多上游负载均衡

当同一个模型有多个上游/节点可用时，负载均衡器（LoadBalancer）在它们之间分发请求，提供故障转移、权重分配和粘性会话。本章带你建两个完整案例：OpenAI 高可用（双 OpenAI + 备用）和多供应商故障转移（OpenAI + Azure）。

你将完成什么

• 一个 OpenAI 高可用负载均衡器 gpt-4o-ha（3 个节点：美区 + 欧区 + 备用）
• 或一个多供应商负载均衡器 gpt-4o-multi（OpenAI 主 + Azure 备）
• 密钥组的 load_balancers 维度放行 LB
• 客户端用 LB name 调用

前置

• 网关已运行（http://localhost:7890），能登录控制台
• 多把上游 API key（OpenAI 美区/欧区、Azure OpenAI 等）

核心概念

• LoadBalancer 本身就是一个"模型名"：客户端用 LB 的 name（如 gpt-4o-ha）调用，跟调用普通模型一样
• entries：LB 下的节点列表，每个指向一个上游+模型的组合
• weight：权重越高分配越多请求；weight=0 为备用节点，仅在正常节点全部不可用时启用

案例 A：OpenAI 高可用

场景：两个 OpenAI 上游（美区+欧区），加一个备用上游，实现故障自动转移。

1. 建 3 个上游

控制台 → 上游服务 → 新建，分别建：

⚠️ OpenAI 不提供区域子域——api-eu.openai.com、api-backup.openai.com 这类地址不存在，照抄会 DNS 失败。下面三个上游用同一 OpenAI 端点、不同账号（组织）的 API key 实现多账号高可用与故障转移；名称里的 us/eu 仅作区分，不对应真实地理区域。跨供应商容灾见案例 B。

名称	协议	基础 URL
openai-us	openai	https://api.openai.com/v1
openai-eu	openai	https://api.openai.com/v1
openai-backup	openai	https://api.openai.com/v1

每个上游填各自账号的 API key。三个上游端点相同、凭据独立，网关在它们之间按权重分发、故障转移。

2. 各上游下建模型 gpt-4o

在每个上游下展开 → 模型子表 → 新建模型 gpt-4o，上游模型 ID 都填 gpt-4o。

3. 建负载均衡器

控制台 → 负载均衡器 → 新建：

{
  "name": "gpt-4o-ha",
  "entries": [
    {"upstream": "openai-us", "model": "gpt-4o", "weight": 5},
    {"upstream": "openai-eu", "model": "gpt-4o", "weight": 3},
    {"upstream": "openai-backup", "model": "gpt-4o", "weight": 0}
  ],
  "retry_on_different_node": true,
  "extra_config": { "sticky_session_enabled": false }
}

ℹ️ 这里显式设 extra_config.sticky_session_enabled = false 是为了演示按 5:3 权重分发：粘性会话默认 true（同一客户端粘同一节点），开启时权重比例不会逐请求体现。要演示加权分发就关掉它。粘性会话细节见开启粘性会话。

保存。

4. 配密钥组放行 LB

控制台 → 访问密钥 → 密钥组 → 找到目标密钥组 → 编辑 → 「负载均衡器」子页签 → 勾选 gpt-4o-ha（或 *）。

{
  "name": "full-access",
  "models": ["*"],
  "load_balancers": ["gpt-4o-ha"]
}

「所有模型」不附带负载均衡器权限，反之亦然——两个维度要分别勾选。

5. 客户端用 LB name 调用

curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <你的访问密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-ha",
    "messages": [{"role":"user","content":"hi"}]
  }'

网关按 5:3 权重在 openai-us / openai-eu 间分发请求。某节点故障时自动重试到其他节点（retry_on_different_node=true，受 MAX_UPSTREAM_RETRIES 控制）。所有正常节点不可用时启用备用节点 openai-backup（weight=0）。

案例 B：多供应商故障转移

场景：主用 OpenAI，备用 Azure OpenAI，实现供应商级容灾。

1. 建上游

名称	协议	基础 URL
openai	openai	https://api.openai.com/v1
azure-openai	openai	https://{resource}.openai.azure.com/openai/v1

2. 各上游下建模型

• openai 下建模型 gpt-4o，上游模型 ID gpt-4o
• azure-openai 下建模型 gpt-4o-deploy，上游模型 ID 用 Azure 部署名

3. 建负载均衡器

{
  "name": "gpt-4o-multi",
  "entries": [
    {"upstream": "openai", "model": "gpt-4o", "weight": 10},
    {"upstream": "azure-openai", "model": "gpt-4o-deploy", "weight": 5}
  ],
  "retry_on_different_node": true
}

4. 密钥组放行 + 客户端调用

同案例 A 第 4-5 步，把 LB name 换成 gpt-4o-multi。

故障转移行为

当 retry_on_different_node = true（默认）时：

1. 请求发到当前选中节点
2. 节点返回可重试错误（5xx、连接超时、读取超时）
3. 网关自动选下一个节点重试
4. 重试次数受 MAX_UPSTREAM_RETRIES 控制

当所有节点都不可用时，网关在重试预算耗尽后返回 503，响应携带最后一次错误。

流式响应限制：流式重试仅在发送第一个 SSE 数据块之前尝试。一旦客户端开始接收数据，不支持中途换节点。

常见问题

Q：LB 的 name 和普通模型的 name 冲突了怎么办？ LB 和普通模型共享全局唯一名称空间。不能有同名的 LB 和模型。

Q：客户端报 403？ 密钥组的 load_balancers 列表没包含 LB name。检查「负载均衡器」子页签是否勾选。

Q：客户端报 503 持续不停？ 所有节点都不可用。检查每个上游的 base_url 和 API key。若上游确实全挂，网关在重试预算耗尽后返回 503。

Q：怎么开粘性会话（同一客户端持续路由到同一节点）？ 见 开启粘性会话。

Q：怎么监控各节点健康状态？ 控制台 → 负载均衡器 → 点该 LB → Entries 面板，看每个节点的状态（healthy/unavailable）与有效权重（等于配置权重）。

下一步：创建负载均衡器 看完整字段表与操作步骤；负载均衡字段 看完整字段表与重试配置；访问密钥与密钥组字段 看密钥组的负载均衡器维度。