LoCoMo_refined 评测引擎源码深潜:多候选金标匹配、精确命中捷径与异步并发打分完整指南

原创2026-11-03 19:18:131,695 阅读

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 函数中,流程分三步:

  1. 逐候选计算词汇指标:对每个候选分别计算 F1 和 BLEU(compute_token_f1 / compute_bleu1);
  2. 逐候选并发调用 LLM Judge:每个候选都发起一次异步判定任务,Judge 返回 0/1 二分类分数与判定理由;
  3. 按综合分挑选最佳候选:排序键为 (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 打印上下文(问题、金标、预测的前若干字符),方便排查是哪道题卡住了。

两个工程细节同样值得新手学习:

  1. JSON 安全抽取:extract_json_object 是一个手写状态机,能穿透 ``` 代码围栏、正确跳过字符串内的花括号与转义符,从模型回复中抠出第一个配平的 {...},避免 json.loads 直接解析整段回复时崩溃;
  2. 参数自适应:向 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 对照本文再走一遍代码,实践出真知!

登录后查看全文
LoCoMo_refined