portkey-ai/gateway · 上手攻略

• 仓库：portkey-ai/gateway
• 链接：https://github.com/Portkey-AI/gateway
• 分类：ai
• 作者：Tom
• 更新：2026-07-10

这是什么

Portkey AI Gateway 是一个开源的 AI 网关（LLM Router），用单一 API 接口聚合 1600+ 语言、视觉、音频和图像模型。它既是路由层（自动重试、负载均衡、降级），也是安全层（Guardrails 内容审查），同时自带可观测性（监控、日志、成本追踪）。本质上，它是你所有 AI 应用访问大模型的统一入口。

核心定位：不再需要在代码里硬编码各种 provider SDK，一个端点搞定所有 LLM 调用。

解决什么问题

多 LLM provider 时代给开发者带来了新的复杂度：

• ** provider 切换成本**：从 OpenAI 切到 Anthropic 要改代码，从 GPT-4 切到 Gemini 要换 SDK
• 稳定性风险：单 provider 调用遇到限流或宕机，应用直接挂掉
• 成本不可控：没有统一视角，容易超出预算
• 合规需求：企业需要内容审查、访问控制、SOC2/HIPAA 合规

Portkey Gateway 在应用层和 provider API 层之间加了一层，所有请求都经过这个 gateway，对应用代码透明。

快速安装

最快方式（Node.js / npm）

npx @portkey-ai/gateway
# Gateway 运行在 http://localhost:8787/v1
# 控制台：http://localhost:8787/public/

pip（Python SDK）

pip install -qU portkey-ai

Docker

docker run -e PORTKEY_API_KEY=your_key \
  -p 8787:8787 \
  portkeyai/gateway:latest

Cloudflare Workers / Replit / Kubernetes

详见仓库 docs/installation-deployments.md

核心用法

Python SDK（最常用）

from portkey_ai import Portkey

# OpenAI 兼容接口，不需要改现有代码
client = Portkey(
    provider="openai",        # 或 'anthropic', 'bedrock', 'groq' 等
    authorization="sk-***"    # 实际 provider 的 API key
)

# 完全兼容 OpenAI SDK
client.chat.completions.create(
    messages=[{"role": "user", "content": "What's the weather like?"}],
    model="gpt-4o-mini"
)

配置重试与降级

config = {
    "retry": {"attempts": 5},
}

client = client.with_options(config=config)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story"}]
)
# 请求失败自动重试最多 5 次（指数退避）

Guardrails（内容审查）

config = {
    "output_guardrails": [{
        "default.contains": {
            "operator": "none",
            "words": ["Apple"]   # 禁止回复包含 Apple
        },
        "deny": True
    }]
}

client = client.with_options(config=config)

client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply randomly with Apple or Bat"}]
)
# 永远返回 "Bat"，因为含 "Apple" 的回复被拦截

负载均衡

# 同时使用多个 API key，自动分配流量
# 支持权重配置、故障自动切换

REST API（任何语言）

curl -X POST http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

支持的 Provider（部分）

MCP Gateway（企业功能）

如果你在使用 MCP（Model Context Protocol）服务，Portkey MCP Gateway 提供： - 统一认证：在 gateway 侧做一次认证，MCP server 收到已验证请求 - 访问控制：细粒度控制哪个团队/用户可以访问哪些工具 - 全链路可观测：每个 tool call 记录完整上下文（谁、什么参数、响应、延迟） - 身份转发：自动将用户身份（邮箱、团队、角色）传给 MCP server

支持 Claude Desktop、Cursor、VS Code 等主流 MCP 客户端。

典型适用场景

• 多 provider 切换：产品需要同时支持 GPT-4o、Gemini 和 Claude，通过 gateway 统一管理
• 高可用 AI 应用：关键业务场景不允许 LLM 调用失败，gateway 的自动重试+降级确保稳定性
• 企业合规：需要内容审查（PII 检测、毒害内容过滤）但不想在业务代码里写规则
• 成本控制：需要追踪各 provider 实际消耗，识别浪费
• MCP 管理：用 MCP 构建 Agent 时需要统一的认证和可观测性层

坑与注意

1. Gateway 2.0 即将发布：当前开源版为 1.x，2.0 预发布版在 2.0.0 分支，企业核心功能正在合并进开源版本，生产环境使用前请 check 最新发布分支状态。

2. x-portkey-provider header：使用 REST API 时必须指定 provider，否则 gateway 不知道往哪个后端路由。

3. API Key 管理：测试时可以用 authorization 传明文 key，生产环境建议使用 Portkey 平台生成的虚拟 key，避免在代码中硬编码真实 provider key。

4. Guardrails 仅后置过滤：当前 guardrail 在 model 输出后才检查，不会阻止模型生成有害内容，只是拦截后返回错误或重试。如果需要前置拦截，需要自行在应用层实现。

5. 部分高级功能需要企业版：Prompt 模板管理、成本优化（provider 自动切换）在托管版/企业版中提供，开源版不含这些特性。

6. 托管 vs 自托管：Portkey 同时提供云托管版本（portkey.ai）和纯开源自托管版本，两者功能集有差异，企业采购前需确认功能清单。

与同类对比

LiteLLM 是最直接的竞品，两者都做 LLM 统一路由，Portkey 的差异化在于：内置 Guardrails 数量多、企业 MCP Gateway 支持、以及 Portkey 平台提供观测和 key 管理能力。如果你只需要简单路由+重试，LiteLLM 更轻量；如果需要安全合规+可观测性，Portkey 更完整。

一句话推荐结论

在多 provider LLM 时代，Portkey AI Gateway 是目前开源方案中 Guardrails 最成熟、MCP 支持最完善、企业可观测性做得最完整的选择，适合需要统一路由+安全合规的生产 AI 应用。

来源：GitHub README (https://github.com/Portkey-AI/gateway)、portkey.ai 官方文档