尧图网站建设 
Cloudflare Vectorize 配置实战指南索引创建、Worker 绑定、元数据过滤与批量写入Codex Skills 参考【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以仓库内 Vectorize 配置文档 为核心骨架系统讲解 Cloudflare Vectorize 向量数据库的完整配置链路——从创建索引、配置 Worker 绑定到元数据索引、CLI 批量操作与基数优化实践并深入解析其不可变配置约束与生产环境部署清单。读完本文你将掌握一套可直接复制到生产环境的 Vectorize 配置流程并理解每个配置决策背后的源码级原理与运行时行为。一、配置之前理解 Vectorize 的核心约束Cloudflare Vectorize 是构建在 Cloudflare 全球网络之上的向量数据库用于语义搜索、推荐系统、RAG 与分类等 AI 应用场景。在开始任何配置操作前有三个全局事实决定了后续所有命令的写法参见 Vectorize 概览文档索引配置不可变dimensions向量维度与metric距离度量在索引创建后无法修改只能新建索引并迁移数据数据写入为异步最终一致插入/更新/删除请求立即返回但向量需要 510 秒才能被查询命中索引的定位决策在 SKILL.md 的决策树中向量嵌入AI/语义搜索场景对应vectorize/参考目录配置前应先确认这是否是你需要的存储方案。距离度量metric的选择创建索引时必须指定度量方式且一旦确定不可更改因此选择要慎重。仓库文档给出的决策建议是你在构建什么 ├─ 文本/语义搜索 → cosine最常用 ├─ 图像相似度 → euclidean ├─ 推荐系统 → dot-product └─ 已归一化向量 → dot-product度量适用场景分数含义cosine文本嵌入、语义相似度越高越接近1.0 为完全相同euclidean绝对距离、空间数据越低越接近0.0 为完全相同dot-product推荐系统、归一化向量越高越接近二、创建索引维度与度量的不可变决策2.1 创建命令npx wrangler vectorize create my-index --dimensions768 --metriccosinemy-index索引名称后续绑定与所有 CLI 操作都要引用它--dimensions768向量维度必须与你的嵌入模型输出维度严格一致见下方模型维度对照表--metriccosine距离度量按上节决策树选择。⚠️ 维度与度量不可变Immutable——索引创建后无法更改dimensions和metric。如果后续换用不同维度的嵌入模型必须创建新索引并迁移全部数据见 gotchas 文档 中的 Index Config Immutable 条目。2.2 维度上限与模型对照VectorizeV2单个索引支持最多 1536 维的 32 位浮点向量、最多 1000 万个向量。常见的 Workers AI 文本嵌入模型及其维度来源于 patterns 文档模型维度备注cf/baai/bge-small-en-v1.5384轻量cf/baai/bge-base-en-v1.5768推荐cf/baai/bge-large-en-v1.51024高精度--dimensions必须与模型输出维度完全一致否则查询时会产生维度不匹配错误这是 gotchas 文档列出的常见故障点之一。三、Worker 绑定让运行时访问索引3.1 配置文件声明在wrangler.jsonc中声明 Vectorize 绑定// wrangler.jsonc { vectorize: [ { binding: VECTORIZE, index_name: my-index } ] }bindingWorker 运行时环境变量名建议使用全大写常量命名如VECTORIZEindex_name对应第 2.1 节创建的索引名称。3.2 TypeScript 类型声明在 Worker 入口中声明Env接口使绑定获得完整的类型提示interface Env { VECTORIZE: Vectorize; }绑定完成后即可在代码中调用运行时 API。最小验证示例来源于 README 快速开始const matches await env.VECTORIZE.query(queryVector, { topK: 5 });部署前的身份认证执行npx wrangler whoami确认已登录否则部署会失败。交互环境用wrangler loginCI/CD 环境通过CLOUDFLARE_API_TOKEN环境变量认证详见 SKILL.md 认证章节 与 wrangler 认证文档。3.3 与查询相关的绑定配置联动绑定只是入口查询时的行为由运行时参数控制。以下为 api.md 中与配置强相关的查询参数参数取值说明topK1100返回结果数使用returnValues或returnMetadata: all时上限降为 20returnMetadatanone/indexed/allindexed只返回索引过的元数据字符串仅前 64 字节all返回完整元数据namespace字符串租户分区先过滤再做向量搜索filter对象依赖元数据索引的过滤条件四、元数据索引必须先于数据创建的过滤基础设施4.1 为什么要先创建元数据索引必须在插入向量之前创建——已存在的向量不会被追溯索引retroactively indexed。这是配置阶段最容易踩的坑如果先灌数据再建索引已有的向量元数据无法被过滤只能重新上传全部数据。4.2 创建命令wrangler vectorize create-metadata-index my-index --property-namecategory --typestring wrangler vectorize create-metadata-index my-index --property-nameprice --typenumber每个索引最多创建10 个元数据索引。--property-name支持点号表示嵌套字段如product.category--type决定索引的数据类型类型用途string分类、标签仅索引前 64 字节number价格、时间戳boolean标志位64 字节截断细节string类型的元数据在索引时只取前 64 字节returnMetadata: indexed返回时也只返回前 64 字节。需要完整元数据应使用all代价是 topK 上限降为 20。4.3 元数据过滤操作符创建好元数据索引后查询的filter参数才可用来源于 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。典型混合过滤示例多租户 时间范围见 patterns 文档const matches await env.VECTORIZE.query(vec, { topK: 20, filter: { category: { $in: [tech, science] }, published: { $gte: lastMonthTimestamp } } });五、CLI 命令全集索引与向量的日常运维配置文档给出的完整命令清单按用途分为三组5.1 索引管理wrangler vectorize list # 列出所有索引 wrangler vectorize info index-name # 查看索引详情维度、度量、向量数 wrangler vectorize delete index-name # 删除索引5.2 向量操作wrangler vectorize insert index-name --fileembeddings.ndjson # 从 NDJSON 文件批量插入 wrangler vectorize get index-name --idsid1,id2 # 按 ID 取回向量 wrangler vectorize delete-by-ids index-name --idsid1,id2 # 按 ID 删除5.3 元数据索引管理wrangler vectorize list-metadata-index index-name # 列出已建元数据索引 wrangler vectorize delete-metadata-index index-name --property-namefield # 删除元数据索引CLI 批量操作与运行时 API 对应insert与 API 的insert一致重复 ID 保留先插入的需要覆盖语义时应使用运行时upsert重复 ID 保留后插入的。六、NDJSON 批量上传格式、限制与异步语义6.1 文件格式CLI 的--file参数接收NDJSON每行一个 JSON 对象格式的向量数据{id: 1, values: [0.1, 0.2, ...], metadata: {category: docs}} {id: 2, values: [0.4, 0.5, ...], namespace: tenant-abc}字段说明与 api.md 的 VectorizeVector 类型 对应字段约束id字符串最长 64 字节values数值数组长度必须等于索引维度namespace可选租户分区最长 64 字节metadata可选最大 10 KiB6.2 文件限制限制每文件最多 5000 个向量文件最大 100 MB。6.3 写入的异步性插入请求返回后向量需要510 秒才可查询配置文档强调的异步变更语义。生产环境在插入后立即查询会出现无结果这属于预期行为而非故障。排查清单见 gotchas 文档插入后等待 510 秒再查检查 namespace 拼写大小写敏感确认元数据索引已存在检查向量维度是否与索引一致。七、运行时 API 补充与配置配套的写入与查询参数配置文档聚焦 CLI 与绑定实际生产代码还需要配套的运行时 API。以下要点直接决定配置是否生效7.1 批量写入上限单次 500 个向量Workers API 强制单次调用最多 500 个向量该限制未公开文档化超出会静默截断必须显式分批见 patterns 批量摄入示例const BATCH 500; for (let i 0; i vectors.length; i BATCH) { await env.VECTORIZE.upsert(vectors.slice(i, i BATCH)); }分批带来的吞吐差异显著逐条插入约 1K 向量/分钟而批量写入可达 200K 向量/分钟。7.2 查询参数与性能权衡配置topK 上限速度不带元数据100最快returnMetadata: indexed100快returnMetadata: all20较慢returnValues: true20较慢官方推荐returnMetadata: indexed作为速度与数据量的最佳平衡点。7.3 其他常用操作// 按 ID 取回V2 还支持用已有向量查询的 queryById const vectors await env.VECTORIZE.getByIds([id1, id2]); // 删除单次最多 1000 个 ID await env.VECTORIZE.deleteByIds([id1, id2]); // 索引信息{ dimensions, metric, vectorCount } const info await env.VECTORIZE.describe();八、基数最佳实践高基数元数据的分桶策略配置文档特别强调高基数high-cardinality元数据值会拖慢过滤性能应将其分桶为有限集合。典型反例是毫秒级时间戳——每个向量的时间戳几乎都不同无法利用索引过滤正确做法是按 5 分钟窗口分桶// ❌ 毫秒级时间戳高基数过滤效率低 metadata: { timestamp: Date.now() } // ✅ 5 分钟分桶低基数可利用索引 metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }同样的思路适用于任何连续值字段先分桶成离散集合再配合$gte/$lt等操作符做范围查询如按timestamp_bucket过滤近 N 分钟的数据。多租户隔离的基数决策如果元数据用于多租户隔离请参考 README 多租户策略租户数量 ├─ 5 万 → 使用 namespace推荐 │ ├─ 最快向量搜索前过滤 │ └─ 严格隔离 ├─ 5 万 → 使用元数据过滤 │ ├─ 较慢向量搜索后过滤 │ └─ 需要元数据索引 └─ 每租户独立索引 → 仅当合规强制要求 └─ 付费计划每账户上限 5 万索引注意 namespace 配额付费计划 5 万个免费计划仅 1 千个。九、生产环境检查清单与常见错误配置文档给出的部署前检查清单逐项核验以正确的维度创建索引——维度与嵌入模型输出一致且创建后不可改先创建元数据索引——在任何向量插入之前完成否则需全量重传测试批量上传——用 5000 向量/100MB 以内的 NDJSON 文件走通wrangler vectorize insert配置绑定——wrangler.jsonc中声明vectorize绑定并核对index_name部署 Worker——先wrangler whoami确认认证再执行部署验证查询——插入后等待 510 秒再查询确认结果与过滤条件符合预期。常见配置错误速查来源于 gotchas 文档错误后果正确做法嵌入形状错误维度不匹配从 Workers AI 响应中提取result.data[0]而非整个响应数据插入后才建元数据索引已有向量无法被过滤必须全部重传re-upsert混淆 insert 与 upsert数据覆盖行为不符预期insert忽略重复保留首个upsert覆盖保留末个不批量写入吞吐极低约 1K/分钟按 500 个/批分块约 200K/分钟批量调用超 500静默截断丢数据严格slice分批核心限制速查V2资源限制每索引向量数10,000,000最大维度1536批量 upsertWorkers500索引的字符串元数据64 字节元数据索引数10namespace 数50,000付费/ 1,000免费十、配套参考文档本指南对应的完整参考文件位于仓库skills/.curated/cloudflare-deploy/references/vectorize/目录按任务选择阅读README.md概览、度量选择、多租户策略、语义搜索与 RAG 工作流api.md运行时 API、类型定义、过滤操作符、性能对照configuration.md本文档原始出处索引/绑定/元数据索引/CLI 配置patterns.mdWorkers AI、OpenAI、LangChain 集成RAG 与多租户模式gotchas.md限制、常见错误与故障排查。部署层面的大局决策可参考技能总纲 SKILL.md其中 I need to store data 决策树会将向量嵌入场景指向本参考目录结合 Workers AI 参考 可实现嵌入生成 向量检索 LLM 生成的完整 RAG 链路。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Vectorize 配置实战指南：索引创建、Worker 绑定、元数据过滤与批量写入（Codex Skills 参考）
Cloudflare Vectorize 配置实战指南索引创建、Worker 绑定、元数据过滤与批量写入Codex Skills 参考【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以仓库内 Vectorize 配置文档 为核心骨架系统讲解 Cloudflare Vectorize 向量数据库的完整配置链路——从创建索引、配置 Worker 绑定到元数据索引、CLI 批量操作与基数优化实践并深入解析其不可变配置约束与生产环境部署清单。读完本文你将掌握一套可直接复制到生产环境的 Vectorize 配置流程并理解每个配置决策背后的源码级原理与运行时行为。一、配置之前理解 Vectorize 的核心约束Cloudflare Vectorize 是构建在 Cloudflare 全球网络之上的向量数据库用于语义搜索、推荐系统、RAG 与分类等 AI 应用场景。在开始任何配置操作前有三个全局事实决定了后续所有命令的写法参见 Vectorize 概览文档索引配置不可变dimensions向量维度与metric距离度量在索引创建后无法修改只能新建索引并迁移数据数据写入为异步最终一致插入/更新/删除请求立即返回但向量需要 510 秒才能被查询命中索引的定位决策在 SKILL.md 的决策树中向量嵌入AI/语义搜索场景对应vectorize/参考目录配置前应先确认这是否是你需要的存储方案。距离度量metric的选择创建索引时必须指定度量方式且一旦确定不可更改因此选择要慎重。仓库文档给出的决策建议是你在构建什么 ├─ 文本/语义搜索 → cosine最常用 ├─ 图像相似度 → euclidean ├─ 推荐系统 → dot-product └─ 已归一化向量 → dot-product度量适用场景分数含义cosine文本嵌入、语义相似度越高越接近1.0 为完全相同euclidean绝对距离、空间数据越低越接近0.0 为完全相同dot-product推荐系统、归一化向量越高越接近二、创建索引维度与度量的不可变决策2.1 创建命令npx wrangler vectorize create my-index --dimensions768 --metriccosinemy-index索引名称后续绑定与所有 CLI 操作都要引用它--dimensions768向量维度必须与你的嵌入模型输出维度严格一致见下方模型维度对照表--metriccosine距离度量按上节决策树选择。⚠️ 维度与度量不可变Immutable——索引创建后无法更改dimensions和metric。如果后续换用不同维度的嵌入模型必须创建新索引并迁移全部数据见 gotchas 文档 中的 Index Config Immutable 条目。2.2 维度上限与模型对照VectorizeV2单个索引支持最多 1536 维的 32 位浮点向量、最多 1000 万个向量。常见的 Workers AI 文本嵌入模型及其维度来源于 patterns 文档模型维度备注cf/baai/bge-small-en-v1.5384轻量cf/baai/bge-base-en-v1.5768推荐cf/baai/bge-large-en-v1.51024高精度--dimensions必须与模型输出维度完全一致否则查询时会产生维度不匹配错误这是 gotchas 文档列出的常见故障点之一。三、Worker 绑定让运行时访问索引3.1 配置文件声明在wrangler.jsonc中声明 Vectorize 绑定// wrangler.jsonc { vectorize: [ { binding: VECTORIZE, index_name: my-index } ] }bindingWorker 运行时环境变量名建议使用全大写常量命名如VECTORIZEindex_name对应第 2.1 节创建的索引名称。3.2 TypeScript 类型声明在 Worker 入口中声明Env接口使绑定获得完整的类型提示interface Env { VECTORIZE: Vectorize; }绑定完成后即可在代码中调用运行时 API。最小验证示例来源于 README 快速开始const matches await env.VECTORIZE.query(queryVector, { topK: 5 });部署前的身份认证执行npx wrangler whoami确认已登录否则部署会失败。交互环境用wrangler loginCI/CD 环境通过CLOUDFLARE_API_TOKEN环境变量认证详见 SKILL.md 认证章节 与 wrangler 认证文档。3.3 与查询相关的绑定配置联动绑定只是入口查询时的行为由运行时参数控制。以下为 api.md 中与配置强相关的查询参数参数取值说明topK1100返回结果数使用returnValues或returnMetadata: all时上限降为 20returnMetadatanone/indexed/allindexed只返回索引过的元数据字符串仅前 64 字节all返回完整元数据namespace字符串租户分区先过滤再做向量搜索filter对象依赖元数据索引的过滤条件四、元数据索引必须先于数据创建的过滤基础设施4.1 为什么要先创建元数据索引必须在插入向量之前创建——已存在的向量不会被追溯索引retroactively indexed。这是配置阶段最容易踩的坑如果先灌数据再建索引已有的向量元数据无法被过滤只能重新上传全部数据。4.2 创建命令wrangler vectorize create-metadata-index my-index --property-namecategory --typestring wrangler vectorize create-metadata-index my-index --property-nameprice --typenumber每个索引最多创建10 个元数据索引。--property-name支持点号表示嵌套字段如product.category--type决定索引的数据类型类型用途string分类、标签仅索引前 64 字节number价格、时间戳boolean标志位64 字节截断细节string类型的元数据在索引时只取前 64 字节returnMetadata: indexed返回时也只返回前 64 字节。需要完整元数据应使用all代价是 topK 上限降为 20。4.3 元数据过滤操作符创建好元数据索引后查询的filter参数才可用来源于 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。典型混合过滤示例多租户 时间范围见 patterns 文档const matches await env.VECTORIZE.query(vec, { topK: 20, filter: { category: { $in: [tech, science] }, published: { $gte: lastMonthTimestamp } } });五、CLI 命令全集索引与向量的日常运维配置文档给出的完整命令清单按用途分为三组5.1 索引管理wrangler vectorize list # 列出所有索引 wrangler vectorize info index-name # 查看索引详情维度、度量、向量数 wrangler vectorize delete index-name # 删除索引5.2 向量操作wrangler vectorize insert index-name --fileembeddings.ndjson # 从 NDJSON 文件批量插入 wrangler vectorize get index-name --idsid1,id2 # 按 ID 取回向量 wrangler vectorize delete-by-ids index-name --idsid1,id2 # 按 ID 删除5.3 元数据索引管理wrangler vectorize list-metadata-index index-name # 列出已建元数据索引 wrangler vectorize delete-metadata-index index-name --property-namefield # 删除元数据索引CLI 批量操作与运行时 API 对应insert与 API 的insert一致重复 ID 保留先插入的需要覆盖语义时应使用运行时upsert重复 ID 保留后插入的。六、NDJSON 批量上传格式、限制与异步语义6.1 文件格式CLI 的--file参数接收NDJSON每行一个 JSON 对象格式的向量数据{id: 1, values: [0.1, 0.2, ...], metadata: {category: docs}} {id: 2, values: [0.4, 0.5, ...], namespace: tenant-abc}字段说明与 api.md 的 VectorizeVector 类型 对应字段约束id字符串最长 64 字节values数值数组长度必须等于索引维度namespace可选租户分区最长 64 字节metadata可选最大 10 KiB6.2 文件限制限制每文件最多 5000 个向量文件最大 100 MB。6.3 写入的异步性插入请求返回后向量需要510 秒才可查询配置文档强调的异步变更语义。生产环境在插入后立即查询会出现无结果这属于预期行为而非故障。排查清单见 gotchas 文档插入后等待 510 秒再查检查 namespace 拼写大小写敏感确认元数据索引已存在检查向量维度是否与索引一致。七、运行时 API 补充与配置配套的写入与查询参数配置文档聚焦 CLI 与绑定实际生产代码还需要配套的运行时 API。以下要点直接决定配置是否生效7.1 批量写入上限单次 500 个向量Workers API 强制单次调用最多 500 个向量该限制未公开文档化超出会静默截断必须显式分批见 patterns 批量摄入示例const BATCH 500; for (let i 0; i vectors.length; i BATCH) { await env.VECTORIZE.upsert(vectors.slice(i, i BATCH)); }分批带来的吞吐差异显著逐条插入约 1K 向量/分钟而批量写入可达 200K 向量/分钟。7.2 查询参数与性能权衡配置topK 上限速度不带元数据100最快returnMetadata: indexed100快returnMetadata: all20较慢returnValues: true20较慢官方推荐returnMetadata: indexed作为速度与数据量的最佳平衡点。7.3 其他常用操作// 按 ID 取回V2 还支持用已有向量查询的 queryById const vectors await env.VECTORIZE.getByIds([id1, id2]); // 删除单次最多 1000 个 ID await env.VECTORIZE.deleteByIds([id1, id2]); // 索引信息{ dimensions, metric, vectorCount } const info await env.VECTORIZE.describe();八、基数最佳实践高基数元数据的分桶策略配置文档特别强调高基数high-cardinality元数据值会拖慢过滤性能应将其分桶为有限集合。典型反例是毫秒级时间戳——每个向量的时间戳几乎都不同无法利用索引过滤正确做法是按 5 分钟窗口分桶// ❌ 毫秒级时间戳高基数过滤效率低 metadata: { timestamp: Date.now() } // ✅ 5 分钟分桶低基数可利用索引 metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }同样的思路适用于任何连续值字段先分桶成离散集合再配合$gte/$lt等操作符做范围查询如按timestamp_bucket过滤近 N 分钟的数据。多租户隔离的基数决策如果元数据用于多租户隔离请参考 README 多租户策略租户数量 ├─ 5 万 → 使用 namespace推荐 │ ├─ 最快向量搜索前过滤 │ └─ 严格隔离 ├─ 5 万 → 使用元数据过滤 │ ├─ 较慢向量搜索后过滤 │ └─ 需要元数据索引 └─ 每租户独立索引 → 仅当合规强制要求 └─ 付费计划每账户上限 5 万索引注意 namespace 配额付费计划 5 万个免费计划仅 1 千个。九、生产环境检查清单与常见错误配置文档给出的部署前检查清单逐项核验以正确的维度创建索引——维度与嵌入模型输出一致且创建后不可改先创建元数据索引——在任何向量插入之前完成否则需全量重传测试批量上传——用 5000 向量/100MB 以内的 NDJSON 文件走通wrangler vectorize insert配置绑定——wrangler.jsonc中声明vectorize绑定并核对index_name部署 Worker——先wrangler whoami确认认证再执行部署验证查询——插入后等待 510 秒再查询确认结果与过滤条件符合预期。常见配置错误速查来源于 gotchas 文档错误后果正确做法嵌入形状错误维度不匹配从 Workers AI 响应中提取result.data[0]而非整个响应数据插入后才建元数据索引已有向量无法被过滤必须全部重传re-upsert混淆 insert 与 upsert数据覆盖行为不符预期insert忽略重复保留首个upsert覆盖保留末个不批量写入吞吐极低约 1K/分钟按 500 个/批分块约 200K/分钟批量调用超 500静默截断丢数据严格slice分批核心限制速查V2资源限制每索引向量数10,000,000最大维度1536批量 upsertWorkers500索引的字符串元数据64 字节元数据索引数10namespace 数50,000付费/ 1,000免费十、配套参考文档本指南对应的完整参考文件位于仓库skills/.curated/cloudflare-deploy/references/vectorize/目录按任务选择阅读README.md概览、度量选择、多租户策略、语义搜索与 RAG 工作流api.md运行时 API、类型定义、过滤操作符、性能对照configuration.md本文档原始出处索引/绑定/元数据索引/CLI 配置patterns.mdWorkers AI、OpenAI、LangChain 集成RAG 与多租户模式gotchas.md限制、常见错误与故障排查。部署层面的大局决策可参考技能总纲 SKILL.md其中 I need to store data 决策树会将向量嵌入场景指向本参考目录结合 Workers AI 参考 可实现嵌入生成 向量检索 LLM 生成的完整 RAG 链路。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考