Workers AI:模型推理与本地调试

在 Worker 里直接调用 Cloudflare 托管的 AI 模型(LLM、embedding、图片、语音),无需自建 GPU、无需第三方 API key。本页讲计费模型、本地开发的行为和接入步骤。

计费:一切换算成 Neurons

所有模型用量统一换算成 Neurons 计费:

免费额度:每天 10,000 Neurons,UTC 0 点重置。Workers Free 档这是硬上限(用完即报错);Workers Paid 档超出部分按 $0.011 / 1,000 Neurons 计费。
按模型类型,计价单位不同(与 Neurons 等价标注,只是展示单位不同):

类型	计费单位	例子
LLM	输入 + 输出 token(输出比输入贵 5~8 倍)	llama-3.1-8b-fast:输入 $0.045/M,输出 $0.384/M
Embedding	仅输入 token	bge-small-en-v1.5:$0.020/M
图片	按 512×512 tile 或 diffusion 步数	flux-1-schnell:$0.0000528/tile
音频	语音转文字按分钟,TTS 按千字符	Whisper:$0.0005/分钟

最新单价见 Workers AI Pricing,Dashboard → Workers & Pages → Workers AI 可按模型查用量。

本模型目录里少数模型(部分 Kimi、GLM、DeepSeek 变体)只对付费档开放。

本地开发:binding 不是 mock,走真实推理

关键认知:与 D1/R2/KV(miniflare 本地模拟)不同,Workers AI 的 binding 在本地开发时不会被模拟——pnpm dev(vite plugin 底层是 miniflare/workerd)里调用 env.AI.run() 会代理到你真实的 Cloudflare 账号做真实推理。

由此推论:

需要 wrangler 登录态(wrangler login,或 CLOUDFLARE_API_TOKEN);多账号时在 wrangler.jsonc 顶层指定 account_id。
用量照常计费,计入每天 10,000 免费额度。本地调试不是免费的——只是通常免费额度够用(以 llama-3.1-8b-fast 计,10k Neurons ≈ 每天约 28 万输出 token)。
不需要任何 secret env key,binding 本身就是凭证。这和 Resend/Stripe「无 key 即关闭」的降级模式不同(见下文)。

接入步骤

wrangler 配置加 binding。wrangler.jsonc(git-ignored)与 wrangler.example.jsonc(模板参考)两处同步:
```
"ai": { "binding": "AI" }
```
类型声明:在 worker env 类型里加 AI: Ai(import type { Ai } from '@cloudflare/workers-types')。

const result = await env.AI.run('@cf/meta/llama-3.1-8b-instruct-fast', {
  messages: [{ role: 'user', content: 'hello' }],
})

优雅降级(按本模板惯例)

AI binding 不走 env key,「没配置就自动关闭」在这里不成立——需要显式开关,例如 wrangler.jsonc 的 vars 放 AI_ENABLED,或对调用点 try/catch 兜底。原则不变:AI 不可用时主流程照常工作,只是相应功能降级。

测试注意

workers 池(*.workers.test.ts):vitest-pool-workers 支持 ai binding,行为同本地 dev——真实远程调用、消耗额度。批量断言用小模型 + 短 prompt。
node 池(*.node.test.ts):没有 workerd runtime、没有 binding。纯逻辑测试照惯例把 AI 调用抽象在函数边界外(注入或参数化),保持 node 可测。

成本与坑

本地调试别裸跑大模型:调试期用 @cf/meta/llama-3.1-8b-instruct-fast 这类小模型,上线再按需升级;输出 token 单价远高于输入,生成式功能的大头在输出。
别在热路径/循环里无节制调用:先算一笔账(日活 × 人均调用 × 每 token 单价)再上量。
AI Gateway 转发第三方模型(OpenAI、Anthropic 等):通过 Unified Billing 充值有 5% 手续费;但用 AI Gateway 缓存自己的 Workers AI 请求不额外收费。
相关 Workers/D1 本地行为对照见 Cloudflare 已知坑。