前言

最近在折腾 Hermes Agent 原型开发，需要频繁切换通义千问、DeepSeek、Kimi、豆包、智谱GLM等国产模型做效果对比。在实操过程中，遇到了绝大多数AI开发者都会碰到的痛点：

• 各大模型厂商独立分配 API-Key，需要维护大量密钥，管理混乱；

• 多平台单独充值，账户余额分散闲置，资金利用率低；

• 不同厂商接口协议、SDK 格式不统一，需要编写多套适配代码；

• Hermes 框架直连各家模型，切换模型就要新增一套 Provider 配置，效率极低。

得益于 Hermes Agent 原生支持OpenAI 兼容自定义端点，我找到了一套极简解决方案：通过统一聚合API网关，仅维护一套密钥，即可无缝切换十余款主流国产大模型。

本篇分享完整可落地的实操流程，包含基础接口调用、Python SDK 实战、Hermes 完整接入配置，全程无复杂改造、开箱即用。

参考官方文档：https://open.dingcloud.com/document_center?id=328&mdId=276

一、方案核心优势：统一 OpenAI 兼容协议

本次实操使用的鼎道模型 Token 服务，完整兼容 OpenAI Chat Completions 标准协议，同时支持 Anthropic 协议，是非常适配 Agent 开发的聚合方案。

核心特性：

• 无需修改业务代码，仅替换 BaseURL 即可完成接入；

• 原生支持流式输出、Temperature、Top_P、Function Calling 等全部主流参数透传；

• 单密钥、单余额，一键切换多款主流国产大模型。

基础接口信息

• 请求地址：https://brain-cloud.dingcloud.com/brain-cloud/api/v1/chat/completions

• 请求方式：POST

• 鉴权方式：Bearer Token

• 支持模型：qwen3.6-plus、deepseek-v4-flash、kimi-k2.6、glm-5.2、doubao-seed-2-1-pro、MiniMax-M2.5

二、基础接口调用实操（可直接运行）

2.1 Curl 快速测试

复制以下命令，替换个人 API Key 即可直接调用，支持流式输出：

curl --location "https://brain-cloud.dingcloud.com/brain-cloud/api/v1/chat/completions" \
 --header "Authorization: Bearer user-xxxxxxxxxxxxxxxx" \
 --header "Content-Type: application/json" \
 --data '{
 "model": "kimi-k2.6",
 "messages": [
 {"role":"system","content":"你是一个乐于助人的助手"},
 {"role":"user","content":"简单介绍向量数据库"}
 ],
 "stream": true
 }'

2.2 Python OpenAI SDK 调用

完全复用 OpenAI 原生写法，仅修改 BaseURL 和 Key，零学习成本：

from openai import OpenAI

# 初始化客户端，仅需替换这两个参数
client = OpenAI(
    api_key="user-xxxxxxxxxxxxxxxx",
    base_url="https://brain-cloud.dingcloud.com/brain-cloud/api/v1"
)

# 切换模型只需修改 model 字段，无需改动其他代码
resp = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[{"role":"user","content":"写一段快速排序python代码"}],
    temperature=0.7,
    stream=True
)

# 流式输出打印
for chunk in resp:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

只需修改 model 字段，即可无缝切换 DeepSeek、GLM、豆包、Kimi 等所有支持模型，非常适合做多模型效果对比测试。

三、Hermes Agent 完整接入配置

Hermes 支持交互式向导、手动配置文件两种接入方式，两种方式均可快速完成部署。

3.1 交互式向导配置（新手推荐）

终端执行配置命令，一键唤起配置向导：

hermes model

按照终端提示依次填写：

1. 选择：Custom endpoint（自定义端点）

2. BaseURL：https://brain-cloud.dingcloud.com/brain-cloud/api/v1

3. 输入个人专属 API Key

4. 填写模型 ID（如 qwen3.6-plus、deepseek-v4-flash）

5. API 兼容模式选择：2. Chat Completions

配置自动保存至 ~/.hermes/config.yaml，无需额外编译，直接生效。

3.2 手动修改配置文件

打开 Hermes 全局配置文件，直接写入以下配置：

model:
  default: "qwen3.6-plus"
  provider: "custom"
  base_url: "https://brain-cloud.dingcloud.com/brain-cloud/api/v1"
  api_key: "user-xxxxxxxxxxxxxxxx"

后续切换模型，仅需修改 default 对应的模型名称，无需重复配置接口和密钥。

3.3 验证接入成功

# 查看当前模型配置
hermes config show

# 启动对话测试
hermes

四、实操踩坑总结（避坑指南）

• BaseURL 必须携带尾部 /v1，缺失会导致 Hermes 接口请求报错；

• 模型 ID 必须严格匹配官方文档标识，不可自定义别名，否则调用失败；

• 首次接入建议先用 Curl 调通接口，排除密钥、权限问题后，再配置 Hermes；

• 流式输出、函数调用均全兼容，无需额外适配框架参数。

五、适用场景总结

这套统一接入方案，非常适合三类开发者：

• Agent 原型开发者：需要横向对比多款国产大模型效果，快速筛选最优模型；

• 个人/小团队开发者：告别多密钥、多账户管理，降低接入和维护成本；

• 轻量化 AI 业务场景：简单问答用轻量模型降本，复杂推理用深度模型提效。

注：核心高并发生产业务，建议提前评估服务稳定性，做好降级、熔断容错策略。