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 未返回该头重试会直接放弃并把错误抛给业务。遇到重试次数没生效时先确认响应头再怀疑配置。⚠️坑点三缓存模式选错会省不到钱或省出事故。命中差异直接决定成本和正确性维度方案 Asimple cache方案 Bsemantic cache命中条件prompt 完全一致语义相似度过阈值成本收益低只挡重复请求高改写/近似问法也能命中风险几乎无近义问题可能返回不贴切答案适用客服、工单等重复话术知识库问答等近似查询密集场景✅ 推荐做法先用 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 18:39:32 · 阅读 1.2k Portkey Gateway 配置速查：429 重试、多模型 Fallback 与请求级覆盖怎么配
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 未返回该头重试会直接放弃并把错误抛给业务。遇到重试次数没生效时先确认响应头再怀疑配置。⚠️坑点三缓存模式选错会省不到钱或省出事故。命中差异直接决定成本和正确性维度方案 Asimple cache方案 Bsemantic cache命中条件prompt 完全一致语义相似度过阈值成本收益低只挡重复请求高改写/近似问法也能命中风险几乎无近义问题可能返回不贴切答案适用客服、工单等重复话术知识库问答等近似查询密集场景✅ 推荐做法先用 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考