Cloudflare Workers AI 免费额度：每日 1 万 Neurons，免绑卡边缘推理

Workers AI 提供两种调用形态：一种是平台原生的推理端点，返回结果放在 result.response 字段里；另一种是 OpenAI 兼容端点，请求和响应结构与 OpenAI 一致，可以直接把现有代码改一下 base_url 就能用。

base_url 与鉴权

两种 base_url 形态如下，把占位符替换成你自己的账户 ID：

• 原生推理端点：https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/
• OpenAI 兼容端点：https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1

鉴权统一使用请求头 Authorization: Bearer <API Token>，令牌就是申请流程里创建的那个；原生端点的模型名直接拼在 URL 路径末尾，兼容端点则把模型名放进请求体。

常用模型名与获取途径

模型名统一以 @cf/ 开头，常用的如 @cf/meta/llama-3.1-8b-instruct、@cf/mistral/mistral-7b-instruct-v0.1、@cf/qwen/qwen1.5-14b-chat-awq。完整模型清单在 Workers AI 控制台的模型目录和官方文档里查看，目录中会标注各模型的上下文长度与是否计入免费额度。

一次对话补全调用

先把账户 ID 和令牌放进环境变量，避免写死在代码里：

export CF_ACCOUNT_ID="你的账户ID"
export CF_API_TOKEN="你的API令牌"

然后用 curl 调用原生端点，下面是一次完整的多轮对话补全请求：

curl "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/ai/run/@cf/meta/llama-3.1-8b-instruct" \
  -H "Authorization: Bearer $CF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手"},
      {"role": "user", "content": "用一句话解释什么是边缘推理"}
    ],
    "max_tokens": 256,
    "temperature": 0.7,
    "stream": false
  }'

关键参数说明：messages 是对话数组，支持 system、user、assistant 三种角色，总长度受模型上下文窗口限制，本平台的模型多为 2K–8K，超出会直接报错；max_tokens 控制本次生成的 token 上限，输出越长消耗的 Neurons 越多；temperature 取值 0 到 1，越大越发散，做客服问答或结构化抽取建议调到 0.2 左右；stream 设为 true 时返回流式响应，适合在 Worker 里做打字机效果。

如果已经在用 OpenAI SDK，只需替换 base_url 和模型名，其余代码不用动：

from openai import OpenAI

client = OpenAI(
    api_key="你的API令牌",
    base_url="https://api.cloudflare.com/client/v4/accounts/你的账户ID/ai/v1",
)

resp = client.chat.completions.create(
    model="@cf/meta/llama-3.1-8b-instruct",
    messages=[{"role": "user", "content": "用一句话解释什么是边缘推理"}],
    max_tokens=256,
    temperature=0.7,
)
print(resp.choices[0].message.content)

额度耗尽与限流的典型表现与排查顺序

典型表现是接口返回 HTTP 429，或者响应体里 success 为 false、errors 数组给出额度用尽或请求过于频繁的描述；兼容端点则直接抛出 429 异常。按下面的顺序排查最省时间：

1. 先读响应体 errors 里的原始描述，分清是鉴权失败、模型名不存在，还是当天额度用尽。
2. 检查 Authorization 头是否完整、令牌是否被撤销或权限过窄，以及 URL 里的账户 ID 是否与令牌所属账号一致。
3. 确认模型名带 @cf/ 前缀、拼写无误，并核对它是否在免费额度覆盖的范围内。
4. 打开控制台的用量面板查看当天 Neurons 消耗；确实用尽就等 UTC 0 点重置，或临时切换到参数量更小的模型。
5. 若只有个别请求失败，缩短 messages 内容并调低 max_tokens，排除上下文超限的可能。