环境准备与依赖安装
在开始构建 RAG 聊天机器人之前，合理的环境配置是确保项目顺利进行的关键。本章将指导您完成所有必要的环境设置，包括 Node.js 和 Wrangler CLI 的安装、各 API 服务的申请与配置，以及 Cloudflare Vectorize 向量数据库的初始化。通过按照本章步骤操作，您将建立起一个完整的开发环境，为后续的开发工作奠定坚实基础。
开发环境要求
为了构建和运行 RAG 聊天机器人，你需要准备以下开发环境：
- Node.js 20 或更高版本
- npm 或 pnpm 作为包管理器
- Cloudflare Wrangler CLI 用于开发和部署
必要的 API 申请
根据你的选择，你需要申请不同的 API 密钥：
千问（Qwen）API 申请步骤：
- 访问阿里云百炼平台
- 注册并完成实名认证
- 开通大模型服务，选择合适的付费方案
- 获取 API Key 和 Base URL
- 记录以下信息：
QWEN_API_KEY: 你的 API 密钥QWEN_BASE: API 基础 URL（通常是https://dashscope.aliyuncs.com/compatible-mode/v1）
Google Gemini API 申请步骤：
- 访问 Google AI Studio
- 登录 Google 账号
- 创建新的 API 密钥
- 记录
GOOGLE_API_KEY
Cloudflare 服务配置
注册和配置 Cloudflare
安装 Wrangler CLI：
npm install -g wrangler登录 Cloudflare：
wrangler login
创建 Vectorize 索引
Vectorize 是 Cloudflare 提供的向量数据库服务，在 RAG 系统中用于存储和检索文档向量。
创建索引时需要考虑以下因素：
- 维度匹配：索引维度必须与所使用的嵌入模型输出维度一致
- 距离度量：根据应用场景选择合适的距离度量方式
- 命名规范：使用描述性的索引名称
# 为千问 text-embedding-v4 模型（1024 维）创建索引
wrangler vectorize create website-rag --dimensions=1024 --metric=cosine
上述命令用于在 Cloudflare Vectorize 服务中创建一个名为 website-rag 的向量索引，适配千问 text-embedding-v4 模型（输出维度为 1024）。各参数说明如下：
website-rag：索引名称，需唯一，用于后续绑定和引用。--dimensions：指定向量的维度，需与所用嵌入模型的输出维度一致（如 text-embedding-v4 为 1024）。--metric：指定向量相似度的计算方式，可选值包括：cosine：余弦相似度（推荐用于文本检索）euclidean：欧氏距离dot-product：点积
text-embedding-v4 模型输出的每个向量就是 1024 维。如果设置为其他数值，将导致存储和检索时维度不匹配，无法正常使用。不同模型的输出维度可能不同，务必查阅模型文档后正确设置。此外，wrangler vectorize create 还支持以下常用参数：
--preset：指定预设的嵌入模型，自动配置维度和距离度量（如openai/text-embedding-ada-002等）。--description：为索引添加描述信息，便于管理。--json：以 JSON 格式输出结果，便于脚本处理。-e, --env：指定环境变量文件或环境名，适用于多环境部署。
完整参数列表可通过 wrangler vectorize create --help 查看。建议根据实际嵌入模型和业务需求合理设置参数，确保索引性能和检索效果。
创建元数据索引
在向量数据库中，元数据（Metadata）是与每个向量一起存储的结构化信息，例如文档的 URL、语言、标签等。元数据本身不是 Cloudflare Vectorize 独有的概念，几乎所有主流的嵌入数据库（如 Pinecone、Weaviate、Milvus 等）都支持为向量附加元数据，并基于元数据进行过滤检索。通过为常用的元数据字段建立索引，可以高效地实现如“按语言筛选”、“按标签过滤”等复杂查询，提升检索的灵活性和性能。
为了支持基于元数据的过滤查询，需要为常用的元数据字段创建索引：
# 为 URL 字段创建元数据索引
wrangler vectorize create-metadata-index website-rag --property-name=url --type=string
# 为语言字段创建元数据索引
wrangler vectorize create-metadata-index website-rag --property-name=language --type=string
# 为标签字段创建元数据索引
wrangler vectorize create-metadata-index website-rag --property-name=tags --type=string
Vectorize 支持最多创建 10 个元数据索引，每个索引支持的类型包括：
string：字符串类型number：数字类型boolean：布尔类型
查看索引信息
创建索引后，可以查看索引的详细信息：
# 查看索引基本信息
wrangler vectorize list
# 查看索引详细信息
wrangler vectorize info website-rag
# 查看元数据索引
wrangler vectorize list-metadata-index website-rag
项目初始化
克隆项目仓库：
git clone https://github.com/rootsongjc/rag-chatbot.git cd rag-chatbot安装 Node.js 依赖：
npm install配置
wrangler.toml，加入你的 API 密钥和 Vectorize 索引配置：name = "website-rag-worker" main = "src/index.ts" compatibility_date = "2024-07-31" [vars] PROVIDER = "qwen" EMBED_DIM = 1024 LLM_MODEL = "qwen-turbo-latest" EMBED_MODEL = "text-embedding-v4" QWEN_API_KEY = "your-qwen-api-key" QWEN_BASE = "https://dashscope.aliyuncs.com/compatible-mode/v1" # 绑定 Vectorize 索引 [[vectorize]] binding = "VECTORIZE" index_name = "website-rag" # 绑定 AI 模型（如果使用 Workers AI） [ai] binding = "AI"
环境变量配置
建议将敏感信息（如 API 密钥）存储在环境变量中，而不是直接写在配置文件里：
# 设置环境变量
export QWEN_API_KEY="your-qwen-api-key"
或在 .dev.vars 文件中配置（仅用于开发环境）：
QWEN_API_KEY=your-qwen-api-key
GOOGLE_API_KEY=your-google-api-key
验证配置
配置完成后，可以通过以下方式验证设置是否正确：
测试 Vectorize 连接：
# 查看索引信息 wrangler vectorize info website-rag测试 Worker 部署：
# 本地开发模式 wrangler dev # 部署到 Cloudflare wrangler deploy创建一个简单的测试脚本来验证嵌入模型是否正常工作。
// test-embedding.ts import { createEmbedding } from './src/embedding'; async function testEmbedding() { try { const testText = "这是一个测试文本"; const embedding = await createEmbedding(testText); console.log(`成功生成嵌入向量，维度：${embedding.length}`); } catch (error) { console.error("嵌入生成失败：", error); } } testEmbedding();
通过以上步骤，你应该能够成功设置 RAG 聊天机器人所需的开发环境，并正确配置 Cloudflare Vectorize 服务。