数据规格与格式说明

本文说明 RL-Insight 当前支持各种数据规格的目录布局和数据要求，便于采集与对接。

流水线在校验阶段会使用 rl_insight.data.DataChecker 注册的规则；通用规则见 rl_insight/data/rules.py，VeRL 日志规则见 rl_insight/data/verl_log_rules.py。具体校验项以代码为准，部分规则可能尚未接入 DataChecker.rules，文档仅描述数据侧约定。

1. Torch Profiler 数据

1.1 目录结构

<profile-data-path>/
└── <role>/
    └── prof_*.json.gz

参考：./rl-insight/data/torch_data

1.2 文件内容要点

  • 解压/解析后的 JSON 需包含 distributedInfo（如 rank）与 traceEvents（Chrome Trace 风格事件列表）。

  • 事件中用于绘制的区间一般为 ph: "X"，并带有 ts、dur 等字段（时间单位以文件内约定为准）。

1.3 内容示例（节选）

完整文件体积较大，此处仅保留与解析相关的关键字段示意：

{
  "schemaVersion": 1,
  "distributedInfo": {
    "backend": "cpu:gloo,cuda:nccl",
    "rank": 0,
    "world_size": 2
  },
  "traceEvents": [
    {
      "ph": "X",
      "name": "cudaMemGetInfo",
      "pid": 369418,
      "tid": 1722878400,
      "ts": 4541015316353.111,
      "dur": 10083720.552,
      "args": {}
    },
    {
      "name": "process_name",
      "ph": "M",
      "pid": 369418,
      "tid": 0,
      "args": { "name": "ray::WorkerDict.actor_rollout_compute_log_prob" }
    }
  ]
}

2. MSTX（Ascend）Profiling 数据

2.1 目录结构

<profile-data-path>/
└── <role>/
    └── *_ascend_pt/
        ├── profiler_info_*.json
        └── ASCEND_PROFILER_OUTPUT/
            └── trace_view.json

参考：./rl-insight/data/mstx_data

2.2 trace_view.json 要点

  • 为事件数组；解析侧会识别元数据事件（如 ph: "M"）以及 name 为 Overlap Analysis 的进程上下文，并消费其中的 ph: "X" 等区间事件。

  • 区间事件通常带有 ts、dur（具体类型以采集导出为准）。

2.3 内容示例（节选）

[
  {
    "name": "process_name",
    "pid": 3550586784,
    "tid": 0,
    "ph": "M",
    "args": { "name": "Overlap Analysis" }
  },
  {
    "name": "Computing",
    "pid": 3550586784,
    "tid": 2,
    "ts": "1773285899055563.748",
    "dur": 53.301,
    "ph": "X",
    "args": {}
  },
]

2.4 输入数据要求

MSTX 输入当前包含三类检查：

  • PathExistsRule
    检查输入对象是否为目录路径，且目录存在

  • MstxJsonFileExistsRule
    检查 *_ascend_pt/ASCEND_PROFILER_OUTPUT/trace_view.json 是否存在，并检查 profiler_info_*.json 是否存在

  • MstxJsonFieldValidRule
    检查相关 JSON 文件是否非空，并验证关键字段是否齐全

其中：

  • trace_view.json 要求事件包含 ph、name、pid、tid

  • profiler_info_*.json 要求包含 config、start_info、end_info、torch_npu_version、cann_version、rank_id

3. NVTX Profiling 数据

3.1 目录结构

<profile-data-path>/
  ├── worker_process_*.*.jsonl
  └── worker_process_*.*.jsonl

3.2 worker_process_..jsonl 要点

  • jsonl文件包括以color开头的条目，条目中的eventType等于60，且包含start、end、textId字段

  • jsonl文件需有包括全局时间信息的条目，该条目中有startTime信息

  • jsonl文件需有包含RANK信息的条目，对应的，该条目的value中有RANK信息

3.3 内容示例（节选）

{"id":38,"table":"StringIds","value":"compute_log_prob"}
{"duration":21068815496,"globalVid":281474976710656,"startTime":6589107243593703,"stopTime":6589128312409199,"table":"ANALYSIS_DETAILS"}
{"color":255,"domainId":0,"end":21019655556,"eventType":60,"globalTid":282747880941798,"rangeId":1,"start":20979323,"table":"NVTX_EVENTS","textId":38}
{"name":"PROCESS_0:ENVIRONMENT_VARIABLE","table":"META_DATA_CAPTURE","value":"RANK=\"0\""}

4. 输出生成summary_event数据

4.1 格式示例

<summary-event-data-path>/
└── summary_event_dataframe_sample.json

参考：./rl-insight/data/summary_event_data

解析后汇总生成的数据文件 summary_event_dataframe_sample.json，内容必须包含”role”, “name”, “rank_id”, “start_time_ms”, “end_time_ms”字段，文件内容示例：

[
  {
    "name":"agent_loop_rollout_replica_0",
    "role":"agent_loop_rollout_replica_0",
    "domain":"default",
    "start_time_ms":1773285888698.7263183594,
    "end_time_ms":1773285890928.7919921875,
    "duration_ms":2230.06575,
    "rank_id":1,
    "tid":3555733409
  },
  {
    "name":"agent_loop_rollout_replica_0",
    "role":"agent_loop_rollout_replica_0",
    "domain":"default",
    "start_time_ms":1773285888698.7546386719,
    "end_time_ms":1773285890928.1730957031,
    "duration_ms":2229.4185,
    "rank_id":0,
    "tid":3555714976
  },
]

4.2 输出数据校验

输出侧校验的目标，是保证 parser 的产出能够被 visualizer 正常消费。

当前 SUMMARY_EVENT 类型使用 ParserOutputValidatorRule 进行检查，重点包括：

  • 输出必须是 pandas.DataFrame

  • DataFrame 不能为空

  • 必须包含关键字段列：

    • role

    • name

    • rank_id

    • start_time_ms

    • end_time_ms

5. VeRL 训练日志（可选校验）

DataEnum.VERL_LOG 对 单个 VeRL 训练 .log 文件做存在性与关键指标子串校验（例如 DataChecker 或 tests/data/check_verl_log.py）。路径必须是文件，不能是目录。

5.1 校验规则（以代码为准）

  1. 存在与路径（VerlLogExistRule）：扩展名为 .log，文件非空，且能被识别为 VeRL 日志：文件名中含 verl（不区分大小写），或文件开头约 64KiB 内容中含 verl。

  2. 关键子串（VerlLogKeyParamsRule）：日志正文（读取至多约 2MiB，不区分大小写）须同时包含以下子串，定义见 rl_insight/data/verl_log_rules.py 中 DEFAULT_REQUIRED_KEYWORDS：

    • verl

    • actor/loss

    • critic/score/mean

    • critic/rewards/mean

    • response_length/mean

    • actor/grad_norm

    • training/global_step

    • training/epoch

    • actor/lr

    • actor/entropy

    • Training Progress:（tqdm 类进度条前缀，完整日志中常见）

    若仅存在 step: 而日志未打印 training/global_step / training/epoch 字面量，将不通过。可按业务在代码中传入自定义 required_keywords 放宽或收紧。

5.2 data/verl_data/ 示例数据

仓库 data/verl_data/ 下提供：

  • good_minimal_verl.log：体量很小的合成日志，覆盖当前必填子串，推荐用于脚本/文档中的快速校验示例。

  • 负面样例（用于手工跑 check_verl_log.py 或自测规则；说明文字已避免误包含上述关键字）：

文件

典型失败原因

bad_exist_empty_verl.log

空文件

bad_exist_unbranded.log

无 VeRL 标识（文件名与正文均不含 verl）

bad_keys_startup_only_verl.log

仅启动信息，缺指标类关键字

bad_keys_five_legacy_metrics_verl.log

仅有部分指标，缺全局步进/epoch/lr/entropy 等

bad_keys_no_training_step_tokens_verl.log

有 step= 但未出现 training/global_step、training/epoch 子串

bad_keys_no_entropy_verl.log

缺 actor/entropy

*.log 若被根目录 .gitignore 忽略，需本地自备或使用 git add -f 将约定路径纳入版本库。

5.3 命令示例

python tests/data/check_verl_log.py data/verl_data/good_minimal_verl.log

5. GMM 专家负载dump数据

GMM 热力图输入类型为 DataEnum.GMM_DATA（CLI：--input-type gmm_data、--profiler-type gmm）。路径约定、参数与示意图见 docs/overview/gmm_heatmap_quickstart.md。本节补充数据侧目录与文件格式说明。

5.1 目录结构

解析器会递归查找文件名后缀为 group_list.pt 的文件，且必须位于名为 dump_tensor_data 的目录下；路径中需能匹配 step_{整数} 与 rank{整数}，并与正式采集层级一致（与常见训练 dump 目录相同，例如本地完整数据可放在 gmm_dump/ 等任意根目录名之下，只要子目录层级符合下述约定即可。

<gmm-root>/
├── step_1/                                # 训练步骤
│   ├── actor_compute_log_prob/            # 角色/阶段（文件夹名即 role）
│   │   └── rank0/                         # Rank ID
│   │       └── dump_tensor_data/          # 张量 dump 目录（必填层级名）
│   │           ├── NPU.npu_grouped_matmul.0.forward.kwargs.group_list.pt
│   │           ├── NPU.npu_grouped_matmul.1.forward.kwargs.group_list.pt
│   │           └── ...
│   └── actor_update/
│       └── rank0/
│           └── dump_tensor_data/
│               ├── NPU.npu_grouped_matmul.0.forward.kwargs.group_list.pt
│               └── ...
├── step_2/
└── ...

参考（仓库内最小可解析示例，体量极小，便于测试与文档对照）：../../data/gmm_data

5.2 group_list.pt 文件内容

  • 文件为 PyTorch torch.save 序列化对象；解析侧优先以 weights_only=True 加载，需为 torch.Tensor 或 numpy.ndarray，语义为一维 expert 负载：reshape(-1) 后第 i 个元素对应 expert_index == i 分到该 expert 的 token 数（非负整数）。

  • 文件名需能被解析器识别为 GMM 算子序号，典型 pattern 为
    NPU.npu_grouped_matmul.<op_index>.forward.kwargs.group_list.pt
    其中 <op_index> 会映射为汇总表中的 stage（层/算子序号）。

5.3 输入数据校验

GmmDataRule（见 rl_insight/data/rules.py）要求：

  • 输入为已存在的目录路径；

  • 其下至少存在一个位于 dump_tensor_data 路径段中的 *group_list.pt 文件。