cloudflare-workers-ai

Cloudflare Workers AI - 完整参考

用于借助 Cloudflare Workers AI 构建 AI 驱动应用的生产就绪知识领域。

状态：生产就绪 ✅ 最后更新：2025-11-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 参考

核心 API：env.AI.run()

const response = await env.AI.run(model, inputs, options?);

参数	类型	说明
model	string	模型 ID（例如，@cf/meta/llama-3.1-8b-instruct）
inputs	object	特定于模型的输入（见下文模型类型）
options.gateway.id	string	用于缓存/日志记录的 AI Gateway ID
options.gateway.skipCache	boolean	跳过 AI Gateway 缓存

返回值：Promise<ModelOutput>（非流式）或 ReadableStream（流式）

按模型类别划分的输入类型

类别	关键输入	输出
文本生成	messages[]、stream、max_tokens、temperature	{ response: string }
嵌入	text: string | string[]	{ data: number[][], shape: number[] }
图像生成	prompt、num_steps、guidance	二进制 PNG
视觉	messages[].content[].image_url	{ response: string }

📄 完整模型详情：加载 references/models-catalog.md，查看完整模型列表、参数和速率限制。

---

模型选择指南

文本生成（大模型）

模型	最适合	速率限制	大小
@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 stream = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages, stream: true });
  return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
});

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

// 1. Generate embedding for query
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 });
// 3. Build context
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');
// 4. Generate with context
const stream = 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(stream, { headers: { 'content-type': 'text/event-stream' } });

📄 更多模式：加载 references/best-practices.md，了解结构化输出、图像生成、多模型共识和生产环境模式。

---

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 },
});

优势：成本追踪、响应缓存（重复查询可节省 50-90%）、请求日志记录、速率限制、分析。

---

速率限制与定价

上次验证信息的日期：2025-01-14

不同模型的速率限制和定价差异很大。请务必查看官方文档以获取最新信息：

• 速率限制：https://developers.cloudflare.com/workers-ai/platform/limits/
• 定价：https://developers.cloudflare.com/workers-ai/platform/pricing/

免费层级：每天 10,000 个神经元 付费层级：每 1,000 个神经元 $0.011

📄 各模型详情：有关每个模型的具体速率限制和定价，请参阅 references/models-catalog.md。

---

生产环境检查清单

部署前必做事项：

• 启用 AI Gateway 以追踪成本
• 为文本生成实现流式传输
• 添加带指数退避的速率限制重试
• 验证输入长度（防止令牌限制错误）
• 添加输入清理（防止提示词注入）

📄 完整检查清单：加载 references/best-practices.md，查看完整的生产环境检查清单、错误处理模式、监控和成本优化内容。

---

外部 SDK 集成

Workers AI 支持 OpenAI SDK 兼容性和 Vercel AI SDK：

// OpenAI SDK - use same patterns with Workers AI models
const openai = new OpenAI({
  apiKey: env.CLOUDFLARE_API_KEY,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
});

// Vercel AI SDK - native integration
import { createWorkersAI } from 'workers-ai-provider';
const workersai = createWorkersAI({ binding: env.AI });

📄 完整集成指南：加载 references/integrations.md，查看 OpenAI SDK、Vercel AI SDK 和 REST API 示例。

---

限制摘要

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

---

何时加载参考资料

参考文件	加载时机……
references/models-catalog.md	选择模型、查看速率限制、比较模型能力时
references/best-practices.md	部署到生产环境、处理错误、优化成本、保障安全时
references/integrations.md	使用 OpenAI SDK、Vercel AI SDK 或 REST API，而非原生绑定时

---

参考资料

• Workers AI 文档
• 模型目录
• AI Gateway
• 定价