企业官网建设流程全解析

Unity ML-Agents 训练可视化指南：使用 TensorBoard 观察与分析强化学习训练过程

【免费下载链接】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

TensorBoard 是 ML-Agents Toolkit 训练流程中的标准可视化工具，用于实时观察mlagents-learn训练过程中记录的各类统计指标。本文以 Using-Tensorboard.md 为主线，结合仓库中 stats.py、cli_utils.py、StatsRecorder.cs 等源码，系统讲解 TensorBoard 的启动方法、训练统计指标的含义与判读方法、数据导出、以及从 Unity C# 环境自定义上报指标（Custom Metrics）的完整方案。阅读完本文，你将能够独立启动并解读一次 ML-Agents 训练的完整可视化面板，并根据曲线判断训练健康度与调参方向。

TensorBoard 与 ML-Agents 的数据流

ML-Agents Toolkit 在每次学习会话（training session）期间会持续保存统计信息。这些统计信息由 Python 训练端负责落盘：

• mlagents-learn命令会把训练统计数据保存到名为results的目录中，并以你在训练时指定的run-id值来组织子目录（见 Using-Tensorboard.md）。
• 从源码看，落盘工作由TensorboardWriter完成：它以base_dir（即results目录）为根，为每个行为（category）创建{base_dir}/{category}子目录，并通过 PyTorch 的SummaryWriter写入标量（add_scalar）与直方图（add_histogram）事件文件（见 stats.py）。

由于 TensorBoard 读取的是results目录下的事件文件（events.out.tfevents.*），所以无论是训练进行中还是训练结束之后，你都可以随时启动 TensorBoard 查看历史曲线。

启动 TensorBoard 查看训练曲线

标准启动步骤

要在训练过程中或训练结束后观察训练进程，请按以下步骤操作：

1. 打开一个终端（terminal）或控制台（console）窗口；
2. 切换到 ML-Agents Toolkit 安装目录（即安装了mlagentsPython 包的目录）；
3. 在命令行运行：

tensorboard --logdir results --port 6006

4. 打开浏览器，访问 http://localhost:6006。

注意事项：

• TensorBoard 的默认端口是 6006。如果 6006 端口上已有会话在运行，可以使用--port选项指定一个空闲端口来启动新会话，例如tensorboard --logdir results --port 6007。
• 如果没有指定run-id，mlagents-learn会使用默认字符串"ppo"。你可以删除results目录下的对应文件夹来清理旧的统计数据（详见 Using-Tensorboard.md）。

多 run 对比与视图设置

TensorBoard 窗口左侧可以选择要显示的训练运行（training runs），支持同时勾选多个run-id进行曲线对比。窗口还提供了曲线显示方式与平滑（smoothing）程度的调节选项，方便在噪声较大的原始曲线中观察趋势。

与 run-id 相关的 CLI 参数

为了让 TensorBoard 中的曲线清晰可辨，训练时应始终为每次训练设置唯一的run-id。相关命令行参数定义在 cli_utils.py：

因此，若你希望重新开始训练并完全清除旧曲线，可以使用--force；若希望从上次中断处继续并在 TensorBoard 中延续曲线，则使用--resume --run-id <run-id>。

ML-Agents 训练统计指标详解

ML-Agents 训练程序保存的统计指标分为环境统计（Environment Statistics）、Is Training、策略统计（Policy Statistics）、学习损失函数（Learning Loss Functions）与自博弈（Self-Play）五大类。TensorBoard 中的典型运行效果如下图所示：

环境统计（Environment Statistics）

• Environment/Lesson：绘制课程（lesson）到课程之间的进度曲线。仅在执行课程学习（curriculum training）时才有意义，对应Environment/Lesson的跨课程进度。
• Environment/Cumulative Reward：所有智能体的平均累积回合奖励（mean cumulative episode reward）。一次成功的训练中该曲线应当持续上升。
• Environment/Episode Length：环境中所有智能体的平均回合长度（mean length of each episode）。

从源码实现看，Environment/Cumulative Reward、Environment/Episode Length等由训练器与智能体处理器在回合结束时写入统计报告器，例如 agent_processor.py 中记录了Environment/Episode Length，rl_trainer.py 中记录了Environment/Cumulative Reward。而Is Training则由 rl_trainer.py 在每个汇总周期上报。

Is Training

• Is Training：布尔型指标，表示智能体当前是否正在更新模型（即训练器仍处于训练阶段而非提前停止）。

策略统计（Policy Statistics）

• Policy/Entropy（PPO；SAC）：模型决策的随机程度。成功的训练过程中该值应当缓慢下降；如果下降过快，应当增大beta超参数。
• Policy/Learning Rate（PPO；SAC）：训练算法在搜索最优策略时每次更新的步长（step size），随时间推移应当下降（PPO 默认采用linear学习率调度，在max_steps时衰减到 0；SAC 默认采用constant，见 Training-Configuration-File.md）。
• Policy/Entropy Coefficient（SAC）：熵项的相对重要性系数。该值在 SAC 中会被自动调整，以保证智能体在训练中保留一定的随机性（SAC 通过自动熵调节机制将熵系数调整到预设的目标熵，init_entcoef仅对应训练开始时熵奖励的初始值）。
• Policy/Extrinsic Reward（PPO；SAC）：每回合从环境中获得的平均累积奖励（mean cumulative reward received from the environment per-episode）。
• Policy/Value Estimate（PPO；SAC）：智能体访问过的所有状态的平均价值估计（mean value estimate for all states visited）。成功的训练过程中应当上升。
• Policy/Curiosity Reward（PPO/SAC+Curiosity）：每回合生成的平均累积内在奖励（intrinsic reward）。
• Policy/Curiosity Value Estimate（PPO/SAC+Curiosity）：智能体对好奇心奖励的价值估计。
• Policy/GAIL Reward（PPO/SAC+GAIL）：每回合生成的平均累积判别器奖励（discriminator-based reward）。
• Policy/GAIL Value Estimate（PPO/SAC+GAIL）：智能体对 GAIL 奖励的价值估计。
• Policy/GAIL Policy Estimate（PPO/SAC+GAIL）：判别器对策略生成的状态-动作对的估计。
• Policy/GAIL Expert Estimate（PPO/SAC+GAIL）：判别器对来自专家演示的状态-动作对的估计。

从源码实现看，Policy/Entropy在 agent_processor.py 中通过self._stats_reporter.add_stat("Policy/Entropy", _entropy)写入，与训练器网络输出的熵计算直接关联。

学习损失函数（Learning Loss Functions）

• Losses/Policy Loss（PPO；SAC）：策略损失函数的平均幅度，与策略（决定动作的过程）的变化程度相关。成功训练期间该值幅度应当下降。
• Losses/Value Loss（PPO；SAC）：价值函数更新的平均损失，反映模型预测各状态价值的能力。该值在智能体学习期间应当上升，一旦奖励稳定后应当下降。
• Losses/Forward Loss（PPO/SAC+Curiosity）：前向模型（forward model）损失函数的平均幅度，反映模型预测新观测编码的能力。
• Losses/Inverse Loss（PPO/SAC+Curiosity）：逆向模型（inverse model）损失函数的平均幅度，反映模型根据两个观测预测动作的能力。
• Losses/Pretraining Loss（BC）：行为克隆（Behavioral Cloning）损失的平均幅度，反映模型模仿演示数据的程度。
• Losses/GAIL Loss（GAIL）：GAIL 判别器损失的平均幅度，反映模型模仿演示数据的程度。

自博弈（Self-Play）

• Self-Play/ELO（Self-Play）：ELO 用于衡量两个玩家之间的相对技能水平。在正常的自博弈训练中，智能体的 ELO 应当稳步上升。

从源码实现看，该指标由幽灵（ghost）训练器在自博弈流程中写入：self._stats_reporter.add_stat("Self-play/ELO", self.current_elo)（见 ghost/trainer.py）。需要注意的是，在 stats.py 中控制台输出实际使用的键为Self-play/ELO，与文档标题书写略有差异，判读曲线时请以 TensorBoard 面板中实际显示的键名为准。

统计指标的写入频率与聚合

这些统计并非每一步都写入 TensorBoard。由 Training-Configuration-File.md 可知，summary_freq（默认50000，即每个汇总周期收集的经验数量）决定了训练统计的生成与显示粒度，直接控制 TensorBoard 曲线的分辨率。而 stats.py 中的StatsReporter会在每个汇总周期把同一 key 的多个值按指定的StatsAggregationMethod（AVERAGE/MOST_RECENT/SUM/HISTOGRAM）聚合为单一标量后写出并清空缓冲，直方图类指标（HISTOGRAM）还会额外写入{key}_hist曲线。

从 TensorBoard 导出数据

要将时序数据导出为 CSV 或 JSON 格式，勾选 TensorBoard 窗口左上角的 “Show data download links” 选项即可，它会为每张图表下方启用下载链接，如下图所示：

导出的 CSV/JSON 数据便于做离线分析、画图或进一步的数据处理，例如将多个 run 的奖励曲线汇总做对比研究。

从 Unity 上报自定义指标（Custom Metrics）

要从 C# 环境向 TensorBoard 上报自定义指标，可以使用StatsRecorder：

var statsRecorder = Academy.Instance.StatsRecorder; statsRecorder.Add("MyMetric", 1.0);

StatsRecorder.Add的完整签名（见 StatsRecorder.cs）为：

public void Add( string key, float value, StatAggregationMethod aggregationMethod = StatAggregationMethod.Average)

关键细节说明：

• 命名支持层级（nesting）：在指标名中使用/可以在 TensorBoard 中建立层级目录，例如"Agent/Health"与"Agent/Wallet"会被分组到Agent标签下（见 StatsRecorder.cs）。
• 聚合方式：StatAggregationMethod枚举定义在 StatsRecorder.cs 中：Average（汇总周期内取平均，默认）、MostRecent（仅上报最新值，多环境并行训练时只跟踪 worker 0 的统计以避免冲突）、Sum（汇总周期内求和）、Histogram（以直方图形式上报）。
• 写入时机：统计仅在每个summary_freq步（训练器配置）写入 TensorBoard 一次；同一周期内收到的多个同名值会按上述StatAggregationMethod聚合。
• 底层传输：StatsRecorder内部通过StatsSideChannel侧信道（SideChannel）把(key, value, aggregationMethod)三元组发送给 Python 端（见 StatsRecorder.cs）。Python 端对应的接收实现是 stats_side_channel.py，它按字符串 key、float32 值、int32 聚合方式的顺序解析消息，再经StatsReporter分发给TensorboardWriter落盘。

结合配置示例理解统计输出

以仓库自带的 config/ppo/3DBall.yaml 为例，其中summary_freq: 12000表示每收集 12000 条经验生成并显示一次统计，这会直接决定 TensorBoard 曲线的点数与平滑程度；keep_checkpoints: 5、max_steps: 500000等参数则控制模型检查点的保存策略，与results目录中的模型文件组织方式相关联。训练结束后，results/<run-id>/<behavior_name>/下既有 TensorBoard 事件文件，也有.onnx与.pt模型文件，方便你结合模型版本回溯对应训练曲线。

总结：TensorBoard 曲线的常见判读套路

通过上述指标的组合判读，你可以定位训练中“探索不足（entropy 崩坍）”“学习率过大（reward 震荡）”“价值估计不准（value loss 不收敛）”等典型问题，并据此调整 Training-Configuration-File.md 中的对应超参数。若需要更深度的底层机制，可继续阅读 stats.py 中的StatsReporter与TensorboardWriter实现，或查看 test_stats.py 中的单元测试以理解统计聚合与写出的边界行为。

【免费下载链接】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