跳到主要内容

添加大模型提供商（provider）

Hermes 已经可以通过自定义大模型提供商（provider）路径与任何 OpenAI 兼容端点进行通信。不要添加内置大模型提供商（provider），除非您希望该服务具有一流的用户体验：

  • 特定于提供商的身份验证或令牌刷新
  • 精心策划的模型目录
  • 设置/hermes model 菜单项
  • provider:model 语法的大模型提供商（provider）别名
  • 需要适配器的非 OpenAI API 形状

如果大模型提供商（provider）只是“另一个与 OpenAI 兼容的基本 URL 和 API 密钥”，则指定的自定义大模型提供商（provider）可能就足够了。

心智模型​

内置大模型提供商（provider）必须跨几个层排列：

  1. hermes_cli/auth.py 决定如何找到凭证。
  2. hermes_cli/runtime_provider.py 将其转换为运行时数据：
  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  1. run_agent.py 使用 api_mode 来决定如何构建和发送请求。
  2. hermes_cli/models.py 和 hermes_cli/main.py 使大模型提供商（provider）显示在 CLI 中。 （hermes_cli/setup.py 自动委托给 main.py — 无需进行任何更改。）
  3. agent/auxiliary_client.py 和 agent/model_metadata.py 保持副任务和代币预算工作。

重要的抽象是api_mode。

  • 大多数提供商使用 chat_completions。
  • Codex 使用 codex_responses。
  • Anthropic 使用 anthropic_messages。
  • 新的非 OpenAI 协议通常意味着添加新的适配器和新的 api_mode 分支。

首先选择实现路径​

路径 A — OpenAI 兼容提供商​

当大模型提供商（provider）接受标准聊天完成样式请求时使用此选项。

典型工作：

  • 添加身份验证元数据
  • 添加模型目录/别名
  • 添加运行时分辨率
  • 添加CLI菜单接线
  • 添加辅助模型默认值
  • 添加测试和用户文档

您通常不需要新的适配器或新的 api_mode。

路径 B — 本地提供商​

当大模型提供商（provider）的行为不像 OpenAI 聊天完成时使用此选项。

今天树中的示例：

  • TODO
  • TODO

该路径包括路径 A 中的所有内容以及：

  • agent/ 中的大模型提供商（provider）适配器
  • 用于请求构建、分派、使用提取、中断处理和响应规范化的 run_agent.py 分支
  • 适配器测试

文件清单​

每个内置大模型提供商（provider）都需要​

1.TODO 2.TODO 3.TODO 4.TODO 5.TODO 6.TODO 7. 测试 8. website/docs/ 下面向用户的文档

提示

hermes_cli/setup.py 不需要需要更改。设置向导将大模型提供商（provider）/模型选择委托给 main.py 中的 select_provider_and_model() — 添加到此处的任何大模型提供商（provider）都会自动在 hermes setup 中可用。

原生/非 OpenAI 提供商的附加内容​

10.TODO 11.TODO 12. pyproject.toml 如果需要提供商 SDK

第 1 步：选择一个规范的提供商 ID​

选择一个提供商 ID 并在任何地方使用它。

存储库中的示例：

  • TODO
  • TODO
  • TODO

相同的 id 应出现在：

  • hermes_cli/auth.py 中的 PROVIDER_REGISTRY
  • hermes_cli/models.py 中的 _PROVIDER_LABELS
  • _PROVIDER_ALIASES 在 hermes_cli/auth.py 和 hermes_cli/models.py 中
  • hermes_cli/main.py 中的 CLI --provider 选择
  • 设置/模型选择分支
  • 辅助模型默认值
  • 测试

如果这些文件之间的 id 不同，则大模型提供商（provider）会感觉半连线：身份验证可能会工作，而 /model、设置或运行时解析会默默地错过它。

步骤 2：在 hermes_cli/auth.py 中添加身份验证元数据​

对于 API 密钥大模型提供商（provider），将 ProviderConfig 条目添加到 PROVIDER_REGISTRY 中：

  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • 可选 base_url_env_var

还要向 _PROVIDER_ALIASES 添加别名。

使用现有的大模型提供商（provider）作为模板：

  • 简单的 API 密钥路径：Z.AI、MiniMax
  • 具有端点检测功能的 API 密钥路径：Kimi、Z.AI
  • 原生代币解析：Anthropic
  • OAuth / auth-store 路径：Nous、OpenAI Codex

此处要回答的问题：

  • Hermes 应该检查哪些环境变量，以及按什么优先顺序？
  • 提供商是否需要覆盖基本 URL？
  • 是否需要端点探测或令牌刷新？
  • 当凭据丢失时，身份验证错误应该显示什么？

如果提供商需要的不仅仅是“查找 API 密钥”，请添加专用的凭证解析器，而不是将逻辑推入不相关的分支。

步骤3：在hermes_cli/models.py中添加模型目录和别名​

更新大模型提供商（provider）目录，以便大模型提供商（provider）可以在菜单中和 provider:model 语法中工作。

典型的编辑：

  • TODO
  • TODO
  • TODO
  • list_available_providers() 内的大模型提供商（provider）显示顺序
  • provider_model_ids() 如果大模型提供商（provider）支持实时 /models 获取

如果大模型提供商（provider）公开实时模型列表，请首先选择该列表，并保留 _PROVIDER_MODELS 作为静态后备。

该文件也是使此类输入起作用的原因：

anthropic:claude-sonnet-4-6
kimi:model-name

如果此处缺少别名，大模型提供商（provider）可能会正确进行身份验证，但在 /model 解析中仍然失败。

步骤 4：解析 hermes_cli/runtime_provider.py 中的运行时数据​

resolve_runtime_provider() 是 CLI、网关、cron、ACP 和帮助程序客户端使用的共享路径。

添加一个返回至少包含以下内容的字典的分支：

{
    "provider": "your-provider",
    "api_mode": "chat_completions",  # or your native mode
    "base_url": "https://...",
    "api_key": "...",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

如果大模型提供商（provider）与 OpenAI 兼容，则 api_mode 通常应保留 chat_completions。

请注意 API 密钥优先级。 Hermes 已经包含避免将 OpenRouter 密钥泄漏到不相关端点的逻辑。新的大模型提供商（provider）应该同样明确哪个密钥指向哪个基本 URL。

步骤 5：在 hermes_cli/main.py 中连接 CLI​

大模型提供商（provider）在出现在交互式 hermes model 流中之前是不可发现的。

在 hermes_cli/main.py 中更新这些：

  • provider_labels 字典
  • providers 列表在 select_provider_and_model() 中
  • 提供商调度 (if selected_provider == ...)
  • --provider 参数选择
  • 登录/注销选项（如果提供商支持这些流程）
  • _model_flow_<provider>() 函数，或者重用 _model_flow_api_key_provider() （如果适合）
提示

hermes_cli/setup.py 不需要更改 - 它从 main.py 调用 select_provider_and_model()，因此您的新大模型提供商（provider）会自动出现在 hermes model 和 hermes setup 中。

步骤 6：保持辅助呼叫正常工作​

这里有两个文件很重要：

agent/auxiliary_client.py​

如果这是直接 API 密钥大模型提供商（provider），则将便宜/快速的默认辅助模型添加到 _API_KEY_PROVIDER_AUX_MODELS 中。

辅助任务包括：

  • 愿景总结
  • 网页提取摘要
  • 上下文压缩摘要
  • 会话搜索摘要
  • 内存刷新

如果大模型提供商（provider）没有合理的辅助默认值，副任务可能会严重回退或意外地使用昂贵的主模型。

agent/model_metadata.py​

为提供商的模型添加上下文长度，以便令牌预算、压缩阈值和限制保持合理。

步骤 7：如果大模型提供商（provider）是本机的，请添加适配器和 run_agent.py 支持​

如果大模型提供商（provider）不是普通的聊天完成，请在 agent/<provider>_adapter.py 中隔离大模型提供商（provider）特定的逻辑。

让 run_agent.py 专注于编排。它应该调用适配器帮助程序，而不是在整个文件中内联手动构建大模型提供商（provider）有效负载。

本地提供商通常需要在这些地方工作：

新适配器文件​

典型职责：

  • 构建 SDK / HTTP 客户端
  • 解析令牌
  • 将 OpenAI 风格的对话消息转换为提供商的请求格式
  • 如果需要转换工具模式
  • 将大模型提供商（provider）响应规范化回 run_agent.py 期望的内容
  • 提取使用情况和完成原因数据

run_agent.py​

搜索 api_mode 并审核每个切换点。至少，验证：

  • __init__ 选择新的 api_mode
  • 为提供商提供客户建筑工程
  • _build_api_kwargs() 知道如何格式化请求
  • _interruptible_api_call() 分派到正确的客户端调用
  • 中断/客户端重建路径工作
  • 响应验证接受大模型提供商（provider）的形状
  • 完成原因提取正确
  • 令牌使用提取正确
  • 后备模型激活可以干净地切换到新的提供商
  • 摘要生成和内存刷新路径仍然有效

另请在 run_agent.py 中搜索 self.client.。当本机大模型提供商（provider）使用不同的客户端对象或 self.client = None 时，任何假设存在标准 OpenAI 客户端的代码路径都可能会中断。

提示缓存和特定于大模型提供商（provider）的请求字段​

提示缓存和特定于提供商的旋钮很容易回归。

树中已有示例：

  • Anthropic 有一个本地提示缓存路径
  • OpenRouter 获取提供商路由字段
  • 并非每个提供商都应该接收每个请求方选项

当您添加本地大模型提供商（provider）时，请仔细检查 Hermes 是否仅发送大模型提供商（provider）实际理解的字段。

步骤 8：测试​

至少，接触保护提供商接线的测试。

常见的地方：

  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • tests/test_<provider>_adapter.py 对于本地提供商

对于仅文档示例，确切的文件集可能有所不同。重点是要涵盖：

  • 授权解析
  • CLI 菜单/提供商选择
  • 运行时大模型提供商（provider）解析
  • 代理执行路径
  • 大模型提供商（provider）：模型解析
  • 任何特定于适配器的消息转换

在禁用 xdist 的情况下运行测试：

source venv/bin/activate
python -m pytest tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/test_cli_model_command.py tests/test_setup_model_selection.py -n0 -q

对于更深层次的更改，请在推送之前运行完整套件：

source venv/bin/activate
python -m pytest tests/ -n0 -q

步骤 9：实时验证​

测试完成后，进行真正的冒烟测试。

source venv/bin/activate
python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model

如果更改菜单，还要测试交互流程：

source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup

对于本机提供商，也至少验证一个工具调用，而不仅仅是纯文本响应。

步骤 10：更新面向用户的文档​

如果提供商打算作为一流选项提供，也请更新用户文档：

  • TODO
  • TODO
  • TODO

开发人员可以完美连接大模型提供商（provider），但仍然让用户无法发现所需的环境变量或设置流程。

OpenAI 兼容提供商清单​

如果大模型提供商（provider）是标准聊天完成，请使用此选项。

  • ProviderConfig 添加到 hermes_cli/auth.py 中
  • 在 hermes_cli/auth.py 和 hermes_cli/models.py 中添加了 [ ] 别名
  • 模型目录添加到 hermes_cli/models.py 中
  • 运行时分支添加到 hermes_cli/runtime_provider.py 中
  • CLI 接线添加到 hermes_cli/main.py （setup.py 自动继承）
  • 辅助模型添加到 agent/auxiliary_client.py 中
  • 在 agent/model_metadata.py 中添加了 [ ] 上下文长度
  • 运行时/CLI 测试已更新
  • 用户文档已更新

本地提供商清单​

当大模型提供商（provider）需要新的协议路径时使用此选项。

  • OpenAI 兼容清单中的所有内容
  • 适配器已添加到 agent/<provider>_adapter.py 中
  • run_agent.py 支持新的 api_mode
  • 中断/重建路径有效
  • 用法和完成原因提取工作
  • 后备路径有效
  • 添加了 [ ] 适配器测试
  • 现场烟雾测试通过

常见陷阱​

1. 将大模型提供商（provider）添加到身份验证但不添加到模型解析​

这使得凭据正确解析，而 /model 和 provider:model 输入失败。

2. 忘记 config["model"] 可以是字符串或字典​

许多大模型提供商（provider）选择代码必须规范这两种形式。

3. 假设需要内置大模型提供商（provider）​

如果服务只是与 OpenAI 兼容，那么定制提供商可能已经以较少的维护来解决用户问题。

4. 忘记辅助路径​

主聊天路径可以工作，而摘要、内存刷新或视觉助手因辅助路由从未更新而失败。

5. 本地大模型提供商（provider）分支隐藏在 run_agent.py 中​

搜索 api_mode 和 self.client.。不要假设明显的请求路径是唯一的。

6. 将仅限 OpenRouter 的旋钮发送给其他提供商​

像提供商路由这样的字段只属于支持它们的提供商。

7. 更新 hermes model 但不更新 hermes setup​

两个流程都需要了解大模型提供商（provider）。

实施时良好的搜索目标​

如果您正在寻找提供商触及的所有地方，请搜索以下符号：

  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • TODO
  • TODO

相关文档​