Cloudflare Workers AI 怎么用?三种调用方式、免费额度与报错排查
简答:只想先跑通一个 AI 接口,先在 Dashboard 使用 LLM Chat App 模板;需要把模型写进自己的 Worker,就配置 Workers AI Binding 并调用 env.AI.run();本地脚本或后端服务则使用 REST API。本文按这三种方式给出可执行步骤,同时补上免费额度、成本估算、前端调用、Token 安全和 workers.dev 连接排查。
定义:Cloudflare Workers AI 是一种可通过 Workers、Pages Functions 或 REST API 调用模型的云端推理服务,模型运行不需要用户自行管理 GPU。
先选调用方式:初学者先用 Dashboard,开发集成再用 Binding 或 REST API
如果你只是想确认账户和模型调用能否正常工作,先用 Dashboard 创建 LLM Chat App;如果要把 AI 能力写进自己的 Worker 或 Pages Functions,使用 Workers AI Binding;如果调用方是本地脚本、后端服务或其他语言程序,使用 REST API。三种方式的主要差别不在模型本身,而在代码位置、认证方式和部署维护方式。
| 方式 | 适合谁 | 前置条件 | 认证或配置 | 最容易遇到的问题 |
|---|---|---|---|---|
| Dashboard | 想快速体验聊天应用的人 | Cloudflare 账户 | Workers & Pages 中选择 LLM Chat App | Dashboard 修改与本地代码不会自动同步 |
| Workers Binding | 要开发自己的 Worker 或 Pages Functions | 账户、Node.js、Wrangler | Wrangler 文件配置 ai.binding,代码使用 env.AI | 绑定名、模型 ID 或请求格式不一致 |
| REST API | 本地脚本、后端和独立服务 | Account ID、API Token、HTTP 客户端 | 调用 /accounts/{ACCOUNT_ID}/ai/run/{model} | Token 权限、Account ID、JSON 请求体错误 |
官方快速入门分别提供了 Dashboard、Workers Binding 和 REST API 三条路径;选择前可以先查看Workers AI 官方概览和Dashboard 快速入门。
方式一:Dashboard 五步创建第一个聊天应用
不想先安装命令行工具时,Dashboard 是最短路径。它适合验证账户、模型调用和网页访问链路,但不适合多人协作或复杂项目的长期版本管理。
- 登录 Cloudflare Dashboard,打开 Workers & Pages。
- 选择 Create application。
- 在模板区域选择 LLM Chat App。
- 选择 Deploy。
- 为 Worker 命名,选择 Create and deploy,然后通过系统提供的
workers.dev子域名预览。
如果页面能打开但聊天请求失败,先确认浏览器开发者工具中的请求状态码,再进入 Workers 应用页面查看日志。不要因为页面能显示就认定模型请求已经成功:网页静态界面、Worker 请求和模型推理是三个不同环节。
官方说明,Dashboard 编辑适合简单场景;要开发更复杂的应用或执行测试,应转向 Wrangler CLI。下载脚本并开始本地开发后,本地改动不会自动同步回 Dashboard,应继续使用 CLI 管理和部署。
方式二:Workers Binding 从零创建一个可调用接口
Workers Binding 的关键是把 AI 资源绑定到 Worker。绑定名写成 AI 时,代码中通过 env.AI 调用;如果你把绑定名改成其他名称,接口类型和调用代码也必须同步修改。
先创建项目:
npm create cloudflare@latest -- hello-ai
cd hello-ai创建向导按照官方示例选择 Hello World example、Worker only、TypeScript,并先不要立即部署。然后在 wrangler.jsonc 中加入 AI 配置:
{
"ai": {
"binding": "AI"
}
}再将 src/index.ts 改为:
export interface Env {
AI: Ai;
}
export default {
async fetch(request, env): Promise<Response> {
const response = await env.AI.run(
"@cf/google/gemma-4-26b-a4b-it",
{
messages: [
{
role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "请用中文说明什么是 DNS。"
}
],
chat_template_kwargs: {
enable_thinking: false
}
}
);
return Response.json(response);
}
} satisfies ExportedHandler<Env>;这个模型 ID 和 chat_template_kwargs.enable_thinking 字段来自官方 Workers Binding 快速入门示例;模型目录会变化,生产使用前应重新打开Workers AI 模型目录核对名称、任务类型和可用状态。官方绑定文档也提供了更通用的 env.AI.run() 调用示例。
绑定配置和调用方法可参考Workers AI Binding 文档。官方文档说明,AI Binding 也可以用于 Pages Functions,但 Pages Functions 的配置入口与普通 Worker 不完全相同。
本地测试、部署与前端调用:不要把 Token 放进浏览器
在项目目录运行本地开发命令:
npx wrangler devWrangler 会提供本地访问地址。Workers AI 本地开发仍会访问你的 Cloudflare 账户并产生模型用量,因此不要让前端自动刷新或测试脚本循环调用。确认本地接口返回 JSON 后,再执行:
npx wrangler login
npx wrangler deploy部署后,官方示例会提供类似 https://hello-ai.<YOUR_SUBDOMAIN>.workers.dev 的访问地址。
如果要让网页调用自己的 Worker,可以让浏览器只请求你的 Worker,由 Worker 通过 Binding 调用模型。下面是一个最小的前端调用示例,前端没有保存 API Token:
const response = await fetch("https://你的-worker.你的子域名.workers.dev", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
prompt: "请用中文解释 MTU"
})
});
const data = await response.json();
console.log(data);对应的 Worker 可以读取请求体,再将提示词传给 Binding:
export interface Env {
AI: Ai;
}
export default {
async fetch(request, env): Promise<Response> {
if (request.method !== "POST") {
return new Response("Method Not Allowed", { status: 405 });
}
const body = await request.json() as { prompt?: string };
const prompt = body.prompt?.trim();
if (!prompt) {
return Response.json(
{ error: "prompt is required" },
{ status: 400 }
);
}
const result = await env.AI.run(
"@cf/meta/llama-3.1-8b-instruct",
{ prompt }
);
return Response.json(result);
}
} satisfies ExportedHandler<Env>;这里的前端调用并不需要 REST API Token。若使用 REST API,则 Token 只能保存在后端环境变量、密钥管理系统或 CI/CD Secret 中,不能写进浏览器 JavaScript、公开仓库或移动端安装包。
方式三:REST API 调用模型,Windows PowerShell 5.1 请用请求文件
REST API 需要 Account ID 和 API Token。官方流程是在 Workers AI 页面选择 Use REST API,创建 Workers AI API Token,再复制 Account ID。如果自行创建 Token,官方要求同时拥有 Workers AI - Read 和 Workers AI - Edit 权限。
Windows PowerShell 5.1 调用原生 curl.exe 时,不建议直接把含双引号的 JSON 写在命令行参数中。为避免 PowerShell 5.1 改写请求体,先用文本编辑器创建当前目录的 body.json:
{
"prompt": "请用中文解释什么是 MTU。"
}然后在 PowerShell 中只把凭据保存在当前会话变量,并使用 --data-binary @body.json:
$accountId = "你的_ACCOUNT_ID"
$apiToken = "你的_API_TOKEN"
curl.exe "https://api.cloudflare.com/client/v4/accounts/$accountId/ai/run/@cf/meta/llama-3.1-8b-instruct" `
-H "Authorization: Bearer $apiToken" `
-H "Content-Type: application/json" `
--data-binary "@body.json"Linux、macOS 或 Git Bash 可以使用:
export ACCOUNT_ID="你的_ACCOUNT_ID"
export API_TOKEN="你的_API_TOKEN"
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/run/@cf/meta/llama-3.1-8b-instruct" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
--data '{"prompt":"请用中文解释什么是 MTU。"}'官方 REST API 示例使用 @cf/meta/llama-3.1-8b-instruct,响应示例包含 result、success、errors 和 messages 字段;更换模型时要同时更换 URL 中的模型 ID,并按模型目录要求调整请求体。完整认证流程见Workers AI REST API 快速入门。
测试结束后清理当前会话变量:
Remove-Variable apiToken -ErrorAction SilentlyContinue
Remove-Variable accountId -ErrorAction SilentlyContinue
模型怎么选:按任务类型和请求格式核对,不要只复制模型名
模型目录中的模型可能有不同的任务类型、输入结构和输出结构。选择时先明确任务,再查看模型详情页,而不是只根据参数规模或搜索结果中的名称复制配置。
| 需求 | 目录中优先查看 | 调用前核对 |
|---|---|---|
| 聊天、问答、文本生成 | Text Generation | 使用 prompt 还是 messages、是否支持流式输出 |
| 语义搜索、相似度和检索 | Text Embeddings | 向量维度、输入格式,以及是否需要向量数据库 |
| 图像理解或分类 | Vision、Image Classification | 图片传入方式、返回字段和限制 |
| 语音识别或合成 | Speech-to-Text、Text-to-Speech | 音频格式、语言参数和返回内容类型 |
例如,官方 Binding 示例使用 Gemma 模型和消息数组,而 REST API 示例使用 Llama 模型和 prompt 字段。这说明模型调用格式不能一概而论。模型名称、目录数量和可用状态以官方模型目录当前显示为准。
Neurons 和免费额度:用输入输出规模做一个可复核的估算
Workers AI 用 Neurons 表示不同模型执行请求所需的计算量;价格页面同时列出部分模型的输入 Token 和输出 Token 单价。当前官方价格页面显示,Workers AI 每天提供 10,000 Neurons 的免费额度;Workers Paid 对超出部分按每 1,000 Neurons 0.011 美元计费,额度每天在 UTC 00:00 重置。部分模型需要付费账单方式,可使用 Workers Paid 或预付 AI Gateway credits,具体适用模型应以价格页当前列表为准。
以价格页列出的 @cf/meta/llama-3.1-8b-instruct 为例,假设一次请求使用 1,000 个输入 Token、500 个输出 Token,按页面列出的输入价格 0.282 美元/百万 Token、输出价格 0.827 美元/百万 Token 估算:
输入成本 = 1,000 ÷ 1,000,000 × 0.282 = 0.000282 美元
输出成本 = 500 ÷ 1,000,000 × 0.827 = 0.0004135 美元
合计约 = 0.0006955 美元按同一页面列出的 Neurons 数值,这个示例约使用 25.608 个输入 Neurons 加 37.5735 个输出 Neurons,合计约 63.1815 Neurons。实际请求的 Token 数量、模型、缓存和返回长度不同,结果也会不同,所以这个数字只能作为计算方法示例,不是固定单次请求价格。
排查费用时按这个顺序:
- 在 Workers AI Dashboard 查看当前 Neurons 用量。
- 确认模型是否需要付费账单方式。
- 区分 Workers Free、Workers Paid 和 AI Gateway credits 的计费路径。
- 检查本地
wrangler dev是否被自动刷新、循环测试或重复重试调用。
价格、模型单价和付费模型清单以Workers AI Pricing当前页面为准。
workers.dev 打不开或请求超时:先区分 DNS、网络和应用错误
部署完成后,如果 workers.dev 地址打不开,不要马上修改模型配置。先把问题分成三层:域名是否能解析、TCP/TLS 是否能连接、Worker 是否返回应用响应。
- 先查 DNS:Windows 使用
nslookup 你的-worker.你的子域名.workers.dev;Linux 或 macOS 使用dig 你的-worker.你的子域名.workers.dev。如果没有地址答案、返回超时或查询失败,先检查本机 DNS、路由器 DNS、企业网络策略和当前网络。 - 再看连接过程:Windows 使用
curl.exe -v https://你的-worker.你的子域名.workers.dev;Linux 或 macOS 使用curl -v https://你的-worker.你的子域名.workers.dev。重点看是否完成 DNS、TCP 和 TLS,然后再看 HTTP 状态码。 - 最后查应用:能建立 HTTPS 连接但返回 401、403、404、405 或 5xx,说明请求已经到达某个 HTTP 服务,应转向 Worker 路由、请求方法、Token、绑定、模型和日志排查。
| 现象 | 优先检查 | 下一步 |
|---|---|---|
| nslookup 或 dig 无答案 | 本机 DNS、网络出口、域名拼写 | 换一个网络交叉测试,再核对部署地址 |
| DNS 有答案但 curl -v 卡在连接或 TLS | 网络出口、防火墙、代理、TLS 握手 | 记录 -v 输出中的失败阶段,不要先改模型 |
| 返回 401 或 403 | REST API Token、权限、请求头 | 确认使用 Bearer Token,检查 Read 与 Edit 权限 |
| 返回 404 或 405 | Worker 路由和 HTTP 方法 | 确认访问路径,检查代码是否只允许 POST |
| 返回模型或额度错误 | 模型 ID、Neurons 用量、付费条件 | 查看模型目录和 Pricing 页面后再重试 |
如果只在某一条网络下访问失败,可以把同一 URL 放到手机热点和固定 Wi-Fi 中交叉测试;如果两条网络都失败,更应优先检查部署地址、Worker 日志和应用代码。本站已有Cloudflare 连接失败排查指南,可用于继续区分 DNS、TLS、源站和本地网络层问题。
常见报错:按认证、绑定、模型和额度分层处理
Account ID 错误:REST API URL 中需要的是账户的 Account ID,不要把 Zone ID、用户 ID 或域名名称填进去。先从 Workers AI 页面复制,再检查 URL 是否包含 /accounts/{ACCOUNT_ID}/ai/run/。
401 或 403:先确认 Token 没有复制缺失、没有过期,并检查自建 Token 是否同时具备 Workers AI - Read 和 Workers AI - Edit。如果错误出现在浏览器请求中,检查是否误把 Token放到了前端。
模型不存在:完整复制模型目录中的 ID。不要只修改模型名称的一部分,也不要把 Dashboard 示例中的请求字段直接套到另一种任务类型。
env.AI 未定义:检查配置文件中的 "binding": "AI" 是否与 TypeScript 的 AI: Ai 和 env.AI 完全一致。若绑定改名为 WORKERS_AI,代码应同步改为 env.WORKERS_AI。
额度错误:查看 Neurons 用量和 Pricing 页面中的付费条件。解决额度或账单条件后,先发送一次单独请求,不要立即循环重试。
Dashboard 改了但本地没变化:这是两套开发路径没有自动同步造成的。转入本地项目后,以本地文件、Wrangler 命令和部署结果为准。需要继续排查账户权限时,可查看本站的Cloudflare API Token 创建与连接排查。
建议的完整上手顺序
- 先用 Dashboard 的 LLM Chat App 确认账户和基本访问正常。
- 再用 Workers Binding 创建只返回 JSON 的最小 Worker,避免一开始加入复杂前端。
- 使用
npx wrangler dev本地测试,注意本地调用也会产生 Workers AI 用量。 - 需要网页接入时,让前端请求自己的 Worker,不要暴露 REST API Token。
- 需要脚本或后端调用时,再创建专用 API Token,并用请求文件测试 Windows
curl.exe。 - 部署前重新核对模型目录、绑定名称、Token 权限、Neurons 额度和网络访问。
本文为独立整理,非 Cloudflare 官方,引用页面仅作参考,本站与 Cloudflare 无合作关系。
核验日期:2026-11-19。官方页面中的模型、价格、权限和控制台路径可能调整,实际操作前请重新打开对应资料核对。
常见问题
Cloudflare Workers AI 免费吗?
官方 Pricing 页面当前显示每天有 10,000 Neurons 免费额度。Workers Paid 对超出免费额度的用量按页面单价计费,部分模型还要求付费账单方式。具体模型和价格应以官方 Pricing 页面当前显示为准。
Cloudflare Workers AI 一定要安装 Node.js 和 Wrangler 吗?
不一定。只使用 Dashboard 创建 LLM Chat App 时,可以先不走本地命令行;创建本地 Worker、配置 Binding、执行 wrangler dev 或部署时,才需要按官方要求准备 Node.js 和 Wrangler。
Workers AI 的 API Token 能放在前端吗?
不建议。浏览器 JavaScript、网页源码和移动端安装包都可能被读取。更安全的做法是让前端请求自己的 Worker,再由 Worker 使用 Binding 或服务端凭据调用模型。
为什么 env.AI 报错或显示未定义?
最常见原因是绑定名称不一致。配置写成 <code>"binding": "AI"</code> 时使用 <code>env.AI</code>;如果配置改成其他名称,TypeScript 接口和调用代码也必须同步修改。
本地 wrangler dev 会不会产生 Workers AI 用量?
会。官方 Workers and Wrangler 文档明确说明,本地开发调用仍会访问 Cloudflare 账户并产生用量,因此应避免自动刷新、循环请求和无控制的重试。
workers.dev 能解析但网页还是打不开怎么办?
先用 <code>curl -v</code> 区分 DNS、TCP、TLS 和 HTTP 阶段;如果已经返回 HTTP 状态码,说明请求至少到达了 HTTP 服务,应继续检查 Worker 路由、请求方法、模型、权限和日志,而不是只修改本机 DNS。
相关阅读
- Cloudflare 连接失败排查指南
- Cloudflare API Token 创建与连接排查
- Cloudflare Workers 入门与组件选型指南
- Cloudflare Pages 部署与域名绑定指南