compare

比较：跨跟踪器进行同 epoch 运行对比

最常见的比较错误，是在运行 A 处于第 11/100 个 epoch、基线数值却来自第 100 个 epoch 时，报告“运行 A 落后基线 4 个百分点”。学生仍在训练中；这样的比较毫无意义。此技能会强制按相同 epoch 对齐。

当助手报告差值却未对齐运行时，Agentic Stop hook 会从 reason 路由到此处。

何时运行

用户刚刚说了以下任意一句：

• “将运行 A 与基线／运行 B 比较”
• “我的运行是在进步／追上来／落后吗”
• “给这些实验排名”
• “X 与 Y 的 wandb / neptune”
• “跟踪相对基线的差距”

自动检测跟踪器

按以下顺序检查：

1. 已设置 WANDB_API_KEY 环境变量，或项目中导入了 wandb → wandb
2. 已设置 NEPTUNE_API_TOKEN 环境变量 → neptune
3. 已设置 MLFLOW_TRACKING_URI 环境变量，或存在 mlruns/ 目录 → mlflow
4. 存在 runs/ 或 lightning_logs/ 目录 → tensorboard
5. 运行目录中存在 *results*.json / *meta*.json 文件 → 本地文件格式

如果都没有匹配项，先询问用户指标存放在哪里，再做判断。

流程

1. 确认运行

获取完整名称（不要用简称）。如果用户说“fvs-fm 对比基线”，请确认：

• 是哪个 fvs-fm 运行（项目 + 实体 + 运行 ID）
• 是哪个基线（完整运行名称；基线通常有多个变体）

2. 获取指标历史（而不仅是最终值）

需要完整曲线，而不只是最后报告的值。仅比较最终值会掩盖收敛动态。

对于 wandb：

import wandb
api = wandb.Api()
run = api.run("entity/project/run-id")
history = run.history(samples=10000)  # full history, not just summary

对于 tensorboard，解析事件文件（tensorboard.backend.event_processing.event_accumulator.EventAccumulator）。

对于 neptune / mlflow，使用各自的 API。

3. 找出学生当前所处的步数

学生是仍在进行中的运行（或正在评估的运行）。从最新的历史记录行获取其当前 epoch / 步数。

4. 截取基线在相同步数的指标

这是关键步骤。基线可能已经运行到（比如）第 100 个 epoch，而学生还在第 11 个 epoch。提取基线_在第 11 个 epoch 的指标_，而不是第 100 个 epoch 的指标。

student_step = student_history['epoch'].max()
baseline_at_same_step = baseline_history[baseline_history['epoch'] == student_step]

如果基线没有完全匹配的步数，则进行插值或选择最近的步数，并说明采用了哪种方式。

5. 区分代理指标与下游指标

大多数 ML 流程都有一个_代理指标_（计算开销低，在训练期间计算，例如特征上的 kNN 准确率、损失、困惑度）和一个_目标下游指标_（计算开销高，定期计算或仅在最后计算，例如微调线性探针准确率、下游任务 F1）。

代理指标用于跟踪收敛；目标指标才是项目实际优化的对象。只报告代理指标可能会造成误导：某个运行在 kNN 上落后，可能会在下游微调时缩小差距。请分别报告两者：

                        | student (ep 11) | baseline (ep 11) | delta |
| proxy (kNN top-1)     | 36.4%           | 38.9%            | -2.5  |
| downstream (linear)   | not yet         | 42.1%            | n/a   |

如果用户只有代理数据，请明确说明。切勿仅凭代理指标判定胜者。

6. 输出中的运行名称

报告中的每一行都要使用完整运行名称。不要写 cs-ad vs fvs-fm；始终写 phase1-7src-conv-s-adaptor-mlp vs phase1-7src-fastvit-s-featmap-mlp。未来的你读到这里时，不会记得这些简称。

反面模式

• “X 落后基线 4pp”：没有说明_处于哪个步数_。几乎总是错的。
• “X 已收敛”：却没有展示曲线最后 5 个 epoch。
• “最佳运行是 Y”：依据的是不同运行中记录方式不同的指标（归约方式不同，评估集也不同）。
• 将单种子比较当作定论。已知方差时注明；否则标注为单种子。

输出

按指标对（代理指标 + 下游指标）提供精简的比较表。每行都按学生当前所处的步数对齐。每个单元格都必须能追溯到具体的跟踪器运行 ID 和步数。最后用一两句话解读比较结果；“根据当前斜率推测，学生有望在第 N 步追上”是有用的表述；在收敛前，很少有理由断言“学生正在领先／落后”。