@freeCodeCamp: 很多RAG教程在本地运行没问题，但一旦尝试部署就会出问题。在这本手册中，@dannwaneri 教你…

很多 RAG 教程在本地运行良好，但当你尝试部署时就会出问题。在本手册中，@dannwaneri 将教你如何使用 Cloudflare Workers、Vectorize 和 Workers AI 构建一个生产级 RAG 系统。你还会学到如何处理加载、查询、错误处理和性能问题，同时保持低成本。https://freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/… — # 如何使用 Cloudflare Workers 构建生产级 RAG 系统——开发者手册 来源：https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/ 大多数 RAG 教程只会展示一个可用的 demo，然后就收工了。你复制代码，它在本地运行，但当你试图投入生产时，一切就崩溃了。本教程不同。我运行着一个生产级 RAG 系统（vectorize-mcp-worker (https://github.com/dannwaneri/vectorize-mcp-worker)），它处理真实流量，总成本仅为 5 美元/月。而我评估过的替代方案价格从 100 美元到 200 美元/月不等。这之间的差别不是魔法，而是架构。在这里，你将构建 rag-tutorial-simple：一个干净、极简的 RAG 聊天机器人，部署在 Cloudflare Workers 上。无需外部 API 密钥，无需付费的向量数据库订阅，无需管理服务器。只需 Cloudflare 的免费套餐——Workers、Vectorize 和 Workers AI——在边缘完成繁重工作。 ## 目录 1. 你将构建什么 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-what-you-will-build) 2. 前置条件 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-prerequisites) 3. RAG 的工作原理 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-how-rag-works) 4. 如何设置项目 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-how-to-set-up-your-project) 5. 如何构建数据管道 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-how-to-build-the-data-pipeline) 6. 如何构建查询管道 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-how-to-build-the-query-pipeline) 7. 如何添加错误处理和安全 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-how-to-add-error-handling-and-security) 8. 性能与成本分析 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-performance-and-cost-analysis) 9. 结论 (https://www.freecodecamp.org/news/build-a-production-rag-system-with-cloudflare-workers-handbook/#heading-conclusion) ## 你将构建什么 完成本教程后，你将拥有一个全局部署的 RAG API，它能够： - 通过 HTTP 接收自然语言问题 - 使用 Workers AI 将其转换为向量嵌入 - 搜索存储在 Cloudflare Vectorize 中的知识库 - 将检索到的上下文传递给 LLM（同样基于 Workers AI）以生成答案 - 返回基于事实、准确的响应（而非幻觉） 完整源代码可在 github.com/dannwaneri/rag-tutorial-simple (https://github.com/dannwaneri/rag-tutorial-simple) 获取。 ## 前置条件 这是一个中级教程。你需要熟悉： - JavaScript/TypeScript：async/await、promise、基本类型 - HTTP API：REST、请求/响应、JSON - 命令行基础：运行 npm 命令、导航目录 你需要： - Node.js 18 或更高版本：通过 node --version 检查 - 一个 Cloudflare 账户：免费套餐即可，在 cloudflare.com (https://dash.cloudflare.com/sign-up) 注册 - 一个代码编辑器：推荐 VS Code 以获得 TypeScript 支持 就这样。没有 OpenAI 密钥，没有用于嵌入的信用卡。开始构建吧。 ## RAG 的工作原理 在编写任何代码之前，你需要对你构建的内容有一个清晰的思维模型。本节解释 RAG 系统的三个核心组件、数据如何在它们之间流动，以及为什么这种架构能够大规模运行。 ### 思维模型 把传统 LLM 想象成一位学医多年的医生，但自从毕业那天起就一直待在一个没有互联网的偏远小屋里。他们很聪明，但只知道毕业时掌握的知识。如果你问他们去年批准的药物，他们要么说不知道，要么——更糟——自信地给出错误信息。 RAG 给那位医生提供了一间最新的医学图书馆。在回答你的问题之前，他们可以查找相关页面、阅读它们，并利用这些信息给出准确的答案。他们的训练仍然重要（即他们知道如何阅读和解释信息），但他们不再局限于多年前记住的内容。 从技术角度看，RAG 在每次请求中分三步工作： 1. 检索：从知识库中找到最相关的文档 2. 增强：将这些文档作为上下文添加到 LLM 提示中 3. 生成：让 LLM 利用其训练和检索到的上下文生成答案 ### 三个组件 每个 RAG 系统都有三个活动部件。理解每一个将帮助你调试问题并在构建过程中做出更好的架构决策。 #### 嵌入模型 嵌入模型将文本转换为向量——一个表示该文本含义的数字数组。在本教程中你将使用的模型 @cf/baai/bge-base-en-v1.5 会为任何给定的文本输出 768 个数字。 嵌入的关键特性是：语义相似的文本会产生数值相似的向量。“How do I install Node.js?” 和 “What’s the process for setting up Node?” 会产生彼此靠近的向量。“How do I install Node.js?” 和 “What is the capital of France?” 会产生相距很远的向量。这就是语义搜索成为可能的原因。你不是在匹配关键词，而是在匹配含义。 有一条规则你绝不能打破：你的文档和你的查询必须使用相同的模型进行嵌入。如果你用 bge-base-en-v1.5 嵌入文档，而用不同的模型嵌入查询，向量将无法比较，你的搜索将返回垃圾结果。 #### 向量数据库 向量数据库存储你的嵌入，并让你能够通过相似度进行搜索。在本教程中，你将使用 Cloudflare Vectorize。当你运行相似度搜索时，你传入一个查询向量，Vectorize 返回它存储的 K 个最相似的向量，以及它们的元数据和相似度分数。这被称为近似最近邻搜索，Vectorize 经过优化即使面对数百万个向量也能快速完成。 与使用外部向量数据库（如 Pinecone）相比，使用 Vectorize 的关键优势在于共置。Vectorize 运行在与你 Worker 相同的 Cloudflare 网络中。没有外部 API 调用，没有身份验证往返，也没有应用程序与数据库之间的网络延迟。 #### 语言模型 LLM 只负责一件事：读取检索到的上下文并生成自然语言答案。它不搜索任何东西，也不判断什么是相关的。它只是读取你给它的内容并写一个响应。 这种关注点分离是刻意的。LLM 擅长语言：理解问题、综合信息、清晰写作。向量数据库擅长检索：快速找到相关文档。RAG 结合了它们的优势，而不要求任何一个组件去做它并非设计用于的任务。 在本教程中，你将通过 Workers AI 使用 @cf/meta/llama-3.3-70b-instruct-fp8-fast。无需 API 密钥。 ### 关于视觉嵌入的说明 如果你计划将这个系统扩展到搜索图像，你可能会想使用像 CLIP 这样的视觉语言模型来生成视觉嵌入（表示图像本身而非其文字描述的向量）。这听起来很聪明，但在实践中对 RAG 效果更差。 视觉嵌入匹配像素相似性。它们擅长“找到看起来像这张图片的图片“。它们不擅长“找到登录屏幕“或“找到显示错误率的仪表板“，因为那些查询是关于含义的，而不是关于像素的。 更好的方法——已在生产中使用——是通过多模态模型（如 Llama 4 Scout）传递图像，该模型生成详细的文本描述并通过 OCR 提取可见文本。然后你使用与其它文档相同的 BGE 模型嵌入那个描述。结果位于一个统一的索引中，与你现有的查询管道兼容，并为 RAG 用例产生比视觉嵌入更好的搜索结果。 Cloudflare Workers AI 目前不支持 CLIP。但即使支持，描述在语义搜索方面也会优于它。 ### 查询如何在系统中流动 以下是当用户向你的成品 Worker 发送问题“What is RAG?“时发生的精确过程： 1. 第 1 步——嵌入问题（20-30ms）：你的 Worker 使用问题文本调用 Workers AI。嵌入模型返回一个 768 维的向量，表示问题的含义。 2. 第 2 步——搜索 Vectorize（30-50ms）：你的 Worker 将该向量传递给 Vectorize，Vectorize 搜索你的知识库并返回 3 个最相似的文档及其相似度分数。 3. 第 3 步——过滤并构建上下文（< 1ms）：相似度分数低于 0.5 的文档被丢弃。剩余的文档文本被合并成一个上下文字符串。 4. 第 4 步——生成答案（500-1500ms）：你的 Worker 将上下文和问题发送给 LLM。LLM 读取上下文并生成基于事实的答案。 5. 第 5 步——返回给用户：答案和来源元数据以 JSON 形式返回。 总时间：通常端到端 600-1600ms。LLM 生成步骤占主导地位。其他一切都很快速。 ### 为什么这能大规模工作 对 Cloudflare RAG 的一个常见反对意见是它无法满足亚 200ms 的检索需求。这种反对源于一个特定的架构错误：试图在单个同步请求中运行整个 RAG 管道，包括繁重的嵌入生成和重排序。那是错误的架构。 你在本教程中构建的架构将加载步骤（较慢，只运行一次）与查询步骤（快速，每次请求都运行）分开。当用户提出问题时，你的文档已经被嵌入并存储。查询管道只需要嵌入问题、运行一次向量搜索并调用 LLM。这三个步骤很快。 我的生产系统（vectorize-mcp-worker (https://github.com/dannwaneri/vectorize-mcp-worker)）运行这种架构，并以 5 美元/月的成本处理真实流量。完整的性能分析在这里 (https://dev.to/dannwaneri/i-built-a-production-rag-system-for-5month-most-alternatives-cost-100-200-21hj)。Cloudflare RAG 是可行的。你只需要正确地构建它。 ## 如何设置项目 在本节中，你将搭建一个 Cloudflare Worker，创建一个 Vectorize 索引来存储你的嵌入，并配置将它们连接在一起的绑定。 ### 如何创建项目 打开终端并为项目创建一个新目录。 在 Mac/Linux 上： mkdir rag-tutorial-simple && cd rag-tutorial-simple 在 Windows PowerShell 上： mkdir rag-tutorial-simple cd rag-tutorial-simple 然后运行 Cloudflare 脚手架工具： npm create cloudflare@latest 按如下方式回答提示： - 目录/应用名称：rag-tutorial-simple - 你想从哪里开始？ Hello World 示例 - TypeScript？ 是 - 部署？ 否 完成后，你将拥有一个可用的 TypeScript Worker，并且 Wrangler 已经配置好。 ### 如何创建 Vectorize 索引 Vectorize 是 Cloudflare 的向量数据库。它与你的 Worker 位于同一网络中，因此搜索时没有外部 API 调用，也没有额外延迟。 npx wrangler vectorize create rag-tutorial-index --dimensions=768 --metric=cosine 这里需要注意两件事。--dimensions=768 告诉 Vectorize 每个嵌入由多少个数字组成。这必须与你使用的嵌入模型的输出匹配。你将使用的模型（@cf/baai/bge-base-en-v1.5）输出 768 维。如果这个数字不匹配，你的搜索将失败。 --metric=cosine 是 Vectorize 测量向量之间相似度的方式。余弦相似度测量两个向量之间的角度，而不是它们之间的距离。对于文本嵌入，这比其他指标更准确地捕捉语义含义。 ### 如何配置 wrangler.toml 打开 wrangler.toml 并将其内容替换为以下内容： name = "rag-tutorial-simple" main = "src/index.ts" compatibility_date = "2026-02-25" [[vectorize]] binding = "VECTORIZE" index_name = "rag-tutorial-index" [ai] binding = "AI" [[vectorize]] 块将你的 Worker 连接到你刚刚创建的索引。[ai] 块让你的 Worker 能够访问 Workers AI——既用于生成嵌入，也用于运行生成答案的语言模型。 注意这里没有任何 API 密钥。Cloudflare 在内部处理身份验证，因为一切——你的 Worker、Vectorize 和 Workers AI——都在同一个账户下运行。 ### 如何更新 src/index.ts 打开 src/index.ts 并将生成的代码替换为： export interface Env { VECTORIZE: VectorizeIndex; AI: Ai; LOAD_SECRET: string; } export default { async fetch(request: Request, env: Env): Promise<Response> { return new Response("RAG tutorial worker is running", { status: 200 }); }, }; Env 接口告诉 TypeScript 你的 Worker 中有哪些绑定可用。VectorizeIndex 和 Ai 是 Cloudflare 类型定义提供的类型。 ### 如何验证你的设置 启动本地开发服务器： npx wrangler dev 打开浏览器并访问 http://localhost:8787。你应该看到： RAG tutorial worker is running 你会在终端中看到两个警告。两者都是预期的。第一个警告说 Vectorize 不支持本地模式。这意味着 Vectorize 查询在本地开发期间无法工作，除非使用 --remote 标志运行。你将在稍后测试完整管道时这样做。 第二个警告说 AI 绑定始终访问远程资源。这意味着即使是在本地开发中，嵌入生成和 LLM 调用也会始终访问 Cloudflare 的服务器。这没问题：在免费套餐限制内的使用不产生任何费用。 此时你的项目结构： rag-tutorial-simple/ ├── scripts/ │ └── knowledge-base.ts ├── src/ │ └── index.ts ├── wrangler.toml ├── package.json └── tsconfig.json ## 如何构建数据管道 数据管道负责两件事：为知识库中的每个文档生成嵌入，并将这些嵌入存储到 Vectorize 中。你将在 Worker 内部通过一个 /load 端点来处理这两个步骤。这种方法有一个关键优势：你不需要 API 令牌、账户 ID 或任何外部工具。一切使用你在 wrangler.toml 中已经配置的绑定。 ### 如何创建知识库 在项目中创建一个 scripts/ 文件夹并添加一个名为 knowledge-base.ts 的文件： mkdir scripts 将你的文档添加到 scripts/knowledge-base.ts： `` export const documents = [ { id: “1”, text: “Cloudflare Workers run JavaScript at the edge, in over 300 data centers worldwide. Requests are handled close to the user, reducing latency significantly compared to a single-region server.”, metadata: { source: “cloudflare-docs”, category: “workers” }, }, { id: “2”, text: “Vectorize is Cloudflare’s vector database. It stores embeddings an