Cloudflare Workers AI 实战指南边缘 GPU 推理、模型选型与 RAG 落地全解析【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文是面向开发者的 Cloudflare Workers AI 完整实操指南覆盖在 Cloudflare 边缘网络上运行 GPU 加速 AI 推理的核心路径如何通过原生 Workers Binding 调用 50 预训练模型、如何按文本生成 / Embeddings / 图像生成等任务选型、如何组合 Vectorize 构建 RAG 检索增强生成以及流式输出、Function Calling、REST API、成本控制与常见坑位排查。读完本文你将能在 Workers / Pages 中直接部署可用的 AI 推理服务并掌握一套从配置、调用到上线的可复制方案。Workers AI 是什么边缘上的无服务器 GPU 推理Workers AI 是 Cloudflare 提供的无服务器 AI 推理服务核心特点可归纳为以下几点依据 workers-ai/README.md50 预训练模型覆盖 LLM 文本生成、Embeddings 向量化、图像生成、语音转文字、翻译等任务类型原生 Workers Binding通过env.AI.run()直接调用无需任何外部 API 调用与额外依赖按量付费每次推理消耗 neurons神经元按模型复杂度阶梯计价OpenAI 兼容 REST API非 Workers 环境、外部服务可通过标准 HTTP 调用兼容 OpenAI SDK流式输出文本生成原生支持 Streaming降低首字延迟Function Calling部分模型支持工具调用可用于构建 Agent 应用。从架构上看推理运行在 Cloudflare 的 GPU 网络中。模型在首次请求时加载存在约 13 秒的冷启动延迟后续请求会显著加快据 api.md后续请求约 100500ms。理解这一点对设计缓存与预热策略至关重要。在仓库的 SKILL.md 决策树中Workers AI 被定位为 Need AI / Run inference (LLMs, embeddings, images) 的首选参考与 Vectorize向量数据库、Agents SDK有状态 Agent、AI Gateway缓存/路由、AI SearchAI 搜索组件构成完整的 AI 基础设施组合。快速开始部署你的第一个 AI Worker1. 配置 wrangler.jsonc 并添加 Binding在wrangler.jsonc中添加ai绑定依据 configuration.md{ name: my-ai-worker, main: src/index.ts, compatibility_date: 2024-01-01, ai: { binding: AI } }2. 安装 TypeScript 类型npm install --save-dev cloudflare/workers-types安装后即可在Env接口中使用Ai类型该类型来自cloudflare/workers-types见 gotchas.mdinterface Env { AI: Ai; } export default { async fetch(request: Request, env: Env) { const response await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [{ role: user, content: What is Cloudflare? }] }); return Response.json(response); } };3. 本地开发与部署# Setup - add binding to wrangler.jsonc wrangler dev --remote # Must use --remote for AI wrangler deploy关键前提本地Local开发环境不包含模型权重AI 推理必须使用wrangler dev --remote见 configuration.md。执行wrangler deploy前请先通过npx wrangler whoami确认已认证参考 SKILL.md。模型选择决策树正确选型是控制成本与质量的核心。以下决策树完整继承自 README.md文本生成Chat / Completion优先级模型 ID特点神经元成本质量最佳cf/meta/llama-3.1-70b-instruct70B 参数质量最高但昂贵~2000 neurons均衡cf/meta/llama-3.1-8b-instruct质量与成本平衡默认推荐~200 neurons最快最省cf/mistral/mistral-7b-instruct-v0.1速度快、成本最低~50 neuronsFunction Calling工具调用使用cf/meta/llama-3.1-8b-instruct或cf/meta/llama-3.1-70b-instruct原生工具支持代码生成使用cf/deepseek-ai/deepseek-coder-6.7b-instruct代码专项优化。Embeddings语义搜索 / RAG场景模型 ID维度说明英文·最佳cf/baai/bge-base-en-v1.5系列中的bge-large-en-v1.51024质量最高英文·均衡cf/baai/bge-base-en-v1.5768质量良好英文·快速cf/baai/bge-small-en-v1.5384维度低、质量略低但快多语言hf/sentence-transformers/paraphrase-multilingual-minilm-l12-v2-多语言场景说明README 原文将英文场景三个模型分别写作bge-large-en-v1.5/bge-base-en-v1.5/bge-small-en-v1.5仓库其余文档api.md、patterns.md中的完整 ID 为cf/baai/bge-base-en-v1.5等选择具体型号时请在官方模型目录中核对完整 ID 以确保拼写无误错误模型 ID 会触发错误码 7502。图像生成Stable Diffusioncf/stabilityai/stable-diffusion-xl-base-1.0约 10,000 neurons属于高成本任务人像/面部优化cf/lykon/dreamshaper-8-lcm针对人脸优化。其他任务语音转文字cf/openai/whisper翻译cf/meta/m2m100-1.2b支持 100 种语言图像分类cf/microsoft/resnet-50三种调用方式SDK 方法决策树原生 Binding推荐适用场景构建 Workers / Pages 应用且使用 TypeScript。优势零外部依赖、性能最佳、类型原生。await env.AI.run(model, input);REST API适用场景外部服务、非 Workers 环境、测试调试。优势标准 HTTP任意环境可用。curl https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/run/cf/meta/llama-3.1-8b-instruct \ -H Authorization: Bearer API_TOKEN \ -d {messages:[{role:user,content:Hello}]}对应在代码中通过fetch调用见 configuration.mdconst response await fetch( https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/run/cf/meta/llama-3.1-8b-instruct, { method: POST, headers: { Authorization: Bearer ${API_TOKEN} }, body: JSON.stringify({ messages: [{ role: user, content: Hello }] }) } );API Token 需在 Cloudflare 控制台创建授予 Workers AI - Read 权限见 configuration.md。Vercel AI SDK / OpenAI SDK 集成适用场景需要使用 Vercel AI SDK 的流式 UI、工具调用抽象等能力。优势跨提供商统一接口。import { openai } from ai-sdk/openai; const model openai(model-name, { baseURL: https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/v1, headers: { Authorization: Bearer API_TOKEN } });原生 OpenAI SDK 同样适用configuration.md只需将baseURL指向 Workers AI 的 OpenAI 兼容端点/ai/v1import OpenAI from openai; const client new OpenAI({ apiKey: env.CLOUDFLARE_API_TOKEN, baseURL: https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/v1 });核心 API 详解env.AI.run 的完整用法文本生成核心方法是await env.AI.run(model, input)api.mdconst result await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [ { role: system, content: You are helpful }, { role: user, content: Hello } ], temperature: 0.7, // 0-1 max_tokens: 100 }); console.log(result.response);temperature采样温度范围 01值越低输出越确定设为 0 可获得确定性输出见 gotchas.mdmax_tokens单次输出最大 token 数注意不要超过模型上下文窗口2K8K token随模型而异。流式输出Streaming / SSEconst stream await env.AI.run(model, { messages, stream: true }); return new Response(stream, { headers: { Content-Type: text/event-stream } });stream: true时返回ReadableStream可逐 chunk 消费for await或通过TransformStream包装为标准 SSE 格式完整实现见 patterns.mdconst { readable, writable } new TransformStream(); const writer writable.getWriter(); (async () { for await (const chunk of stream) { await writer.write(new TextEncoder().encode(data: ${JSON.stringify(chunk)}\n\n)); } await writer.write(new TextEncoder().encode(data: [DONE]\n\n)); await writer.close(); })(); return new Response(readable, { headers: { Content-Type: text/event-stream } });Embeddings批量向量化const result await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [Query, Doc 1, Doc 2] // 批量提交以提高效率 }); const [queryEmbed, doc1Embed, doc2Embed] result.data; // 768 维向量返回结构为{ data: number[][]; shape: number[] }data是按输入顺序排列的向量数组gotchas.md。批量提交多条文本是官方推荐的性能优化手段见 api.md。Function Calling工具调用const tools [{ type: function, function: { name: getWeather, description: Get weather for location, parameters: { type: object, properties: { location: { type: string } }, required: [location] } } }]; const response await env.AI.run(model, { messages, tools }); if (response.tool_calls) { const args JSON.parse(response.tool_calls[0].function.arguments); // 执行函数把结果回传给模型 }注意目前仅cf/meta/llama-3.1-*与mistral-7b-instruct-v0.2支持工具调用gotchas.md。图像生成const image await env.AI.run(cf/stabilityai/stable-diffusion-xl-base-1.0, { prompt: Mountain sunset, num_steps: 20, // 1-20 guidance: 7.5 // 1-20 }); return new Response(image, { headers: { Content-Type: image/png } });语音识别Speech-to-Textconst audioArray Array.from(new Uint8Array(await request.arrayBuffer())); const result await env.AI.run(cf/openai/whisper, { audio: audioArray }); console.log(result.text);翻译const result await env.AI.run(cf/meta/m2m100-1.2b, { text: Hello, source_lang: en, target_lang: es }); console.log(result.translated_text);错误码速查表错误码含义修复方法7502模型不存在检查模型 ID 拼写在官方模型目录核对7504输入校验失败核对输入 schema文本生成需messages数组Embeddings 需text字段7505触发限流降低请求频率或升级套餐7506上下文超限缩减输入长度messages内容RAG vs 直接生成何时组合 Vectorize使用 RAGVectorize Workers AI的场景回答关于特定文档 / 私有数据的提问需要从已知语料中获得事实准确的回答上下文超过模型窗口4K tokens部分模型仅 2K8K构建知识库问答系统。使用直接生成的场景创意写作、头脑风暴通用知识问答上下文较小、可完整放进 prompt4K tokens成本敏感场景RAG 会增加 embedding 与向量检索成本。RAG 完整落地实现仓库 patterns.md 给出了四步式标准实现// 1. Embed query向量化查询 const embedding await env.AI.run(cf/baai/bge-base-en-v1.5, { text: query }); // 2. Search vectors检索向量库 const results await env.VECTORIZE.query(embedding.data[0], { topK: 5, returnMetadata: true }); // 3. Build context拼接上下文 const context results.matches.map(m m.metadata?.text).join(\n\n); // 4. Generate with context带上下文生成 const response await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [ { role: system, content: Answer based on:\n\n${context} }, { role: user, content: query } ] });配套的 Vectorize 配置见 configuration.md{ ai: { binding: AI }, vectorize: { bindings: [{ binding: VECTORIZE, index_name: embeddings-index }] } }Vectorize 是全局分布式向量数据库详见 vectorize/README.md创建索引时需指定维度与距离度量且索引配置不可变创建后无法修改维度或度量方式。文本/语义搜索建议使用cosine度量。若追求更高一致性可在检索后从 R2/D1/KV 拉取全文再喂给模型具体见 vectorize/patterns.md。平台限制与成本优化平台限制一览继承自 README.md限制项免费额度付费套餐Neurons/天10,000按量付费速率限制随模型而异更高联系支持上下文窗口视模型而定2K-8K相同流式输出✅ 支持✅ 支持Function Calling✅ 支持部分模型✅ 支持定价免费额度 10,000 neurons/天超出后按实际消耗的神经元计费随模型而异。神经元成本对照来自 patterns.md 与 gotchas.md任务类型模型Neurons/请求分类cf/mistral/mistral-7b-instruct-v0.1~50聊天cf/meta/llama-3.1-8b-instruct~200复杂任务cf/meta/llama-3.1-70b-instruct~2000Embeddingscf/baai/bge-base-en-v1.5~10图像生成Stable Diffusion XL 等10,000成本优化要点按任务选最小可用模型能 8B 解决的不要上 70B例如用cf/meta/llama-3.1-8b-instruct替代 70B批量 Embeddings单次请求传入多个文本text: textsArray一次调用完成多段向量化patterns.md流式输出长响应降低感知延迟api.md接受冷启动首次请求约 13 秒后续约 100500ms对高频 prompt 可借助 AI Gateway 缓存gotchas.md。工程实战模式重试、回退与并行错误处理与指数退避重试针对 7505 限流错误实现重试patterns.mdasync function runWithRetry(env, model, input, maxRetries 3) { for (let attempt 0; attempt maxRetries; attempt) { try { return await env.AI.run(model, input); } catch (error) { if (error.message?.includes(7505) attempt maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, attempt) * 1000)); continue; } throw error; } } }模型回退Fallback高成本模型失败时回退到低成本模型patterns.mdtry { return await env.AI.run(cf/meta/llama-3.1-70b-instruct, { messages }); } catch { return await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages }); }Prompt 模式System Prompt 与 Few-shot// System prompts const PROMPTS { json: Respond with valid JSON only., concise: Keep responses brief., cot: Think step by step before answering. }; // Few-shot 示例 messages: [ { role: system, content: Extract as JSON }, { role: user, content: John bought 3 apples for $5 }, { role: assistant, content: {name:John,item:apples,qty:3} }, { role: user, content: actualInput } ]并行执行同一请求内并行执行多个独立任务patterns.mdconst [sentiment, summary, embedding] await Promise.all([ env.AI.run(cf/mistral/mistral-7b-instruct-v0.1, { messages: sentimentPrompt }), env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: summaryPrompt }), env.AI.run(cf/baai/bge-base-en-v1.5, { text }) ]);常见坑位与排查指南Gotchas关键警告cloudflare/ai包已弃用不要安装cloudflare/ai包请使用原生 Bindinggotchas.md// ❌ 错误 - 不要安装 cloudflare/ai import Ai from cloudflare/ai; // ✅ 正确 - 使用原生 binding export default { async fetch(request: Request, env: Env) { await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [...] }); } }常见问题速查表问题原因与修复本地 AI 不工作本地无模型权重使用wrangler dev --remoteenv.AI is undefinedwrangler.jsonc缺少ai绑定配置类型Ai未找到安装cloudflare/workers-types输出为空检查上下文限制2K-8K tokens校验输入结构输出不一致设置temperature: 0获得确定性输出冷启动延迟首次请求 1-3s 属正常高频 prompt 使用 AI Gateway 缓存Embedding 返回结构差异不同模型返回结构可能不同bge-base-en-v1.5返回{ data: [[0.1, 0.2, ...]] }取向量时使用response.data[0]gotchas.md。推荐的类型定义interface TextGenerationResponse { response: string; } interface EmbeddingResponse { data: number[][]; shape: number[]; }多模型统一管理与推荐阅读顺序多模型配置模板将常用模型集中管理便于切换与维护configuration.mdconst MODELS { chat: cf/meta/llama-3.1-8b-instruct, embed: cf/baai/bge-base-en-v1.5, image: cf/stabilityai/stable-diffusion-xl-base-1.0 };开发工作流命令汇总# 本地开发AI 必须 --remote wrangler dev --remote # 部署到生产 wrangler deploy # 查看模型目录在 Cloudflare 官方文档核对模型 ID 与参数配套文档阅读路径Workers AI 参考文档按主题拆分为四份按需取用configuration.md — wrangler.jsonc 配置、TypeScript 类型、Bindings、环境变量与 RAG 配置api.md —env.AI.run()全量用法、流式、Function Calling、REST API、响应类型与错误码patterns.md — RAG 与 Vectorize 集成、Prompt 工程、批处理、错误处理与缓存gotchas.md — 已弃用包、限流、定价、常见错误排查。推荐路径快速开始本文→ 首次配置读 configuration.md → 选模型用上文的决策树 → 深入调用读 api.md → 构建 RAG 读 patterns.md → 成本与排错读 gotchas.md。关联生态Workers AI 常与以下平台服务组合使用见 README.mdvectorize — 向量数据库承载 RAG 检索ai-gateway — 为 AI 请求提供缓存、限流与分析workers — Worker 运行时与 fetch handler 模式。至此从模型选型、Binding 配置、三类调用方式、核心 API、RAG 落地到成本与排错你已具备在 Cloudflare 边缘网络上线 AI 推理能力的完整工具箱。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考