⚡

CloudflareVectorize向量数据库技能 cloudflare-vectorize

这是一个用于构建语义搜索和检索增强生成（RAG）应用的 Cloudflare Vectorize 技能。它提供了向量数据库管理、嵌入生成、相似性搜索、元数据过滤等功能，适用于基于 Cloudflare Workers 的 AI 驱动应用程序开发。关键词：向量数据库、语义搜索、RAG、AI应用、Cloudflare、嵌入模型、相似性搜索、元数据过滤、Workers AI。

RAG应用 0 次安装 0 次浏览 更新于 3/8/2026

name: cloudflare-vectorize description: Cloudflare Vectorize 向量数据库，用于语义搜索和RAG。适用于向量索引、嵌入、相似性搜索，或遇到维度不匹配、过滤器错误时。 关键词：向量化、向量数据库、向量索引、向量搜索、相似性搜索、语义搜索、 最近邻、knn搜索、ann搜索、RAG、检索增强生成、与数据聊天、 文档搜索、语义问答、上下文检索、bge-base、@cf/baai/bge-base-en-v1.5、 text-embedding-3-small、text-embedding-3-large、Workers AI 嵌入、openai 嵌入、 插入向量、更新向量、查询向量、删除向量、元数据过滤、命名空间过滤、 topK 搜索、余弦相似性、欧几里得距离、点积、wrangler vectorize、元数据索引、 创建向量化索引、向量化维度、向量化度量、向量化绑定 license: MIT

Cloudflare Vectorize

Cloudflare Vectorize 的完整实现指南 - 一个全球分布的向量数据库，用于使用 Cloudflare Workers 构建语义搜索、RAG（检索增强生成）和 AI 驱动的应用程序。

状态: 生产就绪 ✅ 最后更新: 2025-11-21 依赖项: cloudflare-worker-base（用于 Worker 设置）、cloudflare-workers-ai（用于嵌入） 最新版本: wrangler@4.50.0, @cloudflare/workers-types@4.20251014.0 令牌节省: ~65% 预防的错误: 8 节省的开发时间: ~3 小时

这个技能提供什么

核心功能

  • ✅ 索引管理: 创建、配置和管理向量索引
  • ✅ 向量操作: 插入、更新、查询、删除和列出向量
  • ✅ 元数据过滤: 每个索引最多 10 个元数据索引的高级过滤
  • ✅ 语义搜索: 使用余弦、欧几里得或点积度量查找相似向量
  • ✅ RAG 模式: 完整的检索增强生成工作流
  • ✅ Workers AI 集成: 使用 @cf/baai/bge-base-en-v1.5 进行原生嵌入生成
  • ✅ OpenAI 集成: 支持 text-embedding-3-small/large 模型
  • ✅ 文档处理: 文本分块和批量摄取管道

包含的模板

  1. basic-search.ts - 使用 Workers AI 的简单向量搜索
  2. rag-chat.ts - 带有上下文检索的完整 RAG 聊天机器人
  3. document-ingestion.ts - 文档分块和嵌入管道
  4. metadata-filtering.ts - 高级过滤示例

关键设置规则

⚠️ 插入向量前必须执行

# 1. 使用固定维度和度量创建索引
bunx wrangler vectorize create my-index \
  --dimensions=768 \
  --metric=cosine

# 2. 立即创建元数据索引（在插入向量之前！）
bunx wrangler vectorize create-metadata-index my-index \
  --property-name=category \
  --type=string

bunx wrangler vectorize create-metadata-index my-index \
  --property-name=timestamp \
  --type=number

原因: 元数据索引必须在向量插入前存在。在元数据索引创建前添加的向量将无法在该属性上进行过滤。

索引配置（后续无法更改）

# 维度必须匹配嵌入模型输出：
# - Workers AI @cf/baai/bge-base-en-v1.5: 768 维度
# - OpenAI text-embedding-3-small: 1536 维度
# - OpenAI text-embedding-3-large: 3072 维度

# 度量决定相似性计算：
# - cosine: 最适合归一化嵌入（最常见）
# - euclidean: 向量之间的绝对距离
# - dot-product: 用于非归一化向量

Wrangler 配置

wrangler.jsonc:

{
  "name": "my-vectorize-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-21",
  "vectorize": [
    {
      "binding": "VECTORIZE_INDEX",
      "index_name": "my-index"
    }
  ],
  "ai": {
    "binding": "AI"
  }
}

TypeScript 类型

export interface Env {
  VECTORIZE_INDEX: VectorizeIndex;
  AI: Ai;
}

interface VectorizeVector {
  id: string;
  values: number[] | Float32Array | Float64Array;
  namespace?: string;
  metadata?: Record<string, string | number | boolean | string[]>;
}

interface VectorizeMatches {
  matches: Array<{
    id: string;
    score: number;
    values?: number[];
    metadata?: Record<string, any>;
    namespace?: string;
  }>;
  count: number;
}

常见操作

快速参考

操作 方法 关键点
插入 insert([...]) 如果 ID 存在，则保留第一个
更新 upsert([...]) 如果 ID 存在，则覆盖（用于更新）
查询 query(vector, { topK, filter }) 返回相似向量
删除 deleteByIds([...]) 按 ID 数组删除
获取 getByIds([...]) 检索特定向量

过滤操作符

操作符 示例 描述
$eq { category: "docs" } 相等（隐式）
$ne { status: { $ne: "archived" } } 不相等
$in { category: { $in: ["a", "b"] } } 在数组中
$nin { category: { $nin: ["x"] } } 不在数组中
$gte/$lt { timestamp: { $gte: 123 } } 范围查询

📄 完整操作指南: 加载 references/vector-operations.md 以获取完整的插入/更新/查询/删除示例代码。

嵌入生成

模型 提供商 维度 最适合
@cf/baai/bge-base-en-v1.5 Workers AI 768 免费，通用
text-embedding-3-small OpenAI 1536 平衡质量/成本
text-embedding-3-large OpenAI 3072 最高质量

📄 集成指南:

  • 加载 references/integration-workers-ai-bge-base.md 以获取 Workers AI 设置
  • 加载 references/integration-openai-embeddings.md 以获取 OpenAI 集成

元数据最佳实践

关键限制

限制 值
最大元数据索引 每个索引 10 个
最大元数据大小 每个向量 10 KiB
字符串索引 前 64 字节（UTF-8）
过滤器大小 最大 2048 字节

无效键字符

键不能：为空、包含 .（保留用于嵌套）、包含 " 或以 $ 开头。

📄 完整元数据指南: 加载 references/metadata-guide.md 以获取基数最佳实践、嵌套元数据和高级过滤模式。

RAG 模式（完整示例）

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { question } = await request.json();

    // 1. 为用户问题生成嵌入
    const questionEmbedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: question
    });

    // 2. 在向量数据库中搜索相似内容
    const results = await env.VECTORIZE_INDEX.query(
      questionEmbedding.data[0],
      {
        topK: 3,
        returnMetadata: 'all',
        filter: { type: "documentation" }
      }
    );

    // 3. 从检索到的文档构建上下文
    const context = results.matches
      .map(m => m.metadata.content)
      .join('

---

');

    // 4. 使用上下文通过 LLM 生成答案
    const answer = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
      messages: [
        {
          role: "system",
          content: `基于此上下文回答：

${context}`
        },
        {
          role: "user",
          content: question
        }
      ]
    });

    return Response.json({
      answer: answer.response,
      sources: results.matches.map(m => m.metadata.title)
    });
  }
};

文档分块策略

推荐分块大小: 300-500 个字符以保持语义连贯性。

分块的关键元数据:

  • doc_id: 父文档 ID
  • chunk_index: 在文档中的位置
  • content: 用于检索显示的文本

📄 完整分块实现: 参见 templates/document-ingestion.ts 以获取完整的分块管道。

常见错误及解决方案

错误 1: 在向量插入后创建元数据索引

问题: 现有向量上的过滤无效
解决方案: 删除并重新插入向量或在插入前创建元数据索引

错误 2: 维度不匹配

问题: "向量维度与索引配置不匹配"
解决方案: 确保嵌入模型输出匹配索引维度：
  - Workers AI bge-base: 768
  - OpenAI small: 1536
  - OpenAI large: 3072

错误 3: 无效的元数据键

问题: "无效的元数据键"
解决方案: 键不能：
  - 为空
  - 包含 .（点）
  - 包含 "（引号）
  - 以 $（美元符号）开头

错误 4: 过滤器过大

问题: "过滤器超过 2048 字节"
解决方案: 简化过滤器或拆分为多个查询

错误 5: 在高基数字段上进行范围查询

问题: 查询缓慢或准确性降低
解决方案: 对范围查询使用低基数字段，或对时间戳使用秒而不是毫秒

错误 6: 插入与更新混淆

问题: 索引中的更新未反映
解决方案: 使用 upsert() 覆盖现有向量，而不是 insert()

错误 7: 缺少绑定

问题: "VECTORIZE_INDEX 未定义"
解决方案: 在 wrangler.jsonc 中添加 [[vectorize]] 绑定

错误 8: 命名空间与元数据混淆

问题: 不清楚何时使用命名空间与元数据过滤
解决方案:
  - 命名空间: 分区键，在元数据过滤器之前应用
  - 元数据: 在命名空间内的灵活键值过滤

Wrangler CLI 参考

基本命令:

# 创建索引（维度/度量是永久性的）
bunx wrangler vectorize create <name> --dimensions=768 --metric=cosine

# 创建元数据索引（必须在插入向量之前！）
bunx wrangler vectorize create-metadata-index <name> --property-name=category --type=string

# 获取索引信息
bunx wrangler vectorize info <name>

📄 完整 CLI 参考: 加载 references/wrangler-commands.md 以获取所有 vectorize 命令。

性能提示

  1. 批量操作: 以 100-1000 个向量为批次插入/更新
  2. 选择性返回: 仅在需要时使用 returnValues: true（节省带宽）
  3. 元数据基数: 保持索引元数字段为低基数以进行范围查询
  4. 命名空间过滤: 在元数据过滤器之前应用命名空间过滤器（先处理）
  5. 查询优化: 使用 topK=3-10 以获得最佳延迟（较大值增加搜索时间）

何时使用此技能

✅ 使用 Vectorize 当:

  • 构建文档、产品或内容的语义搜索
  • 实现带有上下文检索的 RAG 聊天机器人
  • 创建基于相似性的推荐引擎
  • 构建多租户应用程序（使用命名空间）
  • 需要全球分布和低延迟

❌ 不要使用 Vectorize 用于:

  • 传统关系型数据（使用 D1）
  • 键值查找（使用 KV）
  • 大型文件存储（使用 R2）
  • 实时协作状态（使用 Durable Objects）

何时加载参考

参考文件 加载时机…
references/vector-operations.md 需要完整的插入/更新/查询/删除代码示例
references/metadata-guide.md 设置元数据索引，过滤最佳实践
references/wrangler-commands.md 使用 Vectorize CLI 命令
references/integration-workers-ai-bge-base.md 集成 Workers AI 嵌入
references/integration-openai-embeddings.md 集成 OpenAI 嵌入
references/embedding-models.md 比较嵌入模型选项
references/index-operations.md 索引生命周期管理

模板

模板 用途
templates/basic-search.ts 简单向量搜索
templates/rag-chat.ts 完整 RAG 聊天机器人
templates/document-ingestion.ts 文档分块管道
templates/metadata-filtering.ts 高级过滤

官方文档

版本: 1.0.0 状态: 生产就绪 ✅ 令牌节省: ~65% 预防的错误: 8 个主要类别 节省的开发时间: 每个实现约 2.5 小时