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:
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"。
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是否可用和调用统计,可写入结果用于诊断。 - 安装。
freshEnvironment 中没有推理阶段安装的内容,因此评委参数没有显式设置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 页面写明评委职责、推荐评委和修改过的默认值,并链接到评委总览。
