用 Cloudflare Edge 之力，让 PDF 开口说话

想象一个场景：深夜，律师王某在处理一份 200 页的并购合同。传统方式是 Ctrl+F 一个词一个词地搜，效率低下且容易遗漏关联条款。而现在，他只需要打开浏览器，上传 PDF，问一句"这份合同的主要风险点有哪些"——3 秒钟内， AI 基于合同全文给出精准答案。这就是 cloudflare-rag 正在做的事情：让 PDF 等文档成为可对话的知识库，而它运行的载体，是全球分布的 Cloudflare Edge 网络。

背景：RAG 为什么需要新基建

RAG（Retrieval Augmented Generation，检索增强生成）是当前大模型应用的主流架构，核心思想是在回答用户问题前，先从外部知识库中检索相关片段，再交给 LLM 生成答案。传统 RAG 系统通常部署在 AWS/GCP/Azure 等中心云上，冷启动成本高、延迟受地域影响大。

Cloudflare RAG 的作者 Rafal Wilinski 敏锐地看到了 Edge 计算的机会：将 RAG 的检索和生成都搬到 Cloudflare 全球 300+ 个边缘节点上，用户无论身在何处，都能获得低延迟的文档问答体验。项目最早于 2024 年 8 月开源，迅速获得了 RAG 开发者社区和 Cloudflare 官方生态团队的广泛关注。

核心架构：四层 RAG + Hybrid Search

cloudflare-rag 的技术架构值得深入拆解。它采用了**混合检索（Hybrid Search）**策略，同时融合两种检索方法：

稀疏检索层：Cloudflare D1 + BM25 —— D1 是 Cloudflare 的 SQLite 边缘数据库，在此之上用 BM25（经典文本检索算法）做全文搜索。BM25 擅长精确关键词匹配，适合查找包含特定术语的段落。

稠密检索层：Cloudflare Vectorize —— 将文档切块后用嵌入模型生成向量，存入 Vectorize 向量数据库。用户查询同样转为向量，通过余弦相似度在向量空间中找到语义最相似的文档块。Vectorize 支持元数据索引，可按 session_id 隔离不同用户的文档。

查询改写（Query Rewriting） 是这个项目的一个亮点。当用户输入一个问题时，系统先用 LLM 将其改写为 5 个不同角度的查询（这一步由 Groq 的 llama-3.1-8b-instant 模型完成），再同时执行稀疏和稠密检索，最后融合结果。这一步显著提升了检索召回率——一个模糊的问题往往在改写后能找到更多相关片段。

生成层 支持多 LLM 提供商的 fallback 机制：优先用 Groq（免费、低延迟），若无 API Key 则降级到 Cloudflare Workers AI（内置 llama-3.1-8b-instruct），还可切换 OpenAI GPT-4o-mini 或 Anthropic Claude。所有 LLM 调用都经过 Cloudflare AI Gateway，支持请求级别的负载均衡和重试。

文档处理：PDF 到向量的完整流水线

当用户上传一个 PDF 文件时，后端执行以下流水线：

1. 上传：文件通过 Cloudflare Pages 的 API 端点接收，存入 R2 对象存储，生成唯一 R2 URL。
2. 解析：使用 unpdf（Node.js PDF 解析库，在 Worker 内运行，无需外部 OCR 服务）提取 PDF 全文文本。
3. 切分：用 LangChain 的 RecursiveCharacterTextSplitter 将长文本按重叠方式切成 500 字符的块（chunk），每个块附带 session_id 元数据。
4. 向量化：每个文本块通过 @cloudflare/ai-utils 的嵌入接口（bge-large-zh-v1.5 模型，1024 维向量）生成向量，存入 Vectorize 索引。
5. 入库：原始文本块和元数据存入 D1 SQLite 数据库，与 Vectorize 中的向量记录一一对应。

前端：Remix + TypeScript 构建的对话界面

前端采用 Remix 框架（React 全栈框架），部署在 Cloudflare Pages 上。关键文件包括：

• app/routes/_index.tsx：主对话页面，接收用户问题，调用 /api/stream SSE 端点接收流式响应。
• app/components/fileUpload.tsx：拖拽式文件上传组件，支持 PDF、TXT 等格式。
• app/lib/aiGateway.ts：封装了 Workers AI、Groq、OpenAI、Anthropic 四种 LLM 调用，统一接口，支持 stream 模式。

流式响应通过 Server-Sent Events（SSE）实现——LLM 每生成一个 token，就实时推送至前端显示，用户无需等待完整回答，体验接近 ChatGPT。

部署体验：复杂度高，但有章可循

deploy 到 Cloudflare RAG 并非"一键启动"。官方提供了 setup.sh 脚本，依次创建 Vectorize 向量索引（1024 维，euclidean 度量）、R2 存储桶、D1 数据库和 KV 命名空间。然后需要手动将返回的 ID 填入 wrangler.toml，再配置 .dev.vars 中的 API Key。

完成后，通过 npm run deploy 部署到 Cloudflare Pages，或直接点击 README 中的 "Deploy to Cloudflare Workers" 按钮，理论上可实现 GitHub 代码到生产环境的直达。

值得注意的是，项目使用了 Cloudflare Smart Placement（在 wrangler.toml 中配置 mode = "smart"），系统会自动将 Worker 调度到距离数据最近的边缘节点，这是 Cloudflare 区别于传统 CDN 的一个高级特性。

技术栈全景

局限与注意事项

首先，部署复杂度不可忽视。对于没有 Cloudflare 使用经验的用户，理解 D1/Vectorize/R2/KV 的关系本身就是一道门槛。官方 Demo（cloudflare-rag.pages.dev）可以体验，但绕不开账号配置。

其次，Vectorize 向量数据库有免费额度和查询限制。Cloudflare 的免费计划每月有请求次数上限，高频使用场景需要付费计划。

第三，项目没有 Docker 支持，无法在本地通过 docker-compose 模拟完整的 Cloudflare 基础设施。开发者调试依赖 Cloudflare 沙箱环境。

第四，PDF 解析依赖 unpdf，对扫描版 PDF（图片文字）支持有限，仍需配合 OCR 流程才能完整提取。

行业意义

cloudflare-rag 代表了一个重要趋势：边缘优先的 AI 应用架构。传统 AI 应用往往受限于中心云的地理位置，而 Cloudflare 拥有全球最广泛的边缘节点网络（约 300+ 个数据中心），将 LLM 推理和向量检索下沉到边缘，可以实现亚秒级响应——这对用户体验至关重要。

项目代码结构清晰、文档完整，对于想学习 Cloudflare Workers AI 生态、或者需要快速搭建企业内部文档问答系统的团队，有很高的参考价值。特别推荐其混合检索 + 查询改写的设计模式，可以直接迁移到其他 RAG 实现中。