cloudflare-workers-ai

Cloudflare Workers AI - 完整参考

用于使用 Cloudflare Workers AI 构建 AI 应用的生产就绪知识领域。

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

---

目录

1. 快速开始（5 分钟）
2. Workers AI API 参考
3. 模型选择指南
4. 常见模式
5. AI Gateway 集成
6. 速率限制与定价
7. 生产环境检查清单

---

快速开始（5 分钟）

1. 添加 AI 绑定

wrangler.jsonc：

{
  "ai": {
    "binding": "AI"
  }
}

2. 运行你的第一个模型

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      prompt: 'What is Cloudflare?',
    });

    return Response.json(response);
  },
};

3. 添加流式传输（推荐）

const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true, // Always use streaming for text generation!
});

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

为什么使用流式传输？

• 防止在内存中缓冲大型响应
• 缩短首个 Token 的生成时间
• 为长篇内容提供更好的用户体验
• 避免 Worker 超时问题

---

Workers AI API 参考

env.AI.run()

运行 AI 模型推理。

签名：

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

参数：

• model（string，必填）- 模型 ID（例如：@cf/meta/llama-3.1-8b-instruct）
• inputs（object，必填）- 模型专属输入
• options（object，可选）- 其他选项
  • gateway（object）- AI Gateway 配置
    • id（string）- Gateway ID
    • skipCache（boolean）- 跳过 AI Gateway 缓存

返回值：

• 非流式：Promise<ModelOutput> - JSON 响应
• 流式：ReadableStream - 服务器发送事件流

---

文本生成模型

输入格式：

{
  messages?: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>;
  prompt?: string; // Deprecated, use messages
  stream?: boolean; // Default: false
  max_tokens?: number; // Max tokens to generate
  temperature?: number; // 0.0-1.0, default varies by model
  top_p?: number; // 0.0-1.0
  top_k?: number;
}

输出格式（非流式）：

{
  response: string; // Generated text
}

示例：

const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is TypeScript?' },
  ],
  stream: false,
});

console.log(response.response);

---

文本嵌入模型

输入格式：

{
  text: string | string[]; // Single text or array of texts
}

输出格式：

{
  shape: number[]; // [batch_size, embedding_dimensions]
  data: number[][]; // Array of embedding vectors
}

示例：

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

console.log(embeddings.shape); // [2, 768]
console.log(embeddings.data[0]); // [0.123, -0.456, ...]

---

图像生成模型

输入格式：

{
  prompt: string; // Text description
  num_steps?: number; // Default: 20
  guidance?: number; // CFG scale, default: 7.5
  strength?: number; // For img2img, default: 1.0
  image?: number[][]; // For img2img (base64 or array)
}

输出格式：

• 二进制图像数据（PNG/JPEG）

示例：

const imageStream = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A beautiful sunset over mountains',
});

return new Response(imageStream, {
  headers: { 'content-type': 'image/png' },
});

---

视觉模型

输入格式：

{
  messages: Array<{
    role: 'user' | 'assistant';
    content: Array<{ type: 'text' | 'image_url'; text?: string; image_url?: { url: string } }>;
  }>;
}

示例：

const response = await env.AI.run('@cf/meta/llama-3.2-11b-vision-instruct', {
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is in this image?' },
        { type: 'image_url', image_url: { url: 'data:image/png;base64,iVBOR...' } },
      ],
    },
  ],
});

---

模型选择指南

文本生成（大模型）

模型	最适合	速率限制	规模
@cf/meta/llama-3.1-8b-instruct	通用、快速	300/min	8B
@cf/meta/llama-3.2-1b-instruct	超快、简单任务	300/min	1B
@cf/qwen/qwen1.5-14b-chat-awq	高质量、复杂推理	150/min	14B
@cf/deepseek-ai/deepseek-r1-distill-qwen-32b	编码、技术内容	300/min	32B
@hf/thebloke/mistral-7b-instruct-v0.1-awq	快速、高效	400/min	7B

文本嵌入

模型	维度	最适合	速率限制
@cf/baai/bge-base-en-v1.5	768	通用 RAG	3000/min
@cf/baai/bge-large-en-v1.5	1024	高精度搜索	1500/min
@cf/baai/bge-small-en-v1.5	384	快速、低存储占用	3000/min

图像生成

模型	最适合	速率限制	速度
@cf/black-forest-labs/flux-1-schnell	高质量、照片级真实感	720/min	快
@cf/stabilityai/stable-diffusion-xl-base-1.0	通用	720/min	中
@cf/lykon/dreamshaper-8-lcm	艺术风格化	720/min	快

视觉模型

模型	最适合	速率限制
@cf/meta/llama-3.2-11b-vision-instruct	图像理解	720/min
@cf/unum/uform-gen2-qwen-500m	快速图像描述	720/min

---

常见模式

模式 1：包含历史记录的聊天补全

app.post('/chat', async (c) => {
  const { messages } = await c.req.json<{
    messages: Array<{ role: string; content: string }>;
  }>();

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

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

---

模式 2：RAG（检索增强生成）

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

const vector = embeddings.data[0];

// Step 2: Search Vectorize
const matches = await env.VECTORIZE.query(vector, { topK: 3 });

// Step 3: Build context from matches
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');

// Step 4: Generate response 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,
});

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

---

模式 3：使用 Zod 的结构化输出

import { z } from 'zod';

const RecipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(z.string()),
  instructions: z.array(z.string()),
  prepTime: z.number(),
});

app.post('/recipe', async (c) => {
  const { dish } = await c.req.json<{ dish: string }>();

  const response = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    messages: [
      {
        role: 'user',
        content: `Generate a recipe for ${dish}. Return ONLY valid JSON matching this schema: ${JSON.stringify(RecipeSchema.shape)}`,
      },
    ],
  });

  // Parse and validate
  const recipe = RecipeSchema.parse(JSON.parse(response.response));

  return c.json(recipe);
});

---

模式 4：图像生成 + R2 存储

app.post('/generate-image', async (c) => {
  const { prompt } = await c.req.json<{ prompt: string }>();

  // Generate image
  const imageStream = await c.env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
    prompt,
  });

  const imageBytes = await new Response(imageStream).bytes();

  // Store in R2
  const key = `images/${Date.now()}.png`;
  await c.env.BUCKET.put(key, imageBytes, {
    httpMetadata: { contentType: 'image/png' },
  });

  return c.json({
    success: true,
    url: `https://your-domain.com/${key}`,
  });
});

---

AI Gateway 集成

AI Gateway 为 AI 请求提供缓存、日志记录和分析功能。

设置：

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

优势：

• ✅ 成本跟踪 - 监控每个请求的神经元用量
• ✅ 缓存 - 降低重复推理成本
• ✅ 日志记录 - 调试和分析 AI 请求
• ✅ 速率限制 - 增加一层保护
• ✅ 分析 - 请求模式和性能

访问 Gateway 日志：

const gateway = env.AI.gateway('my-gateway');
const logId = env.AI.aiGatewayLogId;

// Send feedback
await gateway.patchLog(logId, {
  feedback: { rating: 1, comment: 'Great response' },
});

---

速率限制与定价

速率限制（每分钟）

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

定价（基于神经元）

免费层级：

• 每天 10,000 个神经元
• 每天 00:00 UTC 重置

付费层级：

• 每 1,000 个神经元收费 $0.011
• 包含每天 10,000 个神经元
• 超出免费额度后可无限使用

费用示例：

模型	输入（1M 个令牌）	输出（1M 个令牌）
Llama 3.2 1B	$0.027	$0.201
Llama 3.1 8B	$0.088	$0.606
BGE-base 嵌入	$0.005	N/A
Flux 图像生成	~$0.011/张图像	N/A

---

生产环境检查清单

部署前

• 启用 AI Gateway 以进行成本跟踪和日志记录
• 为所有文本生成端点实现流式传输
• 添加速率限制重试，并采用指数退避
• 验证输入长度，防止令牌限制错误
• 设置适当的超时（Workers：CPU 默认 30s，最长 5m）
• 在 Cloudflare 仪表板中监控神经元用量
• 测试错误处理，涵盖模型不可用和速率限制的情况
• 添加输入清理，防止提示词注入
• 如果从浏览器使用，则配置 CORS
• 规划扩展 - 如有需要，升级到付费套餐

错误处理

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;
      const message = lastError.message.toLowerCase();

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

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

  throw lastError!;
}

监控

app.use('*', async (c, next) => {
  const start = Date.now();

  await next();

  // Log AI usage
  console.log({
    path: c.req.path,
    duration: Date.now() - start,
    logId: c.env.AI.aiGatewayLogId,
  });
});

---

OpenAI 兼容性

Workers AI 支持兼容 OpenAI 的端点。

使用 OpenAI SDK：

import OpenAI from 'openai';

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

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

// Embeddings
const embeddings = await openai.embeddings.create({
  model: '@cf/baai/bge-base-en-v1.5',
  input: 'Hello world',
});

端点：

• /v1/chat/completions - 文本生成
• /v1/embeddings - 文本嵌入

---

Vercel AI SDK 集成

npm install workers-ai-provider ai

import { createWorkersAI } from 'workers-ai-provider';
import { generateText, streamText } from 'ai';

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

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

// Stream text
const stream = streamText({
  model: workersai('@cf/meta/llama-3.1-8b-instruct'),
  prompt: 'Tell me a story',
});

---

限制摘要

功能	限制
并发请求	无硬性限制（受速率限制约束）
最大输入令牌数	因模型而异（通常为 2K-128K）
最大输出令牌数	因模型而异（通常为 512-2048）
流式传输块大小	~1 KB
图像大小（输出）	~5 MB
请求超时	受 Workers 超时限制（默认 30s，CPU 最长 5m）
每日免费神经元	10,000
速率限制	参见“速率限制与定价”部分

---

参考资料

• Workers AI 文档
• 模型目录
• AI Gateway
• 定价
• 限制
• REST API