Python Low Level API

1. DecisionSteps— contains the data from Agents belonging to the same "Behavior" in the simulation, such as observations and rewards. Only Agents that requested a decision since the last call to are in the DecisionSteps object.

包含的数据来自属于代理的行为，例如画面和奖励。仅在上一次调用env.step()之后代理请求完一个决策才在DecisionSteps对象里。

2. TerminalSteps— contains the data from Agents belonging to the same "Behavior" in the simulation, such as observations and rewards. Only Agents whose episode ended since the last call to are in the TerminalSteps object.

包含的数据来自属于代理的行为，例如画面和奖励。仅有上一次调用env.step()之后每个代理的回合结束了才在TerminalSteps对象里。

3. BehaviorSpec— describes the shape of the observation data inside DecisionSteps and TerminalSteps as well as the expected action shapes.

描述了DecisionSteps和TerminalSteps中观测数据的形状以及预期的动作形状。

该数据为字典类型，key为对应的behavior name。其长度与behavior_name的个数一样，其而不是代理个数。

一个代理的行为是由一群代理通过behaviourName参数定义的，通过共享相同的画面和动作类型。（这些在behaviorSpec对象里共享）。可以把agent behavior看作是一群代理共用着相同的策略。所有代理有着相同的行为，拥有相同的目标和奖励信号。

经过验证，不同团队下的相同behavior name标识，最后输出到Python端是不同的behavior name。

主要是ml-agents在最后输出时name的时候对这个behavior name进行了字符串的拼接，即behavior name+team id，组成新的 behavior name。目的是想区分不同团队下的代理，以更好的进行团队合作。这种其实适用于mapoca这种考虑团队合作以及个人对团队收益影响的算法，以使团队收益最大化。对于mappo、maddpg这种直接将其他代理算进观察空间的算法，来训练合作和博弈。mapoca的做法显得更加适合团队合作的环境。

相同behavior name相同团队，最后输出的behavior name是肯定相同的。

在模拟环境中，代理必须拥有Behavior Parameters用来沟通，Behavior Type 必须设置为 Default。

MyUnityEnvironment

ml-agents/docs/Python-LLAPI.md at develop · Unity-Technologies/ml-agents · GitHub

构造环境

work-id 可以用于指定训练进程id，保证唯一被使用。

成员

reset：重置环境。

close：关闭环境。

step：类似unity的update帧的概念，但不是不对应unity的生命周期。

BehaviorSpec：返回behaviour Name到BehaviorSpec的一个映射，随着在模拟环境种增加了新的Agent行为，则映射中的条目数量在未来也会增加。

Get Steps : env.get_steps(behavior_name: str)

返回一个元组，第一个元素为DecisionSteps, 第二个元素为TerminalSteps

behavior_name作为键，对应着DecisionSteps, TerminalSteps中某条step。

DecisionSteps还包含下一个操作的操作掩码，而TerminalSteps包含终止的原因（Agent是否达到最大步长而被中断）

SetActions：env.set_actions(behavior_name: str, action: ActionTuple)

为所有的代理设置的action。action参数是一个元组，由一群离散的action和连续的action组成的。

元组的第一个维度表示 在上一次调用env.step()之后请求完决策的代理数量。

第二个维度是对应数组的离散或连续动作的数量。

Set Action for Agent :

env.set_action_for_agent(agent_group: str, agent_id: int, action: ActionTuple)

一般来说代理的行为都一样，但也有例外。此函数用来设置一个特殊的代理。agent_group为Agent所属的组名，agent_id为Agent的整数标识。

Observations

一群代理收集来的画面数据集合。数组第一个维度代表这群代理的批次大小，即在上一次调用env.step()之后请求完决策的代理数量。

Steps和Step的不同

Steps，比如DecisionSteps 表示关于包含了一整个批次的所有代理的状态信息。而Step仅包含了单个代理的信息

DecisionSteps

obs：obs字段是一群代理收集来的画面数据集合。数组第一个维度代表这群代理的批次大小，即在上一次调用env.step()之后请求完决策的代理数量。

reward：长度为批大小的float向量,自上一个step以来每个agent所获得的奖励。

agent_id:agent_id是长度为批大小的int向量，包含对应Agent的唯一标识符。这用于跨模拟步骤跟踪代理。

ML Python Low Level下的agent_id应该是从0开始递增的。

Action_mask是一个可选的二维布尔数组列表，仅在使用多离散动作时可用。每个数组对应一个操作分支。每个数组的第一个维度是批处理大小，第二个维度包含分支的每个操作的掩码。如果为true，则在此模拟步骤中代理无法使用该操作。

len(DecisionSteps) : 在上一次调用env.step()之后请求完决策的代理数量。

DecisionSteps[agent_id]：返回一个agent对应的一个DecisionStep

TerminalSteps

跟DecisionSteps类似，除此之外还有一个Interrupted属性。

Interrupted：Interrupted是一个长度为批次大小的布尔值数组。如果关联代理自最后一个决策步骤后中断，则为true。例如，如果Agent达到了该集的最大步数。

len(DecisionSteps) : 在上一次调用env.step()之后请求完决策的代理数量。

TerminalSteps[agent_id]：返回一个agent对应的一个TerminalStep

BehaviorSpec

observation_specs：observation_spec列表

action_spec：action_spec是一个ActionSpec名称元组，它定义了代理的action数量和类型。

Tips：ObservationSpec的顺序与DecisionSteps、DecisionStep、TerminalSteps和TerminalStep中画面的顺序相同。

observation_spec

每个ObservationSpec对应于一个画面的属性:

shape：Shape是一个int元组，它对应于画面这个数组对象的形状，即维度(没有代理维度的数量)。

dimension_property：是一个标志元组，其中包含有关如何在相应维度中处理数据的额外信息。

Observation_type是一个enum，对应于生成数据的观测类型（default, goal...)）

Action_spec

continuous_size:连续型动作的数量

discrete_size：离散型动作的数量

• discrete_branches is a Tuple of ints. Each int corresponds to the number of different options for each branch of the action. For example: In a game direction input (no movement, left, right) and jump input (no jump, jump) there will be two branches (direction and jump), the first one with 3 options and the second with 2 options. (discrete_size = 2 and discrete_action_branches = (3,2,))

通信

除了上面所述的Unity和python之间的通信方式之外，我们还提供了共享agent-agnostic信息的方法。

这些附加的方法被称为侧通道。ML-Agents包括两个现成的侧通道，如下所述。也可以创建自定义的侧通道来在Unity环境和Python之间传递任何额外的数据。创建自定义侧通道的说明可以在这里找到。

ml-agents/docs/Python-LLAPI.md at develop · Unity-Technologies/ml-agents · GitHub

侧通道作为单独的类存在，这些类被实例化，然后作为列表传递给UnityEnvironment类构造函数的side_channels参数。

一个侧通道 仅仅当env.step or env.reset() 被调用时接受或发送消息。

例如官方api中的EngineConfigurationChannel、EnvironmentParameters就是侧通道：

EnvironmentParameters：EnvironmentParameters将允许您在环境中获取和设置预定义的数值。这对于调整特定于环境的设置或从环境中读取与代理无关的信息非常有用。您可以在侧通道上调用get_property和set_property来读取和写入属性。

环境参数

为我们的模拟环境通过配置文件来设置参数，供python与c#端获取

behaviors:
  BehaviorY:
    # < Same as above >

# Add this section
environment_parameters:
  my_environment_parameter: 3.0

有时候我们希望根据环境来变化我们的参数，比如改变某个奖励大小或改变环境的某个变量参数，总是由python端进行变化，c#从python端通过EnvironmentParameter对象GetWithDefault("key",defaultValueWhenNoExist)获取到这个key的值。

环境参数随机化

ml-agents/docs/Training-ML-Agents.md at develop · Unity-Technologies/ml-agents · GitHub

即按照配置规则，进行随机化。

behaviors:
  BehaviorY:
    # < Same as above >

# Add this section
environment_parameters:
  mass:
    sampler_type: uniform
    sampler_parameters:
        min_value: 0.5
        max_value: 10

  length:
    sampler_type: multirangeuniform
    sampler_parameters:
        intervals: [[7, 10], [15, 20]]

  scale:
    sampler_type: gaussian
    sampler_parameters:
        mean: 2
        st_dev: .3

课程学习

ml-agents/docs/Training-ML-Agents.md at develop · Unity-Technologies/ml-agents · GitHub

课程学习，通俗易懂就是阶段性学习。是一种训练机器学习模型的方法。用于支持逐步训练智能体的能力。它可以帮助在训练过程中逐渐增加任务的难度，并逐步引入新的环境和奖励。使其逐渐适应更复杂的任务。

简单来说，它就是分阶段的变化环境参数。当满足当前阶段的条件（阈值）时，课程将进入下一个阶段。最后一个阶段就不需要指定条件了。completion_criteria
measure：表示用什么来衡量学习进度和课程进展。可以是reward 或progress 、Elo 选项

min_lesson_length：表示在阶段完成之前在这个阶段必须完成的最小的回合数。如果达到该回合数，即threshold阈值将用于判断是否结束课程，进入下一个阶段。如果设置衡量目标是奖励，则目标为平均累积奖励

behavior：指定要跟踪的行为。可以有不同名称的多种行为，每种行为都在不同的训练点。此设置允许课程只跟踪其中一个。

示例：

environment_parameters:
  ball_touch:
    curriculum:
      - name: Lesson0
        completion_criteria:
          measure: progress
          behavior: Guard
          signal_smoothing: true
          min_lesson_length: 100
          threshold: 0.05
        value: 0.15
      - name: Lesson1
        completion_criteria:
          measure: progress
          behavior: Guard
          signal_smoothing: true
          min_lesson_length: 100
          threshold: 0.1
        value: 0.08
      - name: Lesson3
        value: 0.005

tensorboard使用

切换目录  --logdir results  训练日志与结果存在当前目录下的results文件夹下

tensorboard --logdir results --port 6006

在Jupyter Notebook中，您可以使用调试器来调试代码。调试器是一个交互式工具，可以帮助您找到代码中的错误，并逐步执行代码以了解代码的运行情况。

要使用调试器，您需要在代码单元格中添加调试语句，例如“pdb.set_trace()”。当代码执行到这个语句时，调试器将停止代码的执行，并允许您逐步执行代码，查看变量的值和代码的执行情况