data-juicer 评测结果记录器:用 wandb 可视化模型训练指标与构建排行榜实战指南

原创2026-10-05 11:20:161,987 阅读
文章标签:数据工程大模型人工智能数据清洗数据增强数据分析多模态RAG

data-juicer 评测结果记录器:用 wandb 可视化模型训练指标与构建排行榜实战指南

本指南以 data-juicer 仓库中的 Evaluation Results Recorder(README)为核心,讲解如何通过 wandb_writer.py 把大模型评测结果(目前支持 HELM 评测输出)写入 Weights & Biases(wandb),在训练过程中持续跟踪指标变化,并将多个模型汇聚成可比较的排行榜。读完本文,你将掌握 wandb_writer.py 的两种数据来源配置(HELM 输出目录解析、配置文件直读)、排行榜构建方法,以及其底层写入逻辑,能直接用于自己的模型训练与评测流程。

一、功能总览:记录什么、能看到什么

wandb_writer.py(源码位于 tools/evaluator/recorder/wandb_writer.py)是 data-juicer Auto Evaluation Toolkit(tools/evaluator/README.md)的配套结果记录工具。evaluator.py 负责自动用 HELM 或 OpenAI API 评测模型,而 wandb_writer.py 负责把评测结果沉淀到 wandb,提供两类核心能力:

  • 可视化训练过程中评测指标的变化:按迭代(iteration)把每个基准(benchmark)的指标逐点写入 wandb,形成指标随训练步数变化的曲线,用于监控模型在训练中期的表现起伏;
  • 制作排行榜(leaderboard):把同一 wandb 项目下多个模型的评测结果汇总,做归一化聚合后生成对比条形图,用于横向比较不同模型。

下图分别为指标变化曲线与排行榜对比图(来自仓库 docs/imgs/eval-02.png 与 docs/imgs/eval-01.png):

训练过程中各评测指标随步数的变化曲线

不同模型在多个基准指标上的得分对比(排行榜)

其中 eval-02.png 展示的是 mmlu.EM、boolq.EM、narrative_qa.F1、hellaswag.EM 四个指标随训练步数(Step)推进的波动曲线;eval-01.png 则是多个模型在这四个指标上的条形对比。

二、快速上手:命令行用法

使用方式非常简单,一条命令即可完成评测结果的写入:

python wandb_writer.py --config <config_file> [--print-only]

若从仓库根目录运行,需带上完整相对路径:

python tools/evaluator/recorder/wandb_writer.py --config tools/evaluator/recorder/config/mymodel_example.yaml

两个核心参数说明:

参数 含义
config_file yaml 配置文件路径,内容见下文「配置详解」;仓库在 tools/evaluator/recorder/config 下提供了三种场景的示例文件
--print-only 仅把解析出的结果打印到命令行,不执行写 wandb 操作,用于调试与本地验证

值得补充的是,源码 get_args() 中还定义了一个 README 未提及的 --summary-only 开关(见 wandb_writer.py):开启后跳过逐场景的 detail 写入,仅将汇总(summary)结果写入 wandb。三种场景的示例配置文件分别为:

使用前提:本地已安装 wandb 库(wandb_writer.py 顶部 import wandb)并完成登录认证;若使用自建 wandb 实例,则在 base_url 中填写实例地址,源码中的 wandb.init 与 wandb.Api 都会携带该 base_url(见 wandb_writer.py 与 wandb_writer.py)。

三、配置详解:通用骨架

所有配置文件都包含两个通用顶层字段,其余字段按实际场景追加:

project: <str>   # wandb 项目名
base_url: <str>  # wandb 实例 url
# other specific configuration items
  • project:结果写入的 wandb 项目名,同一项目下才能跨模型生成排行榜;
  • base_url:wandb 实例地址,使用官方云端时可留空(源码中 base_url 默认为 None)。

其余字段组织在 evals 列表(每个元素是一次评测记录任务,eval_type 目前仅支持 helm)和可选的 leaderboard 顶层字段中。main() 的流程是:先遍历 evals 逐个写入,若顶层存在 leaderboard: True 再执行排行榜生成(见 wandb_writer.py);遇到非 helm 的 eval_type 会抛出 NotImplementedError。

四、场景一:从 HELM 输出目录解析评测结果

该模式从 HELM 评测输出目录中提取指标并写入 wandb,适合与 evaluator.py 自动评测链路衔接。完整配置如下:

# general configurations
project: <str>
base_url: <str>

evals:  # evaluations to record
  - eval_type: helm    # 目前仅支持 helm
    model_name: <str>  # 模型名字
    source: helm       # 使用 helm 模式:从 helm 输出目录解析
    helm_output_dir: <your helm output dir path>
    helm_suite_name: <your helm suite name>
    token_per_iteration: <tokens per iteration in billions>
    benchmarks:  # 需要记录到 wandb 的评测指标,如下为一些样例
      - name: mmlu
        metrics:
          - EM
      - name: boolq
        metrics:
          - EM
      - name: narrative_qa
        metrics:
          - F1
      - name: hellaswag
        metrics:
          - EM
      - ...

各字段含义:

字段 说明
eval_type 固定为 helm(当前唯一支持的类型)
model_name 模型名称,会作为 wandb run 的 group 与 run id 的一部分
source helm 或 file,默认值为 helm(源码见 wandb_writer.py)
helm_output_dir HELM 输出根目录
helm_suite_name HELM suite 名称,用于定位 runs/<suite_name>/groups/ 下的评测 JSON 文件
token_per_iteration 每次迭代消耗的 token 数量(单位:十亿 B),会写入 run 的 config,供排行榜横轴换算
benchmarks 需要记录的基准及其指标;不提供时自动使用 HELM 的 16 组核心指标(见下文)
default_iteration 可选字段,当某条评测结果无法从行首解析出迭代号时使用的兜底迭代值,默认 0(源码见 wandb_writer.py)

默认的 16 组核心指标

若省略 benchmarks,代码会自动使用 DEFAULT_HELM_BENCHMARKS(源码定义见 wandb_writer.py):

mmlu.EM, raft.EM, imdb.EM, truthful_qa.EM, summarization_cnndm.ROUGE-2,
summarization_xsum.ROUGE-2, boolq.EM, msmarco_trec.NDCG@10,
msmarco_regular.RR@10, narrative_qa.F1, natural_qa_closedbook.F1,
natural_qa_openbook_longans.F1, quac.F1, civil_comments.EM,
hellaswag.EM, openbookqa.EM

需要说明:README 正文中列出的默认指标为 15 项(未含 quac.F1),而源码 DEFAULT_HELM_BENCHMARKS / DEFAULT_HELM_METRICS 实际定义了包含 quac.F1 在内的 16 项,使用时以源码为准;配置文件中显式给出 benchmarks 即可完全自定义。

底层解析逻辑

parse_scenario()(见 wandb_writer.py)的具体流程为:

  1. 打开 {helm_output_dir}/runs/{suite_name}/groups/{scenario_name}.json;
  2. 遍历 JSON 中的每个 subject,从其 header 中匹配 scenario_metrics(即配置的 metrics)对应的列下标;
  3. 逐行读取 rows,尝试从首列值中提取迭代号:优先按 _ 分割取最后一段,再尝试按 / 分割取最后一段,均失败则回退到 default_iteration;
  4. 以 iteration -> scenario -> subject -> metric 的四级结构组装结果。

这意味着 HELM 输出目录中必须存在以 {suite_name}/groups/{scenario_name}.json 组织的文件,且行首列需携带可解析的迭代信息(如 iter_1000 或路径式 xxx/1000)。示例配置见 config/mymodel_example.yaml。

五、场景二:从配置文件直接读取评测结果

当评测结果已经存在(例如来自历史实验记录),可以直接在配置文件中写死指标分数,让工具跳过文件解析直接写入 wandb。该模式还要求提供该模型训练时使用的 token 数量(单位:B)。完整配置如下:

# general configurations
project: <str>
base_url: <str>

evals:  # evaluations to record
  - eval_type: helm
    model_name: llama-7B  # 模型名字
    source: file          # 使用 file 模式:直接从配置文件提取评测结果
    token_num: 1000       # 该模型训练时使用的 token 数量(单位:B)
    eval_result:          # 需要被记录的评测结果
      mmlu:
        EM: 0.345
      boolq:
        EM: 0.751
      narrative_qa:
        F1: 0.524
      hellaswag:
        EM: 0.747
      ...

关键字段:

字段 说明
source 固定为 file,源码据此走 parse_from_file 分支
token_num 训练使用的 token 总量(单位:B),写入 run config,排行榜用它作为横轴刻度
eval_result 双层嵌套结构:基准名 -> 指标名 -> 分数

该模式下,代码直接调用 write_wandb("summary", {default_iteration: eval_result}, "summary")(见 wandb_writer.py),即把整份 eval_result 作为一次写入内容;由于不解析迭代号,通常配合 default_iteration 指定迭代位置。仓库提供了完整的 16 指标示例 config/llama_example.yaml,可直接作为模板替换数值。

六、场景三:构建排行榜

排行榜用于横向比较同一 wandb 项目下多个模型。配置如下:

# general configurations
project: <str>
base_url: <str>

leaderboard: True
leaderboard_metrics:  # 排行榜中需要统计的指标
  - mmlu.EM
  - boolq.EM
  - quac.F1
  - hellaswag.EM
  - ...
excluded_models:   # 不参与排行榜的模型名称
  - <model to exclude>
  - ...

字段说明:

字段 说明
leaderboard 置 True 开启排行榜生成
leaderboard_metrics 参与排名的指标列表,格式为 基准.指标;省略时默认使用与前述相同的 16 组核心指标(DEFAULT_HELM_METRICS)
excluded_models 从排行榜中排除的模型名(源码按 excluded_models 键读取,见 wandb_writer.py)

排行榜的生成算法(源码级解读)

make_leaderboard()(见 wandb_writer.py)的核心步骤:

  1. 通过 wandb.Api 拉取该项目下所有带 summary 标签的 run,跳过 group == "leaderboard" 以及出现在 excluded_models 中的 run;
  2. 用 scan_history 按 _step 与各 leaderboard_metrics 取历史,把每个 run 在每步的指标得分按 指标 -> 模型 -> 迭代 组织;
  3. 对每个指标做 min-max 归一化:score' = (score - min) / (max - min)(cal_score(),见 wandb_writer.py),把不同量纲的指标压缩到 0~1 区间;
  4. 按模型、按迭代把所有指标的归一化得分求和得到综合分;
  5. 用 wandb.Table 以 ["model", "token_num", "score"] 三列组织数据,横轴取 run config 中的 token_num;若未提供则用 迭代号 * token_per_iteration 换算;两者都没有则为空;
  6. 通过 wandb.plot.bar 记录 benchmark_score 条形图,run 的 group/name 均为 leaderboard。

因此排行榜的横轴刻度代表训练消耗的 token 数(便于对比不同训练进度的模型),纵轴为多指标归一化后的综合得分。README 中文版提示"仅有包含全部指标评测结果的模型才会进入榜单",实际算法上则是对各 run 已有的指标得分做归一化求和,指标覆盖越全的模型综合分越有可比性。

注意一个细节:示例文件 config/leaderboard_example.yaml 中排名字段写作 excluded_runs,而源码实际读取的是 excluded_models,配置时请以 excluded_models 为准。

七、wandb 写入机制:run 的组织与标签

write_wandb()(见 wandb_writer.py)决定了数据在 wandb 中的呈现方式:

  • 每个评测场景(如 mmlu)独立一个 run:group = model_name,name = 场景名,run id = "{project}-{model}-{name}",并打上 tags = ["evalate", tag],其中 tag 为 detail(单场景)或 summary(汇总);
  • 若配置了 token_num 或 token_per_iteration,会写入 run 的 config,供排行榜横轴使用;
  • 每个迭代点通过 wandb.log(result[iteration], int(iteration)) 以 step 方式写入,从而在 wandb 中形成指标随步数变化的曲线;
  • 写入结束后 run.finish() 收尾。

parse_scenarios() 的整体流程是:逐场景解析并写 detail → 通过 make_summary() 把各场景在各迭代的指标合并到 summary → 最后写一份 summary run(见 wandb_writer.py)。这也解释了为什么 --summary-only 能跳过逐场景写入、仅保留汇总结果。

八、与 Auto Evaluation Toolkit 的配合使用

wandb_writer.py 是 tools/evaluator/evaluator.py 自动评测链路的下游环节。推荐的工作流(见 tools/evaluator/README.md):

  1. 准备至少两台多卡机器(一台训练、一台评测)与共享文件系统(如 NAS),在各机器上安装 data-juicer 及第三方依赖(Megatron-LM、HELM,详见 thirdparty/LLM_ecosystems/README.md);
  2. 用 Megatron-LM 将数据集预处理为 mmap 格式,训练机保存 checkpoint 到共享路径;
  3. 运行 python tools/evaluator/evaluator.py --config <config> --begin-iteration <n> --iteration-interval <m> --check-interval <k> 对 checkpoint 做自动评测(支持 megatron/huggingface 两种模型类型、helm/gpt 两种评测类型);
  4. 评测完成后,用本文的 wandb_writer.py 把 HELM 输出目录(source: helm)或已有结果(source: file)写入 wandb,实现指标跟踪与排行榜构建。

其中 evaluator.py 的 helm_output_path 即对应 recorder 配置中的 helm_output_dir,两者共享同一 HELM 输出目录约定。GPT 评测细节可参考 tools/evaluator/gpt_eval/README.md。

九、注意事项与排错建议

  • 默认指标口径:默认 16 组核心指标以源码 DEFAULT_HELM_BENCHMARKS/DEFAULT_HELM_METRICS 为准(含 quac.F1),README 文字列出的清单少了 quac.F1;如需精确控制,务必显式填写 benchmarks 或 leaderboard_metrics。
  • 迭代号解析:HELM 输出的场景 JSON 行首列需要包含可解析的迭代信息(_ 或 / 分隔),否则所有数据都会落到 default_iteration(默认 0),曲线会退化为单点。
  • 先调试后写入:使用 --print-only 可以先在命令行核对解析出的结构化结果,确认无误后再正式写入;--summary-only 可在数据量大时只保留汇总 run。
  • 排行榜横轴:需要 token_num(file 模式)或 token_per_iteration(helm 模式)才能给出有意义的 token 刻度,两者都缺失时横轴为 None。
  • 实例地址:使用自建 wandb 实例时务必填写 base_url,它同时作用于 wandb.init 与排行榜读取使用的 wandb.Api。
  • 配置键名:排行榜排除名单请使用 excluded_models(源码读取的键),不要照抄示例文件中的 excluded_runs。

至此,你已经可以从 HELM 评测输出或既有指标文件出发,把模型训练过程中的评测表现完整沉淀到 wandb,并生成多模型对比的排行榜,为训练监控与模型选型提供数据支撑。

登录后查看全文
data-juicer