Unity 机器学习智能体工具包

(最新版本) (所有版本)

Unity 机器学习智能体工具包（ML-Agents）是一个开源项目，它使游戏和模拟环境能够作为训练智能体的平台。我们基于 PyTorch 提供了当前最先进的算法实现，让游戏开发者和爱好者可以轻松地为 2D、3D 以及 VR/AR 游戏训练智能体。研究人员也可以使用我们提供的简单易用的 Python API，通过强化学习、模仿学习、神经进化或其他方法来训练智能体。这些训练好的智能体可用于多种用途，包括控制 NPC 行为（在多智能体和对抗性等多种场景中）、自动化测试游戏版本，以及在发布前评估不同的游戏设计决策。ML-Agents 工具包对游戏开发者和人工智能研究者都大有裨益，因为它提供了一个中心化平台，可以在 Unity 丰富的环境中评估人工智能领域的进展，并将这些成果开放给更广泛的研究和游戏开发社区。

功能特性

• 17+ 个 示例 Unity 环境
• 支持多种环境配置和训练场景
• 灵活的 Unity SDK，可集成到您的游戏或自定义 Unity 场景中
• 支持通过多种深度强化学习算法（PPO、SAC、MA-POCA、自我对弈）训练单智能体、多智能体协作以及多智能体竞争场景。
• 支持通过两种模仿学习算法（BC 和 GAIL）从示范中学习。
• 可快速简便地添加您自己的 自定义训练算法 和/或组件。
• 针对复杂任务可轻松定义课程式学习场景
• 使用环境随机化训练鲁棒性更强的智能体
• 通过按需决策实现灵活的智能体控制
• 可同时使用多个 Unity 环境实例进行训练
• 利用 推理引擎 提供原生跨平台支持
• 可从 Python 控制 Unity 环境 Python LLAPI
• 可将 Unity 学习环境封装为 gym 环境
• 可将 Unity 学习环境封装为 PettingZoo 环境

发布与文档

⚠️ 文档迁移通知 我们已将 Unity Package 文档 作为主要的开发者文档，并已弃用对 网页文档 的维护。请使用 Unity Package 文档以获取最新信息。

下表展示了我们的最新版本，包括处于积极开发中且可能不稳定的 develop 分支。以下是一些有用的指南：

• 版本管理页面 概述了我们如何管理 GitHub 发布以及 ML-Agents 各组件的版本化进程。
• 发布页面 包含了各版本之间的变更详情。
• 迁移页面 提供了从早期版本的 ML-Agents Toolkit 升级的详细说明。
• com.unity.ml-agents 包已在 Unity 2020.1 及更高版本上通过验证。经过验证的包版本号为 1.0.x。

版本	发布日期	源代码	文档	下载	Python 包	Unity 包
Release 23	2025年8月28日	源代码	文档	下载	1.1.0	4.0.0
develop（不稳定）	--	源代码	文档	下载	--	--

如果您是对此感兴趣的科研人员，并希望探讨 Unity 作为 AI 平台，请参阅我们关于 Unity 和 ML-Agents Toolkit 的预印本论文。

如果您使用 Unity 或 ML-Agents Toolkit 进行研究，我们恳请您引用以下论文作为参考文献：

@article{juliani2020,
  title={Unity: A general platform for intelligent agents},
  author={Juliani, Arthur and Berges, Vincent-Pierre and Teng, Ervin and Cohen, Andrew and Harper, Jonathan and Elion, Chris and Goy, Chris and Gao, Yuan and Henry, Hunter and Mattar, Marwan and Lange, Danny},
  journal={arXiv preprint arXiv:1809.02627},
  url={https://arxiv.org/pdf/1809.02627.pdf},
  year={2020}
}

此外，如果您在研究中使用 MA-POCA 训练器，我们也恳请您引用以下论文作为参考文献：

@article{cohen2022,
  title={On the Use and Misuse of Absorbing States in Multi-agent Reinforcement Learning},
  author={Cohen, Andrew and Teng, Ervin and Berges, Vincent-Pierre and Dong, Ruo-Ping and Henry, Hunter and Mattar, Marwan and Zook, Alexander and Ganguly, Sujoy},
  journal={RL in Games Workshop AAAI 2022},
  url={http://aaai-rlg.mlanctot.info/papers/AAAI22-RLG_paper_32.pdf},
  year={2022}
}

其他资源

• Unity 讨论区
• CodeMonkeyUnity 的 ML-Agents 教程
• Huggingface 关于 ML-Agents 的入门介绍
• 社区创建的 ML-Agents 项目
• Huggingface 上的 ML-Agents 模型
• 博客文章
• Discord 社区

社区与反馈

ML-Agents Toolkit 是一个开源项目，我们鼓励并欢迎社区贡献。如果您希望参与贡献，请务必阅读我们的贡献指南和行为准则。

如您在安装或配置 ML-Agents Toolkit 时遇到问题，或希望讨论如何更好地设置和训练您的智能体，请在 Unity ML-Agents 讨论区 创建新主题。请尽可能提供详细信息，以便他人更有效地帮助您。如果您在使用 ML-Agents Toolkit 时遇到其他问题，或有特定的功能需求，请提交 GitHub 问题。

请通过回复此讨论帖，告诉我们您希望 ML-Agents Unity 包中包含哪些示例。

隐私政策

为了提升 Unity ML-Agents Toolkit 的开发者体验，我们在编辑器中加入了分析功能。有关更多信息，请参阅 Unity 隐私政策 中的“由 Unity 被动收集的信息”。

Unity ML-Agents 快速上手指南

Unity ML-Agents Toolkit 是一个开源项目，允许将游戏和模拟环境作为训练智能代理（Agents）的场所。它基于 PyTorch 实现了多种前沿算法（如 PPO、SAC、模仿学习等），帮助开发者轻松为 2D、3D 及 VR/AR 应用训练智能行为。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• Unity 编辑器: 版本 2020.1 或更高（推荐使用最新 LTS 版本）
• Python: 版本 3.8 至 3.10 (推荐 3.8+)
• 包管理器: pip (通常随 Python 安装)

注意：本指南假设您已安装好 Unity Hub 和基础 Python 环境。国内用户建议使用清华源或阿里源加速 Python 包下载。

2. 安装步骤

第一步：安装 Python 依赖

打开终端（Terminal 或 CMD），运行以下命令安装 ML-Agents 的 Python 端库。

通用安装命令：

pip install mlagents

国内加速安装（推荐）：

pip install mlagents -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步：在 Unity 中安装 Package

1. 打开 Unity 编辑器，创建一个新的 3D 项目或打开现有项目。
2. 点击菜单栏 Window > Package Manager。
3. 点击左上角的 + 号，选择 Add package by name...。
4. 在弹出的对话框中输入包名：

   com.unity.ml-agents
   

5. 点击 Add。Unity 将自动下载并安装最新的验证版本（当前主要版本为 4.x）。

提示：如果网络较慢导致安装失败，可尝试在 Unity 的 Packages/manifest.json 文件中手动添加 "com.unity.ml-agents": "4.0.0" (版本号以实际最新为准)，然后重启 Unity。

3. 基本使用

以下是训练第一个智能代理的最简流程：

步骤 A: 导入示例场景

为了快速验证，我们直接使用官方提供的示例环境。

1. 在 Unity 菜单中，点击 ML-Agents > Import Examples.
2. 等待资源导入完成。
3. 在 Project 窗口导航至 Packages/com.unity.ml-agents/Examples/3DBall/Scenes。
4. 双击打开 3DBall.unity 场景。

步骤 B: 配置训练参数

1. 在场景中选中名为 LearningBehavior 的游戏对象（或在 Hierarchy 中找到带有 Behavior Parameters 组件的对象）。
2. 确保 Behavior Name 设置为 3DBall（这将作为训练时的标识符）。
3. 无需修改其他代码，默认配置已包含观测空间和行为动作定义。

步骤 C: 启动训练

1. 保持 Unity 场景处于未运行状态（不要点击 Play），但需保存场景。
2. 回到终端，确保位于项目根目录或任意路径。
3. 运行以下训练命令：

mlagents-learn config/ppo/3DBall.yaml --run-id=first_run --env-name=3DBall

• --run-id: 自定义本次训练的标识。
• --env-name: 必须与 Unity 场景中 Behavior Parameters 组件里的 Behavior Name 一致。
• 如果是首次运行且未指定环境路径，脚本会尝试连接正在运行的 Unity 实例。请先在 Unity 中点击 Play 按钮，然后再执行上述命令（或者使用 --env-path 指定构建好的可执行文件路径进行无头训练）。

最简单的交互式训练流程（推荐新手）：

1. 在 Unity 中点击 Play 按钮运行场景。
2. 在终端执行：

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

3. 观察终端输出，当看到 Connected to Unity environment 时，表示训练已开始。
4. 训练完成后，模型将保存在 results/first_run/models/ 目录下。

步骤 D: 使用训练好的模型

训练结束后，将生成的 .onnx 模型文件（位于 results/<run-id>/models/）拖拽到 Unity 项目中，替换原示例文件夹中的模型，或赋值给 Behavior Parameters 组件的 Model 字段，即可让 AI 自主控制平衡球。