GateLLM

外观

负载均衡字段 ​

本章讲负载均衡器的字段表、重试配置、与密钥组的关系、重试相关环境变量。操作步骤（怎么建一个 LB）见 创建负载均衡器，粘性会话见 开启粘性会话。

字段表 ​

字段类型默认值说明
namestring（必需）客户端调用时填的模型名
aliasesarray[]额外可用的名字
entriesarray（必需）节点列表，每项含 {upstream, model, weight}
retry_on_different_nodebooltrue出错时自动重试到其他节点
extra_config.sticky_session_enabledbooltrue粘性会话开关，嵌在 extra_config 下（非顶层字段）。启用后同一客户端持续路由到同一节点；关闭则每请求按权重重选
binding_ttl_secsu64300绑定有效期（秒）；0 = 永久绑定
binding_key_templatestring—自定义绑定键，支持 {{access_key_hash}}、{{header:X}}
static_bindingsarray[]管理员预设的固定绑定
enabledbooltrue

entries 字段 ​

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

json
{
  "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}
  ]
}

权重规则：

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

static_bindings 字段 ​

json
{
  "static_bindings": [
    {
      "binding_key": "vip-user-hash",
      "upstream": "openai-us",
      "model": "gpt-4o",
      "access_key": "alice-key"
    },
    {
      "binding_key": "team-a-hash",
      "upstream": "openai-eu",
      "model": "gpt-4o",
      "access_key_group": "team-a"
    }
  ]
}
  • binding_key：手动指定的绑定键值（不是模板，直接写实际值）
  • upstream + model：固定路由目标
  • access_key / access_key_group：限定到某密钥或密钥组（可选）

重试配置 ​

故障转移由重试相关环境变量控制（无状态、每请求独立，无跨请求失败记忆）：

变量默认值作用
MAX_UPSTREAM_RETRIES3单请求最大重试次数（跨所有凭据累计）
MAX_KEY_ROTATIONS0最多轮换多少把不同的上游凭据；0 = 不限

跨所有重试层（凭据轮换 + LB 节点故障转移）的总尝试上限固定为 6，硬顶防止 N×M 放大，不通过环境变量开放。

当 retry_on_different_node = true（默认）时：

  1. 请求发到当前选中节点
  2. 节点返回可重试错误（5xx、连接超时、读取超时；4xx 与解析错误不可重试，直接失败）
  3. 网关自动选下一个节点重试
  4. 重试受 MAX_UPSTREAM_RETRIES 与固定的总尝试上限双重约束

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

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

与密钥组的关系 ​

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

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

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

常见问题 ​

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

Q：流式请求中途切换节点吗？ 不支持。流式重试仅在发送第一个 SSE 数据块之前尝试。一旦客户端开始接收数据，即使节点故障也不会中途换节点。

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

下一步：创建负载均衡器 看操作步骤；开启粘性会话 看绑定键与静态绑定；环境变量配置参考 看全部环境变量；访问密钥与密钥组字段 看密钥组的 LB 维度。