26 · 自定义模型接入

通过 OpenAI / Anthropic 兼容协议，将任意 LLM 接入 Trae——API 网关、自托管、私有部署全覆盖。

01 为什么需要自定义模型

Trae 内置了 8+ 款经过深度适配的模型——Claude Sonnet 4、GPT-5.4、DeepSeek R1、豆包 1.5 Pro 等。这些模型开箱即用，体验经过了 Trae 团队的精心调优。但在某些场景下，内置模型并不够用。

假设你遇到以下任意一种情况：

• 你公司有私有化部署的大模型，出于数据安全考虑，所有代码生成必须走内部 API
• 你发现 Trae 内置的模型定价对你来说太高了，想通过第三方 API 网关以更低价格使用同类能力
• 你想使用 Trae 官方列表里没有的模型——比如最新的 Llama 4、Mistral Large、Qwen 2.5 等
• 你手头有便宜的推理卡（如 4090 / A100），本地跑一个开源模型免费编码
• 你在中国大陆使用 Trae 国际版，但希望降低 API 调用的网络延迟（通过国内中转）

既然 Trae 是一个”你用哪个模型你来定”的工具，那自定义模型接入就是给你一把万能钥匙——不局限于 Trae 为你准备好的选项，你自己决定用哪个模型、从哪里调用、花多少钱。

自定义模型能做什么

Trae（编辑器） ──→ 自定义 API 端点 ──→ 你选择的模型
                      │
                      ├── API 网关（APIYI / OneAPI / etc.）→ 400+ 模型
                      ├── 自托管（Ollama / vLLM / TGI）→ 本地推理
                      └── 私有 API（企业内网模型服务）→ 数据不出域

一句话概括：自定义模型接入 = 你自己控制 Trae 背后的大脑。

02 协议兼容性：OpenAI 与 Anthropic

Trae 的自定义模型接入基于标准 API 协议。它不要求你接入的模型必须是某种特定实现，只要求模型暴露的接口兼容以下两种格式之一。

OpenAI Chat Completions 协议

这是最广泛使用的协议。OpenAI 的 /v1/chat/completions 接口格式几乎成了行业标准——大多数第三方 API 服务、开源模型框架都兼容这个格式。

Trae 调用自定义模型时，发送的请求格式如下：

POST {baseURL}/chat/completions
Authorization: Bearer {apiKey}
Content-Type: application/json
 
{
  "model": "{modelName}",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "stream": true,
  "tools": [...],   // Trae 会传入工具定义（Function Calling）
  "max_tokens": 4096,
  "temperature": 0.1
}

Trae 对 OpenAI 协议的要求：

Anthropic Messages 协议

如果你接入的是 Anthropic 官方 API（Claude 系列）或兼容 Anthropic 协议的服务，Trae 也支持：

POST {baseURL}/messages
x-api-key: {apiKey}
anthropic-version: 2023-06-01
Content-Type: application/json
 
{
  "model": "{modelName}",
  "system": "...",
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "stream": true,
  "tools": [...],
  "max_tokens": 4096
}

如何选择协议

心智模型：provider 字段决定的是**“Trae 用什么格式发请求”，不是”你的模型是什么”。选择 openai provider 接入 Anthropic 的模型也可以——只要你用的 API 网关能把 OpenAI 格式翻译成 Anthropic 格式。但通常建议源原生协议**，减少翻译层出错概率。

03 实战：通过 API 网关接入 400+ 模型

API 网关是自定义模型接入中最实用的场景。你不需要自己架设 GPU 服务器，只需要找一个第三方 API 服务商，通过它使用数百种模型。

为什么需要 API 网关

API 网关解决的问题很简单：一个 API Key，访问几百种模型。

┌───── 无网关 ────────────────────┐
│ Claude → 一个账号 / 一个 API Key │
│ GPT    → 另一个账号 / 另一个 Key │
│ Llama  → 再注册一个服务         │
│ Qwen   → 再再注册一个服务       │
└─────────────────────────────────┘

┌───── 有网关 ────────────────────┐
│          ┌──────────────┐       │
│  Trae ──→│   API 网关    │──→ 任何模型 │
│          │  (APIYI /    │       │
│          │   OneAPI)    │       │
│          └──────────────┘       │
│ 一个 Key，统一计费，统一接口      │
└─────────────────────────────────┘

以 APIYI 为例的配置全流程

APIYI  是一个流行的 LLM API 网关（2026 年国内开发圈使用较多），支持 400+ 模型，包括 Claude、GPT、Gemini、DeepSeek、Qwen、Llama、Mistral 等。

步骤 1：注册并获取 API Key

在 APIYI 注册账号 → 充值（支持支付宝） → 获取 API Key。

步骤 2：确认 API 地址

APIYI 通常提供一个统一的 OpenAI 兼容端点：

Base URL: https://api.apiyi.com/v1

步骤 3：在 Trae 中配置自定义模型

打开 Trae 设置：

1. Cmd + , 打开设置
2. 搜索 Custom API
3. 添加自定义 Provider：

{
  "trae.customProviders": [
    {
      "name": "apiyi",
      "displayName": "APIYI 网关",
      "provider": "openai",
      "apiKey": "sk-apiyi-你的真实密钥",
      "baseURL": "https://api.apiyi.com/v1",
      "models": [
        "gpt-5.4",
        "claude-sonnet-4-20260514",
        "gemini-2.5-pro",
        "deepseek-r1",
        "qwen-3-coder",
        "llama-4-scout",
        "mistral-large-2505"
      ]
    }
  ]
}

重要：models 列表要填写 API 网关实际支持的模型 ID，不是你的想象。不同网关的模型名称可能不同（如 claude-sonnet-4-20260514 或 claude-sonnet-4）。查看网关的文档确认正确的模型 ID。

步骤 4：验证

配置保存后，在 Trae 的模型选择器中应该能看到 APIYI 网关 和你列出的所有模型。随便选一个发一条消息测试：

你：1 + 1 等于几？
（如果模型正常回复，配置成功）

网关之间怎么选

一个实用的建议：如果你是国内开发者，想用 Claude 又不想忍受高延迟和昂贵的官方定价——通过 APIYI 这类网关用 Claude sonnet 4，价格通常是官方的 1/3 到 1/2，延迟还更低（因为网关在国内有网络优化）。代价呢？可靠性不如官方——网关偶尔会有过载、限流、模型版本落后的问题。

配置技巧：同时使用多个网关

Trae 支持配置多个自定义 provider，你可以同时用两个网关，甚至网关 + 内置模型混用：

{
  "trae.customProviders": [
    {
      "name": "apiyi",
      "displayName": "APIYI 网关",
      "provider": "openai",
      "apiKey": "sk-apiyi-xxx",
      "baseURL": "https://api.apiyi.com/v1",
      "models": ["claude-sonnet-4", "gpt-5.4"]
    },
    {
      "name": "groq",
      "displayName": "Groq (超快推理)",
      "provider": "openai",
      "apiKey": "gsk_xxx",
      "baseURL": "https://api.groq.com/openai/v1",
      "models": ["llama-4-scout-17b", "mixtral-8x7b-32768"]
    }
  ]
}

所有模型都出现在同一个下拉选择器中，随时切换，互不干扰。

04 配置自定义端点的完整步骤

上一个章节以 APIYI 为例做了快速配置。这一节我们用更系统的方式梳理配置的全流程，以及每个字段的含义。

配置入口

Trae 中自定义模型的配置有三处入口，效果相同：

配置字段详解

{
  "trae.customProviders": [
    {
      "name": "my-provider",           // 必需，内部标识，唯一
      "displayName": "我的自定义模型",   // 可选，显示在模型选择器中的名称
      "provider": "openai",            // 必需，"openai" 或 "anthropic"
      "apiKey": "sk-xxx",             // 必需，API 密钥
      "baseURL": "https://...",       // 必需，API 基础地址
      "models": ["model-a", "model-b"], // 必需，可用模型列表
      "config": {                      // 可选，额外配置
        "maxTokens": 8192,
        "temperature": 0.3
      }
    }
  ]
}

各字段的最佳实践

name — 简短、无空格、字母数字 + 下划线。如 my-company-llm、apiyi、local-ollama。

displayName — 如果你不填，模型选择器里会显示 name。建议填一个友好的名字，比如”公司内部模型”、“本地 Ollama”。

provider — 这是最重要的字段，决定了 Trae 用什么 API 格式发请求。选错了会导致”401 认证错误”或”404 接口找不到”。

快速判断：如果你的 API 文档里有 POST /v1/chat/completions，选 openai。如果文档里有 POST /messages 和 x-api-key header，选 anthropic。

apiKey — 安全提醒：不要把 API Key 硬编码在分享的配置中。Trae 支持通过环境变量注入：

{
  "apiKey": "${MY_CUSTOM_API_KEY}"
}

然后在 shell 配置文件（.zshrc 或 .bashrc）中设置 export MY_CUSTOM_API_KEY=sk-xxx。

baseURL — 注意：不要包含具体路径。Trae 会根据 provider 自动拼接路径。例如 openai provider 会在 baseURL 后加 /chat/completions，anthropic 加 /messages。所以：

✅ 正确: https://api.apiyi.com/v1
❌ 错误: https://api.apiyi.com/v1/chat/completions（Trae 会拼成 v1/chat/completions/chat/completions）

models — 列出的模型 ID 必须和 API 端点实际接受的 model 参数一致。建议先 curl 测试：

curl https://api.apiyi.com/v1/models \
  -H "Authorization: Bearer sk-xxx" \
  | jq '.data[].id'

这条命令会列出网关支持的所有模型 ID。

测试配置是否成功

配置完不要急着关设置。做这三个测试：

1. 列表可见：模型选择器下拉中出现了你的自定义模型
2. 简单对话：Chat 模式下发一条 “Hello”，看能否正常回复
3. 代码生成：让模型写一段代码（如 “用 Python 写一个快速排序”），确认输出质量可选

如果测试 1 失败：检查 models 字段是否有笔误。 如果测试 2 失败：检查 baseURL 和 apiKey。 如果测试 3 失败（模型能说话但代码质量差）：这是模型本身的问题，不是配置问题——下一节详细讨论。

05 自托管模型集成：Ollama

接下来我们进入更”硬核”的场景：在自己的机器上运行模型。

为什么要自托管

• 免费：模型推理不需要按 token 付费，只要你付电费和硬件钱
• 隐私：你的代码永远不会离开本地机器
• 离线可用：不需要互联网连接
• 完全控制：你可以用任何模型，随时换，任意微调

用 Ollama 接入 Trae

Ollama  是本地运行大模型最简便的工具，支持 macOS / Linux / Windows。

步骤 1：安装 Ollama

# macOS
brew install ollama
 
# Linux
curl -fsSL https://ollama.ai/install.sh | sh

步骤 2：拉取模型

# 拉取一个编码能力不错的模型（大小约 4-8GB）
ollama pull qwen2.5-coder:7b
 
# 其他推荐选项
ollama pull llama-4-scout:7b    # Meta 最新的轻量模型
ollama pull deepseek-coder:6.7b  # DeepSeek 编码专项
ollama pull mistral:7b          # Mistral 通用模型

步骤 3：启动 Ollama 服务

ollama serve
# 默认监听 http://localhost:11434

步骤 4：确认 OpenAI 兼容端点可用

Ollama 从 0.3.0 版本开始内置了 OpenAI 兼容 API：

# 测试
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder:7b",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

如果返回正常，说明 API 端点可用。

步骤 5：在 Trae 中配置

{
  "trae.customProviders": [
    {
      "name": "local-ollama",
      "displayName": "本地 Ollama",
      "provider": "openai",
      "apiKey": "ollama",            // Ollama 不验证 API Key，填任何值都可以
      "baseURL": "http://localhost:11434/v1",
      "models": ["qwen2.5-coder:7b", "llama-4-scout:7b", "deepseek-coder:6.7b"]
    }
  ]
}

Ollama 模型的”性格评估”

下表是我在实际使用中整理的本地模型表现，供你参考（7-8B 参数级别）：

注意：7B 级别的本地模型整体能力大约相当于 GPT-3.5 到 GPT-4 之间的水平。它们能处理基础的 CRUD、编写单元测试、做简单的重构——但对于复杂架构设计、大型代码库重构，效果会明显不如商用模型。这不是 Ollama 的问题，是参数量的物理限制。

06 自托管模型集成：vLLM

如果说 Ollama 适合个人本地使用，那 vLLM 适合专业部署。vLLM 是一个高性能推理引擎，支持更大的模型（34B、70B、甚至 180B），通过 PagedAttention 技术大幅提升吞吐量。

vLLM vs Ollama 对比

vLLM 配置步骤

步骤 1：安装 vLLM

# 推荐在 Python 3.10+ 环境下安装
pip install vllm
 
# 如果你有 CUDA 12.1+
pip install vllm[cuda]

步骤 2：启动模型服务

# 启动 Qwen 2.5 Coder 7B（单卡 24GB+ 即可）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-7B-Instruct \
  --port 8000 \
  --max-model-len 8192
 
# 或者更大的 DeepSeek V2（需要多卡）
python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V2-Lite \
  --port 8000 \
  --tensor-parallel-size 2  # 两张 GPU

步骤 3：确认端点

vLLM 默认提供 OpenAI 兼容端点：

Base URL: http://localhost:8000/v1

步骤 4：在 Trae 中配置

{
  "trae.customProviders": [
    {
      "name": "vllm-local",
      "displayName": "vLLM 本地服务",
      "provider": "openai",
      "apiKey": "not-needed",
      "baseURL": "http://localhost:8000/v1",
      "models": ["Qwen/Qwen2.5-Coder-7B-Instruct"]
    }
  ]
}

性能调优提示

如果你发现 vLLM 在 Trae 中响应偏慢，可以调整以下参数：

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-7B-Instruct \
  --port 8000 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.95 \   # 更大限度利用显存
  --max-num-batched-tokens 4096 \    # 控制批处理大小
  --enforce-eager                     # 禁用图优化（减少首 token 延迟）

07 工具调用（Function Calling）兼容性

自定义模型接入 Trae 后面临的最大挑战不是”能不能说话”，而是**“能不能调用工具”**。

为什么工具调用如此重要

Trae 的核心能力（Builder 模式、SOLO 模式、代码编辑、文件操作）全都依赖工具调用——模型不是直接输出文本，而是输出”我要执行什么操作”，Trae 再根据这个操作去读写文件、运行命令。

Trae 给模型的请求:
  "请创建一个新的 React 组件 Button"
  + 工具列表: [read_file, write_file, run_terminal, search_code...]

模型返回:
  {
    "content": "我来创建一个 Button 组件...",
    "tool_calls": [
      {"function": {"name": "write_file", "arguments": "{\"path\":\"...\",\"content\":\"...\"}"}},
      {"function": {"name": "run_terminal", "arguments": "{\"command\":\"npm install\"}"}}
    ]
  }

如果模型无法正确输出 tool_calls，Trae 的行动能力就降级为”能聊天的文本助手”，无法操作文件、无法运行代码。

哪些模型能正确支持工具调用

根据我的测试经验：

如果工具调用不工作怎么办

如果自定义模型能正常对话，但在 Builder / SOLO 模式下无法操作文件，很可能是工具调用出了问题。你可以：

1. 降级到 Chat 模式——Chat 模式不依赖模型的自主工具调用，你可以在对话中让模型生成代码，然后手动复制粘贴
2. 换一个 API 网关——有时候不是模型不行，是网关没有正确转发工具调用参数。尝试换一个网关（如从 APIYI 换到 OneAPI）
3. 升级模型——如果用的是 7B 本地模型，换到 14B 或 34B 通常会显著改善工具调用质量

一个残酷的事实：目前 7B 级别及以下的模型，工具调用的可靠性远不如商用模型。如果你重度依赖 SOLO 模式，自托管小模型的体验会让你失望。工具调用是门槛，不是所有模型都能跨过。

08 成本对比：自定义 vs 内置

“自定义模型比内置模型便宜”是大多数人的第一直觉。但实际情况更复杂。

成本构成对比

具体价格对比（API 网关 vs 官方 API）

以 Claude Sonnet 4 为例：

成本效率公式

选择自定义模型时，不要只看”价格”，要看**“有效代码产出/每元”**：

成本效率 = 模型生成的可用代码量 ÷ 成本（元）

示例：
- Claude Sonnet 4（官方）：生成 1000 行代码需要 $0.50，其中 950 行可直接用
  → 效率 = 1900 行/美元

- Qwen 2.5 Coder 7B（本地）：生成 1000 行代码需要 $0（电费忽略），但只有 500 行可用
  → 效率 = 无限大...不对
  → 关键是你的**调试时间**：修复那 500 行不可用的代码可能需要 30 分钟

时间成本是隐性的大头。如果便宜模型生成的代码质量差，你花在调试和修复上的时间可能远超省下的 API 费用。

09 质量预期：自定义模型到底行不行

这是最需要管理预期的一节。不是所有模型都适合放在 Trae 里用。

质量分级

什么场景下自定义模型够用

✅ 够用场景：

1. 简单的 CRUD 代码生成——增删改查、REST API 端点、数据模型定义。7B 模型也能轻松胜任
2. 单元测试编写——“给这个函数写测试”大部分模型都能完成得很好
3. 注释和文档生成——不涉及逻辑，主要考验语言能力，小模型也够
4. 代码解释——“这段代码在做什么”不需要创造能力，小模型表现不错
5. 代码翻译——从 Python 翻译到 TypeScript，7B 模型也能做到 80% 准确

❌ 不够用场景：

1. 复杂架构设计——微服务拆分、设计模式选择、大型重构，小模型完全无法胜任
2. Builder 模式自动化——Builder 依赖模型的 tool calling 编排，本地小模型经常搞乱步骤
3. SOLO 模式自主开发——SOLO 需要模型有自主规划能力，小模型常常在第三步就迷失方向
4. 大型代码库理解——超过 10000 行代码的项目，小模型的注意力完全不够用
5. Security / SQL 注入检测——这类场景需要深刻理解代码语义，小模型容易漏报

一句话总结质量预期：自定义模型（尤其是本地小模型）适合做”体力活”——写重复的样板代码、填单元测试、加注释。但对于需要”脑力”的工作——架构决策、安全审查、复杂重构——还是得用 Trae 内置的顶级商用模型。

10 自定义模型接入的心智模型

到了这里，你应该对自定义模型的能力和边界有了整体认识。让我用一个心智模型帮你建立直觉。

“瑞士军刀” vs “专业工具"

如果把 Trae 内置模型比作专业工具：
  Claude Sonnet 4 = 手术刀（精准，昂贵）
  GPT-5.4         = 电锯（快速，猛烈）
  DeepSeek R1     = 激光测量仪（专精一域）

自定义模型的作用是给你的工具箱里加几把不那么贵但够用的工具：
  7B 本地模型     = 普通螺丝刀（哪里都能用一下，但干不了细活）
  14B 本地模型    = 电动螺丝刀（效率高一些，但依然有局限）
  API 网关模型    = 各种平价替代品（比正品便宜，偶尔出小毛病）

"三个”问题帮你决定

问题 1：你主要的 Trae 使用模式是什么？

• 90% Chat 模式（对话式编码） → 自定义模型可用
• 重度使用 Builder / SOLO → 不建议完全依赖自定义模型

问题 2：你的项目复杂度如何？

• 小项目（< 10 个文件） → 自定义模型完全够用
• 中等项目（10-100 个文件） → 自定义模型主力，关键任务切回内置
• 大型项目（100+ 文件） → 谨慎，建议内置模型为主

问题 3：你的预算多少？

• $0/月（纯免费） → 本地 Ollama + 国内免费模型
• $10-30/月 → API 网关（省钱还能用好模型）
• $30+/月 → Trae 国际版套餐 + 内置模型（省心省力）

推荐配置方案

11 常见问题与排错

Q: 配置了自定义模型，但在模型选择器中看不到

原因：JSON 格式错误或 name 字段冲突。 解决：检查 JSON 是否有尾逗号（JSON 不允许尾逗号），确保 name 不和其他 provider 重复。

Q: 模型可以对话，但不能读写文件

原因：工具调用（Function Calling）不兼容。 解决：看第 07 节的工具调用兼容性表。如果是 API 网关问题，尝试换一个网关。如果是本地小模型，考虑升级到 14B 以上。

Q: 响应特别慢，经常超时

原因：网络延迟（通过网关）或本地推理速度慢。 解决：

• API 网关：检查你的网络环境，考虑换一个国内延迟低的网关
• Ollama/vLLM：降低 max_tokens，或在 vLLM 中调小 max-model-len
• 如果首 token 延迟超过 10 秒，Trae 可能会自动超时断连

Q: 自定义模型的响应频繁被截断

原因：max_tokens 设置太小。Trae 默认传给模型的 max_tokens 是 4096，如果模型生成的代码较长可能会被截断。 解决：在配置中增加 maxTokens：

{
  "trae.customProviders": [
    {
      "name": "my-model",
      "config": {
        "maxTokens": 16384
      }
    }
  ]
}

Q: 用 API 网关的模型，代码质量不如预期

原因：API 网关可能用的不是模型最新版本。比如”Claude Sonnet 4”在官方是最新版，但在一些网关中可能是旧版 checkpoint。 解决：用网关前先在网关自己的 Playground 里测试，确认质量可接受。定期更新网关端的模型 ID。

12 小结

自定义模型接入是 Trae 中最强大的”开放能力”之一。它让 Trae 从一个**“只能使用平台准备的模型”的工具，变成了一个”你决定用什么大脑”**的平台。

但能力越大，责任越大——不是所有模型都适合放进 Trae。工具调用、编码质量、响应速度、稳定性——每个维度都是选择自定义模型时需要权衡的变量。

我的建议很简单：让内置模型做”建筑师”（架构设计、复杂重构），让自定义模型做”建筑工人”（写单元测试、填 CRUD）。两者各司其职，你才能在成本和效率之间找到最佳平衡点。

下一篇： 27 · Trae 中的 Prompt 工程最佳实践 —— 掌握与 AI 高效沟通的技巧，让每个模型发挥最大效能。