企业官网建设流程全解析

Workers AI 实战模式全解析：从 RAG、SSE 流式到错误重试与成本优化

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

导读

本文是 Cloudflare Workers AI 服务端推理实战的模式速查手册，完整覆盖在 Cloudflare Workers 中构建 AI 应用时最常用的 7 类代码模式：RAG 检索增强生成、SSE 流式响应、错误处理与指数退避重试、模型回退、提示词工程、并行执行以及成本优化。读完本文，你将获得一套可直接复制、可组合进自己 Worker 项目的 TypeScript 实现方案，并理解每个模式背后的平台机制（GPU 冷启动、神经元计费、Vectorize 向量检索约束等）。

模式总览与适用场景

Workers AI 通过原生 binding 在 Worker 边缘运行时上提供 GPU 推理，无需外部 API 调用。其运行形态决定了以下现实约束，也构成了各类模式的出发点（依据见 workers-ai/README.md）：

• 冷启动：模型首次请求加载耗时 1～3 秒，后续请求约 100～500ms；
• 按神经元计费：不同模型每次推理消耗的 neurons 差异巨大（从嵌入的 ~10 到图像生成的 ~10,000+）；
• 速率限制：命中后返回错误码7505，需要重试策略；
• 上下文窗口：2K～8K token 不等，超出即报7506。

因此，一套健壮的 Workers AI 应用，几乎必然同时用到本文的多个模式：用 RAG 补足上下文与事实准确性、用 SSE 提升首字节体验、用重试与回退保证可用性、用并行与批量控制成本。下面是每个模式的完整实现。

RAG：检索增强生成

RAG（Retrieval-Augmented Generation）是在上下文超出模型窗口或需要基于私有语料作答时的首选方案。在 Cloudflare 技术栈中，RAG 由Workers AI（嵌入 + 生成）+ Vectorize（向量检索）两个产品协作完成（vectorize/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 } ] });

关键细节：data[0]与响应结构

• 嵌入模型@cf/baai/bge-base-en-v1.5的返回结构为{ data: number[][], shape: number[] }，查询时传入data[0]而不是data或整个响应对象（vectorize/patterns.md、gotchas.md）。传入错误对象会导致 Vectorize 查询失败或维度不匹配。
• returnMetadata的取值与性能关系（vectorize/api.md）："none"（最快）→"indexed"（推荐，topK 可达 100）→"all"（topK 上限降至 20）。
• 需要「先嵌入文档再入库」时，务必保持嵌入模型与查询时一致（维度一致性是硬约束）：@cf/baai/bge-small-en-v1.5为 384 维，bge-base-en-v1.5为 768 维，bge-large-en-v1.5为 1024 维。

RAG 与直接生成怎么选

依据 workers-ai/README.md 的决策树：

• 用 RAG：回答特定文档/数据的问题、需要已知语料上的事实准确性、上下文超过模型窗口（>4K tokens）、构建知识库聊天；
• 用直接生成：创意写作/头脑风暴、通用知识问答、小上下文可放入提示词（<4K tokens）、以及成本敏感场景（RAG 会额外叠加嵌入与向量检索成本）。

进阶：从向量结果取全文

向量库里存的是截断/摘要元数据时，可先用returnMetadata拿到引用 key，再回源拉取完整文档（R2/D1/KV）拼入上下文，这是生产级 RAG 的常见变体：

const docs = await Promise.all(results.matches.map(m => env.R2.get(m.metadata.key).then(o => o?.text()) ));

Streaming：SSE 流式输出

文本生成类模型支持stream: true，返回一个可异步迭代的流。把模型输出逐 chunk 转发为Server-Sent Events（SSE），可以显著降低用户感知的首字节延迟——不必等全文生成完毕再一次性返回（api.md 也提到「Stream long responses - reduce perceived latency」）。

const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages, stream: true }); const { 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' } });

要点拆解：

1. stream: true后env.AI.run返回的是ReadableStream（gotchas.md），每个 chunk 形如{ response: "..." }，可通过chunk.response取增量文本；
2. TransformStream做背压桥接：上游模型流与下游 HTTP Response 之间通过 writer/reader 连接，模型生成速度慢于网络发送时不会丢数据；
3. SSE 帧协议：每条消息以data:前缀 + JSON + 两个换行\n\n结束，结束信号用data: [DONE]（OpenAI 兼容约定）；
4. 必须设置Content-Type: text/event-stream，否则浏览器端EventSource无法解析。

简化的直接转发写法（不拆帧，直接透传）也成立：

const stream = await env.AI.run(model, { messages, stream: true }); return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });

注意：AI Gateway 的响应缓存不支持流式（ai-gateway/features.md），流式场景不要依赖网关缓存。

错误处理与重试：指数退避

Workers AI 的错误码体系（api.md）：

其中7505是唯一值得自动重试的瞬时错误。官方推荐模式是对它做指数退避重试：

async 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; } } }

设计要点：

• 只重试可恢复错误：7502（模型不存在）、7504（输入校验失败）、7506（上下文超限）属于确定性错误，重试无意义，应立即抛出；
• 退避节奏：第 0 次失败等 1s（2^0×1000），第 1 次等 2s，第 2 次等 4s……用Math.pow(2, attempt) * 1000实现；attempt < maxRetries - 1保证最后一次失败不再等待而是直接抛出；
• 可进一步结合 ai-gateway 的速率限制功能在入口侧削峰，从源头减少 7505 的出现。

模型回退：用容量换可用性

当高规格模型不可用时，降级到小模型保证服务不中断。这是可用性模式，与大模型选型决策树（README.md）配套：70B 模型质量最好但昂贵，8B 均衡，7B Mistral 最快最便宜。

try { 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 }); }

落地建议：

• 可以扩展到多级回退链（70B → 8B → 7B），每级降一档；
• 捕获范围可以更精细：只有 7505 类瞬时错误才触发回退，模型名拼写错误不应回退（可参照上文runWithRetry的错误分类思路）；
• 从 gotchas.md 的成本角度看，70B 单次可达 ~2000 neurons，8B 约 ~200，回退本身也是成本保护伞。

提示词模式：System Prompt 与 Few-shot

常用 System Prompt 模板

把高频指令抽成常量对象，便于统一管理与切换策略：

// System prompts const PROMPTS = { json: 'Respond with valid JSON only.', concise: 'Keep responses brief.', cot: 'Think step by step before answering.' };

• json：强制结构化输出，配合下游JSON.parse使用；
• cot（Chain-of-Thought）：引导模型先推理再作答，适合复杂推理题；
• 追求确定性时给生成参数设temperature: 0（gotchas.md 指出这是消除「响应不一致」的手段）。

Few-shot：给模型示范

在messages中穿插「问题 → 理想答案」示例，让模型模仿输出格式。这是让 LLM 输出严格结构化的最可靠手段之一：

// 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 } ]

结合 api.md 的说明，messages数组可含system/user/assistant三种角色，并支持temperature（0～1）与max_tokens参数，生成的文本在response字段。

进阶：函数调用（Function Calling）

对于需要「结构化工具调用」而非纯文本的场景，Workers AI 支持tools参数（仅@cf/meta/llama-3.1-*与mistral-7b-instruct-v0.2等少数模型原生支持，见 gotchas.md）：

const response = await env.AI.run(model, { messages, tools: [ { type: 'function', function: { name: 'getWeather', parameters: { ... } } } ]}); if (response.tool_calls) { const args = JSON.parse(response.tool_calls[0].function.arguments); // 执行函数后把结果作为 assistant 消息回传 }

并行执行：一次请求搞定多任务

Workers AI 的每次run是独立的推理请求，多个独立任务可用Promise.all并发执行，避免串行等待累计延迟：

const [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 }) ]);

适用场景与注意事项：

• 典型用例：同一篇内容同时做情感分析、摘要抽取、向量嵌入入库，一次请求并发完成三类产出；
• 混用模型是故意的：小任务（情感分类）用便宜的小模型，生成任务用质量模型，嵌入用专门的嵌入模型——与成本优化模式天然互补；
• 不要并行执行有依赖关系的调用；并发上限受套餐速率限制约束，批量任务过重时仍需配合节流（可参考 vectorize/api.md 中「每批 500 条」的分批思路）。

成本优化：神经元预算的工程化

Workers AI 按神经元（neurons）计费，免费额度为每天 10,000 neurons（README.md）。各任务类型典型消耗（patterns.md 与 gotchas.md 综合）：

从这张表可以得出几条可操作的省钱原则：

1. 按任务匹配模型：分类用 ~50 的 Mistral 7B，别用 ~2000 的 70B；「用能满足需求的最小模型」（gotchas.md 原话：「Use smallest that works」）；
2. 嵌入成本极低，但量级大：RAG 管线的每次文档入库、每次查询都产生嵌入调用，单次虽仅 ~10 neurons，累计起来不容忽视；
3. 批量嵌入一次处理多段文本，用一次调用代替多次：

// Batch embeddings const response = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: textsArray // Process multiple at once });

• 图像生成是成本大头（SDXL 一次约 ~10,000 neurons，几乎耗尽免费额度），非必要慎用（README.md）。

配合外部手段进一步省钱：

• AI Gateway 缓存：对确定性提示词（如常见问候、模板化回答）开启缓存，缓存 TTL 支持 60s～30 天（ai-gateway/features.md）；temperature: 0的请求更容易命中缓存；
• 冷启动意识：首次请求 1～3s、后续 100～500ms（api.md），热模型的重复调用既快又省，避免频繁切换模型打散热缓存。

组合使用：一个完整的模式编排示例

把上述模式串起来，一个「知识库问答 Worker」的典型调用链是：嵌入查询 → Vectorize 检索（RAG）→ 并行做摘要与情绪分析 → SSE 流式返回，全程包裹重试与模型回退：

// 1. 嵌入 + 检索 const emb = await runWithRetry(env, '@cf/baai/bge-base-en-v1.5', { text: query }); const matches = await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: true }); // 2. 构建上下文 const context = matches.matches.map(m => m.metadata?.text).join('\n\n'); // 3. 流式生成（失败则回退到 8B） const model = '@cf/meta/llama-3.1-70b-instruct'; const fallback = '@cf/meta/llama-3.1-8b-instruct'; const stream = await runWithRetry(env, model, { messages: [ { role: 'system', content: `Answer based on:\n\n${context}` }, { role: 'user', content: query } ], stream: true }).catch(() => env.AI.run(fallback, { messages: [{ role: 'user', content: query }], stream: true })); // 4. SSE 转发 const { 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' } });

环境与配置前提

以上所有模式均依赖 Workers AI binding 的正确配置（详见 configuration.md）：

{ "name": "my-ai-worker", "main": "src/index.ts", "compatibility_date": "2024-01-01", "ai": { "binding": "AI" }, "vectorize": { "bindings": [{ "binding": "VECTORIZE", "index_name": "embeddings-index" }] } }

• 本地开发必须wrangler dev --remote：本地无 GPU 推理能力，纯本地模式env.AI不可用（configuration.md）；
• TypeScript 类型：安装@cloudflare/workers-types后，Env接口中声明AI: Ai; VECTORIZE: VectorizeIndex;；
• 不要安装已废弃的@cloudflare/ai包，一律使用原生 bindingenv.AI.run（gotchas.md）；
• 本文所有模式均在 Cloudflare Workers 运行时环境（env.AIbinding）下成立；若在 Worker 之外通过 REST API 调用，对应端点为POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}（api.md）。

相关资源

• workers-ai/README.md — 模型选型决策树、RAG vs 直接生成、平台限制
• workers-ai/api.md —env.AI.run()参数、错误码、性能提示
• workers-ai/configuration.md — wrangler.jsonc 绑定配置
• workers-ai/gotchas.md — 已废弃包警告、限流、定价细节
• vectorize/patterns.md — RAG 集成、批量入库、多租户检索
• vectorize/api.md — 查询/写入 API、过滤运算符、性能权衡
• ai-gateway/features.md — 缓存、限流、日志等网关能力

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills