全栈 Cloudflare RAG

这是一个使用 Cloudflare 构建 RAG（检索增强生成）应用的全栈示例。它利用了 Cloudflare Workers、Pages、D1、KV、R2、AI Gateway 和 Workers AI。

https://github.com/user-attachments/assets/cbaa0380-7ad6-448d-ad44-e83772a9cf3f

演示

特性：

• 每次交互都通过 Server-Sent Events 流式传输到 UI
• 结合 D1 上的全文搜索和 Vectorize 上的向量搜索的混合 RAG
• 使用 AI Gateway 在多个提供商（OpenAI、Groq、Anthropic）之间切换，并提供回退机制
• 通过 Cloudflare 的 KV 实现基于 IP 的速率限制
• OCR 在 Cloudflare Worker 内部运行，使用 unpdf
• 智能部署会自动将您的工作负载放置在最佳位置，以最大限度地减少延迟并加速应用程序

开发

请确保已安装 Node.js、pnpm 和 wrangler CLI。

安装依赖项：

pnpm install # 或 npm install

部署必要的基础组件：

./setup.sh

然后，在 wrangler.toml 中，将 d1_databases.database_id 设置为您的 D1 数据库 ID，将 kv_namespaces.rate_limiter 设置为您的速率限制 KV 命名空间 ID。

接着，创建一个 .dev.vars 文件，填入您的 API 密钥：

CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id # 必需
GROQ_API_KEY=your-groq-api-key # 可选
OPENAI_API_KEY=your-openai-api-key # 可选
ANTHROPIC_API_KEY=your-anthropic-api-key # 可选

如果您没有这些密钥，/api/stream 将回退到 Workers AI。

运行开发服务器：

npm run dev

然后您可以在 http://localhost:5173/ 访问该应用。

部署

在设置好必要的基础组件后，首先配置密钥：

npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put GROQ_API_KEY
npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put ANTHROPIC_API_KEY

然后将您的应用部署到 Cloudflare Pages：

npm run deploy

混合搜索 RAG

该项目结合了对 Cloudflare D1 的经典全文搜索（稀疏）以及对 Vectorize 的嵌入式混合搜索（密集），从而兼得两者之长，为 LLM 提供最相关的上下文。

其工作流程如下：

1. 我们接收用户输入，并使用 LLM 将其改写成 5 个不同的查询。
2. 我们分别在两个数据存储中执行这些查询——在 D1 数据库中使用 BM25 进行全文搜索，在 Vectorize 中进行密集检索。
3. 我们将两个数据存储中的结果合并在一起，使用 Reciprocal Rank Fusion，得到一个统一的结果列表。
4. 然后我们从该列表中选取前 10 条结果，传递给 LLM 生成响应。

许可证

本项目采用 MIT 许可证条款进行授权。

咨询服务

如果您需要帮助构建 AI 应用程序，请通过 Twitter 或我的 网站 联系我。我很乐意为您提供帮助！

Cloudflare RAG 快速上手指南

本指南帮助中国开发者快速部署基于 Cloudflare 全栈技术（Workers, Pages, D1, Vectorize 等）的 RAG（检索增强生成）应用。该方案支持混合搜索（全文 + 向量）、多模型切换及流式输出。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS, Linux 或 Windows (推荐 WSL2)
• 运行时环境：已安装 Node.js (建议 LTS 版本)
• 包管理器：已安装 pnpm (推荐) 或 npm
  • 安装 pnpm: npm install -g pnpm
• Cloudflare CLI：已安装 wrangler
  • 安装命令：npm install -g wrangler
  • 登录认证：运行 wrangler login 并按提示完成浏览器授权
• 网络环境：由于涉及 Cloudflare 服务及外部大模型 API，请确保网络能正常访问 GitHub、Cloudflare Dashboard 及相关 AI 提供商接口。

安装步骤

1. 克隆项目与安装依赖

首先获取源代码并安装项目依赖。国内开发者若遇到 npm/pnpm 源连接缓慢，可临时切换至腾讯云或阿里云镜像源。

git clone https://github.com/RafalWilinski/cloudflare-rag.git
cd cloudflare-rag

# 安装依赖 (推荐使用 pnpm)
pnpm install
# 或者使用 npm
# npm install

2. 初始化基础设施

运行脚本自动创建所需的 Cloudflare 资源（如 D1 数据库、KV 命名空间、Vectorize 索引等）。

./setup.sh

> 注意：Windows PowerShell 用户可能需要运行 sh setup.sh 或将脚本内容手动执行。

3. 配置本地环境变量

脚本执行后，您需要将生成的资源 ID 填入配置文件，并设置 API 密钥。

1. 打开 wrangler.toml 文件：

   • 将 d1_databases.database_id 替换为您实际的 D1 数据库 ID。
   • 将 kv_namespaces.rate_limiter 替换为您实际的 KV 命名空间 ID。

2. 在项目根目录创建 .dev.vars 文件，填入以下信息：

CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id # 必填：Cloudflare 账户 ID
GROQ_API_KEY=your-groq-api-key # 可选：Groq API Key
OPENAI_API_KEY=your-openai-api-key # 可选：OpenAI API Key
ANTHROPIC_API_KEY=your-anthropic-api-key # 可选：Anthropic API Key

提示：如果您未配置上述第三方 API Key，系统将自动降级使用 Cloudflare Workers AI 作为默认推理后端，无需额外付费即可体验基础功能。

基本使用

启动开发服务器

完成配置后，运行以下命令启动本地开发环境：

npm run dev

访问应用

终端显示启动成功后，在浏览器中访问：

http://localhost:5173/

此时您已拥有一个本地运行的 RAG 应用。您可以尝试上传 PDF 文档（系统会自动通过 Worker 进行 OCR 处理），然后针对文档内容进行提问。系统将结合 D1 全文检索和 Vectorize 向量检索，通过流式传输（SSE）返回答案。

部署到生产环境（可选）

若需将应用发布到公网，请按以下步骤操作：

1. 设置生产密钥（将密钥安全地存储在 Cloudflare）：

   npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
   npx wrangler secret put GROQ_API_KEY
   npx wrangler secret put OPENAI_API_KEY
   npx wrangler secret put ANTHROPIC_API_KEY
   

2. 执行部署：

   npm run deploy
   

部署完成后，您将获得一个由 Cloudflare Pages 托管的全球加速域名。