跳到主要内容

迁移指南：从 providers 迁移到 model_list

本指南介绍如何从旧版 providers 配置迁移到新的 model_list 格式。

为什么要迁移？​

新版 model_list 配置有以下优势：

  • 零代码接入新提供商：只需修改配置即可添加 OpenAI 兼容的提供商
  • 负载均衡：为同一模型配置多个端点
  • 协议前缀路由：使用 openai/、anthropic/ 等前缀
  • 更清晰的配置结构：以模型为中心，而非以厂商为中心

版本时间线​

版本状态
v1.x引入 model_list，providers 已废弃但仍可用
v1.x+1显著的废弃警告，提供迁移工具
v2.0移除 providers 配置

迁移前后对比​

迁移前：旧版 providers 配置​

{
  "providers": {
    "openai": {
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    },
    "anthropic": {
      "api_key": "sk-ant-your-key"
    },
    "deepseek": {
      "api_key": "sk-your-deepseek-key"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "gpt-5.2"
    }
  }
}

迁移后：新版 model_list 配置​

{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-your-key"
    },
    {
      "model_name": "deepseek",
      "model": "deepseek/deepseek-chat",
      "api_key": "sk-your-deepseek-key"
    }
  ],
  "agents": {
    "defaults": {
      "model": "gpt4"
    }
  }
}

协议前缀​

model 字段使用 [协议前缀/]模型标识符 格式：

前缀说明示例
openai/OpenAI API（默认）openai/gpt-5.2
anthropic/Anthropic APIanthropic/claude-opus-4
antigravity/Google Cloud（OAuth）antigravity/gemini-2.0-flash
gemini/Google Gemini APIgemini/gemini-2.0-flash-exp
openrouter/OpenRouteropenrouter/anthropic/claude-sonnet-4.6
groq/Groq APIgroq/llama-3.1-70b
deepseek/DeepSeek APIdeepseek/deepseek-chat
cerebras/Cerebras APIcerebras/llama-3.3-70b
qwen/通义千问qwen/qwen-max
zhipu/智谱 AIzhipu/glm-4
nvidia/NVIDIA NIMnvidia/llama-3.1-nemotron-70b
ollama/Ollama（本地）ollama/llama3
vllm/vLLM（本地）vllm/my-model
moonshot/Moonshot（Kimi）moonshot/moonshot-v1-8k
volcengine/火山引擎volcengine/doubao-pro-32k
shengsuanyun/神算云shengsuanyun/deepseek-v3

注意：如果不指定前缀，默认使用 openai/。

ModelConfig 字段说明​

字段必填说明
model_name是模型别名（在 agents.defaults.model 中引用）
model是协议前缀 + 模型标识符（如 openai/gpt-5.2）
api_base否API 地址 URL
api_key视情况*API 认证 Key
proxy否HTTP 代理地址
auth_method否认证方式：oauth、token
connect_mode否CLI 提供商连接模式：stdio、grpc
rpm否每分钟请求数限制

*基于 HTTP 的协议需要 api_key，除非 api_base 指向本地服务。

负载均衡​

为同一模型配置多个端点，自动分发请求：

{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-key1",
      "api_base": "https://api1.example.com/v1"
    },
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-key2",
      "api_base": "https://api2.example.com/v1"
    },
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-key3",
      "api_base": "https://api3.example.com/v1"
    }
  ]
}

请求 gpt4 时，会通过轮询方式分发到三个端点。

添加 OpenAI 兼容的新提供商​

使用 model_list 接入新提供商无需改动代码：

{
  "model_list": [
    {
      "model_name": "my-custom-llm",
      "model": "openai/my-model-v1",
      "api_key": "your-api-key",
      "api_base": "https://api.your-provider.com/v1"
    }
  ]
}

只需将协议指定为 openai/（或省略以使用默认值），并提供该提供商的 API 地址即可。

向后兼容​

迁移期间，旧的 providers 配置仍可使用：

  1. 如果 model_list 为空而 providers 有数据，系统会在内部自动转换
  2. 会输出废弃警告："providers config is deprecated, please migrate to model_list"
  3. 所有现有功能保持不变

迁移检查清单​

  • 确认当前使用的所有提供商
  • 为每个提供商创建 model_list 条目
  • 使用正确的协议前缀
  • 将 agents.defaults.model 更新为新的 model_name
  • 测试所有模型正常工作
  • 删除或注释掉旧的 providers 配置段

故障排查​

模型未找到​

model "xxx" not found in model_list or providers

解决：确认 model_list 中的 model_name 与 agents.defaults.model 中的值一致。

未知协议错误​

unknown protocol "xxx" in model "xxx/model-name"

解决：使用支持的协议前缀，参考上方协议前缀表。

缺少 API Key​

api_key or api_base is required for HTTP-based protocol "xxx"

解决：为基于 HTTP 的提供商提供 api_key 和/或 api_base。

需要帮助？​