跳到主要内容

大模型提供商（provider）运行时解析

Hermes 有一个共享的大模型提供商（provider）运行时解析器，用于：

  • 命令行界面
  • 网关
  • 计划任务
  • ACP
  • 辅助模型调用

主要实现：

  • hermes_cli/runtime_provider.py — 凭证解析，_resolve_custom_runtime()
  • hermes_cli/auth.py — 提供商注册表，resolve_provider()
  • hermes_cli/model_switch.py — 共享 /model 切换管道（CLI + 网关）
  • agent/auxiliary_client.py — 辅助模型路由

如果您尝试添加新的一流推理大模型提供商（provider），请阅读本页旁边的 Adding Providers。

解析优先级​

在较高层面上，提供商解析使用：

  1. 显式 CLI/运行时请求
  2. config.yaml 模型/提供商配置 3.环境变量
  3. 提供商特定的默认值或自动解析

这种顺序很重要，因为 Hermes 将保存的模型/大模型提供商（provider）选择视为正常运行的事实来源。这可以防止过时的 shell 导出以静默方式覆盖用户最后在 hermes model 中选择的端点。

提供商​

目前的大模型提供商（provider）家族包括：

  • AI 网关（Vercel）
  • OpenRouter
  • Nous Portal
  • OpenAI 法典
  • Copilot / Copilot ACP
  • Anthropic（本土）
  • 谷歌/双子座
  • 阿里巴巴/DashScope
  • DeepSeek
  • Z.艾
  • 基米/登月
  • MiniMax
  • 迷你麦克斯中国
  • 基洛代码
  • Hugging Face
  • OpenCode Zen / OpenCode Go
  • 自定义 (provider: custom) — 任何 OpenAI 兼容端点的一流提供商
  • 命名的自定义大模型提供商（provider）（config.yaml 中的 custom_providers 列表）

运行时解析的输出​

运行时解析器返回数据，例如：

  • provider
  • api_mode
  • base_url
  • api_key
  • source
  • 提供商特定的元数据，例如到期/刷新信息

为什么这很重要​

这个解析器是 Hermes 可以在以下之间共享身份验证/运行时逻辑的主要原因：

  • hermes chat
  • 网关消息处理
  • 在新会话中运行的 cron 作业
  • ACP 编辑会议
  • 辅助模型任务

AI 网关​

在 ~/.hermes/.env 中设置 AI_GATEWAY_API_KEY 并使用 --provider ai-gateway 运行。 Hermes 从网关的 /models 端点获取可用模型，过滤到具有工具使用支持的语言模型。

OpenRouter、AI 网关和自定义 OpenAI 兼容的基本 URL​

Hermes 包含的逻辑可避免在存在多个大模型提供商（provider）密钥（例如 OPENROUTER_API_KEY、AI_GATEWAY_API_KEY 和 OPENAI_API_KEY）时将错误的 API 密钥泄漏到自定义端点。

每个提供商的 API 密钥的范围仅限于其自己的基本 URL：

  • OPENROUTER_API_KEY 仅发送到 openrouter.ai 端点
  • AI_GATEWAY_API_KEY 仅发送到 ai-gateway.vercel.sh 端点
  • OPENAI_API_KEY 用于自定义端点并作为后备

Hermes 还区分：

  • 用户选择的真实自定义端点
  • 未配置自定义端点时使用的 OpenRouter 后备路径

这种区别对于以下方面尤其重要：

  • 本地模型服务器
  • 非 OpenRouter/非 AI 网关 OpenAI 兼容 API
  • 切换提供商而无需重新运行安装程序
  • 配置保存的自定义端点即使在当前 shell 中未导出 OPENAI_BASE_URL 时也应继续工作

原生Anthropic路径​

Anthropic 不再只是“通过 OpenRouter”。

当大模型提供商（provider）解析选择 anthropic 时，Hermes 使用：

  • api_mode = anthropic_messages
  • 原生 Anthropic Messages API
  • agent/anthropic_adapter.py 用于翻译

当两者都存在时，本机 Anthropic 的凭证解析现在更喜欢可刷新的 Claude Code 凭证，而不是复制的 env 令牌。实际上这意味着：

  • 当 Claude Code 凭证文件包含可刷新身份验证时，它们将被视为首选源
  • 手动 ANTHROPIC_TOKEN / CLAUDE_CODE_OAUTH_TOKEN 值仍然可以作为显式覆盖使用
  • Hermes 预检在本机消息 API 调用之前刷新人类凭证
  • 重建 Anthropic 客户端后，Hermes 仍会在 401 上重试一次，作为后备路径

OpenAI Codex 路径​

Codex 使用单独的响应 API 路径：

  • api_mode = codex_responses
  • 专用凭证解析和授权存储支持

辅助模型路由​

辅助任务例如：

  • 想象
  • 网页提取摘要
  • 上下文压缩摘要
  • 会话搜索摘要
  • 技能中心运营
  • MCP辅助操作
  • 内存刷新

可以使用自己的大模型提供商（provider）/模型路由而不是主要的会话模型。

当使用大模型提供商（provider） main 配置辅助任务时，Hermes 通过与正常聊天相同的共享运行时路径来解决该问题。实际上这意味着：

  • 环境驱动的自定义端点仍然有效
  • 通过 hermes model / config.yaml 保存的自定义端点也可以工作
  • 辅助路由可以区分真实保存的自定义端点和 OpenRouter 回退之间的区别

后备模型​

Hermes 支持已配置的后备模型/大模型提供商（provider）对，允许在主模型遇到错误时进行运行时故障转移。

内部如何运作​

  1. 存储：AIAgent.__init__ 存储 fallback_model 字典并设置 _fallback_activated = False。

  2. 触发点：_try_activate_fallback()是从run_agent.py中主重试循环中的三个地方调用的：

  • 对无效 API 响应进行最大重试后（无选择、缺少内容）
  • 不可重试的客户端错误（HTTP 401、403、404）
  • 发生暂时性错误（HTTP 429、500、502、503）的最大重试次数后
  1. 激活流程 (_try_activate_fallback):
  • 如果已激活或未配置，则立即返回 False
  • 从 auxiliary_client.py 调用 resolve_provider_client() 以构建具有正确身份验证的新客户端
  • 确定 api_mode：openai-codex 为 codex_responses，anthropic 为 anthropic_messages，其他所有内容为 chat_completions
  • 就地交换：self.model、self.provider、self.base_url、self.api_mode、self.client、self._client_kwargs
  • 对于Anthropic回退：构建本机Anthropic客户端而不是与 OpenAI 兼容的客户端
  • 重新评估提示缓存（为 OpenRouter 上的 Claude 模型启用）
  • 设置 _fallback_activated = True — 防止再次触发
  • 将重试计数重置为 0 并继续循环
  1. 配置流程：
  • CLI：cli.py 读取 CLI_CONFIG["fallback_model"] → 传递到 AIAgent(fallback_model=...)
  • 网关：gateway/run.py._load_fallback_model() 读取 config.yaml → 传递到 AIAgent
  • 验证：provider 和 model 键必须为非空，否则禁用回退

什么不支持后备​

  • 子代理委托 (tools/delegate_tool.py)：子代理继承父代理的大模型提供商（provider），但不继承后备配置
  • Cron 作业 (cron/)：使用固定大模型提供商（provider）运行，无后备机制
  • 辅助任务：使用自己独立的大模型提供商（provider）自动检测链（参见上面的辅助模型路由）

测试覆盖率​

请参阅 tests/test_fallback_model.py 了解涵盖所有受支持的大模型提供商（provider）、一次性语义和边缘情况的全面测试。

相关文档​