Cloudflare Vectorize 是 Cloudflare 提供的全球分布式向量数据库，用于构建语义搜索、RAG（检索增强生成）和 AI 驱动的应用，并与 Cloudflare Workers 配合使用。本技能为完整实现指南。
一、用途 适用于在文档、产品或内容之上构建语义搜索；实现带上下文检索的 RAG 聊天机器人；基于相似度创建推荐引擎；构建多租户应用（使用命名空间）；需要全球分发和低延迟的场景。不适用于传统关系型数据（用 D1）、键值查找（用 KV）、大文件存储（用 R2）、实时协作状态（用 Durable Objects）。
二、主要能力 索引管理：创建、配置和管理向量索引。 向量操作：插入、upsert、查询、删除、列出向量。 元数据过滤：每个索引支持最多 10 个元数据索引，可进行高级过滤。 语义搜索：使用余弦、欧几里得或点积度量查找相似向量。 RAG 模式：完整的检索增强生成工作流。 Workers AI 集成：使用 @cf/baai/bge-base-en-v1.5 原生生成嵌入。 OpenAI 集成：支持 text-embedding-3-small/large 模型。 文档处理：文本分块与批量摄入管道。 附带模板：basic-search.ts（简单向量搜索）、rag-chat.ts（带上下文检索的完整 RAG 聊天机器人）、document-ingestion.ts（文档分块与嵌入管道）、metadata-filtering.ts（高级过滤示例）。
三、关键设置规则 插入向量前必须先创建索引（固定维度和度量），并立即创建元数据索引。元数据索引必须在插入向量之前存在，否则先插入的向量无法按该属性过滤。索引配置一旦创建不可更改。维度必须与嵌入模型输出匹配：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（相等，隐式）、$ne（不等）、$in（在数组中）、$nin（不在数组中）、$gte/$lt（范围查询）。
嵌入生成模型： @cf/baai/bge-base-en-v1.5（Workers AI，768 维，免费，通用） text-embedding-3-small（OpenAI，1536 维，质量/成本平衡） text-embedding-3-large（OpenAI，3072 维，最高质量）
元数据限制：每个索引最多 10 个元数据索引；每个向量元数据最大 10 KiB；字符串索引取前 64 字节（UTF-8）；过滤器最大 2048 字节。无效键：不能为空、不能包含 .（保留用于嵌套）、不能包含 "、不能以 $ 开头。
RAG 完整示例代码：
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const { question } = await request.json();
const questionEmbedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
text: question
});
const results = await env.VECTORIZE_INDEX.query(
questionEmbedding.data[0],
{
topK: 3,
returnMetadata: 'all',
filter: { type: "documentation" }
}
);
const context = results.matches
.map(m => m.metadata.content)
.join('\n\n---\n\n');
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（用于检索展示的文本）。
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>
五、常见错误与解决方案
- 元数据索引在向量插入后创建：过滤不生效，需删除并重新插入向量，或在插入前创建元数据索引。
- 维度不匹配：确保嵌入模型输出与索引维度一致。
- 无效元数据键：键不能为空、含 .、含 "、或以 $ 开头。
- 过滤器过大（超过 2048 字节）：简化过滤器或拆分为多个查询。
- 高基数上的范围查询：查询慢或精度降低，使用低基数字段或时间戳用秒而非毫秒。
- insert 与 upsert 混淆：更新需用 upsert() 覆盖。
- 缺少绑定：在 wrangler.jsonc 添加 vectorize 绑定。
- 命名空间与元数据混淆：命名空间为分区键，在元数据过滤之前应用；元数据为命名空间内的灵活键值过滤。
六、性能建议 批量操作：按 100-1000 个向量批量插入/ upsert。选择性返回：仅在需要时使用 returnValues: true。元数据基数：范围查询的索引字段保持低基数。命名空间过滤：先应用命名空间过滤（优先处理）。查询优化：topK=3-10 延迟最佳（值越大会增加搜索时间）。
七、安全安装建议 安装向量数据库包时遵循供应链安全最佳实践：阻止安装后脚本（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；状态：生产就绪；令牌节省约 65%；预防 8 大类错误；每次实现节省约 2.5 小时开发时间。