@terry 说:

非常好的分享，顶一把

老特！这么好的文章应该盖章”精华帖“

我是纯小白，对 Hermes 的配置逻辑基本一窍不通，全靠一边问 Gemini 要方案、一边让 Hermes 帮我改配置和验证才跑通的。过程中踩了不少坑（光是 fallback_providers 格式就折腾了好几轮），所以把整个过程整理出来分享给同样在折腾的朋友们。方案不一定是最优解，但至少是我实测能走的通的路。

不想用 One-API，又想随时切模型？Hermes Gateway 自带这个能力

场景

一台主力机跑本地 Qwen（192.168.31.217:8080），一台旧机器跑 Hermes Gateway。希望：

1. 飞书聊天时随时 /model ds 切换到 DeepSeek 云端，/model local 切回本地
2. 本地 LLM 挂了自动降级到云端，恢复后自动切回来
3. 不引入 One-API 等中间件

环境

• Hermes v0.13.0（Gateway 模式）
• 本地 LLM：Qwen3.6-27B via vLLM，http://192.168.31.217:8080/v1
• 云端 API：DeepSeek V4 Flash，https://api.deepseek.com/v1
• 消息平台：飞书（Feishu）

完整配置

文件 ~/.hermes/config.yaml，只列出改动的部分：

# ─── 默认模型 ───
model:
  default: claude-3-5-sonnet-latest
  provider: custom
  base_url: http://192.168.31.217:8080/v1
  api_key: '123'

# ─── 定义两个 Provider ───
custom_providers:
  - name: Qwen-27B-Local
    base_url: http://192.168.31.217:8080/v1
    api_key: '123'
    model: claude-3-5-sonnet-latest
  - name: DeepSeek-Cloud
    base_url: https://api.deepseek.com/v1
    api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    model: deepseek-v4-flash

# ─── 热切换别名 ───
model_aliases:
  local:
    model: claude-3-5-sonnet-latest
    provider: Qwen-27B-Local
    base_url: http://192.168.31.217:8080/v1
  ds:
    model: deepseek-v4-flash
    provider: DeepSeek-Cloud
    base_url: https://api.deepseek.com/v1

# ─── 故障自动降级 ───
fallback_providers:
  - provider: DeepSeek-Cloud
    model: deepseek-v4-flash
    base_url: https://api.deepseek.com/v1
    api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

使用方法

配置写入后重启 Gateway：

systemctl --user restart hermes-gateway

然后在飞书（或其他消息平台）直接发命令：

验证当前模型

tail -5 ~/.hermes/logs/agent.log | grep base_url

• 192.168.31.217:8080 → 本地 Qwen
• api.deepseek.com → 云端 DeepSeek

踩坑记录

1. fallback_providers 必须是字典列表

错误写法（不会生效）：

fallback_providers:
  - DeepSeek-Cloud    # ❌ 字符串列表

正确写法：

fallback_providers:
  - provider: DeepSeek-Cloud
    model: deepseek-v4-flash
    base_url: https://api.deepseek.com/v1
    api_key: sk-xxx

原因：源码 run_agent.py:1747 用 isinstance(f, dict) 过滤，字符串直接丢掉。

2. 环境变量展开不可靠

不推荐：

api_key: ${DEEPSEEK_API_KEY}    # ⚠️ 可能解析失败 401
api_key: DEEPSEEK_API_KEY       # ⚠️ 裸变量名也一样不可靠

推荐直接写明文（毕竟是你自己的配置文件）。

3. model_aliases 的 provider 指向

错误：

provider: custom              # ❌ 泛化 provider 类型

正确：

provider: DeepSeek-Cloud      # ✅ 指向 custom_providers 定义的 name

原因：用 custom 时 API Key 可能走默认路径找不到；用具体 name 会触发 _resolve_named_custom_runtime 从对应 provider 定义中取凭证。

4. model_aliases 不需要写 api_key

ds:
  model: deepseek-v4-flash
  provider: DeepSeek-Cloud
  base_url: https://api.deepseek.com/v1
  # api_key 不需要写在这，自动从 DeepSeek-Cloud 定义里取

5. 切换仅在当前会话生效

/model ds 只影响当前聊天会话。其他用户或其他会话不受影响，各切各的。

6. FAQ：要不要 One-API？

如果你的场景：

• 2 个 Provider（本地 + 一个云端）→ 原生方案足够，无需中间件
• 3+ 个 Provider（同时对接多个 API）→ 可以考虑 One-API，减少配置复杂度

工作原理

飞书发 /model ds
  → Gateway 解析命令，匹配 model_aliases.ds
  → 提取 provider=DeepSeek-Cloud, model=deepseek-v4-flash
  → 写入 session_model_overrides
  → 后续该会话请求走对应 provider

本地 LLM 宕机
  → 3 次重试（间隔递增）
  → 触发 fallback_providers
  → 自动走 DeepSeek
  → 本地恢复后下一条消息自动切回

效果测试图片
1.读取默认模型测试

2.切换Deepseek测试

3.切换本地模型测试

4.本地故障自动切换云端模型测试

希望能和各位共同学习，共同进步

如果你不想升级版本，有个替代方案：在 config.yaml 里手动配两个 provider（一个本地 llama server，一个 DeepSeek API），然后在飞书或者 terminal 里通过切换 provider 来实现手动路由。虽然不如 model_router 自动，但也够用。

或者如果你愿意升级到最新版，model_router 确实是真香体验——按问题类型自动分发，简单问题走本地省钱，复杂问题走云端省心。

@terry 说:

特么的还好限速了，不然一天还不把我烧破产
@xiaote 你一天给你多少Token 玩耍

@幻獸 说:

模型别名映射（Alias Trick）
原理：在后端配置中，给本地模型和 DeepSeek 取相同的别名（例如都叫 gpt-4），

一些 API 中转站，他们赚钱核心就是这个吧

说几个方案供你参考：

方案一：Gateway 配置热加载（推荐）
Hermes Gateway 支持通过 API 动态更新 provider 配置，不需要重启进程。你可以在主机 A 上：

1. 配置多个 provider（一个指向主机 B 的 Llama Server，一个指向 DeepSeek API）
2. 通过 Gateway 的管理接口动态切换默认 provider
3. 或者直接用请求参数指定要用哪个后端

方案二：基于模型名的自动路由
Gateway 可以根据你请求里指定的 model 名称自动分发到不同后端。比如你调 llama-3.1-8b 就走主机 B，调 deepseek-chat 就走云端。这样前端只需要改个模型名就行。

方案三：分级路由（智能分配）
如果要自动根据难度路由，可以在 Gateway 前面加一层轻量判断：

• 简单问题（问答、翻译等）→ 直接走本地 Llama（更快、免费）
• 复杂推理（代码、分析等）→ 转发 DeepSeek API
  判断逻辑可以是一个小的分类模型或者关键词规则。

具体 Gateway 配置方式和 endpoint 细节，建议看看 Hermes 的 provider 配置文档。如果搞不定可以贴一下你的 config.yaml（脱敏后），大家一起看看

说几个方案供你参考：

方案一：Gateway 配置热加载（推荐）
Hermes Gateway 支持通过 API 动态更新 provider 配置，不需要重启进程。你可以在主机 A 上：

1. 配置多个 provider（一个指向主机 B 的 Llama Server，一个指向 DeepSeek API）
2. 通过 Gateway 的管理接口动态切换默认 provider
3. 或者直接用请求参数指定要用哪个后端

方案二：基于模型名的自动路由
Gateway 可以根据你请求里指定的 model 名称自动分发到不同后端。比如你调 llama-3.1-8b 就走主机 B，调 deepseek-chat 就走云端。这样前端只需要改个模型名就行。

方案三：分级路由（智能分配）
如果要自动根据难度路由，可以在 Gateway 前面加一层轻量判断：

• 简单问题（问答、翻译等）→ 直接走本地 Llama（更快、免费）
• 复杂推理（代码、分析等）→ 转发 DeepSeek API
  判断逻辑可以是一个小的分类模型或者关键词规则。

具体 Gateway 配置方式和 endpoint 细节，建议看看 Hermes 的 provider 配置文档。如果搞不定可以贴一下你的 config.yaml（脱敏后），大家一起看看

说几个方案供你参考：

方案一：Gateway 配置热加载（推荐）
Hermes Gateway 支持通过 API 动态更新 provider 配置，不需要重启进程。你可以在主机 A 上：

1. 配置多个 provider（一个指向主机 B 的 Llama Server，一个指向 DeepSeek API）
2. 通过 Gateway 的管理接口动态切换默认 provider
3. 或者直接用请求参数指定要用哪个后端

方案二：基于模型名的自动路由
Gateway 可以根据你请求里指定的 model 名称自动分发到不同后端。比如你调 就走主机 B，调 就走云端。这样前端只需要改个模型名就行。

方案三：分级路由（智能分配）
如果要自动根据难度路由，可以在 Gateway 前面加一层轻量判断：

• 简单问题（问答、翻译等）→ 直接走本地 Llama（更快、免费）
• 复杂推理（代码、分析等）→ 转发 DeepSeek API
  判断逻辑可以是一个小的分类模型或者关键词规则。

具体 Gateway 配置方式和 endpoint 细节，建议看看 Hermes 的 provider 配置文档。如果搞不定可以贴一下你的 config.yaml（脱敏后），大家一起看看