尧图网站建设 
Cloudflare Vectorize 运行时 API 参考从向量类型到查询过滤的完整实战指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以 Cloudflare Vectorize 的运行时 API 为核心系统讲解向量索引在 Cloudflare Workers 中的完整调用方式包括核心类型定义、相似度查询、插入与更新、批量操作、元数据过滤以及性能权衡策略并对照本仓库中 Vectorize 的配置、模式与踩坑文档给出可直接落地的生产级代码示例。读完本文你将能够在 Worker 中正确使用env.VECTORIZE绑定完成语义搜索、RAG 与多租户隔离等典型场景并避开批量限制、延迟可见性等常见陷阱。本文主体基于 Vectorize API 参考同时引用了该技能包内的 README、configuration.md、patterns.md 与 gotchas.md 作为佐证。该技能通过 SKILL.md 接入用于在 Cloudflare 平台上部署与构建应用Vectorize 在决策树中被定位为 AI/ML 场景下的向量数据库用于承载 RAG 与语义搜索。核心数据类型VectorizeVector所有写入与查询操作都围绕VectorizeVector类型展开它在 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 }四个字段的含义与约束如下id必填向量唯一标识最大 64 字节。它同时是insert/upsert去重、getByIds读取与deleteByIds删除的依据。values必填嵌入向量本身类型为number[]维度必须与索引创建时声明的--dimensions完全一致。如果维度不匹配查询会失败——这是排查 no results 时必须首先检查的点见 gotchas.md 的 Troubleshooting 一节。namespace可选逻辑分区最大 64 字节。用于多租户隔离查询时可通过namespace参数把检索范围限定在某个分区内filter before vector search速度最快。metadata可选附加的业务元数据最大 10 KiB。可用于filter条件筛选也可随查询结果返回配合returnMetadata使用。从仓库能力概览看索引支持最高 1536 维32 位浮点、单索引 1000 万向量V2距离度量支持cosine、euclidean、dot-product三种见 README.md。维度与度量在索引创建后不可修改配置不可变因此建索引前必须确认嵌入模型的输出维度例如 Workers AI 的cf/baai/bge-base-en-v1.5输出 768 维。查询操作query 参数全解与 queryByIdquery 基本用法query是 Vectorize 使用频率最高的运行时操作用于以向量为查询条件返回最相似的 Top-K 结果const 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? }各参数的作用参数取值说明topK数字返回的最近邻数量。常规上限 100开启returnValues或returnMetadata: all时上限降为 20returnMetadatanone/indexed/all是否返回元数据。none最快indexed为推荐平衡点all会返回完整元数据但限制 topKreturnValuesboolean是否在结果中返回向量值开启后 topK 上限为 20namespace字符串将搜索限定在指定命名空间内实现逻辑隔离filter对象元数据过滤条件要求已创建对应的元数据索引matches.matches[0]的结果项结构为{ id, score, metadata? }其中score的语义取决于索引所用的距离度量cosine越高越相似1.0 表示完全一致适合文本嵌入与语义相似度检索euclidean越低越接近0.0 表示完全一致适合绝对距离与空间数据dot-product越高越相似适合推荐系统与预归一化向量。returnMetadata 的三个档位文档给出的取舍关系是一条明确的性能梯度nonefastest→indexedrecommended→alltopK max 20indexed是推荐档位速度接近none同时返回已被元数据索引的字段。但需要注意一个关键细节——indexed只返回字符串字段的前 64 字节因为字符串元数据索引本身就是按 64 字节截断存储的详见 gotchas.md。如果需要完整元数据必须改用all代价是 topK 上限降为 20。queryByIdV2 专属V2 索引额外支持queryById它允许你直接以索引中已存在的向量作为查询向量免去二次嵌入计算await env.VECTORIZE.queryById(doc-123, { topK: 5 });典型场景是相似文档推荐给定一篇文档 ID找出与其嵌入最接近的其他文档无需重新调用嵌入模型生成查询向量。写入操作insert 与 upsert 的语义差异写入接口分为insert与upsert两者的差别在于对重复id的处理策略// 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若id已存在则用新向量覆盖保留后写入的新向量。两个接口都接收向量数组且单次调用最多 500 个向量超过部分会被静默截断——这是 Workers API 层未写入公开文档的硬限制见 gotchas.md。延迟可见性写入是异步的insert/upsert调用立即返回但新写入的向量需要510 秒才会变得可查询。在写入后立即查询的流程中必须考虑这一窗口期这也是排查查不到刚插入的数据的首要原因。此外patterns.md 还给出了一个常见错误提醒接入 Workers AI 时必须把嵌入结果中的result.data[0]而非整个响应对象传给query或写入接口否则维度形状不匹配会直接导致失败。其他运行时操作getByIds、deleteByIds 与 describe按 ID 读取// Get by IDs const vectors await env.VECTORIZE.getByIds([id1, id2]);按主键批量读取向量适用于命中向量后回源取详情之前先确认向量存在的场景。按 ID 删除// Delete (max 1000 IDs per call) await env.VECTORIZE.deleteByIds([id1, id2]);单次调用最多删除1000 个 ID。注意删除与插入一样是异步变更同样存在可见性延迟。索引信息// Index info const info await env.VECTORIZE.describe(); // { dimensions, metric, vectorCount }describe()返回索引的元信息dimensions维度、metric距离度量、vectorCount当前向量总数。这在运行时动态校验嵌入维度是否与索引匹配时非常实用。元数据过滤操作符、约束与索引前置要求过滤操作符过滤基于元数据字段进行前提是这些字段已建立元数据索引见 configuration.md。支持的比较操作符如下操作符示例$eq隐式{ category: docs }$ne{ status: { $ne: deleted } }$in/$nin{ tag: { $in: [sale] } }$lt、$lte、$gt、$gte{ price: { $lt: 100 } }注意$eq是隐式操作符——直接写{ category: docs }即表示相等匹配。这些操作符可以组合构成 patterns.md 中展示的混合搜索式复合条件const matches await env.VECTORIZE.query(vec, { topK: 20, filter: { category: { $in: [tech, science] }, published: { $gte: lastMonthTimestamp } } });过滤约束过滤条件本身有一组硬约束超出即报错或失效过滤表达式最大 2048 字节键中不能包含点号.和$——嵌套字段需用点号表示法如product.category作为索引属性名见 gotchas.md值类型仅限 string / number / boolean / null。元数据索引必须先于数据创建过滤能否生效取决于元数据索引的创建时机必须在插入向量之前创建元数据索引已存在的向量不会被追溯索引configuration.md 明确标注 existing vectors not retroactively indexed。如果先插数据后建索引需要重新 upsert 全部向量。创建命令示例wrangler vectorize create-metadata-index my-index --property-namecategory --typestring wrangler vectorize create-metadata-index my-index --property-nameprice --typenumber元数据索引支持的类型与用途类型用途备注string分类、标签仅前 64 字节被索引number价格、时间戳支持范围比较boolean标志位布尔匹配单个索引最多可建10 个元数据索引V2 限制见 gotchas.md。性能权衡topK、returnMetadata 与 returnValues 的组合查询性能主要取决于返回多少数据以及返回的数据类型。api.md 给出了完整的组合矩阵配置topK 上限速度无元数据returnMetadata: nonereturnValues: false100最快returnMetadata: indexed100快returnMetadata: all20较慢returnValues: true20较慢对照 gotchas.md 的表格可以更精确地记忆这个规则returnMetadatareturnValuesMax topKnone/indexedfalse100all任意20任意true20实践建议默认使用returnMetadata: indexed关闭returnValues这是速度与数据完备性之间的最佳平衡仅在需要完整元数据如展示详情或需要下游再计算时才开启all或returnValues并接受 topK 降至 20 的代价。批量操作吞吐量优化的关键500/批 的分片循环Workers API 单次调用最多 500 个向量因此批量写入必须显式分片。api.md 给出的标准写法for (let i 0; i vectors.length; i 500) { await env.VECTORIZE.upsert(vectors.slice(i, i 500)); }这一模式的必要性来自 gotchas 中的性能数据单条逐条插入吞吐约 1K 条/分钟而 500/批批量插入可达 200K 条/分钟相差两个数量级。批量不仅绕开静默截断的坑更是吞吐量优化的核心手段。大批量导入NDJSON 文件除运行时 API 外configuration.md 还提供了 CLI 层面的批量导入路径——NDJSON 文件wrangler vectorize insert index-name --fileembeddings.ndjson文件内容形如每行一个向量对象{id: 1, values: [0.1, 0.2, ...], metadata: {category: docs}} {id: 2, values: [0.4, 0.5, ...], namespace: tenant-abc}限制单文件最多 5000 个向量、最大 100 MB。CLI 还配套提供wrangler vectorize list、wrangler vectorize info index-name、wrangler vectorize get index-name --ids...、wrangler vectorize delete-by-ids index-name --ids...等运维命令详见 configuration.md适合初始化灌库与索引管理场景。高基数元数据分桶过滤依赖元数据索引而高基数字段会稀释过滤效率并逼近 2048 字节的过滤表达式上限。configuration.md 给出的最佳实践是对高基数数据做时间分桶// ❌ 毫秒级时间戳高基数 metadata: { timestamp: Date.now() } // ✅ 5 分钟分桶低基数 metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }集成场景中的 API 调用范式语义搜索Workers AI 嵌入 Vectorize 查询// 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 });这里再次强调必须传result.data[0]而不是整个响应或data数组。Workers AI 常用嵌入模型的维度与本文 API 的values维度约束一一对应见 patterns.md模型维度cf/baai/bge-small-en-v1.5384cf/baai/bge-base-en-v1.5768推荐cf/baai/bge-large-en-v1.51024创建索引时用npx wrangler vectorize create my-index --dimensions768 --metriccosine声明与所选模型一致的维度维度与度量不可变创建后无法修改并在 wrangler.jsonc 中声明绑定{ vectorize: [ { binding: VECTORIZE, index_name: my-index } ] }对应 TypeScript 侧的类型声明interface Env { VECTORIZE: Vectorize; }RAG 检索增强生成RAG 将本文的query、getByIds相关能力与 Workers AI 生成模型组合成完整链路见 patterns.md// 1. Embed query const emb await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [query] }); // 2. Search vectors const matches await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: indexed }); // 3. Fetch full docs from R2/D1/KV const docs await Promise.all(matches.matches.map(m env.R2.get(m.metadata.key).then(o o?.text()))); // 4. Generate with context const answer await env.AI.run(cf/meta/llama-3-8b-instruct, { prompt: Context:\n${docs.filter(Boolean).join(\n\n)}\n\nQuestion: ${query}\n\nAnswer: });该模式中returnMetadata: indexed的价值得到充分体现向量中只存key等轻量元数据通过m.metadata.key回源 R2 取完整文档既避免了大向量存储又绕开了元数据 10 KiB 的体积上限。多租户namespace 优先filter 兜底多租户隔离有两种 API 层面的实现路径见 patterns.md方案一命名空间租户 5 万推荐——写入与查询均带上namespace检索发生在向量搜索之前速度快且隔离严格await env.VECTORIZE.upsert([{ id: 1, values: emb, namespace: tenant-${id} }]); await env.VECTORIZE.query(vec, { namespace: tenant-${id}, topK: 10 });方案二元数据过滤租户 5 万——以filter: { tenantId: id }实现隔离需先创建tenantId的元数据索引属于向量搜索后的后置过滤速度较慢await env.VECTORIZE.upsert([{ id: 1, values: emb, metadata: { tenantId: id } }]); await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });namespace 与元数据过滤的容量边界来自 README.md付费套餐支持 5 万命名空间、免费套餐 1000 个单账户付费套餐的索引数量上限为 5 万。仅在合规强制要求时才考虑每租户一个索引的方案。常见陷阱与排查清单结合 gotchas.md 的完整限制表V2使用本文 API 时必须牢记以下约束资源上限每索引向量数10,000,000最大维度1536Workers 单次批量 upsert500字符串元数据索引长度64 字节元数据索引数量10命名空间数量50,000付费/ 1,000免费排查问题时按以下清单逐项核对查不到结果插入后是否已等待 510 秒的异步可见期namespace拼写是否一致区分大小写是否已创建所需的元数据索引values维度是否与索引声明的维度一致。元数据过滤失效索引必须在数据插入之前创建字符串超过 64 字节会被截断过滤时注意前缀匹配语义嵌套字段使用点号表示法如product.category作为属性名。常见编码错误嵌入形状错误未提取 Workers AI 返回的result.data[0]先插数据后建元数据索引需要全量 re-upsertinsert与upsert语义混淆前者保留首条去重忽略后者保留末条覆盖更新不做 500/批 分片吞吐从 200K/分钟骤降到约 1K/分钟且超出部分被静默截断。结语Vectorize 的运行时 API 表面简单但围绕topK/returnMetadata/returnValues的组合、500 向量的批量上限、510 秒的写入可见性、64 字节的字符串索引截断以及元数据索引先行原则隐藏着一系列直接影响生产可用性的约束。以本文的 API 参考为主线配合仓库中的 configuration.md索引创建与绑定、patterns.mdRAG、多租户、混合搜索与 gotchas.md极限与排障一起阅读即可在 Cloudflare Workers 上稳定落地语义搜索与 RAG 应用。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Vectorize 运行时 API 参考：从向量类型到查询过滤的完整实战指南
Cloudflare Vectorize 运行时 API 参考从向量类型到查询过滤的完整实战指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以 Cloudflare Vectorize 的运行时 API 为核心系统讲解向量索引在 Cloudflare Workers 中的完整调用方式包括核心类型定义、相似度查询、插入与更新、批量操作、元数据过滤以及性能权衡策略并对照本仓库中 Vectorize 的配置、模式与踩坑文档给出可直接落地的生产级代码示例。读完本文你将能够在 Worker 中正确使用env.VECTORIZE绑定完成语义搜索、RAG 与多租户隔离等典型场景并避开批量限制、延迟可见性等常见陷阱。本文主体基于 Vectorize API 参考同时引用了该技能包内的 README、configuration.md、patterns.md 与 gotchas.md 作为佐证。该技能通过 SKILL.md 接入用于在 Cloudflare 平台上部署与构建应用Vectorize 在决策树中被定位为 AI/ML 场景下的向量数据库用于承载 RAG 与语义搜索。核心数据类型VectorizeVector所有写入与查询操作都围绕VectorizeVector类型展开它在 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 }四个字段的含义与约束如下id必填向量唯一标识最大 64 字节。它同时是insert/upsert去重、getByIds读取与deleteByIds删除的依据。values必填嵌入向量本身类型为number[]维度必须与索引创建时声明的--dimensions完全一致。如果维度不匹配查询会失败——这是排查 no results 时必须首先检查的点见 gotchas.md 的 Troubleshooting 一节。namespace可选逻辑分区最大 64 字节。用于多租户隔离查询时可通过namespace参数把检索范围限定在某个分区内filter before vector search速度最快。metadata可选附加的业务元数据最大 10 KiB。可用于filter条件筛选也可随查询结果返回配合returnMetadata使用。从仓库能力概览看索引支持最高 1536 维32 位浮点、单索引 1000 万向量V2距离度量支持cosine、euclidean、dot-product三种见 README.md。维度与度量在索引创建后不可修改配置不可变因此建索引前必须确认嵌入模型的输出维度例如 Workers AI 的cf/baai/bge-base-en-v1.5输出 768 维。查询操作query 参数全解与 queryByIdquery 基本用法query是 Vectorize 使用频率最高的运行时操作用于以向量为查询条件返回最相似的 Top-K 结果const 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? }各参数的作用参数取值说明topK数字返回的最近邻数量。常规上限 100开启returnValues或returnMetadata: all时上限降为 20returnMetadatanone/indexed/all是否返回元数据。none最快indexed为推荐平衡点all会返回完整元数据但限制 topKreturnValuesboolean是否在结果中返回向量值开启后 topK 上限为 20namespace字符串将搜索限定在指定命名空间内实现逻辑隔离filter对象元数据过滤条件要求已创建对应的元数据索引matches.matches[0]的结果项结构为{ id, score, metadata? }其中score的语义取决于索引所用的距离度量cosine越高越相似1.0 表示完全一致适合文本嵌入与语义相似度检索euclidean越低越接近0.0 表示完全一致适合绝对距离与空间数据dot-product越高越相似适合推荐系统与预归一化向量。returnMetadata 的三个档位文档给出的取舍关系是一条明确的性能梯度nonefastest→indexedrecommended→alltopK max 20indexed是推荐档位速度接近none同时返回已被元数据索引的字段。但需要注意一个关键细节——indexed只返回字符串字段的前 64 字节因为字符串元数据索引本身就是按 64 字节截断存储的详见 gotchas.md。如果需要完整元数据必须改用all代价是 topK 上限降为 20。queryByIdV2 专属V2 索引额外支持queryById它允许你直接以索引中已存在的向量作为查询向量免去二次嵌入计算await env.VECTORIZE.queryById(doc-123, { topK: 5 });典型场景是相似文档推荐给定一篇文档 ID找出与其嵌入最接近的其他文档无需重新调用嵌入模型生成查询向量。写入操作insert 与 upsert 的语义差异写入接口分为insert与upsert两者的差别在于对重复id的处理策略// 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若id已存在则用新向量覆盖保留后写入的新向量。两个接口都接收向量数组且单次调用最多 500 个向量超过部分会被静默截断——这是 Workers API 层未写入公开文档的硬限制见 gotchas.md。延迟可见性写入是异步的insert/upsert调用立即返回但新写入的向量需要510 秒才会变得可查询。在写入后立即查询的流程中必须考虑这一窗口期这也是排查查不到刚插入的数据的首要原因。此外patterns.md 还给出了一个常见错误提醒接入 Workers AI 时必须把嵌入结果中的result.data[0]而非整个响应对象传给query或写入接口否则维度形状不匹配会直接导致失败。其他运行时操作getByIds、deleteByIds 与 describe按 ID 读取// Get by IDs const vectors await env.VECTORIZE.getByIds([id1, id2]);按主键批量读取向量适用于命中向量后回源取详情之前先确认向量存在的场景。按 ID 删除// Delete (max 1000 IDs per call) await env.VECTORIZE.deleteByIds([id1, id2]);单次调用最多删除1000 个 ID。注意删除与插入一样是异步变更同样存在可见性延迟。索引信息// Index info const info await env.VECTORIZE.describe(); // { dimensions, metric, vectorCount }describe()返回索引的元信息dimensions维度、metric距离度量、vectorCount当前向量总数。这在运行时动态校验嵌入维度是否与索引匹配时非常实用。元数据过滤操作符、约束与索引前置要求过滤操作符过滤基于元数据字段进行前提是这些字段已建立元数据索引见 configuration.md。支持的比较操作符如下操作符示例$eq隐式{ category: docs }$ne{ status: { $ne: deleted } }$in/$nin{ tag: { $in: [sale] } }$lt、$lte、$gt、$gte{ price: { $lt: 100 } }注意$eq是隐式操作符——直接写{ category: docs }即表示相等匹配。这些操作符可以组合构成 patterns.md 中展示的混合搜索式复合条件const matches await env.VECTORIZE.query(vec, { topK: 20, filter: { category: { $in: [tech, science] }, published: { $gte: lastMonthTimestamp } } });过滤约束过滤条件本身有一组硬约束超出即报错或失效过滤表达式最大 2048 字节键中不能包含点号.和$——嵌套字段需用点号表示法如product.category作为索引属性名见 gotchas.md值类型仅限 string / number / boolean / null。元数据索引必须先于数据创建过滤能否生效取决于元数据索引的创建时机必须在插入向量之前创建元数据索引已存在的向量不会被追溯索引configuration.md 明确标注 existing vectors not retroactively indexed。如果先插数据后建索引需要重新 upsert 全部向量。创建命令示例wrangler vectorize create-metadata-index my-index --property-namecategory --typestring wrangler vectorize create-metadata-index my-index --property-nameprice --typenumber元数据索引支持的类型与用途类型用途备注string分类、标签仅前 64 字节被索引number价格、时间戳支持范围比较boolean标志位布尔匹配单个索引最多可建10 个元数据索引V2 限制见 gotchas.md。性能权衡topK、returnMetadata 与 returnValues 的组合查询性能主要取决于返回多少数据以及返回的数据类型。api.md 给出了完整的组合矩阵配置topK 上限速度无元数据returnMetadata: nonereturnValues: false100最快returnMetadata: indexed100快returnMetadata: all20较慢returnValues: true20较慢对照 gotchas.md 的表格可以更精确地记忆这个规则returnMetadatareturnValuesMax topKnone/indexedfalse100all任意20任意true20实践建议默认使用returnMetadata: indexed关闭returnValues这是速度与数据完备性之间的最佳平衡仅在需要完整元数据如展示详情或需要下游再计算时才开启all或returnValues并接受 topK 降至 20 的代价。批量操作吞吐量优化的关键500/批 的分片循环Workers API 单次调用最多 500 个向量因此批量写入必须显式分片。api.md 给出的标准写法for (let i 0; i vectors.length; i 500) { await env.VECTORIZE.upsert(vectors.slice(i, i 500)); }这一模式的必要性来自 gotchas 中的性能数据单条逐条插入吞吐约 1K 条/分钟而 500/批批量插入可达 200K 条/分钟相差两个数量级。批量不仅绕开静默截断的坑更是吞吐量优化的核心手段。大批量导入NDJSON 文件除运行时 API 外configuration.md 还提供了 CLI 层面的批量导入路径——NDJSON 文件wrangler vectorize insert index-name --fileembeddings.ndjson文件内容形如每行一个向量对象{id: 1, values: [0.1, 0.2, ...], metadata: {category: docs}} {id: 2, values: [0.4, 0.5, ...], namespace: tenant-abc}限制单文件最多 5000 个向量、最大 100 MB。CLI 还配套提供wrangler vectorize list、wrangler vectorize info index-name、wrangler vectorize get index-name --ids...、wrangler vectorize delete-by-ids index-name --ids...等运维命令详见 configuration.md适合初始化灌库与索引管理场景。高基数元数据分桶过滤依赖元数据索引而高基数字段会稀释过滤效率并逼近 2048 字节的过滤表达式上限。configuration.md 给出的最佳实践是对高基数数据做时间分桶// ❌ 毫秒级时间戳高基数 metadata: { timestamp: Date.now() } // ✅ 5 分钟分桶低基数 metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }集成场景中的 API 调用范式语义搜索Workers AI 嵌入 Vectorize 查询// 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 });这里再次强调必须传result.data[0]而不是整个响应或data数组。Workers AI 常用嵌入模型的维度与本文 API 的values维度约束一一对应见 patterns.md模型维度cf/baai/bge-small-en-v1.5384cf/baai/bge-base-en-v1.5768推荐cf/baai/bge-large-en-v1.51024创建索引时用npx wrangler vectorize create my-index --dimensions768 --metriccosine声明与所选模型一致的维度维度与度量不可变创建后无法修改并在 wrangler.jsonc 中声明绑定{ vectorize: [ { binding: VECTORIZE, index_name: my-index } ] }对应 TypeScript 侧的类型声明interface Env { VECTORIZE: Vectorize; }RAG 检索增强生成RAG 将本文的query、getByIds相关能力与 Workers AI 生成模型组合成完整链路见 patterns.md// 1. Embed query const emb await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [query] }); // 2. Search vectors const matches await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: indexed }); // 3. Fetch full docs from R2/D1/KV const docs await Promise.all(matches.matches.map(m env.R2.get(m.metadata.key).then(o o?.text()))); // 4. Generate with context const answer await env.AI.run(cf/meta/llama-3-8b-instruct, { prompt: Context:\n${docs.filter(Boolean).join(\n\n)}\n\nQuestion: ${query}\n\nAnswer: });该模式中returnMetadata: indexed的价值得到充分体现向量中只存key等轻量元数据通过m.metadata.key回源 R2 取完整文档既避免了大向量存储又绕开了元数据 10 KiB 的体积上限。多租户namespace 优先filter 兜底多租户隔离有两种 API 层面的实现路径见 patterns.md方案一命名空间租户 5 万推荐——写入与查询均带上namespace检索发生在向量搜索之前速度快且隔离严格await env.VECTORIZE.upsert([{ id: 1, values: emb, namespace: tenant-${id} }]); await env.VECTORIZE.query(vec, { namespace: tenant-${id}, topK: 10 });方案二元数据过滤租户 5 万——以filter: { tenantId: id }实现隔离需先创建tenantId的元数据索引属于向量搜索后的后置过滤速度较慢await env.VECTORIZE.upsert([{ id: 1, values: emb, metadata: { tenantId: id } }]); await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });namespace 与元数据过滤的容量边界来自 README.md付费套餐支持 5 万命名空间、免费套餐 1000 个单账户付费套餐的索引数量上限为 5 万。仅在合规强制要求时才考虑每租户一个索引的方案。常见陷阱与排查清单结合 gotchas.md 的完整限制表V2使用本文 API 时必须牢记以下约束资源上限每索引向量数10,000,000最大维度1536Workers 单次批量 upsert500字符串元数据索引长度64 字节元数据索引数量10命名空间数量50,000付费/ 1,000免费排查问题时按以下清单逐项核对查不到结果插入后是否已等待 510 秒的异步可见期namespace拼写是否一致区分大小写是否已创建所需的元数据索引values维度是否与索引声明的维度一致。元数据过滤失效索引必须在数据插入之前创建字符串超过 64 字节会被截断过滤时注意前缀匹配语义嵌套字段使用点号表示法如product.category作为属性名。常见编码错误嵌入形状错误未提取 Workers AI 返回的result.data[0]先插数据后建元数据索引需要全量 re-upsertinsert与upsert语义混淆前者保留首条去重忽略后者保留末条覆盖更新不做 500/批 分片吞吐从 200K/分钟骤降到约 1K/分钟且超出部分被静默截断。结语Vectorize 的运行时 API 表面简单但围绕topK/returnMetadata/returnValues的组合、500 向量的批量上限、510 秒的写入可见性、64 字节的字符串索引截断以及元数据索引先行原则隐藏着一系列直接影响生产可用性的约束。以本文的 API 参考为主线配合仓库中的 configuration.md索引创建与绑定、patterns.mdRAG、多租户、混合搜索与 gotchas.md极限与排障一起阅读即可在 Cloudflare Workers 上稳定落地语义搜索与 RAG 应用。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考