尧图网页设计 
Cloudflare Vectorize 实战指南在 Codex Skills 中构建全球分布式向量数据库与 RAG 应用【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 Skills Catalog for Codex 仓库中 cloudflare-deploy Skill 下的 Vectorize 参考文档为骨架系统讲解如何在 Cloudflare 平台搭建全局分发的向量数据库从索引创建、Worker 绑定、运行时 API 到语义搜索、RAG 与多租户隔离的完整实战方案。读完本文你将掌握 Vectorize V2 的全部核心能力、配置要点与生产环境下的关键陷阱能够直接在一线代码中落地可运行的检索增强生成应用。Vectorize 是 Cloudflare 提供的全球分布式向量数据库专为 AI 应用设计存储并查询向量嵌入vector embeddings用于语义搜索、推荐系统、RAG检索增强生成与分类任务。在 cloudflare-deploy 的整体能力图中它位于存储层Vector embeddings (AI/semantic search) → vectorize/与 AI 层Vector database for RAG/search → vectorize/的交叉位置是 Worker 应用接入 AI 语义能力的核心存储件。根据 Vectorize README其状态为Generally Available (GA)文档最后更新于 2026-01-27。一、快速开始三步打通向量检索Vectorize 的入门路径非常短只需三步即可在 Worker 中完成一次向量查询以下代码取自 Vectorize README 的 Quick Start// 1. Create index // npx wrangler vectorize create my-index --dimensions768 --metriccosine // 2. Configure binding (wrangler.jsonc) // { vectorize: [{ binding: VECTORIZE, index_name: my-index }] } // 3. Query vectors const matches await env.VECTORIZE.query(queryVector, { topK: 5 });其中第一步用 Wrangler CLI 创建索引768 维、cosine 度量第二步在 Worker 配置中声明VECTORIZE绑定将索引注入运行时环境第三步便可在代码中通过env.VECTORIZE直接发起查询。关于每个环节的细节不可变配置、绑定字段、CLI 全集、批量导入将在后续小节逐一展开。二、核心特性与 V2 容量限制Vectorize README 列出的关键特性如下单索引支持 1000 万向量V2维度最高153632 位浮点三种距离度量cosine、euclidean、dot-product元数据过滤最多10 个元数据索引命名空间Namespace支持付费5 万个、免费1 千个与 Workers AI 无缝集成全球分布式部署将 gotchas.md 中的 Limits (V2) 表格合并后可以得到一份完整的容量清单资源上限单索引向量数10,000,000最大维度1536Workers API 单次批量写入500条索引化字符串元数据64 字节元数据索引数10命名空间数50,000付费/ 1,000免费注意以上是V2平台的限制维度以 32 位浮点数存储这些数字同时也是你在做容量规划和索引设计时的硬约束。三、距离度量选择按场景选对度量标准Vectorize README 给出了一个非常实用的决策树帮助你按构建目标选择度量What are you building? ├─ Text/semantic search → cosine (most common) ├─ Image similarity → euclidean ├─ Recommendation system → dot-product └─ Pre-normalized vectors → dot-product三种度量的详细对比分数含义决定了排序方向与业务解读方式度量最佳场景分数解读cosine文本嵌入、语义相似度越高越接近1.0 表示完全相同euclidean绝对距离、空间数据越低越接近0.0 表示完全相同dot-product推荐系统、归一化向量越高越接近⚠️ 索引配置不可变索引创建后维度dimensions与度量metric均无法修改。一旦建错只能新建索引并迁移数据。这也是 configuration.md 把生产检查清单第一步放在用正确维度创建索引的原因。四、索引创建与 Worker 绑定4.1 创建索引CLI依据 configuration.mdnpx wrangler vectorize create my-index --dimensions768 --metriccosine--dimensions必须与后续写入向量的维度严格一致--metric按第三节决策树选择。两者均不可变。4.2 Worker 绑定配置在wrangler.jsonc中声明绑定// wrangler.jsonc { vectorize: [ { binding: VECTORIZE, index_name: my-index } ] }在 TypeScript 侧绑定通过Env接口注入类型interface Env { VECTORIZE: Vectorize; }此后即可在 Worker 的任何 handler 中通过env.VECTORIZE访问索引。4.3 元数据索引必须先于数据创建元数据索引Metadata Indexes用于支撑filter过滤查询必须在插入向量之前创建——已经存在的向量不会被追溯索引这是 configuration.md 与 gotchas.md 共同强调的首要规则wrangler vectorize create-metadata-index my-index --property-namecategory --typestring wrangler vectorize create-metadata-index my-index --property-nameprice --typenumber支持的类型与用途类型适用场景string分类、标签仅索引前 64 字节number价格、时间戳boolean标志位4.4 CLI 命令全集configuration.md 整理了完整的 Wrangler 子命令# Index management wrangler vectorize list wrangler vectorize info index-name wrangler vectorize delete index-name # Vector operations wrangler vectorize insert index-name --fileembeddings.ndjson wrangler vectorize get index-name --idsid1,id2 wrangler vectorize delete-by-ids index-name --idsid1,id2 # Metadata indexes wrangler vectorize list-metadata-index index-name wrangler vectorize delete-metadata-index index-name --property-namefield4.5 批量上传NDJSONCLI 支持通过 NDJSON 文件批量导入每行一条向量{id: 1, values: [0.1, 0.2, ...], metadata: {category: docs}} {id: 2, values: [0.4, 0.5, ...], namespace: tenant-abc}文件限制每文件最多 5000 条向量最大 100 MB。4.6 高基数Cardinality最佳实践configuration.md 特别指出对高基数字段如毫秒级时间戳直接建元数据索引会显著拖慢过滤性能应进行分桶// ❌ Millisecond timestamps metadata: { timestamp: Date.now() } // ✅ 5-minute buckets metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }将连续时间戳归并到 5 分钟桶可大幅降低索引基数、提升过滤效率。4.7 生产检查清单按 configuration.md 的清单顺序执行可避免绝大多数上线事故用正确的维度创建索引先创建元数据索引测试批量上传配置绑定部署 Worker验证查询五、运行时 API 详解5.1 向量类型api.md 定义了写入/查询的向量结构interface VectorizeVector { id: string; // Max 64 bytes values: number[]; // Must match index dimensions namespace?: string; // Optional partition (max 64 bytes) metadata?: Recordstring, any; // Max 10 KiB }values长度必须与索引维度一致id与namespace上限均为 64 字节metadata上限 10 KiB。5.2 查询Queryconst matches await env.VECTORIZE.query(queryVector, { topK: 10, // Max 100 (or 20 with returnValues/returnMetadata:all) returnMetadata: indexed, // none | indexed | all returnValues: false, namespace: tenant-123, filter: { category: docs } }); // matches.matches[0] { id, score, metadata? }returnMetadata三档选择的性能语义api.mdnone最快 → indexed推荐 → alltopK 上限降为 20queryById仅 V2直接以已有向量的 id 作为查询向量免去先取向量再查询的两步调用await env.VECTORIZE.queryById(doc-123, { topK: 5 });5.3 写入Insert 与 Upsert 的语义差异api.md 强调了两者的关键区别// Insert: ignores duplicates (keeps first) await env.VECTORIZE.insert([{ id, values, metadata }]); // Upsert: overwrites duplicates (keeps last) await env.VECTORIZE.upsert([{ id, values, metadata }]);insert遇到重复 id 时保留先写入者upsert则覆盖为后写入者。每次调用最多 500 条向量写入后约需510 秒才可被查询到。5.4 其他操作// Get by IDs const vectors await env.VECTORIZE.getByIds([id1, id2]); // Delete (max 1000 IDs per call) await env.VECTORIZE.deleteByIds([id1, id2]); // Index info const info await env.VECTORIZE.describe(); // { dimensions, metric, vectorCount }deleteByIds单次最多 1000 个 iddescribe()可用于运行时校验索引维度是否与嵌入模型匹配排查维度不匹配问题。5.5 元数据过滤Filtering过滤要求元数据索引已存在支持的运算符api.md运算符示例$eq隐式{ category: docs }$ne{ status: { $ne: deleted } }$in/$nin{ tag: { $in: [sale] } }$lt,$lte,$gt,$gte{ price: { $lt: 100 } }约束过滤表达式最大2048 字节键名中不允许出现点号.与$值仅支持 string/number/boolean/null。嵌套字段可用点号表示法例如product.category。5.6 性能对照与批量策略api.md 给出了不同查询配置下的 topK 上限与速度对比配置topK 上限速度无元数据返回100最快returnMetadata: indexed100快returnMetadata: all20较慢returnValues: true20较慢批量写入原则始终按 500 条/批切分以获得最佳吞吐for (let i 0; i vectors.length; i 500) { await env.VECTORIZE.upsert(vectors.slice(i, i 500)); }六、常见工作流实战6.1 语义搜索Semantic SearchVectorize README 展示了嵌入 查询的最小闭环// 1. Generate embedding const result await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [query] }); // 2. Query Vectorize const matches await env.VECTORIZE.query(result.data[0], { topK: 5, returnMetadata: indexed });关键点在于Workers AI 返回的是{ data: [...] }结构必须传result.data[0]第一个嵌入向量而不是整个响应对象——这是 patterns.md 与 gotchas.md 共同列出的头号常见错误。6.2 RAG 模式完整链路Vectorize README 给出了一个可直接落地的四步 RAG 实现嵌入查询 → 向量检索 → 从 R2/D1/KV 取回全文 → 交给 LLM 生成带上下文的回答。// 1. Generate query embedding const embedding await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [query] }); // 2. Search Vectorize const matches await env.VECTORIZE.query(embedding.data[0], { topK: 5 }); // 3. Fetch full documents from R2/D1/KV const docs await Promise.all(matches.matches.map(m env.R2.get(m.metadata.key).then(obj obj?.text()) )); // 4. Generate LLM response with context const answer await env.AI.run(cf/meta/llama-3-8b-instruct, { prompt: Context: ${docs.join(\n\n)}\n\nQuestion: ${query}\n\nAnswer: });这里的典型范式是向量库只存嵌入与元数据如对象 key全文放 R2/D1/KV检索命中后再取全文拼入 prompt。注意 patterns.md 中的改良版对docs.filter(Boolean)做了空值过滤建议在实际代码中保留。6.3 OpenAI 集成patterns.md 提供了使用 OpenAI 嵌入模型的等价写法const response await openai.embeddings.create({ model: text-embedding-ada-002, input: query }); const matches await env.VECTORIZE.query(response.data[0].embedding, { topK: 5 });即无论嵌入来自 Workers AI 还是外部服务Vectorize 查询接口接收的始终是一个一维浮点数组。6.4 混合搜索向量 元数据过滤当检索目标同时包含语义相关性与结构化条件时用filter做混合搜索patterns.mdconst matches await env.VECTORIZE.query(vec, { topK: 20, filter: { category: { $in: [tech, science] }, published: { $gte: lastMonthTimestamp } } });注意$in与$gte组合使用需要category、published均已建立元数据索引。6.5 批量摄取Batch Ingestion生产环境摄入大量向量时必须分批const BATCH 500; for (let i 0; i vectors.length; i BATCH) { await env.VECTORIZE.upsert(vectors.slice(i, i BATCH)); }gotchas.md 给出的量化对比极具说服力单条逐个插入约 1K 条/分钟批量插入可达 200K 条/分钟吞吐差异可达两个数量级。6.6 Workers AI 嵌入模型维度速查patterns.md 与 gotchas.md 一致给出模型维度cf/baai/bge-small-en-v1.5384cf/baai/bge-base-en-v1.5768推荐cf/baai/bge-large-en-v1.51024创建索引时的--dimensions必须与所选模型维度一致如选 bge-base 则建 768 维索引。七、多租户策略三档方案的选择逻辑Vectorize README 给出了按租户数量选择隔离方案的标准决策树How many tenants? ├─ 50K tenants → Use namespaces (recommended) │ ├─ Fastest (filter before vector search) │ └─ Strict isolation ├─ 50K tenants → Use metadata filtering │ ├─ Slower (post-filter after vector search) │ └─ Requires metadata index └─ Per-tenant indexes → Only if compliance mandated └─ 50K index limit per account (paid plan)命名空间方案推荐租户 5 万命名空间在向量搜索之前完成过滤速度快且隔离严格patterns.mdawait env.VECTORIZE.upsert([{ id: 1, values: emb, namespace: tenant-${id} }]); await env.VECTORIZE.query(vec, { namespace: tenant-${id}, topK: 10 });元数据过滤方案租户 5 万先建索引查询时用 filter 在向量检索之后做后置过滤适合租户数超命名空间上限的场景wrangler vectorize create-metadata-index my-index --property-nametenantId --typestringawait env.VECTORIZE.upsert([{ id: 1, values: emb, metadata: { tenantId: id } }]); await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });每租户独立索引仅在合规强制要求下使用受付费计划每账号 5 万索引上限约束。八、关键陷阱与故障排查Vectorize README 的 Critical Gotchas 部分浓缩了五个最重要的问题gotchas.md 则给出了完整细节异步写入Async Mutationsinsert/upsert/delete 立即返回但向量需要510 秒后才可被查询到——写入后的即时查询会查不到结果必须处理这一延迟。500 条批量上限Workers API 强制每次调用最多 500 条向量超出部分被静默截断文档未公开此行为务必手动切分。元数据截断returnMetadata: indexed只返回字符串的前64 字节需要完整元数据用all但 topK 上限会降为 20。topK 上限联动使用returnValues或returnMetadata: all时topK 最大为20而非 100。元数据索引先行必须先创建元数据索引再插入向量存量向量不会被追溯索引。其中 topK 限制的完整对照表gotchas.mdreturnMetadatareturnValues最大 topKnone/indexedfalse100all任意20任意true20常见错误清单gotchas.md嵌入形状错误忘记从 Workers AI 响应中取result.data[0]导致维度不匹配或类型错误数据先于元数据索引索引建晚了只能重新 upsert 全部向量混淆 insert 与 upsertinsert忽略重复、upsert覆盖重复不批量写入吞吐可从约 1K 条/分钟跌至 200K 条/分钟的水平。排查指引查询无结果时依次检查插入后是否已等待 510 秒命名空间拼写是否正确区分大小写元数据索引是否存在向量维度是否与索引匹配元数据过滤失效时依次检查索引是否早于数据创建字符串是否超过 64 字节被截断嵌套字段是否使用点号表示法如product.category九、文档导航按任务定位阅读材料Vectorize README 提供了按任务定制的阅读顺序表任务建议阅读初次接触 Vectorize本文档README即可实现功能特性README api patterns搭建/配置环境README configuration排查问题gotchas与 AI 集成README patternsRAG 实现README patterns配套文件同一目录仓库相对路径README.md总览、快速决策本文主体api.md运行时 API、类型、操作query/insert/upsertconfiguration.md搭建、CLI、元数据索引patterns.mdRAG、Workers AI、OpenAI、LangChain、多租户gotchas.md限制、陷阱、故障排查十、结语一条可复制的落地路径综合全篇一个生产级 Vectorize 应用的标准落地顺序是按嵌入模型维度与业务语义选定--dimensions/--metric不可变→ 先建元数据索引 → 以 500 条/批的节奏批量 upsert接受 510 秒的查询延迟→ 配置 Worker 绑定 → 按场景选择returnMetadata: indexed与合适的 topK → 通过命名空间或元数据过滤实现多租户隔离。将本文的 API 细节、性能对照表与陷阱清单与 api.md、configuration.md、patterns.md、gotchas.md 配合使用即可在 Cloudflare 平台上稳定运行语义搜索与 RAG 应用。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Vectorize 实战指南：在 Codex Skills 中构建全球分布式向量数据库与 RAG 应用
Cloudflare Vectorize 实战指南在 Codex Skills 中构建全球分布式向量数据库与 RAG 应用【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 Skills Catalog for Codex 仓库中 cloudflare-deploy Skill 下的 Vectorize 参考文档为骨架系统讲解如何在 Cloudflare 平台搭建全局分发的向量数据库从索引创建、Worker 绑定、运行时 API 到语义搜索、RAG 与多租户隔离的完整实战方案。读完本文你将掌握 Vectorize V2 的全部核心能力、配置要点与生产环境下的关键陷阱能够直接在一线代码中落地可运行的检索增强生成应用。Vectorize 是 Cloudflare 提供的全球分布式向量数据库专为 AI 应用设计存储并查询向量嵌入vector embeddings用于语义搜索、推荐系统、RAG检索增强生成与分类任务。在 cloudflare-deploy 的整体能力图中它位于存储层Vector embeddings (AI/semantic search) → vectorize/与 AI 层Vector database for RAG/search → vectorize/的交叉位置是 Worker 应用接入 AI 语义能力的核心存储件。根据 Vectorize README其状态为Generally Available (GA)文档最后更新于 2026-01-27。一、快速开始三步打通向量检索Vectorize 的入门路径非常短只需三步即可在 Worker 中完成一次向量查询以下代码取自 Vectorize README 的 Quick Start// 1. Create index // npx wrangler vectorize create my-index --dimensions768 --metriccosine // 2. Configure binding (wrangler.jsonc) // { vectorize: [{ binding: VECTORIZE, index_name: my-index }] } // 3. Query vectors const matches await env.VECTORIZE.query(queryVector, { topK: 5 });其中第一步用 Wrangler CLI 创建索引768 维、cosine 度量第二步在 Worker 配置中声明VECTORIZE绑定将索引注入运行时环境第三步便可在代码中通过env.VECTORIZE直接发起查询。关于每个环节的细节不可变配置、绑定字段、CLI 全集、批量导入将在后续小节逐一展开。二、核心特性与 V2 容量限制Vectorize README 列出的关键特性如下单索引支持 1000 万向量V2维度最高153632 位浮点三种距离度量cosine、euclidean、dot-product元数据过滤最多10 个元数据索引命名空间Namespace支持付费5 万个、免费1 千个与 Workers AI 无缝集成全球分布式部署将 gotchas.md 中的 Limits (V2) 表格合并后可以得到一份完整的容量清单资源上限单索引向量数10,000,000最大维度1536Workers API 单次批量写入500条索引化字符串元数据64 字节元数据索引数10命名空间数50,000付费/ 1,000免费注意以上是V2平台的限制维度以 32 位浮点数存储这些数字同时也是你在做容量规划和索引设计时的硬约束。三、距离度量选择按场景选对度量标准Vectorize README 给出了一个非常实用的决策树帮助你按构建目标选择度量What are you building? ├─ Text/semantic search → cosine (most common) ├─ Image similarity → euclidean ├─ Recommendation system → dot-product └─ Pre-normalized vectors → dot-product三种度量的详细对比分数含义决定了排序方向与业务解读方式度量最佳场景分数解读cosine文本嵌入、语义相似度越高越接近1.0 表示完全相同euclidean绝对距离、空间数据越低越接近0.0 表示完全相同dot-product推荐系统、归一化向量越高越接近⚠️ 索引配置不可变索引创建后维度dimensions与度量metric均无法修改。一旦建错只能新建索引并迁移数据。这也是 configuration.md 把生产检查清单第一步放在用正确维度创建索引的原因。四、索引创建与 Worker 绑定4.1 创建索引CLI依据 configuration.mdnpx wrangler vectorize create my-index --dimensions768 --metriccosine--dimensions必须与后续写入向量的维度严格一致--metric按第三节决策树选择。两者均不可变。4.2 Worker 绑定配置在wrangler.jsonc中声明绑定// wrangler.jsonc { vectorize: [ { binding: VECTORIZE, index_name: my-index } ] }在 TypeScript 侧绑定通过Env接口注入类型interface Env { VECTORIZE: Vectorize; }此后即可在 Worker 的任何 handler 中通过env.VECTORIZE访问索引。4.3 元数据索引必须先于数据创建元数据索引Metadata Indexes用于支撑filter过滤查询必须在插入向量之前创建——已经存在的向量不会被追溯索引这是 configuration.md 与 gotchas.md 共同强调的首要规则wrangler vectorize create-metadata-index my-index --property-namecategory --typestring wrangler vectorize create-metadata-index my-index --property-nameprice --typenumber支持的类型与用途类型适用场景string分类、标签仅索引前 64 字节number价格、时间戳boolean标志位4.4 CLI 命令全集configuration.md 整理了完整的 Wrangler 子命令# Index management wrangler vectorize list wrangler vectorize info index-name wrangler vectorize delete index-name # Vector operations wrangler vectorize insert index-name --fileembeddings.ndjson wrangler vectorize get index-name --idsid1,id2 wrangler vectorize delete-by-ids index-name --idsid1,id2 # Metadata indexes wrangler vectorize list-metadata-index index-name wrangler vectorize delete-metadata-index index-name --property-namefield4.5 批量上传NDJSONCLI 支持通过 NDJSON 文件批量导入每行一条向量{id: 1, values: [0.1, 0.2, ...], metadata: {category: docs}} {id: 2, values: [0.4, 0.5, ...], namespace: tenant-abc}文件限制每文件最多 5000 条向量最大 100 MB。4.6 高基数Cardinality最佳实践configuration.md 特别指出对高基数字段如毫秒级时间戳直接建元数据索引会显著拖慢过滤性能应进行分桶// ❌ Millisecond timestamps metadata: { timestamp: Date.now() } // ✅ 5-minute buckets metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }将连续时间戳归并到 5 分钟桶可大幅降低索引基数、提升过滤效率。4.7 生产检查清单按 configuration.md 的清单顺序执行可避免绝大多数上线事故用正确的维度创建索引先创建元数据索引测试批量上传配置绑定部署 Worker验证查询五、运行时 API 详解5.1 向量类型api.md 定义了写入/查询的向量结构interface VectorizeVector { id: string; // Max 64 bytes values: number[]; // Must match index dimensions namespace?: string; // Optional partition (max 64 bytes) metadata?: Recordstring, any; // Max 10 KiB }values长度必须与索引维度一致id与namespace上限均为 64 字节metadata上限 10 KiB。5.2 查询Queryconst matches await env.VECTORIZE.query(queryVector, { topK: 10, // Max 100 (or 20 with returnValues/returnMetadata:all) returnMetadata: indexed, // none | indexed | all returnValues: false, namespace: tenant-123, filter: { category: docs } }); // matches.matches[0] { id, score, metadata? }returnMetadata三档选择的性能语义api.mdnone最快 → indexed推荐 → alltopK 上限降为 20queryById仅 V2直接以已有向量的 id 作为查询向量免去先取向量再查询的两步调用await env.VECTORIZE.queryById(doc-123, { topK: 5 });5.3 写入Insert 与 Upsert 的语义差异api.md 强调了两者的关键区别// Insert: ignores duplicates (keeps first) await env.VECTORIZE.insert([{ id, values, metadata }]); // Upsert: overwrites duplicates (keeps last) await env.VECTORIZE.upsert([{ id, values, metadata }]);insert遇到重复 id 时保留先写入者upsert则覆盖为后写入者。每次调用最多 500 条向量写入后约需510 秒才可被查询到。5.4 其他操作// Get by IDs const vectors await env.VECTORIZE.getByIds([id1, id2]); // Delete (max 1000 IDs per call) await env.VECTORIZE.deleteByIds([id1, id2]); // Index info const info await env.VECTORIZE.describe(); // { dimensions, metric, vectorCount }deleteByIds单次最多 1000 个 iddescribe()可用于运行时校验索引维度是否与嵌入模型匹配排查维度不匹配问题。5.5 元数据过滤Filtering过滤要求元数据索引已存在支持的运算符api.md运算符示例$eq隐式{ category: docs }$ne{ status: { $ne: deleted } }$in/$nin{ tag: { $in: [sale] } }$lt,$lte,$gt,$gte{ price: { $lt: 100 } }约束过滤表达式最大2048 字节键名中不允许出现点号.与$值仅支持 string/number/boolean/null。嵌套字段可用点号表示法例如product.category。5.6 性能对照与批量策略api.md 给出了不同查询配置下的 topK 上限与速度对比配置topK 上限速度无元数据返回100最快returnMetadata: indexed100快returnMetadata: all20较慢returnValues: true20较慢批量写入原则始终按 500 条/批切分以获得最佳吞吐for (let i 0; i vectors.length; i 500) { await env.VECTORIZE.upsert(vectors.slice(i, i 500)); }六、常见工作流实战6.1 语义搜索Semantic SearchVectorize README 展示了嵌入 查询的最小闭环// 1. Generate embedding const result await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [query] }); // 2. Query Vectorize const matches await env.VECTORIZE.query(result.data[0], { topK: 5, returnMetadata: indexed });关键点在于Workers AI 返回的是{ data: [...] }结构必须传result.data[0]第一个嵌入向量而不是整个响应对象——这是 patterns.md 与 gotchas.md 共同列出的头号常见错误。6.2 RAG 模式完整链路Vectorize README 给出了一个可直接落地的四步 RAG 实现嵌入查询 → 向量检索 → 从 R2/D1/KV 取回全文 → 交给 LLM 生成带上下文的回答。// 1. Generate query embedding const embedding await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [query] }); // 2. Search Vectorize const matches await env.VECTORIZE.query(embedding.data[0], { topK: 5 }); // 3. Fetch full documents from R2/D1/KV const docs await Promise.all(matches.matches.map(m env.R2.get(m.metadata.key).then(obj obj?.text()) )); // 4. Generate LLM response with context const answer await env.AI.run(cf/meta/llama-3-8b-instruct, { prompt: Context: ${docs.join(\n\n)}\n\nQuestion: ${query}\n\nAnswer: });这里的典型范式是向量库只存嵌入与元数据如对象 key全文放 R2/D1/KV检索命中后再取全文拼入 prompt。注意 patterns.md 中的改良版对docs.filter(Boolean)做了空值过滤建议在实际代码中保留。6.3 OpenAI 集成patterns.md 提供了使用 OpenAI 嵌入模型的等价写法const response await openai.embeddings.create({ model: text-embedding-ada-002, input: query }); const matches await env.VECTORIZE.query(response.data[0].embedding, { topK: 5 });即无论嵌入来自 Workers AI 还是外部服务Vectorize 查询接口接收的始终是一个一维浮点数组。6.4 混合搜索向量 元数据过滤当检索目标同时包含语义相关性与结构化条件时用filter做混合搜索patterns.mdconst matches await env.VECTORIZE.query(vec, { topK: 20, filter: { category: { $in: [tech, science] }, published: { $gte: lastMonthTimestamp } } });注意$in与$gte组合使用需要category、published均已建立元数据索引。6.5 批量摄取Batch Ingestion生产环境摄入大量向量时必须分批const BATCH 500; for (let i 0; i vectors.length; i BATCH) { await env.VECTORIZE.upsert(vectors.slice(i, i BATCH)); }gotchas.md 给出的量化对比极具说服力单条逐个插入约 1K 条/分钟批量插入可达 200K 条/分钟吞吐差异可达两个数量级。6.6 Workers AI 嵌入模型维度速查patterns.md 与 gotchas.md 一致给出模型维度cf/baai/bge-small-en-v1.5384cf/baai/bge-base-en-v1.5768推荐cf/baai/bge-large-en-v1.51024创建索引时的--dimensions必须与所选模型维度一致如选 bge-base 则建 768 维索引。七、多租户策略三档方案的选择逻辑Vectorize README 给出了按租户数量选择隔离方案的标准决策树How many tenants? ├─ 50K tenants → Use namespaces (recommended) │ ├─ Fastest (filter before vector search) │ └─ Strict isolation ├─ 50K tenants → Use metadata filtering │ ├─ Slower (post-filter after vector search) │ └─ Requires metadata index └─ Per-tenant indexes → Only if compliance mandated └─ 50K index limit per account (paid plan)命名空间方案推荐租户 5 万命名空间在向量搜索之前完成过滤速度快且隔离严格patterns.mdawait env.VECTORIZE.upsert([{ id: 1, values: emb, namespace: tenant-${id} }]); await env.VECTORIZE.query(vec, { namespace: tenant-${id}, topK: 10 });元数据过滤方案租户 5 万先建索引查询时用 filter 在向量检索之后做后置过滤适合租户数超命名空间上限的场景wrangler vectorize create-metadata-index my-index --property-nametenantId --typestringawait env.VECTORIZE.upsert([{ id: 1, values: emb, metadata: { tenantId: id } }]); await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });每租户独立索引仅在合规强制要求下使用受付费计划每账号 5 万索引上限约束。八、关键陷阱与故障排查Vectorize README 的 Critical Gotchas 部分浓缩了五个最重要的问题gotchas.md 则给出了完整细节异步写入Async Mutationsinsert/upsert/delete 立即返回但向量需要510 秒后才可被查询到——写入后的即时查询会查不到结果必须处理这一延迟。500 条批量上限Workers API 强制每次调用最多 500 条向量超出部分被静默截断文档未公开此行为务必手动切分。元数据截断returnMetadata: indexed只返回字符串的前64 字节需要完整元数据用all但 topK 上限会降为 20。topK 上限联动使用returnValues或returnMetadata: all时topK 最大为20而非 100。元数据索引先行必须先创建元数据索引再插入向量存量向量不会被追溯索引。其中 topK 限制的完整对照表gotchas.mdreturnMetadatareturnValues最大 topKnone/indexedfalse100all任意20任意true20常见错误清单gotchas.md嵌入形状错误忘记从 Workers AI 响应中取result.data[0]导致维度不匹配或类型错误数据先于元数据索引索引建晚了只能重新 upsert 全部向量混淆 insert 与 upsertinsert忽略重复、upsert覆盖重复不批量写入吞吐可从约 1K 条/分钟跌至 200K 条/分钟的水平。排查指引查询无结果时依次检查插入后是否已等待 510 秒命名空间拼写是否正确区分大小写元数据索引是否存在向量维度是否与索引匹配元数据过滤失效时依次检查索引是否早于数据创建字符串是否超过 64 字节被截断嵌套字段是否使用点号表示法如product.category九、文档导航按任务定位阅读材料Vectorize README 提供了按任务定制的阅读顺序表任务建议阅读初次接触 Vectorize本文档README即可实现功能特性README api patterns搭建/配置环境README configuration排查问题gotchas与 AI 集成README patternsRAG 实现README patterns配套文件同一目录仓库相对路径README.md总览、快速决策本文主体api.md运行时 API、类型、操作query/insert/upsertconfiguration.md搭建、CLI、元数据索引patterns.mdRAG、Workers AI、OpenAI、LangChain、多租户gotchas.md限制、陷阱、故障排查十、结语一条可复制的落地路径综合全篇一个生产级 Vectorize 应用的标准落地顺序是按嵌入模型维度与业务语义选定--dimensions/--metric不可变→ 先建元数据索引 → 以 500 条/批的节奏批量 upsert接受 510 秒的查询延迟→ 配置 Worker 绑定 → 按场景选择returnMetadata: indexed与合适的 topK → 通过命名空间或元数据过滤实现多租户隔离。将本文的 API 细节、性能对照表与陷阱清单与 api.md、configuration.md、patterns.md、gotchas.md 配合使用即可在 Cloudflare 平台上稳定运行语义搜索与 RAG 应用。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考