cloudflare-workers-ai

Cloudflare Workers AI

状态：生产就绪 ✅ 最后更新：2026-01-21 依赖项：cloudflare-worker-base（用于 Worker 设置） 最新版本：[email protected]、@cloudflare/[email protected]、[email protected]

近期更新（2025）：

• 2025 年 4 月 - 性能：Llama 3.3 70B 速度提升 2-4 倍（推测解码、前缀缓存），BGE 嵌入速度提升 2 倍
• 2025 年 4 月 - 重大变更：max_tokens 现在会正确默认为 256（此前默认值未生效），BGE 池化参数（cls 与 mean 不向后兼容）
• 2025 年 - 新模型（14 个）：Mistral 3.1 24B（视觉 + 工具）、Gemma 3 12B（128K 上下文）、EmbeddingGemma 300M、Llama 4 Scout、GPT-OSS 120B/20B、Qwen 模型（QwQ 32B、Coder 32B）、Leonardo 图像生成、Deepgram Aura 2、Whisper v3 Turbo、IBM Granite、Nova 3
• 2025 年 - 平台：上下文窗口 API 变更（按 token 而非字符计数）、按单位计费且精确到模型、workers-ai-provider v3.0.2（AI SDK v5）、LoRA 秩最高可达 32（此前为 8）、每个账户可使用 100 个适配器
• 2025 年 10 月：模型弃用（改用 Llama 4、GPT-OSS）

---

快速开始（5 分钟）

// 1. Add AI binding to wrangler.jsonc
{ "ai": { "binding": "AI" } }

// 2. Run model with streaming (recommended)
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      messages: [{ role: 'user', content: 'Tell me a story' }],
      stream: true, // Always stream for text generation!
    });

    return new Response(stream, {
      headers: { 'content-type': 'text/event-stream' },
    });
  },
};

**为什么使用流式传输？**避免在内存中缓冲、更快获得首个 token，并避免 Worker 超时问题。

---

已知问题预防

此技能可预防 7 个已记录的问题：

问题 #1：上下文窗口验证改为按 Token 计数（2025 年 2 月）

错误：尽管模型支持更大的上下文，仍出现 "Exceeded character limit" 来源：Cloudflare 更新日志 发生原因：2025 年 2 月之前，Workers AI 验证提示词时使用固定的 6144 字符限制，即使模型支持更大的基于 token 的上下文窗口（例如，Mistral 支持 32K token）。更新后，验证方式改为按 token 计数。 预防措施：检查上下文窗口限制时，计算 token 数（而非字符数）。

import { encode } from 'gpt-tokenizer'; // or model-specific tokenizer

const tokens = encode(prompt);
const contextWindow = 32768; // Model's max tokens (check docs)
const maxResponseTokens = 2048;

if (tokens.length + maxResponseTokens > contextWindow) {
  throw new Error(`Prompt exceeds context window: ${tokens.length} tokens`);
}

const response = await env.AI.run('@cf/mistral/mistral-7b-instruct-v0.2', {
  messages: [{ role: 'user', content: prompt }],
  max_tokens: maxResponseTokens,
});

问题 #2：控制面板中的神经元用量不一致

错误：控制面板显示的神经元用量远高于根据 token 计算的预期值 来源：Cloudflare 社区讨论 发生原因：用户反馈称，控制面板显示的神经元用量达到数亿级，而 token 用量仅为数千级；AutoRAG 功能和某些模型尤其如此。预期神经元用量（基于定价文档）与控制面板中的实际指标之间的差异尚未得到完整说明。 预防措施：通过 AI Gateway 日志监控神经元用量，并与请求关联。如果用量明显超出预期，请提交支持工单。

// Use AI Gateway for detailed request logging
const response = await env.AI.run(
  '@cf/meta/llama-3.1-8b-instruct',
  { messages: [{ role: 'user', content: query }] },
  { gateway: { id: 'my-gateway' } }
);

// Monitor dashboard at: https://dash.cloudflare.com → AI → Workers AI
// Compare neuron usage with token counts
// File support ticket with details if discrepancy persists

问题 #3：本地开发中的 AI 绑定需要远程模式或最新工具

错误："MiniflareCoreError: wrapped binding module can't be resolved (internal modules only)" 来源：GitHub 问题 #6796 发生原因：在本地开发中使用 Miniflare 的 Workers AI 绑定时（尤其是使用自定义 Vite 插件时），AI 绑定需要外部 Worker，而较旧的 unstable_getMiniflareWorkerOptions 未能正确公开这些 Worker。当 Miniflare 无法解析内部 AI Worker 模块时，就会出现此错误。 预防措施：在本地开发中为 AI 使用远程绑定，或更新到最新版本的 @cloudflare/vite-plugin。

// wrangler.jsonc - Option 1: Use remote AI binding in local dev
{
  "ai": { "binding": "AI" },
  "dev": {
    "remote": true // Use production AI binding locally
  }
}

# Option 2: Update to latest tooling
npm install -D @cloudflare/vite-plugin@latest

# Option 3: Use wrangler dev instead of custom Miniflare
npm run dev

问题 #4：Flux 图像生成的 NSFW 过滤器误报

错误：无害提示词触发 "AiError: Input prompt contains NSFW content (code 3030)" 来源：Cloudflare 社区讨论 原因：即使使用“hamburger”这类无害的单词提示词，Flux 图像生成模型（@cf/black-forest-labs/flux-1-schnell）有时也会误报 NSFW 内容错误。缺少上下文时，NSFW 过滤器可能过于敏感。 预防措施：为可能触发过滤器的词语添加描述性上下文，而不是使用单词提示词。

// ❌ May trigger error 3030
const response = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'hamburger', // Single word triggers filter
});

// ✅ Add context to avoid false positives
const response = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A photo of a delicious large hamburger on a plate with lettuce and tomato',
  num_steps: 4,
});

问题 #5：图像生成错误 1000——缺少 num_steps 参数

错误："Error: unexpected type 'int32' with value 'undefined' (code 1000)" 来源：Cloudflare 社区讨论 原因：未提供 num_steps 参数时，图像生成 API 调用会返回错误代码 1000，尽管文档称该参数可选。实际上，大多数 Flux 模型都需要此参数。 预防措施：使用图像生成模型时始终包含 num_steps: 4（Flux Schnell 通常使用 4）。

// ✅ Always include num_steps for image generation
const image = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A beautiful sunset over mountains',
  num_steps: 4, // Required - typically 4 for Flux Schnell
});

// Note: FLUX.2 [klein] 4B has fixed steps=4 (cannot be adjusted)

问题 #6：Zod v4 与结构化输出工具不兼容

错误：使用 Zod v4 时，Stagehand 出现语法错误和转译失败 来源：GitHub Issue #10798 原因：Stagehand（浏览器自动化）以及 Workers AI 中的一些结构化输出示例无法与 Zod v4（现为默认版本）配合使用。底层的 zod-to-json-schema 库尚不支持 Zod v4，导致转译失败。 预防措施：在 zod-to-json-schema 支持 v4 之前，将 Zod 固定在 v3。

# Install Zod v3 specifically
npm install zod@3

# Or pin in package.json
{
  "dependencies": {
    "zod": "~3.23.8" // Pin to v3 for compatibility
  }
}

问题 #7：通过 AI Gateway 缓存标头按请求控制缓存

这不是错误，而是一项重要功能：AI Gateway 支持通过 HTTP 标头按请求控制缓存，可自定义 TTL、绕过缓存并自定义缓存键，不受仪表板默认设置的限制。 来源：AI Gateway 缓存文档 适用场景：需要为不同请求设置不同的缓存行为时（例如，昂贵查询缓存 1 小时，实时数据跳过缓存）。 实现方式：请参阅下方的 AI Gateway 集成部分，了解标头用法。

---

API 参考

env.AI.run(
  model: string,
  inputs: ModelInputs,
  options?: { gateway?: { id: string; skipCache?: boolean } }
): Promise<ModelOutput | ReadableStream>

---

模型选择指南（2025 年更新）

文本生成（LLM）

模型	最适合	速率限制	大小	备注
2025 年模型
@cf/meta/llama-4-scout-17b-16e-instruct	最新 Llama，通用场景	300/min	17B	2025 年新品
@cf/openai/gpt-oss-120b	最大型开源 GPT	300/min	120B	2025 年新品
@cf/openai/gpt-oss-20b	更小型开源 GPT	300/min	20B	2025 年新品
@cf/google/gemma-3-12b-it	128K 上下文，140 多种语言	300/min	12B	2025 年新品，支持视觉
@cf/mistralai/mistral-small-3.1-24b-instruct	视觉 + 工具调用	300/min	24B	2025 年新品
@cf/qwen/qwq-32b	推理、复杂任务	300/min	32B	2025 年新品
@cf/qwen/qwen2.5-coder-32b-instruct	编码专家	300/min	32B	2025 年新品
@cf/qwen/qwen3-30b-a3b-fp8	快速量化模型	300/min	30B	2025 年新品
@cf/ibm-granite/granite-4.0-h-micro	小型、高效	300/min	Micro	2025 年新品
性能（2025 年）
@cf/meta/llama-3.3-70b-instruct-fp8-fast	速度提升 2-4 倍（2025 年更新）	300/min	70B	推测解码
@cf/meta/llama-3.1-8b-instruct-fp8-fast	快速 8B 版本	300/min	8B	-
标准模型
@cf/meta/llama-3.1-8b-instruct	通用场景	300/min	8B	-
@cf/meta/llama-3.2-1b-instruct	超快，适用于简单任务	300/min	1B	-
@cf/deepseek-ai/deepseek-r1-distill-qwen-32b	编码、技术任务	300/min	32B	-

文本嵌入（速度提升 2 倍 - 2025）

模型	维度	最适合	速率限制	备注
@cf/google/embeddinggemma-300m	768	一流的 RAG	3000/min	2025 年新增
@cf/baai/bge-base-en-v1.5	768	通用 RAG（速度提升 2 倍）	3000/min	建议使用 pooling: "cls"
@cf/baai/bge-large-en-v1.5	1024	高准确度（速度提升 2 倍）	1500/min	建议使用 pooling: "cls"
@cf/baai/bge-small-en-v1.5	384	快速、存储占用低（速度提升 2 倍）	3000/min	建议使用 pooling: "cls"
@cf/qwen/qwen3-embedding-0.6b	768	Qwen 嵌入	3000/min	2025 年新增

重要（2025）：BGE 模型现已支持 pooling: "cls" 参数（推荐），但与 pooling: "mean"（默认值）不向后兼容。

图像生成

模型	最适合	速率限制	备注
@cf/black-forest-labs/flux-1-schnell	高质量、逼真写实	720/min	⚠️ 请参阅下方警告
@cf/leonardo/lucid-origin	Leonardo AI 风格	720/min	2025 年新增，需设置 num_steps
@cf/leonardo/phoenix-1.0	Leonardo AI 变体	720/min	2025 年新增，需设置 num_steps
@cf/stabilityai/stable-diffusion-xl-base-1.0	通用	720/min	需设置 num_steps

⚠️ 常见的图像生成问题：

• 错误 1000：务必包含 num_steps: 4 参数（即使文档称其为可选项，此参数仍为必需）
• 错误 3030（NSFW 过滤器）：像“汉堡”这样的单个词可能会触发误报；请在提示词中添加描述性上下文

// ✅ Correct pattern for image generation
const image = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A photo of a delicious hamburger on a plate with fresh vegetables',
  num_steps: 4, // Required to avoid error 1000
});
// Descriptive context helps avoid NSFW false positives (error 3030)

视觉模型

模型	最适合	速率限制	备注
@cf/meta/llama-3.2-11b-vision-instruct	图像理解	720/min	-
@cf/google/gemma-3-12b-it	视觉 + 文本（128K 上下文）	300/min	2025 年新增

音频模型（2025）

模型	类型	速率限制	备注
@cf/deepgram/aura-2-en	文本转语音（英语）	720/min	2025 年新增
@cf/deepgram/aura-2-es	文本转语音（西班牙语）	720/min	2025 年新增
@cf/deepgram/nova-3	语音转文本（+ WebSocket）	720/min	2025 年新增
@cf/openai/whisper-large-v3-turbo	语音转文本（更快）	720/min	2025 年新增

---

常用模式

RAG（检索增强生成）

// 1. Generate embeddings
const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [userQuery] });

// 2. Search Vectorize
const matches = await env.VECTORIZE.query(embeddings.data[0], { topK: 3 });
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');

// 3. Generate with context
const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [
    { role: 'system', content: `Answer using this context:\n${context}` },
    { role: 'user', content: userQuery },
  ],
  stream: true,
});

---

使用 Zod 的结构化输出

import { z } from 'zod';

const Schema = z.object({ name: z.string(), items: z.array(z.string()) });

const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [{
    role: 'user',
    content: `Generate JSON matching: ${JSON.stringify(Schema.shape)}`
  }],
});

const validated = Schema.parse(JSON.parse(response.response));

---

AI Gateway 集成

为 AI 请求提供缓存、日志记录、成本跟踪和分析功能。

Gateway 基本用法

const response = await env.AI.run(
  '@cf/meta/llama-3.1-8b-instruct',
  { prompt: 'Hello' },
  { gateway: { id: 'my-gateway', skipCache: false } }
);

// Access logs and send feedback
const gateway = env.AI.gateway('my-gateway');
await gateway.patchLog(env.AI.aiGatewayLogId, {
  feedback: { rating: 1, comment: 'Great response' },
});

单请求缓存控制（高级）

使用 HTTP 标头覆盖默认缓存行为，实现精细控制：

// Custom cache TTL (1 hour for expensive queries)
const response = await fetch(
  `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/workers-ai/@cf/meta/llama-3.1-8b-instruct`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${env.CLOUDFLARE_API_KEY}`,
      'Content-Type': 'application/json',
      'cf-aig-cache-ttl': '3600', // 1 hour in seconds (min: 60, max: 2592000)
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: prompt }],
    }),
  }
);

// Skip cache for real-time data
const response = await fetch(gatewayUrl, {
  headers: {
    'cf-aig-skip-cache': 'true', // Bypass cache entirely
  },
  // ...
});

// Check if response was cached
const cacheStatus = response.headers.get('cf-aig-cache-status'); // "HIT" or "MISS"

可用的缓存标头：

• cf-aig-cache-ttl：以秒为单位设置自定义 TTL（60s 到 1 个月）
• cf-aig-skip-cache：完全绕过缓存（'true'）
• cf-aig-cache-key：自定义缓存键，实现精细控制
• cf-aig-cache-status：响应标头，显示 "HIT" 或 "MISS"

**优点：**成本跟踪、缓存（减少重复推理）、日志记录、速率限制、分析、按请求自定义缓存。

---

速率限制与定价（2025 年更新）

速率限制（每分钟）

任务类型	默认限制	备注
文本生成	300/min	部分快速模型：400-1500/min
文本嵌入	3000/min	BGE-large：1500/min
图像生成	720/min	所有图像模型
视觉模型	720/min	图像理解
音频（TTS/STT）	720/min	Deepgram、Whisper
翻译	720/min	M2M100、Opus MT
分类	2000/min	文本分类

定价（按单位计费，以 Neurons 结算 - 2025 年）

免费层级：

• 每天 10,000 个 neurons
• 每天 00:00 UTC 重置

付费层级（每 1,000 个 neurons 收费 $0.011）：

• 每天包含 10,000 个 neurons
• 超出免费额度后可无限使用

2025 年模型费用（每 1M 个 tokens）：

模型	输入	输出	备注
2025 年模型
Llama 4 Scout 17B	$0.270	$0.850	2025 年新品
GPT-OSS 120B	$0.350	$0.750	2025 年新品
GPT-OSS 20B	$0.200	$0.300	2025 年新品
Gemma 3 12B	$0.345	$0.556	2025 年新品
Mistral 3.1 24B	$0.351	$0.555	2025 年新品
Qwen QwQ 32B	$0.660	$1.000	2025 年新品
Qwen Coder 32B	$0.660	$1.000	2025 年新品
IBM Granite Micro	$0.017	$0.112	2025 年新品
EmbeddingGemma 300M	$0.012	N/A	2025 年新品
Qwen3 Embedding 0.6B	$0.012	N/A	2025 年新品
性能（2025 年）
Llama 3.3 70B Fast	$0.293	$2.253	快 2-4 倍
Llama 3.1 8B FP8 Fast	$0.045	$0.384	快速版本
标准模型
Llama 3.2 1B	$0.027	$0.201	-
Llama 3.1 8B	$0.282	$0.827	-
Deepseek R1 32B	$0.497	$4.881	-
BGE-base（快 2 倍）	$0.067	N/A	2025 年加速
BGE-large（快 2 倍）	$0.204	N/A	2025 年加速
图像模型（2025 年）
Flux 1 Schnell	$0.0000528，每个 512x512 图块	-
Leonardo Lucid	$0.006996，每个 512x512 图块	2025 年新品
Leonardo Phoenix	$0.005830，每个 512x512 图块	2025 年新品
音频模型（2025 年）
Deepgram Aura 2	每 1k 个字符 $0.030	2025 年新品
Deepgram Nova 3	每分钟音频 $0.0052	2025 年新品
Whisper v3 Turbo	每分钟音频 $0.0005	2025 年新品

---

使用重试进行错误处理

async function runAIWithRetry(
  env: Env,
  model: string,
  inputs: any,
  maxRetries = 3
): Promise<any> {
  let lastError: Error;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await env.AI.run(model, inputs);
    } catch (error) {
      lastError = error as Error;

      // Rate limit - retry with exponential backoff
      if (lastError.message.toLowerCase().includes('rate limit')) {
        await new Promise((resolve) => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }

      throw error; // Other errors - fail immediately
    }
  }

  throw lastError!;
}

---

OpenAI 兼容性

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: env.CLOUDFLARE_API_KEY,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/v1`,
});

// Chat completions
await openai.chat.completions.create({
  model: '@cf/meta/llama-3.1-8b-instruct',
  messages: [{ role: 'user', content: 'Hello!' }],
});

端点： /v1/chat/completions、/v1/embeddings

---

Vercel AI SDK 集成（workers-ai-provider v3.0.2）

import { createWorkersAI } from 'workers-ai-provider'; // v3.0.2 with AI SDK v5
import { generateText, streamText } from 'ai';

const workersai = createWorkersAI({ binding: env.AI });

// Generate or stream
await generateText({
  model: workersai('@cf/meta/llama-3.1-8b-instruct'),
  prompt: 'Write a poem',
});

---

社区技巧

注意： 这些技巧来自社区讨论和生产实践。

Hono 框架流式传输模式

使用 Hono 进行 Workers AI 流式传输时，应将流直接作为 Response 返回（而不是通过 Hono 的流式传输工具）：

import { Hono } from 'hono';

type Bindings = { AI: Ai };
const app = new Hono<{ Bindings: Bindings }>();

app.post('/chat', async (c) => {
  const { prompt } = await c.req.json();

  const stream = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    messages: [{ role: 'user', content: prompt }],
    stream: true,
  });

  // Return stream directly (not c.stream())
  return new Response(stream, {
    headers: {
      'content-type': 'text/event-stream',
      'cache-control': 'no-cache',
      'connection': 'keep-alive',
    },
  });
});

来源： Hono 讨论 #2409

排查原因不明的 AI 绑定故障

如果遇到原因不明的 Workers AI 故障：

# 1. Check wrangler version
npx wrangler --version

# 2. Clear wrangler cache
rm -rf ~/.wrangler

# 3. Update to latest stable
npm install -D wrangler@latest

# 4. Check local network/firewall settings
# Some corporate firewalls block Workers AI endpoints

注意： 大多数“版本不兼容”问题实际上是网络配置问题。

---

参考资料

• Workers AI 文档
• 模型目录
• AI Gateway
• 定价
• 更新日志
• LoRA 适配器
• MCP 工具： 使用 mcp__cloudflare-docs__search_cloudflare_documentation 获取最新文档