cloudflare-vectorize

Cloudflare Vectorize

Cloudflare Vectorize 完整实现指南——这是一款全球分布式向量数据库，可借助 Cloudflare Workers 构建语义搜索、RAG（检索增强生成）和 AI 驱动的应用。

状态：已可用于生产环境 ✅ 最后更新：2025-11-21 依赖项：cloudflare-worker-base（用于 Worker 设置）、cloudflare-workers-ai（用于嵌入） 最新版本：[email protected]、@cloudflare/[email protected] 节省 Token：约 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. Create the index with FIXED dimensions and metric
bunx wrangler vectorize create my-index \
  --dimensions=768 \
  --metric=cosine

# 2. Create metadata indexes IMMEDIATELY (before inserting vectors!)
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

原因：必须先创建元数据索引，再插入向量。在创建元数据索引之前添加的向量，无法按该属性进行筛选。

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

# Dimensions MUST match your embedding model output:
# - Workers AI @cf/baai/bge-base-en-v1.5: 768 dimensions
# - OpenAI text-embedding-3-small: 1536 dimensions
# - OpenAI text-embedding-3-large: 3072 dimensions

# Metrics determine similarity calculation:
# - cosine: Best for normalized embeddings (most common)
# - euclidean: Absolute distance between vectors
# - dot-product: For non-normalized vectors

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. Generate embedding for user question
    const questionEmbedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: question
    });

    // 2. Search vector database for similar content
    const results = await env.VECTORIZE_INDEX.query(
      questionEmbedding.data[0],
      {
        topK: 3,
        returnMetadata: 'all',
        filter: { type: "documentation" }
      }
    );

    // 3. Build context from retrieved documents
    const context = results.matches
      .map(m => m.metadata.content)
      .join('\n\n---\n\n');

    // 4. Generate answer with LLM using context
    const answer = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
      messages: [
        {
          role: "system",
          content: `Answer based on this context:\n\n${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：在插入向量后创建元数据索引

Problem: Filtering doesn't work on existing vectors
Solution: Delete and re-insert vectors OR create metadata indexes BEFORE inserting

错误 2：维度不匹配

Problem: "Vector dimensions do not match index configuration"
Solution: Ensure embedding model output matches index dimensions:
  - Workers AI bge-base: 768
  - OpenAI small: 1536
  - OpenAI large: 3072

错误 3：元数据键无效

Problem: "Invalid metadata key"
Solution: Keys cannot:
  - Be empty
  - Contain . (dot)
  - Contain " (quote)
  - Start with $ (dollar sign)

错误 4：筛选条件过大

Problem: "Filter exceeds 2048 bytes"
Solution: Simplify filter or split into multiple queries

错误 5：对高基数数据进行范围查询

Problem: Slow queries or reduced accuracy
Solution: Use lower cardinality fields for range queries, or use seconds instead of milliseconds for timestamps

错误 6：混淆插入与 Upsert

Problem: Updates not reflecting in index
Solution: Use upsert() to overwrite existing vectors, not insert()

错误 7：缺少绑定

Problem: "VECTORIZE_INDEX is not defined"
Solution: Add [[vectorize]] binding to wrangler.jsonc

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

Problem: Unclear when to use namespace vs metadata filtering
Solution:
  - Namespace: Partition key, applied BEFORE metadata filters
  - Metadata: Flexible key-value filtering within namespace

Wrangler CLI 参考

基本命令：

# Create index (dimensions/metric are PERMANENT)
bunx wrangler vectorize create <name> --dimensions=768 --metric=cosine

# Create metadata index (MUST be before inserting vectors!)
bunx wrangler vectorize create-metadata-index <name> --property-name=category --type=string

# Get index info
bunx wrangler vectorize info <name>

📄 完整的 CLI 参考：加载 references/wrangler-commands.md 以查看所有 Vectorize 命令。

性能提示

1. 批量操作：每批插入/Upsert 100-1000 个向量
2. 选择性返回：仅在需要时使用 returnValues: true（可节省带宽）
3. 元数据基数：范围查询使用的已索引元数据字段应保持低基数
4. 命名空间筛选：先应用命名空间筛选，再应用元数据筛选（命名空间筛选会先处理）
5. 查询优化：使用 topK=3-10 可获得最佳延迟（更大的值会增加搜索时间）

何时使用此技能

✅ 适用于以下情况：

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

❌ 以下情况不适用：

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

何时加载参考资料

参考文件	加载时机……
references/vector-operations.md	需要完整的插入/Upsert/查询/删除代码示例时
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	高级筛选

安全安装

安装向量数据库包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本——npm config set ignore-scripts true（或使用 Bun：默认禁用）
• 冷却期——等待 7 天，让社区审查新的包版本
• 安装前审计——运行 socket package score npm <pkg> 或使用 socket npm install <pkg> 检查包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

官方文档

• Vectorize 文档
• Workers AI 模型
• RAG 教程

---

版本：1.0.0 状态：可用于生产 ✅ Token 节省：约 65% 预防的错误：8 大类 节省的开发时间：每次实现约 2.5 小时