请求路由

ai.TokenHub 提供多层级、高弹性的智能请求路由机制，支持按不同策略将请求分发到最适合的大模型服务商，实现成本优化、高可用和性能最优的平衡。

核心路由类型

ai.TokenHub 共支持 5 种路由策略，可满足不同场景的需求：

---

1. 精确路由 (Exact Routing) - 基于模型名称前缀

这是最直接、确定性最强的路由方式，可精确指定请求发送到哪个服务商。

规则

在 API 请求的 model 字段中使用 provider/model 格式，系统会直接解析前缀并转发到对应服务商。

示例

{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ]
}

其他示例：

• anthropic/claude-3-opus
• deepseek/deepseek-chat
• zhipu/glm-4

工作流程

1. 系统解析模型前缀 openai/
2. 直接将请求转发给 OpenAI 服务商
3. 使用后缀 gpt-4o 作为实际请求的模型名称

适用场景

• 调试特定服务商的功能
• 需要确保请求发送到某一特定后端（例如该服务商有独占模型或更优价格）
• 强制绕过负载均衡规则，避免请求被分发到其他服务商

---

2. 负载均衡路由 (Load-Balanced Routing) - 基于虚拟密钥权重

这是 ai.TokenHub 最强大的路由功能，允许将请求按比例分发到多个服务商，实现成本、性能和可用性的最佳平衡。

规则

通过虚拟密钥 (Virtual Key) 配置权重策略，创建虚拟密钥时，可以添加多个服务商并为每个服务商设置权重值。请求中 model 字段不需要包含服务商前缀（例如只写 "gpt-4o"）。

工作流程

1. 系统根据请求中的虚拟密钥和模型名
2. 在模型目录 (Model Catalog) 中查找所有支持该模型的健康服务商
3. 按照虚拟密钥中配置的权重比例随机选择其中一个服务商转发请求

权重计算示例

虚拟密钥配置：

服务商	权重	流量占比
OpenAI	70	~70%
Azure	30	~30%

最终结果：大约 70% 的 gpt-4o 请求发送至 OpenAI，30% 发送至 Azure OpenAI。

适用场景

• 成本优化：将大部分流量导向更便宜的服务商（如 DeepSeek、Moonshot）
• A/B 测试：对比不同服务商同一模型的响应质量或延迟
• 故障转移 (Failover)：结合健康检查，当主服务商不可用时自动切换到备用服务商

---

3. 故障转移与回退路由 (Fallback Routing)

ai.TokenHub 具备内置的弹性机制，用于处理服务商故障或模型不可用的情况，提升服务整体可用性。

规则类型

1. 精确路由故障转移：当精确路由指定的服务商返回错误（如 5xx 服务错误、429 限流）或超时时，系统可配置自动尝试模型目录中其他支持该模型的服务商。
2. 负载均衡故障转移：当负载均衡选中的服务商失败时，系统会从剩余的健康服务商中按权重重新选择，自动重试。

配置方式

在虚拟密钥设置中开启 Fallback Enabled 选项，并可设置最大重试次数（默认 2 次）。

适用场景

• 提升生产环境的高可用性（HA），避免单点故障
• 应对突发的大模型服务商宕机或限流事件
• 关键业务链路的可靠性保障

---

4. 条件路由 (Conditional Routing) - 基于请求头或参数

ai.TokenHub 支持根据请求的特定元数据动态修改路由行为，实现高度自定义的路由策略。

常见条件规则示例

• 基于用户/密钥的路由覆盖：即使请求写了 openai/gpt-4，但若虚拟密钥配置中强制指定了路由策略，则以后者为准
• 基于 Stream 模式：可配置非流式请求走 A 服务商，流式请求走 B 服务商（因为某些服务商对流式支持更好）
• 基于内容长度：长文本自动路由到支持大上下文窗口且价格较低的服务商
• 基于优先级标签：高优先级业务请求优先路由到更稳定、延迟更低的服务商

实现方式

通过 ai.TokenHub 的 插件系统 (Plugins) 或 中间件 自定义逻辑实现，支持完全可编程的路由规则。

---

5. 缓存路由 (Cache Routing)

虽然不是严格意义上的服务商路由，但它决定了请求是否直接由 ai.TokenHub 响应而不经过后端 LLM，可大幅降低成本和延迟。

规则

启用语义缓存（Semantic Cache）或精确匹配缓存后，符合条件的请求直接返回缓存结果，无需调用后端大模型。

路由优先级

缓存命中 > 精确路由/负载均衡路由。如果缓存命中，请求甚至不会发送到任何 LLM 服务商。

---

路由决策流程图

当你在 ai.TokenHub 上发起一个请求时，路由决策遵循以下逻辑：

请求进入
    │
    ├─ 1. 检查缓存 -> 命中？ -> 返回缓存结果（结束）
    │               否 ↓
    ├─ 2. 解析虚拟密钥/认证信息
    │
    ├─ 3. 检查 model 字段是否有服务商前缀？
    │      ├─ 有前缀 -> **精确路由**：直接发送至指定服务商
    │      │              │
    │      │              ├─ 成功？ -> 返回结果
    │      │              └─ 失败？ -> 根据故障转移配置决定是否尝试其他服务商
    │      │
    │      └─ 无前缀 -> **负载均衡路由**：
    │                     ├─ 查询模型目录中支持该模型的健康服务商列表
    │                     ├─ 结合虚拟密钥中的权重配置
    │                     ├─ 按权重随机选择一个服务商
    │                     └─ 发送请求（失败则按权重重试下一个）

API 配置示例

虚拟密钥路由配置

{
  "api_key": "sk-xxxxxx",
  "name": "生产环境密钥",
  "routing": {
    "strategy": "weighted_load_balance",
    "providers": [
      {
        "provider": "openai",
        "weight": 70,
        "enabled": true,
        "models": ["gpt-4o", "gpt-3.5-turbo"]
      },
      {
        "provider": "azure",
        "weight": 30,
        "enabled": true,
        "models": ["gpt-4o", "gpt-3.5-turbo"]
      }
    ],
    "fallback": {
      "enabled": true,
      "max_retries": 2,
      "retry_on": ["5xx", "429", "timeout"]
    },
    "cache": {
      "semantic_cache_enabled": true,
      "cache_ttl": "1h",
      "similarity_threshold": 0.9
    }
  }
}

请求路由参数示例

curl https://ai-tokenhub.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true,
    "routing_options": {
      "preferred_provider": "openai",
      "fallback_enabled": true,
      "cache_enabled": true
    }
  }'

响应中的路由信息

每个API响应都会在头部返回实际路由信息：

X-Routed-Provider: openai
X-Routed-Model: gpt-4o
X-Cache-Hit: false
X-Response-Time: 234ms