Portkey AI Gateway入门指南：编写第一个网关配置

最新推荐文章于 2025-06-05 09:09:47 发布

原创最新推荐文章于 2025-06-05 09:09:47 发布 · 324 阅读

8 ·

CC 4.0 BY-SA版权

Portkey AI Gateway入门指南：编写第一个网关配置

gateway 项目地址: https://gitcode.com/gh_mirrors/ga/gateway

前言

在现代AI应用开发中，与大型语言模型(LLM)的交互已成为常态。然而，直接调用API时开发者常会遇到各种挑战：请求失败、速率限制、缓存管理等。Portkey AI Gateway正是为解决这些问题而设计的智能网关解决方案。

什么是Portkey AI Gateway

Portkey AI Gateway是一个中间层服务，位于您的应用程序和LLM提供商(如OpenAI)之间，提供了一系列增强功能：

自动重试失败的请求
智能缓存机制
负载均衡
请求超时处理
多目标回退策略

基础API调用

让我们从最基本的GPT-4 API调用开始。Portkey的客户端SDK设计上与OpenAI SDK保持兼容，使得迁移变得简单。

import { Portkey } from 'portkey-ai';

// 初始化Portkey客户端
const portkey = new Portkey({
  apiKey: '您的Portkey API密钥',
  virtualKey: '您的虚拟密钥'
});

const messages = [
  {
    role: 'user',
    content: `世界七大奇迹是什么？`
  }
];

// 发起聊天补全请求
const response = await portkey.chat.completions.create({
  messages,
  model: 'gpt-4'
});

console.log(response.choices[0].message.content);

这里有几个关键概念需要理解：

Portkey API密钥：用于验证您的Portkey账户
虚拟密钥(Virtual Key)：Portkey的安全机制，用于代理实际的LLM提供商API密钥

网关配置的核心概念

Portkey的强大之处在于其灵活的网关配置系统。这些配置以JSON格式定义，可以控制请求的各种行为。

自动重试配置示例

{
  "retry": {
    "attempts": 3,          // 重试次数
    "on_status_codes": [429] // 触发重试的状态码
  }
}

这个简单配置可以让您的应用在遇到429(请求过多)状态码时自动重试3次。

配置的两种应用方式

1. 通过UI创建并引用配置ID

Portkey提供了直观的配置构建器界面：

在配置构建器中创建新配置
为配置命名(如"request_retries")
编写配置JSON并保存
获取生成的配置ID

应用配置只需在初始化时传入配置ID：

const portkey = new Portkey({
  apiKey: '您的密钥',
  virtualKey: '虚拟密钥',
  config: 'pc-xxxxx-edx21x' // 这里使用配置ID
});

优势：

配置与代码分离
无需重新部署即可更新配置
版本历史追踪

2. 直接在代码中定义配置

对于需要动态生成配置的场景，可以直接在代码中构建配置对象：

const portkey = new Portkey({
  apiKey: '您的密钥',
  virtualKey: '虚拟密钥',
  config: JSON.stringify({
    retry: {
      attempts: 3,
      on_status_codes: [429]
    }
  })
});

多场景集成示例

使用Axios直接调用

const response = await axios({
  method: 'post',
  url: 'Portkey的API端点',
  headers: {
    'Content-Type': 'application/json',
    'x-portkey-api-key': 'PORTKEY_API_KEY',
    'x-portkey-provider': 'openai',
    'x-portkey-config': CONFIG_ID // 或直接JSON字符串
  },
  data: {
    model: 'gpt-4',
    messages: [...]
  }
});

与OpenAI SDK集成

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'OPENAI_API_KEY', // 当使用virtualKey时此项被忽略
  baseURL: PORTKEY_GATEWAY_URL,
  defaultHeaders: {
    'x-portkey-api-key': PORTKEY_API_KEY,
    'x-portkey-provider': 'openai',
    'x-portkey-config': JSON.stringify({
      retry: { attempts: 3, on_status_codes: [429] }
    })
  }
});

高级用法：请求级配置

除了全局配置，还可以为单个请求指定特定配置：

const response = await portkey.chat.completions.create(
  {
    messages,
    model: 'gpt-4'
  },
  {
    config: {
      retry: {
        attempts: 5, // 这个请求需要更多重试次数
        on_status_codes: [429, 500]
      }
    }
  }
);

进阶配置示例

Portkey支持复杂的多目标配置策略，例如：

主目标 (OpenAI GPT4):
  基础缓存
  当429错误时:
    目标2 (负载均衡):
      Anthropic Claude3
      语义缓存
      当5XX错误时
    目标3 (负载均衡):
      Anyscale Mixtral 7B
      当4XX/5XX错误时:
        目标4 (回退):
          Llama模型
          自动重试
          请求超时设置

这种配置结构让您能够构建高度弹性的AI应用架构。