LoCoMo_refined 评测引擎源码深潜:多候选金标匹配、精确命中捷径与异步并发打分完整指南
LoCoMo_refined 评测引擎源码深潜:多候选金标匹配、精确命中捷径与异步并发打分完整指南
LoCoMo_refined 是基于 LoCoMo 重新校准的长对话记忆评测基准(benchmark),其评测引擎用 LLM Judge 严格判定记忆系统回答的对错。本文带你完整读懂 src/evaluate.py 背后的三大核心机制:多候选金标匹配、精确命中捷径与异步并发打分——即使你只是评测领域的新手,也能快速理解这套引擎如何又快又准地给 1,382 道题目打分。
评测引擎架构总览:一条命令跑通全流程
整套评测由 scripts/run_eval.sh 串联,分两步执行:
| 步骤 | 命令输出 | 核心模块 | 职责 |
|---|---|---|---|
| [1/2] Scoring | 逐题打分 | src/evaluate.py | 读取题目与预测答案,计算 llm / f1 / bleu 三类指标 |
| 2/2] Summarizing | 汇总报告 | [src/summarize.py | 生成 JSON 汇总与 Markdown 报表 |
各模块分工清晰,就像一条流水线上的工位:
- 📋 数据入口:data/public/questions.jsonl 存放 1,382 道题目,每题的
answer字段是一个可接受金标答案的列表; - ⚖️ 判定规则:src/llm_judge.py 内置
refined(默认,更严格)与original(原始宽松版)两套 Judge 提示词,官方裁判模型为 Qwen3-14B; - 🚀 推理运行时:src/llm_judge_runtime.py 中的
AsyncBinaryJudge负责调用模型、重试与解析结果; - 🔢 词汇指标:src/bleu_f1.py 提供轻量级的 token 级 F1 与 BLEU-1 计算。
多候选金标匹配:answer 列表如何逐候选打分取最优
为什么 answer 要设计成列表?因为同一道题可能有多种"完整且正确"的表达方式(比如日期格式不同)。规则是:只要命中列表中任意一个候选,就算匹配成功,而不是要求覆盖所有候选。
核心逻辑在 _evaluate_candidates 函数中,流程分三步:
- 逐候选计算词汇指标:对每个候选分别计算 F1 和 BLEU(
compute_token_f1/compute_bleu1); - 逐候选并发调用 LLM Judge:每个候选都发起一次异步判定任务,Judge 返回 0/1 二分类分数与判定理由;
- 按综合分挑选最佳候选:排序键为
(llm_score, f1_score, bleu_score)三元组,取最高分者作为matched_answer写回结果。
💡 这里有个精妙之处:未启用的指标会记为
-1.0而非0.0,这样排序时"没打的分"不会与"打了 0 分"混淆——保证无论开哪几种指标,候选排序都只取决于你真正启用的那些分数。
在更底层的 AsyncBinaryJudge 里(_evaluate_async),如果直接传入一组金标候选,则会并发判定并短路返回:任何一个候选被判 CORRECT,整题立即记 1 分。
精确命中捷径:0 次 LLM 调用的满分快速通道
并非每道题都要麻烦 LLM 出面。_evaluate_candidates 在进入正式打分前设置了三道"捷径",能省则省:
| 场景 | 判定结果 | LLM 调用 |
|---|---|---|
| ✅ 预测答案与某个候选逐字符精确相等 | llm / f1 / bleu 全部记 1.0 | 0 次 |
| ✅ 预测为空、但金标非空 | 全部记 0.0 | 0 次 |
| ✅ 金标候选全为空 | 全部记 0.0 | 0 次 |
精确命中时,llm_reason 会被写为固定文案 "Predicted answer exactly matches the reference answer.",保证可追溯。
这道捷径的价值很实际:省 API 成本、消除模型波动、加快整体评测。对于日期类题目(如 "7 May 2023"),模型输出常常与金标完全一致,捷径覆盖率相当可观。
异步并发打分:Semaphore 限流与任务聚合
1,382 道题如果逐题串行调用 LLM,耗时不可接受。引擎在 evaluate_public_predictions 中用经典的"信号量 + 任务池"模式实现并发:
- 🔒 并发闸门:
asyncio.Semaphore(concurrency)限制同时进行的打分任务数,默认 4,可通过--concurrency参数调大; - 🌐 任务聚合:所有题目一次性创建为
asyncio.Task,再经asyncio.gather统一收口,最后按原始题目序号排序写出结果,保证输出文件行序稳定; - 🧵 题内并发:单道题的多个金标候选还会再各起一个子任务(
as_completed收集),题间并发与题内并发形成两层流水线; - 📊 进度反馈:
_ProgressReporter在终端渲染进度条(含百分比与已用时长),非交互环境下按 100 题粒度打印日志。
LLM Judge 运行时:重试、限流退避与 JSON 安全抽取
调用大模型 API 最大的不确定性是网络与限流。_evaluate_single_gold 用 tenacity 的 AsyncRetrying 最多重试 10 次,并内置智能退避策略:
- 捕获到限流特征(
429、rate limit、tpm等)→ 随机等待 20~60 秒; - 其他错误 → 固定等待 1 秒后重试;
- 每次重试都会向 stderr 打印上下文(问题、金标、预测的前若干字符),方便排查是哪道题卡住了。
两个工程细节同样值得新手学习:
- JSON 安全抽取:
extract_json_object是一个手写状态机,能穿透 ``` 代码围栏、正确跳过字符串内的花括号与转义符,从模型回复中抠出第一个配平的{...},避免json.loads直接解析整段回复时崩溃; - 参数自适应:向 Qwen 系列发送
enable_thinking: False关闭思考模式;若某模型不支持该参数,会记忆并自动降级重发一次,不会反复失败。
此外,若你配置的裁判模型不是 Qwen3-14B,scripts/run_eval.sh 与 src/llm_judge.py 都会发出警告并要求交互确认——因为非官方裁判的结果可能与基准分数不可直接比较。
快速上手:配置环境变量并运行评测命令
跑通完整评测只需两步:
第一步:准备预测文件 outputs/predictions.jsonl,每行一个对象(可用 data/public/submission_template.jsonl 作模板):
{"qa_id":"conv-26#q0000","predicted_answer":"7 May 2023"}
第二步:运行评测:
export EVALUATOR_MODEL=qwen3-14b
./scripts/run_eval.sh --metrics llm f1 bleu --llm-judge refined
运行后在 outputs/ 目录得到三份产物:逐题打分明细 predictions_scored.jsonl、汇总 predictions_scored_summary.json 与可读报表 predictions_scored_summary.md(含按 category、按对话的分组统计表)。
核心源码文件导航
| 文件 | 说明 |
|---|---|
| src/evaluate.py | 评测主流程:候选匹配、精确命中捷径、并发调度 |
| src/llm_judge.py | refined / original 两套 Judge 提示词与模型配置 |
| src/llm_judge_runtime.py | AsyncBinaryJudge:异步推理、重试、JSON 抽取 |
| src/bleu_f1.py | token 级 F1 与 BLEU-1 实现 |
| src/summarize.py | 分数汇总与 Markdown 报表渲染 |
| scripts/run_eval.sh | 评测入口脚本 |
| data/public/questions.jsonl | 1,382 道公开题目 |
读完这篇深潜指南,你应该已经掌握了 LoCoMo_refined 评测引擎的完整脉络:多候选金标匹配保证了"表达不同但内容正确"的答案不被误杀,精确命中捷径让大量题目免去 LLM 调用,异步并发与智能重试则让千题级别的评测既快又稳。接下来不妨打开 src/evaluate.py 对照本文再走一遍代码,实践出真知!