EvalHarness/tests/error.md

EvalHarness 对标 evalscope 全程踩坑记录

28 bench 双框架对比过程中发现的所有问题（我方 bug / es 方 bug / 口径差），按层归类。 每条含：现象 → 根因 → 修复 → 验证结果。

---

一.5、fix2 轮新增修复（2026-09-02 晚，prompt 逐字对齐 + 基建）

16.5. es bfcl 单轮全 0 = 依赖版本崩溃（已帮修，evalscope/.../bfcl/v3/utils.py） - 现象：es bfcl simple/multiple/parallel 等 10 个单轮类全部 0 分，irrelevance 类却 0.9+ - 根因：utils.py convert_format_language() import bfcl_eval.constants.enums（BFCL v4 新版枚举），环境装的是 bfcl_eval 2025.8.6.2（旧版，ast_checker 直接比较字符串 "Java"/"JavaScript"/"Python"）→ ModuleNotFoundError → except 吞掉 → 全部判 ast_decoder:decoder_failed - 修复：utils.py 两个 convert 函数改为版本兼容（try 新版枚举，fallback 旧版字符串，注意 JavaScript 大写 S） - 验证：es bfcl 20/类 0.1736 → 0.3563（simple 0.55、live_simple 0.7、parallel 0.45-0.5 全部起来） - 遗留：我方 0.266 vs es 修复版 0.356 仍差 0.09——我方 bfcl_mock 的官方后端转换细节（underscore_to_dot 等）待对齐

17. 多段 pool spec range 替换 bug（model/runner.py::_make_adapter）
    • 现象：多段逗号池（105+138+140+143 共 20 口）全军覆没 ConnectError，单段池正常；curl 同口 200
    • 根因：re.sub(r'\{..\}', port, u, count=1) 每次只替换最前的 range → 20 个成员 URL 全带字面量 {8200..8203}，httpx 连畸形 host 必败
    • 修复：按逗号拆段，每段独立 search+替换自己的 range
    • 验证：20 成员展开正确，4/4 请求成功；停滞的 mmlu_pro 恢复 1 samples/s
18. 网络抖动三层自愈（集群路由分钟级断通交替，17:07-18:15 反复）
    • adapter：httpx.Timeout(connect=15, read=300, write=30, pool=15)——半开 TCP 快速失败
    • pool：实例级 failover（已有）
    • runner.run_one：6 次退避重试（10/20/40/60/90s）跨过断网窗口——gather 不再被单点异常炸掉
19. prompt 逐字对齐 10 处（双侧渲染 diff 器验证，全部 IDENTICAL）：
    • mmlu 域匹配失效（subject/category 键名不一致 → 全局前 5，es 是每科目 5 范例）
    • mmlu_pro 三处（header 应在范例前 / cot_content 变换单 ANSWER / 测试选项 A) x）
    • bbh 测试题缺 Q:/A: Let's think 包装
    • aime 缺尾部 Remember to put your answer inside \boxed{}. + 前导 \n
    • gsm8k \boxed{}. 句号；math fewshot 单换行分隔；imo/hmmt/cmmlu/trivia 尾换行
    • lcb 缺 ### Format: 前缀 + starter_code 进代码块 + expert 头移到 system role
    • hle judge prompt 换 es 逐字版 + 三态契约移 system role
    • trivia list(str) 拆字符隐患
20. es limit 是 per-subset 语义：es mmlu limit=200 = 每科目 200 = 全量 14042！同题跑法必须 per-subset k（mmlu 4/科目=228、cmmlu 3、hle 25、imo 25、lb2 66/长度）
21. gfc ckpt 版本漂移：数据镜像重物化后 metadata 变化 → key_for 失配 restored 0；同口径 f1 直接从本次 report.samples 算更稳

---

一、我方框架 bug（16 个，全部已修）

判分 / 聚合层

1. few_shot_hook 从未挂载（data/registry.py）

   • 现象：bbh 全程 0-shot（无官方 3-shot CoT），15 个 MCQ 子集接近 0 分
   • 根因：register_dataset 装饰器从不把模块级 <name>_few_shot 函数挂到 provider 上，runner getattr(prov, 'few_shot_hook') 永远 None
   • 修复：装饰器里 factory.__globals__.get(f'{spec.name}_few_shot') 自动拾取（注意 __globals__ 是 dict 要用 .get 不是 getattr）
   • 验证：bbh 27子集×10 = 0.819 vs es 0.8185

2. MCQ 抽取格式不匹配（eval/recipes/qa.py）

   • 现象：bbh 全部 MCQ 子集判分全 miss
   • 根因：mcq_letter 返回裸字母 'A'，target 是 '(A)'
   • 修复：bbh recipe 按 target 形态格式化为 f'({val})'

3. llm_judge 标签子串扫描（eval/scorer.py）

   • 现象：hle 虚高 1.0、simple_qa 解析错乱
   • 根因：label in upper 全文子串匹配——judge 解释文本里 "CONSISTS" 命中 'C'、"ANSWER" 命中 'A'
   • 修复：三级解析——label_pattern 正则（如 GRADE:\s*([CI])）→ 尾行词边界匹配 → 全文词边界兜底
   • 验证：hle 1.0→0.031（es 0.050 同族）、simple_qa 见下条

4. dict 聚合器主指标被派生值均值覆盖（eval/runner.py）

   • 现象：simple_qa 真值 0.035 被报成 0.403
   • 根因：simpleqa_official 返回 5 个派生指标 dict，代码取 mean(全部值) = mean(0.035, 0.945, 0.02, 0.98, 0.036) = 0.403
   • 修复：dict 展开时主指标取同名键 out[metric]，无同名键才退化均值
   • 验证：simple_qa 同题 0.050 vs es 0.0503

5. judge adapter 拿不到 API key

   • 现象：judge 全 401
   • 根因：launcher 没 export OPENAI_API_KEY（spec URL 里不含 key）
   • 修复：启动脚本统一带 key

配对 / 选样层

6. 双重 _apply_limits 依赖原地 shuffle 别名（model/runner.py）

   • 现象：per-task 截断时判分配对错位（mmlu 一度 0.275）
   • 根因：run_eval 和 generate_predictions 各调一次 _apply_limits，旧实现靠「in-place shuffle 使两处列表别名同步」侥幸正确；per-group 重写返回新列表后别名断裂 → samples 顺序 ≠ preds 顺序
   • 修复：run_eval 用确定性重算得到与 generate_predictions 完全一致的 work 列表再 zip 判分
   • 验证：mmlu 恢复 0.730+

7. checkpoint key 不含 subset

   • 现象：lb2 三个长度互相污染缓存
   • 修复：ckpt 名加 :{subset} 后缀

8. checkpoint key 不含 prompt / 生成参数

   • 现象：改 prompt 模板后重跑，复用旧模板的预测（hswag 渲染实验多次被坑；humaneval 指令头实验同）
   • 教训：改任何影响 prompt 的东西必须删 ckpt（此后每次模板修改都显式 rm ckpt）

9. no_shuffle 没管到 per_task 分支

   • 现象：以为在跑「同题前 N」，实际 per-group 内仍 Random(42).shuffle 取前 N（hswag 同题实验一度假对齐）
   • 修复：per_task 分支尊重 shuffle=False（组内不洗直接前 N）

10. 选样语义与 es 不同（model/runner.py）

    • es：每个 subset 独立 Random(42).shuffle 后取前 N
    • 我方旧实现：全局 shuffle 后按组截断 → 同池不同题
    • 修复：per_task 时按组分组、组内独立 Random(42)、组序内取前 N

生成 / prompt 层

11. /no_think 裸拼污染题面

    • 现象：prompt 尾部最后一个选项后面跟 /no_think 字样
    • 根因：Qwen3 软开关实现把标记 append 到最后一条 user 消息
    • 修复：普通请求改 chat_template_kwargs: {enable_thinking: false}（服务端验证支持）；tools 请求保留软开关（模板 400 规避）
    • 验证：gpqa 0.263 → 0.460（es 0.480）

12. MCQ 选项渲染字符级差异（strict/cot_letter 分支）

    • 现象：hswag 同题下 A. 渲染 = 0.7825、A) 渲染 = 0.565——两个字符差 22 分（no-think Qwen3 对格式极端敏感）
    • 修复：所有 MCQ 分支逐字对齐 es：A) 选项 + one of A,B,C,D（mmlu_pro 例外：es 用 A 空格分隔）
    • 验证：wino 0.655 = es 0.655；hswag 对齐中

13. prompt 模板逐 bench 缺失/走样（最大一类，累计 12+ 处）

    • mmlu/cmmlu/mmlu_pro：我方 strict「整个回复只能是 ANSWER」 vs es「Think step by step + last line ANSWER」→ 全部对齐（mmlu 0.730→0.795，es 0.800）
    • few-shot 渲染：es 范例=裸题+A)+ANSWER:，我方=Question:/A./Answer: → 对齐 + 按科目域匹配范例（es biology 题配 biology 范例）
    • mmlu_pro：es 专属模板（Question:/Options:/A x + CoT 范例 + 按域 header）→ 0.471→0.579（es 0.629）
    • gsm8k：es 范例=题+Reasoning:全文+ANSWER: \boxed{} → runner 加 reasoning 元数据渲染分支
    • math：es 范例=Problem:/Solution: 裸答案 → 同上
    • aime×3：es=「Solve the following math problem step by step. Put your answer inside \boxed{}.」指令前置，我方是题后 suffix → 加 aime_es
    • imo/hmmt26：es=Problem:\n{题}\n\nPlease reason boxed（Problem: 前缀），我方裸题 → 套 imo_es（imo 0.138→0.19；hmmt 验证中）
    • simple_qa：es=Answer the question:\n\n{q} 且无 Answer 行契约，我方自加契约 → simple_qa_es
    • trivia：es 开放卷（Content: {wiki证据列表} + es 模板），我方闭卷（镜像键名读错 wiki_content≠wiki_context）→ 修键名+开模板（0.555→0.700，es 0.660）
    • lb2：es=<text> 包装 + CoT 契约，我方裸文档+strict → lb2_es
    • humaneval：es 指令头（"Read the following function signature..."）→ 加了头后 harness 仍用 input 拼程序导致指令进 main.py 全 0 → metadata 存原始 prompt，harness 用 metadata 版
    • LCB：我方无代码契约（模型输出 LaTeX 数学推导！）→ 官方 system+### Question:/### Answer:+```python 格式 → lcb_es
    • drop：es=Think step by step + "Answer: [ANSWER]" → prompt_suffix；范例=完整 Passage 式

14. tau2 env 内部调用不传生成参数（agent/envs/tau2_official.py）

    • 现象：agent 调用走 adapter 默认 4096 tokens/无温度
    • 修复：run_task(gen_kwargs=) 透传（temp 0/16k；16k+长对话会超 131072 上下文 → 8192）

15. tau2 reward 读不存在的字段

    • 根因：读 environment_reward/communication_reward，tau2 官方 reward_info 字段是 reward/db_check/... → 恒 0
    • 修复：取 rewards['reward']（es 同款官方综合分）

16. HF 下载同步阻塞事件循环

    • 现象：18 任务并发时全卡死（py-spy 见主线程 _hf_download）
    • 修复：asyncio.to_thread 物化

基础设施

• 根盘写满（Errno 28）两次：HF 缓存迁移 /data2、清 modelscope 196G、truncate docker 巨型日志
• pkill -f <pattern> 会误杀自己所在 shell（cmdline 含 pattern）→ 用 launcher 文件 + 短命令
• bash 工具 timeout 会杀未及 detach 的后台任务 → nohup ... < /dev/null & disown + 立即返回
• checkpoint 恢复打印 restored N (M to generate)：N≠M 命中时警惕 key 失配（多次救场信号）

---

二、es（evalscope）侧问题（代码级证据）

1. tau2 崩溃：tau2_bench/generation.py:118 openai_chat_choices(include_reasoning=False) 丢弃 Qwen3 思考通道 → 空 content → 官方引擎 message.py:116 校验 raise（temp=0 确定性复现）
2. gfc 误判（已帮修）：general_fc_adapter.py is_call_tool = finish_reason=='tool_calls'，vLLM/Qwen3 输出 tool_calls 时 finish_reason 常为 'stop' → FN 虚高。patch：or bool(tool_calls)
3. BCB 执行器空跑（已帮修）：bigcodebench_adapter.py passed = status=='success'——沙箱命令完成≠测试通过，198/200 空输出判对（0.99 虚高）。patch：unittest 显式 runner + __BCB_RESULT__ PASS 标记 → 0.365（与我们 0.375、交叉判分三方一致）
4. LCB 本地执行全体 -2：use_sandbox=false 本机跑 codegen_metrics 全失败（环境缺依赖）；docker sandbox 修复后 0.413 有效
5. gfc 0.0 失败运行残骸：断连+空回复产物；重跑 0.456
6. swe 无评测断点：198/200 评完后报告步骤遇断连作废，重跑=整段 4h（我们用日志聚合出真值 0.0）

---

三、口径差（非 bug，须同口径才可比）

类别	内容
选样	双方 shuffle42 的 base 行序不同 → 不同题集。统一方案：双侧 shuffle=False 取原始前 N（数据源行序一致，已验证 400/400 同题）
金标集合	drop：es=answer+validated_answers 合并（任一算对），我们镜像无该字段 → 严 ~0.065
指标定义	gfc：es 报 tool_call_f1，我们 acc（已重算同口径）；imo：judge vs math_equal（已统一 judge：0.188 vs 0.198）
数据构成	math 全量：我们随机 200（易题占比高）vs es 5 Level 均衡——对齐档 L×N 才可比
执行环境	bfcl/gfc/tau2：es+Qwen3 的 agent 栈兼容性差；LCB：判定器不同（官方 codegen_metrics vs 自写 runner）
截断	lb2 文档中位 41.7 万字符天然超 131072——head+tail 截断双方同构（非 bug）

---

四、方法论教训

1. 分数不一致时先做同题实验（同 prompt 双跑 / 同题双侧）——hswag 0.2 之谜三小时才定位到两个字符
2. 交叉判分（A 的输出 × B 的判分器）是分离「判分层差 vs 生成层差」的唯一利器
3. 隔离变量实验：同题×同 prompt×只换渲染 → 定位 A. vs A)
4. no-think 模型对 prompt 字符级格式极端敏感（22 分级别的摆动）
5. ckpt key 必须覆盖 prompt 语义，否则改模板=白改