如何给 LLM 调用加自动重试与多模型 fallbackPortkey 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凌晨的监控里突然刷出一排 429 和 503聊天接口的错误率开始爬坡。这篇文章带你把 Portkey Gateway 的网关配置从零跑通一遍写一份重试配置、接到现有 SDK、再验证它真的生效。做完后你能独立维护一份带重试、fallback 和缓存的生产配置不需要改动业务代码。一、它到底解决什么问题读完这一节你能说清楚网关层和“自己在代码里写重试”的分工边界。原生 SDK 只负责把请求发给单一 provider。上游抖一下错误就原样抛到你的业务层。Portkey Gateway 在中间做转发行为由一份 JSON 配置驱动哪些状态码重试、重试几次、失败后落到哪个 target、重复请求是否走缓存全部声明在这份配置里。能力原生 SDK 的做法通过 Portkey Gateway 的做法失败重试应用层自写循环加 sleep配置里声明retry.attempts网关代为重试多模型容灾每个 provider 各写一套 try/catch一个targets数组声明 fallback 链响应缓存自建 Redis 层自己做 keycache.mode声明 simple 或 semantic超时兜底各 HTTP client 分散设置request_timeout统一毫秒级控制观测自己打日志再拼看板Logs 页统一看耗时、成本、重试次数心智模型就一句话行为从代码搬进配置代码只发请求。二、最小可用实现配置从 0 到 1读完这一节你能创建一份重试配置并用两种接法各发出一带重试的请求。主线是三段写配置、建配置、发请求。第一步写一份最小重试配置。网关不会猜你的意图必须显式声明。下面的配置表示命中 429、500、503 时最多再试 2 次{ retry: { attempts: 2, on_status_codes: [429, 500, 503] } }保存后命中这三个状态码的请求会被网关自动重发而不是把错误抛给你。第二步在控制台创建配置。进入 Configs 页点 Create起个名字把上面的 JSON 粘进编辑器并保存会得到一个形如pc-xxxxx的配置 ID后面靠它引用这张图重点看两处左侧的 JSON 编辑区和保存后列表里露出的配置 ID。第三步发起一次请求。有两种接法按你现状选。接法 A项目 SDK 直连。适合新接入或愿意换 SDK 的场景初始化时传配置 ID此后所有请求自动带上重试import { Portkey } from portkey-ai; const portkey new Portkey({ apiKey: pk-xxxx, virtualKey: vk-xxxx, config: pc-xxxxx // 配置 ID }); const response await portkey.chat.completions.create({ model: gpt-4o, messages: [{ role: user, content: 你好 }] });效果这行config让该客户端发出的每个请求都继承重试行为。接法 B兼容现有 OpenAI SDK。只改 baseURL 和默认头业务代码一行不动import OpenAI from openai; import { PORTKEY_GATEWAY_URL, createHeaders } from portkey-ai; const openai new OpenAI({ apiKey: sk-xxxx, baseURL: PORTKEY_GATEWAY_URL, // 指向网关而非 OpenAI defaultHeaders: createHeaders({ provider: openai, apiKey: pk-xxxx, config: pc-xxxxx // 配置 ID }) }); // …其余调用代码不变效果请求经网关转发配置通过x-portkey-config请求头注入SDK 侧无感知。自托管部署时整站行为也可以写在根目录的 conf.example.json 里它演示了插件开关、provider 凭据和限流条目的结构。三、配置项逐个讲字段、默认值与适用场景读完这一节你能对着字段表决定每个开关开不开并知道哪几个字段最容易写错。核心字段一览字段与默认值来自网关的配置校验逻辑见 config.ts字段默认值作用什么时候该开retry.attempts0不重试最大重试次数上限 5上游偶发 429/5xxretry.on_status_codes[429, 500, 502, 503, 504]触发重试的状态码列表只想对特定错误码重试时retry.use_retry_after_header关429 时按供应商的 retry-after 头冷却再试被限流且想尊重供应商建议cache.modeDISABLEDsimple 精确匹配semantic 语义匹配重复提问多、想省 tokencache.max_age可选未设缓存存活时长需要控制数据新鲜度strategy.modesinglesingle / loadbalance / fallback / conditional多 provider 分流或容灾targets[].weight可选loadbalance 下各 target 的流量占比按额度分摊流量request_timeout可选单请求超时毫秒超时网关返回 408防长尾请求拖垮线程池三个容易踩坑的字段各给一句最小示例。attempts上限是 5源码常量MAX_RETRIES写更大不会按比例放大别按“越大越稳”来加retry: { attempts: 5 } // 上限 5 次use_retry_after_header打开后网关会读取retry-after-ms、x-ms-retry-after-ms、retry-after三个响应头决定等待时长retry: { attempts: 2, use_retry_after_header: true }最后一条是硬约束配置必须至少含providerapi_key、strategytargets、cache、retry、request_timeout之一否则整份配置被拒。写空对象“先占位”的做法会直接报错。四、两个进阶场景请求级覆盖与多级 fallback读完这一节你能处理两类真实需求临时加大力度以及单供应商挂掉不崩线。场景一请求级临时覆盖默认配置。业务动机某批离线批处理请求允许更长等待但不想动全局配置。把 config 作为第二个参数单独传即可const response await portkey.chat.completions.create( { model: gpt-4o, messages }, { config: { retry: { attempts: 5 } } } // 仅本次请求生效 );效果这次请求按 5 次重试执行其他请求仍走客户端级的全局配置。场景二多级 fallback 叠加流量分摊。业务动机OpenAI 被限流时不能让整个服务瘫痪。外层 loadbalance 把流量摊给 Anthropic 和 OpenAI 组内层 fallback 让 OpenAI 失败后落到 Azure{ strategy: { mode: loadbalance }, targets: [ { virtual_key: anthropic-key, weight: 0.5 }, { strategy: { mode: fallback }, weight: 0.5, on_status_codes: [429, 503], targets: [ { virtual_key: openai-key }, { virtual_key: azure-key } ] } ] }效果流量五五开OpenAI 命中 429/503 时自动切到 Azure用户侧无感。这张图看路由走向同一层按 weight 分流失败沿内层 targets 顺序下探。五、怎么验证它真的生效了读完这一节你能用日志、响应头和 traceID 三件套确认配置不是摆设。看日志。控制台 Logs 页列出每条请求的 provider、模型、token、成本和重试情况这张图重点看每行的状态标记被缓存命中或触发重试的请求会有对应图标。看响应头。网关会在响应里回写几个关键字段定义见 src/globals.ts 的RESPONSE_HEADER_KEYS响应头用途x-portkey-retry-attempt-count实际重试次数重试耗尽时为 -1x-portkey-cache-status缓存状态未命中为 MISSx-portkey-trace-id与日志互查的请求标识发一条标记请求便于事后在日志里精准过滤await portkey.chat.completions.create( { model: gpt-4o, messages }, { traceID: verify-retry-1 } // 日志页按它过滤 );效果你在 Logs 页输入这个 traceID就能看到这条请求的完整执行轨迹。三个常见坑按这个顺序排查⚠️ 完全没重试。先确认attempts大于 0网关把缺失的 attempts 归一成 0等于没配见 requestContext.ts 的normalizeRetryConfig再确认错误码在on_status_codes列表里。429 后直接放弃。开了use_retry_after_header时供应商给的冷却时间超过 60 秒总预算MAX_RETRY_LIMIT_MS网关会跳过本次重试日志里表现为重试次数断档。配置整体不生效。确认x-portkey-config请求头真的到达了网关自托管时直接看服务端访问日志最快。顺序固定先看头、再看状态码、最后看 attempts。重试的完整实现在 retryHandler.ts排到第四类问题时可以进去读。六、延伸导航仓库内关键文件按需取用每个都只说一句话。入门系列从第一次调用讲到缓存与重试cookbook/getting-started/自托管示例配置含插件开关与限流条目conf.example.json网关各接口的请求处理入口src/handlers/部署方式Docker 与 K8sdocs/installation-deployments.md重试、fallback 和缓存的本质是把故障处理从代码挪进配置。下一步建议挑你业务里最易抖的一条 LLM 调用接到这份配置上用 traceID 标记一条请求到 Logs 里确认重试次数和预期一致。【免费下载链接】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 调用加自动重试与多模型 fallback：Portkey Gateway 配置解析
如何给 LLM 调用加自动重试与多模型 fallbackPortkey 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凌晨的监控里突然刷出一排 429 和 503聊天接口的错误率开始爬坡。这篇文章带你把 Portkey Gateway 的网关配置从零跑通一遍写一份重试配置、接到现有 SDK、再验证它真的生效。做完后你能独立维护一份带重试、fallback 和缓存的生产配置不需要改动业务代码。一、它到底解决什么问题读完这一节你能说清楚网关层和“自己在代码里写重试”的分工边界。原生 SDK 只负责把请求发给单一 provider。上游抖一下错误就原样抛到你的业务层。Portkey Gateway 在中间做转发行为由一份 JSON 配置驱动哪些状态码重试、重试几次、失败后落到哪个 target、重复请求是否走缓存全部声明在这份配置里。能力原生 SDK 的做法通过 Portkey Gateway 的做法失败重试应用层自写循环加 sleep配置里声明retry.attempts网关代为重试多模型容灾每个 provider 各写一套 try/catch一个targets数组声明 fallback 链响应缓存自建 Redis 层自己做 keycache.mode声明 simple 或 semantic超时兜底各 HTTP client 分散设置request_timeout统一毫秒级控制观测自己打日志再拼看板Logs 页统一看耗时、成本、重试次数心智模型就一句话行为从代码搬进配置代码只发请求。二、最小可用实现配置从 0 到 1读完这一节你能创建一份重试配置并用两种接法各发出一带重试的请求。主线是三段写配置、建配置、发请求。第一步写一份最小重试配置。网关不会猜你的意图必须显式声明。下面的配置表示命中 429、500、503 时最多再试 2 次{ retry: { attempts: 2, on_status_codes: [429, 500, 503] } }保存后命中这三个状态码的请求会被网关自动重发而不是把错误抛给你。第二步在控制台创建配置。进入 Configs 页点 Create起个名字把上面的 JSON 粘进编辑器并保存会得到一个形如pc-xxxxx的配置 ID后面靠它引用这张图重点看两处左侧的 JSON 编辑区和保存后列表里露出的配置 ID。第三步发起一次请求。有两种接法按你现状选。接法 A项目 SDK 直连。适合新接入或愿意换 SDK 的场景初始化时传配置 ID此后所有请求自动带上重试import { Portkey } from portkey-ai; const portkey new Portkey({ apiKey: pk-xxxx, virtualKey: vk-xxxx, config: pc-xxxxx // 配置 ID }); const response await portkey.chat.completions.create({ model: gpt-4o, messages: [{ role: user, content: 你好 }] });效果这行config让该客户端发出的每个请求都继承重试行为。接法 B兼容现有 OpenAI SDK。只改 baseURL 和默认头业务代码一行不动import OpenAI from openai; import { PORTKEY_GATEWAY_URL, createHeaders } from portkey-ai; const openai new OpenAI({ apiKey: sk-xxxx, baseURL: PORTKEY_GATEWAY_URL, // 指向网关而非 OpenAI defaultHeaders: createHeaders({ provider: openai, apiKey: pk-xxxx, config: pc-xxxxx // 配置 ID }) }); // …其余调用代码不变效果请求经网关转发配置通过x-portkey-config请求头注入SDK 侧无感知。自托管部署时整站行为也可以写在根目录的 conf.example.json 里它演示了插件开关、provider 凭据和限流条目的结构。三、配置项逐个讲字段、默认值与适用场景读完这一节你能对着字段表决定每个开关开不开并知道哪几个字段最容易写错。核心字段一览字段与默认值来自网关的配置校验逻辑见 config.ts字段默认值作用什么时候该开retry.attempts0不重试最大重试次数上限 5上游偶发 429/5xxretry.on_status_codes[429, 500, 502, 503, 504]触发重试的状态码列表只想对特定错误码重试时retry.use_retry_after_header关429 时按供应商的 retry-after 头冷却再试被限流且想尊重供应商建议cache.modeDISABLEDsimple 精确匹配semantic 语义匹配重复提问多、想省 tokencache.max_age可选未设缓存存活时长需要控制数据新鲜度strategy.modesinglesingle / loadbalance / fallback / conditional多 provider 分流或容灾targets[].weight可选loadbalance 下各 target 的流量占比按额度分摊流量request_timeout可选单请求超时毫秒超时网关返回 408防长尾请求拖垮线程池三个容易踩坑的字段各给一句最小示例。attempts上限是 5源码常量MAX_RETRIES写更大不会按比例放大别按“越大越稳”来加retry: { attempts: 5 } // 上限 5 次use_retry_after_header打开后网关会读取retry-after-ms、x-ms-retry-after-ms、retry-after三个响应头决定等待时长retry: { attempts: 2, use_retry_after_header: true }最后一条是硬约束配置必须至少含providerapi_key、strategytargets、cache、retry、request_timeout之一否则整份配置被拒。写空对象“先占位”的做法会直接报错。四、两个进阶场景请求级覆盖与多级 fallback读完这一节你能处理两类真实需求临时加大力度以及单供应商挂掉不崩线。场景一请求级临时覆盖默认配置。业务动机某批离线批处理请求允许更长等待但不想动全局配置。把 config 作为第二个参数单独传即可const response await portkey.chat.completions.create( { model: gpt-4o, messages }, { config: { retry: { attempts: 5 } } } // 仅本次请求生效 );效果这次请求按 5 次重试执行其他请求仍走客户端级的全局配置。场景二多级 fallback 叠加流量分摊。业务动机OpenAI 被限流时不能让整个服务瘫痪。外层 loadbalance 把流量摊给 Anthropic 和 OpenAI 组内层 fallback 让 OpenAI 失败后落到 Azure{ strategy: { mode: loadbalance }, targets: [ { virtual_key: anthropic-key, weight: 0.5 }, { strategy: { mode: fallback }, weight: 0.5, on_status_codes: [429, 503], targets: [ { virtual_key: openai-key }, { virtual_key: azure-key } ] } ] }效果流量五五开OpenAI 命中 429/503 时自动切到 Azure用户侧无感。这张图看路由走向同一层按 weight 分流失败沿内层 targets 顺序下探。五、怎么验证它真的生效了读完这一节你能用日志、响应头和 traceID 三件套确认配置不是摆设。看日志。控制台 Logs 页列出每条请求的 provider、模型、token、成本和重试情况这张图重点看每行的状态标记被缓存命中或触发重试的请求会有对应图标。看响应头。网关会在响应里回写几个关键字段定义见 src/globals.ts 的RESPONSE_HEADER_KEYS响应头用途x-portkey-retry-attempt-count实际重试次数重试耗尽时为 -1x-portkey-cache-status缓存状态未命中为 MISSx-portkey-trace-id与日志互查的请求标识发一条标记请求便于事后在日志里精准过滤await portkey.chat.completions.create( { model: gpt-4o, messages }, { traceID: verify-retry-1 } // 日志页按它过滤 );效果你在 Logs 页输入这个 traceID就能看到这条请求的完整执行轨迹。三个常见坑按这个顺序排查⚠️ 完全没重试。先确认attempts大于 0网关把缺失的 attempts 归一成 0等于没配见 requestContext.ts 的normalizeRetryConfig再确认错误码在on_status_codes列表里。429 后直接放弃。开了use_retry_after_header时供应商给的冷却时间超过 60 秒总预算MAX_RETRY_LIMIT_MS网关会跳过本次重试日志里表现为重试次数断档。配置整体不生效。确认x-portkey-config请求头真的到达了网关自托管时直接看服务端访问日志最快。顺序固定先看头、再看状态码、最后看 attempts。重试的完整实现在 retryHandler.ts排到第四类问题时可以进去读。六、延伸导航仓库内关键文件按需取用每个都只说一句话。入门系列从第一次调用讲到缓存与重试cookbook/getting-started/自托管示例配置含插件开关与限流条目conf.example.json网关各接口的请求处理入口src/handlers/部署方式Docker 与 K8sdocs/installation-deployments.md重试、fallback 和缓存的本质是把故障处理从代码挪进配置。下一步建议挑你业务里最易抖的一条 LLM 调用接到这份配置上用 traceID 标记一条请求到 Logs 里确认重试次数和预期一致。【免费下载链接】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），仅供参考