diff --git a/.gitattributes b/.gitattributes index c1e530428f..b2f6100a26 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,3 +2,4 @@ *.unity binary *.prefab binary *.meta binary +*.md text diff --git a/README.md b/README.md index 171ce6c06f..69020c0d15 100755 --- a/README.md +++ b/README.md @@ -72,6 +72,17 @@ make sure to include as much detail as possible. For any other questions or feedback, connect directly with the ML-Agents team at ml-agents@unity3d.com. +## Translations + +To make Unity ML-Agents accessible to the global research and +Unity developer communities, we're attempting to create and maintain +translations of our documentation. We've started with translating a subset +of the documentation to one language (Chinese), but we hope to continue +translating more pages and to other languages. Consequently, +we welcome any enhancements and improvements from the community. + +- [Chinese](docs/localized/zh-CN/) + ## License [Apache License 2.0](LICENSE) diff --git a/docs/localized/zh-CN/README.md b/docs/localized/zh-CN/README.md new file mode 100755 index 0000000000..7ebd571fbc --- /dev/null +++ b/docs/localized/zh-CN/README.md @@ -0,0 +1,75 @@ + + +# Unity ML-Agents (Beta) + +**注意:** 本文档为v0.3版本文档的部分翻译版,目前并不会随着英文版文档更新而更新。若要查看更新更全的英文版文档,请查看[这里](https://github.com/Unity-Technologies/ml-agents)。 + +**Unity Machine Learning Agents** (ML-Agents) 是一款开源的 Unity 插件, +使得我们得以在游戏环境和模拟环境中训练智能 agent。您可以使用 reinforcement learning(强化学习)、imitation learning(模仿学习)、neuroevolution(神经进化)或其他机器学习方法, 通过简单易用的 Python API进行控制,对 Agent 进行训练。我们还提供最先进算法的实现方式(基于 +TensorFlow),让游戏开发者和业余爱好者能够轻松地 +训练用于 2D、3D 和 VR/AR 游戏的智能 agent。 +这些经过训练的 agent 可用于多种目的, +包括控制 NPC 行为(采用各种设置, +例如多个 agent 和对抗)、对游戏内部版本进行自动化测试、以及评估不同游戏设计决策的预发布版本。ML-Agents 对于游戏开发者和 AI 研究人员双方 +都有利,因为它提供了一个集中的平台, +使得我们得以在 Unity 的丰富环境中测试 AI 的最新进展, +并使结果为更多的研究者和游戏开发者所用。 + +## 功能 +* 用于控制 Unity 环境的 Python API +* 10 多个示例 Unity 环境 +* 支持多种环境配置方案和训练方案 +* 使用 deep reinforcement learning(深度强化学习)技术训练带记忆的Agent +* 可轻松定义的 Curriculum Learning(课程学习)方案 +* 通过广播 Agent 行为实现监督学习 +* 内置 Imitation Learning(模仿学习)支持 +* 通过按需决策功能实现灵活的 Agent 控制 +* 在环境中可查看神经网络的输出 +* 通过 Docker 实现简化设置(测试功能) + +## 文档和参考 + +**除了安装和使用说明外,如需更多信息, +请参阅我们的[文档主页](docs/Readme.md)。**如果您使用的 +是 v0.3 之前的 ML-Agents 版本,强烈建议您参考 +我们的[关于迁移到 v0.3 的指南](/docs/Migrating-v0.3.md)。 + +我们还发布了一系列与 ML-Agents 相关的博客文章: +- reinforcement learning(强化学习)概念概述 +([多臂强盗](https://blogs.unity3d.com/2017/06/26/unity-ai-themed-blog-entries/) +和 [Q-learning](https://blogs.unity3d.com/2017/08/22/unity-ai-reinforcement-learning-with-q-learning/)) +- [在实际游戏中使用机器学习 Agent:初学者指南](https://blogs.unity3d.com/2017/12/11/using-machine-learning-agents-in-a-real-game-a-beginners-guide/) +- [文章](https://blogs.unity3d.com/2018/02/28/introducing-the-winners-of-the-first-ml-agents-challenge/)公布我们 +[第一个 ML-Agents 挑战](https://connect.unity.com/challenges/ml-agents-1)的获胜者 +- [文章](https://blogs.unity3d.com/2018/01/23/designing-safer-cities-through-simulations/) +概述如何利用 Unity 作为模拟器来设计更安全的城市。 + +除了我们自己的文档外,这里还有一些额外的相关文章: +- [Unity AI - Unity 3D 人工智能](https://www.youtube.com/watch?v=bqsfkGbBU6k) +- [游戏开发者学习机器学习](https://mikecann.co.uk/machine-learning/a-game-developer-learns-machine-learning-intent/) +- [在 Intel 体系结构上单独研究 Unity Technologies ML-Agents](https://software.intel.com/en-us/articles/explore-unity-technologies-ml-agents-exclusively-on-intel-architecture) + +## 社区和反馈 + +ML-Agents 是一个开源项目,我们鼓励并欢迎大家贡献自己的力量。 +如果您想做出贡献,请务必查看我们的 +[贡献准则](/CONTRIBUTING.md)和 +[行为准则](/CODE_OF_CONDUCT.md)。 + +您可以通过 Unity Connect 和 GitHub 与我们 +以及更广泛的社区进行交流: +* 加入我们的 +[Unity 机器学习频道](https://connect.unity.com/messages/c/035fba4f88400000) +与使用 ML-Agents 的其他人以及对机器学习充满热情的 Unity 开发者 +交流。我们使用该频道来展示关于 ML-Agents +(在更广泛的范围内,还包括游戏中的机器学习)的最新动态。 +* 如果您在使用 ML-Agents 时遇到任何问题,请 +[提交问题](https://github.com/Unity-Technologies/ml-agents/issues)并 +确保提供尽可能多的详细信息。 + +对于任何其他问题或反馈,请直接与 ML-Agents 团队联系, +地址为 ml-agents@unity3d.com。 + +## 许可证 + +[Apache 许可证 2.0](LICENSE) diff --git a/docs/localized/zh-CN/docs/Getting-Started-with-Balance-Ball.md b/docs/localized/zh-CN/docs/Getting-Started-with-Balance-Ball.md new file mode 100755 index 0000000000..43effcc307 --- /dev/null +++ b/docs/localized/zh-CN/docs/Getting-Started-with-Balance-Ball.md @@ -0,0 +1,355 @@ +# 3D Balance Ball 环境入门 + +本教程介绍在 Unity 中打开 ML-Agents 示例环境、 +构建 Unity 可执行文件、在其中训练 agent 以及 +最终将经过训练的模型嵌入到 Unity 环境中的端到端过程。 + +ML-Agents 包含大量[示例环境](Learning-Environment-Examples.md), +您可以通过这些环境来了解 ML-Agents 的 +不同使用方式。这些环境也可以用作新环境的模板 +或用作测试新 ML 算法的方法。阅读本教程后, +您应该能够了解并构建示例环境。 + +![3D Balance Ball](images/balance.png) + +本演练过程将使用 **3D Balance Ball** 环境。3D Balance Ball 包含 +大量平台和球(它们都是彼此的副本)。 +每个平台都会试图通过水平或垂直旋转的方式 +防止球掉落。在这种环境下,平台是一个 **agent**, +可以在对球进行平衡的每一步中获得奖励。agent 也会 +因为掉球而得到负奖励(惩罚)。训练过程的 +目标是让平台学会绝不掉球。 + +让我们开始吧! + +## 安装 + +为了安装和设置 ML-Agents、Python 所依赖的库和 Unity 软件, +请参阅[安装说明](Installation.md)。 + +## 了解 Unity 环境 (3D Balance Ball) + +agent 是一种观测并与_环境_交互的 +自主参与者 (actor)。在 ML-Agent的语境下,环境是一个包含一个 Academy, 一个或多个 Brain, 一个或多个Agent, Agent 与其他实体交互的场景。 + +![Unity Editor](images/mlagents-3DBallHierarchy.png) + +**注意:**在 Unity 中,场景内所有元素的基础对象均为 +_游戏对象_(GameObject)。游戏对象本质上是其他任何元素 +(包括行为、图形、物理等)的容器。要查看组成游戏对象的组件, +请在 Scene 窗口中选择 GameObject,然后打开 +Inspector 窗口。Inspector 会显示游戏对象上的每个组件。 + +在打开 3D Balance Ball 场景后,您可能会首先注意到它包含的 +不是一个平台,而是多个平台。场景中的每个平台都是 +独立的 agent,但它们全部共享同一个 brain。3D Balance Ball 通过 +这种方式可以加快训练速度,因为所有 12 个 agent 可以并行参与训练任务。 + +### Academy + +在这个示例场景中的 Academy 对象是 Ball3DAcademy 游戏对象。 +当您在 Inspector 中查看该 Academy 组件时,可以看到若干 +用于控制环境工作方式的属性。例如,Inspector中可以看到 +**Training** 和 **Inference Configuration** 属性, 在其中我们可以设置之后生成的 Unity 可执行文件的 +图形和 Time Scale 属性。Academy 在训练期间使用 +**Training Configuration**,而在不训练时使用 +**Inference Configuration**。(*Inference* 等同于**不**进行训练的任何时候,此时 agent 可以使用经过训练的模型控制,或用写定的代码控制,或让玩家直接控制。) +通常情况下,您需要为 **Training configuration** 设置低图形质量 +和高Time Scale,而为 **Inference Configuration** 设置高图形质量和 +`1.0` 的Time Scale。 + +**注意:**如果您想在训练期间观测环境,则可以调整 +**Inference Configuration** 设置来使用更大的窗口和更接近 +1:1 的时间刻度。当你要正式训练时一定要重新设置这些参数; +否则,训练可能需要很长时间。 + +对于环境,另一个需要关注的方面是 Academy 的实现。 +由于 Academy 基类是抽象的,您必须始终定义一个子类。 +您可以实现以下三个函数,但这些函数都是可选的: + +* Academy.InitializeAcademy() — 启动环境时调用一次。 +* Academy.AcademyStep() — 在 +Agent.AgentAction() 之前(以及 agent 收集其观测结果之后)的每个模拟步骤调用。 +* Academy.AcademyReset() — 在 Academy 开始或重新开始模拟 +(包括第一次)时调用。 + +3D Balance Ball 环境不使用这些函数(每个 agent 在需要时 +会自行重置),但许多环境都会使用这些函数来 +控制 agent 周围的环境。 + +### Brain + +场景中的 Ball3DBrain 游戏对象包含 Brain 组件, +是 Academy 对象的子级。(场景中的所有 Brain 对象都必须是 +Academy 的子级。)3D Balance Ball 环境中的所有 agent 使用 +同一个 Brain 实例。 +Brain 不存储关于 agent 的任何信息, +只是将 agent 收集的观测结果发送到决策过程, +然后将所选的动作返回给 agent。因此,所有 agent 可共享 +同一个 brain,但会独立行动。Brain 设置可以提供很多 +关于 agent 工作方式的信息。 + +**Brain Type** 决定了 agent 如何决策。 +**External** 和 **Internal** 类型需要协同使用:训练 agent 时使用 **External**, +而在采用经过训练的模型时使用 **Internal**。 +**Heuristic** brain 允许您通过扩展 Decision 类来对 agent 的逻辑进行 +手动编码。最后,**Player** brain 可让您将键盘命令 +映射到动作,这样在测试 agent 和环境时 +会非常有用。如果这些类型的 brain 都不能满足您的需求,您可以 +实现自己的 CoreBrain 来创建自有的类型。 + +在本教程中,进行训练时,需要将 **Brain Type** 设置为 **External**; +当您将经过训练的模型嵌入到 Unity 应用程序中时,需要将 +**Brain Type** 更改为 **Internal**。 + +**向量观测空间** + +在决策之前,agent 会收集有关自己在环境中所处的状态的 +观测结果。ML-Agents 将观测分为两类: +**Continuous** 和 **Discrete**。**Continuous** 向量观测空间 +会收集浮点数向量中的观测结果。**Discrete** +向量观测空间是一个状态表的索引。大多数示例环境 +都使用连续的向量观测空间。 + +3D Balance Ball 示例中所用的 Brain 实例使用 **State Size** 为 8 的 +**Continuous** 向量观测空间。这意味着 +包含 agent 观测结果的特征向量包含八个元素: +平台旋转的 `x` 和 `z` 分量以及球相对位置和 +速度的 `x`、`y` 和 `z` 分量。(观测结果值 +在 agent 的 `CollectObservations()` 函数中进行定义。) + +**向量运动空间** + +brain 以*动作*的形式向 agent 提供指令。与状态 +一样,ML-Agents 将动作分为两种类型:**Continuous** +向量运动空间是一个可以连续变化的数字向量。向量 +每个元素的含义都是由 agent 逻辑定义的(PPO 训练过程是一个了解agent的哪种状态更好的过程,这个过程是通过学习不同agent的不同状态会对应多少奖励来实现的)。 +例如,一个元素可能表示施加到 agent 某个 +`RigidBody` 上的力或扭矩。**Discrete** 向量运动空间将其动作 +定义为一个表。提供给 agent 的具体动作是这个表的 +索引。 + +根据设计,3D Balance Ball 示例会使用这两种类型的向量运动 +空间。 +您可以尝试使用两种设置进行训练,观测是否有 +差异。(使用离散运动空间时将 `Vector Action Space Size` 设置为 4, +而使用连续运动空间时将其设置为 2。) + +### Agent + +Agent 是在环境中进行观测并采取动作的参与者。 +在 3D Balance Ball 环境中,Agent 组件被放置在 12 个 +平台游戏对象上。基础 Agent 对象有一些影响其行为的 +属性: + +* **Brain** — 每个 Agent 必须有一个 Brain。brain 决定了 agent 如何 +决策。3D Balance Ball 场景中的所有 agent 共享同一个 +brain。 +* **Visual Observations** — 定义 agent 用来观测其环境的 +任何 Camera 对象。3D Balance Ball 不使用摄像机观测。 +* **Max Step** — 定义在 agent 决定自己完成之前可以发生多少个 +模拟步骤。在 3D Balance Ball 中,agent 在 5000 步之后重新开始。 +* **Reset On Done** — 定义 agent 是否在完成时重新开始。 +3D Balance Ball 将此项设置为 true,因此 agent 在达到 +**Max Step** 计数后或在掉球后重新开始。 + +也许 agent 更有趣的方面在于 Agent 子类的 +实现。在创建 agent 时,您必须扩展 Agent 基类。 +Ball3DAgent 子类定义了以下方法: + +* Agent.AgentReset() — Agent 重置时(包括会话开始时) +调用。Ball3DAgent 类使用重置函数来重置 +平台和球。该函数会将重置值随机化,从而使 +训练不局限于特定的开始位置和平台 +姿态。 +* Agent.CollectObservations() — 在每个模拟步骤调用。负责 +收集 agent 对环境的观测结果。由于分配给 +agent 的 Brain 实例设置为状态大小为 8 的连续向量观测空间, +因此 `CollectObservations()` 必须调用 8 次 +`AddVectorObs`。 +* Agent.AgentAction() — 在每个模拟步骤调用。接收 brain 选择的 +动作。Ball3DAgent 示例可以处理连续和离散 +运动空间类型。在此环境中,两种状态类型之间实际上 +没有太大的差别:这两种向量运动空间在每一步都会 +导致平台旋转发生小变化。`AgentAction()` 函数 +为 agent 分配奖励;在此示例中,agent 在每一步 +将球保持在平台上时收到较小的正奖励, +而在掉球时收到更大的负奖励。agent 在掉球时还会被标记为 +完成状态,因此会重置一个用于下一模拟步骤的 +新球。 + +## 构建环境 + +第一步是打开包含 3D Balance Ball 环境的 +Unity 场景: + +1. 启动 Unity。 +2. 在 Projects 对话框上,选择窗口顶部的 **Open** 选项。 +3. 使用随后打开的文件对话框,找到 ML-Agents 项目内的 +`unity-environment` 文件夹,然后单击 **Open**。 +4. 在 `Project` 窗口中,找到文件夹 +`Assets/ML-Agents/Examples/3DBall/`。 +5. 双击 `Scene` 文件以加载包含 Balance Ball 环境的 +场景。 + +![3DBall 场景](images/mlagents-Open3DBall.png) + +由于我们要建立此环境来进行训练,因此我们需要 +将 agent 使用的 brain 设置为 **External**。这样 agent 在 +进行决策时能够与外部训练过程进行通信。 + +1. 在 **Scene** 窗口中,单击 Ball3DAcademy 对象旁边的三角形 +图标。 +2. 选择其子对象 `Ball3DBrain`。 +3. 在 Inspector 窗口中,将 **Brain Type** 设置为 `External`。 + +![将 Brain 设置为 External](images/mlagents-SetExternalBrain.png) + +接下来,我们希望设置场景以便在训练过程启动我们的环境可执行文件时 +正确播放场景。这意味着: +* 环境应用程序在后台运行 +* 没有对话需要互动 +* 正确的场景会自动加载 + +1. 打开 Player Settings(菜单:**Edit** > **Project Settings** > **Player**)。 +2. 在 **Resolution and Presentation** 下方: + - 确保选中 **Run in Background**。 + - 确保 **Display Resolution Dialog** 设置为 Disabled。 +3. 打开 Build Settings 窗口(菜单:**File** > **Build Settings**)。 +4. 选择目标平台。 + -(可选)选择“Development Build”以便 + [记录调试消息](https://docs.unity3d.com/Manual/LogFiles.html)。 +5. 如果 **Scenes in Build** 列表中显示了任何场景,请确保 +唯一选中的是 3DBall Scene。(如果该列表为空,则表示 +仅当前场景包含在编译中)。 +6. 单击 *Build*: + a. 在 File 对话框中,导航至 ML-Agents 目录中的 `python` + 文件夹。 + b. 指定文件名,然后单击 **Save**。 + +![编译窗口](images/mlagents-BuildWindow.png) + +## 使用 Reinforcement Learning(强化学习)来训练 Brain + +有了一个包含模拟环境的 Unity 可执行文件后,现在我们 +可以执行训练。为了首先确保您的环境和 Python +API 能正常工作,您可以使用 `python/Basics` +[Jupyter 笔记本](/docs/Background-Jupyter.md)。 +此笔记本包含了 API 功能的简单演练。 +在 `Basics` 中,务必将 `env_name` 设置为您先前构建的 +环境文件的名称。 + +### 使用 PPO 进行训练 + +为了训练 agent 对球进行正确平衡,我们将使用一种称为 Proximal Policy Optimization (PPO) 的 +Reinforcement Learning(强化学习)算法。 +与其他许多 RL 算法相比,这种算法经证明是一种安全、 +有效且更通用的方法,因此我们选择它作为与 ML-Agents +一起使用的示例算法。有关 PPO 的更多信息, +请参阅 OpenAI 近期发布的[博客文章](https://blog.openai.com/openai-baselines-ppo/), +其中对 PPO 进行了说明。 + + +为了训练 Balance Ball 环境中的 agent,我们将使用 Python +包。我们提供了一个名为 `learn.py` 的方便的 Python 包装脚本,此脚本会接受用于配置训练和预测阶段的参数。 + + +我们将向这个脚本传递我们刚才构建的环境可执行文件的路径。(可选)我们可以 +使用 `run_id` 来识别实验并创建用于存储模型和摘要统计信息的文件夹。当使用 +TensorBoard 来观测训练统计信息时,将每次训练的此项设置为顺序值 +将会很有用。也就是说,第一次训练时为“BalanceBall1”, +第二次训练时为“BalanceBall2”,依此类推。如果不这样做,每次训练的 +摘要信息都会保存在同一个目录中,并且全部将包含在 +同一个图中。 + +总之,转到命令行,进入 `ml-agents` 目录并输入: + +```python +python3 python/learn.py --run-id= --train +``` + +`--train` 标志告诉 ML-Agents 以训练模式运行。`env_file_path` 应该是刚才创建的 Unity 可执行文件的路径。 + + +### 观测训练进度 + +开始使用 `learn.py` 按照前面部分所述的方式进行训练后,`ml-agents` 文件夹将 +包含一个 `summaries` 目录。为了更详细地观测训练过程, +您可以使用 TensorBoard。从命令行中运行: + +`tensorboard --logdir=summaries` + +然后导航至 `localhost:6006`。 + +从 TensorBoard 中,您将看到摘要统计信息: + +* Lesson - 只有在进行 +[课程训练](/docs/Training-Curriculum-Learning.md)时才有意义。 +3D Balance Ball 环境中不使用此项。 +* Cumulative Reward - 所有 agent 的平均累积场景奖励。 +在成功训练期间应该增大。 +* Entropy - 模型决策的随机程度。在成功训练过程中 +应该缓慢减小。如果减小得太快,应增大 `beta` +超参数。 +* Episode Length - 所有 agent 在环境中每个场景的 +平均长度。 +* Learning Rate - 训练算法搜索最优 policy 时需要多大的 +步骤。随着时间推移应该减小。 +* Policy Loss - policy 功能更新的平均损失。与 policy +(决定动作的过程)的变化程度相关。此项的幅度 +在成功训练期间应该减小。 +* Value Estimate - agent 访问的所有状态的平均价值估算。 +在成功训练期间应该增大。 +* Value Loss - 价值功能更新的平均损失。与模型 +对每个状态的价值进行预测的能力相关。此项 +在成功训练期间应该减小。 + +![TensorBoard 运行示例](images/mlagents-TensorBoard.png) + +## 将经过训练的 Brain 嵌入到 Unity 环境中(测试功能) + +一旦训练过程完成,并且训练过程保存了模型 +(通过 `Saved Model` 消息可看出),您便可以将该模型添加到 Unity 项目中, +然后将其用于 brain 类型为 **Internal** 的 agent。 + +### 设置 TensorFlowSharp 支持 + +由于 TensorFlowSharp 支持仍处于实验阶段,因此默认情况下会 +将其禁用。为了启用这项支持,必须遵循以下步骤。请注意, +只有完成这些步骤后才能使用 `Internal` Brain 模式。 + +1. 确保 TensorFlowSharp 插件位于 `Assets` 文件夹中。 +可在 +[此处](https://s3.amazonaws.com/unity-ml-agents/0.3/TFSharpPlugin.unitypackage)下载一个包含 TF# 的 Plugins 文件夹。 +下载后,双击并将其导入。您可以在 Project 选项卡中 +(位于 `Assets` > `ML-Agents` > `Plugins` > `Computer` 下) +检查 TensorFlow 的相关文件来查看是否安装成功 +2. 转到 `Edit` > `Project Settings` > `Player` +3. 对于每个目标平台 +(**`PC, Mac and Linux Standalone`**、**`iOS`** 或 **`Android`**): + 1.转到 `Other Settings`。 + 2.选择 `Scripting Runtime Version` 为 + `Experimental (.NET 4.6 Equivalent)` + 3.在 `Scripting Defined Symbols` 中,添加标志 `ENABLE_TENSORFLOW`。 + 输入后,按 Enter。 +4. 转到 `File` > `Save Project` +5. 重新启动 Unity Editor。 + +### 将经过训练的模型嵌入到 Unity 中 + +1. 经过训练的模型存储在 `ml-agents` 文件夹中的 `models/` 内。训练 +完成后,该位置会有一个 `.bytes` 文件,其中的 `` 是训练期间使用的可执行文件的 +名称。 +2. 将 `.bytes` 从 `python/models/ppo/` 移入 +`unity-environment/Assets/ML-Agents/Examples/3DBall/TFModels/`。 +3. 打开 Unity Editor,然后选择 `3DBall` 场景(如上所述)。 +4. 从 Scene 层级视图中选择 `Ball3DBrain` 对象。 +5. 将 `Type of Brain` 更改为 `Internal`。 +6. 将 `.bytes` 文件从 Editor 的 Project 窗口拖入 +`3DBallBrain` Inspector 窗口中的 `Graph Model` 占位区域。 +7. 按 Editor 顶部的 Play 按钮。 + +如果您正确执行了这些步骤,您现在应该能够 +看到 Unity 编辑器中有这个用于控制平衡球行为的 +训练模型。从这里开始,您便可以重新构建 Unity 的可执行文件, +并单独运行该可执行文件,在其中内置 agent 新学到的行为。 diff --git a/docs/localized/zh-CN/docs/Installation.md b/docs/localized/zh-CN/docs/Installation.md new file mode 100755 index 0000000000..8bc6541774 --- /dev/null +++ b/docs/localized/zh-CN/docs/Installation.md @@ -0,0 +1,70 @@ +# 安装和设置 + +为了安装和使用 ML-Agents,您需要安装 Unity,克隆这个代码仓库, +并安装 Python 以及其他所依赖的库。下面的每个小节 +都会概述每个步骤,此外还会介绍尚在测试阶段的 Docker 的配置方法。 + +## 安装 **Unity 2017.1** 或更高版本 + +[下载](https://store.unity.com/download) 并安装 Unity。如果您想 +使用我们的 Docker 设置(稍后介绍),请确保在安装 Unity 时选择 +_Linux Build Support_ 组件。 + +

+ Linux Build Support +

+ +## 克隆 ml-agents 代码仓库 + +安装完成后,您需要克隆 ML-Agents GitHub 代码仓库。 + + git clone git@github.com:Unity-Technologies/ml-agents.git + +此代码仓库中的 `unity-environment` 目录包含了要添加到项目中的 +Unity Assets。`python` 目录包含训练代码。 +这两个目录都位于代码仓库的根目录。 + +## 安装 Python(以及依赖项) + +为了使用 ML-Agents,您需要安装 Python 3 以及 +[要求文件](../python/requirements.txt)中列出的依赖项。 +一些主要的依赖项包括: +- [TensorFlow](/docs/Background-TensorFlow.md) +- [Jupyter](/docs/Background-Jupyter.md) + +### Windows 用户 + +如果您是刚接触 Python 和 TensorFlow 的 Windows 用户,请遵循[此指南](/docs/Installation-Windows.md)来设置 Python 环境。 + +### Mac 和 Unix 用户 + +如果您的 Python 环境不包括 `pip`,请参阅这些 +[说明](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers) +以了解其安装方法。 + +要安装依赖项,请进入代码仓库的 `python` 子目录, +然后从命令行中运行: + + pip3 install . + +## 基于 Docker 的安装(测试阶段) + +如果您想使用 Docker for ML-Agents,请按照 +[该指南](/docs/Using-Docker.md)进行操作。 + +## Unity 包 + +您可以通过 Unity 包的形式下载 ML-Agents: + + * 带 TensorflowSharp 插件的 ML-Agents([AWS S3链接](https://s3.amazonaws.com/unity-ml-agents/0.3/ML-AgentsWithPlugin.unitypackage),[百度盘链接](https://pan.baidu.com/s/1qkWOqb0meyTorBG-So_PfA)) + * 不带 TensorflowSharp 插件的 ML-Agents([AWS S3链接](https://s3.amazonaws.com/unity-ml-agents/0.3/ML-AgentsNoPlugin.unitypackage),[百度盘链接](https://pan.baidu.com/s/1K8fZFslW6PWNgmWA6oO4Yg)) + * 仅包含 TensorflowSharp 插件([AWS S3链接](https://s3.amazonaws.com/unity-ml-agents/0.3/TFSharpPlugin.unitypackage),[百度盘链接](https://pan.baidu.com/s/1s0mJN8lvuxTcYbs2kL2FqA)) + +## 帮助 + +如果您在安装 ML-Agents 时遇到任何问题,请 +[提交问题](https://github.com/Unity-Technologies/ml-agents/issues),并在提交时 +提供有关操作系统、Python 版本和相关错误消息(如可能)的 +信息。 diff --git a/docs/localized/zh-CN/docs/Learning-Environment-Create-New.md b/docs/localized/zh-CN/docs/Learning-Environment-Create-New.md new file mode 100755 index 0000000000..892d5f32ea --- /dev/null +++ b/docs/localized/zh-CN/docs/Learning-Environment-Create-New.md @@ -0,0 +1,434 @@ +# 创建新的学习环境 + +本教程将介绍创建 Unity 环境的过程。Unity 环境是用 Unity 引擎构建的应用程序,可用于训练 Reinforcement Learning(强化学习)agent。 + +![简单的 ML-Agents 环境](images/mlagents-NewTutSplash.png) + +在此示例中,我们将训练一个球滚动到一个随机放置的立方体。这个球还要学习避免从平台上掉落。 + +## 概述 + +在 Unity 项目中使用 ML-Agents 涉及以下基本步骤: + +1. 创建一个容纳 agent 的环境。从包含少量对象的简单物理模拟环境到整个游戏或生态系统,环境的形式可以多种多样。 +2. 实现一个 Academy 子类,并将这个子类添加到包含该环境的 Unity 场景中的游戏对象 (GameObject)。此游戏对象将用作场景中任何 Brain 对象的父级。您的 Academy 类可以实现一些可选的方法,从而独立于任何 agent 来对场景进行更新。例如,您可以在环境中添加、移动或删除 agent 和其他实体。 +3. 将一个或多个 Brain 对象作为 Academy 的子级添加到场景中。 +4. 实现 Agent 子类。Agent 子类定义了必要的代码供 agent 用于观测自身环境、执行指定动作以及计算用于强化训练的奖励。您还可以实现可选方法,从而在 agent 完成任务或任务失败时重置 agent。 +5. 将 Agent 子类添加到相应的游戏对象,通常是在场景内表示模拟中的 agent 的对象。必须为每个 Agent 对象分配一个 Brain 对象。 +6. 如果要进行训练,应将 Brain 类型设置为 External 并[执行训练过程](/docs/Training-ML-Agents.md)。 + +**注意:**如果您不熟悉 Unity,而本教程中未充分讲解 Editor 任务的情况下,请参阅 Unity 手册中的[了解界面](https://docs.unity3d.com/Manual/LearningtheInterface.html)。 + +如果尚未安装,请遵循[安装说明](Installation.md)。 + +## 设置 Unity 项目 + +要完成的第一项任务是创建一个新的 Unity 项目并将 ML-Agents Assets导入其中: + +1. 启动 Unity Editor 并创建一个名为“RollerBall”的新项目。 + +2. 在你的文件系统中,找到包含您所克隆的 ML-Agents 代码仓库的文件夹。 + +3. 将 `ML-Agents` 文件夹从 `unity-environments/Assets` 拖到 Unity Editor Project 窗口中。 + +您的 Unity **Project** 窗口应包含以下Assets: + +![Project 窗口](images/mlagents-NewProject.png) + +## 创建环境: + +接下来,我们将创建一个非常简单的场景来充当我们的 ML-Agents 环境。该环境的“physical”组件包括一个 Plane(充当 agent 移动的基础地板)、一个 Cube(充当 agent 寻找的目标)以及一个 Sphere(表示 agent 本身)。 + +**创建地板平板:** + +1. 在 Hierarchy 窗口中右键单击,选择 3D Object > Plane。 +2. 将游戏对象命名为“Floor”。 +3. 选择 Plane 以便在 Inspector 窗口中查看其属性。 +4. 将 Transform 设置为 Position = (0,0,0)、Rotation = (0,0,0)、Scale = (1,1,1)。 +5. 在 Plane 的 Mesh Renderer 上,展开 Materials 属性并将默认材质更改为 *floor*。 + +(要设置新材质,请单击当前材质名称旁边的小圆圈图标。此时将打开 **Object Picker** 对话框,然后便可从项目中当前所有材质的列表中选择不同的材质。) + +![Inspector 窗口中的 Floor(地板)](images/mlagents-NewTutFloor.png) + +**添加目标立方体** + +1. 在 Hierarchy 窗口中右键单击,选择 3D Object > Cube。 +2. 将游戏对象命名为“Target” +3. 选择 Target 以便在 Inspector 窗口中查看其属性。 +4. 将 Transform 设置为 Position = (3,0.5,3)、Rotation = (0,0,0)、Scale = (1,1,1)。 +5. 在 Cube 的 Mesh Renderer 上,展开 Materials 属性并将默认材质更改为 *block*。 + +![Inspector 窗口中的目标立方体](images/mlagents-NewTutBlock.png) + +**添加 Agent 球体** + +1. 在 Hierarchy 窗口中右键单击,选择 3D Object > Sphere。 +2. 将游戏对象命名为“RollerAgent” +3. 选择 Target 以便在 Inspector 窗口中查看其属性。 +4. 将 Transform 设置为 Position = (0,0.5,0)、Rotation = (0,0,0)、Scale = (1,1,1)。 +5. 在 Sphere 的 Mesh Renderer 上,展开 Materials 属性并将默认材质更改为 *checker 1*。 +6. 单击 **Add Component**。 +7. 向 Sphere 添加 Physics/Rigidbody 组件。(添加 Rigidbody) + +![Inspector 窗口中的 Agent 游戏对象](images/mlagents-NewTutSphere.png) + +请注意,我们将在本教程的稍后部分创建一个 Agent 子类以作为组件添加到此游戏对象。 + +**添加空游戏对象来容纳 Academy 和 Brain** + +1. 在 Hierarchy 窗口中右键单击,选择 Create Empty。 +2. 将游戏对象命名为“Academy” +3. 右键单击 Academy 游戏对象,然后选择 Create Empty。 +4. 将 Academy 的此子级命名为“Brain”。 + +![场景层级视图](images/mlagents-NewTutHierarchy.png) + +您可以调整摄像机角度以便在运行时更好地查看场景。接下来的步骤是创建并添加 ML-Agent 组件。 + +## 实现 Academy + +Academy 对象可在场景中协调 ML-Agents 并驱动模拟中的决策部分。每个 ML-Agent 场景需要一个 Academy 实例。由于 Academy 基类是抽象的,即使不需要对特定环境使用任何方法,您也必须创建自己的子类。 + +首先,将一个 New Script 组件添加到先前创建的 Academy 游戏对象: + +1. 选择 Academy 游戏对象以便在 Inspector 窗口中查看该对象。 +2. 单击 **Add Component**。 +3. 在组件列表中单击 **New Script**(位于底部)。 +4. 将该脚本命名为“RollerAcademy”。 +5. 单击 **Create and Add**。 + +接下来,编辑新的 `RollerAcademy` 脚本: + +1. 在 Unity Project 窗口中,双击 `RollerAcademy` 脚本,在代码编辑器中将其打开。(默认情况下,新脚本直接放置于 **Assets** 文件夹中。) +2. 在编辑器中,将基类从 `MonoBehaviour` 更改为 `Academy`。 +3. 删除默认添加的 `Start()` 和 `Update()` 方法。 + +在这样的基本场景中,我们不需要 Academy 初始化、重置或以其他方式控制环境中的任何对象,因此我们采用最简单的 Academy 实现: + +```csharp +public class RollerAcademy : Academy { } +``` + +Academy 属性的默认设置也适合该环境,因此我们无需在 Inspector 窗口中更改 RollerAcademy 组件的任何设置。 + +![Academy 属性](images/mlagents-NewTutAcademy.png) + +## 添加 Brain + +Brain 对象内部封装了决策过程。Agent 将观测结果发送给自己的 Brain,并期望收到决策。Brain Type 设置决定了 Brain 如何决策。与 Academy 和 Agent 类不同,您不需要创建自己的 Brain 子类。 + +要创建 Brain: + +1. 选择先前创建的 Brain 游戏对象以便在 Inspector 窗口中显示该对象的属性。 +2. 单击 **Add Component**。 +3. 选择 **Scripts/Brain** 组件以将其添加到该游戏对象。 + +我们稍后再讲解 Brain 属性,但现在将 Brain Type 保留为 **Player**。 + +![Brain 默认属性](images/mlagents-NewTutBrain.png) + +## 实现 Agent + +要创建 Agent: + +1. 选择 RollerAgent 游戏对象以便在 Inspector 窗口中查看该对象。 +2. 单击 **Add Component**。 +3. 在组件列表中单击 **New Script**(位于底部)。 +4. 将该脚本命名为“RollerAgent”。 +5. 单击 **Create and Add**。 + +然后,编辑新的 `RollerAgent` 脚本: + +1. 在 Unity Project 窗口中,双击 `RollerAgent` 脚本,在代码编辑器中将其打开。 +2. 在编辑器中,将基类从 `MonoBehaviour` 更改为 `Agent`。 +3. 删除 `Update()` 方法。我们将使用 `Start()` 函数,所以暂时将其保留。 + +到目前为止介绍的这些,都是为了将 ML-Agents 添加到任何 Unity 项目而需要执行的基本步骤。接下来,我们将添加逻辑,让我们的 agent 能够使用 reinforcement learning(强化学习)技术学习滚动到立方体。 + +在这种简单的情况下,我们不使用 Academy 对象来控制环境。以前,如果我们想要改变环境,例如在模拟之前或模拟过程中更改地板的大小,或者添加或删除 agent以及其他物体,我们可以在 Academy 中实现相应的方法。但现在,我们会让 Agent 在成功或失败时完成对自己和目标进行重置的所有工作。 + +**初始化和重置 Agent** + +agent 到达目标时会将自己标记为完成状态,而 agent 重置函数会将目标移动到随机位置。另外,如果 agent 从平台上滚下,重置函数会将其放回到地板上。 + +为了移动目标游戏对象,我们需要它的 Transform 对象的引用(这个对象中存储了游戏对象在 3D 世界中的位置、方向和比例)。要取得此引用,请将一个类型为 `Transform` 的公共字段添加到 RollerAgent 类中。Unity 中的组件的公共字段会显示在 Inspector 窗口中,允许您选择在 Unity Editor 中将哪个游戏对象用作目标。要重置 agent 的速度(并在稍后用力移动 agent),我们需要引用 Rigidbody 组件。[Rigidbody](https://docs.unity3d.com/ScriptReference/Rigidbody.html) 是 Unity 用于物理模拟的主要元素。(请参阅[物理](https://docs.unity3d.com/Manual/PhysicsSection.html)以查看 Unity 物理的完整文档。)由于 Rigidbody 组件与我们的 Agent 脚本位于同一个游戏对象上,因此取得此引用的最佳方式是使用 `GameObject.GetComponent()`,我们可以在脚本的 `Start()` 方法中调用它。 + +到目前为止,我们的 RollerAgent 脚本如下所示: + +```csharp +using System.Collections.Generic; +using UnityEngine; + +public class RollerAgent : Agent +{ + Rigidbody rBody; + void Start () { + rBody = GetComponent(); + } + + public Transform Target; + public override void AgentReset() + { + if (this.transform.position.y < -1.0) + { + // agent 掉落 + this.transform.position = Vector3.zero; + this.rBody.angularVelocity = Vector3.zero; + this.rBody.velocity = Vector3.zero; + } + else + { + // 将目标移动到新的位置 + Target.position = new Vector3(Random.value * 8 - 4, + 0.5f, + Random.value * 8 - 4); + } + } +} +``` + +接下来,让我们实现 Agent.CollectObservations() 函数。 + +**观测环境** + +Agent 将我们收集的信息发送给 Brain,由 Brain 使用这些信息来做决策。当您训练 agent(或使用经过训练的模型)时,数据将作为特征向量输入到神经网络中。为了让 agent 成功学习某个任务,我们需要提供正确的信息。为了决定要收集哪些信息,一个好的经验法则是考虑您在计算问题的分析解决方案时需要用到什么。 + +在我们的示例中,我们的 agent 收集的信息包括: + +* 目标的位置。一般来说,为了进行更一般化的训练,较好的做法是使用其他对象的相对位置而不是绝对位置。请注意,agent 仅收集 x 和 z 坐标,因为地板与 x-z 平面平行,并且目标位置的 y 分量不会改变。 + +```csharp +// 计算相对位置 +Vector3 relativePosition = Target.position - this.transform.position; + +// 相对位置 +AddVectorObs(relativePosition.x / 5); +AddVectorObs(relativePosition.z / 5); +``` + +* agent 本身在地板范围内的位置。收集此数据时收集的是 agent 与地板每个边的距离。 + +```csharp +// 与平台边缘的距离 +AddVectorObs((this.transform.position.x + 5) / 5); +AddVectorObs((this.transform.position.x - 5) / 5); +AddVectorObs((this.transform.position.z + 5) / 5); +AddVectorObs((this.transform.position.z - 5) / 5); +``` + +* agent 的速度。这有助于 agent 学习去控制自己的速度,使其不会越过目标和从平台上滚下。 + +```csharp +// Agent 速度 +AddVectorObs(rBody.velocity.x / 5); +AddVectorObs(rBody.velocity.z / 5); +``` + +所有值都除以 5 可将神经网络的输入归一化到范围 [-1,1]。(因为平台的跨度为 10 个单位,所以使用数字 5。) + +总的来说,状态观测结果包含 8 个值,当我们开始设置 Brain 属性时,我们需要使用连续状态空间: + +```csharp +List observation = new List(); +public override void CollectObservations() +{ + // 计算相对位置 + Vector3 relativePosition = Target.position - this.transform.position; + + // 相对位置 + AddVectorObs(relativePosition.x/5); + AddVectorObs(relativePosition.z/5); + + // 与平台边缘的距离 + AddVectorObs((this.transform.position.x + 5)/5); + AddVectorObs((this.transform.position.x - 5)/5); + AddVectorObs((this.transform.position.z + 5)/5); + AddVectorObs((this.transform.position.z - 5)/5); + + // Agent 速度 + AddVectorObs(rBody.velocity.x/5); + AddVectorObs(rBody.velocity.z/5); +} +``` + +Agent 代码的最后一部分是 Agent.AgentAction() 函数,此函数接收 Brain 的决策。 + +**动作** + +Brain 的决策以动作数组的形式传递给 `AgentAction()` 函数。此数组中的元素数量由 agent 的 Brain 的 `Vector Action Space Type` 和 `Vector Action Space Size` 设置确定。RollerAgent 使用连续向量运动空间,并需要 brain 提供的两个连续控制信号。因此,我们要将 Brain `Vector Action Size` 设置为 2。第一个元素 `action[0]` 确定沿 x 轴施加的力;`action[1]` 确定沿 z 轴施加的力。(如果我们允许 agent 以三维方式移动,那么我们需要将 `Vector Action Size` 设置为 3。)注意,Brain 并不知道动作数组中的值是什么意思。训练过程只是根据观测输入来调整动作值,然后看看会得到什么样的奖励。 + +RollerAgent 使用 `Rigidbody.AddForce` 函数将 action[] 数组中的值应用到其 Rigidbody 组件 `rBody`: + +```csharp +Vector3 controlSignal = Vector3.zero; +controlSignal.x = Mathf.Clamp(action[0], -1, 1); +controlSignal.z = Mathf.Clamp(action[1], -1, 1); +rBody.AddForce(controlSignal * speed); +``` + +agent 将动作值限制在 [-1,1] 范围内,原因有两个。首先,学习算法对于尝试非常大的值的动机较小(因为不会对 agent 行为产生任何影响),这样可以避免神经网络计算中出现数值不稳定的问题。其次,我们没有在别的地方采取措施阻止神经网络返回过大的值,所以我们希望在任何情况下都将它们限制在合理的范围内。 + +**奖励** + +Reinforcement learning(强化学习)需要奖励。应在 `AgentAction()` 函数中分配奖励。学习算法使用在模拟和学习过程的每个步骤中分配给 agent 的奖励来确定是否为 agent 提供了最佳动作。您会希望 agent 完成分配的任务(在此情况下是指到达目标立方体)时奖励 agent,而在 agent 彻底失败(掉下平台)时惩罚 agent。有时,您可以通过一些子奖励来鼓励帮助 agent 完成任务的行为,从而加快训练速度。例如,如果 agent 在某个步骤中靠近目标,则 RollerAgent 奖励系统会提供小奖励,并会在每个步骤提供很小的负奖励来促使 agent 快速完成其任务。 + +RollerAgent 会计算到达目标所需的距离。当到达目标时,代码将 Agent.reward 变量增加 1.0,并通过将 agent 设置为 done 来将 agent 标记为完成。 + +```csharp +float distanceToTarget = Vector3.Distance(this.transform.position, + Target.position); +// 已到达目标 +if (distanceToTarget < 1.42f) +{ + Done(); + AddReward(1.0f); +} +``` + +**注意:**当您将 agent 标记为完成状态时,它将停止活动,直到重置为止。您可以通过设置 Inspector 中的 Agent.ResetOnDone 属性, 以便当它被标记为完成状态时,立即重置 agent。你也可以等待 Academy 自己重置环境。本教程中的 RollerBall 环境的重置依赖于 `ResetOnDone` 机制,并且我们目前没有为 Academy 设置 `Max Steps` 限制,在这样的条件下 Academy 绝不会自己重置环境。 + +为了鼓励 agent 继续往前,我们还要在它进一步接近目标时提供奖励(保存先前的步距测量值): + +```csharp +// 进一步接近 +if (distanceToTarget < previousDistance) +{ + AddReward(0.1f); +} +``` + +此外还可以为了鼓励 agent 更快完成任务而在每个步骤中分配负奖励: + +```csharp +// 时间惩罚 +AddReward(-0.05f); +``` + +最后,为了惩罚 agent 掉下平台,会为它分配一个大的负奖励,不仅如此,当它掉下平台后,我们还要将 agent 设置为完成状态,以便它在下一步重置自己: + +```csharp +// 掉下平台 +if (this.transform.position.y < -1.0) +{ + Done(); + AddReward(-1.0f); +} +``` + +**AgentAction()** + +利用上面列出的动作和奖励逻辑,`AgentAction()` 函数的最终版本如下所示: + +```csharp +public float speed = 10; +private float previousDistance = float.MaxValue; + +public override void AgentAction(float[] vectorAction, string textAction) +{ + // 奖励 + float distanceToTarget = Vector3.Distance(this.transform.position, + Target.position); + + // 已到达目标 + if (distanceToTarget < 1.42f) + { + Done(); + AddReward(1.0f); + } + + // 进一步接近 + if (distanceToTarget < previousDistance) + { + AddReward(0.1f); + } + + // 时间惩罚 + AddReward(-0.05f); + + // 掉下平台 + if (this.transform.position.y < -1.0) + { + Done(); + AddReward(-1.0f); + } + previousDistance = distanceToTarget; + + // 动作,大小 = 2 + Vector3 controlSignal = Vector3.zero; + controlSignal.x = Mathf.Clamp(vectorAction[0], -1, 1); + controlSignal.z = Mathf.Clamp(vectorAction[1], -1, 1); + rBody.AddForce(controlSignal * speed); + } +``` + +请注意函数之前定义的 `speed` 和 `previousDistance` 类变量。由于 `speed` 是公共变量,您可以从 Inspector 窗口中设置该值。 + +## 最终 Editor 设置 + +现在,所有游戏对象和 ML-Agent 组件都已准备就绪,因此可以在 Unity Editor 中将一切串起来了。这包括将 Brain 对象分配给 Agent,并设置 Brain 属性,使这些属性与我们的 agent 代码兼容。 + +1. 在 Hierarchy 窗口中展开 Academy 游戏对象,使 Brain 对象可见。 +2. 选中 RollerAgent 游戏对象以便,在 Inspector 窗口中显示该对象的属性。 +3. 将 Brain 对象从 Hierarchy 窗口拖到 RollerAgent 的 Brain 字段。 + +![将 Brain 分配给 RollerAgent](images/mlagents-NewTutAssignBrain.png) + +另外,将 Target 游戏对象从 Hierarchy 窗口拖到 RollerAgent 的 Target 字段。 + +最后,选择 Brain 游戏对象以便能够在 Inspector 窗口中查看该对象的属性。设置以下属性: + +* `Vector Observation Space Type` = **Continuous** +* `Vector Observation Space Size` = 8 +* `Vector Action Space Type` = **Continuous** +* `Vector Action Space Size` = 2 +* `Brain Type` = **Player** + +现在您已准备好在训练之前测试环境。 + +## 测试环境 + +在开始长时间进行训练之前,手动测试您的环境始终是一种明智的做法。我们将 Brain 设置为 **Player** 类型的原因是,我们可以使用直接的键盘控制方式来控制 agent。但首先,您需要将键盘定义为动作映射。尽管 RollerAgent 的 `Action Size` 仅为 2,但对于每个动作,我们将用一个键指定正值,再用一个键指定负值,因此总共为四个键。 + +1. 选择 Brain 游戏对象以便在 Inspector 中查看该对象的属性。 +2. 将 **Brain Type** 设置为 **Player**。 +3. 展开 **Continuous Player Actions**(仅在使用 **Player* brain 时可见)。 +4. 将 **Size** 设置为 4。 +5. 设置以下映射: + +| 元素 | 键 | 索引 | 值 | +| :------------ | :---: | :------: | :------: | +| 元素 0 | D | 0 | 1 | +| 元素 1 | A | 0 | -1 | +| 元素 2 | W | 1 | 1 | +| 元素 3 | S | 1 | -1 | + +**Index** 值对应于传递给 `AgentAction()` 函数的动作数组的索引。**Value** 在 **Key** 被按下时分配给 action[Index]。 + +按 **Play** 运行场景,并用 WASD 键在平台上移动 agent。确保在 Unity Editor Console 窗口中没有显示任何错误,并且 agent 在到达目标或掉下平台时会重置。请注意,对于较复杂的调试,ML-Agents SDK 提供了一个方便的 Monitor 类,您可以使用该类轻松地在 Game 窗口中显示 agent 状态信息。 + +您可以执行一个额外的测试是,首先使用 `python/Basics` +[Jupyter Notebook](/docs/Background-Jupyter.md) +确保您的环境和 Python API 能正常工作。在 `Basics` 中,务必将 +`env_name` 设置为您生成的此环境对应的可执行文件的 +名称。 + +现在可以开始训练 Agent 了。为了准备进行训练,必须首先将 **Brain Type** 从 **Player** 更改为 **External**。此后的过程与[训练 ML-Agents](/docs/Training-ML-Agents.md) 中所述的过程相同。 + +## 回顾:场景布局 + +本节简要回顾了在 Unity 环境中使用 Agent 时 +如何组织场景。 + +您需要在场景中包含三种游戏对象才能使用 Unity ML-Agents: + * Academy + * Brain + * Agent + +切记: + * 场景中只能有一个 Academy 游戏对象。 + * 您可以拥有多个 Brain 游戏对象,但它们必须是 Academy 游戏对象的子级。 + +您的场景层级视图应该如以下示例所示: + +![场景层级视图](images/scene-hierarchy.png) diff --git a/docs/localized/zh-CN/docs/Learning-Environment-Design.md b/docs/localized/zh-CN/docs/Learning-Environment-Design.md new file mode 100755 index 0000000000..7dcdafbb48 --- /dev/null +++ b/docs/localized/zh-CN/docs/Learning-Environment-Design.md @@ -0,0 +1,89 @@ +# Unity 中的 Reinforcement Learning(强化学习) + +Reinforcement learning(强化学习)是一种人工智能技术,通过奖励期望的行为来训练 _agent_ 执行任务。在 reinforcement learning(强化学习)过程中,agent 会探索自己所处的环境,观测事物的状态,并根据这些观测结果采取相应动作。如果该动作带来了更好的状态,agent 会得到正奖励。如果该动作带来的状态不太理想,则 agent 不会得到奖励或会得到负奖励(惩罚)。随着 agent 在训练期间不断学习,它会优化自己的决策能力,以便随着时间的推移获得最高奖励。 + +ML-Agents 使用一种称为 [Proximal Policy Optimization (PPO)](https://blog.openai.com/openai-baselines-ppo/) 的 reinforcement learning(强化学习)技术。PPO 使用神经网络来逼近理想函数;这种理想函数将 agent 的观测结果映射为 agent 在给定状态下可以采取的最佳动作。ML-Agents PPO 算法在 TensorFlow 中实现,并在单独的 Python 过程中运行(通过一个socket与正在运行的 Unity 应用程序进行通信)。 + +**注意:**如果您并非要专门研究机器学习和 reinforcement learning(强化学习)主题,只想训练 agent 完成任务,则可以将 PPO 训练视为一个_黑盒_。在 Unity 内部以及在 Python 训练方面有一些与训练相关的参数可进行调整,但您不需要深入了解算法本身就可以成功创建和训练 agent。[训练 ML-Agents](/docs/Training-ML-Agents.md)提供了执行训练过程的逐步操作程序。 + +## 模拟和训练过程 + +训练和模拟过程以 ML-Agents Academy 类编排的步骤进行。Academy 与场景中的 Agent 和 Brain 对象一起协作逐步完成模拟。当 Academy 已达到其最大步数或场景中的所有 agent 均_完成_时,一个训练场景即完成。 + +在训练期间,处于外部的 Python 进程会在训练过程中与 Academy 不断进行通信以便运行一系列场景,同时会收集数据并优化其神经网络模型。分配给 agent 的 Brain 类型决定了我们是否进行训练。**External** brain 会与外部过程进行通信以训练 TensorFlow 模型。成功完成训练后,您可以将经过训练的模型文件添加到您的 Unity 项目中,以便提供给 **Internal** brain 来控制agent的行为。 + +ML-Agents Academy 类按如下方式编排 agent 模拟循环: + +1. 调用您的 Academy 子类的 `AcademyReset()` 函数。 +2. 对场景中的每个 agent 调用 `AgentReset()` 函数。 +3. 对场景中的每个 agent 调用 `CollectObservations()` 函数。 +4. 使用每个 agent 的 Brain 类来决定 agent 的下一动作。 +5. 调用您的子类的 `AcademyAct()` 函数。 +6. 对场景中的每个 agent 调用 `AgentAction()` 函数,传入由 agent 的 brain 选择的动作。(如果 agent 已完成,则不调用此函数。) +7. 如果 agent 已达到其 `Max Step` 计数或者已将其自身标记为 `done`,则调用 agent 的 `AgentOnDone()` 函数。或者,如果某个 agent 在场景结束之前已完成,您可以将其设置为重新开始。在这种情况下,Academy 会调用 `AgentReset()` 函数。 +8. 当 Academy 达到其自身的 `Max Step` 计数时,它会通过调用您的 Academy 子类的 `AcademyReset()` 函数来再次开始下一场景。 + +要创建训练环境,请扩展 Academy 和 Agent 类以实现上述方法。`Agent.CollectObservations()` 和 `Agent.AgentAction()` 函数必须实现;而其他方法是可选的,即是否需要实现它们取决于您的具体情况。 + +**注意:**在这里用到的 Python API 也可用于其他目的。例如,借助于该 API,您可以将 Unity 用作您自己的机器学习算法的模拟引擎。请参阅 [Python API](/docs/Python-API.md) 以了解更多信息。 + +## 组织 Unity 场景 + +为了在 Unity 场景中训练和使用 ML-Agents,该场景必须包含一个 Academy 子类实例,若干个 Brain 游戏对象和 Agent 子类实例。场景中的任何 Brain 游戏对象都必须附加到 Hierarchy 视图中的 Academy 游戏对象的子级下。Agent 子类实例应该附到代表该 agent 的游戏对象下。 + +[Screenshot of scene hierarchy] + +您必须为每个 agent 分配一个 brain,但可以在多个 agent 之间共享 brain。每个 agent 都将进行自己的观测并独立行动,但会使用相同的决策逻辑,而对于 **Internal** brain,则会使用相同的经过训练的 TensorFlow 模型。 + +### Academy + +Academy 对象会指挥多个 agent 的决策过程。一个场景中有且仅能有一个Academy 对象。 + +您必须创建 Academy 类的子类(因为Academy类是抽象类)。创建 Academy 的子类时,你可以实现以下方法(全部都是可选方法): + +* `InitializeAcademy()` — 第一次启动时准备环境。 +* `AcademyReset()` — 为下一轮的模拟准备环境和 agent。你可以使用这个函数在场景中放入并初始化实体。 +* `AcademyStep()` — 为下一模拟步骤准备环境。Academy 基类首先调用此函数,然后才调用当前步骤的任何 `AgentAction()` 方法。您可以使用此函数在 agent 采取动作之前更新场景中的其他对象。请注意,在 Academy 调用此方法之前,agent 已收集了自己的观测结果并选择了动作。 + +Academy 基类还定义了若干可以在 Unity Editor Inspector 中设置的重要属性。对于训练而言,这些属性中最重要的是 `Max Steps`,它决定了每个训练场景的持续时间。Academy 的步骤计数器达到此值后,它将调用 `AcademyReset()` 函数来开始下一轮模拟。 + + 请参阅 [Academy](/docs/Learning-Environment-Design-Academy.md) 以查看 Academy 属性及其用途的完整列表。 + +### Brain + +Brain 内部封装了决策过程。Brain 对象必须放在 Hierarchy 视图中的 Academy 的子级。我们必须为每个 Agent 分配一个 Brain,但可以在多个 Agent 之间共享同一个 Brain。 + +当我们使用 Brain 类的时候不需要使用其子类,而应该直接使用 Brain 这个类。Brain 的行为取决于 brain 的类型。在训练期间,应将 agent 上连接的 Brain 的 Brain Type 设置为 **External**。要使用经过训练的模型,请将模型文件导入 Unity 项目,并将对应 Brain 的 Brain Type 更改为 **Internal**。请参阅 [Brain](/docs/Learning-Environment-Design-Brains.md) 以了解有关使用不同类型的 Brain 的详细信息。如果四种内置的类型不能满足您的需求,您可以扩展 CoreBrain 类以创建其它的 Brain 类型。 + +Brain 类有若干可以使用 Inspector 窗口进行设置的重要属性。对于使用 brain 的 agent,这些属性必须恰当。例如,`Vector Observation Space Size` 属性必须与 agent 创建的特征向量的长度完全匹配。请参阅 [Agent](/docs/Learning-Environment-Design-Agents.md) 以获取有关创建 agent 和正确设置 Brain 实例的信息。 + +请参阅 [Brain](/docs/Learning-Environment-Design-Brains.md) 以查看 Brain 属性的完整列表。 + +### Agent + +Agent 类代表场景中负责收集观测结果并采取动作的一个参与者 (actor)。我们在配置的时候通常会把Agent 类的脚本附在这个参与者对应的游戏对象上。例如,附加到足球比赛中的球员对象,或车辆模拟中的汽车对象上。此外,必须为每个 Agent 类的脚本分配一个 Brain。 + +要创建 agent,请扩展 Agent 类并实现基本的 `CollectObservations()` 和 `AgentAction()` 方法: + +* `CollectObservations()` — 收集 agent 对其环境的观测结果。 +* `AgentAction()` — 执行由 agent 的 brain 选择的动作,并为当前状态分配奖励。 + +这些函数的实现决定了分配给此 agent 的 Brain 的属性要如何设置。 + +您还必须确定 Agent 如何完成任务,以及当它超时后如何处理。agent 完成其任务(或彻底失败)后,您可以在 `AgentAction()` 函数中手动将 agent 设置为完成。您还可以将 agent 的 `Max Steps` 属性设置为正值,这样 agent 在执行了此数量的步骤后会认为自己已完成。Academy 达到自己的 `Max Steps` 计数后,会开始下一场景。如果将 agent 的 `ResetOnDone` 属性设置为 true,则 agent 可以在一个场景中多次尝试自己的任务。(在 `Agent.AgentReset()` 函数中可以设置 agent 的初始化逻辑,为下一次的任务做好准备。) + +请参阅 [Agent](/docs/Learning-Environment-Design-Agents.md) 以详细了解如何编写一个你自己的 agent。 + +## 环境 + +ML-Agents 中的_环境_可以是 Unity 中构建的任何场景。Unity 场景为 agent 提供了观察、行动和学习的环境。如何设置 Unity 场景实际上取决于您的目标。您可能想要试图解决某个特定的reinforcement learning(强化学习)问题,这种情况下您可以在某一个场景内又进行训练又进行测试。或者,您可能想要训练 agent 在复杂的游戏或模拟条件下的做出某些行为,这种情况下创建更有针对性的训练场景可能会更加高效和实用。 + +训练和测试(或正常游戏)场景都必须包含一个 Academy 对象来控制 agent 的决策过程。Academy 定义了若干可以针对训练场景与测试场景进行不同设置的属性。Academy 的 **Configuration** 属性用于控制渲染和时间刻度。您可以设置 **Training Configuration** 来最大限度缩短 Unity 用于渲染图形的时间,从而加快训练速度。您可能还需要调整其他 Academy 功能设置。例如,`Max Steps` 的大小应尽可能小,从而尽量缩短训练时间,但也不能太小,必须大到足以让 agent 完成任务并在学习过程中有一些额外的“徘徊思考”(wandering) 时间。在测试场景中,您通常根本不希望 Academy 重置场景;如果是这样,应将 `Max Steps` 设置为零。 + +在 Unity 中创建训练环境时,必须设置场景以便可以通过外部训练过程来控制场景。注意以下几点: + +* 在训练程序启动后,Unity 可执行文件会被自动打开,然后训练场景会自动开始训练。 +* 场景中至少须包括一个 **External** brain。 +* Academy 必须在每一轮训练后将场景重置为有效的初始状态。 +* 训练场景必须有明确的结束状态,为此需要使用 `Max Steps`,或让每个 agent 将自身设置为 `done`。 + diff --git a/docs/localized/zh-CN/docs/Learning-Environment-Examples.md b/docs/localized/zh-CN/docs/Learning-Environment-Examples.md new file mode 100644 index 0000000000..ef43ca4860 --- /dev/null +++ b/docs/localized/zh-CN/docs/Learning-Environment-Examples.md @@ -0,0 +1,224 @@ +# 学习环境示例 + +Unity ML-Agents 中内置了一些搭建好的学习环境的示例,并且我们还在不断增加新的示例,这些示例演示了该平台的各种功能。示例环境位于 +`unity-environment/Assets/ML-Agents/Examples` 中,并且我们在下文中进行了简单的介绍。 +此外,我们的 +[首届 ML-Agents 挑战赛](https://connect.unity.com/challenges/ml-agents-1) +中包含了由社区成员创建的一些环境示例。 + +此页仅概述了我们提供的示例环境。如果想要更多地学习如何设计和构建您自己的环境,请参阅 +[创建新的学习环境](Learning-Environment-Create-New.md) +页面。 + +如果您想提交自己的环境,请参阅我们的 +[贡献指南](/CONTRIBUTING.md)页面。 + +## Basic + +![Basic](images/basic.png) + +* 训练环境:一种线性移动任务,在此任务中 agent 必须向左或向右移动到奖励状态。 +* 目标:移动到最高奖励状态。 +* Agent设置:环境包含一个 agent,上面附带了单个 brain。 +* Agent 奖励函数设置: + * 达到次优状态时 +0.1。 + * 达到最优状态时 +1.0。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(离散变量)一个变量,对应于当前状态。 + * 向量运动空间:(离散变量)两个可能的动作(向左移动、向右移动)。 + * 视觉观测:0 +* 重置参数:无 + +## 3DBall: 3D Balance Ball + +![3D Balance Ball](images/balance.png) + +* 训练环境:一种平衡球任务,在此任务中 agent 需要控制平台。 +* 目标:agent 必须平衡平台,以尽可能长时间在平台上保持球不掉落。 +* Agent设置:环境包含 12 个全部链接到单个 brain 的同类 agent。 +* Agent 奖励函数设置: + * 球在平台上保持不掉下的每一步都 +0.1。 + * 球掉下平台时 -1.0。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)8 个,对应于平台的旋转以及球的位置、旋转和速度。 + * 向量观测空间(困难版本,因为观测到的信息减少了):(连续变量)5 个变量,对应于平台的旋转以及球的位置和旋转。 + * 向量运动空间:(连续变量)2 个,其中一个值对应于 X 旋转,而另一个值对应于 Z 旋转。 + * 视觉观测:0 +* 重置参数:无 + +## GridWorld + +![GridWorld](images/gridworld.png) + +* 训练环境:某一个典型版本的的grid-world任务。场景包含 agent、目标和障碍。 +* 目标:agent 必须在网格中避开障碍的同时移动到目标。 +* Agent设置:环境包含一个链接到单个 brain 的 agent。 +* Agent 奖励函数设置: + * 每一步 -0.01。 + * agent 导航到目标网格位置时 +1.0(场景结束)。 + * agent 移动到障碍物时 -1.0(场景结束)。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:无 + * 向量运动空间:(离散变量)4 个,对应于基本方向的移动。 + * 视觉观测:一个对应于 GridWorld 自上而下的视图。 +* 重置参数:三个参数,分别对应于网格大小、障碍物数量和目标数量。 + + +## Tennis + +![Tennis](images/tennis.png) + +* 训练环境:agent 控制球拍将球弹过球网的双人游戏。 +* 目标:agent 必须在彼此之间弹起网球,同时不能丢球或击球出界。 +* Agent设置:环境包含两个链接到单个 brain(名为 TennisBrain)的 agent。在训练之后,您可以将另一个名为 MyBrain 的 brain 附加到其中一个 agent,从而与经过训练的模型进行游戏比赛。 +* Agent 奖励函数设置(agent互相之间独立): + * agent 击球过网时 +0.1。 + * agent 让球落入自己的范围或者击球出界时 -0.1。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)8 个,分别对应于球和球拍的位置和速度。 + * 向量运动空间:(连续变量)2 个,分别对应于朝向球网或远离球网的运动,以及上下的运动。 + * 视觉观测:无 +* 重置参数:一个参数,对应于球的大小。 + +## Push Block + +![Push](images/push.png) + +* 训练环境:一个平台,agent 可以在该平台上推动方块。 +* 目标:agent 必须将方块推向目标。 +* Agent设置:环境包含一个链接到单个 brain 的 agent。 +* Agent 奖励函数设置: + * 每一步 -0.0025。 + * 方块接触到目标时 +1.0。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)15 个,分别对应于 agent、方块和目标的位置和速度。 + * 向量运动空间:(连续变量)2 个,分别对应于 X 和 Z 方向的移动。 + * 视觉观测:无。 +* 重置参数:无。 + +## Wall Jump + +![Wall](images/wall.png) + +* 训练环境:一个平台环境,agent 可以在该环境中跳过墙。 +* 目标:agent 必须利用一个方块越过墙并到达目标。 +* Agent设置:环境包含一个链接到两个不同 brain 的 agent。agent 链接到的 brain 根据墙的高度而变化。 +* Agent 奖励函数设置: + * 每一步 -0.0005。 + * agent 接触到目标时 +1.0。 + * agent 掉下平台时 -1.0。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)16 个,分别对应于 agent、方块和目标的位置和速度以及墙的高度。 + * 向量运动空间:(离散变量)74 个,分别对应于 14 个射线投射,每个射线投射可检测 4 个可能的物体,加上 agent 的全局位置以及 agent 是否落地。 + * 视觉观测:无。 +* 重置参数:4,对应于可能的墙壁的高度。 + +## Reacher + +![Tennis](images/reacher.png) + +* 训练环境:可以移动到目标位置的双关节臂。 +* 目标:agent 必须将手移动到目标位置,并保持在此处。 +* Agent设置:环境包含 32 个链接到单个 brain 的 agent。 +* Agent 奖励函数设置(agent互相之间独立): + * 当 agent 的手处于目标位置时,每过一步 +0.1。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)26 个,对应于两个机械臂 Rigidbody 的位置、旋转、速度和角速度。 + * 向量运动空间:(连续变量)4 个,对应于两个关节的两个方向上的转动。 + * 视觉观测:无 +* 重置参数:两个,对应于目标大小和目标移动速度。 + +## Crawler + +![Crawler](images/crawler.png) + +* 训练环境:一种有 4 个手臂的生物,每个手臂分两节 +* 目标:agent 必须沿 x 轴移动其身体,并且保持不跌倒。 +* Agent设置:环境包含 3 个链接到单个 brain 的 agent。 +* Agent 奖励函数设置(agent互相之间独立): + * +1 乘以 x 方向的速度 + * 跌倒时 -1。 + * -0.01 乘以动作平方 + * -0.05 乘以 y 位置变化 + * -0.05 乘以 z 方向的速度 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)117 个,对应于每个肢体的位置、旋转、速度和角速度以及身体的加速度和角速度。 + * 向量运动空间:(连续变量)12 个,对应于适用于 12 个关节的扭矩。 + * 视觉观测:无 +* 重置参数:无 + +## Banana Collector + +![Banana](images/banana.png) + +* 训练环境:一个包含多个 agent 的环境,这些 agent 争相收集香蕉。 +* 目标:agent 必须学习尽可能接近更多的黄色香蕉,同时避开红色香蕉。 +* Agent设置:环境包含 10 个链接到单个 brain 的 agent。 +* Agent 奖励函数设置(agent互相之间独立): + * 接触黄色香蕉时 +1 + * 接触红色香蕉时 -1。 +* Brain 设置:一个有以下观测/运动空间的 brain。 + * 向量观测空间:(连续变量)51 个,对应于 agent 的速度, agent 前进方向,以及 agent 对周围物体进行基于射线的感知。 + * 向量运动空间:(连续变量)3 个,对应于向前移动,绕 y 轴旋转,以及是否使用激光使其他 agent 瘫痪。 + * 视觉观测(可选):每个 agent 的第一人称视图。 +* 重置参数:无 + +## Hallway + +![Hallway](images/hallway.png) + +* 训练环境:在一个环境中,agent 需要在房间内查找信息、记住信息并使用信息移动到正确目标。 +* 目标:移动到与房间内的方块的颜色相对应的目标。 +* Agent设置:环境包含一个链接到单个 brain 的 agent。 +* Agent 奖励函数设置(agent互相之间独立): + * 移动到正确目标时 +1。 + * 移动到错误目标时 -0.1。 + * 时间流逝惩罚 -0.0003。 +* Brain 设置:一个有以下观测/运动空间的 Brain: + * 向量观测空间:(连续变量)30 个,对应于针对物体、目标和墙壁的射线投射检测信号。 + * 向量运动空间:(离散变量)4 个,对应于 agent 旋转和前进/后退运动。 + * 视觉观测(可选):agent 的第一人称视图。 +* 重置参数:无 + +## Bouncer + +![Bouncer](images/bouncer.png) + +* 训练环境:在一个环境中,agent 需要按需决策。agent 必须决定在接触地面时如何进行下一次弹跳。 +* 目标:抓住漂浮的香蕉。跳跃次数有限。 +* Agent设置:环境包含一个链接到单个 brain 的 agent。 +* Agent 奖励函数设置(agent互相之间独立): + * 抓住香蕉时 +1。 + * 弹跳出界时 -1。 + * -0.05 乘以跳跃力的在各个方向上的平方和。能量消耗惩罚。 +* Brain 设置:一个有以下观测/运动空间的 Brain 的设置: + * 向量观测空间:(连续变量)6 个,对应于 agent 和香蕉的局部位置。 + * 向量运动空间:(连续变量)3 个,对应于 agent 为跳跃所用的力。 + * 视觉观测:无 +* 重置参数:无 + +## Soccer Twos + +![SoccerTwos](images/soccer.png) + +* 训练环境:在一个环境中,四个 agent 在 2 对 2 玩具足球比赛中比赛。 +* 目标: + * 前锋:让球进入对手的球门。 + * 守门员:防止球进入自己的球门。 +* Agent设置:环境包含四个 agent,其中两个链接到一个 brain(前锋),两个链接到另一个 brain(守门员)。 +* Agent 奖励函数设置(agent互相之间非独立): + * 前锋: + * 球进入对手球门时 +1。 + * 球进入自己队的球门时 -0.1。 + * 存在性惩罚 -0.001。 + * 守门员: + * 球进入自己队的球门时 -1。 + * 球进入对手球门时 +0.1。 + * 存在性奖励 +0.001。 +* Brain 设置:两个有以下观测/运动空间的 Brain: + * 向量观测空间:(连续变量)112,对应于局部的 14 个射线投射,每个射线投射可检测 7 个可能的物体类型,以及物体的距离。感知范围是 agent 前面的 180 度视角。 + * 向量运动空间:(离散变量) + * 前锋:6 个,对应于前进、后退、侧身移动以及旋转。 + * 守门员:4 个,对应于前进、后退、侧身移动。 + * 视觉观测:无 +* 重置参数:无 diff --git a/docs/localized/zh-CN/docs/ML-Agents-Overview.md b/docs/localized/zh-CN/docs/ML-Agents-Overview.md new file mode 100644 index 0000000000..b1019fedd7 --- /dev/null +++ b/docs/localized/zh-CN/docs/ML-Agents-Overview.md @@ -0,0 +1,435 @@ +# ML-Agents 概述 + +**Unity Machine Learning Agents** (ML-Agents) 是一款开源的 Unity 插件,使我们得以在游戏和其它模拟环境中训练智能的 agent。您可以使用 reinforcement learning(强化学习)、 +imitation learning(模仿学习)、neuroevolution(神经进化)或其他机器学习方法 +通过简单易用的 Python API 对 Agent 进行训练。我们还提供最先进算法的实现方式(基于 +TensorFlow),让游戏开发者和业余爱好者能够轻松地 +训练用于 2D、3D 和 VR/AR 游戏的智能 agent。 +这些经过训练的 agent 可用于多种目的, +包括控制 NPC 行为(采用各种设置, +例如多个 agent 和对抗)、对游戏内部版本进行自动化测试 +以及评估不同游戏设计决策的预发布版本。ML-Agents 对于游戏开发者和 AI 研究人员双方 +都有利,因为它提供了一个集中的平台, +可以在 Unity 的丰富环境中评估 AI 的进步情况, +然后提供给更广泛的研究和游戏开发者社区。 + +根据您的背景(如研究人员、游戏开发人员、业余爱好者), +您现在可能在脑海中会有非常不同的问题。 +为了让您更轻松地过渡到 ML-Agents, +我们提供了多个后台页面,其中包括有关 +[Unity 引擎](/docs/Background-Unity.md)、 +[机器学习](/docs/Background-Machine-Learning.md)和 +[TensorFlow](/docs/Background-TensorFlow.md) 的概述和有用资源。如果您不熟悉 Unity 场景,不了解基本的机器学习概念,或者以前没有听说过 TensorFlow,**强烈**建议您浏览相关的背景知识页面。 + +此页面的其余部分深入介绍了 ML-Agents、包括其重要组件、 +支持的不同的训练模式以及这些训练模式对应的应用场景。读完后 +您应该对 ML-Agents 的_功能_有一个很好的了解。随后的文档页面 +提供了 ML-Agents _用法_的示例。 + +## 运行示例:训练 NPC 行为 + +为了帮助解释此页面中的材料和术语,我们将通篇使用一个 +虚构的运行示例。我们将探讨 +在游戏中训练非玩家角色 (NPC) 行为的问题。 +(NPC 是一个永远不受人类玩家控制的游戏角色, +其行为由游戏开发者预先定义。)更具体地说, +我们假设我们正在开发一个由玩家控制士兵的多玩家战争主题 +游戏。在此游戏中,我们有一名担任军医的 NPC,他会负责寻找 +和恢复受伤的玩家。最后,我们假设有两支军队, +每支军队有五名队员和一名 NPC 军医。 + +军医的行为相当复杂。此角色首先需要避免受伤, +因此需要检测何时处于危险之中并转移至安全 +位置。其次,此角色需要了解其队员中哪些人受伤 +而需要帮助。如果多人受伤,则需要评估受伤程度 +并决定首先帮助哪个伤者。最后, +一名优秀的军医总能把自己置于一个可以快速帮助队员的 +位置。符合所有这些特征意味着军医需要在任何情况下 +测量环境的若干属性(例如,队员位置、 +敌人位置、哪一名队员受伤以及受伤程度), +然后决定采取的行动(例如,躲避敌人的火力、 +前往帮助其队员之一)。鉴于环境中存在有大量的可变参数 +以及军医可以采取的大量可能的行动, +手工定义和实现此类复杂的行为极具挑战性, +并且很容易出错。 + +凭借 ML-Agents,您可以使用各种方法来_训练_这类 NPC +(称为 **agent**)的行为。基本理念很简单。 +我们需要在游戏(称为**环境**)的每个时刻定义 +三个实体: +- **观测** - 军医对环境的感知。 +观测可以是数字和/或视觉形式。数字观测会从 agent 的角度 +测量环境的属性。对于 +我们的军医来说,这将是军医可以看到的战场属性。 +根据游戏和 agent 的不同,数字观测的数据可以是_离散_的 +或_连续_的形式。对于大多数有趣的环境,agent 将需要若干连续的 +数字观测,而对于具有少量独特配置的简单环境, +离散观测就足够了。 +另一方面,视觉观测是附加到 agent 的摄像头 +所生成的图像,代表着 agent 在该时间点看到的 +内容。我们通常会将 agent 的观测与环境(或游戏)的 +**状态**混淆。环境状态表示包含所有游戏角色的 +整个场景的相关信息。但是,agent 观测 +仅包含 agent 了解的信息,通常是 +环境状态的一个子集。例如,军医观测不能包括 +军医不知道的隐身敌人的信息。 +- **动作** - 军医可采取的动作。与观测 +类似,根据环境和 agent 的复杂性, +动作可以是连续的或离散的。就军医而言, +如果环境是一个只是基于位置的简单网格世界, +那么采用四个值(东、西、南、北)之一的离散动作 +就足够了。但是,如果环境更加复杂并且军医可以 +自由移动,那么使用两个连续动作(一个对应于方向, +另一个对应于速度)更合适。 +- **奖励信号** - 一个表示军医行为的标量值。 +请注意,不需要在每个时刻都提供奖励信号, +只有在军医执行好的或坏的动作时 +才提供。例如,军医在死亡时会得到很大的负奖励, +每当恢复受伤的队员时会得到适度的正奖励, +而在受伤队员因缺乏救助而死亡时 +会得到适度的负奖励。请注意,奖励信号表示如何将任务的目标 +传达给 agent,所以采用的设置方式需要确保当获得的奖励达到最大值时,agent能够产生我们最期望的行为。 + +在定义这三个实体(**reinforcement learning(强化学习)任务** +的模块)之后,我们现在可以 +_训练_军医的行为了。为此需要通过许多试验来 +模拟环境,随着时间的推移,通过最大化未来奖励, +使军医能够针对每次的观测学会采取 +最佳的动作。关键在于,军医学习能够使奖励得到最大值的动作的过程, +便是在学习使自己成为一名优秀军医(即拯救最多生命的 +军医)的过程。在 **reinforcement learning(强化学习)** +技术中,所学习的行为称为 **policy**, +我们想学习的 policy 本质上是一个从每个可能的观测到该观测下最优动作的映射。请注意, +通过运行模拟来学习 policy 的过程被称为 +**训练阶段**,而让 NPC 使用其学习到的 policy +玩游戏的过程被称为**预测阶段**。 + +ML-Agents 提供了所有必要工具,从而使我们得以利用 Unity 作为 +模拟引擎来学习 Unity 环境中不同对象的 policy。 +在接下来的几节中,我们将讨论 ML-Agents 如何实现这一目的以及 +它所提供的功能有什么。 + +## 主要组件 + +ML-Agents 是一个 Unity 插件,它包含三个高级组件: +* **学习环境** - 其中包含 Unity 场景和所有游戏 +角色。 +* **Python API** - 其中包含用于训练(学习某个行为或 policy)的 +所有机器学习算法。请注意, +与学习环境不同,Python API 不是 Unity 的一部分,而是位于外部 +并通过 External Communicator 与 Unity 进行通信。 +* **External Communicator** - 它将 Unity 环境与 Python API +连接起来。它位于 Unity 环境中。 + +

+ Simplified ML-Agents Scene Block Diagram +

+ +_ML-Agents 的简化框图。_ + +学习环境包含三个可帮助组织 Unity 场景的 +附加组件: +* **Agent** - 它可以被附加到一个 Unity 游戏对象上(场景中的 +任何角色),负责生成它的观测结果、执行它接收的动作 +并适时分配奖励(正/负)。 +每个 Agent 只与一个 Brain 相关联。 +* **Brain** - 它封装了 Agent 的决策逻辑。 +实质上,Brain 中保存着每个 Agent 的 policy, +决定了 Agent 在每种情况下应采取的动作。更具体地说, +它是从 Agent 接收观测结果和奖励并返回动作的 +组件。 +* **Academy** - 它指挥 agent 的观测和决策过程。 +在 Academy 内,可以指定若干环境参数, +例如渲染质量和环境运行速度参数。 +External Communicator 位于 Academy 内。 + +每个学习环境都会有一个全局的 Academy ,与每一个游戏角色一一对应的多个 Agent。虽然每个 Agent 必须与一个 Brain 相连, +但具有相似观测和动作的多个 Agent 可关联到 +同一个 Brain。在我们的示例游戏中,我们有两个各自拥有 +自己军医的军队。因此,在我们的学习环境中将有两个 Agent, +每名军医对应一个 Agent,但这两个军医都可以关联到同一个 Brain。 +请注意,这两个军医与同一个 Brain 相连的原因是,他们的观测和动作_空间_ +是相似的。这并不意味着在每种情况下 +他们都会有相同的观测和动作_值_。换句话说, +Brain 定义了所有可能的观测和动作的空间, +而与之相连的 Agent(在本示例中是指军医)可以各自拥有 +自己独特的观测和动作值。如果我们将游戏 +扩展到包含坦克驾驶员 NPC,那么附加到这些角色的 +Agent 不能与连接到军医的 Agent 共享一个 Brain(军医和驾驶员 +有不同的动作)。 + +

+ Example ML-Agents Scene Block Diagram +

+ +_示例游戏的 ML-Agents 的示例框图。_ + +我们尚未讨论 ML-Agents 如何训练行为以及 Python API 和 +External Communicator 的作用。在我们深入了解这些细节之前, +让我们总结一下先前的组件。每个游戏角色上附有一个 Agent, +而每个 Agent 都连接到一个 Brain。Brain 从 Agent 处接收观测结果和奖励并返回动作。Academy 除了能够控制环境参数之外,还可确保所有 Agent 和 Brain 都处于同步状态。那么,Brain 如何控制 Agent 的动作呢? + +实际上,我们有四种不同类型的 Brain,它们可以实现广泛的训练和预测情形: +* **External** - 使用 Python API 进行决策。这种情况下, +Brain 收集的观测结果和奖励通过 External Communicator +转发给 Python API。Python API 随后返回 Agent 需要采取的相应动作。 +* **Internal** - 使用嵌入式 +[TensorFlow](/docs/Background-TensorFlow.md) 模型进行决策。 +嵌入式 TensorFlow 模型包含了学到的 policy,Brain 直接使用 +此模型来确定每个 Agent 的动作。 +* **Player** - 使用键盘或控制器的实际输入进行 +决策。这种情况下,人类玩家负责控制 Agent,由 Brain 收集的 +观测结果和奖励不用于控制 Agent。 +* **Heuristic** - 使用写死的逻辑行为进行决策,目前市面上大多数游戏角色行为都是这么定义的。这种类型有助于调试 +具有写死逻辑行为的 Agent。也有助于把这种由写死逻辑指挥的 Agent 与 +训练好的 Agent 进行比较。在我们的示例中,一旦我们 +为军医训练了 Brain,我们便可以为一个军队的军医分配 +经过训练的 Brain,而为另一个军队的军医分配具有写死逻辑行为的 +Heuristic Brain。然后,我们可以评估哪个军医的效率更高。 + +根据目前所述,External Communicator 和 Python API 似乎 +只能由 External Brain 所用。实际并非如此。 +我们可以配置 Internal、Player 和 Heuristic 类型的 Brain, +使它们也能通过 External Communicator(一种称为 _broadcasting_ 的功能) +将观测结果、奖励和动作发送给 Python API。我们很快就会 +看到,这样可以实现其他的训练模式。 + +

+ ML-Agents Scene Block Diagram +

+ +_一个包含多个 Agent 和 Brain 的场景的 +可能配置示例。_ + +## 训练模式 + +鉴于 ML-Agents 的灵活性,我们可以通过多种方式进行训练 +和预测。 + +### 内置的训练和预测 + +如前所述,ML-Agents 附带了多种用于训练智能 agent 的 +最先进算法的实现。在此模式下, +Brain 类型在训练期间设置为 External,在预测期间设置为 Internal。 +更具体地说,在训练期间,场景中的所有军医 +通过 External Communicator 将他们的观测结果发送到 Python API +(这是采用 External Brain 时的行为)。Python API 会处理这些观测结果并发回 +每个军医要采取的动作。在训练期间,这些动作大多是 +探索性的,旨在帮助 Python API 学习每位军医的 +最佳 policy。训练结束后,便可导出每个军医 +所学的 policy。由于我们所有的实现都基于 TensorFlow, +因此所学的 policy 只是一个 TensorFlow 模型文件。然后在预测阶段, +我们将 Brain 类型切换为 Internal,并加入从训练阶段 +生成的 TensorFlow 模型。现在,在预测阶段,军医 +仍然继续生成他们的观测结果,但不再将结果发送到 +Python API,而是送入他们的嵌入了的 Tensorflow 模型, +以便生成每个军医在每个时间点上要采取的_最佳_动作。 + +总结一下:我们的实现是基于 TensorFlow 的,因此, +在训练期间,Python API 使用收到的观测结果来学习 +TensorFlow 模型。然后在预测过程中该模型将嵌入到 +Internal Brain 中,以便为连接到该 Brain 的所有 Agent 生成 +最佳动作。**请注意,我们的 Internal Brain 目前是实验性的, +因为它仅限于 TensorFlow 模型并会利用第三方 +[TensorFlowSharp](https://github.com/migueldeicaza/TensorFlowSharp) + 库。** + +[3D Balance Ball 示例入门](Getting-Started-with-Balance-Ball.md) +教程使用 **3D Balance Ball** 示例环境介绍了此训练模式。 + +### 自定义训练和预测 + +先前的模式中使用 External Brain 类型进行训练, +从而生成 Internal Brain 类型可以理解和使用的 TensorFlow +模型。然而,ML-Agents 的任何用户都可以利用自己的算法 +进行训练和预测。在这种情况下,训练阶段和预测阶段 +的 Brain 类型都会设置为 External,并且场景中所有 Agent 的行为 +都将在 Python 中接受控制。 + +我们目前没有教程介绍这种模式,但您可以在[这里](/docs/Python-API.md) +了解有关 Python API 的更多信息。 + +### Curriculum Learning(课程学习) + +此模式是_内置训练和预测_的扩展, +在训练复杂环境中的复杂行为时特别 +有用。Curriculum learning(课程学习)是一种训练机器学习模型 +的方式,这种训练方式会逐渐引入问题较难理解的方面, +使该模型总是受到最佳挑战。这种思路已经存在了 +很长一段时间,这也是我们人类通常学习的方式。比如 +任何童年时期的初等教育,课程和主题都会 +进行排序。例如,先教算术,再教代数。 +同样,先教代数,再教微积分。前期课程中学到的技能和知识为 +后期的课程提供了基础。机器学习 +也是同样的道理,对较简单任务的训练可以为将来 +较难的任务提供基础。 + +

+ Example Math Curriculum +

+ +_数学课程的示例。从简单主题到复杂主题的课程进度安排, +后一个课程基于前一个课程。_ + +当我们考虑 reinforcement learning(强化学习)的实际原理时, +学习信号是在整个训练过程中偶尔收到的奖励。 +训练 agent 完成此任务时的起点将是一个 +随机 policy。该起始 policy 将使 agent 随意转圈, +这样的行为在复杂环境中可能永远不会获得奖励或极少 +获得奖励。因此,通过在训练开始时简化环境, +我们可让 agent 将随机 policy 快速更新为更有意义的 policy, +即,随着环境逐渐复杂化,policy 也会不断 +改进。在我们的示例中,我们可以考虑当每个队只包含一个 +玩家时,首先训练军医,然后再反复增加玩家人数 +(即环境复杂度)。ML-Agents 支持在 +Academy 内设置自定义环境参数。因此, +可以根据训练进度动态调整与难度或复杂性相关的 +环境要素(比如游戏对象)。 + +[使用 Curriculum Learning(课程学习)进行训练](/docs/Training-Curriculum-Learning.md) +教程使用 **Wall Area** 示例环境介绍了此训练模式。 + +### Imitation Learning(模仿学习) + +简单地展示我们希望 agent 执行的行为, +而不是试图通过试错法来让它学习,这种方式 +通常会更直观。例如,这种模式不是通过 +设置奖励功能来训练军医,而是通过游戏控制器提供军医 +应该如何表现的示例。更具体地说, +在这种模式下,训练期间的 Brain 类型设置为 Player, +并且所有使用控制器执行的动作(不仅包括 agent 观测) +都将被记录并发送到 Python API。imitation learning(模仿学习) +算法随后将会使用这些来自人类玩家的观测结果以及他们对应的动作来 +学习 policy。 + +[使用 Imitation Learning(模仿学习)进行训练](/docs/Training-Imitation-Learning.md)教程 +使用 **Banana Collector** 示例环境介绍了此训练模式。 + +## 灵活的训练方案 + +虽然迄今为止的讨论都主要集中在使用 ML-Agents 对单个 agent 进行训练 +方面,但同时实现多种训练方案也是可能的。 +我们很高兴看到社区创建了许多新奇而有趣的 +环境。刚开始训练智能 agent 的新用户可以参考以下一些示例 +来获得灵感: +* 单 Agent。与单个 Brain 相连的单个 Agent,拥有自己的奖励 +信号。这是传统的 agent 训练方式。一个示例是 +任何单人游戏,比如 Chicken。 +[视频链接](https://www.youtube.com/watch?v=fiQsmdwEGT8&feature=youtu.be)。 +* 同步单 Agent。与单个 Brain 相连的多个独立 Agent, +具有独立奖励信号。传统训练方案的 +并行版本,这可以加速和稳定训练 +过程。当您在一个环境中拥有同一角色的多个版本 +而这些角色版本应该学习类似行为时,这很有用。一个可能的示例是训练 +十二个机械臂同时打开一扇门。 +[视频链接](https://www.youtube.com/watch?v=fq0JBaiCYNA)。 +* 对抗性自我模拟。与单个 Brain 相连的两个相互作用的 Agent, +具有反向奖励信号。在双人游戏中,对抗性自我模拟 +可以让 agent 变得越来越熟练,同时始终拥有完美匹配的 +对手:自身。这是训练 AlphaGo 时采用的策略, +最近被 OpenAI 用于训练一种人类对战的 1 比 1 Dota 2 agent。 +* 协作性多 Agent。与单个或多个不同 Brain 相连的多个相互作用的 Agent,具有共享的奖励信号。在此方案中,所有 agent 必须共同完成一项不能单独完成的任务。示例包括这样的环境:每个 agent 只能访问部分信息,并且需要共享这些信息才能完成任务或协作解决难题。 +* 竞争性多 Agent。与单个或多个不同 Brain 相连的多个 +相互作用的 Agent,具有反向奖励信号。在此 +方案中,agent 必须相互竞争才能赢得比赛, +或获得一些有限的资源。所有的团队运动都属于 +这种情况。 +* 生态系统。与单个或多个不同 Brain 相连的多个 +相互作用的 Agent,具有独立奖励信号。这种方案可以 +看成是创造一个小世界,在这个小世界中,拥有不同目标的动物 +都可以相互影响,比如可能有斑马、大象和长颈鹿的稀树草原, +或者城市环境中的自动驾驶模拟。 + +## 其他功能 + +除了提供灵活的训练方案外,ML-Agents 还 +包含其他功能,可用于提高训练过程的灵活性和 +解释能力。 + +* **按需决策** - 使用 ML-Agents 可以让 agent 仅在需要时 +才请求决策,而不是在环境的每一步都 +请求决策。这种方案可用于训练基于回合的游戏、 +agent 必须对事件作出反应的游戏, +或 agent 可以采取持续时间不同的动作 +的游戏。在每一步决策与按需决策之间切换 +只需点击一下按钮即可实现。您可以在 +[此处](/docs/Learning-Environment-Design-Agents.md#on-demand-decision-making)了解更多关于按需决策功能的 +信息。 + +* **记忆增强 Agent** - 在某些情况下, +agent 必须学会记住过去才能做出 +最好的决策。当 agent 只能部分观测环境时, +跟踪过去的观测结果可以帮助 agent 学习。我们在 +教练中提供了一种_长短期记忆_ +([LSTM](https://en.wikipedia.org/wiki/Long_short-term_memory)) + 的实现,使 agent 能够存储要在未来步骤中 +使用的记忆。您可以在 +[此处](/docs/Feature-Memory.md)了解有关在训练中启用 LSTM 的更多信息。 + +* **监控 Agent 的决策过程** - 由于 ML-Agents 中的通信 +是双向通道通信,因此我们在 Unity 中提供了一个 agent Monitor 类, +这个类可以显示经过训练的 agent 的各个方面, +例如 agent 对自己在 Unity 环境中的表现(称为**价值估算**) +的感知。通过利用作为可视化工具的 Unity 并实时提供 +这些输出,研究人员和开发人员可以更轻松地 +调试 agent 的行为。您可以在 +[此处](/docs/Feature-Monitor.md)了解更多关于使用 Monitor 类的信息。 + +* **复杂的视觉观测** - 在其他平台中,agent 的观测可能 +仅限于单个向量或图像,与之不同的是,ML-Agents 允许 +每个 agent 使用多个摄像机进行观测。因此,agent 可以 +学习整合来自多个视觉流的信息。这在多种情况下 +都会很有用,例如训练需要多个摄像头且摄像头具有 +不同视角的自动驾驶车辆,或可能需要整合空中视觉和 +第一人称视觉的导航 agent。您可以在 +[此处](/docs/Learning-Environment-Design-Agents.md#multiple-visual-observations)了解更多关于向 agent 添加视觉观测的 +信息。 + +* **Broadcasting** - 如前所述,默认情况下,External Brain 会将 +其所有 Agent 的观测结果发送到 Python API。这对 +训练或预测很有帮助。Broadcasting 是一种可以为 +其他三种模式(Player、Internal、Heuristic)启用的功能, +这种情况下的 Agent 观测和动作也会发送到 Python API +(尽管 Agent **不**受 Python API 控制)。Imitation Learning(模仿学习) +会利用这一功能,此情况下会使用 Player Brain 的观测和动作 +来通过示范的方式学习 agent 的 policy。 +不过,这对 Heuristic 和 Internal Brain 也有帮助, +特别是在调试 agent 行为时。您可以在 +[此处](/docs/Learning-Environment-Design-Brains.md#using-the-broadcast-feature)了解更多关于使用 broadcasting 功能的 +信息。 + +* **Docker 设置(测试功能)** - 为了便于在不直接安装 +Python 或 TensorFlow 的情况下设置 ML-Agents, +我们提供了关于如何创建和运行 Docker 容器的 +[指南](/docs/Using-Docker.md)。由于渲染视觉观测的限制, +该功能被标记为测试功能。 + +* **AWS 上的云训练** - 为了便于在 Amazon Web Services (AWS) +机器上使用 ML-Agents,我们提供了一份 +[指南](/docs/Training-on-Amazon-Web-Service.md) +让您了解如何设置 EC2 实例以及公共的预配置 Amazon +Machine Image (AMI)。 + +## 总结和后续步骤 + +简要总结一下:ML-Agents 使 Unity 中构建的游戏和模拟环境 +可以成为训练智能 agent 的平台。它旨在 +使研究人员和开发人员可以在 Unity 中采用多种训练模式和方案,应用 +机器学习技术,推动机器学习技术的发展。 + +为了帮助您使用 ML-Agents,我们制作了几个 +关于[安装 ML-Agents](Installation.md)、 +3D Balance Ball 环境 +[入门](Getting-Started-with-Balance-Ball.md)(这是我们众多 +[示例环境](Learning-Environment-Examples.md)之一)以及 +[创建您自己的环境](Learning-Environment-Create-New.md)的深入教程。 + diff --git a/docs/localized/zh-CN/docs/Readme.md b/docs/localized/zh-CN/docs/Readme.md new file mode 100644 index 0000000000..e385db056a --- /dev/null +++ b/docs/localized/zh-CN/docs/Readme.md @@ -0,0 +1,42 @@ +# Unity ML-Agents 文档 + +## 入门 + * [ML-Agents 概述*](ML-Agents-Overview.md) + * [背景:Unity](/docs/Background-Unity.md) + * [背景:机器学习](/docs/Background-Machine-Learning.md) + * [背景:TensorFlow](/docs/Background-TensorFlow.md) + * [安装和设置*](Installation.md) + * [背景:Jupyter Notebooks](/docs/Background-Jupyter.md) + * [Docker 设置(测试功能)](/docs/Using-Docker.md) + * [教你快速入门--3D Balance Ball 训练环境示例*](Getting-Started-with-Balance-Ball.md) + * [官方训练环境示例*](Learning-Environment-Examples.md) + +## 创建训练环境 + * [从头创建一个训练环境*](Learning-Environment-Create-New.md) + * [设计训练环境*](Learning-Environment-Design.md) + * [Agent](/docs/Learning-Environment-Design-Agents.md) + * [Academy](/docs/Learning-Environment-Design-Academy.md) + * [Brain](/docs/Learning-Environment-Design-Brains.md):[Player](/docs/Learning-Environment-Design-Player-Brains.md)、[Heuristic](/docs/Learning-Environment-Design-Heuristic-Brains.md)、[Internal 和 External](/docs/Learning-Environment-Design-External-Internal-Brains.md) + * [训练环境设计要点](/docs/Learning-Environment-Best-Practices.md) + * [如何使用 Monitor 功能](/docs/Feature-Monitor.md) + * [如何使用 TensorFlowSharp 插件(测试功能)](/docs/Using-TensorFlow-Sharp-in-Unity.md) + +## 进行训练 + * [如何用 ML-Agents 进行训练](/docs/Training-ML-Agents.md) + * [Proximal Policy Optimization 训练要点](/docs/Training-PPO.md) + * [Curriculum Learning(课程学习)训练要点](/docs/Training-Curriculum-Learning.md) + * [Imitation Learning(模仿学习)训练要点](/docs/Training-Imitation-Learning.md) + * [LSTM 训练要点](/docs/Feature-Memory.md) + * [如何使用 Amazon Web Services 进行云端训练](/docs/Training-on-Amazon-Web-Service.md) + * [如何使用 TensorBoard 观察训练过程](/docs/Using-Tensorboard.md) + +## 帮助 + * [如何从老版本升级到 ML-Agents v0.3](/docs/Migrating-v0.3.md) + * [ML-Agents 术语表](/docs/Glossary.md) + * [ML-Agents 尚未实现功能以及常见问题](/docs/Limitations-and-Common-Issues.md) + +## API 文档 + * [API 参考](/docs/API-Reference.md) + * [如何使用 Python API](/docs/Python-API.md) + +**注:** 有翻译版的文档会在右上角标注*号。 \ No newline at end of file diff --git a/docs/localized/zh-CN/docs/images/academy.png b/docs/localized/zh-CN/docs/images/academy.png new file mode 100644 index 0000000000..19e42d5d60 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/academy.png differ diff --git a/docs/localized/zh-CN/docs/images/agent.png b/docs/localized/zh-CN/docs/images/agent.png new file mode 100644 index 0000000000..4504666f30 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/agent.png differ diff --git a/docs/localized/zh-CN/docs/images/anaconda_default.PNG b/docs/localized/zh-CN/docs/images/anaconda_default.PNG new file mode 100644 index 0000000000..9d65d81b69 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/anaconda_default.PNG differ diff --git a/docs/localized/zh-CN/docs/images/anaconda_install.PNG b/docs/localized/zh-CN/docs/images/anaconda_install.PNG new file mode 100644 index 0000000000..237c59cae7 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/anaconda_install.PNG differ diff --git a/docs/localized/zh-CN/docs/images/balance.png b/docs/localized/zh-CN/docs/images/balance.png new file mode 100644 index 0000000000..ee9049f6af Binary files /dev/null and b/docs/localized/zh-CN/docs/images/balance.png differ diff --git a/docs/localized/zh-CN/docs/images/banana.png b/docs/localized/zh-CN/docs/images/banana.png new file mode 100644 index 0000000000..c485f22126 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/banana.png differ diff --git a/docs/localized/zh-CN/docs/images/banner.png b/docs/localized/zh-CN/docs/images/banner.png new file mode 100755 index 0000000000..9068615db9 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/banner.png differ diff --git a/docs/localized/zh-CN/docs/images/basic.png b/docs/localized/zh-CN/docs/images/basic.png new file mode 100644 index 0000000000..0824ac6091 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/basic.png differ diff --git a/docs/localized/zh-CN/docs/images/bc_teacher_helper.png b/docs/localized/zh-CN/docs/images/bc_teacher_helper.png new file mode 100644 index 0000000000..0f188f36ef Binary files /dev/null and b/docs/localized/zh-CN/docs/images/bc_teacher_helper.png differ diff --git a/docs/localized/zh-CN/docs/images/bouncer.png b/docs/localized/zh-CN/docs/images/bouncer.png new file mode 100644 index 0000000000..b36764bfa3 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/bouncer.png differ diff --git a/docs/localized/zh-CN/docs/images/brain.png b/docs/localized/zh-CN/docs/images/brain.png new file mode 100644 index 0000000000..7cc9749361 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/brain.png differ diff --git a/docs/localized/zh-CN/docs/images/broadcast.png b/docs/localized/zh-CN/docs/images/broadcast.png new file mode 100644 index 0000000000..0bf73e8e78 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/broadcast.png differ diff --git a/docs/localized/zh-CN/docs/images/conda_new.PNG b/docs/localized/zh-CN/docs/images/conda_new.PNG new file mode 100644 index 0000000000..96d6cc8bf4 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/conda_new.PNG differ diff --git a/docs/localized/zh-CN/docs/images/crawler.png b/docs/localized/zh-CN/docs/images/crawler.png new file mode 100644 index 0000000000..6123e86670 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/crawler.png differ diff --git a/docs/localized/zh-CN/docs/images/cuDNN_membership_required.png b/docs/localized/zh-CN/docs/images/cuDNN_membership_required.png new file mode 100644 index 0000000000..40a9ee0abc Binary files /dev/null and b/docs/localized/zh-CN/docs/images/cuDNN_membership_required.png differ diff --git a/docs/localized/zh-CN/docs/images/cuda_toolkit_directory.PNG b/docs/localized/zh-CN/docs/images/cuda_toolkit_directory.PNG new file mode 100644 index 0000000000..d097d17905 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/cuda_toolkit_directory.PNG differ diff --git a/docs/localized/zh-CN/docs/images/cudnn_zip_files.PNG b/docs/localized/zh-CN/docs/images/cudnn_zip_files.PNG new file mode 100644 index 0000000000..532d888c76 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/cudnn_zip_files.PNG differ diff --git a/docs/localized/zh-CN/docs/images/curriculum.png b/docs/localized/zh-CN/docs/images/curriculum.png new file mode 100644 index 0000000000..e62c256b81 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/curriculum.png differ diff --git a/docs/localized/zh-CN/docs/images/curriculum_progress.png b/docs/localized/zh-CN/docs/images/curriculum_progress.png new file mode 100644 index 0000000000..adbced8261 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/curriculum_progress.png differ diff --git a/docs/localized/zh-CN/docs/images/docker_build_settings.png b/docs/localized/zh-CN/docs/images/docker_build_settings.png new file mode 100644 index 0000000000..e0325a34b6 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/docker_build_settings.png differ diff --git a/docs/localized/zh-CN/docs/images/edit_env_var.png b/docs/localized/zh-CN/docs/images/edit_env_var.png new file mode 100644 index 0000000000..2fd622c431 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/edit_env_var.png differ diff --git a/docs/localized/zh-CN/docs/images/gridworld.png b/docs/localized/zh-CN/docs/images/gridworld.png new file mode 100644 index 0000000000..f31d6e01a1 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/gridworld.png differ diff --git a/docs/localized/zh-CN/docs/images/hallway.png b/docs/localized/zh-CN/docs/images/hallway.png new file mode 100644 index 0000000000..776c73f70e Binary files /dev/null and b/docs/localized/zh-CN/docs/images/hallway.png differ diff --git a/docs/localized/zh-CN/docs/images/internal_brain.png b/docs/localized/zh-CN/docs/images/internal_brain.png new file mode 100644 index 0000000000..1a434e03fc Binary files /dev/null and b/docs/localized/zh-CN/docs/images/internal_brain.png differ diff --git a/docs/localized/zh-CN/docs/images/learning_environment.png b/docs/localized/zh-CN/docs/images/learning_environment.png new file mode 100644 index 0000000000..df590a0b9f Binary files /dev/null and b/docs/localized/zh-CN/docs/images/learning_environment.png differ diff --git a/docs/localized/zh-CN/docs/images/learning_environment_basic.png b/docs/localized/zh-CN/docs/images/learning_environment_basic.png new file mode 100644 index 0000000000..14431e8c50 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/learning_environment_basic.png differ diff --git a/docs/localized/zh-CN/docs/images/learning_environment_example.png b/docs/localized/zh-CN/docs/images/learning_environment_example.png new file mode 100644 index 0000000000..7ffaa030b6 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/learning_environment_example.png differ diff --git a/docs/localized/zh-CN/docs/images/math.png b/docs/localized/zh-CN/docs/images/math.png new file mode 100644 index 0000000000..6cd1b696dd Binary files /dev/null and b/docs/localized/zh-CN/docs/images/math.png differ diff --git a/docs/localized/zh-CN/docs/images/ml-agents-LSTM.png b/docs/localized/zh-CN/docs/images/ml-agents-LSTM.png new file mode 100644 index 0000000000..313a8edc1f Binary files /dev/null and b/docs/localized/zh-CN/docs/images/ml-agents-LSTM.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-3DBallHierarchy.png b/docs/localized/zh-CN/docs/images/mlagents-3DBallHierarchy.png new file mode 100644 index 0000000000..166d506d5a Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-3DBallHierarchy.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-BuildWindow.png b/docs/localized/zh-CN/docs/images/mlagents-BuildWindow.png new file mode 100644 index 0000000000..4eae2512d6 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-BuildWindow.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewProject.png b/docs/localized/zh-CN/docs/images/mlagents-NewProject.png new file mode 100644 index 0000000000..e8120309cd Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewProject.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutAcademy.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutAcademy.png new file mode 100644 index 0000000000..02e2a4d210 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutAcademy.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutAssignBrain.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutAssignBrain.png new file mode 100644 index 0000000000..9e00edbc4a Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutAssignBrain.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutBlock.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutBlock.png new file mode 100644 index 0000000000..32eac7fe1e Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutBlock.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutBrain.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutBrain.png new file mode 100644 index 0000000000..b130395452 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutBrain.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutFloor.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutFloor.png new file mode 100644 index 0000000000..b3e71bb11a Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutFloor.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutHierarchy.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutHierarchy.png new file mode 100644 index 0000000000..549040098f Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutHierarchy.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutSphere.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutSphere.png new file mode 100644 index 0000000000..982e1e3a3b Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutSphere.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-NewTutSplash.png b/docs/localized/zh-CN/docs/images/mlagents-NewTutSplash.png new file mode 100644 index 0000000000..25d8e80d21 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-NewTutSplash.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-Open3DBall.png b/docs/localized/zh-CN/docs/images/mlagents-Open3DBall.png new file mode 100644 index 0000000000..f59092a5bb Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-Open3DBall.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-SetExternalBrain.png b/docs/localized/zh-CN/docs/images/mlagents-SetExternalBrain.png new file mode 100644 index 0000000000..7637fa50c0 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-SetExternalBrain.png differ diff --git a/docs/localized/zh-CN/docs/images/mlagents-TensorBoard.png b/docs/localized/zh-CN/docs/images/mlagents-TensorBoard.png new file mode 100644 index 0000000000..ffe7055e4f Binary files /dev/null and b/docs/localized/zh-CN/docs/images/mlagents-TensorBoard.png differ diff --git a/docs/localized/zh-CN/docs/images/monitor.png b/docs/localized/zh-CN/docs/images/monitor.png new file mode 100644 index 0000000000..da342630c6 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/monitor.png differ diff --git a/docs/localized/zh-CN/docs/images/new_system_variable.PNG b/docs/localized/zh-CN/docs/images/new_system_variable.PNG new file mode 100644 index 0000000000..d9ea72a72d Binary files /dev/null and b/docs/localized/zh-CN/docs/images/new_system_variable.PNG differ diff --git a/docs/localized/zh-CN/docs/images/normalization.png b/docs/localized/zh-CN/docs/images/normalization.png new file mode 100644 index 0000000000..768c436971 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/normalization.png differ diff --git a/docs/localized/zh-CN/docs/images/path_variables.PNG b/docs/localized/zh-CN/docs/images/path_variables.PNG new file mode 100644 index 0000000000..c6455327d7 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/path_variables.PNG differ diff --git a/docs/localized/zh-CN/docs/images/player_brain.png b/docs/localized/zh-CN/docs/images/player_brain.png new file mode 100755 index 0000000000..043f0d9c1b Binary files /dev/null and b/docs/localized/zh-CN/docs/images/player_brain.png differ diff --git a/docs/localized/zh-CN/docs/images/push.png b/docs/localized/zh-CN/docs/images/push.png new file mode 100644 index 0000000000..661e5721be Binary files /dev/null and b/docs/localized/zh-CN/docs/images/push.png differ diff --git a/docs/localized/zh-CN/docs/images/reacher.png b/docs/localized/zh-CN/docs/images/reacher.png new file mode 100644 index 0000000000..2311f6bc65 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/reacher.png differ diff --git a/docs/localized/zh-CN/docs/images/rl_cycle.png b/docs/localized/zh-CN/docs/images/rl_cycle.png new file mode 100644 index 0000000000..2283360dd7 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/rl_cycle.png differ diff --git a/docs/localized/zh-CN/docs/images/scene-hierarchy.png b/docs/localized/zh-CN/docs/images/scene-hierarchy.png new file mode 100755 index 0000000000..b045adeff1 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/scene-hierarchy.png differ diff --git a/docs/localized/zh-CN/docs/images/soccer.png b/docs/localized/zh-CN/docs/images/soccer.png new file mode 100644 index 0000000000..26d59de6d3 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/soccer.png differ diff --git a/docs/localized/zh-CN/docs/images/splitbar.png b/docs/localized/zh-CN/docs/images/splitbar.png new file mode 100644 index 0000000000..8f3a2c2b8b Binary files /dev/null and b/docs/localized/zh-CN/docs/images/splitbar.png differ diff --git a/docs/localized/zh-CN/docs/images/system_variable_name_value.PNG b/docs/localized/zh-CN/docs/images/system_variable_name_value.PNG new file mode 100644 index 0000000000..85d1d18b6c Binary files /dev/null and b/docs/localized/zh-CN/docs/images/system_variable_name_value.PNG differ diff --git a/docs/localized/zh-CN/docs/images/tennis.png b/docs/localized/zh-CN/docs/images/tennis.png new file mode 100644 index 0000000000..817f8a8ef9 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/tennis.png differ diff --git a/docs/localized/zh-CN/docs/images/unity-logo-rgb.png b/docs/localized/zh-CN/docs/images/unity-logo-rgb.png new file mode 100755 index 0000000000..4a37a405cc Binary files /dev/null and b/docs/localized/zh-CN/docs/images/unity-logo-rgb.png differ diff --git a/docs/localized/zh-CN/docs/images/unity-wide.png b/docs/localized/zh-CN/docs/images/unity-wide.png new file mode 100644 index 0000000000..1668b46745 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/unity-wide.png differ diff --git a/docs/localized/zh-CN/docs/images/unity_linux_build_support.png b/docs/localized/zh-CN/docs/images/unity_linux_build_support.png new file mode 100644 index 0000000000..c253efcae6 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/unity_linux_build_support.png differ diff --git a/docs/localized/zh-CN/docs/images/visual-observation.png b/docs/localized/zh-CN/docs/images/visual-observation.png new file mode 100644 index 0000000000..f89a71489e Binary files /dev/null and b/docs/localized/zh-CN/docs/images/visual-observation.png differ diff --git a/docs/localized/zh-CN/docs/images/wall.png b/docs/localized/zh-CN/docs/images/wall.png new file mode 100644 index 0000000000..41430ca279 Binary files /dev/null and b/docs/localized/zh-CN/docs/images/wall.png differ