ding.policy

基本策略

请参考 ding/policy/base_policy.py 了解更多详情。

策略

class ding.policy.Policy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

DI-engine 中强化学习（RL）和模仿学习（IL）策略的基本类。

Property:

cfg, learn_mode, collect_mode, eval_mode

__init__(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None) → None

Overview:

根据输入的配置和模型初始化策略实例。此方法将初始化策略中的不同字段，包括 learn, collect, eval。learn 字段用于训练策略，collect 字段用于收集训练数据，eval 字段用于评估策略。enable_field 用于指定要初始化的字段，如果为 None，则所有字段都将被初始化。

Arguments:

• cfg (EasyDict): 用于初始化策略的最终合并配置。对于默认配置，请参阅策略类的 config 属性及其注释。

• 模型 (torch.nn.Module): 用于初始化策略的神经网络模型。如果它是None，那么模型将根据default_model方法和cfg.model字段创建。否则，模型将被设置为由外部调用者创建的model实例。

• enable_field (Optional[List[str]]): 要初始化的字段列表。如果为None，则所有字段都将被初始化。否则，只有enable_field中的字段会被初始化，这有助于节省资源。

注意

对于派生的策略类，它应该实现_init_learn、_init_collect、_init_eval方法来初始化相应的字段。

__repr__() → str

Overview:

获取策略的字符串表示。

Returns:

• repr (str): 策略的字符串表示。

_create_model(cfg: EasyDict, model: Module | None = None) → Module

Overview:

根据输入配置和模型创建或验证神经网络模型。如果输入模型为None，则模型将根据default_model方法和cfg.model字段创建。否则，模型将被验证为torch.nn.Module的实例，并设置为外部调用者创建的model实例。

Arguments:

• cfg (EasyDict): 用于初始化策略的最终合并配置。

• 模型 (torch.nn.Module): 用于初始化策略的神经网络模型。用户可以参考相应策略中定义的默认模型来自定义自己的模型。

Returns:

• 模型 (torch.nn.Module): 创建的神经网络模型。策略的不同模式将为模型添加不同的包装器和插件，用于训练、收集和评估。

Raises:

• 运行时错误：如果输入模型不是None且不是torch.nn.Module的实例。

abstract _forward_collect(data: Dict[int, Any], **kwargs) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作，或用于在学习模式中计算损失的动作逻辑值。此方法留给子类实现，如果需要，可以在kwargs部分添加更多参数。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

abstract _forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（评估策略性能，例如与环境交互或在验证数据集上计算指标）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。此方法留给子类实现。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

abstract _forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失值、策略熵、q值、优先级等。此方法留给子类实现，如果需要，可以在data项中添加更多参数。

Arguments:

• 数据 (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，在_forward_learn方法中，数据应通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。

Returns:

• 输出 (Dict[int, Any]): 策略前向的训练信息，包括一些用于监控训练的指标，如损失、优先级、q值、策略熵，以及一些用于下一步训练的数据，如优先级。注意输出数据项应为Python原生标量，而不是PyTorch张量，这样便于外部使用。

_get_attribute(name: str) → Any

Overview:

为了控制策略属性的访问，我们向外部暴露了不同的模式，而不是直接使用策略实例。我们还提供了一种方法来获取不同模式下的策略属性。

Arguments:

• 名称 (str): 属性的名称。

Returns:

• 值 (Any): 属性的值。

注意

DI-engine的策略将首先尝试访问_get_{name}方法，然后尝试访问_{name}属性。如果两者都未找到，它将引发一个NotImplementedError。

abstract _get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可以直接用于训练的样本列表。一个训练样本可以是一个处理过的转换（使用n步TD的DQN）或者一些多时间步的转换（DRQN）。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，你也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据，例如n步奖励、优势等。

注意

我们将在下一个发布版本中对process_transition和get_train_sample方法进行向量化。用户可以通过重写这两个方法和收集器本身来自定义数据处理过程。

abstract _init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。如果collect字段在enable_field中，此方法将在__init__方法中调用。几乎不同的策略都有其自己的收集模式，因此必须在子类中重写此方法。

注意

对于需要保存和加载的成员变量，请参考_state_dict_collect和_load_state_dict_collect方法。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

abstract _init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。如果eval字段在enable_field中，此方法将在__init__方法中调用。几乎不同的策略都有其自己的评估模式，因此必须在子类中重写此方法。

注意

对于需要保存和加载的成员变量，请参考_state_dict_eval和_load_state_dict_eval方法。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

abstract _init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。如果learn字段在enable_field中，此方法将在__init__方法中被调用。几乎不同的策略都有其自己的学习模式，因此此方法必须在子类中被重写。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_init_multi_gpu_setting(model: Module, bp_update_sync: bool) → None

Overview:

初始化多GPU数据并行训练设置，包括在训练开始时广播模型参数，并准备钩子函数以对模型参数的梯度进行全归约。

Arguments:

• 模型 (torch.nn.Module): 需要训练的神经网络模型。

• bp_update_sync (bool): 是否在所有reduce模型参数的梯度后同步更新模型参数。异步更新可以在不同的网络层中并行进行，如管道，从而节省时间。

_load_state_dict_collect(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略收集模式中，例如加载预训练的state_dict、自动恢复检查点，或在分布式训练场景中从learner加载模型副本。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略收集状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_load_state_dict_eval(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略评估模式中，例如加载自动恢复检查点，或在分布式训练场景中从学习者加载模型副本。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略评估状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

提示

默认实现是 ['cur_lr', 'total_loss']。其他派生类可以根据需要覆盖此方法以添加自己的键。

abstract _process_transition(obs: Tensor | Dict[str, Tensor], policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，例如。一些策略需要做一些特殊的处理并打包其自己必要的属性（例如隐藏状态和logit），因此这个方法留给子类来实现。

Arguments:

• obs (Union[torch.Tensor, Dict[str, torch.Tensor]]): 当前时间步的观察值。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。通常，它包含动作和动作的logit。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_reset_collect(data_id: List[int] | None = None) → None

Overview:

在必要时为收集模式重置一些有状态的变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有有状态的变量。否则，它将根据data_id重置有状态的变量。例如，在data_id中收集的不同环境/情节在RNN中将具有不同的隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的状态变量。

注意

此方法不是必须实现的。子类可以根据需要覆盖此方法。

_reset_eval(data_id: List[int] | None = None) → None

Overview:

在必要时重置一些用于评估模式的状态变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有状态变量。否则，它将根据data_id重置状态变量。例如，在data_id中的不同环境/情节在评估时将具有不同的RNN隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的状态变量。

注意

这个方法不是必须实现的。如果有必要，子类可以覆盖这个方法。

_reset_learn(data_id: List[int] | None = None) → None

Overview:

在必要时为学习模式重置一些有状态的变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有有状态的变量。否则，它将根据data_id重置有状态的变量。例如，data_id中的不同轨迹在RNN中将具有不同的隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的ID，用于重置由data_id指定的状态变量。

注意

此方法不是必须实现的。子类可以根据需要覆盖此方法。

_set_attribute(name: str, value: Any) → None

Overview:

为了控制策略属性的访问，我们向外部暴露了不同的模式，而不是直接使用策略实例。我们还提供了一种方法来设置不同模式下的策略属性。新属性将被命名为_{name}。

Arguments:

• 名称 (str): 属性的名称。

• 值 (Any): 属性的值。

_state_dict_collect() → Dict[str, Any]

Overview:

返回收集模式的状态字典，通常只包括模型，这对于分布式训练场景中自动恢复收集器是必要的。

Returns:

• state_dict (Dict[str, Any]): 当前策略收集状态的字典，用于保存和恢复。

提示

并非所有场景都需要自动恢复收集器，有时，我们可以直接关闭崩溃的收集器并重新启动一个新的。

_state_dict_eval() → Dict[str, Any]

Overview:

返回评估模式的状态字典，通常只包括模型，这对于分布式训练场景中自动恢复评估器是必要的。

Returns:

• state_dict (Dict[str, Any]): 当前策略评估状态的字典，用于保存和恢复。

提示

并非所有场景都需要自动恢复评估器，有时，我们可以直接关闭崩溃的评估器并重新启动一个新的。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

property collect_mode: collect_function

Overview:

返回策略的收集模式接口，用于训练模型。这里我们使用namedtuple来定义不可变的接口，并限制策略在不同模式下的使用。此外，派生子类可以覆盖这些接口以自定义其自己的收集模式。

Returns:

• 接口 (Policy.collect_function): 策略的收集模式接口，它是一个命名元组，其不同字段的值是不同的内部方法。

Examples:

>>> policy = Policy(cfg, model)
>>> policy_collect = policy.collect_mode
>>> obs = env_manager.ready_obs
>>> inference_output = policy_collect.forward(obs)
>>> next_obs, rew, done, info = env_manager.step(inference_output.action)

classmethod default_config() → EasyDict

Overview:

获取策略的默认配置。此方法用于创建策略的默认配置。

Returns:

• cfg (EasyDict): 对应策略的默认配置。对于派生策略类，它将递归地合并基类的默认配置和其自身的默认配置。

提示

此方法将深拷贝类的config属性并返回结果。因此，用户无需担心返回的配置被修改。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于DQN，其注册名称为dqn，import_names为ding.model.template.q_learning.DQN

property eval_mode: eval_function

Overview:

返回策略的评估模式接口，用于训练模型。这里我们使用namedtuple来定义不可变的接口，并限制策略在不同模式下的使用。此外，派生的子类可以覆盖这些接口以自定义其自己的评估模式。

Returns:

• 接口 (Policy.eval_function): 策略的评估模式接口，它是一个命名元组，其不同字段的值是不同的内部方法。

Examples:

>>> policy = Policy(cfg, model)
>>> policy_eval = policy.eval_mode
>>> obs = env_manager.ready_obs
>>> inference_output = policy_eval.forward(obs)
>>> next_obs, rew, done, info = env_manager.step(inference_output.action)

property learn_mode: learn_function

Overview:

返回策略的学习模式接口，用于训练模型。这里我们使用namedtuple来定义不可变的接口，并限制策略在不同模式下的使用。此外，派生的子类可以覆盖这些接口以自定义其自己的学习模式。

Returns:

• 接口 (Policy.learn_function): 策略学习模式的接口，它是一个namedtuple，其不同字段的值是不同的内部方法。

Examples:

>>> policy = Policy(cfg, model)
>>> policy_learn = policy.learn_mode
>>> train_output = policy_learn.forward(data)
>>> state_dict = policy_learn.state_dict()

sync_gradients(model: Module) → None

Overview:

在数据并行的多GPU训练中同步（allreduce）模型参数的梯度。

Arguments:

• 模型 (torch.nn.Module): 需要同步梯度的模型。

注意

此方法仅用于多GPU训练，应在backward方法之后和step方法之前调用。用户还可以使用bp_update_sync配置来控制是否同步梯度的allreduce和优化器更新。

CommandModePolicy

class ding.policy.CommandModePolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

带有命令模式的策略，可以在旧版本的DI-engine管道中使用：serial_pipeline。CommandModePolicy使用_get_setting_learn、_get_setting_collect、_get_setting_eval方法在不同工作器之间交换信息。

Interface:

_init_command, _get_setting_learn, _get_setting_collect, _get_setting_eval

Property:

command_mode

abstract _get_setting_collect(command_info: Dict[str, Any]) → Dict[str, Any]

Overview:

根据command_info，即全局训练信息（例如训练迭代、收集的环境步骤、评估结果等），返回收集模式的设置，其中包含动态变化的收集模式超参数，例如eps、temperature等。

Arguments:

• command_info (Dict[str, Any]): 全局训练信息，定义在 commander 中。

Returns:

• 设置 (Dict[str, Any]): 收集模式的最新设置，通常用作 policy._forward_collect 方法的额外参数。

abstract _get_setting_eval(command_info: Dict[str, Any]) → Dict[str, Any]

Overview:

根据command_info，即全局训练信息（例如训练迭代、收集的环境步骤、评估结果等），返回评估模式的设置，其中包含动态变化的评估模式超参数，例如temperature等。

Arguments:

• command_info (Dict[str, Any]): 全局训练信息，定义在 commander 中。

Returns:

• 设置 (Dict[str, Any]): 评估模式的最新设置，通常用作 policy._forward_eval 方法的额外参数。

abstract _get_setting_learn(command_info: Dict[str, Any]) → Dict[str, Any]

Overview:

根据command_info，即全局训练信息（例如训练迭代、收集的环境步骤、评估结果等），返回学习模式的设置，其中包含动态变化的学习模式超参数，例如batch_size、learning_rate等。

Arguments:

• command_info (Dict[str, Any]): 全局训练信息，定义在 commander 中。

Returns:

• 设置 (Dict[str, Any]): 学习模式的最新设置，通常用作 policy._forward_learn 方法的额外参数。

abstract _init_command() → None

Overview:

初始化策略的命令模式，包括相关属性和模块。如果command字段在enable_field中，此方法将在__init__方法中被调用。几乎不同的策略都有其自己的命令模式，因此此方法必须在子类中被重写。

注意

如果你想在_init_command方法中设置一些特殊的成员变量，最好给它们加上前缀_command_，以避免与其他模式冲突，例如self._command_attr1。

property command_mode: Policy.command_function

Overview:

返回策略的命令模式接口，用于训练模型。这里我们使用namedtuple来定义不可变的接口，并限制策略在不同模式下的使用。此外，派生子类可以覆盖这些接口以自定义其自己的命令模式。

Returns:

• 接口 (Policy.command_function): 命令模式的接口，它是一个namedtuple，其不同字段的值是不同的内部方法。

Examples:

>>> policy = CommandModePolicy(cfg, model)
>>> policy_command = policy.command_mode
>>> settings = policy_command.get_setting_learn(command_info)

create_policy

ding.policy.create_policy(cfg: EasyDict, **kwargs) → Policy

Overview:

根据cfg和其他kwargs创建一个策略实例。

Arguments:

• cfg (EasyDict): 最终合并的策略配置。

ArgumentsKeys:

• 类型 (str): 在 POLICY_REGISTRY.register 方法中设置的策略类型，例如 dqn。

• import_names (List[str]): 在创建策略之前要导入的模块名称（路径）列表，例如 ding.policy.dqn。

Returns:

• policy (Policy): 创建的策略实例。

提示

kwargs 包含需要传递给策略构造函数的其他参数。您可以参考相应策略类的 __init__ 方法以获取详细信息。

注意

有关如何合并配置的更多详细信息，请参阅DI-engine的系统文档（en link）。

get_policy_cls

ding.policy.get_policy_cls(cfg: EasyDict) → type

Overview:

根据cfg获取策略类，用于访问相关的类变量/方法。

Arguments:

• cfg (EasyDict): 最终合并的策略配置。

ArgumentsKeys:

• 类型 (str): 在 POLICY_REGISTRY.register 方法中设置的策略类型，例如 dqn。

• import_names (List[str]): 在创建策略之前要导入的模块名称（路径）列表，例如 ding.policy.dqn。

Returns:

• 策略 (type): 策略类。

DQN

请参考 ding/policy/dqn.py 获取更多详细信息。

DQN策略

class ding.policy.DQNPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

DQN算法的策略类，由Double DQN/Dueling DQN/PER/多步TD扩展。

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	dqn	RL policy register name, refer to registry POLICY_REGISTRY	This arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network	This arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy
4	priority	布尔	假	Whether use priority(PER)	Priority sample, update priority
5	priority_IS _weight	布尔	假	Whether use Importance Sampling Weight to correct biased update. If True, priority must be True.
6	discount_ factor	浮点数	0.97, [0.95, 0.999]	Reward’s future discount factor, aka. gamma	May be 1 when sparse reward env
7	nstep	整数	1, [3, 5]	N-step reward discount sum for target q_value estimation
8	model.dueling	布尔	真	dueling head architecture
9	model.encoder _hidden _size_list	列表 (int)	[32, 64, 64, 128]	Sequence of hidden_size of subsequent conv layers and the final dense layer.	default kernel_size is [8, 4, 3] default stride is [4, 2 ,1]
10	model.dropout	浮点数	无	Dropout rate for dropout layers.	[0,1] If set to None means no dropout
11	learn.update per_collect	整数	3	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	This args can be vary from envs. Bigger val means more off-policy
12	learn.batch_ size	整数	64	The number of samples of an iteration
13	learn.learning _rate	浮点数	0.001	Gradient step length of an iteration.
14	learn.target_ update_freq	整数	100	Frequence of target network update.	Hard(assign) update
15	learn.target_ theta	浮点数	0.005	Frequence of target network update. Only one of [target_update_freq, target_theta] should be set	Soft(assign) update
16	learn.ignore_ done	布尔	假	Whether ignore done for target value calculation.	Enable it for some fake termination env
17	collect.n_sample	整数	[8, 128]	The number of training samples of a call of collector.	It varies from different envs
18	collect.n_episode	整数	8	The number of training episodes of a call of collector	only one of [n_sample ,n_episode] should be set
19	collect.unroll _len	整数	1	unroll length of an iteration	In RNN, unroll_len>1
20	other.eps.type	字符串	exp	exploration rate decay type	Support [‘exp’, ‘linear’].
21	other.eps. start	浮点数	0.95	start value of exploration rate	[0,1]
22	other.eps. end	浮点数	0.1	end value of exploration rate	[0,1]
23	other.eps. decay	整数	10000	decay length of exploration	greater than 0. set decay=10000 means the exploration rate decay from start value to end value during decay length.

_forward_collect(data: Dict[int, Any], eps: float) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。此外，此策略还需要eps参数进行探索，即经典的epsilon-greedy探索策略。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

• eps (float): 探索的epsilon值。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参阅我们的DQNPolicy单元测试：ding.policy.tests.test_dqn。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参阅我们的DQNPolicy单元测试：ding.policy.tests.test_dqn。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、q值、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于DQN，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参阅我们的DQNPolicy单元测试：ding.policy.tests.test_dqn。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可以直接用于训练的样本列表。在使用n步TD的DQN中，一个训练样本是一个处理过的转换。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，你也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据，例如n步奖励和目标观测值。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于DQN，它包含用于通过epsilon-greedy采样机制平衡探索和利用的collect_model，以及其他算法特定的参数，如unroll_len和nstep。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

提示

一些变量需要在不同的模式中独立初始化，例如DQN中的gamma和nstep。这种设计是为了方便不同策略模式的并行执行。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于DQN，它包含评估模型，以贪婪地选择具有argmax q_value机制的动作。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于DQN，主要包含优化器、算法特定的参数如nstep和gamma、主模型和目标模型。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于DQN，它包含obs、next_obs、action、reward、done。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于DQN，它包含动作和动作的logit（q_value）。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于DQN，其注册名称为dqn，import_names为ding.model.template.q_learning。

DQNSTDIM策略

class ding.policy.DQNSTDIMPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

DQN算法的策略类，通过ST-DIM辅助目标进行扩展。 ST-DIM论文链接：https://arxiv.org/abs/1906.08226。

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	dqn_stdim	RL policy register name, refer to registry POLICY_REGISTRY	This arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network	This arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy
4	priority	布尔	假	Whether use priority(PER)	Priority sample, update priority
5	priority_IS _weight	布尔	假	Whether use Importance Sampling Weight to correct biased update. If True, priority must be True.
6	discount_ factor	浮点数	0.97, [0.95, 0.999]	Reward’s future discount factor, aka. gamma	May be 1 when sparse reward env
7	nstep	整数	1, [3, 5]	N-step reward discount sum for target q_value estimation
8	learn.update per_collect _gpu	整数	3	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	This args can be vary from envs. Bigger val means more off-policy
10	learn.batch_ size	整数	64	The number of samples of an iteration
11	learn.learning _rate	浮点数	0.001	Gradient step length of an iteration.
12	learn.target_ update_freq	整数	100	Frequence of target network update.	Hard(assign) update
13	learn.ignore_ done	布尔	假	Whether ignore done for target value calculation.	Enable it for some fake termination env
14	collect.n_sample	整数	[8, 128]	The number of training samples of a call of collector.	It varies from different envs
15	collect.unroll _len	整数	1	unroll length of an iteration	In RNN, unroll_len>1
16	other.eps.type	字符串	exp	exploration rate decay type	Support [‘exp’, ‘linear’].
17	other.eps. start	浮点数	0.95	start value of exploration rate	[0,1]
18	other.eps. end	浮点数	0.1	end value of exploration rate	[0,1]
19	other.eps. decay	整数	10000	decay length of exploration	greater than 0. set decay=10000 means the exploration rate decay from start value to end value during decay length.
20	aux_loss _weight	浮点数	0.001	the ratio of the auxiliary loss to the TD loss	any real value, typically in [-0.1, 0.1].

_forward_learn(data: Dict[str, Any]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、q值、优先级、辅助损失。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于DQNSTDIM，列表中的每个元素是一个包含至少以下键的字典：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于DQNSTDIM，它首先调用超类的_init_learn方法，然后初始化额外的辅助模型、其优化器和损失权重。如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_model_encode(data: dict) → Tuple[Tensor]

Overview:

获取主模型的编码作为辅助模型的输入。

Arguments:

• 数据 (dict): 字典类型数据，与_forward_learn输入相同。

Returns:

• (Tuple[torch.Tensor]): 用于应用对比嵌入学习的两个张量的元组。在ST-DIM算法中，这两个变量分别是obs和next_obs的dqn编码。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

PPO

请参考 ding/policy/ppo.py 获取更多详细信息。

PPO策略

class ding.policy.PPOPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

策略类中的on-policy版本PPO算法。论文链接：https://arxiv.org/abs/1707.06347。

_forward_collect(data: Dict[int, Any]) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少动作和其他在self._process_transition方法中定义的学习模式所需的必要数据（动作逻辑和值）。字典的键与输入数据相同，即环境ID。

提示

如果你想在这个策略上添加更多技巧，比如多项式采样中的温度因子，你可以将相关数据作为该方法的额外关键字参数传递。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PPOPolicy单元测试：ding.policy.tests.test_ppo。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。PPO中的_forward_eval通常使用确定性采样方法来获取动作，而_forward_collect通常使用随机采样方法来平衡探索和利用。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PPOPolicy单元测试：ding.policy.tests.test_ppo。

_forward_learn(data: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、clipfrac、approx_kl。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括最新收集的训练样本，适用于像PPO这样的在线策略算法。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于PPO，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、logit、value、done。有时，它还包含其他键，如weight。

Returns:

• return_infos (List[Dict[str, Any]]): 表示训练结果的信息列表，每次训练迭代都会将一个信息字典附加到最终列表中。该列表将被处理并记录在文本日志和tensorboard中。字典的值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

提示

PPO的训练过程包含两个循环。外循环使用epoch_per_collect轮次训练所有收集的训练样本。内循环将所有数据分割成不同的小批次，每个小批次的长度为batch_size。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PPOPolicy单元测试：ding.policy.tests.test_ppo。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可以直接用于训练的样本列表。在PPO中，一个训练样本是一个经过处理的转换，其中包含新计算的traj_flag和adv字段。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，您也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据，例如GAE优势。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于PPO，它包含用于平衡探索和利用的collect_model（例如离散动作空间中的多项式采样机制），以及其他算法特定的参数，如unroll_len和gae_lambda。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

提示

一些变量需要在不同的模式下独立初始化，例如PPO中的gamma和gae_lambda。这种设计是为了方便不同策略模式的并行执行。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于PPO，它包含用于选择最佳动作的评估模型（例如，在离散动作中使用argmax机制贪婪地选择动作）。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于PPO，主要包含优化器、算法特定的参数，如损失权重、clip_ratio和recompute_adv。此方法还执行一些特殊的网络初始化，并为值准备运行均值/标准差监控器。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于PPO，它包含obs、next_obs、action、reward、done、logit、value。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于PPO，它包含状态值、动作和动作的logit。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

注意

next_obs 用于在必要时计算n步回报，因此我们默认将其放入过渡中。如果您不需要n步回报，可以删除此字段以节省内存占用。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于PPO，其注册名称为ppo，import_names为ding.model.template.vac。

注意

因为现在PPO支持单智能体和多智能体的使用，所以我们可以用相同的策略和两个不同的默认模型来实现这些功能，这是由self._cfg.multi_agent控制的。

PPOPGPolicy

class ding.policy.PPOPGPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

策略版本的PPO算法的策略类（纯策略梯度，无价值网络）。 论文链接：https://arxiv.org/abs/1707.06347。

_forward_collect(data: Dict[int, Any]) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少动作和在self._process_transition方法中定义的学习模式所需的其他必要数据（动作对数）。字典的键与输入数据相同，即环境ID。

提示

如果你想在这个策略上添加更多技巧，比如多项式采样中的温度因子，你可以将相关数据作为该方法的额外关键字参数传递。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。PPO中的_forward_eval通常使用确定性采样方法来获取动作，而_forward_collect通常使用随机采样方法来平衡探索和利用。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PPOPGPolicy单元测试：ding.policy.tests.test_ppo。

_forward_learn(data: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、clipfrac、approx_kl。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括最新的收集的训练样本，适用于像PPO这样的在线策略算法。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于PPOPG，列表中的每个元素是一个包含至少以下键的字典：obs、action、return、logit、done。有时，它还包含其他键，如weight。

Returns:

• return_infos (List[Dict[str, Any]]): 表示训练结果的信息列表，每次训练迭代都会将一个信息字典附加到最终列表中。该列表将被处理并记录在文本日志和tensorboard中。字典的值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

提示

PPOPG的训练过程包含两个循环。外循环使用epoch_per_collect周期训练所有收集的训练样本。内循环将所有数据分割成不同的小批次，每个小批次的长度为batch_size。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_get_train_sample(data: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的整个情节数据（一系列转换），将其处理成可以直接用于训练的样本列表。在PPOPG中，一个训练样本是一个经过处理的转换，其中包含新计算的return字段。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，您也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• data (List[Dict[str, Any]): 剧集数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据，例如折扣的回合回报。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于PPOPG，它包含用于平衡探索和利用的collect_model（例如离散动作空间中的多项式采样机制），以及其他算法特定的参数，如unroll_len和gae_lambda。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

提示

一些变量需要在不同的模式下独立初始化，例如PPO中的gamma和gae_lambda。这种设计是为了方便不同策略模式的并行执行。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于PPOPG，它包含用于选择最佳动作的评估模型（例如，在离散动作中使用argmax机制贪婪地选择动作）。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于PPOPG，主要包含优化器、算法特定的参数，如损失权重和clip_ratio。此方法还会执行一些特殊的网络初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于PPOPG，它包含观测值、动作、奖励、完成状态、逻辑值。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于PPOPG，它包含动作和动作的logit。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

PPOOffPolicy

class ding.policy.PPOOffPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

离策略版本PPO算法的策略类。论文链接：https://arxiv.org/abs/1707.06347。 此版本更适合大规模分布式训练。

_forward_collect(data: Dict[int, Any]) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少动作和其他在self._process_transition方法中定义的学习模式所需的必要数据（动作逻辑和值）。字典的键与输入数据相同，即环境ID。

提示

如果你想在这个策略上添加更多技巧，比如多项式采样中的温度因子，你可以将相关数据作为该方法的额外关键字参数传递。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PPOOffPolicy单元测试：ding.policy.tests.test_ppo。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。PPO中的_forward_eval通常使用确定性采样方法来获取动作，而_forward_collect通常使用随机采样方法来平衡探索和利用。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PPOOffPolicy单元测试：ding.policy.tests.test_ppo。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、clipfrac和approx_kl。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于PPOOff，列表中的每个元素都是一个字典，至少包含以下键：obs、adv、action、logit、value、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可以直接用于训练的样本列表。在PPO中，一个训练样本是一个经过处理的转换，其中包含新计算的traj_flag和adv字段。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，您也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据，例如GAE优势。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于PPOOff，它包含collect_model以平衡探索和利用（例如离散动作空间中的多项式采样机制），以及其他算法特定的参数，如unroll_len和gae_lambda。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

提示

一些变量需要在不同的模式中独立初始化，例如PPOOff中的gamma和gae_lambda。 这种设计是为了方便不同策略模式的并行执行。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于PPOOff，它包含用于选择最佳动作的评估模型（例如，在离散动作中使用argmax机制贪婪地选择动作）。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于PPOOff，主要包含优化器、算法特定的参数，如损失权重和clip_ratio。此方法还执行一些特殊的网络初始化，并为值准备运行均值/标准差监控器。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于PPO，它包含obs、next_obs、action、reward、done、logit、value。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于PPO，它包含状态值、动作和动作的logit。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

注意

next_obs 用于在必要时计算n步回报，因此我们默认将其放入过渡中。如果您不需要n步回报，可以删除此字段以节省内存占用。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

PPOSTDIMPolicy

class ding.policy.PPOSTDIMPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

策略类，基于策略版本PPO算法与ST-DIM辅助模型。 PPO论文链接：https://arxiv.org/abs/1707.06347。 ST-DIM论文链接：https://arxiv.org/abs/1906.08226。

_forward_learn(data: Dict[str, Any]) → Dict[str, Any]

Overview:

学习模式的前向和后向功能。

Arguments:

• 数据 (dict): 字典类型的数据

Returns:

• info_dict (Dict[str, Any]): 包括当前的学习率、总损失、策略损失、价值损失、熵损失、优势绝对最大值、近似KL散度、裁剪比例

_init_learn() → None

Overview:

学习模式初始化方法。由self.__init__调用。 初始化辅助模型、其优化器以及辅助损失与主损失的权重。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_model_encode(data)

Overview:

获取主模型的编码作为辅助模型的输入。

Arguments:

• 数据 (dict): 字典类型数据，与_forward_learn输入相同。

Returns:

• (Tuple[Tensor]): the tuple of two tensors to apply contrastive embedding learning.

  在ST-DIM算法中，这两个变量分别是obs和next_obs的dqn编码。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括用于表示学习的模型、优化器和辅助优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

BC

请参考 ding/policy/bc.py 获取更多详细信息。

行为克隆策略

class ding.policy.BehaviourCloningPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

行为克隆（BC）策略类，支持离散和连续动作空间。该策略通过监督学习进行训练，数据是由专家收集的离线数据集。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括损失和时间等各种训练信息。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于BC，列表中的每个元素都是一个包含至少以下键的字典：obs，action。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_init_collect() → None

Overview:

BC策略使用离线数据集，因此不需要收集数据。然而，有时我们需要使用训练好的BC策略来收集数据用于其他目的。

_init_eval()

Overview:

初始化策略的评估模式，包括相关属性和模块。对于BC，它包含评估模型，用于通过argmax q_value机制贪婪地选择离散动作空间中的动作。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于BC，主要包含优化器、算法特定的参数，如lr_scheduler、loss等。如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于离散BC，其注册名称为discrete_bc，import_names为ding.model.template.bc。

DDPG

请参考 ding/policy/ddpg.py 获取更多详细信息。

DDPG策略

class ding.policy.DDPGPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

DDPG算法的策略类。论文链接：https://arxiv.org/abs/1509.02971.

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	ddpg	RL policy register name, refer to registry POLICY_REGISTRY	this arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network
3	random_ collect_size	整数	25000	Number of randomly collected training samples in replay buffer when training starts.	Default to 25000 for DDPG/TD3, 10000 for sac.
4	model.twin_ critic	布尔	假	Whether to use two critic networks or only one.	Default False for DDPG, Clipped Double Q-learning method in TD3 paper.
5	learn.learning _rate_actor	浮点数	1e-3	Learning rate for actor network(aka. policy).
6	learn.learning _rate_critic	浮点数	1e-3	Learning rates for critic network (aka. Q-network).
7	learn.actor_ update_freq	整数	2	When critic network updates once, how many times will actor network update.	Default 1 for DDPG, 2 for TD3. Delayed Policy Updates method in TD3 paper.
8	learn.noise	布尔	假	Whether to add noise on target network’s action.	Default False for DDPG, True for TD3. Target Policy Smoo- thing Regularization in TD3 paper.
9	learn.- ignore_done	布尔	假	Determine whether to ignore done flag.	Use ignore_done only in halfcheetah env.
10	learn.- target_theta	浮点数	0.005	Used for soft update of the target network.	aka. Interpolation factor in polyak aver- aging for target networks.
11	collect.- noise_sigma	浮点数	0.1	Used for add noise during co- llection, through controlling the sigma of distribution	Sample noise from dis- tribution, Ornstein- Uhlenbeck process in DDPG paper, Gaussian process in ours.

_forward_collect(data: Dict[int, Any], **kwargs) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DDPGPolicy单元测试：ding.policy.tests.test_ddpg。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DDPGPolicy单元测试：ding.policy.tests.test_ddpg。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于DDPG，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和logit，用于混合动作空间。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DDPGPolicy单元测试：ding.policy.tests.test_ddpg。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一个转换列表）数据，将其处理成一个可以直接用于训练的样本列表。在DDPG中，一个训练样本是一个处理过的转换（unroll_len=1）。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于DDPG，它包含用于通过扰动噪声机制平衡探索和利用的collect_model，以及其他算法特定的参数，如unroll_len。如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于DDPG，它包含评估模型，用于通过argmax q_value机制贪婪地选择混合动作空间中的动作类型。如果enable_field中有eval字段，则此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于DDPG，主要包含两个优化器，算法特定的参数如gamma和twin_critic，以及主模型和目标模型。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于DDPG，它包含obs、next_obs、action、reward、done。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于DDPG，它包含动作和动作的logit（在混合动作空间中）。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

TD3

请参考 ding/policy/td3.py 获取更多详细信息。

TD3策略

class ding.policy.TD3Policy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

TD3算法的策略类。由于DDPG和TD3有许多共同点，我们可以通过改变_actor_update_freq、_twin_critic和模型包装器中的噪声，轻松地从DDPG类派生出这个TD3类。 论文链接: https://arxiv.org/pdf/1802.09477.pdf

配置:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	td3	RL policy register name, refer to registry POLICY_REGISTRY	this arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network
3	random_ collect_size	整数	25000	Number of randomly collected training samples in replay buffer when training starts.	Default to 25000 for DDPG/TD3, 10000 for sac.
4	model.twin_ critic	布尔	真	Whether to use two critic networks or only one.	Default True for TD3, Clipped Double Q-learning method in TD3 paper.
5	learn.learning _rate_actor	浮点数	1e-3	Learning rate for actor network(aka. policy).
6	learn.learning _rate_critic	浮点数	1e-3	Learning rates for critic network (aka. Q-network).
7	learn.actor_ update_freq	整数	2	When critic network updates once, how many times will actor network update.	Default 2 for TD3, 1 for DDPG. Delayed Policy Updates method in TD3 paper.
8	learn.noise	布尔	真	Whether to add noise on target network’s action.	Default True for TD3, False for DDPG. Target Policy Smoo- thing Regularization in TD3 paper.
9	learn.noise_ range	字典	dict(min=-0.5, max=0.5,)	Limit for range of target policy smoothing noise, aka. noise_clip.
10	learn.- ignore_done	布尔	假	Determine whether to ignore done flag.	Use ignore_done only in halfcheetah env.
11	learn.- target_theta	浮点数	0.005	Used for soft update of the target network.	aka. Interpolation factor in polyak aver -aging for target networks.
12	collect.- noise_sigma	浮点数	0.1	Used for add noise during co- llection, through controlling the sigma of distribution	Sample noise from dis -tribution, Ornstein- Uhlenbeck process in DDPG paper, Gaussian process in ours.

_forward_collect(data: Dict[int, Any], **kwargs) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DDPGPolicy单元测试：ding.policy.tests.test_ddpg。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DDPGPolicy单元测试：ding.policy.tests.test_ddpg。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于DDPG，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和logit，用于混合动作空间。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DDPGPolicy单元测试：ding.policy.tests.test_ddpg。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一个转换列表）数据，将其处理成一个可以直接用于训练的样本列表。在DDPG中，一个训练样本是一个处理过的转换（unroll_len=1）。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于DDPG，它包含用于通过扰动噪声机制平衡探索和利用的collect_model，以及其他算法特定的参数，如unroll_len。如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于DDPG，它包含评估模型，用于通过argmax q_value机制贪婪地选择混合动作空间中的动作类型。如果enable_field中有eval字段，则此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于DDPG，主要包含两个优化器，算法特定的参数如gamma和twin_critic，以及主模型和目标模型。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于DDPG，它包含obs、next_obs、action、reward、done。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于DDPG，它包含动作和动作的logit（在混合动作空间中）。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

SAC

请参考 ding/policy/sac.py 获取更多详细信息。

SAC策略

class ding.policy.SACPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

连续SAC算法的策略类。论文链接：https://arxiv.org/pdf/1801.01290.pdf

Config:

ID	符号	类型	默认值	描述	其他
1	type	字符串	sac	RL policy register name, refer to registry POLICY_REGISTRY	this arg is optional, a placeholder
2	cuda	布尔	真	Whether to use cuda for network
3	on_policy	布尔	假	SAC is an off-policy algorithm.
4	priority	布尔	假	Whether to use priority sampling in buffer.
5	priority_IS_ weight	布尔	假	Whether use Importance Sampling weight to correct biased update
6	random_ collect_size	整数	10000	Number of randomly collected training samples in replay buffer when training starts.	Default to 10000 for SAC, 25000 for DDPG/ TD3.
7	learn.learning _rate_q	浮点数	3e-4	Learning rate for soft q network.	Defalut to 1e-3
8	learn.learning _rate_policy	浮点数	3e-4	Learning rate for policy network.	Defalut to 1e-3
9	learn.alpha	浮点数	0.2	Entropy regularization coefficient.	alpha is initiali- zation for auto alpha, when auto_alpha is True
10	learn. auto_alpha	布尔	假	Determine whether to use auto temperature parameter alpha.	Temperature parameter determines the relative importance of the entropy term against the reward.
11	learn.- ignore_done	布尔	假	Determine whether to ignore done flag.	Use ignore_done only in env like Pendulum
12	learn.- target_theta	浮点数	0.005	Used for soft update of the target network.	aka. Interpolation factor in polyak aver aging for target networks.

_forward_collect(data: Dict[int, Any], **kwargs) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

logit 在 SAC 中表示高斯分布的 mu 和 sigma。这里我们使用这个名称以保持一致性。

注意

有关更详细的示例，请参考我们的SACPolicy单元测试：ding.policy.tests.test_sac。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

logit 在 SAC 中表示高斯分布的 mu 和 sigma。这里我们使用这个名称以保持一致性。

注意

有关更详细的示例，请参考我们的SACPolicy单元测试：ding.policy.tests.test_sac。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于SAC，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的SACPolicy单元测试：ding.policy.tests.test_sac。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一个转换列表）数据，将其处理成一个可以直接用于训练的样本列表。在连续SAC中，一个训练样本是一个处理过的转换（unroll_len=1）。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于SAC，它包含collect_model和其他算法特定的参数，如unroll_len。如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于SAC，它包含评估模型，该模型配备了base模型包装器以确保兼容性。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于SAC，主要包含三个优化器，算法特定的参数如gamma和twin_critic，主模型和目标模型。特别是，用于平衡最大熵目标的auto_alpha机制也在这里初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于连续SAC，它包含obs、next_obs、action、reward、done。当collector_logit为True时，logit也会被添加。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于连续SAC，它包含动作和动作的logit（mu和sigma）。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

离散SAC策略

class ding.policy.DiscreteSACPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

离散SAC算法的策略类。论文链接：https://arxiv.org/abs/1910.07207。

_forward_collect(data: Dict[int, Any], eps: float) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。此外，此策略还需要eps参数进行探索，即经典的epsilon-greedy探索策略。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

• eps (float): 探索的epsilon值。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DiscreteSACPolicy单元测试：ding.policy.tests.test_discrete_sac。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DiscreteSACPolicy单元测试：ding.policy.tests.test_discrete_sac。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于SAC，列表中的每个元素都是一个字典，至少包含以下键：obs、action、logit、reward、next_obs、done。有时，它还包含其他键，如weight。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的DiscreteSACPolicy单元测试：ding.policy.tests.test_discrete_sac。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一个转换列表）数据，将其处理成可以直接用于训练的样本列表。在离散SAC中，一个训练样本是一个处理过的转换（unroll_len=1）。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于SAC，它包含collect_model，通过epsilon和多项式采样机制来平衡探索和利用，以及其他算法特定的参数，如unroll_len。如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于DiscreteSAC，它包含用于通过argmax q_value机制贪婪选择动作类型的评估模型。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于DiscreteSAC，主要包含三个优化器，算法特定的参数如gamma和twin_critic，主模型和目标模型。特别是，用于平衡最大熵目标的auto_alpha机制也在这里初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于离散SAC，它包含obs、next_obs、logit、action、reward、done。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于离散SAC，它包含动作和动作的logit。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

SQILSAC策略

class ding.policy.SQILSACPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

连续SAC算法与SQIL扩展的策略类。 SAC论文链接: https://arxiv.org/pdf/1801.01290.pdf SQIL论文链接: https://arxiv.org/abs/1905.11108

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于SAC，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

对于SQIL + SAC，输入数据由两部分组成，大小相同：代理数据和专家数据。根据SQIL算法，它们都被重新标记了新的奖励。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的SACPolicy单元测试：ding.policy.tests.test_sac。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于SAC，主要包含三个优化器，算法特定的参数如gamma和twin_critic，主模型和目标模型。特别是，用于平衡最大熵目标的auto_alpha机制也在这里初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

R2D2

请参考 ding/policy/r2d2.py 获取更多详细信息。

R2D2策略

class ding.policy.R2D2Policy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

R2D2的策略类，来自论文分布式强化学习中的循环经验回放。 R2D2提出应使用几种技巧来改进DRQN，即一些循环经验回放技巧和用于离策略训练的预热机制。

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	r2d2	RL policy register name, refer to registry POLICY_REGISTRY	This arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network	This arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy
4	priority	布尔	假	Whether use priority(PER)	Priority sample, update priority
5	priority_IS _weight	布尔	假	Whether use Importance Sampling Weight to correct biased update. If True, priority must be True.
6	discount_ factor	浮点数	0.997, [0.95, 0.999]	Reward’s future discount factor, aka. gamma	May be 1 when sparse reward env
7	nstep	整数	3, [3, 5]	N-step reward discount sum for target q_value estimation
8	burnin_step	整数	2	The timestep of burnin operation, which is designed to RNN hidden state difference caused by off-policy
9	learn.update per_collect	整数	1	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	This args can be vary from envs. Bigger val means more off-policy
10	learn.batch_ size	整数	64	The number of samples of an iteration
11	learn.learning _rate	浮点数	0.001	Gradient step length of an iteration.
12	learn.value_ rescale	布尔	真	Whether use value_rescale function for predicted value
13	learn.target_ update_freq	整数	100	Frequence of target network update.	Hard(assign) update
14	learn.ignore_ done	布尔	假	Whether ignore done for target value calculation.	Enable it for some fake termination env
15	collect.n_sample	整数	[8, 128]	The number of training samples of a call of collector.	It varies from different envs
16	collect.unroll _len	整数	1	unroll length of an iteration	In RNN, unroll_len>1

_forward_collect(data: Dict[int, Any], eps: float) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。此外，此策略还需要eps参数进行探索，即经典的epsilon-greedy探索策略。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

• eps (float): 探索的epsilon值。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据（prev_state）。字典的键与输入数据相同，即环境ID。

注意

RNN的隐藏状态在策略中维护，因此我们不需要将它们传递到数据中，而是在回合结束时使用_reset_collect方法重置隐藏状态。此外，之前的隐藏状态对于训练是必要的，因此我们需要在_process_transition方法中返回它们。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的R2D2Policy单元测试：ding.policy.tests.test_r2d2。

_forward_learn(data: List[List[Dict[str, Any]]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据（对于R2D2来说是轨迹），然后返回输出结果，包括各种训练信息，如损失、q值、优先级。

Arguments:

• data (List[List[Dict[int, Any]]]): 用于策略前向传播的输入数据，包括一批训练样本。对于每个字典元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过实用函数self._data_preprocess_learn在时间和批次维度上进行堆叠。对于R2D2，列表中的每个元素是一个长度为unroll_len的轨迹，轨迹列表中的元素是一个包含至少以下键的字典：obs、action、prev_state、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参阅我们的R2D2Policy单元测试：ding.policy.tests.test_r2d2。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可以直接用于训练的样本列表。在R2D2中，一个训练样本是经过处理的转换，长度为unroll_len。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，你也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个样本是一个固定长度的轨迹，样本中的每个元素与输入转换的格式相似，但可能包含更多的训练数据，例如n步奖励和value_gamma因子。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于R2D2，它包含collect_model，通过epsilon-greedy采样机制来平衡探索和利用，并维护rnn的隐藏状态。此外，还有一些关于其他算法特定参数的初始化操作，如burnin_step、unroll_len和nstep。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

提示

一些变量需要在不同的模式下独立初始化，例如R2D2中的gamma和nstep。这种设计是为了方便不同策略模式的并行执行。

_init_learn() → None

Overview:

初始化策略的学习模式，包括一些属性和模块。对于R2D2，主要包含优化器、算法特定的参数如burnin_step、value_rescale和gamma，以及主模型和目标模型。由于使用了RNN，所有模型都应该用hidden_state进行包装，这需要以适当的大小进行初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于R2D2，它包含观测值（obs）、动作（action）、前一个状态（prev_state）、奖励（reward）和完成标志（done）。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 给定观察值作为输入时，策略网络的输出。对于R2D2，它包含动作和RNN的prev_state。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_reset_collect(data_id: List[int] | None = None) → None

Overview:

在必要时重置一些用于评估模式的状态变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有状态变量。否则，它将根据data_id重置状态变量。例如，在data_id中的不同环境/情节在评估时将具有不同的RNN隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的有状态变量（例如，R2D2中的RNN隐藏状态）。

_reset_eval(data_id: List[int] | None = None) → None

Overview:

在必要时重置一些用于评估模式的状态变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有状态变量。否则，它将根据data_id重置状态变量。例如，在data_id中的不同环境/情节在评估时将具有不同的RNN隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的有状态变量（例如，R2D2中的RNN隐藏状态）。

_reset_learn(data_id: List[int] | None = None) → None

Overview:

在必要时为学习模式重置一些有状态的变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有有状态的变量。否则，它将根据data_id重置有状态的变量。例如，data_id中的不同轨迹在RNN中将具有不同的隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的有状态变量（例如R2D2中的RNN隐藏状态）。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于R2D2，其注册名称为drqn，import_names为ding.model.template.q_learning。

IMPALA

请参考 ding/policy/impala.py 获取更多详细信息。

IMPALAPolicy

class ding.policy.IMPALAPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

IMPALA算法的策略类。论文链接：https://arxiv.org/abs/1802.01561。

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	impala	RL policy register name, refer to registry POLICY_REGISTRY	this arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network	this arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy
	priority	布尔	假	Whether use priority(PER)	priority sample, update priority
5	priority_ IS_weight	布尔	假	Whether use Importance Sampling Weight	If True, priority must be True
6	unroll_len	整数	32	trajectory length to calculate v-trace target
7	learn.update per_collect	整数	4	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	this args can be vary from envs. Bigger val means more off-policy

_forward_collect(data: Dict[int, Any]) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少动作和其他在self._process_transition方法中定义的学习模式所需的必要数据（动作逻辑和值）。字典的键与输入数据相同，即环境ID。

提示

如果你想在这个策略上添加更多技巧，比如多项式采样中的温度因子，你可以将相关数据作为该方法的额外关键字参数传递。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考IMPALAPolicy的unittest：ding.policy.tests.test_impala。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。IMPALA中的_forward_eval通常使用确定性样本来获取动作，而_forward_collect通常使用随机样本方法来平衡探索和利用。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考IMPALAPolicy的unittest：ding.policy.tests.test_impala。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括损失和当前学习率等各种训练信息。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于IMPALA，列表中的每个元素都是一个字典，至少包含以下键：obs、action、logit、reward、next_obs、done。有时，它还包含其他键，如weight。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考IMPALAPolicy的unittest：ding.policy.tests.test_impala。

_get_train_sample(data: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可用于训练的样本列表。在IMPALA中，一个训练样本是经过处理的转换，其长度为unroll_len。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于IMPALA，它包含用于平衡探索和利用的collect_model（例如离散动作空间中的多项式采样机制），以及其他算法特定的参数，如unroll_len。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于IMPALA，它包含用于选择最佳动作的评估模型（例如，在离散动作中使用argmax机制贪婪地选择动作）。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于IMPALA，主要包含优化器、算法特定的参数（如损失权重和gamma）、主（学习）模型。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于IMPALA，它包含obs、next_obs、action、reward、done、logit。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于IMPALA，它包含动作和动作的logit。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于IMPALA，其注册名称为vac，import_names为ding.model.template.vac。

QMIX

请参考 ding/policy/qmix.py 获取更多详细信息。

QMIX策略

class ding.policy.QMIXPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

QMIX算法的策略类。QMIX是一种多智能体强化学习算法，您可以通过以下链接查看论文https://arxiv.org/abs/1803.11485。

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	qmix	RL policy register name, refer to registry POLICY_REGISTRY	this arg is optional, a placeholder
2	cuda	布尔	真	Whether to use cuda for network	this arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy
	priority	布尔	假	Whether use priority(PER)	priority sample, update priority
5	priority_ IS_weight	布尔	假	Whether use Importance Sampling Weight to correct biased update.	IS weight
6	learn.update_ per_collect	整数	20	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	this args can be vary from envs. Bigger val means more off-policy
7	learn.target_ update_theta	浮点数	0.001	Target network update momentum parameter.	between[0,1]
8	learn.discount _factor	浮点数	0.99	Reward’s future discount factor, aka. gamma	may be 1 when sparse reward env

_forward_collect(data: Dict[int, Any], eps: float) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。此外，此策略还需要eps参数进行探索，即经典的epsilon-greedy探索策略。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

• eps (float): 探索的epsilon值。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据（prev_state）。字典的键与输入数据相同，即环境ID。

注意

RNN的隐藏状态在策略中维护，因此我们不需要将它们传递到数据中，而是在回合结束时使用_reset_collect方法重置隐藏状态。此外，之前的隐藏状态对于训练是必要的，因此我们需要在_process_transition方法中返回它们。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

更多详细示例，请参考我们的QMIXPolicy单元测试：ding.policy.tests.test_qmix。

_forward_learn(data: List[List[Dict[str, Any]]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据（对于QMIX来说是轨迹），然后返回输出结果，包括各种训练信息，如损失、q值、梯度范数。

Arguments:

• data (List[List[Dict[int, Any]]]): 用于策略前向的输入数据，包括一批训练样本。对于每个字典元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过实用函数self._data_preprocess_learn在时间和批次维度上进行堆叠。对于QMIX，列表中的每个元素是一个长度为unroll_len的轨迹，轨迹列表中的元素是一个包含至少以下键的字典：obs、action、prev_state、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

更多详细示例，请参考我们的QMIXPolicy单元测试：ding.policy.tests.test_qmix。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一系列转换）数据，将其处理成可以直接用于训练的样本列表。在QMIX中，一个训练样本是经过处理的转换，具有unroll_len长度。此方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，您也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个样本是一个固定长度的轨迹，样本中的每个元素与输入转换的格式相似。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于QMIX，它包含collect_model，通过epsilon-greedy采样机制平衡探索和利用，并维护rnn的隐藏状态。此外，还有一些关于其他算法特定参数的初始化操作，如burnin_step、unroll_len和nstep。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括一些属性和模块。对于QMIX，主要包含优化器、算法特定的参数如gamma、主模型和目标模型。由于使用了RNN，所有模型都应该用hidden_state进行包装，这需要以适当的大小进行初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

提示

对于多智能体算法，我们经常需要使用agent_num来初始化一些必要的变量。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。 - agent_num (int): 由于这是一个多智能体算法，我们需要输入智能体的数量。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于QMIX，它包含观测值、下一个观测值、动作、前一个状态、奖励和完成标志。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，通常包括在多智能体环境（如MPE和SMAC）中的agent_obs和global_obs。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于QMIX，它包含动作和RNN的prev_state。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_reset_collect(data_id: List[int] | None = None) → None

Overview:

在必要时重置一些用于评估模式的状态变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有状态变量。否则，它将根据data_id重置状态变量。例如，在data_id中的不同环境/情节在评估时将具有不同的RNN隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的有状态变量（例如，QMIX中的RNN隐藏状态）。

_reset_eval(data_id: List[int] | None = None) → None

Overview:

在必要时重置一些用于评估模式的状态变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有状态变量。否则，它将根据data_id重置状态变量。例如，在data_id中的不同环境/情节在评估时将具有不同的RNN隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的有状态变量（例如，QMIX中的RNN隐藏状态）。

_reset_learn(data_id: List[int] | None = None) → None

Overview:

在必要时为学习模式重置一些有状态的变量，例如RNN的隐藏状态或某些特殊算法的记忆库。如果data_id为None，则意味着重置所有有状态的变量。否则，它将根据data_id重置有状态的变量。例如，data_id中的不同轨迹在RNN中将具有不同的隐藏状态。

Arguments:

• data_id (Optional[List[int]]): 数据的id，用于重置由data_id指定的有状态变量（例如QMIX中的RNN隐藏状态）。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型和优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认模型设置以进行演示。

Returns:

• model_info (Tuple[str, List[str]]): 模型名称和模式导入名称

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。对于QMIX，ding.model.qmix.qmix

CQL

请参考 ding/policy/cql.py 获取更多详细信息。

CQL策略

class ding.policy.CQLPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

CQL算法用于连续控制的策略类。论文链接：https://arxiv.org/abs/2006.04779.

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	cql	RL policy register name, refer to registry POLICY_REGISTRY	this arg is optional, a placeholder
2	cuda	布尔	真	Whether to use cuda for network
3	random_ collect_size	整数	10000	Number of randomly collected training samples in replay buffer when training starts.	Default to 10000 for SAC, 25000 for DDPG/ TD3.
4	model.policy_ embedding_size	整数	256	Linear layer size for policy network.
5	model.soft_q_ embedding_size	整数	256	Linear layer size for soft q network.
6	model.value_ embedding_size	整数	256	Linear layer size for value network.	Defalut to None when model.value_network is False.
7	learn.learning _rate_q	浮点数	3e-4	Learning rate for soft q network.	Defalut to 1e-3, when model.value_network is True.
8	learn.learning _rate_policy	浮点数	3e-4	Learning rate for policy network.	Defalut to 1e-3, when model.value_network is True.
9	learn.learning _rate_value	浮点数	3e-4	Learning rate for policy network.	Defalut to None when model.value_network is False.
10	learn.alpha	浮点数	0.2	Entropy regularization coefficient.	alpha is initiali- zation for auto alpha, when auto_alpha is True
11	learn.repara_ meterization	布尔	真	Determine whether to use reparameterization trick.
12	learn. auto_alpha	布尔	假	Determine whether to use auto temperature parameter alpha.	Temperature parameter determines the relative importance of the entropy term against the reward.
13	learn.- ignore_done	布尔	假	Determine whether to ignore done flag.	Use ignore_done only in halfcheetah env.
14	learn.- target_theta	浮点数	0.005	Used for soft update of the target network.	aka. Interpolation factor in polyak aver aging for target networks.

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从离线数据集中输入一些训练批次数据，然后返回输出结果，包括损失、动作、优先级等各种训练信息。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于CQL，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于SAC，主要包含三个优化器，算法特定的参数如gamma、min_q_weight、with_lagrange和with_q_entropy，以及主模型和目标模型。特别是，用于平衡最大熵目标的auto_alpha机制也在这里初始化。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

离散CQL策略

class ding.policy.DiscreteCQLPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

离散CQL算法在离散动作空间环境中的策略类。 论文链接：https://arxiv.org/abs/2006.04779。

_forward_learn(data: List[Dict[str, Any]]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从离线数据集中输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于DiscreteCQL，列表中的每个元素都是一个包含至少以下键的字典：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma，用于n步回报计算。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于DiscreteCQL，主要包含优化器、算法特定的参数如gamma、nstep和min_q_weight，以及主模型和目标模型。如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

决策变换器

请参考 ding/policy/dt.py 获取更多详细信息。

DTPolicy

class ding.policy.DTPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

决策变换器算法在离散环境中的策略类。 论文链接：https://arxiv.org/abs/2106.01345。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（评估策略性能，例如与环境交互。前向意味着策略从环境中获取一些输入数据（当前观察/回报目标和历史信息），然后返回输出数据，例如与环境交互的动作。参数： - data (Dict[int, Any]): 用于策略前向的输入数据，至少包括观察和奖励以计算运行回报目标。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

决策变换器在评估时会对不同类型的环境执行不同的操作。

_forward_learn(data: List[Tensor]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从离线数据集中输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、当前学习率等。

Arguments:

• data (List[torch.Tensor]): 用于策略前向的输入数据，包括一系列处理过的torch.Tensor数据，即时间步、状态、动作、回报、轨迹掩码。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于DQN，它包含评估模型，一些算法特定的参数，如context_len、max_eval_ep_len等。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

提示

为了评估完整的片段，我们需要为transformer推理维护一些历史信息。这些变量需要在_init_eval中初始化，并在必要时在_reset_eval中重置。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于决策变换器，它主要包含优化器、算法特定的参数，如rtg_scale和学习率调度器。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_reset_eval(data_id: List[int] | None = None) → None

Overview:

在必要时为评估模式重置一些有状态的变量，例如用于决策变压器的变压器的历史信息。如果data_id为None，则意味着重置所有有状态的变量。否则，它将根据data_id重置有状态的变量。例如，在data_id中的不同环境/情节在评估时将有不同的历史。

Arguments:

• data_id (Optional[List[int]]): 数据的ID，用于重置由data_id指定的状态变量。

PDQN

请参考 ding/policy/pdqn.py 了解更多详情。

PDQN策略

class ding.policy.PDQNPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

PDQN算法的策略类，它在离散-连续混合动作空间上扩展了DQN算法。 论文链接: https://arxiv.org/abs/1810.06394.

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	pdqn	RL policy register name, refer to registry POLICY_REGISTRY	This arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network	This arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy	This value is always False for PDQN
4	priority	布尔	假	Whether use priority(PER)	Priority sample, update priority
5	priority_IS _weight	布尔	假	Whether use Importance Sampling Weight to correct biased update. If True, priority must be True.
6	discount_ factor	浮点数	0.97, [0.95, 0.999]	Reward’s future discount factor, aka. gamma	May be 1 when sparse reward env
7	nstep	整数	1, [3, 5]	N-step reward discount sum for target q_value estimation
8	learn.update per_collect	整数	3	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	This args can be vary from envs. Bigger val means more off-policy
9	learn.batch_ size _gpu	整数	64	The number of samples of an iteration
11	learn.learning _rate	浮点数	0.001	Gradient step length of an iteration.
12	learn.target_ update_freq	整数	100	Frequence of target network update.	Hard(assign) update
13	learn.ignore_ done	布尔	假	Whether ignore done for target value calculation.	Enable it for some fake termination env
14	collect.n_sample	整数	[8, 128]	The number of training samples of a call of collector.	It varies from different envs
15	collect.unroll _len	整数	1	unroll length of an iteration	In RNN, unroll_len>1
16	collect.noise _sigma	浮点数	0.1	add noise to continuous args during collection
17	other.eps.type	字符串	exp	exploration rate decay type	Support [‘exp’, ‘linear’].
18	other.eps. start	浮点数	0.95	start value of exploration rate	[0,1]
19	other.eps. end	浮点数	0.05	end value of exploration rate	[0,1]
20	other.eps. decay	整数	10000	decay length of exploration	greater than 0. set decay=10000 means the exploration rate decay from start value to end value during decay length.

_forward_collect(data: Dict[int, Any], eps: float) → Dict[int, Any]

Overview:

收集模式下的策略前向函数（通过与环境的交互收集训练数据）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回输出数据，例如与环境交互的动作。此外，此策略还需要eps参数进行探索，即经典的epsilon-greedy探索策略。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

• eps (float): 探索的epsilon值。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，包括至少一个动作和其他在self._process_transition方法中定义的学习模式所需的必要数据。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PDQNPolicy单元测试：ding.policy.tests.test_pdqn。

_forward_eval(data: Dict[int, Any]) → Dict[int, Any]

Overview:

评估模式下的策略前向函数（通过与环境的交互来评估策略性能）。前向意味着策略从环境中获取一些必要的数据（主要是观察），然后返回与环境交互的动作。

Arguments:

• data (Dict[int, Any]): 用于策略前向传播的输入数据，至少包括观测值。字典的键是环境ID，值是对应环境的数据。

Returns:

• 输出 (Dict[int, Any]): 策略前向的输出数据，至少包括动作。字典的键与输入数据相同，即环境ID。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PDQNPolicy单元测试：ding.policy.tests.test_pdqn。

_forward_learn(data: Dict[str, Any]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、q值、目标q值、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于PDQN，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的PDQNPolicy单元测试：ding.policy.tests.test_pdqn。

_get_train_sample(transitions: List[Dict[str, Any]]) → List[Dict[str, Any]]

Overview:

对于给定的轨迹（转换，一个转换列表）数据，将其处理成可以直接用于训练的样本列表。在PDQN中，一个训练样本是一个处理过的转换。这个方法通常用于收集器中，在训练前执行必要的RL数据预处理，这可以帮助学习者分摊相关的时间消耗。此外，你也可以将此方法实现为一个恒等函数，并在self._forward_learn方法中进行数据处理。

Arguments:

• transitions (List[Dict[str, Any]): 轨迹数据（一个转换列表），每个元素的格式与self._process_transition方法的返回值相同。

Returns:

• 样本 (List[Dict[str, Any]]): 处理后的训练样本，每个元素的格式与输入转换类似，但可能包含更多用于训练的数据，例如n步奖励和目标观测值。

_init_collect() → None

Overview:

初始化策略的收集模式，包括相关属性和模块。对于PDQN，它包含collect_model，用于通过epsilon-greedy采样机制和连续动作机制来平衡探索和利用，此外，其他算法特定的参数如unroll_len和nstep也在这里初始化。 如果collect字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_collect方法中设置一些特殊的成员变量，最好给它们加上前缀_collect_，以避免与其他模式冲突，例如self._collect_attr1。

提示

一些变量需要在不同的模式中独立初始化，例如PDQN中的gamma和nstep。这种设计是为了方便不同策略模式的并行执行。

_init_eval() → None

Overview:

初始化策略的评估模式，包括相关属性和模块。对于PDQN，它包含评估模型，以贪婪地选择具有argmax q_value机制的动作。 如果eval字段在enable_field中，此方法将在__init__方法中调用。

注意

如果你想在_init_eval方法中设置一些特殊的成员变量，最好给它们加上前缀_eval_，以避免与其他模式冲突，例如self._eval_attr1。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于PDQN，主要包含两个优化器，算法特定的参数如nstep和gamma，以及主模型和目标模型。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_load_state_dict_learn(state_dict: Dict[str, Any]) → None

Overview:

将state_dict变量加载到策略学习模式中。

Arguments:

• state_dict (Dict[str, Any]): 之前保存的策略学习状态的字典。

提示

如果你只想加载模型的部分内容，你可以简单地将strict参数在load_state_dict中设置为False，或者参考ding.torch_utils.checkpoint_helper进行更复杂的操作。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

_process_transition(obs: Tensor, policy_output: Dict[str, Tensor], timestep: namedtuple) → Dict[str, Tensor]

Overview:

处理和打包一个时间步的转换数据到一个字典中，该字典可以直接用于训练并保存在回放缓冲区中。对于PDQN，它包含obs、next_obs、action、reward、done和logit。

Arguments:

• obs (torch.Tensor): 当前时间步的环境观察值，例如Atari中的堆叠2D图像。

• policy_output (Dict[str, torch.Tensor]): 策略网络的输出，以观察作为输入。对于PDQN，它包含混合动作和动作的logit（离散部分的q_value）。

• 时间步长 (namedtuple): 环境步骤方法返回的执行结果命名元组，除了所有元素都已转换为张量数据。通常，它包含下一个观测值、奖励、完成标志、信息等。

Returns:

• transition (Dict[str, torch.Tensor]): 当前时间步的已处理转换数据。

_state_dict_learn() → Dict[str, Any]

Overview:

返回学习模式的状态字典，通常包括模型、目标模型、离散部分优化器和连续部分优化器。

Returns:

• state_dict (Dict[str, Any]): 当前策略学习状态的字典，用于保存和恢复。

default_model() → Tuple[str, List[str]]

Overview:

返回此算法的默认神经网络模型设置以供演示。__init__ 方法将自动调用此方法以获取默认模型设置并创建模型。

Returns:

• model_info (Tuple[str, List[str]]): 注册的模型名称和模型的导入名称。

注意

用户可以定义和使用自定义的网络模型，但必须遵守由import_names路径指示的相同接口定义。例如，关于PDQN，其注册名称为pdqn，import_names为ding.model.template.pdqn。

MDQN

请参考 ding/policy/mdqn.py 获取更多详细信息。

MDQN策略

class ding.policy.MDQNPolicy(cfg: EasyDict, model: Module | None = None, enable_field: List[str] | None = None)

Overview:

Munchausen DQN算法的策略类，通过辅助目标进行扩展。 论文链接：https://arxiv.org/abs/2007.14430.

Config:

ID	符号	类型	默认值	描述	其他（形状）
1	type	字符串	mdqn	RL policy register name, refer to registry POLICY_REGISTRY	This arg is optional, a placeholder
2	cuda	布尔	假	Whether to use cuda for network	This arg can be diff- erent from modes
3	on_policy	布尔	假	Whether the RL algorithm is on-policy or off-policy
4	priority	布尔	假	Whether use priority(PER)	Priority sample, update priority
5	priority_IS _weight	布尔	假	Whether use Importance Sampling Weight to correct biased update. If True, priority must be True.
6	discount_ factor	浮点数	0.97, [0.95, 0.999]	Reward’s future discount factor, aka. gamma	May be 1 when sparse reward env
7	nstep	整数	1, [3, 5]	N-step reward discount sum for target q_value estimation
8	learn.update per_collect _gpu	整数	1	How many updates(iterations) to train after collector’s one collection. Only valid in serial training	This args can be vary from envs. Bigger val means more off-policy
10	learn.batch_ size	整数	32	The number of samples of an iteration
11	learn.learning _rate	浮点数	0.001	Gradient step length of an iteration.
12	learn.target_ update_freq	整数	2000	Frequence of target network update.	Hard(assign) update
13	learn.ignore_ done	布尔	假	Whether ignore done for target value calculation.	Enable it for some fake termination env
14	collect.n_sample	整数	4	The number of training samples of a call of collector.	It varies from different envs
15	collect.unroll _len	整数	1	unroll length of an iteration	In RNN, unroll_len>1
16	other.eps.type	字符串	exp	exploration rate decay type	Support [‘exp’, ‘linear’].
17	other.eps. start	浮点数	0.01	start value of exploration rate	[0,1]
18	other.eps. end	浮点数	0.001	end value of exploration rate	[0,1]
19	other.eps. decay	整数	250000	decay length of exploration	greater than 0. set decay=250000 means the exploration rate decay from start value to end value during decay length.
20	entropy_tau	浮点数	0.003	the ration of entropy in TD loss
21	alpha	浮点数	0.9	the ration of Munchausen term to the TD loss

_forward_learn(data: Dict[str, Any]) → Dict[str, Any]

Overview:

学习模式下的策略前向函数（训练策略并更新参数）。前向意味着策略从回放缓冲区输入一些训练批次数据，然后返回输出结果，包括各种训练信息，如损失、动作间隙、剪辑比例、优先级。

Arguments:

• data (List[Dict[int, Any]]): 用于策略前向传播的输入数据，包括一批训练样本。对于列表中的每个元素，字典的键是数据项的名称，值是对应的数据。通常，值是torch.Tensor或np.ndarray或其字典/列表组合。在_forward_learn方法中，数据通常需要首先通过一些实用函数（如default_preprocess_learn）在批次维度上进行堆叠。对于MDQN，列表中的每个元素都是一个字典，至少包含以下键：obs、action、reward、next_obs、done。有时，它还包含其他键，如weight和value_gamma。

Returns:

• info_dict (Dict[str, Any]): 表示训练结果的信息字典，该字典将被记录在文本日志和tensorboard中，值必须是python标量或标量列表。有关字典的详细定义，请参考_monitor_vars_learn方法的代码。

注意

输入值可以是 torch.Tensor 或字典/列表的组合，当前策略支持所有这些类型。对于不支持的数据类型，主要原因是相应的模型不支持它。您可以实现自己的模型，而不是使用默认模型。有关更多信息，请在 GitHub 仓库中提出问题，我们将继续跟进。

注意

有关更详细的示例，请参考我们的MDQNPolicy单元测试：ding.policy.tests.test_mdqn。

_init_learn() → None

Overview:

初始化策略的学习模式，包括相关属性和模块。对于MDQN，它包含优化器、算法特定的参数，如entropy_tau、m_alpha和nstep，以及主模型和目标模型。 如果learn字段在enable_field中，此方法将在__init__方法中调用。

注意

对于需要保存和加载的成员变量，请参考_state_dict_learn和_load_state_dict_learn方法。

注意

对于需要监控的成员变量，请参考_monitor_vars_learn方法。

注意

如果你想在_init_learn方法中设置一些特殊的成员变量，最好给它们加上前缀_learn_，以避免与其他模式冲突，例如self._learn_attr1。

_monitor_vars_learn() → List[str]

Overview:

返回用于记录self._forward_learn返回字典的必要键。日志模块，例如文本日志、tensorboard日志，将使用这些键来保存相应的数据。

Returns:

• 必要的键 (List[str]): 需要记录的键的列表。

策略工厂

请参考 ding/policy/policy_factory.py 获取更多详细信息。

策略工厂

class ding.policy.PolicyFactory

Overview:

策略工厂类，用于生成不同用途的策略。例如随机动作策略，当random_collect_size > 0时，用于初始样本收集以更好地进行探索。

Interfaces:

get_random_policy

static get_random_policy(policy: Policy.collect_mode, action_space: gym.spaces.Space = None, forward_fn: Callable = None) → Policy.collect_mode

Overview:

根据给定的动作空间，定义随机策略的前向函数，然后将其与给定策略的其他接口打包，并返回策略的最终收集模式接口。

Arguments:

• 策略 (Policy.collect_mode): 策略的收集模式接口。

• action_space (gym.spaces.Space): 环境的动作空间，gym风格。

• forward_fn (Callable): 如果动作空间过于复杂，你可以定义自己的前向函数并将其传递给此函数，注意在这种情况下你应该将 action_space 设置为 None。

Returns:

• random_policy (Policy.collect_mode): 随机策略的收集模式接口。

get_random_policy

ding.policy.get_random_policy(cfg: EasyDict, policy: Policy.collect_mode, env: BaseEnvManager) → Policy.collect_mode

Overview:

获取相应随机策略的入口函数。如果策略在转换中需要特殊的数据项，则返回自身，否则，我们将使用PolicyFactory返回一个通用的随机策略。

Arguments:

• cfg (EasyDict): EasyDict类型的字典配置。

• 策略 (Policy.collect_mode): 策略的收集模式接口。

• env (BaseEnvManager): 环境管理器实例，用于获取动作空间以生成随机动作。

Returns:

• random_policy (Policy.collect_mode): 随机策略的收集模式接口。

常用工具

请参考 ding/policy/common_utils.py 获取更多详细信息。

默认预处理学习

ding.policy.default_preprocess_learn(data: List[Any], use_priority_IS_weight: bool = False, use_priority: bool = False, use_nstep: bool = False, ignore_done: bool = False) → Dict[str, Tensor]

Overview:

策略中_forward_learn方法的默认数据预处理，包括堆叠批量数据，预处理忽略完成，n步和优先级IS权重。

Arguments:

• 数据 (List[Any]): 训练批次样本的列表，每个样本是一个PyTorch张量的字典。

• use_priority_IS_weight (bool): 是否使用优先级IS权重校正，如果为True，此函数将设置每个样本的权重为优先级IS权重。

• use_priority (bool): 是否使用优先级，如果为True，此函数将设置优先级IS权重。

• use_nstep (bool): 是否使用n步TD误差，如果为True，此函数将重新调整奖励。

• ignore_done (bool): 是否忽略完成状态，如果为True，此函数会将done设置为0。

Returns:

• 数据 (Dict[str, torch.Tensor]): 预处理后的字典数据，其值可以直接用于后续模型的前向传播和损失计算。

单环境前向包装器

ding.policy.single_env_forward_wrapper(forward_fn: Callable) → Callable

Overview:

包装策略以支持策略与单一环境之间的健身房式交互。

Arguments:

• forward_fn (Callable): 策略的原始前向函数。

Returns:

• wrapped_forward_fn (Callable): 策略的包装前向函数。

Examples:

>>> env = gym.make('CartPole-v0')
>>> policy = DQNPolicy(...)
>>> forward_fn = single_env_forward_wrapper(policy.eval_mode.forward)
>>> obs = env.reset()
>>> action = forward_fn(obs)
>>> next_obs, rew, done, info = env.step(action)

single_env_forward_wrapper_ttorch

ding.policy.single_env_forward_wrapper_ttorch(forward_fn: Callable, cuda: bool = True) → Callable

Overview:

包装策略以支持策略与单个环境之间的gym风格交互，适用于treetensor（ttorch）数据。

Arguments:

• forward_fn (Callable): 策略的原始前向函数。

• cuda (bool): 是否在策略中使用cuda，如果为True，此函数将把输入数据移动到cuda。

Returns:

• wrapped_forward_fn (Callable): 策略的包装前向函数。

Examples:

>>> env = gym.make('CartPole-v0')
>>> policy = PPOFPolicy(...)
>>> forward_fn = single_env_forward_wrapper_ttorch(policy.eval)
>>> obs = env.reset()
>>> action = forward_fn(obs)
>>> next_obs, rew, done, info = env.step(action)