模型问题

配置和使用 LLM（大语言模型）提供商时可能会遇到各种问题。本页涵盖认证、连接、速率限制等常见故障的排查方法。

认证失败

症状： 401 Unauthorized 或 Authentication failed 错误。

原因： API Key 无效、过期或未正确配置。

解决方案：

# 1. 重新运行交互式配置向导
hermes model

# 2. 手动检查 API Key（注意不要泄露）
cat ~/.hermes/config.yaml | grep api_key

# 3. 验证 API Key 格式
# OpenRouter:  sk-or-v1-xxxxx
# Anthropic:   sk-ant-xxxxx
# OpenAI:      sk-xxxxx
# DeepSeek:    sk-xxxxx
# Kimi:        sk-xxxxx

提示

API Key 必须放置在配置文件或环境变量中，永远不要直接写在命令行参数里，避免被命令历史记录泄露。

如果你使用 OpenRouter，需要确认使用的是 OpenRouter 的 Key，而不是 Anthropic 或 OpenAI 的原始 Key：

~/.hermes/config.yaml

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  api_key: sk-or-v1-...   # 必须是 OpenRouter 的 Key

获取 OpenRouter API Key：openrouter.ai/keys

连接超时

症状： Connection timeout、Network unreachable、长时间无响应后报错。

原因： 网络不通、代理未设置、提供商服务中断。

解决方案：

# 1. 测试网络连通性
curl -I https://openrouter.ai/api/v1/models
curl -I https://api.anthropic.com
curl -I https://api.openai.com

# 2. 如果需要代理
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

# 3. Windows PowerShell 设置代理
# $env:HTTPS_PROXY="http://127.0.0.1:7890"

# 4. 切换到国内可达的提供商
hermes model    # 选择 DeepSeek / Kimi / SiliconFlow / Qwen

注意

如果你在中国大陆，强烈推荐使用 DeepSeek、Kimi (Moonshot)、SiliconFlow 或 Qwen (Dashscope)。这些服务国内直连，无需代理，响应速度也更快。

速率限制

症状： 429 Too Many Requests 或 Rate limit exceeded 错误。

原因： 短时间内发送了过多请求，或免费套餐配额耗尽。

解决方案：

1. 等待重试 — 通常等待 60 秒后可以继续
2. 升级套餐 — 在提供商控制台升级到更高限额的计划
3. 配置自动重试和回退模型：

~/.hermes/config.yaml

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  retry:
    max_retries: 3
    retry_delay: 5
  fallback_models:
    - google/gemini-2.5-pro
    - deepseek/deepseek-chat

4. 使用 OpenRouter — 它聚合了 100+ 模型，当某个模型触发限制时会自动路由到替代模型

模型不可用

症状： Model not found 或选择的模型已下线。

原因： 模型标识符拼写错误、提供商已停用该模型、或使用了不存在的模型名。

解决方案：

# 1. 查看可用模型列表
hermes model    # 交互式选择，只显示可用模型

# 2. 使用 OpenRouter API 查询（需要 API Key）
curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

# 3. 注意模型 ID 格式
# OpenRouter 上的模型需要加提供商前缀：
# ✅ anthropic/claude-sonnet-4-20250514
# ✅ google/gemini-2.5-pro
# ❌ claude-sonnet-4-20250514  （缺少前缀）

常见模型标识符：

提供商	模型 ID 示例
Anthropic	anthropic/claude-sonnet-4-20250514
OpenAI	openai/gpt-4o
Google	google/gemini-2.5-pro
DeepSeek	deepseek/deepseek-chat
Meta	meta-llama/llama-3.3-70b-instruct
Mistral	mistral/mistral-large-latest
Kimi	moonshot/moonshot-v1
Qwen	qwen/qwen-3-235b-a22b

警告

模型 ID 会随提供商更新而变化。如果之前能用的模型突然不可用，检查提供商是否更改了模型名称或下线了该版本。

输出质量差或幻觉严重

症状： Agent 回答不准确、编造信息或逻辑混乱。

原因： 选择了能力较弱的模型、上下文过长导致信息丢失、提示词不够清晰。

解决方案：

1. 升级模型 — 使用更强的模型（如 Claude Sonnet 4、GPT-4o）
2. 优化提示词 — 参考 提示词指南
3. 控制上下文长度 — 定期使用 /clear 清空对话历史
4. 使用 system prompt 引导 — 在配置中添加角色说明：

~/.hermes/config.yaml

agent:
  system_prompt: |
    你是一个精确、严谨的助手。
    回答前先确认事实，不确定时明确说明。
    使用中文回答。

本地模型（Ollama / vLLM）问题

症状： 连接本地模型时失败。

原因： 本地服务未启动、端口不正确、模型未下载。

解决方案：

# Ollama
ollama serve                    # 启动 Ollama 服务
ollama pull llama3.3           # 下载模型
curl http://localhost:11434/api/tags  # 验证服务运行

# vLLM
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --port 8000

# 配置 Hermes 连接本地模型
hermes model    # 选择 Ollama 或 vLLM

# 或手动配置
llm:
  provider: ollama
  model: llama3.3
  base_url: http://localhost:11434

Token 超限

症状： context_length_exceeded 或 maximum context length 错误。

原因： 对话历史过长，超过了模型的上下文窗口。

解决方案：

# 1. 清空当前对话
/clear

# 2. 开始新会话
hermes chat --new

# 3. 在配置中设置自动摘要压缩

~/.hermes/config.yaml

agent:
  auto_summarize: true
  summarize_threshold: 80000   # Token 数阈值

相关页面

• 常见错误 — 运行时的常见错误
• 成本优化 — 降低 Token 消耗的策略
• 提示词指南 — 写出更好的提示词
• hermes doctor 诊断 — 自动诊断工具