> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置 model

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

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

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME"
```

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

## model API 协议列表

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

| ID                                                                   | 说明                                                                          |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`openai-chat`](/zh/user_guide/modules/models/openai_chat)           | OpenAI 兼容对话补全协议，适用于 `/v1/chat/completions` 风格端点。                            |
| [`openai-responses`](/zh/user_guide/modules/models/openai_responses) | OpenAI Responses API 协议，适用于 `/v1/responses` 风格端点以及 Responses 专属的推理和有状态工具调用。 |
| [`anthropic`](/zh/user_guide/modules/models/anthropic_messages)      | 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

[运行参数参考](/zh/user_guide/using_agentcompass/cli/run#参数参考)介绍 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`](/zh/user_guide/using_agentcompass/cli/launch) 为每个 model 声明一个具名请求；这样端点和推理设置的差异是显式的，而不是复制一份隐式对比模板。

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

```bash theme={"system"}
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 全局生成结构。可接受字段是以下三个契约的交集：

```text theme={"system"}
model params
  ├─ 所选 harness 消费或转换的字段
  ├─ 所选 API protocol 定义的 request 字段
  └─ endpoint 和 model deployment 支持的字段
```

```bash theme={"system"}
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 参数。