⚡

CloudflareWorkersAI cloudflare-workers-ai

Cloudflare Workers AI 是一个服务器端AI推理平台，用于运行大语言模型、生成文本和图像、创建嵌入等AI任务，支持流式传输和AI网关集成，适用于构建AI驱动的应用。关键词：Cloudflare Workers AI, AI推理, 文本生成, 图像生成, 嵌入, LLMs, serverless AI, AI应用, 模型运行。

AI应用 0 次安装 0 次浏览 更新于 3/8/2026

name: cloudflare-workers-ai description: Cloudflare Workers AI 用于服务器端GPU推理。用于LLMs、文本/图像生成、嵌入，或遇到AI_ERROR、速率限制、令牌超过错误时。

关键词：workers ai, cloudflare ai, ai绑定, llm workers, @cf/meta/llama, workers ai模型, ai推理, cloudflare llm, ai流式传输, 文本生成ai, ai嵌入, 图像生成ai, workers ai rag, ai网关, llama workers, flux图像生成, stable diffusion workers, 视觉模型ai, ai聊天完成, AI_ERROR, 速率限制ai, 模型未找到, 令牌限制超过, 神经元超过, ai配额超过, 流式失败, 模型不可用, workers ai hono, ai网关workers, vercel ai sdk workers, openai兼容workers, workers ai vectorize license: MIT

Cloudflare Workers AI - 完整参考

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

状态: 生产就绪 ✅ 最后更新: 2025-11-21 依赖: cloudflare-worker-base（用于Worker设置） 最新版本: wrangler@4.43.0, @cloudflare/workers-types@4.20251014.0

目录

  1. 快速开始（5分钟）
  2. Workers AI API参考
  3. 模型选择指南
  4. 常见模式
  5. AI网关集成
  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: '什么是Cloudflare？',
    });

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

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

const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [{ role: 'user', content: '告诉我一个故事' }],
  stream: true, // 总是使用流式传输进行文本生成！
});

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

为什么流式传输？

  • 防止在内存中缓冲大响应
  • 更快的首次令牌时间
  • 长内容更好的用户体验
  • 避免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网关ID用于缓存/日志
options.gateway.skipCache boolean 跳过AI网关缓存

返回: 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 获取完整模型列表、参数和速率限制。

模型选择指南

文本生成（LLMs）

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

文本嵌入

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

图像生成

模型 最适合 速率限制 速度
@cf/black-forest-labs/flux-1-schnell 高质量，照片写实 720/分钟 快速
@cf/stabilityai/stable-diffusion-xl-base-1.0 通用目的 720/分钟 中等
@cf/lykon/dreamshaper-8-lcm 艺术，风格化 720/分钟 快速

视觉模型

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

常见模式

模式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. 生成查询的嵌入
const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [userQuery] });
// 2. 搜索Vectorize
const matches = await env.VECTORIZE.query(embeddings.data[0], { topK: 3 });
// 3. 构建上下文
const context = matches.matches.map((m) => m.metadata.text).join('

');
// 4. 用上下文生成
const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [
    { role: 'system', content: `用这个上下文回答：
${context}` },
    { role: 'user', content: userQuery },
  ],
  stream: true,
});
return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });

📄 更多模式: 加载 references/best-practices.md 获取结构化输出、图像生成、多模型共识和生产模式。

AI网关集成

启用缓存、日志和成本跟踪与AI网关：

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

速率限制和定价因模型而异。总是检查官方文档获取最新信息：

免费层: 10,000神经元/天 付费层: $0.011 每1,000神经元

📄 每模型细节: 见 references/models-catalog.md 获取每个模型的具体速率限制和定价。

生产检查清单

部署前必需：

  • [ ] 启用AI网关进行成本跟踪
  • [ ] 为文本生成实现流式传输
  • [ ] 添加速率限制重试与指数退避
  • [ ] 验证输入长度（防止令牌限制错误）
  • [ ] 添加输入清理（防止提示注入）

📄 完整检查清单: 加载 references/best-practices.md 获取完整生产检查清单、错误处理模式、监控和成本优化。

外部SDK集成

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

// OpenAI SDK - 使用相同模式与Workers AI模型
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 - 原生集成
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超时适用（默认30秒，最大5分钟CPU）
每日免费神经元 10,000
速率限制 见“速率限制和定价”部分

何时加载参考

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

参考