强化学习任务全观测

查看全局训练进度

在任务详情页，单击RL监控 > 训练进度，可查看全局的训练进度。训练进度用于判断任务是否正常推进，并定位单个Step的耗时瓶颈。页面汇总当前Step、总Step、累计运行时长、平均Step耗时及预计剩余时间。阶段时间轴按实际执行链路展示Rollout、Reward、策略更新、参数同步、验证与Checkpoint的状态和耗时。

分析样本流转

在任务详情页，单击RL监控 > 流转分析，可查看样本流转。样本流转分析用于判断Rollout生产与Trainer消费是否匹配。页面汇总轨迹总数、已训练数、采样入批数、在途数量、端到端耗时及Buffer停留时间，并通过流转图展示轨迹从生成到训练完成的转化情况。

该页面同时展示阶段耗时分布，阶段耗时分布以P50、P90、P99标识慢样本，支持下钻至Trace详情，帮助定位轨迹积压、流失或训练等待等问题。

下钻分析样本与轨迹

在样本流转分析页面选择目标慢样本，进入Trace详情页，下钻分析样本与轨迹情况。

里程碑链路按执行顺序展示轨迹生成、Worker下发、Agent执行、Reward打分、采样入批及训练更新等关键节点，并标记各阶段耗时。结合Reward、交互轮数、Token分布和阶段时间轴，可快速识别长耗时或异常阶段。

Trace记录以事件明细还原轨迹的完整执行链路，展示事件时间、所属阶段、交互轮、源模块、目标模块及事件详情。您可以关联查看模型生成、工具调用、环境执行、Reward计算和训练更新等事件，定位跨组件调用中的延迟、失败或异常中断位置。

在Trajectory详情中，可查看该轨迹的Reward、交互轮数、总耗时、关联训练Step和提交时间。展开单个交互轮后，可进一步查看模型推理与环境执行耗时、Token用量、模型输出、工具调用及环境反馈。该视图用于复盘Agent的决策过程，分析低Reward、工具执行失败或长程任务不收敛等问题。

步骤一：集成RL Trace埋点

PAI-DLC提供两种RL Trace埋点方式，请根据使用的训练框架选择。

方式一：通过patch接入（强烈推荐）

如果您使用Verl框架，强烈建议通过patch接入。一条git apply命令即可完成Progress、Sample-flow和Trajectory三类埋点，格式已按规范对齐，无需改动框架代码。

单击下载patch文件，verl-tracing-v1-squash-eeca5b74.patch

进入Verl目录，执行如下命令。

git apply verl-tracing-v1-squash-eeca5b74.patch

方式二：手动添加埋点

如果patch不支持您的框架版本，按照下文埋点数据规范，在Verl v1代码中集成Progress、Sample-flow和Trajectory埋点，确保训练进程能够生成三类观测数据。

步骤二：启动XFuse Agent

在任务启动脚本中设置RL采集场景，并启动XFuse Agent。

export XFUSE_AGENT_SCENARIO="pai-rl"
bash /etc/sysconfig/xfuse-agent/start.sh

步骤三：配置Trace输出目录

设置VERL_TRACE_DIR环境变量。该变量控制Sample-flow、Trajectory和Progress三类数据的落盘路径。

export VERL_TRACE_DIR=<trace_dir>

<trace_dir>为Trace输出目录，例如挂载到训练容器中的共享存储路径。未设置该变量时，不会生成Sample-flow CSV、Trajectory JSONL和Progress文件，Progress信息仍会输出到标准输出。

Trace文件按照以下目录组织：

<VERL_TRACE_DIR>/
├── progress/
├── sample/
└── trajectory/

步骤四：启动训练任务

按照常规方式提交DLC训练任务。将XFuse Agent启动命令和VERL_TRACE_DIR环境变量加入任务启动脚本，并确保所有训练节点均生效。

步骤五：验证Trace数据

训练开始后，执行以下命令检查Trace目录：

find <trace_dir> -maxdepth 2 -type f

正常情况下，目录中包含以下文件：

<trace_dir>/sample/<hostname>-pid<pid>.csv
<trace_dir>/trajectory/trajectory_<pid>_<timestamp>.jsonl
<trace_dir>/progress/<YYYYMMDD-HH>.log

如未生成文件，请依次检查：

1. 所有Worker进程均已接收VERL_TRACE_DIR。

2. 训练进程具有目标目录的写入权限。

3. RL Trace埋点已加载，并与当前Verl v1代码兼容。

4. 多机训练的各节点均可访问对应输出路径。

步骤六：查看观测结果

进入DLC并打开目标训练任务详情页面，查看训练进度、训练阶段、轨迹流转和Stage分布。发现异常阶段后，可在阶段耗时分布中选择最慢样本，并下钻至轨迹详情和Trajectory详情。

推荐的排查路径如下：

训练进度异常
  └─> 定位异常Step和训练阶段
      └─> 检查轨迹流转与Stage分布
          └─> 比较阶段耗时P50/P90/P99/Max
              └─> 打开最慢样本Trace
                  └─> 下钻逐Turn推理、工具和环境耗时

Sample-flow数据

Sample-flow使用CSV格式记录样本或轨迹的状态迁移事件。文件不包含表头，采集器需要按以下顺序配置列名：

job_id,cat,sample_id,sample_status,timestamp,content

建议覆盖以下阶段：

示例如下：

dlc-job-example,sample,prompt-001/sample,RUNNING,1787215029000,from=DataLoader|to=PPOTrainerV1|stage=DATA_PREPROCESS|global_step=1|detail=uid_generated
dlc-job-example,sample,prompt-001/0,RUNNING,1787215030700,from=RewardLoopWorker|to=AgentLoopWorker|stage=ROLLOUT_REWARD|global_step=1|detail=reward_score_computed_score=1.0
dlc-job-example,sample,prompt-001/0,COMPLETE,1787215060000,from=ActorRolloutWorker|to=PPOTrainerV1|stage=TRAIN_UPDATE|global_step=1|detail=actor_parameters_updated
dlc-job-example,sample,*/sample,RUNNING,1787215061000,from=CheckpointEngineManager|to=RolloutReplica|stage=SYNC_PARAMS|global_step=1|detail=weights_synced_global_step=1

Trajectory数据

Trajectory使用JSONL格式记录轨迹明细，每行对应一条已完成轨迹。顶层仅保留索引字段，完整轨迹序列化为raw_message JSON字符串：

{
  "prompt_uid": "<uid>",
  "sample_index": 0,
  "raw_message": "<trajectory_json_string>"
}

解析raw_message后，可获得以下轨迹字段：

turns[]中每个元素表示一轮“模型生成Action → 工具或环境执行 → 返回Observation”，主要字段如下：

示例如下。raw_message在实际JSONL文件中以转义后的单行JSON字符串保存：

{"prompt_uid":"prompt-001","sample_index":0,"raw_message":"{\"request_id\":\"0\",\"n_samples\":4,\"global_step\":1,\"created_at_ts\":1787215072.088,\"completed_at_ts\":1787215073.421,\"total_time_ms\":1332.52,\"turns\":[{\"turn_index\":0,\"prompt_token_count\":87,\"completion_text\":\"Call the search tool.\",\"completion_token_count\":6,\"finish_reason\":\"stop\",\"observation_text\":\"Search completed.\",\"start_ts\":1787215072.120,\"end_ts\":1787215073.321,\"turn_total_time_ms\":1201.45,\"completion_time_ms\":891.30,\"observation_time_ms\":310.15,\"sglang_queue_time_ms\":12.40,\"sglang_ttft_ms\":35.20,\"sglang_prefill_ms\":18.60,\"sglang_decode_time_ms\":825.10,\"template_overhead_tokens\":null,\"template_overhead_text\":null}],\"initial_prompt_text\":\"Complete the task with available tools.\",\"agent_metrics\":{\"generate_sequences\":0.891,\"tool_calls\":0.310,\"reward_score\":1.0,\"num_preempted\":0}}"}

Progress数据

Progress使用按小时轮转的文本日志记录训练控制流，每行记录一条完整事件，不添加时间、日志级别等结构化前缀。文件路径为<VERL_TRACE_DIR>/progress/<YYYYMMDD-HH>.log，同一内容同时输出到标准输出。

Progress日志包括以下行类型：

阶段名称包括generation、compute reward、compute log prob、compute ref log prob、compute values、compute adv、update actor、save checkpoint、eval、record metrics和sync params。未启用的阶段无需输出。其中，generation仅用于Colocate或Sync模式。

separate_async模式示例如下：

Total training steps: 100
==================== Step 1 ====================
Step 1 rollout started
Trainer: try to load global batch@1, chunk[0/0] from replay_queue
Trainer: successfully load global batch@1, chunk[0/0] from replay_queue
Step 1 rollout finished
Task prompt-001/0 is completed, score=1.0 status=Finished
disagg: start compute reward
disagg: end compute reward
disagg: start compute log prob
disagg: end compute log prob
disagg: start compute adv
disagg: end compute adv
Step 1 train started
disagg: start update actor
disagg: end update actor
Step 1 train finished
disagg: start sync params
disagg: end sync params

separate_async模式下，训练阶段的开始和结束日志带有disagg:前缀，Batch加载日志使用固定的Trainer:前缀，Step窗口和轨迹完成日志不带上述前缀。该模式不输出generation阶段和生成吞吐。Colocate或Sync模式的阶段日志不带disagg:前缀，使用generation阶段记录ReplayBuffer取样窗口，并可在Step标识中包含Epoch和已消费Batch数。