Hermes Gateway 多模型切换 — 完整教程

1. 这是什么

让 Hermes Gateway v0.13.0 支持在阿里云百炼的多个模型之间切换，通过钉钉或飞书直接对话切换，不用 SSH 改配置。

支持的模型包括：

  • 百炼 Coding Plan：kimi-k2.5、qwen3.6-plus、glm-5 等

  • 百炼 DeepSeek MaaS：deepseek-v4-pro、deepseek-v4-flash、deepseek-chat、deepseek-reasoner、deepseek-coder 等

2. 运行原理

用户在钉钉发 "切 ds"
  ↓
AI Agent 读取 SKILL_system.md
  ↓ "切 ds" → system_switch_model("alibaba-bailian-deepseek", "deepseek-v4-pro")
  ↓
MCP 服务器 system_mcp.py 收到请求
  ↓
① 读取 /root/.hermes/config.yaml
② 修改 model.provider → alibaba-bailian-deepseek
③ 修改 model.default → deepseek-v4-pro
④ 写回 config.yaml
⑤ 后台执行 systemctl restart hermes-gateway（延迟 2 秒）
  ↓
Gateway 重启，新模型生效
  ↓
AI 回复："模型切换成功！之前: kimi-k2.5 → 现在: deepseek-v4-pro，约 5 秒后生效"

3. 为什么有两个 Provider

阿里云百炼的模型分散在两个不同的 API 端点：

Provider 名 API 端点 用的模型
alibaba-coding-plan https://coding.dashscope.aliyuncs.com/v1 Kimi、千问、GLM、MiniMax 等
alibaba-bailian-deepseek https://llm-ds.aliyuncs.com/compatible-mode/v1 DeepSeek V3/V4/R1 等

两个端点用 不同的 API Key：

  • Coding Plan：`sk-sp-f0677fbb2c74461*****

  • DeepSeek MaaS：`sk-213f7ee4ea7142598b*****

4. 遇到的坑：DeepSeek SSL 证书问题

4.1 问题

DeepSeek MaaS 的原始域名是：

llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com

这个域名的 SSL 证书是：

CN = *.aliyuncs.com（一级通配符）

但 cn-beijing.maas.aliyuncs.com 有两级子域名（cn-beijing + maas），Python 的 SSL 模块不支持跨级通配符匹配。

所以 httpx（Python HTTP 库）在连接时报错：

SSL: CERTIFICATE_VERIFY_FAILED
certificate is not valid for 'llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com'

4.2 解决方案

在服务器 /etc/hosts 文件中添加域名映射，把真实 IP 解析到一个单级子域名 llm-ds.aliyuncs.com。

单级子域名 llm-ds.aliyuncs.com 匹配证书 *.aliyuncs.com，TLS 验证通过。

# /etc/hosts 中添加的行
8.152.159.24 llm-ds.aliyuncs.com

然后把 config.yaml 中的 base_url 从：

https://llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

改成：

https://llm-ds.aliyuncs.com/compatible-mode/v1

注意： IP 地址可能会变化，因为百炼用的是阿里云 NLB（网络负载均衡）。如果某天连不上了，重新获取 IP：

getent hosts llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com
# 选输出的第一个 IP，更新 /etc/hosts

5. 修改的文件（完整列表）

5.1 修改的服务器文件

文件在服务器上的完整路径 修改了什么 修改类型
/etc/hosts 添加 8.152.159.24 llm-ds.aliyuncs.com 一行 系统配置修改
/root/.hermes/config.yaml 添加 DeepSeek provider + available_models + system MCP + system skill 配置文件修改
/root/.hermes/.env 添加 DEEPSEEK_API_KEY 和 DEEPSEEK_BASE_URL（以后可废弃） 环境变量

5.2 新增的服务器文件

文件在服务器上的完整路径 用途
/root/.hermes/servers/system_mcp.py MCP 服务器：提供一个 system_switch_model 工具，AI 可以调用它来切换模型
/root/.hermes/skills/system/SKILL.md 技能文档：告诉 AI 用户说各种模型名时应该调什么参数
/root/switch_model.sh 命令行脚本：管理员 SSH 时手动切换模型用

5.3 config.yaml 的关键改动（对比）

# ===== 修改前（修改前/config.yaml）=====
​
model:
  default: kimi-k2.5                  # 默认模型
  provider: alibaba-coding-plan        # 默认只用 Coding Plan
  base_url: https://coding.dashscope.aliyuncs.com/v1
  available_models:
    alibaba-coding-plan:
      - kimi-k2.5
      - qwen3.6-plus
    alibaba-bailian-deepseek:          # DeepSeek 模型虽然列了，但没有可用的 provider 配置
      - deepseek-chat
      - deepseek-coder
      - deepseek-reasoner
      - deepseek-v4-pro
      - deepseek-v4-flash
​
providers:
  alibaba-coding-plan:
    base_url: https://coding.dashscope.aliyuncs.com/v1
    api_key: YOUR_API_KEY_HERE         # ← 错误！占位符！
​
  alibaba-bailian-deepseek:
    base_url: https://llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    api_key: sk-213f7ee4ea7142598baca0f4**********
    # ← 这个 base_url 的 SSL 证书有问题，连不上！
​
# ===== 修改后（修改后/config.yaml）=====
​
model:
  default: deepseek-v4-pro             # 默认改为 DeepSeek V4 Pro
  provider: alibaba-bailian-deepseek    # 默认用 DeepSeek provider
  available_models:
    alibaba-coding-plan:
      - kimi-k2.5
      - qwen3.6-plus
    alibaba-bailian-deepseek:
      - deepseek-v4-pro
      - deepseek-v4-flash
      - deepseek-chat
      - deepseek-reasoner
      - deepseek-coder
​
providers:
  alibaba-coding-plan:
    base_url: https://coding.dashscope.aliyuncs.com/v1
    api_key: sk-sp-f0677fbb2c74461fad**********  # ← 修复！真实 Key
​
  alibaba-bailian-deepseek:
    base_url: https://llm-ds.aliyuncs.com/compatible-mode/v1   # ← 修复！用了 /etc/hosts 映射的域名
    api_key: sk-213f7ee4ea7142598baca0f**********
​
# 新增 ↓↓↓
skills:
  external_dirs:
    - /root/.hermes/skills/hr
    - /root/.hermes/skills/system     # ← 新增 system 技能目录
​
mcp_servers:
  hr-agent:
    command: python3.11
    args:
      - /root/.hermes/servers/hr_mcp.py
    enabled: true
  system:                              # ← 新增 system MCP 服务器
    command: python3.11
    args:
      - /root/.hermes/servers/system_mcp.py
    enabled: true

6. 新增文件详解

6.1 /root/.hermes/servers/system_mcp.py — 模型切换 MCP 服务器

这个文件是一个 MCP JSON-RPC 服务器，通过 stdin/stdout 与 Hermes Gateway 通信。

它暴露了一个工具：system_switch_model(provider, model)

# ===== 核心逻辑：switch_model 函数 =====
​
def switch_model(provider: str, model: str) -> str:
    # 1. 读取当前配置
    with open("/root/.hermes/config.yaml", "r") as f:
        config = yaml.safe_load(f)
​
    old_provider = config["model"]["provider"]   # 记住旧的 provider
    old_model = config["model"]["default"]        # 记住旧的模型
​
    # 2. 写入新配置
    config["model"]["provider"] = provider
    config["model"]["default"] = model
    with open("/root/.hermes/config.yaml", "w") as f:
        yaml.dump(config, f, ...)
​
    # 3. 后台重启 Gateway（延迟 2 秒，确保当前响应先发出去）
    subprocess.Popen(
        ["/usr/bin/bash", "-c", "sleep 2 && systemctl restart hermes-gateway"],
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
    )
​
    return f"模型切换成功！之前: {old_provider}/{old_model} → 现在: {provider}/{model}"

完整的 MCP 协议处理流程：

Gateway 启动
  ↓
启动 system_mcp.py 子进程
  ↓
Gateway 发送 initialize → system_mcp 返回协议版本和服务器信息
  ↓
Gateway 发送 tools/list → system_mcp 返回工具列表 [system_switch_model]
  ↓
AI 需要切换模型时 → Gateway 发送 tools/call {"name":"system_switch_model","arguments":{...}}
  ↓
system_mcp 执行 switch_model() → 修改配置 → 重启 Gateway → 返回结果

6.2 /root/.hermes/skills/system/SKILL.md — AI 行为指南

这个文件告诉 AI Agent：当用户说某些话时，应该调哪个 MCP 工具、传什么参数。

# ---- SKILL.md 的核心内容 ----
​
## 切换模型
​
用户可通过对话切换底层 AI 模型。调用 MCP 工具即可：
    system_switch_model(provider="...", model="...")
​
### 百炼 DeepSeek (alibaba-bailian-deepseek)
| 用户说法                          | 调什么 MCP 工具                            |
|----------------------------------|-------------------------------------------|
| 切 ds / deepseek / ds-v4 / ds-pro | system_switch_model("alibaba-bailian-deepseek", "deepseek-v4-pro") |
| 切 ds-flash / ds-v4-flash        | system_switch_model("alibaba-bailian-deepseek", "deepseek-v4-flash") |
| 切 ds-v3 / ds-chat               | system_switch_model("alibaba-bailian-deepseek", "deepseek-chat") |
| 切 ds-r1 / ds-reasoner           | system_switch_model("alibaba-bailian-deepseek", "deepseek-reasoner") |
| 切 ds-coder / ds-code            | system_switch_model("alibaba-bailian-deepseek", "deepseek-coder") |
​
### Coding Plan (alibaba-coding-plan)
| 用户说法                          | 调什么 MCP 工具                            |
|----------------------------------|-------------------------------------------|
| 切 kimi / 用kimi                  | system_switch_model("alibaba-coding-plan", "kimi-k2.5") |
| 切 qwen / 千问                    | system_switch_model("alibaba-coding-plan", "qwen3.6-plus") |
​
### 通用规则
如果用户说的模型名不在上面，根据上下文推断 provider：
- 提到 deepseek → alibaba-bailian-deepseek
- 提到 kimi/qwen → alibaba-coding-plan
直接用用户说的模型名调用 system_switch_model，让 API 自行验证。

6.3 /root/switch_model.sh — 命令行切换脚本

给管理员 SSH 时手动用的，AI 在 Gateway 模式下没 bash 权限所以用不了（AI 用 MCP 工具切换）。

#!/bin/bash
# 用法: /root/switch_model.sh <provider名> <模型名>
# 例子:
#   /root/switch_model.sh alibaba-coding-plan kimi-k2.5
#   /root/switch_model.sh alibaba-bailian-deepseek deepseek-v4-pro
​
PROVIDER="${1:-alibaba-coding-plan}"   # 参数1: provider，默认 coding-plan
MODEL="${2:-kimi-k2.5}"                 # 参数2: 模型名，默认 kimi-k2.5
CONFIG="/root/.hermes/config.yaml"
​
# 用 Python 一行修改 YAML
/usr/local/lib/hermes-agent/venv/bin/python3 -c "
import yaml
with open('$CONFIG', 'r') as f:
    c = yaml.safe_load(f)
c['model']['provider'] = '$PROVIDER'
c['model']['default'] = '$MODEL'
with open('$CONFIG', 'w') as f:
    yaml.dump(c, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
print(f'Switched to provider=$PROVIDER model=$MODEL')
"
​
# 重启 Gateway
systemctl restart hermes-gateway
sleep 3
grep '✓ dingtalk connected\|✓ feishu' /root/.hermes/logs/agent.log | tail -2
echo "Done. Model: $PROVIDER / $MODEL"

7. 使用方式

方式一：在钉钉/飞书中对话切换（推荐）

直接在聊天框里说：

你说什么 实际切换到
切 ds / 用 deepseek / ds-pro deepseek-v4-pro
切 ds-flash / ds-v4-flash deepseek-v4-flash
切 ds-v3 / ds-chat deepseek-chat
切 ds-r1 / ds-reasoner deepseek-reasoner
切 ds-coder deepseek-coder
切 kimi / 用 kimi kimi-k2.5
切 qwen / 用千问 qwen3.6-plus
切换到 deepseek-v4-pro deepseek-v4-pro（直接说全名也行）

AI 会自动调 system_switch_model，修改配置 + 重启 Gateway，约 5 秒后生效。

方式二：SSH 命令行切换

ssh -i sshdev.pem root@8.149.132.10
​
# 切到 DeepSeek V4 Pro
/root/switch_model.sh alibaba-bailian-deepseek deepseek-v4-pro
​
# 切到 Kimi
/root/switch_model.sh alibaba-coding-plan kimi-k2.5
​
# 切到千问
/root/switch_model.sh alibaba-coding-plan qwen3.6-plus

8. 部署步骤（从头开始配一个新服务器）

# ===== 前置条件：已有 SSH 连接 =====
ssh -i sshdev.pem root@8.149.132.10
​
# ===== 步骤1：修复 DeepSeek SSL 问题 =====
# 获取 DeepSeek API 端点的真实 IP
getent hosts llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com
# 输出类似：8.152.159.24  llm-9vj2mzeh6ws8xx3y...
​
# 将 IP 映射到单级子域名（匹配 SSL 证书 *.aliyuncs.com）
echo "8.152.159.24 llm-ds.aliyuncs.com" >> /etc/hosts
​
# 验证 SSL 连接（不报错就是成功）
curl -s "https://llm-ds.aliyuncs.com/compatible-mode/v1/models" \
  -H "Authorization: Bearer sk-213f7ee4ea7142598baca0f4ae1e5c3b" | head -50
​
# ===== 步骤2：部署 config.yaml =====
# 退出 SSH，在本地执行
scp -i sshdev.pem 修改后/config.yaml root@8.149.132.10:/root/.hermes/config.yaml
​
# ===== 步骤3：部署 system_mcp.py =====
scp -i sshdev.pem 新增文件/system_mcp.py root@8.149.132.10:/root/.hermes/servers/system_mcp.py
​
# ===== 步骤4：部署 SKILL_system.md =====
ssh -i sshdev.pem root@8.149.132.10 "mkdir -p /root/.hermes/skills/system"
scp -i sshdev.pem 新增文件/SKILL_system.md root@8.149.132.10:/root/.hermes/skills/system/SKILL.md
​
# ===== 步骤5：部署 switch_model.sh（可选） =====
scp -i sshdev.pem 新增文件/switch_model.sh root@8.149.132.10:/root/switch_model.sh
ssh -i sshdev.pem root@8.149.132.10 "chmod +x /root/switch_model.sh"
​
# ===== 步骤6：重启 Gateway =====
ssh -i sshdev.pem root@8.149.132.10 "systemctl restart hermes-gateway"
​
# ===== 步骤7：确认启动成功 =====
ssh -i sshdev.pem root@8.149.132.10 "systemctl status hermes-gateway | head -5"
ssh -i sshdev.pem root@8.149.132.10 "grep '✓ dingtalk connected' /root/.hermes/logs/agent.log | tail -1"
# 应该输出: 20xx-xx-xx xx:xx:xx INFO gateway.run: ✓ dingtalk connected

9. 本目录文件清单

hermes_gateway的切换模型教程/
├── README.md                       ← 你正在看的这个文件
├── 修改前/
│   └── config.yaml                 ← 原始的 Hermes 配置（只有 Coding Plan，base_url 还有 SSL 问题）
├── 修改后/
│   ├── config.yaml                 ← 当前运行的配置（双 provider + 多模型 + SSL 修复 + system MCP 注册）
│   └── .env                        ← 当前环境变量
└── 新增文件/
    ├── system_mcp.py               ← 模型切换 MCP 服务器（提供 system_switch_model 工具）
    ├── switch_model.sh             ← 命令行快速切换脚本
    └── SKILL_system.md             ← AI 行为指南（告诉 AI 怎么理解"切ds"）

所有文件在服务器上的完整路径一览

本地文件 服务器路径 类型
修改前/config.yaml (原始版本，仅供参考) 参考
修改后/config.yaml /root/.hermes/config.yaml 运行时配置
修改后/.env /root/.hermes/.env 环境变量
新增文件/system_mcp.py /root/.hermes/servers/system_mcp.py MCP 服务器
新增文件/SKILL_system.md /root/.hermes/skills/system/SKILL.md 技能文档
新增文件/switch_model.sh /root/switch_model.sh 管理脚本
(无文件，手动添加) /etc/hosts 系统 hosts 文件

10. 当前可用模型速查表

alibaba-coding-plan（百炼 Coding Plan）

端点：https://coding.dashscope.aliyuncs.com/v1

模型名 全称/说明
kimi-k2.5 Moonshot Kimi K2.5
kimi-k2-thinking Kimi K2 思考模式
kimi/kimi-k2.5 Kimi K2.5（完整路径）
qwen3.6-plus 通义千问 3.6 Plus
qwen3.6-flash 通义千问 3.6 Flash（快）
qwen3.6-max-preview 通义千问 3.6 Max（强）
qwen3-max 通义千问 3 Max
qwen-plus 通义千问 Plus
qwen-flash 通义千问 Flash
glm-5 / glm-5.1 智谱 GLM-5
MiniMax-M2.5 MiniMax M2.5
qwq-plus Qwen QwQ Plus（推理）

alibaba-bailian-deepseek（百炼 DeepSeek MaaS）

端点：https://llm-ds.aliyuncs.com/compatible-mode/v1

模型名 全称/说明
deepseek-v4-pro DeepSeek V4 Pro（最强）
deepseek-v4-flash DeepSeek V4 Flash（快）
deepseek-chat DeepSeek V3 对话
deepseek-reasoner DeepSeek R1 推理
deepseek-coder DeepSeek Coder 编程
deepseek-v3.2 DeepSeek V3.2
deepseek-r1 DeepSeek R1
vanchin/deepseek-v3 DeepSeek V3（硅基流动）
vanchin/deepseek-r1 DeepSeek R1（硅基流动）

要添加新模型，只需在 config.yaml 的 model.available_models 对应 provider 下加一行即可。

11. 故障排查

现象 可能原因 检查命令
切模型后报错 provider 配置不对 grep "provider=custom" /root/.hermes/logs/agent.log
DeepSeek 连不上 SSL 或 hosts 问题 curl https://llm-ds.aliyuncs.com/compatible-mode/v1/models -H "Authorization: Bearer sk-xxx"
system MCP 未注册 config.yaml 没配置 grep "system.*registered" /root/.hermes/logs/agent.log
切换后没反应 Gateway 重启失败 systemctl status hermes-gateway + tail -30 /root/.hermes/logs/agent.log
hosts 的 IP 过期 NLB IP 变了 getent hosts llm-9vj2mzeh6ws8xx3y.cn-beijing.maas.aliyuncs.com 更新 /etc/hosts
# gateway # python
Logo
openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

键⼊⽹址到⽹⻚显示，期间发⽣了什么？

摘要：本文详细解析了从浏览器输入URL到页面渲染的完整网络通信流程。首先浏览器解析URL生成HTTP请求报文，通过DNS将域名转换为IP地址。随后通过TCP三次握手建立连接，数据经TCP/IP分层封装后传输。服务器接收数据后层层解包处理请求，返回HTTP响应。浏览器解析响应内容渲染页面，最终通过四次挥手断开连接。整个过程涉及DNS解析、TCP/IP协议栈、路由转发等核心技术，展现了互联网通信的完整

avatar openEuler 社区
cover

Java虚拟机面试题：JVM调优

avatar openEuler 社区

JSONP技术详解与实现方案

JSONP是一种巧妙的跨域解决方案，通过利用<script>标签不受同源策略限制的特性来实现跨域数据获取。优点兼容性好，支持老旧浏览器实现简单，不需要服务器特殊配置支持GET请求跨域缺点仅支持GET请求存在安全风险（XSS攻击）错误处理困难逐渐被CORS取代使用场景需要兼容老旧浏览器的项目第三方API只提供JSONP接口简单的跨域数据获取需求在现代Web开发中，建议优先使用CORS、代理服务器或p

avatar openEuler 社区