配置 model

配置 model ID、端点、凭证、API 协议和端点专属 推理参数。

AgentCompass 不维护固定的 model 名称注册表。model ID 由你实际评测的端点提供，也是agentcompass run 的第三个位置参数：

agentcompass run <benchmark> <harness> "$MODEL_NAME"

runtime 将该 ID 与端点、凭证、API 协议和推理参数一起存入 ModelSpec，再由所选 Harness 决定如何使用。

​

model API 协议列表

不同 provider 的 model ID 各不相同，但 AgentCompass 定义了三个协议 ID；它们也会出现在agentcompass list dump 输出中。

ID	说明
openai-chat	OpenAI 兼容对话补全协议，适用于 /v1/chat/completions 风格端点。
openai-responses	OpenAI Responses API 协议，适用于 /v1/responses 风格端点以及 Responses 专属的推理和有状态工具调用。
anthropic	Anthropic Messages 协议，适用于 Claude 风格 /v1/messages 端点。

协议支持还取决于所选 Harness。端点实现了 OpenAI Chat，并不意味着它能搭配要求响应或Anthropic Messages 行为的 Harness。

--model-api-protocol 可以直接使用上表中的协议 ID。不传该参数或传入 auto 时，由所选 Harness 决定协议；例如 codex 默认使用 openai-responses，claude_code 使用 anthropic。

也可以传入有序 JSON 数组，例如 '["openai-responses","openai-chat"]'。Harness 会选择第一个自身支持的协议；该数组不表示请求失败后的回退，且不能包含 auto。

​

配置 ModelSpec

运行参数参考介绍 model 位置参数和 --model-* 参数；它们共同构造以下ModelSpec 字段：

ModelSpec 字段	CLI 输入	类型与默认值	作用
id	主要 MODEL 位置参数	必填字符串	发送给端点的 model 名称，以及结果路径中的 model 片段。
base_url	--model-base-url <url>	字符串，默认 ""	API 基础 URL；所选客户端能解析 provider 默认地址时可以留空。
api_key	--model-api-key <key>	字符串，默认 ""	端点凭证。应传入环境变量引用，而不是字面量密钥。
api_protocol	--model-api-protocol <protocol>	字符串或有序字符串列表，默认未指定	决定 Harness 如何与端点通信。
params	--model-params <json>	JSON 对象，默认 {}	承载推理、客户端可靠性、推理和 provider 专属请求字段。

​

配置连接信息

一个 agentcompass run 只包含一个 ModelSpec。如需比较多个 model ID，请使用agentcompass launch 为每个 model 声明一个具名请求；这样端点和推理设置的差异是显式的，而不是复制一份隐式对比模板。

统一导出 model 连接信息，避免凭证进入命令历史：

export MODEL_NAME=""
export MODEL_BASE_URL=""
export MODEL_API_KEY=""

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat

​

配置 params 字段

--model-params <json> 没有一套 AgentCompass 全局生成结构。可接受字段是以下三个契约的交集：

model params
  ├─ 所选 harness 消费或转换的字段
  ├─ 所选 API protocol 定义的 request 字段
  └─ endpoint 和 model deployment 支持的字段

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --model-params '{
    "temperature": 0,
    "max_tokens": 4096
  }'

常见 model 参数可按用途分为以下几类：

字段类别	示例	选择方式
采样	temperature、top_p、随机种子字段	对齐官方 Benchmark 设置。调试时只在端点支持的情况下使用确定性取值。
输出预算	max_tokens、max_output_tokens	使用协议要求的字段；在端点上下文预算内尽量避免截断合法输出。
推理	reasoning_effort、思考控制项	使用准确的 model/provider 请求结构，并记录到对齐报告；部分 provider 要求嵌套字段。
客户端可靠性	timeout、max_retries	限制单次 model 请求及传输重试；不要与 Harness 超时或 AgentCompass 任务重试混淆。
provider 扩展	extra_body 和 provider 定义字段	只传入端点明确支持的选项；一个 OpenAI 兼容部署接受的字段可能被另一个拒绝。

这些名称默认不具备可移植性。例如 OpenAI Chat 常用 max_tokens，OpenAI 响应使用max_output_tokens 等响应专属 字段，Anthropic Messages 也有自己的必填请求结构。各协议页面说明 AgentCompass 的转发方式。

所选 Harness 页面同样是权威来源。CLI 驱动 Harness 可能把 ModelSpec 转换为自己的配置文件，而不是通过AgentCompass 原生协议客户端直接转发 --model-params。

--model-params 必须是合法 JSON。CLI 值会深度合并到配置文件的 model.params 同名字段上。只传入与有效端点和 Harness 默认值不同的字段。

​

配置评委与分析 model

部分 Benchmark 和分析器使用额外 model 配置进行评判或定性分析。这些嵌套配置使用相同概念——model ID、基础 URL、API 密钥、协议和参数——但归属于对应组件：

• Benchmark 评委 model 通常位于 --benchmark-params，例如 judge_model。
• 分析器 model 位于 --analysis-params，例如 QualitativeAnalyzer。
• 工具专属摘要 model 可能属于所选 Harness。

除非 Benchmark 或 Harness 明确声明对应结构，不要把评委凭证放入主要 --model-params 对象。

​

排查 model 配置

现象	可能原因
无法识别 provider	底层客户端需要 provider 限定 model ID，或所选 Harness 使用另一协议。
401 或身份验证错误	API 密钥缺失、过期或属于另一端点。
404 或 model 未找到	配置的基础 URL 未提供该 model ID。
429 或限流错误	任务并发数、Harness 并行度、RPM 或词元吞吐量超过端点容量。
不受支持协议	所选 Harness 不支持请求的 API 协议。
无效请求字段	参数使用了错误协议或 provider 专属结构。
持续截断	输出限制太小，或总数上下文预算耗尽。

先把失败缩小到一个任务，检查 Harness 和端点错误，再修改多个 model 参数。