跳转到主要内容
本页说明如何在 Benchmark 的 evaluate() 中接入 LLM 评委或 Agentic 评委。用户侧的参数和行为见评委总览;本页只讲实现约定。

选择评委类型

能用 LLM 评委就不要用 Agentic 评委:后者每题需要多次完整 agent 运行,成本和耗时高一个数量级,结果也更难复现。评测模式的生命周期见评测模式与产物。

通用约定

  • 通过配置 mixin 声明评委参数。 不要在 Benchmark 配置中自己定义 judge_model 等字段,使用 LLMJudgeConfig 或 AgentJudgeConfig,所有 Benchmark 的参数名、校验和 ${ENV} 解析就会保持一致。
  • 显式配置评委。 不要默认让被测 Model 给自己评分。judge_model_spec(req) 会把缺少的连接字段回退到被测 Model,这只是为了方便试跑;Benchmark 页面应要求用户提供完整、独立的评委配置。
  • 区分评委失败与答错。 评委请求失败、超时或输出无法解析时,返回 FATAL issue(judge_failed,输出结构不对时可用 judge_invalid_output),不要写入 0 分。分级规则见结果与聚合。
  • 保留判定依据。 把评委的判定、理由和必要的诊断信息写进结果,方便用户核查单题分数。
  • 在 Benchmark 页面写明评委。 写清评委职责、判定格式、推荐的评委 Model 和修改过的默认值,并链接到通用评委页面,不要重复通用参数说明。

LLM 评委

声明配置

把 LLMJudgeConfig 放在配置类基类列表的第一位,并在 __post_init__ 中调用 LLMJudgeConfig.__post_init__(self),它会先运行基类配置的 __post_init__:
LLMJudgeConfig 提供: 无需自己设置输出上限:调用和 judge_model.params 都没有设置时,generate_text 和 generate_with_metadata 会补上 max_tokens 32768(见默认 max_tokens)。只有 Benchmark 需要其他上限时才在调用时传入 max_tokens,judge_model.params 仍会覆盖它。

使用内置 scorer

只需比较最终答案时,使用 LLMJudgeScorer 和 evaluate_binary_scorer。后者负责调用 scorer、校验 correct 字段,并把异常映射成 FATAL judge_failed:
默认 prompt 是 A/B/C 协议,只有 A 计为正确。需要自己的判定规则时,向 LLMJudgeScorer 传入 prompt_template 和 response_parser:模板可使用 {question}、{gold_answer} 和 {llm_response} 三个占位符;解析函数接收评委回复文本、返回 bool,无法解析时应抛出异常,不要返回 False。

自定义评分流程

评分标准、多次采样或多阶段评分无法套用二元 scorer 时,直接调用 generate_text 或 generate_with_metadata:
  • judge_model.params 中的 timeout 和 max_retries 由客户端处理,其余键随请求发送,无需在 scorer 中另外实现超时和重试。
  • 用 asyncio.gather 并发请求时,runtime 已按 judge_concurrency 限流。
  • 需要区分截断和正常短回复时,使用 generate_with_metadata 并检查 stop_reason == "length"。
可参考 ResearchRubrics(逐条评分标准)和 DeepResearch Bench(多阶段评分)的实现。

Agentic 评委

AgentJudgeScorer 在评测 Environment 中启动评委 Harness,负责组装评委请求、切分窗口、并发运行、重判、时限和 media-inspect。与 LLMJudgeScorer 一样,Benchmark 只提供 prompt 和解析函数。

声明配置

AgentJudgeConfig 是一个 LLMJudgeConfig,一次性提供 judge_harness、judge_harness_params 和全部 judge_agent_* 参数,并统一校验:

预检评委

不要自己探测评委。推理开始前,runner 会从运行 AgentCompass 的机器探测配置的 judge_requirements(req) 返回的每个 Model,任何失败(包括端点不可达)都会终止运行,见模态预检。

判分

  • build_unit(attempt, index, batch) 为一个窗口返回 JudgeUnit:prompt、评委工作目录和 judgment 文件路径。每个窗口使用独立的目录,重判轮次也不要复用目录。
  • parse(outcome, batch) 把 JudgeUnitOutcome 解析为 {item_id: verdict}。outcome.judgment_text 为空、outcome.error 非空或判定缺项时,为对应条目返回失败标记(如 {"passed": None, "error": ...}),不要抛异常;outcome.failure_reason() 给出失败原因。
  • is_judged(verdict) 区分有效判定和失败标记。未判定的条目会在下一轮重判;最终仍未判定的条目保留第一次的失败标记。
  • 时限。 在 evaluate() 开头调用 evaluation_deadline(),它比 runtime 的评测超时提前一段余量。把它传给 scorer.score(..., deadline=deadline),每次评委运行都会截断到剩余预算;再用 call_with_timeout(..., timeout=remaining_budget(deadline)) 包住整个评委步骤兜底;它抛出的 TimeoutError 应转换为 judge_failed。call_with_timeout 只转发位置参数,关键字参数请用 functools.partial 绑定。
  • 媒体。 在 prompt 中加入 scorer.media_instructions():它说明 media-inspect 的用法,没有配置 media-inspect 时返回空字符串。按评委固定的模态只写一版 prompt,不要再写纯文本或无音频的变体。media-inspect 无法安装到评测 Environment 时,scorer.score() 会抛出异常,该任务的判分失败。scorer.media_summary() 返回 ffmpeg 是否可用和调用统计,可写入结果用于诊断。
  • 安装。 fresh Environment 中没有推理阶段安装的内容,因此评委参数没有显式设置 install_strategy 时,preinstalled 的评委 Harness 会退回 install_if_missing。

汇总结果

  • 任一条目最终仍未判定时,整个任务返回 FATAL judge_failed,不给分。
  • 交付物缺失是正常结果,应在 prompt 中要求评委把依赖它的条目判为不通过,而不是记为评委失败。
  • 为每次评委运行保存一条记录(窗口名、覆盖的条目、错误,以及 outcome.diagnostics()),例如 AA-Briefcase-Lite-AC 的 judge_windows。需要保留评委 agent 的对话记录时,加入 outcome.transcript():每步一条,包含文本、推理、工具调用和工具输出,内嵌的 base64 媒体替换为其大小。

隔离被测身份

成对比较或有参考答案时,用中性的标签和路径呈现证据,不要在 prompt、文件名或目录名中透露哪一侧是被测 Model。GDPval-AC 用 A/B 标签呈现被测产物和固定基线。

参考实现

提交前检查

  • 缺少 judge_model 时报错清楚,并在推理前暴露(judge_model_required 或预检)。
  • 评委失败、无法解析和超时都返回 FATAL issue,没有被记为 0 分。
  • 用本地测试验证解析函数在空回复、格式错误和缺项时的行为(测试文件放在不提交的根目录 tests/ 下)。
  • 配置设置了 judge_modalities,runner 的预检通过 judge_requirements(req) 覆盖每个评委 Model,evaluate() 使用 evaluation_deadline()。
  • Benchmark 页面写明评委职责、推荐评委和修改过的默认值,并链接到评委总览。