自定义提供商

概览

自定义提供商允许你集成 AI Gateway 原生不支持的 AI 提供商。此功能使你能够与任何具有 HTTPS API 端点的 AI 提供商一起使用 AI Gateway 的可观测性、缓存、速率限制和其他功能。

用例

内部 AI 模型：连接到你组织自托管的 AI 模型
区域提供商：与你所在区域特定的 AI 提供商集成
专用模型：使用标准提供商不可用的领域特定 AI 服务
自定义端点：将请求路由到你自己的 AI 基础设施

开始之前

前提条件

具有 AI Gateway 访问权限的有效 Cloudflare 账户
来自自定义 AI 提供商的有效 API 密钥
提供商 API 的 HTTPS 基础 URL

身份验证

创建、读取、更新或删除自定义提供商的 API 端点需要身份验证。你需要创建具有适当权限的 Cloudflare API 令牌。

要创建 API 令牌：

前往 Cloudflare 仪表板 API 令牌页面 ↗
点击 Create Token（创建令牌）
选择 Custom Token（自定义令牌） 并添加以下权限：
- AI Gateway - Edit
点击 Continue to summary（继续查看摘要），然后点击 Create Token（创建令牌）
复制令牌 — 你将在 Authorization: Bearer $CLOUDFLARE_API_TOKEN 标头中使用它

创建自定义提供商

要使用 API 创建新的自定义提供商：

获取你的 Account ID 和 Account Tag。
发送 POST 请求创建新的自定义提供商：

Create Custom Providerbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true
  }'

必填字段：

name (string)：提供商的显示名称
slug (string)：唯一标识符（字母数字加连字符）。在你的账户内必须唯一。
base_url (string)：提供商 API 端点的 HTTPS URL。必须以 https:// 开头。

可选字段：

description (string)：提供商描述
link (string)：提供商文档 URL
enable (boolean)：提供商是否激活（默认：false）
beta (boolean)：标记为 Beta 功能（默认：false）
curl_example (string)：使用提供商的 cURL 命令示例
js_example (string)：使用提供商的 JavaScript 代码示例

响应：

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": null,
    "curl_example": null,
    "js_example": null,
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

要使用仪表板创建新的自定义提供商：

登录 Cloudflare 仪表板 ↗ 并选择你的账户。
前往 Compute & AI > AI Gateway > Custom Providers ↗。
选择 Add Custom Provider（添加自定义提供商）。
输入以下信息：
- Provider Name（提供商名称）：提供商的显示名称
- Provider Slug（提供商标识）：唯一标识符（字母数字加连字符）
- 基础 URL：提供商 API 端点的 HTTPS URL（例如 https://api.myprovider.com/v1）
选择 Save（保存） 创建自定义提供商。

列出自定义提供商

检索所有自定义提供商，支持可选过滤和分页：

List all providersbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

查询参数：

page (number)：页码（默认：1）
per_page (number)：每页项目数（默认：20，最大：100）
enable (boolean)：按启用状态过滤
beta (boolean)：按 Beta 状态过滤
search (string)：在 id、name 或 slug 字段中搜索
order_by (string)：排序字段和方向（默认："name ASC"）

示例：

仅列出已启用的提供商：

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?enable=true" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

搜索特定提供商：

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?search=custom" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

响应：

{
  "success": true,
  "result": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Custom Provider",
      "slug": "some-provider",
      "base_url": "https://api.myprovider.com",
      "enable": true,
      "created_at": 1700000000,
      "modified_at": 1700000000
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "total_count": 1,
    "total_pages": 1
  }
}

要查看所有自定义提供商：

登录 Cloudflare 仪表板 ↗ 并选择你的账户。
前往 Compute & AI > AI Gateway > Custom Providers ↗。
你将看到所有自定义提供商的列表，包括名称、slug、基础 URL 和状态。

获取特定自定义提供商

通过 ID 检索特定自定义提供商的详情：

Get provider by IDbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

响应：

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": "https://docs.myprovider.com",
    "curl_example": "curl -X POST https://api.myprovider.com/v1/chat ...",
    "js_example": "fetch('https://api.myprovider.com/v1/chat', {...})",
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

更新自定义提供商

更新现有自定义提供商。所有字段都是可选的 — 仅包含要更改的字段：

Update providerbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Provider Name",
    "enable": true,
    "description": "Updated description"
  }'

可更新字段：

name (string)：提供商显示名称
slug (string)：提供商标识符
base_url (string)：API 端点 URL（必须是 HTTPS）
description (string)：提供商描述
link (string)：文档 URL
enable (boolean)：激活状态
beta (boolean)：Beta 标志
curl_example (string)：cURL 命令示例
js_example (string)：JavaScript 代码示例

示例：

启用提供商：

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enable": true}'

更新提供商 URL：

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://api.newprovider.com"}'

要更新现有自定义提供商：

登录 Cloudflare 仪表板 ↗ 并选择你的账户。
前往 Compute & AI > AI Gateway > Custom Providers ↗。
找到要更新的自定义提供商并选择 Edit（编辑）。
更新要更改的字段（name、slug、base URL 等）。
选择 Save（保存） 应用更改。

删除自定义提供商

删除自定义提供商：

Delete providerbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

响应：

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Custom Provider",
    "slug": "some-provider"
  }
}

要删除自定义提供商：

登录 Cloudflare 仪表板 ↗ 并选择你的账户。
前往 Compute & AI > AI Gateway > Custom Providers ↗。
找到要删除的自定义提供商并选择 Delete（删除）。
出现提示时确认删除。

在 AI Gateway 中使用自定义提供商

创建自定义提供商后，你可以使用两种方法之一通过 AI Gateway 路由请求：Unified API 或提供商专用端点。使用任一方法引用自定义提供商时，必须在 slug 前加上 custom- 前缀。

URL 路由工作原理

当 AI Gateway 收到自定义提供商的请求时，它通过将提供商配置的 base_url 与 gateway URL 中 custom-{slug}/ 之后的路径组合来构建上游 URL。

base_url 字段应仅包含提供商 API 的根域名（或带固定前缀的域名）。任何 API 特定路径段（如 /v1/chat/completions）应放在请求 URL 中，而不是 base_url 中。

公式为：

Gateway URL:   https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-{slug}/{provider-path}
Upstream URL:  {base_url}/{provider-path}

请求 URL 中 custom-{slug}/ 之后的所有内容直接附加到 base_url 以形成最终上游 URL。这意味着 {provider-path} 可以包含多个路径段、查询参数或提供商所需的任何路径结构。

在 Unified API 和提供商专用端点之间选择

	Unified API (`/compat`)	提供商专用端点
最适合	兼容 OpenAI API 的提供商	具有任何 API 结构的提供商
请求格式	必须遵循 OpenAI `/chat/completions` 架构	使用提供商的原生请求格式
路径控制	固定为 `/compat/chat/completions`	完全控制上游路径
如何指定提供商	`model` 字段：`custom-{slug}/{model-name}`	URL 路径：`/custom-{slug}/{path}`

当自定义提供商接受兼容 OpenAI 的 /chat/completions 请求格式时，使用 Unified API。这是最简单的选项，与 OpenAI SDK 配合良好。

当自定义提供商使用非标准 API 路径或请求格式时，使用提供商专用端点。这让你完全控制发送到上游提供商的 URL 路径和请求正文。

通过 Unified API

Unified API 使用兼容 OpenAI 的格式将请求发送到提供商的 chat completions 端点。使用格式 custom-{slug}/{model-name} 指定模型。

Request using custom provider via Unified APIbash

# Run `wrangler auth token` to get an auth token to replace $CF_AIG_TOKEN for use with the API.
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "cf-aig-authorization: Bearer $CF_AIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-some-provider/model-name",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

通过提供商专用端点

提供商专用端点让你完全控制上游路径。URL 中 custom-{slug}/ 之后的所有内容附加到 base_url。

Direct provider endpointbash

# Run `wrangler auth token` to get an auth token to replace $CF_AIG_TOKEN for use with the API.
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-some-provider/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "cf-aig-authorization: Bearer $CF_AIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-name",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

如果 base_url 是 https://api.myprovider.com，此请求被代理到：https://api.myprovider.com/v1/chat/completions

示例

以下示例展示如何为不同类型的提供商配置 base_url 和构建请求 URL。

示例 1：兼容 OpenAI 的提供商（标准 `/v1/` 路径）

许多提供商遵循 OpenAI 约定，在 {domain}/v1/chat/completions 托管 API。

配置：

slug: my-openai-compat
base_url: https://api.example-provider.com

提供商专用端点：

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-my-openai-compat/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "example-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

URL 映射：

组件	值
Gateway URL	`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-my-openai-compat/v1/chat/completions`
`base_url`	`https://api.example-provider.com`
提供商路径	`/v1/chat/completions`
Upstream URL	`https://api.example-provider.com/v1/chat/completions`

由于此提供商兼容 OpenAI，你也可以使用 Unified API：

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-my-openai-compat/example-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

示例 2：具有非标准 API 路径的提供商

某些提供商使用不遵循 /v1/ 约定的 API 路径。例如，chat 端点位于 https://api.custom-ai.com/api/coding/paas/v4/chat/completions 的提供商。

配置：

slug: custom-ai
base_url: https://api.custom-ai.com

提供商专用端点：

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-custom-ai/api/coding/paas/v4/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-ai-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

URL 映射：

组件	值
Gateway URL	`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-custom-ai/api/coding/paas/v4/chat/completions`
`base_url`	`https://api.custom-ai.com`
提供商路径	`/api/coding/paas/v4/chat/completions`
Upstream URL	`https://api.custom-ai.com/api/coding/paas/v4/chat/completions`

示例 3：带路径前缀的自托管模型

如果你在反向代理后面或添加路径前缀的平台上托管自己的模型，如果所有端点共享固定前缀，则仅在 base_url 中包含固定前缀部分。否则，将 base_url 保持为仅域名。

配置（仅域名的 base_url）：

slug: internal-llm
base_url: https://ml.internal.example.com

提供商专用端点：

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-internal-llm/serving/models/my-model:predict \
  -H "Authorization: Bearer $INTERNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "Summarize the following text:"}]
  }'

URL 映射：

组件	值
Gateway URL	`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-internal-llm/serving/models/my-model:predict`
`base_url`	`https://ml.internal.example.com`
提供商路径	`/serving/models/my-model:predict`
Upstream URL	`https://ml.internal.example.com/serving/models/my-model:predict`

示例 4：使用 OpenAI SDK 和自定义基础 URL 的提供商

使用 OpenAI SDK 通过 AI Gateway 连接到自定义提供商时，将 SDK 的 base_url 设置为 gateway 的提供商专用端点路径（直到并包括提供商期望的 API 版本前缀）。

配置：

slug: alt-provider
base_url: https://api.alt-provider.com

Python (OpenAI SDK)：

Using OpenAI SDK with a custom providerpython

from openai import OpenAI

client = OpenAI(
    api_key="your-provider-api-key",
    base_url="https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1",
    default_headers={
        "cf-aig-authorization": "Bearer {cf_aig_token}",
    },
)

# SDK 自动将 /chat/completions 附加到 base_url。
# 最终上游 URL：https://api.alt-provider.com/v1/chat/completions
response = client.chat.completions.create(
    model="alt-model-v2",
    messages=[{"role": "user", "content": "Hello!"}],
)

URL 映射：

组件	值
SDK `base_url`	`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1`
SDK 附加	`/chat/completions`
完整 gateway URL	`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1/chat/completions`
提供商 `base_url`	`https://api.alt-provider.com`
提供商路径	`/v1/chat/completions`
Upstream URL	`https://api.alt-provider.com/v1/chat/completions`

常见错误

409 Conflict - 重复 slug

{
	"success": false,
	"errors": [
		{
			"code": 1003,
			"message": "A custom provider with this slug already exists",
			"path": ["body", "slug"]
		}
	]
}

每个自定义提供商 slug 在你的账户内必须唯一。选择不同的 slug 或更新现有提供商。

404 Not Found

{
	"success": false,
	"errors": [
		{
			"code": 1004,
			"message": "Custom Provider not found"
		}
	]
}

指定的提供商 ID 不存在或你没有访问权限。验证提供商 ID 和身份验证凭据。

400 Bad Request - 无效的 base_url

{
	"success": false,
	"errors": [
		{
			"code": 1002,
			"message": "base_url must be a valid HTTPS URL starting with https://",
			"path": ["body", "base_url"]
		}
	]
}

base_url 字段必须是有效的 HTTPS URL。出于安全原因，不支持 HTTP URL。

向自定义提供商发送请求时出现 404

如果收到来自上游提供商的 404，最常见的原因是路径映射不正确。验证以下内容：

你的 base_url 设置为提供商的根域名（例如 https://api.provider.com），而不是包含 API 路径段。
你的请求 URL 在 custom-{slug}/ 之后包含完整 API 路径。例如，如果上游端点是 https://api.provider.com/api/v2/chat，你的 gateway URL 应以 /custom-{slug}/api/v2/chat 结尾。
没有重复或缺失的路径段。常见错误是在 base_url 和请求路径中都包含 /v1，导致上游收到 /v1/v1/chat/completions。

最佳实践

使用描述性 slug：选择清楚标识提供商的 slug（例如 internal-gpt、regional-ai）
记录集成：使用 curl_example 和 js_example 字段提供使用示例
逐步启用：在激活提供商之前使用 enable: false 测试
监控使用情况：使用 AI Gateway 的分析跟踪对自定义提供商的请求
保护端点：确保自定义提供商的基础 URL 实现适当的身份验证和授权
使用 BYOK：使用 BYOK 安全存储提供商 API 密钥，而不是在每个请求中包含它们

限制

自定义提供商按账户特定，不在 Cloudflare 账户之间共享
base_url 必须使用 HTTPS（不支持 HTTP）
提供商 slug 在每个账户内必须唯一
缓存和速率限制设置全局应用于提供商，而非按模型

自定义提供商

概览

用例

开始之前

前提条件

身份验证

创建自定义提供商

列出自定义提供商

获取特定自定义提供商

更新自定义提供商

删除自定义提供商

在 AI Gateway 中使用自定义提供商

URL 路由工作原理

在 Unified API 和提供商专用端点之间选择

通过 Unified API

通过提供商专用端点

示例

示例 1：兼容 OpenAI 的提供商（标准 /v1/ 路径）

示例 2：具有非标准 API 路径的提供商

示例 3：带路径前缀的自托管模型

示例 4：使用 OpenAI SDK 和自定义基础 URL 的提供商

常见错误

409 Conflict - 重复 slug

404 Not Found

400 Bad Request - 无效的 base_url

向自定义提供商发送请求时出现 404

最佳实践

限制

相关资源

示例 1：兼容 OpenAI 的提供商（标准 `/v1/` 路径）