> ## 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.

# 模型

> 每次 run 的 model endpoint、protocol、API key 和 generation params。

AgentCompass 的模型配置是 run-local 的。Model spec 告诉当前 harness 调用哪个模型、endpoint 在哪里、使用哪个协议，以及传递哪些 generation parameters。

普通 run 不需要全局 model registry。

## Model Spec 字段

| 字段             | 含义                                                                     |
| -------------- | ---------------------------------------------------------------------- |
| `id`           | 传给 provider 的模型名，也用于结果路径。                                              |
| `base_url`     | API endpoint base URL。                                                 |
| `api_key`      | endpoint 的 API key 或 token。                                            |
| `api_protocol` | 协议适配器，例如 `openai-chat`、`openai-responses`、`anthropic`。                 |
| `params`       | 采样和 provider-specific request options，例如 `temperature` 或 `max_tokens`。 |

CLI 通过 `--model-base-url`、`--model-api-key`、`--model-api-protocol` 和 `--model-params` 映射这些字段。

## 基本用法

```bash theme={null}
export MODEL_BASE_URL="https://your-endpoint/v1"
export MODEL_API_KEY="sk-..."

agentcompass run \
  screenspot \
  qwen3vl_gui \
  qwen3-vl \
  --env <env-provider> \
  --benchmark-params '{"category":"desktop"}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --model-params '{"temperature":0}'
```

凭据建议放在 shell 环境变量中。变量名必须使用下划线，例如 `MODEL_BASE_URL`，不能写成 `model-base-url`。

## Protocol 选择

| Protocol           | 常见用途                                            |
| ------------------ | ----------------------------------------------- |
| `openai-chat`      | OpenAI-compatible chat completions 风格 endpoint。 |
| `openai-responses` | OpenAI Responses API 风格 endpoint。               |
| `anthropic`        | Anthropic Messages API 风格 endpoint。             |
| JSON list          | 当 harness 可以在多个协议间选择时，作为有序 fallback list。       |

如果 `api_protocol` 为空，harness 可能使用自己的默认值。公开文档和可复现命令中建议显式传 protocol。

## Python 用法

```python theme={null}
from agentcompass import run_evaluation

run_evaluation(
    benchmark="screenspot",
    harness="qwen3vl_gui",
    model="qwen3-vl",
    environment="host_process",
    benchmark_params={"category": "desktop"},
    model_base_url="https://your-endpoint/v1",
    model_api_key="sk-...",
    model_api_protocol="openai-chat",
    model_params={"temperature": 0},
)
```

## Judge Models

部分 benchmark 和 analyzer 需要第二个模型做 judge 或 qualitative analysis。它们使用同样的概念字段：model id、base URL、API key、protocol 和 params。

常见位置：

* benchmark judge models: `benchmark_params.judge_model`;
* qualitative analyzer model: `analysis_params.QualitativeAnalyzer`;
* comparison analyzer model: `analysis_params.MultiQualitativeAnalyzer`。

## 常见错误

| 现象                         | 可能原因                                                          |
| -------------------------- | ------------------------------------------------------------- |
| provider 无法识别              | model id 需要底层 client 的 provider prefix，或 harness protocol 配错。 |
| 401 / authentication error | `--model-api-key` 缺失，或 key 不属于当前 endpoint。                    |
| 404 / model not found      | model id 在 `--model-base-url` 对应服务中不存在。                       |
| unsupported protocol       | `--model-api-protocol` 不被当前 harness 支持。                       |

## 相关页面

* [Setup](/zh/get_started/setup)
* [支持的组件](/zh/reference/supported_components)
* [CLI 参考](/zh/reference/cli)
* [配置](/zh/reference/configuration)