LLM 限流场景下编写 retry 与 fallback 网关配置Portkey AI Gateway 实践【免费下载链接】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生产服务里调用模型 API偶发的 429 限流和上游 5xx 错误如果应用层不处理用户只能看到失败。本文以开源项目 Portkey AI Gateway 为例说明如何用一段 config 让请求自动重试retry并在重试无果时切到备用模型fallback。一个真实场景高峰时段产品的聊天接口把请求集中打向单一模型供应商接连返回 429部分请求直接超时拿不到响应。应用代码里没写重试这些错误会原样抛给前端。想临时切到备用模型就得改散落在各处的 baseURL 和密钥改起来又慢又容易漏。这类场景里网关的职责就是统一处理瞬时失败命中指定状态码就自动重试若干次重试仍失败再执行 fallback 到备用目标。在 Portkey 开源网关中这两件事都表达为一段 JSON 配置由请求头携带不需要在业务代码里写控制循环。最小可用配置最短路径是只写一个retry块让请求在遇到 429 时自动重试 3 次{ retry: { attempts: 3, // 最大重试次数上限 5 on_status_codes: [429] // 触发重试的状态码列表 } }on_status_codes可以省略此时默认按[429, 500, 502, 503, 504]重试对应src/globals.ts里的RETRY_STATUS_CODES常量。这段配置随请求放在x-portkey-config请求头中下发自托管部署时插件开关、缓存等选项则放在仓库根目录的 conf.example.json 里维护。接入你的代码用portkey-aiSDK 时把配置作为create的第二个参数传入即可import { Portkey } from portkey-ai; const portkey new Portkey({ apiKey: 你的apiKey }); const response await portkey.chat.completions.create( { model: gpt-4, messages: [{ role: user, content: What are 7 wonders of the world? }], }, { config: JSON.stringify({ retry: { attempts: 3, on_status_codes: [429] } }) } // 经 x-portkey-config 下发 ); console.log(response.choices[0].message.content);如果团队坚持沿用 OpenAI SDK把 baseURL 指到网关、再用createHeaders附带 provider、apiKey 和同一份 config 即可配置内容不变可参考仓库内 automatic-retries-on-failures.md 的完整示例。容易踩的 2-3 个坑坑 1只写了on_status_codes请求直接被校验拒绝。现象网关返回配置校验错误请求根本没发出去。原因zod schema 中retry.attempts是必填字段省略会直接报retry.attempts must be defined。排查方法对照 config.ts 的configSchema检查整份 config 至少要满足一个有效组合providerapi_key、strategytargets或cache/retry/request_timeout之一。坑 2拿到 429 后没有重试直接失败。现象上游返回带retry-after的 429但网关没有等待下一次尝试。原因retryHandler.ts 里重试总预算只有 60 秒MAX_RETRY_LIMIT_MS当上游要求的等待时间超过剩余预算时重试被跳过并直接返回原错误。排查方法检查上游响应里的retry-after数值过大就降低重试次数或先放宽上游配额。坑 3分不清这次响应是第几次尝试拿到的。现象重试成功和首次成功在响应体里长得一样。原因网关不在 body 里额外标记尝试次数。排查方法读响应头x-portkey-retry-attempt-count看实际尝试了几次fallback 场景再用x-portkey-last-used-option-index确认最终命中的是targets里的哪一项。深入与验证重试与超时控制的完整实现src/handlers/retryHandler.ts配置字段与校验规则src/middlewares/requestValidator/schema/config.ts自托管配置样例插件、凭据、限流conf.example.json确认配置生效的具体动作发一次请求后检查响应头x-portkey-retry-attempt-count再在网关的 Logs 页面按x-portkey-trace-id搜索这条请求能看到每次上游调用的状态码是否触发过重试或 fallback 一眼可见。retry 和 fallback 的价值在于把瞬时失败怎么办从业务代码下沉成一份声明式配置第一条 retry 配置跑通之后扩展到 loadbalance 或多级 fallback只是往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），仅供参考
LLM 限流场景下编写 retry 与 fallback 网关配置：Portkey AI Gateway 实践
LLM 限流场景下编写 retry 与 fallback 网关配置Portkey AI Gateway 实践【免费下载链接】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生产服务里调用模型 API偶发的 429 限流和上游 5xx 错误如果应用层不处理用户只能看到失败。本文以开源项目 Portkey AI Gateway 为例说明如何用一段 config 让请求自动重试retry并在重试无果时切到备用模型fallback。一个真实场景高峰时段产品的聊天接口把请求集中打向单一模型供应商接连返回 429部分请求直接超时拿不到响应。应用代码里没写重试这些错误会原样抛给前端。想临时切到备用模型就得改散落在各处的 baseURL 和密钥改起来又慢又容易漏。这类场景里网关的职责就是统一处理瞬时失败命中指定状态码就自动重试若干次重试仍失败再执行 fallback 到备用目标。在 Portkey 开源网关中这两件事都表达为一段 JSON 配置由请求头携带不需要在业务代码里写控制循环。最小可用配置最短路径是只写一个retry块让请求在遇到 429 时自动重试 3 次{ retry: { attempts: 3, // 最大重试次数上限 5 on_status_codes: [429] // 触发重试的状态码列表 } }on_status_codes可以省略此时默认按[429, 500, 502, 503, 504]重试对应src/globals.ts里的RETRY_STATUS_CODES常量。这段配置随请求放在x-portkey-config请求头中下发自托管部署时插件开关、缓存等选项则放在仓库根目录的 conf.example.json 里维护。接入你的代码用portkey-aiSDK 时把配置作为create的第二个参数传入即可import { Portkey } from portkey-ai; const portkey new Portkey({ apiKey: 你的apiKey }); const response await portkey.chat.completions.create( { model: gpt-4, messages: [{ role: user, content: What are 7 wonders of the world? }], }, { config: JSON.stringify({ retry: { attempts: 3, on_status_codes: [429] } }) } // 经 x-portkey-config 下发 ); console.log(response.choices[0].message.content);如果团队坚持沿用 OpenAI SDK把 baseURL 指到网关、再用createHeaders附带 provider、apiKey 和同一份 config 即可配置内容不变可参考仓库内 automatic-retries-on-failures.md 的完整示例。容易踩的 2-3 个坑坑 1只写了on_status_codes请求直接被校验拒绝。现象网关返回配置校验错误请求根本没发出去。原因zod schema 中retry.attempts是必填字段省略会直接报retry.attempts must be defined。排查方法对照 config.ts 的configSchema检查整份 config 至少要满足一个有效组合providerapi_key、strategytargets或cache/retry/request_timeout之一。坑 2拿到 429 后没有重试直接失败。现象上游返回带retry-after的 429但网关没有等待下一次尝试。原因retryHandler.ts 里重试总预算只有 60 秒MAX_RETRY_LIMIT_MS当上游要求的等待时间超过剩余预算时重试被跳过并直接返回原错误。排查方法检查上游响应里的retry-after数值过大就降低重试次数或先放宽上游配额。坑 3分不清这次响应是第几次尝试拿到的。现象重试成功和首次成功在响应体里长得一样。原因网关不在 body 里额外标记尝试次数。排查方法读响应头x-portkey-retry-attempt-count看实际尝试了几次fallback 场景再用x-portkey-last-used-option-index确认最终命中的是targets里的哪一项。深入与验证重试与超时控制的完整实现src/handlers/retryHandler.ts配置字段与校验规则src/middlewares/requestValidator/schema/config.ts自托管配置样例插件、凭据、限流conf.example.json确认配置生效的具体动作发一次请求后检查响应头x-portkey-retry-attempt-count再在网关的 Logs 页面按x-portkey-trace-id搜索这条请求能看到每次上游调用的状态码是否触发过重试或 fallback 一眼可见。retry 和 fallback 的价值在于把瞬时失败怎么办从业务代码下沉成一份声明式配置第一条 retry 配置跑通之后扩展到 loadbalance 或多级 fallback只是往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），仅供参考
