企业官网建设流程全解析

Portkey Gateway 配置速查：429 重试、多模型 Fallback 与请求级覆盖怎么配

【免费下载链接】gatewayA blazing fast AI Gateway with integrated guardrails. Route to 1,600+ LLMs, 50+ AI Guardrails with 1 fast & friendly API.项目地址: https://gitcode.com/GitHub_Trending/ga/gateway

凌晨两点告警群炸了：OpenAI 429 一路刷屏，客户工单写的是"你们的AI又挂了"。这类故障大多与代码无关，LLM 供应商限流和瞬时过载是常态。业务侧真正缺的是一层能自动兜住错误的中间件：Portkey AI Gateway 插在业务与各 LLM Provider 之间，用一份 JSON 配置定义重试、负载均衡与多模型 fallback。下面把这块拆成几块来讲。

项目定位与架构速写：一层配置插在 App 和各家 LLM 之间

Portkey AI Gateway 是一个基于 Hono 的高性能 AI 网关，把 1600+ LLM 统一收敛到一个 OpenAI 兼容的 API 后面。它解决的问题很聚焦：请求打向哪个供应商、失败后重试还是切换、重复请求要不要走缓存——全部由 Gateway Config 这份 JSON 声明，而不是散落在业务代码的循环里。

关键入口：

• 配置总览与接入方式：cookbook/getting-started/writing-your-first-gateway-config.md
• 负载均衡 + 嵌套 fallback 完整示例：cookbook/getting-started/resilient-loadbalancing-with-failure-mitigating-fallbacks.md

场景化实操：先写配置，再挂到客户端

请求被打回 429 时怎么自动兜住

场景：高峰时段 OpenAI 频繁返回 429，用户侧表现为间歇性超时。最小可用配置只需要一个retry对象：

{ "retry": { "attempts": 3, "on_status_codes": [429, 503] } }

通过 UI 保存后会生成一个配置 ID（形如pc-xxxxx-edx21x），在客户端实例化时引用，所有请求自动继承该行为，无需改动任何业务调用：

const portkey = new Portkey({ apiKey: 'PORTKEY_API_KEY', config: 'pc-xxxxx-edx21x' });

⚠️ 注意：on_status_codes省略时网关默认对[429, 500, 502, 503, 504]重试；想收窄行为就显式列出状态码，想放宽就改attempts（建议不超过 5）。

多模型混用时怎么配 fallback 链

场景：单一供应商的配额扛不住日常流量，需要在多个 Provider 间分流，且任一路挂了要无缝切到备用。targets支持嵌套strategy，外层 loadbalance、内层 fallback：

{ strategy: { mode: 'loadbalance' }, targets: [ { virtual_key: ANTHROPIC_VK, weight: 0.5 }, { strategy: { mode: 'fallback' }, weight: 0.5, targets: [ { virtual_key: OPENAI_VK }, { virtual_key: AZURE_VK } ] } ] }

改哪个字段调行为：weight控制分流比例，把某个 target 的weight设为 0 等于不动代码下线该目标，适合应急切流；override_params则可按 target 单独覆盖model、max_tokens等参数。

想临时改策略又不想动全局配置时怎么办

场景：一个批量任务需要更高的重试次数或临时换模型，但不想把客户端级配置改掉再改回来。config 支持请求级传入，作用于单次调用：

await portkey.chat.completions.create( { messages, model: 'gpt-4' }, { config: { retry: { attempts: 5 } }, traceID: 'batch-2026-09' } );

traceID用来在 Logs 页过滤出这批请求，确认覆盖确实生效；请求结束后行为自动回落，全局配置不受影响。非 SDK 场景（如 axios 直连）则通过x-portkey-config请求头传同一份 JSON，效果一致。

踩坑与取舍：上生产前建议先核对这三点

⚠️坑点一：配置写错是静默的。配置 ID 写错或 JSON 解析失败时，网关不会抛错，而是按默认行为放行（默认重试范围如上所述）。建议上线前先在 Logs 页验证一次真实的 429 是否触发了重试，而不是只看请求"没报错"。

⚠️坑点二：429 的重试依赖 Provider 的 retry 头。源码里（src/handlers/retryHandler.ts）对 429 会先找retry-after类响应头决定等待时长；若 Provider 未返回该头，重试会直接放弃并把错误抛给业务。遇到"重试次数没生效"时先确认响应头，再怀疑配置。

⚠️坑点三：缓存模式选错会省不到钱或省出事故。命中差异直接决定成本和正确性：

✅ 推荐做法：先用 simple 模式观察命中率，确认相似查询确实密集后再切 semantic，并把缓存挂在 fallback 链的每个 target 上，避免切换供应商后缓存失效。

建议下一步从src/handlers/retryHandler.ts的重试循环入手，把 fallback 链端到端跑通，再看src/handlers/handlerUtils.ts里嵌套 targets 的解析逻辑。

【免费下载链接】gatewayA blazing fast AI Gateway with integrated guardrails. Route to 1,600+ LLMs, 50+ AI Guardrails with 1 fast & friendly API.项目地址: https://gitcode.com/GitHub_Trending/ga/gateway