创建负载均衡器

当同一个模型有多个上游/节点可用时，负载均衡器（LoadBalancer）在它们之间分发请求，提供故障转移、权重分配和粘性会话。

入口：控制台 → 负载均衡器（仅 admin）。

核心概念

• LoadBalancer 本身就是一个"模型名"：客户端用 LB 的 name（如 gpt-4o-ha）调用，跟调用普通模型一样。entries / weight 的含义见 多上游负载均衡。

创建负载均衡器

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

字段	类型	默认值	说明
名称	string	（必需）	客户端调用时填的模型名
别名	string[]	[]	额外可用的名字
entries	array	（必需）	节点列表，每项含 {upstream, model, weight}
出错换节点	bool	true	retry_on_different_node，出错时自动重试到其他节点
粘性会话	bool	true	启用后同一客户端持续路由到同一节点（默认开启）
粘性 TTL	u64	300	绑定有效期（秒）；0 = 永久绑定
绑定键模板	string	—	自定义绑定键，支持 {{access_key_hash}}、{{header:X}}
静态绑定	array	[]	管理员预设的固定绑定
启用	bool	true

Entries 配置

每个 entry 指定一个上游+模型组合及其权重：

在 LB 表单的条目区点 + 添加条目，逐行填（上游是下拉选、模型下拉随上游联动只列该上游下的模型、权重填 0–255）：

上游	模型	权重
openai-us	gpt-4o	5
openai-eu	gpt-4o	3
openai-backup	gpt-4o	0（备用）

权重规则：

• weight > 0：正常节点，按权重比例分配请求（如 5:3 表示 62.5%:37.5%）
• weight = 0：备用节点，仅在所有正常节点不可用时启用
• 权重范围 0–255

故障转移

当 retry_on_different_node = true（默认）时：

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

当所有节点都失败（被排除）或没有可用节点时，网关在重试预算耗尽后返回 503，响应携带最后一次错误。

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

与密钥组的关系

负载均衡器是密钥组里独立于模型的授权维度：密钥组的 load_balancers 列表需包含该负载均衡器的名称（或 "*"），密钥才能通过 LB 调用。models 维度只管普通模型，「所有模型」不会附带放行负载均衡器：

控制台 → 访问密钥 → 密钥组 → 新建 full-access：模型页签点「所有模型」（*）→ 负载均衡器页签勾选 gpt-4o-ha。

LB 是授权单元：网关只在请求进入时校验一次 LB 名称是否在密钥组的 load_balancers 白名单内，不会再用密钥组的 models 列表去逐个校验该 LB 内配置的 entry。也就是说，一旦密钥组放行了某个 LB，该组密钥就能到达该 LB 里配置的每一个 entry——哪怕这些密钥的 models 列表为空、或不含这些 entry 的模型名。

配 LB 时的注意点：把一个模型放进某 LB 的 entry，等于向所有持该 LB 权限的密钥开放该模型。LB 的 entry 集合 = 所有持该 LB 权限密钥的可达并集。若要严格限制某密钥只能用某个模型，应把它配成普通模型并加入该密钥组的 models 列表，而非放进一个已被授权的 LB。

控制台 → 访问密钥 → 密钥组 → 编辑 → 「负载均衡器」子页签勾选对应 LB。

完整案例

OpenAI 高可用（双上游 + 备用）与多供应商故障转移（OpenAI + Azure）两个可复制案例，含完整 JSON 配置与 curl 调用，见 多上游负载均衡。本页只讲建 LB 的字段与故障转移/授权机制。

常见问题

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

Q：怎么让某个密钥不走 LB，直接调某个上游？ 建一个普通模型指向该上游，密钥组的 models 列表包含这个普通模型即可。LB 和普通模型可以同时存在。

Q：所有节点都失败了怎么办？ 网关在重试预算内逐个尝试节点；全部失败后返回 503，响应携带最后一次错误。若上游确实全挂，检查上游配置和连接。

Q：权重设为 0 的备用节点什么时候会被用到？ 仅在所有 weight > 0 的正常节点都不可用时。正常节点恢复后，流量自动切回。

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

下一步：负载均衡字段 看完整字段表与重试配置；开启粘性会话 看粘性会话与静态绑定；多上游负载均衡 quickstart 看场景化示例。