入门指南【ML-Agents 官方文档翻译（ML-Agent 1.9.1，Unity 2018-2020）】

Getting Started Guide

本指南将讲解在 Unity 中打开其中一个示例工程 ，训练一个Agent，并将训练过的模型嵌入到 Unity 环境中的完整过程。
阅读本教程之后，您应该能够训练任何示例环境。
如果你不熟悉的 Unity Engine，查看我们的 Background: Unity 章节。
此外，如果你不熟悉机器学习，请查看我们的 Background: Machine Learning 页面，以了解简要概述和有用的建议。

我们将使用 3D Balance Ball 环境，它包含许多 Agent 立方体和球（它们都是彼此独立的副本）。
每个 Agent 立方体都试图通过水平或垂直旋转来防止球掉落。
在这种环境中，Agent 立方体就是我们的 Agent，它在每一步模拟后根据平衡球状态获得奖励。
Agent 也会因为球的掉落而获得负奖励。
训练的目标是让 Agent 学会用通过旋转让球在头顶上保持平衡。

让我们开始吧！

Installation

如果你还没有安装好 ML-Agents，请先按照 installation instructions 进行配置。
然后，打开包含所有示例环境的 Unity 项目：

1. 通过导航到菜单中的 Window -> Package Manager 来打开包管理器窗口。
2. 导航到 ML-Agents 包并单击。
3. 找到 3D Ball 示例并点击 Import。
4. 在 Project 窗口中，转到 Assets/ML-Agents/Examples/3DBall/Scenes 文件夹并打开 3DBall 场景。

Understanding a Unity Environment

Agent 是一个自主的参与者，它观测并与_环境_交互。
在 Unity 的中，环境是包含一个或多个 Agent 对象（及与 Agent 交互的其他实体）的场景。

**注意：**在Unity中，场景中所有物体的基础对象都是 GameObject。
GameObject 本质上是一个容器，包括行为、图像、物理等。
要查看组成 GameObject 的组件（Component），请在 Scene 窗口中选择 GameObject，然后打开 Inspector 窗口。
Inspector 显示了 GameObject 上的每个组件。

打开 3D Balance Ball 场景后，可以看到场景内包含多个 Agent 立方体。
场景中的每个 Agent 立方体都是独立的，但它们的行为遵从相同的决策网络。
3D Balance Ball 这样做是为了加快训练速度，所有 12 个 Agent 都能同时参与训练。

Agent

Agent 是在环境中进行观测并做出动作的参与者。
在 3D Balance Ball 环境中，Agent 组件被挂在12个 “Agent” GameObject 上。
基础的 Agent 对象有几个影响其行为的属性：

• Behavior Parameters — 每个 Agent 都必须有一个 Behavior Parameter 组件。
  Behavior Parameter 决定了 Agent 如何做出决策。
• Max Step — 定义了 Agent 在一个 Episode 结束前可以进行多少个模拟步骤。
  在 3D Balance Ball 中，Agent 在 5000 步模拟后结束，并重新开始一个新的 Episode。

Behavior Parameters : Vector Observation Space

在做出决策之前，Agent 收集自己对于所处世界中状态的观测。
观测向量是一个包含相关信息的浮点型数组，供 Agent 做出决策。

3D Balance Ball 示例的 Agent 的 Behavior Parameters 使用的 Space Size 为 8。
这意味着包含 Agent 观测的特征向量包含 8 个元素：Agent 立方体旋转的x和z分量以及球的相对位置和速度的x、y和z分量。

Behavior Parameters : Actions

Agent 以动作的形式得到下一步的指令。
ML-Agents Toolkit 将动作分为两种类型：连续（Continuous）和离散（Discrete）。
3D Balance Ball 例子使用了连续动作，即动作是一个可以连续变化的浮点数数组。
更具体地说，它使用 Space Size 为 2 数组分别控制 x轴 和 z 轴方向上的旋转，以保持小球在 Agent 头顶的平衡。

Running a pre-trained model

我们为 Agent 准备并配置了预训练模型（.onnx 文件）。
在 Unity 中，可以使用 Unity Inference Engine 来运行这些模型。
在本节中，我们展示如何使用 3D Ball 示例的预训练模型。

1. 在 Project 窗口中，找到 Assets/ML-Agents/Examples/3DBall/Prefabs 文件夹。
   打开 3DBall Prefab，并点击其中的 Agent 对象。
   你应该能在 Inspector 窗口中看到 Agent 的组件。

   注意：3DBall 场景是使用 3DBall Prefab 构建的。
   我们可以直接修改 3DBall Prefab 以更新场景，而不是逐一改动场景中的每个对象。

1. 在 Project 窗口中，找到位于 Assets/ML-Agents/Examples/3DBall/TFModels 中的 3DBall 模型。
   将模型拖到 Inspector 窗口中的 Behavior Parameters (Script) 组件下的 Model 属性中。

1. 打开 3DBall 场景，检查每个 Agent 的 Inspector 窗口。
   可以发现现在 Behavior Parameters 中都包含 3DBall 作为 Model 。

   注意：也可以选中场景内多个的多个 Agent 实例同时编辑。

2. 把模型的 Inference Device 属性设置为 CPU。

3. 点击 Unity 编辑器中的 Play 按钮，你会看到 Agent 在使用预训练模型控制平衡球。

Training a new model with Reinforcement Learning

搭建任何环境都需要从头开始训练 Agent 来生成一个模型文件（虽然本环境中的 Agent 已配置了预训练模型）。
在本节中将演示如何使用 ML-Agents Python 包中的一些强化学习算法来完成这一任务。
我们提供了一个方便的命令 mlagents-learn，它接受用于配置训练和推理阶段的参数。

Training the environment

1. 打开命令行。
2. 导航到克隆 ml-agents 仓库的文件夹。
   注意：如果你遵循默认的安装说明，那么你应该能够从任何目录运行 ‘mlagents-learn’ 的可执行体。
3. 运行命令：mlagents-learn config/ppo/3DBall.yaml --run-id=first3DBallRun
   • config/ppo/3DBall.yaml 是我们提供的默认训练配置文件的路径。config/ppo 文件夹包含了所有示例环境的训练配置文件，包括 3DBall。
   • run-id 是这个训练会话的唯一名称。
4. 当屏幕上显示 “Start training by pressing the Play button in the Unity Editor” 时，按下 Unity 中的 Play 按钮开始训练。

如果 mlagents-learn 已经正确地运行并开始训练，你应该看到如下结果：

INFO:mlagents_envs:
'Ball3DAcademy' started successfully!
Unity Academy name: Ball3DAcademy

INFO:mlagents_envs:Connected new brain:
Unity brain name: 3DBallLearning
        Number of Visual Observations (per agent): 0
        Vector Observation space size (per agent): 8
        Number of stacked Vector Observation: 1
INFO:mlagents_envs:Hyperparameters for the PPO Trainer of brain 3DBallLearning:
        batch_size:          64
        beta:                0.001
        buffer_size:         12000
        epsilon:             0.2
        gamma:               0.995
        hidden_units:        128
        lambd:               0.99
        learning_rate:       0.0003
        max_steps:           5.0e4
        normalize:           True
        num_epoch:           3
        num_layers:          2
        time_horizon:        1000
        sequence_length:     64
        summary_freq:        1000
        use_recurrent:       False
        memory_size:         256
        use_curiosity:       False
        curiosity_strength:  0.01
        curiosity_enc_size:  128
        output_path: ./results/first3DBallRun/3DBallLearning
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 1000. Mean Reward: 1.242. Std of Reward: 0.746. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 2000. Mean Reward: 1.319. Std of Reward: 0.693. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 3000. Mean Reward: 1.804. Std of Reward: 1.056. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 4000. Mean Reward: 2.151. Std of Reward: 1.432. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 5000. Mean Reward: 3.175. Std of Reward: 2.250. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 6000. Mean Reward: 4.898. Std of Reward: 4.019. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 7000. Mean Reward: 6.716. Std of Reward: 5.125. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 8000. Mean Reward: 12.124. Std of Reward: 11.929. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 9000. Mean Reward: 18.151. Std of Reward: 16.871. Training.
INFO:mlagents.trainers: first3DBallRun: 3DBallLearning: Step: 10000. Mean Reward: 27.284. Std of Reward: 28.667. Training.

可以发现，随着训练的进行，屏幕上的 Mean Reward 值是逐渐增加的。
这是训练取得成功的积极标志。

注意：你可以使用可执行体而非编辑器进行训练。
要做到这一点，请遵循 Using an Executable 中的说明。

Observing Training Progress

开始使用 mlagents-learn 进行训练后，ml-agents 目录下将建立一个 results 文件夹。
为了更仔细地观察训练过程，你可以使用 TensorBoard。
从命令行运行：

tensorboard --logdir results

然后在浏览器中打开 localhost:6006，查看 TensorBoard 汇总的统计信息，如下所示。
就本节而言，最重要的统计数据是 Environment/Cumulative Reward，它应该在训练过程中不断增加，最终趋近于 100，这是 Agent 能够累积的最大奖励。

Embedding the model into the Unity Environment

训练完成时，mlagents-learn 的训练进程将保存模型，命令行打印 Saved Model 的消息。
模型文件可以添加到 Unity 项目中，并与兼容的 Agent（生成模型的 Agent）一起使用。

注意：Saved Model 的消息出现时，不要立刻关闭 Unity 窗口。
要么等待训练进程关闭窗口，要么在命令行按 Ctrl+C。
如果手动关闭窗口，包含模型参数的 .onnx 文件可能不会导出到 ml-agents 文件夹中。

如果你已经使用 Ctrl+C 退出了训练，并想继续上一次的训练，再次运行相同的命令，附加 --resume 标志：

mlagents-learn config/ppo/3DBall.yaml --run-id=first3DBallRun --resume

训练完成的模型将保存为 results/<run-identifier>/<behavior_name>.onnx。
其中的 <behavior_name> 对应与模型相关联的 Agent 的 Behavior Name。
该文件对应于模型最新的 checkpoint。
现在可以通过以下步骤将这个训练过的模型嵌入到您的 Agent 中，步骤与上文 running-a-pre-trained-model 小节类似。

1. 把 onnx 模型文件移动到 Project/Assets/ML-Agents/Examples/3DBall/TFModels/。
2. 在 Unity 编辑器中找到上文提及的 3DBall 文件目录。
3. 打开 3DBall 场景中 Agent 所对应的 prefab：3DBall/Prefabs/3DBall.prefab。
4. 在 Hierarchy 窗口选中 Agent 对象，在 Inspector 窗口中查看 Behavior Parameter 组件。
5. 把 <behavior_name>.onnx 模型文件拖动到组件的 Model 位标。
6. 打开 3DBall 场景，按下编辑器顶部的 Play 按钮。

Next Steps

• 关于 ML-Agents Toolkit 的更多信息及背景知识，请查看ML-Agents Toolkit Overview页面。
• “Hello World”介绍如何创建自己的学习环境，请查看创建新的训练环境页面。
• 要了解本工具包中提供的更复杂的示例环境的概述，请查看示例环境页面。
• 关于各种培训选项的更多信息，请查看Training ML-Agents页面。