跳转到主要内容
根据验证器需要访问的状态选择 none、reuse 或 fresh,并在任务 Environment 关闭前提取后续评测所需的产物。

三种模式

三种模式下,runtime 都在环境存活期间执行声明的收集命令;没有命令就直接收集已有文件。收集流程使用解析后的路径和命令列表,默认继承 Benchmark 声明,也可由执行参数覆盖。execution.save_artifacts 控制本地保存,fresh 要求开启。产物准备与收集不决定分数。

设置默认值和逐任务覆盖

如果所有样本都使用同一种模式,请在 Benchmark 类上设置默认值:
如果不同样本需要不同的验证方式,请在 TaskSpec 上分别设置:
runtime 规划器按以下顺序解析模式:
这是创建初始 ExecutionPlan 时的选择顺序。随后启用的 Recipe 可以按自身契约调整计划;如果 Recipe 会修改评测 Environment,必须在实现和测试中明确哪些字段可以覆盖、哪些字段必须保留。排查实际生效的模式时,应查看 run_info.json 的 resolved_execution_plans,其中记录了 Recipe 调整后的计划。

none:进程内评分

none 适合只依赖 TaskSpec、PreparedTask 和 RunResult 的评测器。不要在这种模式下读取任务工作区:
如果进程内评测器需要调用另一个 Model,应显式配置评审 Model,并记录其版本和推理参数;不要默认让被测 Model 为自己的结果评分。 通过配置 mixin 声明评委,而不是自己定义字段:把 agentcompass.benchmarks.config.LLMJudgeConfig 放在配置类基类列表的第一位(class XConfig(LLMJudgeConfig, RuntimeBenchmarkConfig)),并在 __post_init__ 中调用 LLMJudgeConfig.__post_init__(self)。它声明 judge_model、解析 ${ENV} 引用并校验模型配置;只有部分运行需要评委时,设置 judge_model_required: ClassVar[bool] = False。config.judge_model_spec(req) 返回 ModelSpec,缺少的连接字段取自推理 Model。它还声明了 judge_concurrency(默认 1):评测单个任务时,运行时最多允许这么多个 generate_text / generate_with_metadata 调用同时进行,因此并发调用评委的 scorer 不需要自己的信号量;单个任务会调用很多次评委时,重新声明该字段并提高默认值。

reuse:检查当前任务 Environment

reuse 在任务 Environment 关闭前执行评测,因此验证器能看到 agent 最终留下的工作区:
验证器路径和依赖必须存在于任务 Environment 中。评测阶段使用解析后的 evaluation_network_policy;不要假定执行阶段仍保留原有的网络权限。 完整的 reuse 生产实现可参考 terminalbench2.py。

fresh:准备、采集,再隔离验证

fresh 不会复制整个工作区。声明 verifier 所需的文件或目录后,公共 runtime 会在关闭 agent 环境前采集,并在 fresh 环境中的同一绝对路径恢复:
如果 agent 已经写好这些文件,无需准备命令。需要生成文件时,通过 TaskSpec.artifact_collect 声明命令;Harbor 的 verifier.collect 会映射到同一入口。例如:
评测器收到的环境中已经恢复了声明的文件,不要再次下载或上传:
准备和采集分别使用独立执行预算。准备或传输失败会保留诊断信息,但不继续评分或生成可续跑 checkpoint;正常缺少提交文件则由 verifier 决定分数。大小限制、完整性校验及准备钩子的职责见共同契约。DeepSWE 是准备产物并使用公共传输的生产示例。

Agentic Judge:用评委 Harness 评分

当评分细则需要评委自己打开、渲染或执行交付物(文档、表格、视频)时,使用 agentic judge,而不是只读文本的 LLMJudgeScorer。AgentJudgeScorer 在评测 Environment(reuse 或 fresh)中启动评委 Harness 并负责运行机制;与 LLMJudgeScorer 一样,Benchmark 只提供 prompt 和解析函数:
  • 评委请求在 judge_harness 上使用 judge_model。评委与推理使用同一类型 Harness 时继承推理的 --harness-params;评委 Harness 声明了轮数上限和免审批开关时会自动设置;judge_harness_params 优先级最高。
  • fresh Environment 中没有推理阶段安装的内容,因此除非显式设置 install_strategy,preinstalled 的评委 Harness 会退回 install_if_missing。
  • AgentJudgeSettings.timeout_seconds 限制每次评委运行。在 evaluate() 开头计算 deadline = evaluation_deadline(plan.evaluation_timeout_seconds) 并传给 scorer.score(..., deadline=deadline):每次运行会截断到剩余的评测预算,并在 runtime 超时前结束,超时记为评委失败。再用 call_with_timeout(..., timeout=remaining_budget(deadline)) 包住整个评委步骤作为兜底。
  • 在 select_tasks() 中调用 probe_judge_model(req, config.judge_model, label=...),评委的 key 或模型被拒绝时在推理前就终止运行;宿主机访问不到端点时只记警告,因为评委运行在评测 Environment 中。
  • AgentJudgeSettings.input_modalities(取自 text、image、audio、video)决定评委检查哪些内容。Harness 只能把图片交给 Model,所以 image 开启评委 Harness 自带的看图能力;audio 和 video 需要配置 AgentJudgeSettings.media,AgentCompass 会在评测 Environment 中安装 media-inspect 命令,它用 ffmpeg 截取片段后发给多模态 Model(默认是评委 Model)。把 scorer.media_instructions() 放进评委 prompt:它说明工具的用法,工具不可用时说明哪些内容无法检查。scorer.media_summary() 返回调用统计。
  • 用 AgentJudgeConfig(它是一个 LLMJudgeConfig)一次性获得全部 judge_* 参数:judge_harness、judge_harness_params、judge_agent_max_turns、judge_agent_concurrency、judge_agent_timeout_seconds、judge_agent_rubric_window、judge_agent_max_retries、judge_agent_modalities 和 judge_agent_media,并统一校验。需要不同默认值时重新声明该字段;用 config.agent_judge_settings() 构造 scorer,在 select_tasks() 中用 config.probe_agent_judge(req, label) 预检。
  • 每次评委运行写一个 judgment 文件。失败或无效的运行只影响它覆盖的条目;最终仍未判定的条目必须报告为评测失败,而不是 0 分。
生产实现可参考 aa_briefcase_lite_ac 和 gdpval_ac。

选择模式时检查

  • 评分只依赖答案或内存对象时选 none,不要为简单评分额外创建 sandbox。
  • 验证器必须看到 agent 修改后的原始文件系统时选 reuse,并确保验证器不会污染后续需要保留的结果。
  • 验证器不应信任 agent 留下的依赖或进程时选 fresh,并明确传输的最小提交物。
  • prepare_task()、artifact_collect 中执行的命令以及验证器命令都要设置明确的超时,并保证重试时可以安全重复。
  • 评测失败与正常零分必须使用不同状态,具体映射见结果与聚合。