Portkey AI Gateway 入门实战教程3个配置项让自动重试与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上周四一个线上 LLM 调用连续返回 429 达 11 分钟手写的重试逻辑没有触发整条链路被卡住。那天你如果正在为这类问题头疼可以看看 Portkey AI Gateway——一个通过 1 个 API 路由到 1600 LLM 的开源 AI 网关内置 Retry、Fallback、Load Balancing 与 Guardrails。读完本文你能独立写出一份带 429 重试和多模型 Fallback 的网关配置并在日志里验证整个行为。Portkey AI Gateway 是什么能做什么Portkey AI Gateway 是部署在你应用与各家 LLM 提供商之间的开源中间层把重试、Fallback、负载均衡、缓存这些稳定性逻辑从业务代码里剥离出来变成一份声明式 JSON 配置。它完全兼容 OpenAI SDK 的签名接口几乎可以无缝替换提供商的 API Key 存放在它的密钥库中请求里只传递一个 Virtual Key 标识符不落地明文密钥。除路由能力外它还集成了 50 内容安全插件Guardrails在请求发出前和响应返回后做校验。核心能力一句话说明仓库中对应位置自动重试Retry命中指定状态码后自动重发cookbook/getting-started/automatic-retries-on-failures.mdFallback主提供商失败时按序切换备用模型cookbook/getting-started/fallback-from-openai-to-azure.ipynbLoad Balancing按权重把流量拆到多个提供商cookbook/getting-started/resilient-loadbalancing-with-failure-mitigating-fallbacks.md缓存Cache相同或语义相近的请求直接命中缓存cookbook/getting-started/enable-cache.mdGuardrails 插件注入、PII、毒性检测等 50 插件plugins/⚡ 快速上手跑通一份 429 重试配置这一节以请求被限流时自动重试 3 次为单条主线动线是编写配置 → 发布并拿到配置 ID → 在代码中挂载全程只需要改一行初始化代码。编写最简重试配置Gateway Config 就是一个 JSON 对象最简重试配置如下{ retry: { attempts: 3, // 失败后最多重试 3 次 on_status_codes: [429] // 仅在命中 429 限流时触发 } }它的含义只有一句请求遇到 429 时自动重发最多 3 次。仓库里的配置样例 conf.example.json 展示了完整字段包括缓存开关、集成凭证和限流规则写复杂配置前可以对照它。发布网关配置拿到配置 ID推荐在 Portkey 控制台的 Configs 页面操作点 Create命名例如request_retries把上面的 JSON 粘进编辑器点 Save Config。编辑器会做语法校验保存后会生成一个形如pc-xxxxx-edx21x的配置 ID后续所有引用都靠这个 ID。在代码中挂载配置 ID推荐用 Portkey SDK把配置 ID 作为config参数传入初始化一行搞定import { Portkey } from portkey-ai; const portkey new Portkey({ apiKey: PORTKEY_API_KEY, // Portkey 平台密钥 virtualKey: VKEY, // 提供商密钥的库内标识 config: pc-xxxxx-edx21x // 刚才发布的配置 ID }); // 此后所有请求自动具备 429 重试能力业务代码零改动 const response await portkey.chat.completions.create({ messages: [{ role: user, content: 列出七大奇迹 }], model: gpt-4 });可选如果项目已经用 OpenAI SDK把baseURL换成PORTKEY_GATEWAY_URL、headers 加config即可业务调用不用动。SDK、OpenAI SDK 和裸 HTTP 请求三种挂载方式的完整写法以及只给单次请求挂配置的变体都在入门手册 cookbook/getting-started/writing-your-first-gateway-config.md 中这份文档是官方对 Gateway Config 的逐段讲解。 按场景选型先选行再展开先看下表按你的现状对号入座再往下找对应场景的完整配置不必从头读到尾。场景对应配置要点适用情况单提供商频繁 429retryon_status_codes已在上文跑通流量拆分到多提供商strategy.mode: loadbalancetargets[].weight单家配额不够或想压低成本主提供商宕机要兜底嵌套targets 各自的on_status_codes要求调用不直接报错大量用户问相似问题cache: { mode: simple \| semantic }重复请求费钱、增延迟场景一Load Balancing 加嵌套 Fallback把 50% 流量给 Claude另外 50% 先打 OpenAIOpenAI 失败自动切到 Azure OpenAIconst config { strategy: { mode: loadbalance }, // 顶层两个 target 均分流量 targets: [ { virtual_key: process.env[ANTHROPIC_VIRTUAL_KEY], weight: 0.5 }, // 50% 走 Claude { strategy: { mode: fallback }, // 另外 50% 内部再按序兜底 targets: [ { virtual_key: process.env[OPENAI_VIRTUAL_KEY] }, { virtual_key: process.env[AZURE_OPENAI_VIRTUAL_KEY] } // OpenAI 失败后切 Azure ], weight: 0.5 } ] };把config直接作为参数传给new Portkey({ apiKey, config })所有请求立刻获得上面这套行为不需要改任何业务代码。对应的流量走向是逐 target 的override_params用法和完整的请求示例见 cookbook/getting-started/resilient-loadbalancing-with-failure-mitigating-fallbacks.md这份教程从 SDK 安装讲到日志追踪。场景二一行配置开启缓存多个用户对同一个问题重复提问时每次都会真实计费并等待模型返回。开启缓存只需一个字段// simpleprompt 完全相同才命中semantic按相似度命中 cache: { mode: simple }命中后响应来自缓存日志详情里会显示Cache Status: HIT可以逐条核对simple 与 semantic 两种模式的差别、验证步骤和成本影响在 cookbook/getting-started/enable-cache.md 中有完整对照实验适合第一次开缓存前通读一遍。常见坑新手最常踩的 3 个坑每条按现象 → 原因 → 解决说清楚基本都能在 1 分钟内修掉。坑 1配置写了却没生效。现象是请求照样直接失败日志里只有一次记录。原因是非 SDK 的裸请求中配置要放在请求头x-portkey-config里而不是放进请求体字段。解决SDK 用户确认传的是config参数裸请求用户确认 header 拼写并用 curl 打印一遍最终请求核对。坑 2分不清请求是不是走了 Fallback。现象是接口返回正常但你不知道响应到底来自哪个提供商。原因是默认返回体只包含结果不标注路由过程。解决给请求附一个 trace ID然后在日志列表按该 Trace ID 过滤每次重试和切换会各记一行。坑 3Virtual Key 填了原始密钥。现象是请求直接被网关拒绝。原因是 Portkey 把提供商密钥存在密钥库里请求应传库内的 virtual key 标识如open-ai-key-04ba3e原始密钥永远不要发给网关。解决在控制台的 Virtual Keys 页面核对对应标识替换代码中的值。进阶路线主线跑通后沿这三个方向继续深入按你的角色各取所需src/handlers/网关核心处理代码Retry、Fallback、流式响应在这里落地可以查到每个配置项的实际执行逻辑适合想读源码、二次开发的人docs/installation-deployments.mdDocker 与 K8s 自托管部署说明含环境变量配置适合不想用托管服务、要在内网跑网关的人plugins/Guardrails 插件的完整实现每个插件都有 manifest 和独立测试照着它就能写自己的安全插件适合要给生产流量加 PII 或注入检测的人cookbook/按场景组织的 Notebook 集合涵盖图像生成、Agent 监控、模型对比评测适合想抄作业的人下一步很具体clone 仓库git clone https://gitcode.com/GitHub_Trending/ga/gateway按快速上手一节把重试配置发出去然后在日志里亲眼看到一次 429 被自动重试掉。【免费下载链接】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），仅供参考