大模型提供商配置

Hermes Agent 的一个核心优势在于其灵活的多模型支持——你可以根据任务类型、成本预算和性能需求，为不同的工作场景选择最合适的模型。本章将深入探讨模型提供商的配置、API Key 安全管理、模型切换策略和成本控制方案。

支持的模型提供商清单

Hermes Agent 支持多种模型提供商，涵盖闭源商业模型和开源本地模型：

商业云服务：

• OpenAI：GPT-4o、GPT-4o-mini、o3、o4-mini 等
• Anthropic：Claude Sonnet 4、Claude Opus 4、Claude Haiku 3.5 等
• Google：Gemini 2.5 Pro、Gemini 2.5 Flash 等
• 阿里云：通义千问 2.5、通义千问 2.5-Max 等

开源模型平台：

• Ollama：Llama 3、DeepSeek-V3、Qwen 2.5、Mistral 等
• vLLM：支持与 OpenAI API 兼容的任何模型
• OpenRouter：统一 API 网关，聚合多种模型

配置语法示例：

# .hermes/config.yaml 中的模型配置

# OpenAI 提供商
model:
  provider: openai
  name: gpt-4o
  api_key: ${OPENAI_API_KEY}
  temperature: 0.3
  max_tokens: 8192

# Anthropic 提供商
# model:
#   provider: anthropic
#   name: claude-sonnet-4-20250514
#   api_key: ${ANTHROPIC_API_KEY}

# Ollama 本地模型
# model:
#   provider: ollama
#   name: llama3.1:70b
#   base_url: http://localhost:11434/v1
#   api_key: not-needed  # 本地模型不需要 API Key

API Key 配置与安全管理

API Key 的安全管理是使用 AI 编程助手时的首要关注点。Hermes Agent 提供了多层级的 Key 管理方案：

优先级体系（从高到低）

1. 环境变量：${VAR_NAME} 语法引用的环境变量，优先级最高
2. 命令行参数：--api-key 参数传入的 Key
3. 配置文件：config.yaml 中直接写入的 Key（不推荐）
4. .env 文件：项目根目录下 .env 文件中定义的 Key

推荐的配置方式

# 步骤一：在 shell 配置文件中设置环境变量
echo 'export OPENAI_API_KEY=sk-your-key-here' >> ~/.zshrc
source ~/.zshrc

# 步骤二：在 config.yaml 中引用环境变量
# model:
#   api_key: ${OPENAI_API_KEY}

# 步骤三：验证配置是否生效
hermes-agent config show

多 Key 管理与负载均衡

对于企业用户，可能需要管理多个 API Key 以提高可用性或分摊成本：

# 多 Key 配置示例
model:
  provider: openai
  name: gpt-4o
  api_key:
    - ${OPENAI_API_KEY_1}
    - ${OPENAI_API_KEY_2}
    - ${OPENAI_API_KEY_3}
  key_strategy: round_robin  # round_robin / failover / usage_based

key_strategy 支持三种模式：

• round_robin：轮询使用，均匀分摊请求
• failover：主 Key 失败后切换到备用 Key
• usage_based：根据用量动态分配

安全意识提醒

# 危险！不要将 API Key 硬编码在配置文件中提交到 Git
# ❌ 以下做法不安全：
# model:
#   api_key: sk-xxxxxxxxxxxxxxxx  # 直接写在文件里

# ✅ 正确的做法：
# model:
#   api_key: ${OPENAI_API_KEY}  # 通过环境变量引用

建议将 .hermes/config.yaml 中可能包含敏感信息的部分剥离，通过环境变量注入。同时确保 .gitignore 中包含了 .env 文件：

# .gitignore
.env
.hermes/config.yaml  # 如果包含敏感配置

模型切换策略：按任务类型自动选择

不同的大语言模型在不同类型的编程任务上有各自的优势和劣势。Hermes Agent 支持通过配置实现按任务类型自动选择最佳模型：

# 按任务类型自动选择模型的配置
model_routes:
  - task_pattern: "debug|fix|error"      # 错误修复类任务
    model:
      provider: anthropic
      name: claude-sonnet-4-20250514

  - task_pattern: "refactor|optimize"     # 重构优化类任务
    model:
      provider: openai
      name: gpt-4o

  - task_pattern: "test|write.*test"      # 测试编写类任务
    model:
      provider: openai
      name: gpt-4o-mini                  # 使用性价比更高的模型

  - task_pattern: "doc|readme|comment"    # 文档编写类任务
    model:
      provider: openai
      name: gpt-4o-mini

  - task_pattern: "explain|analyze"       # 代码分析类任务
    model:
      provider: anthropic
      name: claude-sonnet-4-20250514

这种按任务类型路由的策略可以带来以下好处：

• 成本优化：简单任务使用小型模型，复杂任务使用大型模型，整体成本降低 40% 到 60%
• 性能提升：不同模型在不同场景下各有专长，路由策略确保每个任务使用最适合的模型
• 响应速度：简单任务使用轻量模型可以获得更快的响应速度

不同模型在编程任务上的表现差异

为了帮助你选择合适的模型，下表汇总了主流模型在不同编程任务上的表现对比（基于社区实测数据）：

从表中可以总结出几条实用的选型原则：

• 代码生成与重构：优先选择 Claude Opus 4 或 GPT-4o，这两者在复杂代码生成上表现最好
• Bug 修复与调试：Claude Sonnet 4 在错误定位和修复方面表现突出
• 简单任务与测试编写：GPT-4o-mini 性价比最高，速度和成本优势明显
• 本地开发与数据敏感场景：DeepSeek-V3 或 Qwen 2.5 可以在本地运行，数据不出本机

本地模型接入指南

对于数据安全要求严格的场景，Hermes Agent 支持通过 Ollama 接入本地运行的模型：

# 步骤一：安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 步骤二：下载模型（以 DeepSeek-V3 为例）
ollama pull deepseek-v3

# 步骤三：确认 Ollama 服务正常运行
ollama list
# 输出应显示已下载的模型列表

配置 Hermes Agent 使用本地 Ollama 模型：

model:
  provider: ollama
  name: deepseek-v3
  base_url: http://localhost:11434/v1  # Ollama 默认 API 地址
  api_key: not-needed                  # 本地模型不需要 Key
  temperature: 0.3
  max_tokens: 4096

# Ollama 的额外配置
ollama:
  keep_alive: 5m       # 模型在内存中的保持时间
  num_ctx: 8192        # 上下文窗口大小
  num_gpu: -1          # GPU 层数，-1 表示全部

与其他模型提供商的关键差异：

除了 Ollama，vLLM 也是一个常见的本地部署方案，它提供了更高的吞吐量和更灵活的参数控制。vLLM 服务暴露的 API 与 OpenAI API 兼容，因此可以直接使用 provider: openai 配合自定义 base_url 来接入。

成本控制与 Token 优化

使用商业模型 API 时，成本控制是一个重要的考量因素。以下是几种有效的优化策略：

1. 选择合适的模型

# 日常开发使用性价比模型
model:
  provider: openai
  name: gpt-4o-mini  # 成本仅为 GPT-4o 的 1/20

GPT-4o-mini 的输入价格约为每百万 Token 0.15 美元，而 GPT-4o 约为每百万 Token 2.50 美元。对于简单任务使用 Mini 版本，成本可以降低 90% 以上。

2. 设置 Token 预算上限

# 设置单次任务的 Token 预算
agent:
  max_tokens_per_task: 50000  # 单次任务不超过 5 万 Token
  cost_limit_usd: 0.10        # 单次任务成本上限（美元）

3. 使用 /compact 压缩上下文

在交互模式下，当上下文变得冗长时，及时使用 /compact 命令压缩对话历史。压缩后通常可以释放 30% 到 50% 的 Token 空间，减少后续请求的 Token 消耗。

4. 监控 Token 消耗

# 查看当前会话的 Token 统计
hermes-agent sessions stats --session-id <id>

# 查看所有会话的累计消耗
hermes-agent sessions stats --all

# 输出示例：
# 总输入 Token: 1,234,567
# 总输出 Token: 234,567
# 预估总成本: $2.15

5. 控制输出长度

model:
  max_tokens: 4096  # 限制单次输出的最大 Token 数

在某些任务中，Agent 可能会生成过长的输出。设置合理的 max_tokens 上限可以避免在少量任务上消耗过多的 Token。

下表总结了不同成本控制策略的效果评估：

本章小结

本章全面介绍了 Hermes Agent 的大模型提供商配置，包括所有支持的提供商类型、API Key 的安全管理方案、按任务类型的模型路由策略、主流模型的性能对比、本地模型的接入方法，以及成本控制和 Token 优化的多种方案。灵活运用这些配置能力，可以在不同场景下获得最佳的编程体验和成本效益。