Portkey AI网关配置：把大模型请求统一接入代理层

知识分享

2026-10-31 07:40

16 阅读

如果你已经有多家模型供应商的 API Key，并且希望用一个统一入口收口请求、集中查看调用日志，Portkey 网关的基本配置并不复杂：在控制台创建 Gateway、接入 Provider 密钥、生成 Virtual Key，最后把应用里的 base_url 换成网关地址即可。
下面按零基础也能照做的顺序拆解。

先确认使用场景和前置条件

Portkey 的 AI 网关本质是一个反向代理层，你的应用把请求发到 Portkey，Portkey 再按配置转发给 OpenAI、Anthropic 或自建模型服务。
它适合需要密钥集中管理、多模型切换或请求日志观测的场景；
如果只是单机跑一个脚本、只用一个供应商，直接调用官方 API 通常更省事。

动手前准备好三样东西：

一个 Portkey 账号，并确认当前工作区有创建 Gateway 的权限；
至少一个供应商的真实 API Key，例如 OpenAI 的 sk- 开头密钥；
你的应用当前使用的 SDK 和 base_url，后面要替换成网关地址。

创建网关并接入供应商密钥

在网关详情页添加 Provider：选择供应商类型，填入对应的 API Key 和模型前缀。
以 OpenAI 为例，Provider 配置大致对应如下字段：

Provider: OpenAI
API Key: sk-你的真实密钥
Slug: openai

这里的 Slug 是后续请求里用来区分供应商的标识，建议保持简短且全小写。
保存后，控制台通常会提供一次连接检查或示例请求，用来确认密钥可用。
如果页面没有自动检查，不要跳过，后面用 curl 验证。

生成虚拟密钥并替换应用入口

Portkey 推荐应用侧使用 Virtual Key（虚拟密钥），而不是直接把供应商的真实 Key 写进代码。
在网关的 Keys 或 Virtual Keys 页面新建一个虚拟密钥，绑定刚才配置的 Provider，并设置可访问的模型范围。
生成后你会拿到一个形如 pk- 开头的密钥，它只对当前网关有效。

下面修改应用配置。
以 OpenAI 兼容的 Python SDK 为例，把 base_url 指向 Portkey 网关地址，api_key 换成虚拟密钥：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.portkey.ai/v1",
    api_key="pk-你的虚拟密钥",
    default_headers={"x-portkey-provider": "openai"}
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "ping"}]
)
print(resp.choices[0].message.content)

如果你用的不是 OpenAI SDK，思路一致：把请求域名换成 Portkey 网关地址，鉴权头换成虚拟密钥，并通过请求头或网关配置指定 Provider。
具体头字段名称以控制台示例为准，不要凭记忆硬写。

用一次真实请求做验证

配置完成后不要只看控制台状态，发一次真实请求最可靠。
可以在服务器上直接用 curl 验证：

curl https://api.portkey.ai/v1/chat/completions \
  -H "Authorization: Bearer pk-你的虚拟密钥" \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

预期结果是返回一段正常的模型回复，同时控制台的请求日志里能看到这次调用记录。
如果日志里没有记录，说明请求根本没到网关，优先检查 base_url 和网络出口。

常见报错和避坑点

返回 401：先确认 Authorization 头里用的是虚拟密钥而不是供应商真实密钥，再检查虚拟密钥是否绑定了正确的 Provider。
两者不匹配时，网关会拒绝转发。

返回 404 或 model not found：
多半是 Provider 的 Slug 和请求头里的 x-portkey-provider 不一致，
或者虚拟密钥的模型范围没有包含你请求的模型名。

请求超时：如果服务器在国内，先确认到 api.portkey.ai 的网络连通性，再检查是否被本地防火墙或安全组拦截。
不要把供应商密钥直接暴露在前端，虚拟密钥也只应放在服务端环境变量里。

还有一个容易被忽略的点：修改 base_url 后，SDK 里原有的重试、超时参数仍然生效，但网关层也可能有自己的超时设置。
两边都设得过短时，长输出请求容易被截断，建议先保持默认值跑通，再按实际耗时调整。

配置完成后的检查清单

应用代码里不再出现供应商真实 Key，只保留 Portkey 虚拟密钥；
控制台请求日志能对应上应用的每一次调用；
至少验证一次流式输出和一次普通输出，确认返回格式没有被网关改变；
记录网关地址和虚拟密钥的存放位置，方便后续轮换。

Portkey AI 网关配置的核心就是“网关实例 + Provider 密钥 + 虚拟密钥 + 替换 base_url”这四步。
先跑通最小请求，再逐步加路由和日志策略，比一上来堆复杂配置更容易定位问题。

Helicone评测使用教程：为LLM请求加上可观测与打分

LiteLLM配置教程：统一代理OpenAI与本地模型请求