ML-Agents 环境可执行文件构建与训练指南：从 Unity 场景打包到 Headless 服务器部署-开发者社区

人工智能
强化学习
深度学习
机器学习
游戏开发
AI 应用

【免费下载链接】ml-agents

The Unity Machine Learning Agents Toolkit (ML-Agents) is an open-source project that enables games and simulations to serve as environments for training intelligent agents using deep reinforcement learning and imitation learning.

项目地址：https://gitcode.com/gh_mirrors/ml/ml-agents

点击查看免费下载

本文基于 Unity ML-Agents Toolkit 官方文档 Learning-Environment-Executable.md，系统讲解如何将 Unity 训练场景（以 3DBall 平衡球环境为例）构建为独立可执行文件，并通过 Python API 与mlagents-learn命令行工具与之交互、训练，最终把训练产物（ONNX 模型）嵌回场景中，以及如何在无图形界面的 Headless 服务器上加速训练。读完本文，你将掌握"场景配置 → 打包可执行文件 → Python 连接 → 命令行训练 → 模型回嵌"的完整实战链路，并理解其底层通信与进程启动机制。

为什么要使用可执行文件而不是 Unity 编辑器

ML-Agents 既支持在 Unity 编辑器内点击 Play 直接训练，也支持将场景构建为独立可执行文件（Executable）后再进行训练。相比编辑器模式，使用可执行文件有以下优势：

便于分发：你可以把可执行文件直接交给他人使用，而无需共享整个 Unity 工程仓库；
便于远端部署：可以把可执行文件放到远程机器上运行，借助更强的 CPU/GPU 资源加速训练；
支持无图形模式：只要环境不依赖渲染（不使用视觉观测），就可以使用Server Build（Headless）模式获得更快的训练速度；
解放编辑器：训练在独立进程中运行时，你可以继续用 Unity 编辑器做其他事情。

第一步：构建 3DBall 可执行环境

本文以 3DBall（3D Balance Ball）示例环境为例，展示完整的构建流程。仓库中该示例位于 Project/Assets/ML-Agents/Examples/3DBall，包含场景、Prefab、Agent 脚本与预训练模型等完整资源。

打开 3DBall 场景

启动 Unity；
在 Projects 对话框顶部选择Open；
在文件对话框中定位到 ML-Agents 工程下的Project文件夹并点击Open；
在Project窗口中进入Assets/ML-Agents/Examples/3DBall/Scenes/目录；
双击3DBall文件加载包含平衡球环境的场景。

仓库中该目录还包含3DBallHard与Visual3DBall两个变体场景：前者是更难的物理版本，后者使用视觉观测（Camera）而非向量观测。本文聚焦于基础向量观测版本的3DBall。

配置场景以适配训练启动

训练进程启动可执行文件时，程序必须能静默、自动地进入正确场景，因此需要满足三个条件：应用在后台运行、没有需要人工交互的对话框、正确场景自动加载。

打开 Player Settings（菜单：Edit>Project Settings>Player）；
在Resolution and Presentation下：
- 确保Run in Background为勾选状态；
- 确保Display Resolution Dialog设置为 Disabled（注：较新版本的编辑器可能没有该选项）；
打开 Build Settings 窗口（菜单：File>Build Settings）；
选择目标平台；
- （可选）勾选 "Development Build" 以输出调试日志；
如果Scenes in Build列表中已有场景，确保只有 3DBall 场景被勾选（若列表为空，则只有当前场景会被打进构建）；
点击Build：
- 在文件对话框中定位到 ML-Agents 目录；
- 指定文件名并点击Save；
- （Windows 平台）使用 Unity 2018.1 时，构建会要求选择文件夹而非文件名。请在根目录下创建一个子文件夹并选择它，后续步骤中将该子文件夹名称为env_name。注意不能把构建产物放到Assets文件夹内。

完成以上步骤后，你就得到了一个包含模拟环境的 Unity 可执行文件，接下来可以与之交互了。

第二步：用 Python API 与可执行环境交互

如果你希望用 Python API（Low-Level API）与可执行文件交互，只需要把可执行文件的名称传给UnityEnvironment的file_name参数：

from mlagents_envs.environment import UnityEnvironment env = UnityEnvironment(file_name=<env_name>)

其中<env_name>是不带扩展名的可执行文件名称（或路径）。

底层原理：可执行文件是如何被启动的

从源码层面看，UnityEnvironment.__init__会在file_name非空时调用env_utils.launch_executable启动子进程（见 ml-agents-envs/mlagents_envs/environment.py）：

if file_name is not None: try: self._process = env_utils.launch_executable( file_name, self._executable_args() ) except UnityEnvironmentException: self._close(0) raise

其中_executable_args()会拼接 Unity 可执行文件的命令行参数（environment.py）：

若开启无图形模式，追加-nographics -batchmode；
追加--mlagents-port <port>指定通信端口（对应源码中的_PORT_COMMAND_LINE_ARG）；
若指定log_folder且未显式传-logfile，则追加-logFile <path>/Player-<worker_id>.log。

而env_utils.launch_executable（见 ml-agents-envs/mlagents_envs/env_utils.py）内部会先调用validate_environment_path做路径归一化：它会剥离.app、.exe、.x86_64、.x86等扩展名，再按平台查找真正的可执行文件（macOS 在.app/Contents/MacOS/下查找，Windows 在.exe中查找，Linux 查找.x86_64/.x86），这也是为什么file_name可以不带扩展名。启动时还使用了start_new_session=True，使 SIGINT 等信号不会直接传到环境子进程，给环境留出正常关闭的机会。

连接建立后，UnityEnvironment还会通过_check_communication_compatibility校验 Unity 侧与 Python 侧的通信协议版本（API_VERSION = "1.5.0"，见 environment.py），主版本不一致时会抛出版本不兼容异常。

常用构造参数

UnityEnvironment的完整构造参数（environment.py）包括：

参数	默认值	说明
`file_name`	`None`	Unity 可执行文件名称；为`None`时连接编辑器（端口 5004）
`worker_id`	`0`	端口偏移量，端口 =`base_port + worker_id`，用于并行启动多个环境
`base_port`	5005（有可执行文件）/ 5004（编辑器）	通信基准端口
`seed`	`0`	随机种子，随初始化消息发送给 Unity
`no_graphics`	`False`	以无图形模式运行模拟器
`timeout_wait`	`60`	等待环境连接的秒数
`additional_args`	`[]`	附加的 Unity 命令行参数
`side_channels`	`None`	用于非 RL 通信的 Side Channel 列表
`log_folder`	`None`	Unity Player 日志输出目录（需绝对路径）
`num_areas`	`1`	每个 Unity 实例中的并行训练区域数量

第三步：用 mlagents-learn 命令行训练

打开命令行（或终端）窗口；
进入 ML-Agents Toolkit 的安装目录。如果按默认方式安装，则进入ml-agents/文件夹；
运行：

mlagents-learn <trainer-config-file> --env=<env_name> --run-id=<run-identifier>

其中：

<trainer-config-file>：训练器配置文件（YAML）的路径；
<env_name>：从 Unity 导出的可执行文件的名称和路径（不带扩展名）；
<run-identifier>：用于区分不同训练运行结果的字符串标识。

例如，将 3DBall 可执行文件保存到 ML-Agents Toolkit 安装目录后，运行：

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

启动后终端会先打印 ML-Agents 的 ASCII Logo 横幅。注意：如果使用 Anaconda，请先激活 ml-agents 环境（如conda activate ml-agents）。

训练器配置文件解析

命令中的<trainer-config-file>指向训练器配置 YAML。仓库中的 config/ppo/3DBall.yaml 是 3DBall 的 PPO 训练配置：

behaviors: 3DBall: trainer_type: ppo hyperparameters: batch_size: 64 buffer_size: 12000 learning_rate: 0.0003 beta: 0.001 epsilon: 0.2 lambd: 0.99 num_epoch: 3 learning_rate_schedule: linear network_settings: normalize: true hidden_units: 128 num_layers: 2 vis_encode_type: simple reward_signals: extrinsic: gamma: 0.99 strength: 1.0 keep_checkpoints: 5 max_steps: 500000 time_horizon: 1000 summary_freq: 12000

关键参数含义：

trainer_type: ppo：使用 PPO（近端策略优化）算法；
batch_size/buffer_size：每次更新的样本批大小与经验缓冲区容量；
learning_rate/learning_rate_schedule：学习率及其衰减策略（linear线性衰减）；
beta/epsilon/lambd/num_epoch：PPO 的熵正则系数、裁剪范围、GAE 系数与每批更新轮数；
network_settings：网络结构（隐藏单元数hidden_units、层数num_layers、观测归一化normalize）；
reward_signals.extrinsic.gamma：折扣因子，strength为外在奖励信号强度；
max_steps：训练总步数上限（当前配置为 500000）；
time_horizon：累积经验的时间视界；
summary_freq：输出训练统计的频率；
keep_checkpoints：保留的检查点数量。

更完整的配置项说明可参阅 Training-Configuration-File.md。

理解训练启动日志

如果mlagents-learn正常运行并开始训练，你会看到类似如下的输出：

CrashReporter: initialized Mono path[0] = '/Users/dericp/workspace/ml-agents/3DBall.app/Contents/Resources/Data/Managed' Mono config path = '/Users/dericp/workspace/ml-agents/3DBall.app/Contents/MonoBleedingEdge/etc' INFO:mlagents_envs: 'Ball3DAcademy' started successfully! Unity Academy name: Ball3DAcademy INFO:mlagents_envs:Connected new brain: Unity brain name: Ball3DLearning 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 Ball3DLearning: 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/first-run-0/Ball3DLearning INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 1000. Mean Reward: 1.242. Std of Reward: 0.746. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 2000. Mean Reward: 1.319. Std of Reward: 0.693. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 3000. Mean Reward: 1.804. Std of Reward: 1.056. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 4000. Mean Reward: 2.151. Std of Reward: 1.432. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 5000. Mean Reward: 3.175. Std of Reward: 2.250. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 6000. Mean Reward: 4.898. Std of Reward: 4.019. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 7000. Mean Reward: 6.716. Std of Reward: 5.125. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 8000. Mean Reward: 12.124. Std of Reward: 11.929. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 9000. Mean Reward: 18.151. Std of Reward: 16.871. Training. INFO:mlagents.trainers: first-run-0: Ball3DLearning: Step: 10000. Mean Reward: 27.284. Std of Reward: 28.667. Training.

这段日志的解读要点：

环境启动确认：'Ball3DAcademy' started successfully!表示 Unity 侧 Academy 已正常启动，日志同时打印 Mono 运行时路径；
行为（Behavior）连接确认：Connected new brain: Ball3DLearning说明 Python 侧已与 Unity 中的行为建立连接，并打印了观测规格。此处Vector Observation space size (per agent): 8与 3DBall Agent 的观测实现一致——在 Ball3DAgent.cs 的CollectObservations中，Agent 依次加入平台旋转角（2 个）、小球相对位置（3 个）与小球线速度（3 个），共 8 个向量观测；
超参数回显：训练器会打印当前生效的超参数与实际output_path（模型输出目录）；
训练进度：Step: N. Mean Reward: X. Std of Reward: Y按summary_freq周期输出平均奖励与标准差，可据此判断策略是否在收敛。

命令行常用参数（基于源码）

mlagents-learn的命令行参数定义在 ml-agents/mlagents/trainers/cli_utils.py 中，除文档示例用到的--env、--run-id外，常用参数还包括：

参数	默认值	说明
`--env`	`None`	待训练的 Unity 可执行文件路径
`--run-id`	`ppo`	训练运行标识，用于命名模型与统计子目录
`--resume`	`False`	从检查点恢复训练（需配合`--run-id`）
`--initialize-from <RUN_ID>`	`None`	从指定历史 run-id 初始化模型（可用于微调）
`--force`	`False`	强制覆盖已存在的同名 run-id 数据
`--seed`	`-1`	训练随机数种子
`--num-envs`	`1`	并发启动的 Unity 环境实例数
`--num-areas`	`1`	每个实例内的并行训练区域数
`--base-port`	`5005`	环境通信起始端口，第 i 个实例使用`base_port + worker_id`
`--timeout-wait`	`60`	等待 Unity 环境启动的秒数
`--results-dir`	`results`	结果输出根目录
`--no-graphics`	`False`	以无图形模式运行可执行文件（见下文）
`--no-graphics-monitor`	`False`	主 worker 用图形模式、其余 worker 用无图形模式
`--torch-device`	`None`	PyTorch 训练设备，如`"cpu"`、`"cuda"`、`"cuda:0"`

注意：--train与--load已废弃——训练模式现在是默认行为，恢复训练请使用--resume（见 learn.py 中的废弃提示）。

停止训练与获取模型

你可以按Ctrl+C停止训练，训练好的模型会保存在results/<run-identifier>/<behavior_name>.onnx，对应模型的最新检查点。

Windows 平台已知问题：在 Windows 上提前终止训练可能导致模型保存失败，建议等到 Step 达到配置 YAML 中设置的max_steps后再停止。

把训练好的模型嵌入 Agent

获得.onnx模型后，按以下步骤将其嵌入到场景的 Agent 中：

把模型文件移动到Project/Assets/ML-Agents/Examples/3DBall/TFModels/目录（仓库中该目录已包含官方预训练模型3DBall.onnx等）；
按前述方式在 Unity 编辑器中打开3DBall场景；
在 Project 窗口选中3DBallPrefab，并选中Agent；
把<behavior_name>.onnx文件从 Project 窗口拖到Ball3DAgentInspector 窗口的Model占位槽中；
点击编辑器顶部的Play按钮运行，即可看到 Agent 使用训练后的策略自主控制平台保持小球平衡。

第四步：在无图形 Headless 服务器上训练

要在没有图形渲染支持的 Headless 服务器上训练，需要关闭 Unity 可执行文件的图形显示，有两种方式：

命令行方式：在mlagents-learn训练命令中传入--no-graphics选项。这在功能上等价于给 Unity 可执行文件追加-nographics -batchmode参数；
构建方式：在 Unity 编辑器的 Build Settings 中使用Server Build构建可执行文件。

如果你需要带图形训练（例如使用 Camera 视觉观测），则需要在服务器上配置显示渲染支持（例如 xvfb）。本仓库的 Colab Notebook 教程中，Setup 部分给出了在服务器上配置 xvfb 的示例。

源码佐证

--no-graphics与--no-graphics-monitor在 cli_utils.py 中定义，官方 help 明确说明：仅在 Agent 不使用视觉观测时才能安全启用。这两个开关最终会传给UnityEnvironment(no_graphics=...)，并反映在_executable_args()生成的命令行中（追加-nographics -batchmode）。同时，no_graphics_monitor模式下主 worker 仍保留图形，其余 worker 使用无图形模式（见 environment.py），这在多环境并行训练且需保留一个可视化窗口时很有用。

常见问题与排查建议

"Provided filename does not match any environments"：launch_executable找不到可执行文件时会抛出该异常（env_utils.py）。请确认file_name/--env指向的路径存在，且不带.app/.exe等扩展名；Linux 下还需确保文件具备执行权限（源码注释建议chmod -R 755）。
通信版本不兼容：Python 与 Unity 包版本不匹配时，_check_communication_compatibility会拒绝连接并抛出 API 版本不兼容异常（environment.py）。请使用相互兼容的 Unity 包与 Python 包版本。
训练无输出或连接超时：检查Run in Background是否勾选、Display Resolution Dialog是否禁用，以及目标场景是否在 Scenes in Build 列表中唯一勾选；必要时使用--timeout-wait增大等待时间。
需要视觉观测的无头训练：不可使用--no-graphics，需在服务器上配置 xvfb 等虚拟显示方案。