在 AWS EC2 上训练 Unity ML-Agents 环境：完整云端训练部署指南-港品优选

在 AWS EC2 上训练 Unity ML-Agents 环境：完整云端训练部署指南

【免费下载链接】ml-agentsThe 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 在 Amazon Web Service（AWS）EC2 实例上的云端训练方案。你将掌握两条落地路径：一是直接使用官方预配置的 Deep Learning AMI 快速起步；二是从零配置自己的 GPU 实例（含 CUDA、NVIDIA 驱动、虚拟显示 X Server 的完整搭建）。读完本文，你将能够在无显示器的云端服务器上构建、上传并运行 Unity 环境可执行文件，通过mlagents-learn启动强化学习训练，并能独立排查最常见的启动失败问题。

⚠️ 前置说明：本指南对应仓库中的 Training-on-Amazon-Web-Service.md。该文档原为 Unity 官方团队内部使用的指南，官方已声明"我们不再自行使用此指南，因此它可能无法完全按原文正常工作"，仅作为参考保留。文中涉及的 AMI ID、NVIDIA 驱动版本（390.87）等属于历史环境信息，在使用时请结合当前 AWS 镜像市场与驱动版本做相应替换，但整体的部署流程、故障排查思路与 ML-Agents 的训练接入方式依然完全有效。

为什么选择在 EC2 上训练

ML-Agents 的强化学习训练是典型的计算密集型任务，本地机器的 GPU 算力往往成为训练吞吐量的瓶颈。将训练迁移到 AWS EC2 的核心收益在于：

弹性算力：按需租用 GPU 实例（如 p2.xlarge，搭载 Tesla K80），训练完成后即可释放，成本可控；
算力隔离：训练期间可以继续使用本地 Unity Editor 做其他开发任务；
规模化并发：可以在实例上利用 --num-envs 并发训练特性同时启动多个环境实例，加速样本采集；
无人值守：环境以可执行文件（Executable）形式运行，无需依赖本地 Editor 进程。

从架构层面看，云端训练与本地训练的唯一区别在于：Unity 可执行文件与 Python 训练进程（mlagents-learn）在同一台远程机器上通过内部端口通信，而不像 Editor 模式那样通过外部端口连接本地进程。具体通信机制见 environment.py：UnityEnvironment在初始化时若指定了file_name，会通过env_utils.launch_executable直接拉起 Unity 二进制进程，并基于base_port + worker_id建立 socket 连接。

方案一：使用预配置 AMI 快速起步

官方在us-east-1区域准备了一个预配置 AMI，ID 为ami-016ff5559334f8619。该 AMI 基于 AWS Marketplace 上的Deep Learning AMI (Ubuntu)修改而来，已内置 NVIDIA 驱动、CUDA 9 与 cuDNN，并已使用p2.xlarge实例完成过验证。

启动实例并 SSH 登录后，若你的训练任务不使用Headless 模式（即环境需要渲染视觉观测），必须先启动 X Server，否则 Unity 无法创建渲染上下文：

# 启动 X Server，按回车返回命令行 $ sudo /usr/bin/X :0 & # 通过 nvidia-smi 确认 Xorg 进程已出现在 GPU 进程列表中 $ nvidia-smi

正常时nvidia-smi的输出应类似（Xorg 出现在进程列表中）：

# Thu Jun 14 20:27:26 2018 # +-----------------------------------------------------------------------------+ # | NVIDIA-SMI 390.67 Driver Version: 390.67 | # |-------------------------------+----------------------+----------------------+ # | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | # | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | # |===============================+======================+======================| # | 0 Tesla K80 On | 00000000:00:1E.0 Off | 0 | # | N/A 35C P8 31W / 149W | 9MiB / 11441MiB | 0% Default | # +-------------------------------+----------------------+----------------------+ # # +-----------------------------------------------------------------------------+ # | Processes: GPU Memory | # | GPU PID Type Process name Usage | # |=============================================================================| # | 0 2331 G /usr/lib/xorg/Xorg 8MiB | # +-----------------------------------------------------------------------------+

随后让 ubuntu 用户使用该 X Server 作为显示输出：

$ export DISPLAY=:0

提示：该export仅对当前 Shell 会话有效。若训练进程由其他会话启动（如通过nohup、tmux或screen后台运行），需要在该会话中同样设置DISPLAY=:0。

方案二：自行配置 EC2 实例

如果预配置 AMI 不可用或不满足需求，可以自行搭建。前提是拥有一台包含最新 NVIDIA 驱动、CUDA 9 与 cuDNN的 EC2 实例，官方教程使用的是 AWS Marketplace 中 Deep Learning AMI (Ubuntu) 搭配p2.xlarge（Tesla K80，12 GB 显存）。

在实例上安装 ML-Agents Toolkit

SSH 登录实例后：

激活 Deep Learning AMI 自带的 Python 3 环境：
```
source activate python3
```
克隆 ML-Agents 仓库并安装 Python 训练包（mlagents）及其依赖（mlagents_envs等）：
```
git clone --branch release_23 https://github.com/Unity-Technologies/ml-agents.git cd ml-agents/ml-agents/ pip3 install -e .
```
使用-e（editable）模式安装后，mlagents-learn命令可直接从命令行调用。仓库内包结构为 ml-agents/（训练器主包）与 ml-agents-envs/（环境通信层），后者提供了mlagents_envs.environment.UnityEnvironment这一核心 API，见 environment.py。

设置 X Server（可选但关键）

X Server 只在需要视觉观测（visual observation）输入的训练中才必要。这是因为 Unity 引擎当前的限制要求渲染时必须存在一块屏幕；当在无显示器的远程服务器上训练时，必须用虚拟屏幕替代。搭建完成后，Unity 环境渲染到虚拟屏幕，训练方式与本地完全一致。

重要：使用视觉观测构建 Linux 可执行文件时，必须关闭 Headless 模式。

安装并配置 Xorg

# 安装 Xorg 与 OpenGL 工具 $ sudo apt-get update $ sudo apt-get install -y xserver-xorg mesa-utils # 生成使用虚拟显示设备的 xorg 配置（1280x1024 虚拟分辨率） $ sudo nvidia-xconfig -a --use-display-device=None --virtual=1280x1024 # 查询 GPU 的 BusID 信息 $ nvidia-xconfig --query-gpu-info # 将 BusID 写入 /etc/X11/xorg.conf $ sudo sed -i 's/ BoardName "Tesla K80"/ BoardName "Tesla K80"\n BusID "0:30:0"/g' /etc/X11/xorg.conf # 用 vim 打开 xorg.conf，删除 "Section Files" 与 "EndSection" 两行 $ sudo vim /etc/X11/xorg.conf

更新并配置 NVIDIA 驱动

# 下载并安装适用于 Ubuntu 的 NVIDIA 驱动 # 驱动版本请参考官方驱动下载页的最新版本号 $ wget http://download.nvidia.com/XFree86/Linux-x86_64/390.87/NVIDIA-Linux-x86_64-390.87.run $ sudo /bin/bash ./NVIDIA-Linux-x86_64-390.87.run --accept-license --no-questions --ui=none # 禁用 Nouveau 开源驱动，避免与 NVIDIA 闭源驱动冲突 $ sudo echo 'blacklist nouveau' | sudo tee -a /etc/modprobe.d/blacklist.conf $ sudo echo 'options nouveau modeset=0' | sudo tee -a /etc/modprobe.d/blacklist.conf $ sudo echo options nouveau modeset=0 | sudo tee -a /etc/modprobe.d/nouveau-kms.conf # 重新生成 initramfs，使 blacklist 生效 $ sudo update-initramfs -u

重启实例并清理残留进程

$ sudo reboot now

重启后，确认没有任何 Xorg 进程在运行（有则重复执行killall）：

# 结束可能存在的 Xorg 进程（根据配置可能需要执行多次） $ sudo killall Xorg # 用 nvidia-smi 确认 Xorg 不在 GPU 进程列表中 $ nvidia-smi

正常输出应为：

# Thu Jun 14 20:21:11 2018 # +-----------------------------------------------------------------------------+ # | NVIDIA-SMI 390.67 Driver Version: 390.67 | # |-------------------------------+----------------------+----------------------+ # | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | # | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | # |===============================+======================+======================| # | 0 Tesla K80 On | 00000000:00:1E.0 Off | 0 | # | N/A 37C P8 31W / 149W | 0MiB / 11441MiB | 0% Default | # +-------------------------------+----------------------+----------------------+ # # +-----------------------------------------------------------------------------+ # | Processes: GPU Memory | # | GPU PID Type Process name Usage | # |=============================================================================| # | No running processes found | # +-----------------------------------------------------------------------------+

启动 X Server 并验证配置

# 启动 X Server，按回车返回命令行 $ sudo /usr/bin/X :0 & # 确认 Xorg 已进入 GPU 进程列表 $ nvidia-smi # 让 ubuntu 用户使用 X Server 显示 $ export DISPLAY=:0

最后用 OpenGL 测试工具glxgears验证 Xorg 是否工作正常：

$ glxgears # 若配置正确，应看到类似输出： # Running synchronized to the vertical refresh. The framerate should be # approximately the same as the monitor refresh rate. # 137296 frames in 5.0 seconds = 27459.053 FPS # 141674 frames in 5.0 seconds = 28334.779 FPS # 141490 frames in 5.0 seconds = 28297.875 FPS

glxgears的高帧率输出说明 OpenGL 渲染管线已通过 NVIDIA 驱动正常工作，Unity 环境将可以顺利渲染。

在 EC2 上训练：完整流程

环境搭建完成后，按以下步骤在 EC2 上启动训练：

1. 在本地构建 Linux 可执行环境

在 Unity Editor 中打开包含 ML-Agents 环境的项目（没有自定义环境时可使用Project/Assets/ML-Agents/Examples/下的示例环境）；
打开File > Build Settings；
目标平台选择Linux，目标架构选择x86_64（默认的 x86 目前无法工作）；
若未配置 X Server，勾选Headless Mode；若不使用 Headless 模式，则必须完成上文 X Server 搭建；
点击Build生成环境可执行文件。

关于环境可执行文件的更多构建细节（如 Player Settings 中开启Run in Background、禁用分辨率对话框等），可参考 Learning-Environment-Executable.md。

2. 上传可执行文件并授权

# 将构建产物（可执行文件及其 <Executable_Name>_Data 数据文件夹）上传至实例的 ml-agents 目录 # 使用 scp 或 AWS CLI 等工具完成上传 # 为可执行文件添加执行权限 chmod +x <your_env>.x86_64

这一步至关重要：mlagents_envs的 launch_executable 通过subprocess.Popen拉起 Unity 二进制，若缺少执行权限会抛出PermissionError并被包装为UnityEnvironmentException，提示chmod -R 755修复。

3. （非 Headless 时）启动 X Server

# 启动 X Server，按回车返回命令行 $ sudo /usr/bin/X :0 & # 确认 Xorg 在 GPU 进程列表中 $ nvidia-smi # 让 ubuntu 用户使用 X Server 显示 $ export DISPLAY=:0

4. 用 Python 验证环境可启动

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

其中<your_env>是环境可执行文件的路径。若成功，会收到环境加载成功的确认消息。

从源码看，UnityEnvironment.__init__（environment.py）在启动进程后还会依次完成端口选择（有file_name时默认BASE_ENVIRONMENT_PORT，否则DEFAULT_EDITOR_PORT）、初始化消息发送、通信版本兼容性检查等步骤；timeout_wait参数（默认 60 秒）控制等待环境响应的最长时间。这意味着任何一步失败都会直接导致环境初始化异常——这正是下面 FAQ 中各类报错的根源。

5. 启动训练

mlagents-learn <trainer-config-file> --env=<your_env> --train

mlagents-learn是 ML-Agents 训练的唯一入口（实现位于 ml-agents/mlagents/trainers/learn.py，命令行参数由parse_command_line解析为RunOptions）。各参数含义：

<trainer-config-file>：训练器配置 YAML 文件路径，包含全部超参数。仓库为示例环境提供了现成配置，如 config/ppo/3DBall.yaml、config/sac/Walker.yaml、config/poca/SoccerTwos.yaml；
--env=<your_env>：环境可执行文件路径（可选参数，省略时连接 Unity Editor）；
--train：训练模式标志。注意：在 learn.py 中，--train已被标记为废弃——训练现在是默认模式，--train仅为保持向后兼容而保留；
常用附加参数：--run-id=<标识符>区分不同训练结果、--resume恢复训练、--force覆盖已有结果、--num-envs=<n>并发环境数量、--base-port起始端口。详见 Training-ML-Agents.md。

训练产物（TensorBoard 摘要、模型检查点与最终.onnx文件、timers 日志）统一写入results/<run-identifier>/目录。

无图形环境训练（Headless）

若你的训练任务不需要渲染（即不使用 Camera 视觉观测），可以在不搭建 X Server 的情况下直接以无图形模式运行，两种方式：

给mlagents-learn传入--no-graphics参数，等价于给 Unity 可执行文件追加-nographics -batchmode命令行参数；
在 Unity Build Settings 中勾选Server Build构建无图形版本。

若训练确实需要视觉观测（如摄像头输入），则必须在服务器上配置虚拟显示（如本文的 X Server 方案，或 xvfb），参见 Learning-Environment-Executable.md。

常见问题排查（FAQ）

Q1：`<Executable_Name>_Data`文件夹未一并上传

构建 Linux 可执行文件后，如果只上传了二进制而遗漏了同级的<Executable_Name>_Data数据文件夹，启动时会报错：

Set current directory to /home/ubuntu/ml-agents/ml-agents Found path: /home/ubuntu/ml-agents/ml-agents/3dball_linux.x86_64 no boot config - using default values (Filename: Line: 403) There is no data folder

解决：将 Unity 构建输出的整个目录（可执行文件 +<Executable_Name>_Data）完整上传。

Q2：Unity 环境不响应（连接超时）

以下几种情况都会导致 Unity 与 Python 的握手失败：

未配置 X Server 或未正确启动（非 Headless 环境）；
环境进程崩溃；
未执行chmod +x授予执行权限。

典型报错：

Logging to /home/ubuntu/.config/unity3d/<Some_Path>/Player.log Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/home/ubuntu/ml-agents/ml-agents/mlagents_envs/environment.py", line 63, in __init__ aca_params = self.send_academy_parameters(rl_init_parameters_in) File "/home/ubuntu/ml-agents/ml-agents/mlagents_envs/environment.py", line 489, in send_academy_parameters return self.communicator.initialize(inputs).rl_initialization_output File "/home/ubuntu/ml-agents/ml-agents/mlagents_envs/rpc_communicator.py", line 60, in initialize mlagents_envs.exception.UnityTimeOutException: The Unity environment took too long to respond. Make sure that : The environment does not need user interaction to launch The environment and the Python interface have compatible versions.

UnityTimeOutException的定义见 ml-agents-envs/mlagents_envs/exception.py。排查建议：

查看 Unity Player 日志/home/ubuntu/.config/unity3d/<Some_Path>/Player.log，定位环境崩溃原因；
确认环境无需任何交互即可启动（如登录弹窗、对话框会阻塞进程）；
确认 Python 包（mlagents_envs/mlagents）与 Unity 侧的 ML-Agents 包版本兼容——UnityEnvironment.__init__中会显式校验communication_version与package_version，不匹配时抛出版本异常并提示从 release 页挑选兼容版本（见 environment.py）。

Q3：无法启动 X Server

执行sudo /usr/bin/X :0 &时出现：

X.Org X Server 1.18.4 ... (==) Log file: "/var/log/Xorg.0.log", Time: Thu Oct 11 21:10:38 2018 (==) Using config file: "/etc/X11/xorg.conf" (==) Using system config directory "/usr/share/X11/xorg.conf.d" (EE) Fatal server error: (EE) no screens found(EE) (EE) Please consult the X.Org Foundation support at http://wiki.x.org for help. (EE) Please also check the log file at "/var/log/Xorg.0.log" for additional information. (EE) (EE) Server terminated with error (1). Closing log file.

同时nvidia-smi报错：

NVIDIA-SMI has failed because it could not communicate with the NVIDIA driver. Make sure that the latest NVIDIA driver is installed and running.

原因：NVIDIA 驱动未正确加载或已失效，X Server 找不到可用的显示设备（no screens found）。解决：按上文"更新并配置 NVIDIA 驱动"一节重新安装驱动、禁用 Nouveau 并update-initramfs -u后重启，再依序完成 Xorg 配置与验证。

小结

在 AWS EC2 上训练 ML-Agents 环境，本质上是在远程 GPU 机器上复刻"Unity 可执行文件 + Python 训练器"的双进程架构，其核心难点不在 ML-Agents 本身，而在无显示器 Linux 环境的渲染可用性。记住三条主线即可顺利落地：

优先 Headless：不使用视觉观测时，--no-graphics或 Server Build 可完全绕开 X Server 复杂度；
视觉训练必配虚拟屏幕：按 Xorg → NVIDIA 驱动 → 虚拟分辨率 →DISPLAY=:0的顺序逐一验证，并以glxgears为最终验收标准；
训练接入与本地一致：UnityEnvironment验证环境可启动后，直接用mlagents-learn <config> --env=<your_env>拉起训练，产物落入results/<run-identifier>/。

遇到问题时优先查看三个日志/状态源：nvidia-smi（GPU 与驱动状态）、/var/log/Xorg.0.log（显示服务器状态）、/home/ubuntu/.config/unity3d/<Some_Path>/Player.log（Unity 环境状态），即可快速定位绝大多数云端训练故障。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析