View source on GitHub |
Abstract base class for TF-based RL and Bandits agents.
tf_agents.agents.TFAgent(
time_step_spec: tf_agents.trajectories.TimeStep
,
action_spec: tf_agents.typing.types.NestedTensorSpec
,
policy: tf_agents.policies.TFPolicy
,
collect_policy: tf_agents.policies.TFPolicy
,
train_sequence_length: Optional[int],
num_outer_dims: int = 2,
training_data_spec: Optional[tf_agents.typing.types.DistributionSpecV2
] = None,
debug_summaries: bool = False,
summarize_grads_and_vars: bool = False,
enable_summaries: bool = True,
train_step_counter: Optional[tf.Variable] = None
)
Used in the notebooks
Used in the tutorials |
---|
The agent serves the following purposes:
Training by reading minibatches of
experience
, and updating some set of network weights (using thetrain
method).Exposing
policy
objects which can be used to interact with an environment: either to explore and collect new training data, or to maximize reward in the given task.
The agents' main training methods and properties are:
initialize
: Perform any self-initialization before training.train
: This method reads minibatch experience from a replay buffer or logs on disk, and updates some internal networks.preprocess_sequence
: Some algorithms need to perform sequence preprocessing on logs containing "full episode" or "long subset" sequences, to create intermediate items that can then be used bytrain
, even iftrain
does not see the full sequences. In many cases this is just the identity: it passes experience through untouched. This function is typically passed to the argumenttraining_data_spec
: Property that describes the structure expected of theexperience
argument passed totrain
.train_sequence_length
: Property that describes the second dimension of all tensors in theexperience
argument passedtrain
. All tensors passed to train must have the shape[batch_size, sequence_length, ...]
, and some Agents require this to be a fixed value. For example, in regularDQN
, this secondsequence_length
dimension must be equal to2
in allexperience
. In contrast,n-step DQN
will have this equal ton + 1
andDQN
agents constructed withRNN
networks will have this equal toNone
, meaning any length sequences are allowed.This value may be
None
, to mean minibatches containing subsequences of any length are allowed (so long as they're all the same length). This is typically the case with agents constructed withRNN
networks.This value is typically passed as a ReplayBuffer's
as_dataset(..., num_steps=...)
argument.collect_data_spec
: Property that describes the structure expected of experience collected byagent.collect_policy
. This is typically identical totraining_data_spec
, but may be different ifpreprocess_sequence
method is not the identity. In this case,preprocess_sequence
is expected to read sequences matchingcollect_data_spec
and emit sequences matchingtraining_data_spec
.
The agent exposes TFPolicy
objects for interacting with environments:
policy
: Property that returns a policy meant for "exploiting" the environment to its best ability. This tends to mean the "production" policy that doesn't collect additional info for training. Works best when the agent is fully trained."production" policies yet. We have to clean this up. In particular, we have to update PPO and SAC's
policy
objects.collect_policy
: Property that returns a policy meant for "exploring" the environment to collect more data for training. This tends to mean a policy involves some level of randomized behavior and additional info logging.time_step_spec
: Property describing the observation and reward signatures of the environment this agent's policies operate in.action_spec
: Property describing the action signatures of the environment this agent's policies operate in.
Args | |
---|---|
time_step_spec
|
A nest of tf.TypeSpec representing the time_steps. Provided by the user. |
action_spec
|
A nest of BoundedTensorSpec representing the actions. Provided by the user. |
policy
|
An instance of tf_policy.TFPolicy representing the Agent's
current policy.
|
collect_policy
|
An instance of tf_policy.TFPolicy representing the
Agent's current data collection policy (used to set self.step_spec ).
|
train_sequence_length
|
A python integer or None , signifying the number
of time steps required from tensors in experience as passed to
train() . All tensors in experience will be shaped [B, T, ...] but
for certain agents, T should be fixed. For example, DQN requires
transitions in the form of 2 time steps, so for a non-RNN DQN Agent, set
this value to 2. For agents that don't care, or which can handle T
unknown at graph build time (i.e. most RNN-based agents), set this
argument to None .
|
num_outer_dims
|
The number of outer dimensions for the agent. Must be either 1 or 2. If 2, training will require both a batch_size and time dimension on every Tensor; if 1, training will require only a batch_size outer dimension. |
training_data_spec
|
A nest of TensorSpec specifying the structure of data the train() function expects. If None, defaults to the trajectory_spec of the collect_policy. |
debug_summaries
|
A bool; if true, subclasses should gather debug summaries. |
summarize_grads_and_vars
|
A bool; if true, subclasses should additionally collect gradient and variable summaries. |
enable_summaries
|
A bool; if false, subclasses should not gather any
summaries (debug or otherwise); subclasses should gate all summaries
using either summaries_enabled , debug_summaries , or
summarize_grads_and_vars properties.
|
train_step_counter
|
An optional counter to increment every time the train op is run. Defaults to the global_step. |
Raises | |
---|---|
ValueError
|
If num_outer_dims is not in [1, 2] .
|
Methods
initialize
initialize() -> Optional[tf.Operation]
Initializes the agent.
Returns | |
---|---|
An operation that can be used to initialize the agent. |
Raises | |
---|---|
RuntimeError
|
If the class was not initialized properly (super.__init__
was not called).
|
loss
loss(
experience: tf_agents.typing.types.NestedTensor
,
weights: Optional[types.Tensor] = None,
training: bool = False,
**kwargs
) -> tf_agents.agents.tf_agent.LossInfo
Gets loss from the agent.
If the user calls this from _train, it must be in a tf.GradientTape
scope
in order to apply gradients to trainable variables.
If intermediate gradient steps are needed, _loss and _train will return
different values since _loss only supports updating all gradients at once
after all losses have been calculated.
Args | |
---|---|
experience
|
A batch of experience data in the form of a Trajectory . The
structure of experience must match that of self.training_data_spec .
All tensors in experience must be shaped [batch, time, ...] where
time must be equal to self.train_step_length if that property is not
None .
|
weights
|
(optional). A Tensor , either 0-D or shaped [batch] ,
containing weights to be used when calculating the total train loss.
Weights are typically multiplied elementwise against the per-batch loss,
but the implementation is up to the Agent.
|
training
|
Explicit argument to pass to loss . This typically affects
network computation paths like dropout and batch normalization.
|
**kwargs
|
Any additional data as args to loss .
|
Returns | |
---|---|
A LossInfo loss tuple containing loss and info tensors.
|
Raises | |
---|---|
RuntimeError
|
If the class was not initialized properly (super.__init__
was not called).
|
post_process_policy
post_process_policy() -> tf_agents.policies.TFPolicy
Post process policies after training.
The policies of some agents require expensive post processing after training before they can be used. e.g. A Recommender agent might require rebuilding an index of actions. For such agents, this method will return a post processed version of the policy. The post processing may either update the existing policies in place or create a new policy, depnding on the agent. The default implementation for agents that do not want to override this method is to return agent.policy.
Returns | |
---|---|
The post processed policy. |
preprocess_sequence
preprocess_sequence(
experience: tf_agents.typing.types.NestedTensor
) -> tf_agents.typing.types.NestedTensor
Defines preprocess_sequence function to be fed into replay buffers.
This defines how we preprocess the collected data before training.
Defaults to pass through for most agents.
Structure of experience
must match that of self.collect_data_spec
.
Args | |
---|---|
experience
|
a Trajectory shaped [batch, time, ...] or [time, ...] which
represents the collected experience data.
|
Returns | |
---|---|
A post processed Trajectory with the same shape as the input.
|
train
train(
experience: tf_agents.typing.types.NestedTensor
,
weights: Optional[types.Tensor] = None,
**kwargs
) -> tf_agents.agents.tf_agent.LossInfo
Trains the agent.
Args | |
---|---|
experience
|
A batch of experience data in the form of a Trajectory . The
structure of experience must match that of self.training_data_spec .
All tensors in experience must be shaped [batch, time, ...] where
time must be equal to self.train_step_length if that property is not
None .
|
weights
|
(optional). A Tensor , either 0-D or shaped [batch] ,
containing weights to be used when calculating the total train loss.
Weights are typically multiplied elementwise against the per-batch loss,
but the implementation is up to the Agent.
|
**kwargs
|
Any additional data to pass to the subclass. |
Returns | |
---|---|
A LossInfo loss tuple containing loss and info tensors.
|
Raises | |
---|---|
RuntimeError
|
If the class was not initialized properly (super.__init__
was not called).
|