模型

每次 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 映射这些字段。

​

基本用法

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 用法

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
• 支持的组件
• CLI 参考
• 配置