Portkey AI Gateway 入门实战教程：3个配置项让自动重试与Fallback跑起来

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），在请求发出前和响应返回后做校验。

⚡ 快速上手：跑通一份 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 的逐段讲解。

🎯 按场景选型：先选行，再展开

先看下表按你的现状对号入座，再往下找对应场景的完整配置，不必从头读到尾。

场景一：Load Balancing 加嵌套 Fallback

把 50% 流量给 Claude，另外 50% 先打 OpenAI，OpenAI 失败自动切到 Azure OpenAI：

const 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 安装讲到日志追踪。

场景二：一行配置开启缓存

多个用户对同一个问题重复提问时，每次都会真实计费并等待模型返回。开启缓存只需一个字段：

// simple：prompt 完全相同才命中；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 过滤，每次重试和切换会各记一行。

坑 3：Virtual Key 填了原始密钥。现象是请求直接被网关拒绝。原因是 Portkey 把提供商密钥存在密钥库里，请求应传库内的 virtual key 标识（如open-ai-key-04ba3e），原始密钥永远不要发给网关。解决：在控制台的 Virtual Keys 页面核对对应标识，替换代码中的值。

进阶路线

主线跑通后，沿这三个方向继续深入，按你的角色各取所需：

• src/handlers/：网关核心处理代码，Retry、Fallback、流式响应在这里落地，可以查到每个配置项的实际执行逻辑（适合想读源码、二次开发的人）
• docs/installation-deployments.md：Docker 与 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