# 一个厂商多个 Key:加权分流、粘性绑定与备用启用

> AI 网关单上游多 API Key:确定性加权哈希分流、调用方粘性绑定、weight=0 备用启用、绑定状态可观测,与跨上游负载均衡正交叠加。

规范链接: https://www.gatellm.io/zh-CN/use-cases/multi-key-pooling/

单上游挂多把 API Key:按权重分流、同一调用方粘性绑定、weight=0 备用 key 兜底 —— 限流与单 key 故障不再硬等。

## 社区真正在抱怨什么
Reddit 高频:「OpenAI 一把 key 的 RPM 不够用,多开几个号怎么轮询」、「key 被限流 429,业务只能硬等」、「切 key 后同一会话的缓存亲和全丢」。
自己写轮询还要处理粘性、权重、备用与失败摘除,工程量不小。

## GateLLM 怎么做
GateLLM 上游表单支持多把 API Key:确定性加权哈希(FNV-1a)把同一调用方粘性绑定到同一把 key(TTL 内稳定,同位轮换不破黏性),权重决定分流比例;某把 key 失败时在该上游内轮换到下一把未试过的 key 重试,但不覆盖首次粘性绑定;weight=0 的 key 作备用,仅当所有 weight>0 的 key 都失败后才启用。
绑定状态(binding / 预测 / stale)在控制台逐行可观测。
与负载均衡器的跨上游 Smooth WRR 正交叠加:上游内选 key,负载均衡器跨上游选上游。

## 落地的 5 个手段
- 多 key 加权:确定性加权哈希分流,权重即比例
- 粘性绑定:同一调用方 TTL 内粘在同一把上游 key,缓存亲和
- 备用 key:weight=0 不参与常规分流,所有活跃 key 失败后才启用
- 绑定可观测:binding / 预测 / stale 状态逐行可查,3s 自动刷新
- 与 LB 正交:上游内选 key + 跨上游 Smooth WRR 叠加,双层分流

## 常问问题
### 换 key 会不会丢 prompt 缓存亲和?
粘性绑定就是为此设计:同一调用方在 TTL 内稳定绑定同一把上游 key,命中同一厂商账号的缓存;key 同位轮换不破黏性,增删 / 重排 / 改权重才触发重选。

### 备用 key 什么时候生效?
weight=0 的 key 平时不参与分流,仅当所有 weight>0 的 key 都试过失败后才启用,且不存绑定。单把 key 请求失败时,网关在该上游内轮换到下一把未试过的 key 重试,但不覆盖首次粘性绑定——后续该调用方的请求仍从原绑定 key 起步。

- [查看配置参考:上游与模型字段(docs 站)](https://docs.gatellm.io/zh-CN/reference/upstreams-models-fields)

## 相关页面
- [首页](https://www.gatellm.io/zh-CN/index.md)
- [定价](https://www.gatellm.io/zh-CN/pricing.md)
- [成本计算器](https://www.gatellm.io/zh-CN/calculator.md)
- [关于](https://www.gatellm.io/zh-CN/about.md)
- [预约演示](https://www.gatellm.io/zh-CN/demo.md)
- [常见问题](https://www.gatellm.io/zh-CN/faq.md)
- [对比 AI 网关](https://www.gatellm.io/zh-CN/compare.md)
- [对比 LiteLLM](https://www.gatellm.io/zh-CN/compare/litellm.md)
- [对比 OpenRouter](https://www.gatellm.io/zh-CN/compare/openrouter.md)
- [对比 Alibaba Cloud AI Gateway](https://www.gatellm.io/zh-CN/compare/alibaba-cloud.md)
- [对比 Azure API Management](https://www.gatellm.io/zh-CN/compare/azure-apim.md)
- [对比 Apigee](https://www.gatellm.io/zh-CN/compare/apigee.md)
- [对比 Cloudflare AI Gateway](https://www.gatellm.io/zh-CN/compare/cloudflare.md)
- [对比 Kong AI Gateway](https://www.gatellm.io/zh-CN/compare/kong.md)
- [对比 Portkey](https://www.gatellm.io/zh-CN/compare/portkey.md)
- [LiteLLM vs Kong AI Gateway 对比](https://www.gatellm.io/zh-CN/compare/litellm-vs-kong.md)
- [LiteLLM vs OpenRouter 对比](https://www.gatellm.io/zh-CN/compare/litellm-vs-openrouter.md)
- [LiteLLM vs Portkey 对比](https://www.gatellm.io/zh-CN/compare/litellm-vs-portkey.md)
- [场景方案](https://www.gatellm.io/zh-CN/use-cases.md)
- [降低调用成本](https://www.gatellm.io/zh-CN/use-cases/reduce-cost.md)
- [做到高可用](https://www.gatellm.io/zh-CN/use-cases/high-availability.md)
- [多租户隔离](https://www.gatellm.io/zh-CN/use-cases/multi-tenant.md)
- [合规与审计](https://www.gatellm.io/zh-CN/use-cases/compliance-audit.md)
- [从症状排障](https://www.gatellm.io/zh-CN/use-cases/troubleshooting.md)
- [混合多供应商模型栈](https://www.gatellm.io/zh-CN/use-cases/mixed-model-stack.md)
- [在 Office 里自托管用 AI](https://www.gatellm.io/zh-CN/use-cases/self-hosted-office-ai.md)
- [Token 用量可见与归因](https://www.gatellm.io/zh-CN/use-cases/token-ops.md)
- [Token FinOps: AI 支出分摊与管控](https://www.gatellm.io/zh-CN/use-cases/token-finops.md)
- [MCP 工具治理](https://www.gatellm.io/zh-CN/use-cases/mcp-tool-governance.md)
- [给模型统一加联网搜索](https://www.gatellm.io/zh-CN/use-cases/web-search-grounding.md)
- [限制接入的客户端](https://www.gatellm.io/zh-CN/use-cases/client-admission-control.md)
- [强制模型使用策略](https://www.gatellm.io/zh-CN/use-cases/enforce-model-policy.md)
- [客户端不暴露模型选择](https://www.gatellm.io/zh-CN/use-cases/automatic-model-tiering.md)
- [一套协议接任意模型](https://www.gatellm.io/zh-CN/use-cases/one-protocol-any-model.md)
- [Office / Microsoft 365 加载项](https://www.gatellm.io/zh-CN/office-addin.md)
- [术语表](https://www.gatellm.io/zh-CN/glossary.md)
- [模型目录](https://www.gatellm.io/zh-CN/models.md)
- [SDK 与框架集成](https://www.gatellm.io/zh-CN/integrations.md)
- [AI Coding Agent 与 Harness](https://www.gatellm.io/zh-CN/coding-agents.md)
- [安全与合规](https://www.gatellm.io/zh-CN/security.md)
- [隐私政策](https://www.gatellm.io/zh-CN/privacy-policy.md)
- [服务条款](https://www.gatellm.io/zh-CN/terms.md)
- [Cookie 政策](https://www.gatellm.io/zh-CN/cookies.md)
- [数据处理协议 (DPA)](https://www.gatellm.io/zh-CN/dpa.md)
- [子处理方清单](https://www.gatellm.io/zh-CN/subprocessors.md)
- [安全问卷预答库 (CAIQ/SIG/VSA)](https://www.gatellm.io/zh-CN/trust.md)
- [事故响应与支持服务](https://www.gatellm.io/zh-CN/sla.md)
- [漏洞披露政策](https://www.gatellm.io/zh-CN/vulnerability-disclosure.md)
- [开源许可声明](https://www.gatellm.io/zh-CN/open-source-licenses.md)
- [版本支持与生命周期 (EOL)](https://www.gatellm.io/zh-CN/lifecycle.md)
- [技术博客](https://www.gatellm.io/zh-CN/blog.md)
- [你的 Agent 权限比员工还大:在网关层治理 MCP 工具](https://www.gatellm.io/zh-CN/blog/mcp-tool-governance.md)
- [一张一万美元的账单:五种降低 LLM 成本又不让应用变笨的做法](https://www.gatellm.io/zh-CN/blog/reduce-cost.md)
- [厂商的目录价不是你的成本:把真正的 FinOps 用到 Token 支出上](https://www.gatellm.io/zh-CN/blog/token-finops.md)
- [llms.txt](https://www.gatellm.io/zh-CN/llms.txt)