Cloudflare Workers AI

Cloudflare Workers AI 为 Cloudflare 网络上托管的模型提供无服务器推理。AISIX 为这些模型提供面向应用的 OpenAI 兼容 API，并由网关管理 Cloudflare Token、调用方访问权限、限流和用量核算。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 配置。配置网关以加载声明式资源文件。
• Cloudflare 账户 ID 和 Workers AI API Token。在 Cloudflare 控制台中打开 Workers AI 页面并选择 Use REST API，按 REST API 入门所述创建 Token 并复制账户 ID。
• 已安装 curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Workers AI 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

Cloudflare Workers AI 是社区目录服务提供方。AISIX 接受 cloudflare-workers-ai 作为服务提供方值，并选择使用 Bearer 身份认证的 openai 适配器。AISIX 不会提供精选基础 URL 或服务提供方特定的请求和响应重写，因此必须配置账户范围的 api_base。

控制台将该服务提供方标记为传输格式未经验证的社区条目。

创建服务提供方密钥

创建用于存储 Cloudflare 凭证和账户范围 API 根路径的服务提供方密钥：

# 请替换为实际值
export CLOUDFLARE_API_TOKEN="YOUR_PROVIDER_API_KEY"
export CLOUDFLARE_ACCOUNT_ID="YOUR_CLOUDFLARE_ACCOUNT_ID"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cloudflare-workers-ai-prod",
    "provider": "cloudflare-workers-ai",
    "api_key": "'"${CLOUDFLARE_API_TOKEN}"'",
    "api_base": "https://api.cloudflare.com/client/v4/accounts/'"${CLOUDFLARE_ACCOUNT_ID}"'/ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为目录 ID cloudflare-workers-ai。AISIX Cloud Admin API 从目录服务提供方派生适配器；adapter 字段仅接受 BYO 服务提供方密钥，因此不要在此设置。

❷ api_key 存储 Workers AI API Token。Cloudflare 使用 Authorization: Bearer 请求头认证 REST API，这正是 openai 适配器已经发送的形式。该值遵循服务提供方密钥中的凭证处理行为。

❸ api_base 是账户范围的根路径 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/v1。Cloudflare 在 OpenAI 兼容 API 端点中记录的完整端点为 https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/chat/completions。AISIX 会向 api_base 追加 /chat/completions 等端点路径，因此该值必须止于 /ai/v1。如果误粘贴完整端点 URL，AISIX 会移除可识别的后缀和末尾斜杠，但应存储较短的根路径形式。

警告

请始终在 Cloudflare Workers AI 服务提供方密钥上设置 api_base。

对于社区目录服务提供方，省略 api_base 时，AISIX 会回退到公共模型目录发布的基础 URL。Cloudflare Workers AI 的发布值为 https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1。由于每个 Cloudflare 账户都有自己的端点，该值是模板而不是已解析的 URL。AISIX 不会替换占位符，且会原样存储回退值而不重新验证，因此创建请求仍会成功。随后，存储的根路径会保留字面量 ${CLOUDFLARE_ACCOUNT_ID}，而不是账户 ID，第一次请求将在上游失败。该服务提供方不存在可用的共享默认值。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

Workers AI 模型 ID 始终以 @cf/ 开头，后跟发布方和模型名称：@cf/<publisher>/<model>。请把完整字符串写入 model_name，包括 @cf/ 前缀以及 -fp8-fast 等任何精度或变体后缀。删除前缀或复用其他主机为相同权重发布的裸 ID，会导致上游模型错误。

Cloudflare 模型目录当前包含以下 ID：

Cloudflare 模型 ID	说明
@cf/openai/gpt-oss-120b	可选择推理强度的开放权重推理模型。
@cf/meta/llama-3.3-70b-instruct-fp8-fast	量化为 fp8 以加快推理的 Llama 3.3 70B。
@cf/qwen/qwen3-30b-a3b-fp8	用于多语言聊天、推理和工具使用的 Qwen3 指令模型。

创建别名前，请在 Workers AI 模型目录中查看当前列表。确认所选模型是文本生成模型，而不是 Embedding、图像或语音模型。

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cloudflare-gptoss-prod",
    "model_name": "@cf/openai/gpt-oss-120b",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是完整的 Workers AI 模型 ID，例如 @cf/openai/gpt-oss-120b。

❸ provider_key_id 将别名关联到 Cloudflare Workers AI 服务提供方密钥。

有关为预算核算和用量报告关联成本元数据的信息，请参阅模型别名。

创建调用方 API Key

创建能够访问该模型别名的调用方 API Key。明文密钥由服务器生成，并只在创建响应中返回一次，因此请立即保存：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cloudflare-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export CLOUDFLARE_API_TOKEN="YOUR_PROVIDER_API_KEY"
export CLOUDFLARE_ACCOUNT_ID="YOUR_CLOUDFLARE_ACCOUNT_ID"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

为该服务提供方创建完整的声明式资源文件：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "cloudflare-workers-ai-prod"
    provider: "cloudflare-workers-ai"
    adapter: "openai"
    api_key: ${CLOUDFLARE_API_TOKEN}
    api_base: "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1"

models:
  - display_name: "cloudflare-gptoss-prod"
    provider: "cloudflare-workers-ai"
    model_name: "@cf/openai/gpt-oss-120b"
    provider_key: "cloudflare-workers-ai-prod"

api_keys:
  - display_name: "cloudflare-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "cloudflare-gptoss-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cloudflare-gptoss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Cloudflare Workers AI."
      }
    ]
  }'

网关返回 OpenAI 兼容响应，其中回显面向调用方的别名 cloudflare-gptoss-prod。

如果请求失败，请按顺序排查以下三个原因：

1. 上游身份认证失败表示 api_key 值有误，或 Token 缺少 Workers AI 权限。
2. 上游路由或账户错误表示 api_base 有误。确认账户 ID 路径段是真实账户 ID，且该值止于 /ai/v1。
3. 上游模型错误表示 model_name 有误。确认 ID 仍带有 @cf/ 前缀。

补充社区目录未提供的配置

具有 AISIX 精选目录条目的服务提供方会随适配器一同提供请求和响应调整。如果上游对面向调用方的参数使用不同名称，网关会在参数离开前对其重命名。Cloudflare Workers AI 没有精选条目，因此未为它注册任何参数重命名或推理字段映射。AISIX 会使用调用方提供的字段名，把 Chat Completions 正文发送到 /ai/v1 根路径，并按标准 OpenAI Chat Completions JSON 读取响应。

只要 Cloudflare 界面与 OpenAI 形态一致，该默认行为就是正确的。如果存在差异，请在服务提供方密钥上显式配置，而不是改造每个客户端：

{
  "request": {
    "param_renames": {
      "max_completion_tokens": "max_tokens"
    }
  },
  "response": {
    "reasoning_field": "delta.reasoning"
  }
}

• request.param_renames 会在请求发出时重命名顶层参数。当 Workers AI 模型拒绝客户端已经发送的名称时使用该配置。如果请求同时携带两个名称，AISIX 会使用原始面向调用方名称中的值。
• response.reasoning_field 把非标准流式 delta 路径中的推理映射到规范 delta.reasoning_content 字段。当模型在 reasoning_content 之外的位置传输推理时使用该配置。

覆盖项会应用于引用该服务提供方密钥的每个模型，因此请先用非生产别名验证。完整字段目录请参阅服务提供方特定覆盖项。

AISIX 不会剥离其未原生建模的顶层参数。Cloudflare 支持但 AISIX 没有类型化字段的参数仍会原样到达上游。因此，只有参数名称不同时才需要重命名，而不是仅仅因为网关不熟悉该参数。

控制推理强度

@cf/openai/gpt-oss-120b 模型提供推理强度控制，接受 low、medium 和 high。无法识别的顶层参数会透传，因此请在 Chat Completions 正文顶层发送该参数：

{
  "model": "cloudflare-gptoss-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "reasoning_effort": "low"
}

Workers AI 的推理支持因模型而异，有些模型完全不提供推理控制。发送参数前，请在具体模型的模型页面确认，因为不接受该参数的模型可能会拒绝请求。

端点覆盖范围

Cloudflare Workers AI 通过其 OpenAI 兼容根路径提供文本生成和文本 Embedding，因此只有部分 AISIX 代理界面适用于 Workers AI 支持的别名。

路由	Cloudflare Workers AI 别名的行为
/v1/chat/completions	支持，包括 stream: true。
/v1/embeddings	支持。Cloudflare 在同一 /ai/v1 根路径下实现 OpenAI 兼容 Embedding，因此请在同一个服务提供方密钥上创建第二个别名，并将其 model_name 设为 @cf/baai/bge-m3 等 Embedding 模型。请参阅 Embedding。
/v1/responses	支持。非 OpenAI 服务提供方会通过聊天适配器路径桥接，而不是原样透传。
/v1/messages	通过转换支持 Anthropic 形态的调用方。/v1/messages/count_tokens 的 Token 计数要求使用 Anthropic 支持的模型。
/v1/images/generations	拒绝。该路由只接受服务提供方为 openai 的模型。
/v1/rerank	拒绝。该路由只接受 openai、cohere 和 jina 服务提供方值。
/v1/videos	返回未实现错误。该路由仅向固定服务提供方集合分发，其中不包含 cloudflare-workers-ai。
/passthrough/cloudflare-workers-ai/*	支持，并以 api_base 为根路径。隧道只能到达 /ai/v1 下的路径，因此 Cloudflare 原生 /ai/run/@cf/... 端点位于根路径之外，无法通过该服务提供方密钥访问。请参阅服务提供方透传。

后续步骤

你已将 AISIX 接入 Cloudflare Workers AI，并验证了模型别名。接下来可以阅读：

• 模型别名：为该别名配置路由、重试行为或成本元数据。
• 路由和故障转移：在 Cloudflare Workers AI 与另一个服务提供方之间进行故障转移。
• 服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。