Portkey AI Gateway 稳定性实战：3 行 JSON 搞定 LLM 自动重试与多模型 Fallback

Portkey AI Gateway 稳定性实战：3 行 JSON 搞定 LLM 自动重试与多模型 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

凌晨两点，上游一次 503 让客服机器人的整条对话链路静默降级，用户端只剩转圈，直到早班同事手动恢复——这一夜的代价是 40 多条差评工单。问题不在你的代码，而在 LLM API 天生不稳定。把 Portkey AI Gateway 这类 AI Gateway 挂在应用与模型之间，重试、切换、缓存就都变成了几行配置，而不是散落在业务代码里的 try-catch。

能力速览：一张表看懂 AI Gateway 替你挡什么

3 行 JSON 开启 LLM 自动重试

最小可用配置长这样：

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

怎么确认它生效：发一个请求，到 Dashboard 的 Logs 页看这条记录的尝试次数，或检查响应头x-portkey-retry-attempt-count。想主动验证，挑一个容易限流的 key 把并发拉高，看到 429 被自动补成 200，就是它在工作。

生产级 AI Gateway 配置：逐层加料

生产配置不是一次写出来的，而是按"重试 → fallback 链 → 缓存"逐层叠加。

第一层：重试。上一节的最小配置只盯 429。不写on_status_codes时，网关默认对[429, 500, 502, 503, 504]生效，上限 5 次。显式写出它，是为了让"什么时候该重试"这件事可审计。

第二层：Fallback 链。重试打满还在挂，就该换目标了。在顶层加 strategy，并在 targets 里嵌套备选：

{ "strategy": { "mode": "fallback" }, "targets": [ { "provider": "openai", "model": "gpt-4o" }, { "provider": "anthropic", "model": "claude-3-5-sonnet-latest" } ] }

主目标失败后，请求原样落到第二个 target，对调用方透明。

第三层：缓存。前面两层解决"失败"，这层解决"浪费"——高频重复问题不再重复计费：

{ "cache": { "mode": "semantic" } }

三段增量合并进同一个 JSON，就是一份可直接上线的网关配置。LLM 负载均衡同理：把strategy.mode换成loadbalance，给 target 加weight即可，效果示意：

接入方式二选一

Portkey SDK，初始化时把配置交给网关，之后所有调用自动继承：

import { Portkey } from 'portkey-ai'; const portkey = new Portkey({ apiKey: '<YOUR_PORTKEY_API_KEY>', config: 'pc-xxxxx-edx21x', });

OpenAI SDK 兼容，不改业务代码，只换 baseURL 和 header：

import OpenAI from 'openai'; const openai = new OpenAI({ apiKey: '<YOUR_OPENAI_API_KEY>', baseURL: 'https://g.portkey.ai/v1', defaultHeaders: { 'x-portkey-api-key': '<YOUR_PORTKEY_API_KEY>', 'x-portkey-config': 'pc-xxxxx-edx21x', }, });

二选一即可。两种接法背后是同一份配置，迁移成本基本为零。

踩坑三连：最常被配错的三处

配置 ID 和 API Key 不是一个东西

配置 ID 是网关里那份 JSON 的引用凭证，API Key 是网关账号的鉴权密钥。两者要分开存放，别把配置 ID 当密钥填进 vault。

on_status_codes 该写成什么

它是状态码数组。省略时用默认集合[429, 500, 502, 503, 504]，写了就是精确指定。429 场景下网关还会读取上游的retry-after决定等待时长，不必自己手写 sleep。

请求级配置什么时候覆盖全局

单次请求传入的 config 会覆盖实例级配置；targets 嵌套时，子层配置优先于父层。想"默认重试 3 次、个别接口 5 次"，就在请求参数里单独传。

配置太多之后，建议直接在控制台维护并在代码里引用 ID，而不是把 JSON 硬编码在仓库里。长这样：

下一步

• 入门样例目录：cookbook/getting-started/，从最简单的重试教程读起
• 负载均衡 + fallback 完整示例：cookbook/getting-started/resilient-loadbalancing-with-failure-mitigating-fallbacks.md

先把最小重试配置接到你的测试环境跑通，再逐层叠加 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