跳到主要内容
版本：3.10.x

配置多模型路由和自动故障转移

本指南介绍如何使用 ai-proxy-multi 插件在多个模型和服务提供方之间分发 AI 流量，包括配置加权负载均衡、自动故障转移和基于优先级的路由。

概览​

依赖单一模型服务提供方会带来服务中断、限流配额耗尽和成本激增等风险。ai-proxy-multi 插件通过可配置的负载均衡、健康检查和故障转移策略，在多个模型实例之间路由流量。

常见用例：

  • 成本优化 — 将大部分流量路由到低成本模型，并以高级模型作为质量保障。
  • 高可用 — 服务提供方中断或被限流时自动故障转移。
  • 容量分配 — 在多个服务提供方之间分散负载，避免触及单个服务提供方的限流阈值。

前置条件​

  • 安装 Docker。

  • 安装 cURL，用于发送请求并验证服务。

  • 拥有一个正在运行的 API7 网关实例。

  • 从控制台获取令牌，并保存到环境变量：

    export API_KEY=your-dashboard-token   # 请替换为你的控制台令牌

  • 将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。

  • 如果使用 Admin API 示例，请创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后保存其 ID：

    export SERVICE_ID=your-service-id         # 请替换为你的服务 ID

加权负载均衡​

根据成本与性能之间的权衡，在多个模型之间分发流量：

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "multi-llm-weighted",
    "service_id": "$SERVICE_ID",
    "paths": ["/ai"],
    "plugins": {
      "ai-proxy-multi": {
        "balancer": {
          "algorithm": "roundrobin"
        },
        "instances": [
          {
            "name": "gpt-4o-mini",
            "provider": "openai",
            "auth": { "header": { "Authorization": "Bearer $OPENAI_API_KEY" } },
            "options": { "model": "gpt-4o-mini" },
            "weight": 8
          },
          {
            "name": "gpt-4o",
            "provider": "openai",
            "auth": { "header": { "Authorization": "Bearer $OPENAI_API_KEY" } },
            "options": { "model": "gpt-4o" },
            "weight": 2
          }
        ]
      }
    }
  }
EOF

❶ 设置负载均衡算法。roundrobin 根据实例权重分发请求。

❷ 为 gpt-4o-mini 分配权重 8，约 80% 的流量会进入该实例。

❸ 为 gpt-4o 分配权重 2，让 20% 的流量获得高级模型质量。

自动故障转移​

配置故障转移策略，使流量在服务提供方不可用或被限流时自动重新路由。

fallback_strategy 字段支持两种模式：

  • 单一策略（字符串）："instance_health_and_rate_limiting"、"http_429" 或 "http_5xx"。
  • 组合策略（数组）：任一条件匹配时触发故障转移，例如 ["rate_limiting", "http_429", "http_5xx"]。

instance_health_and_rate_limiting 为向后兼容而保留，功能上等同于 rate_limiting。新配置使用数组形式时，请优先使用 rate_limiting。

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "multi-llm-failover",
    "service_id": "$SERVICE_ID",
    "paths": ["/ai"],
    "plugins": {
      "ai-proxy-multi": {
        "fallback_strategy": ["http_429", "http_5xx"],
        "instances": [
          {
            "name": "openai-primary",
            "provider": "openai",
            "auth": { "header": { "Authorization": "Bearer $OPENAI_API_KEY" } },
            "options": { "model": "gpt-4o" },
            "weight": 1,
            "priority": 2
          },
          {
            "name": "anthropic-fallback",
            "provider": "anthropic",
            "auth": { "header": { "Authorization": "Bearer $ANTHROPIC_API_KEY" } },
            "options": { "model": "claude-sonnet-4-20250514" },
            "weight": 1,
            "priority": 1
          }
        ]
      }
    }
  }
EOF

❶ 当前实例返回 HTTP 429（限流）或 5xx（服务器错误）时触发故障转移。

❷ OpenAI 是优先级最高（2）的主实例。

❸ Anthropic 是优先级较低（1）的备用实例，仅当 OpenAI 返回 429 或 5xx 时才将流量路由到此实例。

跨服务提供方路由策略​

根据具体目标组合不同服务提供方：

成本优化​

优先路由到成本最低的模型，并使用高级模型作为备用：

实例服务提供方模型优先级用途
deepseek-primaryDeepSeekdeepseek-chat1每 Token 成本最低
gpt-4o-mini-secondaryOpenAIgpt-4o-mini2中等成本备用实例
gpt-4o-premiumOpenAIgpt-4o3质量最高的备用实例

容量分配​

在多个服务提供方之间分散负载，避免触及各自的限流阈值：

实例服务提供方模型权重用途
openai-poolOpenAIgpt-4o550% 的流量
anthropic-poolAnthropicclaude-sonnet-4-20250514330% 的流量
deepseek-poolDeepSeekdeepseek-chat220% 的流量

响应流式传输​

ai-proxy-multi 插件透明地处理服务器发送事件（SSE）流式传输。客户端发送 "stream": true 时，无论使用哪个服务提供方，网关都会从实际处理请求的实例流式返回 Token。

多模型路由无需额外配置即可进行流式传输。如果 SSE 事件被缓冲，请使用 proxy-buffering 插件禁用 NGINX proxy_buffering。

验证​

发送请求测试多模型路由：

curl "http://127.0.0.1:9080/ai" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

你应收到某个已配置实例的响应。响应中的 model 字段表示处理该请求的实例。

后续步骤​