data-juicer 评测结果记录器:用 wandb 可视化模型训练指标与构建排行榜实战指南
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。三种场景的示例配置文件分别为:
- config/mymodel_example.yaml:从 HELM 输出目录解析;
- config/llama_example.yaml:从配置文件直读结果;
- config/leaderboard_example.yaml:构建排行榜。
使用前提:本地已安装 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)的具体流程为:
- 打开
{helm_output_dir}/runs/{suite_name}/groups/{scenario_name}.json; - 遍历 JSON 中的每个 subject,从其
header中匹配scenario_metrics(即配置的metrics)对应的列下标; - 逐行读取
rows,尝试从首列值中提取迭代号:优先按_分割取最后一段,再尝试按/分割取最后一段,均失败则回退到default_iteration; - 以
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)的核心步骤:
- 通过
wandb.Api拉取该项目下所有带summary标签的 run,跳过group == "leaderboard"以及出现在excluded_models中的 run; - 用
scan_history按_step与各leaderboard_metrics取历史,把每个 run 在每步的指标得分按指标 -> 模型 -> 迭代组织; - 对每个指标做 min-max 归一化:
score' = (score - min) / (max - min)(cal_score(),见 wandb_writer.py),把不同量纲的指标压缩到 0~1 区间; - 按模型、按迭代把所有指标的归一化得分求和得到综合分;
- 用
wandb.Table以["model", "token_num", "score"]三列组织数据,横轴取 run config 中的token_num;若未提供则用迭代号 * token_per_iteration换算;两者都没有则为空; - 通过
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 = 场景名,runid = "{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):
- 准备至少两台多卡机器(一台训练、一台评测)与共享文件系统(如 NAS),在各机器上安装 data-juicer 及第三方依赖(Megatron-LM、HELM,详见 thirdparty/LLM_ecosystems/README.md);
- 用 Megatron-LM 将数据集预处理为 mmap 格式,训练机保存 checkpoint 到共享路径;
- 运行
python tools/evaluator/evaluator.py --config <config> --begin-iteration <n> --iteration-interval <m> --check-interval <k>对 checkpoint 做自动评测(支持megatron/huggingface两种模型类型、helm/gpt两种评测类型); - 评测完成后,用本文的
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,并生成多模型对比的排行榜,为训练监控与模型选型提供数据支撑。