Cloudflare Vectorize 是一个全球分布式向量数据库，用于构建语义搜索、RAG（检索增强生成）以及基于 Cloudflare Workers 的 AI 应用。本技能文档为完整实现指南，状态为生产就绪，最后更新于 2026-01-21。依赖 cloudflare-worker-base（用于 Worker 设置）和 cloudflare-workers-ai（用于嵌入）。最新版本为 wrangler@4.59.3、@cloudflare/workers-types@4.20260109.0。据称可节省约 70% token、预防 14 类错误、节省约 4 小时开发时间。
主要能力
索引管理：创建、配置和管理向量索引。 向量操作：插入、upsert、查询、删除和列出向量（list-vectors 于 2025 年 8 月新增）。 元数据过滤：每个索引最多 10 个元数据索引，支持高级过滤。 语义搜索：使用 cosine、euclidean 或 dot-product 度量查找相似向量。 RAG 模式：完整的检索增强生成工作流。 Workers AI 集成：使用 @cf/baai/bge-base-en-v1.5 原生生成嵌入。 OpenAI 集成：支持 text-embedding-3-small/large 模型。 文档处理：文本分块和批量摄取管道。 测试设置：带 Vectorize 绑定的 Vitest 配置。
包含模板：basic-search.ts（使用 Workers AI 的简单向量搜索）、rag-chat.ts（带上下文检索的完整 RAG 聊天机器人）、document-ingestion.ts（文档分块与嵌入管道）、metadata-filtering.ts（高级过滤模式）。
Vectorize V2 破坏性变更（2024 年 9 月）
V2 于 2024 年 9 月 GA，带来显著破坏性变更。性能改进：索引容量从 200,000 提升至每索引 500 万向量；查询延迟从 549ms 降至 31ms 中位（快 18 倍）；TopK 上限从 20 提升至每次查询 100 条结果；账户索引数从 100 提升至 50,000；每索引命名空间从 100 提升至 50,000。
API 破坏性变更：所有变更操作改为异步，insert 返回 mutationId，向量插入/删除可能需要几秒才能反映；returnMetadata 参数从布尔值改为字符串枚举（'all' | 'indexed' | 'none'）；元数据索引必须在插入向量之前创建，否则该属性不可过滤，需重新 upsert 向量。V1 弃用时间线：2024 年 12 月起无法创建 V1 索引，现有 V1 索引继续工作，迁移时使用 wrangler vectorize --deprecated-v1 标志。Wrangler 最低要求 3.71.0，推荐 4.54.0+。可通过 env.VECTORIZE_INDEX.describe() 查看 mutationId 和 processedUpToMutation 检查变更状态。
关键设置规则
插入向量前必须：1）以固定维度和度量创建索引（npx wrangler vectorize create my-index --dimensions=768 --metric=cosine）；2）立即创建元数据索引（npx wrangler vectorize create-metadata-index my-index --property-name=category --type=string）。索引配置创建后不可更改：维度必须匹配嵌入模型输出（Workers AI bge-base-en-v1.5 为 768，OpenAI text-embedding-3-small 为 1536，text-embedding-3-large 为 3072）；度量决定相似度计算（cosine 适合归一化嵌入，euclidean 为绝对距离，dot-product 用于非归一化向量）。
Wrangler 配置示例（wrangler.jsonc）包含 name、main、compatibility_date、vectorize 绑定（binding 与 index_name）以及 ai 绑定。TypeScript 类型定义 Env 接口包含 VECTORIZE_INDEX 和 AI。
元数据过滤操作符（V2）
支持：隐式 $eq 相等、$ne 不等、$in/$nin 数组、$gte/$lt 等范围查询（数字，V2 新增）、字符串前缀范围查询、点号嵌套元数据、多条件隐式 AND。
元数据最佳实践
低基数适合 $eq 过滤（如 category、language、published）；高基数应避免范围查询（如 user_id、timestamp_ms，建议用秒而非毫秒）。限制：每索引最多 10 个元数据索引，每向量最多 10 KiB 元数据，字符串索引取前 64 字节（UTF-8），数字索引为 Float64 精度，过滤器最大 2048 字节（紧凑 JSON）。向量维度当前上限 1536，Workers AI bge-base（768）和 OpenAI small（1536）支持，OpenAI large（3072）需降维，nomic-embed-code（3584）等不支持，可用 PCA 等降维但可能降低语义质量。元数据键不能为空、不能含点号、不能含引号、不能以 $ 开头。
最佳实践
批量插入：建议批量大小 5000 向量以获得最佳性能。据数据，单条插入 250 万向量需 36 小时以上（未完成），批量插入 400 万向量约 12 小时，快 18 倍。原因：Vectorize 内部预写日志（WAL）针对该大小优化、避免 API 速率限制、平衡吞吐与内存。示例代码展示按 BATCH_SIZE=5000 分批插入并可选延迟 100ms。
查询精度模式：默认使用近似最近邻（ANN）搜索，约 80% 准确率，延迟更快，适合 RAG、搜索、推荐，topK 最高 100；高精度模式通过 returnValues: true 启用，接近 100% 准确率，延迟更高，topK 限制为 20。高精度适用于关键应用（欺诈检测、法律合规）、小结果集（topK < 20）、精度优先于延迟的场景。
常见错误与解决方案
1）元数据索引在向量插入后创建导致过滤失效，需删除重插或在插入前创建。2）维度不匹配，需确保嵌入模型输出与索引维度一致。3）无效元数据键。4）过滤器超过 2048 字节，需简化或拆分查询。5）高基数范围查询慢或精度降低，改用低基数字段或用秒代替毫秒。6）insert 与 upsert 混淆，更新应使用 upsert。7）缺少绑定，需在 wrangler.jsonc 添加 vectorize 绑定。8）命名空间与元数据混淆：命名空间是分区键，在元数据过滤之前应用；元数据是命名空间内的灵活键值过滤。9）V2 异步变更时序，插入向量不会立即可查，可用 mutationId 跟踪并检查 describe()。10）V1 returnMetadata 布尔值在 V2 破坏，需改为字符串枚举。11）wrangler vectorize list --json 输出含日志前缀导致 JSON 解析失败，可用 tail -n +2 或 sed '1d' 去除首行。12）TypeScript 类型缺少过滤操作符（仅含 $eq 和 $ne，缺 $in、$nin、$lt、$lte、$gt、$gte），可手动覆盖类型。13）Windows 开发注册表失败已在 wrangler@4.32.0 修复。14）topK 上限取决于 returnValues/returnMetadata：returnValues: false 且 returnMetadata: 'none' 时 topK 最高 100；returnValues: true 或 returnMetadata: 'all' 时最高 20；returnMetadata: 'indexed' 时最高 100。
V2 迁移清单
更新 wrangler 至 3.71.0+；创建新的 V2 索引（无法从 V1 升级）；在插入向量前创建元数据索引；将 returnMetadata 布尔值改为字符串枚举；处理异步变更（响应含 mutationId）；按 V2 限制测试（topK 最高 100，每索引 500 万向量）；更新异步行为的错误处理。V1 弃用：2024 年 12 月后无法创建新 V1 索引，现有 V1 索引继续工作，V1 操作使用 wrangler vectorize --deprecated-v1。
测试注意事项
使用 @cloudflare/vitest-pool-workers 搭配 Vectorize 或 Workers AI 绑定会导致运行时失败（wrapped binding module can't be resolved）。变通方法：创建不含 Vectorize/AI 绑定的 wrangler-test.jsonc，将 vitest 配置指向测试专用 wrangler 文件，并在测试中 mock 绑定。示例包含 wrangler-test.jsonc、vitest.config.ts 和 mock 代码。