LLM 服务商与路由

Octos 开箱即用地支持 14 家 LLM 服务商。每个服务商需要一个存储在环境变量中的 API 密钥（本地服务商如 Ollama 除外）。

支持的服务商

配置方式

配置文件

在 config.json 中设置 provider 和 model：

{
  "provider": "moonshot",
  "model": "kimi-2.5",
  "api_key_env": "KIMI_API_KEY"
}

api_key_env 字段可覆盖服务商默认的环境变量名。例如，Moonshot 默认使用 MOONSHOT_API_KEY，但你可以将其指向 KIMI_API_KEY。

命令行参数

octos chat --provider deepseek --model deepseek-chat
octos chat --model gpt-4o  # 根据模型名自动检测服务商

凭证存储

除了环境变量，你也可以通过 auth 命令行存储 API 密钥：

# OAuth PKCE (OpenAI)
octos auth login --provider openai

# Device code 流程 (OpenAI)
octos auth login --provider openai --device-code

# 粘贴令牌（其他所有服务商）
octos auth login --provider anthropic
# -> 提示: "Paste your API key:"

# 查看已存储的凭证
octos auth status

# 删除凭证
octos auth logout --provider openai

凭证存储在 ~/.octos/auth.json（文件权限 0600）。解析 API 密钥时，凭证存储的优先级高于环境变量。

自动检测

省略 --provider 时，Octos 会根据模型名推断服务商：

octos chat --model gpt-4o           # -> openai
octos chat --model claude-sonnet-4-20250514  # -> anthropic
octos chat --model deepseek-chat    # -> deepseek
octos chat --model glm-4-plus       # -> zhipu
octos chat --model qwen-max         # -> dashscope

自定义端点

使用 base_url 指向自部署或代理端点：

{
  "provider": "openai",
  "model": "gpt-4o",
  "base_url": "https://your-azure-endpoint.openai.azure.com/v1"
}

{
  "provider": "ollama",
  "model": "llama3.2",
  "base_url": "http://localhost:11434/v1"
}

{
  "provider": "vllm",
  "model": "meta-llama/Llama-3-70b",
  "base_url": "http://localhost:8000/v1"
}

API 类型覆盖

api_type 字段可在服务商使用非标准协议时强制指定传输格式：

{
  "provider": "zai",
  "model": "glm-5",
  "api_type": "anthropic"
}

• "openai" – OpenAI Chat Completions 格式（大多数服务商的默认值）
• "anthropic" – Anthropic Messages 格式（用于 Anthropic 兼容代理）

降级链

配置一个按优先级排列的降级链。当主服务商请求失败时，自动尝试列表中的下一个服务商：

{
  "provider": "moonshot",
  "model": "kimi-2.5",
  "fallback_models": [
    {
      "provider": "deepseek",
      "model": "deepseek-chat",
      "api_key_env": "DEEPSEEK_API_KEY"
    },
    {
      "provider": "gemini",
      "model": "gemini-2.0-flash",
      "api_key_env": "GEMINI_API_KEY"
    }
  ]
}

故障转移规则：

• 401/403（认证错误）– 立即转移，不在同一服务商上重试
• 429（限流）/ 5xx（服务端错误）– 指数退避重试，之后转移
• 400（内容格式错误）– 当错误包含 "must not be empty"、"reasoning_content"、"API key not valid" 或 "invalid_value" 时转移（不同服务商的验证规则可能不同）
• 超时 – 立即转移（不在无响应的服务商上浪费 120s × 重试次数）
• 熔断器 – 连续 3 次失败将标记该服务商为降级状态

重试配置（指数退避）：

429 错误会从响应体中解析 "try again in Xs" 以实现更智能的退避（回退默认：30s）。

自适应路由

当配置了多个降级模型时，自适应路由会以指标驱动的动态选择取代静态优先级链。

路由模式

三种互斥模式，通过 adaptive_routing.mode 设置：

{
  "adaptive_routing": {
    "mode": "hedge",
    "qos_ranking": true,
    "latency_threshold_ms": 10000,
    "error_rate_threshold": 0.3,
    "probe_probability": 0.1,
    "probe_interval_secs": 60,
    "failure_threshold": 3
  }
}

评分公式（Lane 模式）

每个服务商通过加权 4 因子公式评分，越低越好。所有权重可通过 adaptive_routing 配置：

score = w_stability × blended_error_rate
      + w_quality  × (0.6 × norm_quality + 0.4 × norm_throughput)
      + w_priority × norm_config_order
      + w_cost      × norm_output_price

目录可以从 model_catalog.json 基准文件预填充，使路由器在启动时即具备参考评分而非冷启动启发。

自动升级

当检测到持续的延迟恶化时，会话 actor 会自动激活对冲模式 + 投机队列：

• ResponsivenessObserver 从前 5 次请求学习中位数基线（对异常值鲁棒），然后通过 80/20 EMA 每隔 20 个样本自适应调整基线。
• 如果连续 3 次 LLM 响应超过 3×基线 延迟，对冲竞速和投机队列同时启用。
• 当服务商恢复（一次正常延迟响应）时，两者都恢复为 Followup 和静态路由。

服务商包装栈

路由系统由分层包装器组成：