HGfast Cloud 灵狐加速 · 一站式全球云网络返回首页

Cloudflare Workers AI 怎么用?三种调用方式、免费额度与报错排查

更新于 2026-11-19 · hgfastapp.lol

简答:只想先跑通一个 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 AppDashboard 修改与本地代码不会自动同步
Workers Binding要开发自己的 Worker 或 Pages Functions账户、Node.js、WranglerWrangler 文件配置 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 是最短路径。它适合验证账户、模型调用和网页访问链路,但不适合多人协作或复杂项目的长期版本管理。

  1. 登录 Cloudflare Dashboard,打开 Workers & Pages。
  2. 选择 Create application。
  3. 在模板区域选择 LLM Chat App。
  4. 选择 Deploy。
  5. 为 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 dev

Wrangler 会提供本地访问地址。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 数量、模型、缓存和返回长度不同,结果也会不同,所以这个数字只能作为计算方法示例,不是固定单次请求价格。

排查费用时按这个顺序:

  1. 在 Workers AI Dashboard 查看当前 Neurons 用量。
  2. 确认模型是否需要付费账单方式。
  3. 区分 Workers Free、Workers Paid 和 AI Gateway credits 的计费路径。
  4. 检查本地 wrangler dev 是否被自动刷新、循环测试或重复重试调用。

价格、模型单价和付费模型清单以Workers AI Pricing当前页面为准。

workers.dev 打不开或请求超时:先区分 DNS、网络和应用错误

部署完成后,如果 workers.dev 地址打不开,不要马上修改模型配置。先把问题分成三层:域名是否能解析、TCP/TLS 是否能连接、Worker 是否返回应用响应。

  1. 先查 DNS:Windows 使用 nslookup 你的-worker.你的子域名.workers.dev;Linux 或 macOS 使用 dig 你的-worker.你的子域名.workers.dev。如果没有地址答案、返回超时或查询失败,先检查本机 DNS、路由器 DNS、企业网络策略和当前网络。
  2. 再看连接过程:Windows 使用 curl.exe -v https://你的-worker.你的子域名.workers.dev;Linux 或 macOS 使用 curl -v https://你的-worker.你的子域名.workers.dev。重点看是否完成 DNS、TCP 和 TLS,然后再看 HTTP 状态码。
  3. 最后查应用:能建立 HTTPS 连接但返回 401、403、404、405 或 5xx,说明请求已经到达某个 HTTP 服务,应转向 Worker 路由、请求方法、Token、绑定、模型和日志排查。
现象优先检查下一步
nslookup 或 dig 无答案本机 DNS、网络出口、域名拼写换一个网络交叉测试,再核对部署地址
DNS 有答案但 curl -v 卡在连接或 TLS网络出口、防火墙、代理、TLS 握手记录 -v 输出中的失败阶段,不要先改模型
返回 401 或 403REST API Token、权限、请求头确认使用 Bearer Token,检查 Read 与 Edit 权限
返回 404 或 405Worker 路由和 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 创建与连接排查。

建议的完整上手顺序

  1. 先用 Dashboard 的 LLM Chat App 确认账户和基本访问正常。
  2. 再用 Workers Binding 创建只返回 JSON 的最小 Worker,避免一开始加入复杂前端。
  3. 使用 npx wrangler dev 本地测试,注意本地调用也会产生 Workers AI 用量。
  4. 需要网页接入时,让前端请求自己的 Worker,不要暴露 REST API Token。
  5. 需要脚本或后端调用时,再创建专用 API Token,并用请求文件测试 Windows curl.exe。
  6. 部署前重新核对模型目录、绑定名称、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。

相关阅读

参考资料

  1. Cloudflare Workers AI 官方概览
  2. Cloudflare Workers AI Dashboard 快速入门
  3. Cloudflare Workers AI Workers and Wrangler 快速入门
  4. Cloudflare Workers AI Workers Binding 文档
  5. Cloudflare Workers AI REST API 快速入门
  6. Cloudflare Workers AI 模型目录
  7. Cloudflare Workers AI Pricing 定价页