verl RL-Insight是 verl 官方推出的强化学习训练实时监控工具，它把训练器标量指标、vLLM/SGLang 推理引擎指标、TransferQueue 指标、RL 状态时间线和硬件指标统一汇聚到 Grafana 面板，帮助你在多机大规模 RL 训练中实现"一眼看全局、快速定位问题"，是高效调试大规模强化学习作业的关键利器。

为什么大规模 RL 训练需要实时监控

强化学习后训练与纯监督学习不同：一个训练作业同时包含模型训练（actor/critic）、推理采样（rollout）、奖励计算、**数据传输（TransferQueue）**等多个子系统，分布在一堆 GPU/NPU 上。当奖励不涨、吞吐下降或训练崩溃时，只看终端日志远远不够。

RL-Insight 让你在一个监控视图里回答这些问题：

💡 官方在 docs/advance/rl_insight.md 中提供了完整的 RL-Insight 使用文档，本文是对该流程的提炼与补充。

架构速览：4 个组件组成监控链路

图：verl 强化学习 Agent 场景示例——rollout 阶段 Agent 实际生成的 Web 页面，其质量由奖励模型打分，而 RL-Insight 面板上正能看到这类生成过程对应的奖励与引擎指标

RL-Insight 服务端由几个开源监控组件拼装而成，默认端口分工如下：

verl 侧的接入逻辑实现在 verl/utils/tracking.py 的RLInsightLogger中：当trainer.logger里出现rl_insight时，训练入口 verl/trainer/main_ppo.py 会自动设置环境变量VERL_RL_INSIGHT_ENABLE=1，并初始化 RL-Insight 客户端，无需修改任何训练代码。

快速上手：三步开启强化学习训练实时监控

第一步：安装并启动 RL-Insight 服务

在部署监控服务的机器上安装（优先源码安装最新版）：

pip install "rl-insight>=0.2.0"

然后一键安装并启动监控服务：

rl-insight server install # 自动下载 Prometheus / Tempo / Grafana 到 ~/.rl-insight/services rl-insight server start # 打印服务器 IP、Grafana 地址与各端点

⚠️ 离线或内网集群无法访问下载源时，可先在联网机器下载三个组件包，放到同一目录后执行rl-insight server install --local-archive /path/to/archives完成离线安装。

第二步：在 verl 中启用 RL-Insight

1. 设置服务端地址（<server-ip>为server start时打印的 IP，需可被训练进程访问）：

export RL_INSIGHT_SERVER_URL="http://<server-ip>:18080"

多机 Ray 集群请把该变量写入运行时环境文件 verl/trainer/runtime_env.yaml 的env_vars中，使其传播到每个节点：

env_vars: RL_INSIGHT_SERVER_URL: "http://<server-ip>:18080"

2. 在启动命令中把rl_insight加入 logger，例如：

python3 -m verl.trainer.main_ppo \ trainer.logger='["console","rl_insight"]' \ trainer.project_name=verl \ trainer.experiment_name=ppo_rl_insight \ ...

训练器标量指标（奖励、loss、吞吐等）从此自动上报，无需额外配置。

第三步：打开 Grafana 面板查看训练指标

1. 访问http://<server-ip>:3000，使用默认账号admin/admin登录；
2. 左侧导航进入Dashboards，打开RL-Insight目录；
3. 按运行配置选择面板：
   • vLLM rollout →verl_trainer_v1_with_vllm_engine
   • SGLang rollout →verl_trainer_v1_with_sglang_engine
4. 训练运行期间把时间范围设为 Last 5/15 minutes，即可看到实时曲线。

面板内容包括训练指标、各 rollout 副本的推理引擎指标、TransferQueue 指标（如启用）以及 rollout 状态时间线（同步/异步模式各有一套视图）。

进阶：监控 Rollout 引擎与 TransferQueue 指标

默认只上报 trainer 标量指标。要看推理引擎级的细粒度指标（如每个 replica 的吞吐、KV cache、请求延迟）和 TransferQueue 指标，需要打开两个开关：

python3 -m verl.trainer.main_ppo \ trainer.logger='["console","rl_insight"]' \ actor_rollout_ref.rollout.disable_log_stats=False \ transfer_queue.metrics.enabled=True \ ...

• actor_rollout_ref.rollout.disable_log_stats=False：允许 rollout 统计上报，vLLM/SGLang 副本启动后 verl 会把这些/metrics端点注册给 RL-Insight；
• transfer_queue.metrics.enabled=True：当启用 TransferQueue 时暴露其指标端点。

生成路径（vLLM 与 SGLang rollout worker）也会被自动包裹 RL-Insight 状态 trace，从而形成"RL 状态时间线"，帮助你判断 rollout 生成在整体 step 中的耗时占比。

此外，如果你已有 Grafana/Prometheus 环境，verl 也提供不依赖 RL-Insight 的原生方案——docs/advance/grafana_prometheus.md 详细讲解了如何自动改写 Prometheus 配置、抓取 rollout 服务器指标，其中给出了 Qwen235B 长尾 rollout 与异步训练资源空闲的真实案例，非常适合作为性能优化的入门阅读。

高效调试：从指标异常到根因定位

排查清单：面板没数据怎么办

经典案例：用rollout_probs_diff_mean定位训推精度问题

RL 训练中最隐蔽的问题之一是训练与推理引擎的精度不一致，典型表现是actor/grad_norm持续上升。verl 提供了内置的调试指标：设置actor_rollout_ref.rollout.calculate_log_probs=True后，verl/utils/debug/metrics.py 中的calculate_debug_metrics会对比 rollout 与 actor 的 log prob 差异，产出以下指标（可在 RL-Insight 面板中直接观察趋势）：

• training/rollout_probs_diff_mean/_max/_std：差异均值、最大值、标准差
• training/rollout_actor_probs_pearson_corr：概率序列的皮尔逊相关系数

判读标准（参考 docs/faq/faq.rst）：

• ✅ 正常：rollout_probs_diff_mean低于0.005
• ❌ 异常：持续高于0.01，说明推理引擎存在精度问题，可尝试+actor_rollout_ref.rollout.engine_kwargs.vllm.disable_cascade_attn=True规避

这正是"实时监控 → 发现异常 → 定位根因"闭环的典型场景：先看 RL-Insight 面板发现 diff 指标抬升，再打开计算对比定位到具体引擎版本或参数。

需要更细粒度剖析？用 verl Profiler System

实时监控解决"发生了什么"，剖析器解决"为什么这么慢"。verl 内置了统一的 Profiler 框架（架构见 docs/perf/verl_profiler_system.md），通过DistProfiler（verl/utils/profiler/profile.py）支持按 role、按 rank、按 step 选择性地启用多种工具：

推荐的调试节奏：先用 RL-Insight 面板锁定异常的时间窗与子系统（rollout？训练？硬件？）→ 再用 Profiler 对目标 step 和 rank 做深度剖析 → 必要时用rollout_probs_diff系列指标验证精度。三层配合，基本覆盖大规模 RL 训练的全部调试路径。

小结

• 🔍一个入口：trainer.logger='["console","rl_insight"]'+ 环境变量RL_INSIGHT_SERVER_URL，零代码改动接入监控；
• 📊五个维度：训练指标、推理引擎指标、TransferQueue 指标、RL 状态时间线、硬件指标统一进 Grafana；
• 🛠️调试闭环：面板发现异常 → 内置 diff 指标验证精度 → Profiler 深度剖析，从"看到问题"到"定位根因"一气呵成。

核心文档索引：

• RL-Insight 完整指南：docs/advance/rl_insight.md
• Grafana + Prometheus 原生方案：docs/advance/grafana_prometheus.md
• Profiler 体系说明：docs/perf/verl_profiler_system.md
• 训推精度问题 FAQ：docs/faq/faq.rst
• 监控后端实现：verl/utils/tracking.py、调试指标实现：verl/utils/debug/metrics.py