头部信息

在向 Portkey API 发起请求时，您需要包含特定的头部以验证您的请求、指定提供者并配置各种功能。本指南解释了您可以使用的基本和可选头部，以便在 Portkey 上构建应用程序。

必要的标题

1. API 密钥 (x-portkey-api-key)

x-portkey-api-key 头是用于验证您的请求并确保安全访问 Portkey API 的必要条件。您可以从 Portkey 仪表板 获取您的 API 密钥。

示例：

"x-portkey-api-key: $PORTKEY_API_KEY" \

2. 提供者信息

除了 API 密钥，您还必须提供有关您使用的 AI 提供者的信息。可以通过四种方式做到这一点：

2.1. 提供者 (x-portkey-provider) + 认证头

• x-portkey-provider：指定您正在使用的提供者（例如，“openai”，“anthropic”）。请参阅 Portkey 集成提供者 的列表。

• Authorization（或其他适当的认证头，如 x-api-key 或 api-key）：包括指定提供者所需的认证详细信息。

示例：

"x-portkey-provider: openai"
"Authorization: Bearer $OPENAI_API_KEY"

2.2. 虚拟密钥 (x-portkey-virtual-key)

• x-portkey-virtual-key：允许您使用预配置的虚拟密钥，该密钥封装了提供者和认证详细信息。

• 虚拟密钥可以通过 Portkey 仪表板创建和管理。 （文档）

示例：

"x-portkey-virtual-key: your_virtual_key_here"

2.3. 配置 (x-portkey-config)

• x-portkey-config：接受一个 JSON 对象或包含提供者详细信息和其他配置设置的配置 ID。使用配置对象提供灵活性，并允许动态配置您的请求。

• 配置可以保存在 Portkey UI 中，并通过其 ID 引用。 （文档）

• 配置还支持其他可选功能，如缓存、负载均衡、回退、重试和超时。

使用 JSON 对象的示例：

"x-portkey-config: {"provider": "openai", "api_key": "OPENAI_API_KEY"}"

使用配置 ID 的示例：

"x-portkey-config: pp-config-xx"

2.4. 自定义主机 (x-portkey-custom-host) + 提供者 (x-portkey-provider) + 认证头

• 当连接到自定义托管的提供者端点时，请使用此组合。

• x-portkey-custom-host 指定自定义端点的 URL。 （文档）

• x-portkey-provider 指示提供者类型。

• Authorization（或适当的认证头）包括自定义端点的认证详细信息。

---

可选头部

还有其他可选的 Portkey 头部，可以启用各种功能和增强：

1. Trace ID (x-portkey-trace-id)

• x-portkey-trace-id：您可以传递的 ID，用于后续引用一个或多个请求。如果未提供，Portkey 会自动为每个请求生成一个追踪 ID。 (Docs)

示例：

"x-portkey-trace-id: your_custom_trace_id"

2. Metadata (x-portkey-metadata)

• x-portkey-metadata：允许您将自定义元数据附加到请求中，稍后可以在分析和日志仪表板中进行过滤。您可以包含特殊的元数据类型 _user，以将请求与特定用户关联。 (Docs)

示例：

"x-portkey-metadata: {"_user": "user_id_123", "foo": "bar"}"

3. Cache Force Refresh (x-portkey-cache-force-refresh)

• x-portkey-cache-force-refresh：通过发出新的 API 调用并存储更新的值，强制请求的缓存刷新。期望值为 true 或 false。有关更多信息，请参见缓存文档。 (Docs)

示例：

"x-portkey-cache-force-refresh: true"

4. Cache Namespace (x-portkey-cache-namespace)

• x-portkey-cache-namespace：根据自定义字符串对缓存存储进行分区，忽略元数据和其他头部。

示例：

"x-portkey-cache-namespace: any_string"

5. Request Timeout (x-portkey-request-timeout)

• x-portkey-request-timeout：设置请求自动终止的超时时间。时间以毫秒为单位。

示例：

"x-portkey-request-timeout: 3000"

6. Forward Headers (x-portkey-forward-headers)

• x-portkey-forward-headers：允许您直接将敏感头部转发到模型的 API，而不经过 Portkey 的任何处理。期望为 array of strings。 (Docs)

示例：

"x-portkey-forward-headers: ["X-Custom-Header", "Another-Header"]"

7. Cloud-Specific Headers (Azure, Google, AWS)

• 传递更多配置头部给 Azure OpenAI、Google Vertex AI 或 AWS Bedrock

Azure

• x-portkey-azure-resource-name，x-portkey-azure-deployment-id，x-portkey-azure-api-version，Authorization，x-portkey-azure-model-name

Google Vertex AI

• x-portkey-vertex-project-id，x-portkey-vertex-region

AWS Bedrock

• x-portkey-aws-session-token，x-portkey-aws-secret-access-key，x-portkey-aws-region，x-portkey-aws-session-token

所有标题列表

有关所有可用参数及其详细描述的全面列表，请参阅 Portkey SDK Client 文档。

SDK

在 SDK 中使用 Headers

您可以通过 REST API 调用以及使用 OpenAI 或 Portkey SDK 发送这些 headers。使用 Portkey SDK 时，除了 cacheForceRefresh、traceID 和 metadata，其余的 headers 在实例化 Portkey 客户端时传递。

Portkey Node SDK

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
//  authorization: "Bearer PROVIDER_API_KEY",
//  provider: "anthropic",
//  customHost: "CUSTOM_URL",
//  forwardHeaders: ["authorization"],
    virtualKey: "VIRTUAL_KEY",
    config: "CONFIG_ID",   
})

const chatCompletion = await portkey.chat.completions.create({
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-4o',
},{
    traceId: "your_trace_id", 
    metadata: {"_user": "432erf6"}
});

console.log(chatCompletion.choices);

Portkey Python SDK