Vectorize 常见陷阱

# Vectorize 常见陷阱 ## 关键警告 ### 异步变更 插入/更新/删除操作会立即返回，但向量在 5-10 秒内不可查询。 ### 批处理大小限制 **Workers API：每次调用最多 500 个向量**（未文档化，会静默截断） typescript // ✅ 分块为 500 for (let i = 0; i < vectors.length; i += 500) { await env.VECTORIZE.upsert(vectors.slice(i, i + 500)); } ### 元数据截断 `returnMetadata: "indexed"` 仅返回字符串的前 64 字节。使用 `"all"` 获取完整元数据（但最大 topK 会降至 20）。 ### topK 限制 | returnMetadata | returnValues | 最大 topK | |----------------|--------------|----------| | `"none"` / `"indexed"` | `false` | 100 | | `"all"` | 任意 | **20** | | 任意 | `true` | **20** | ### 优先创建元数据索引 在插入前创建 - 现有向量不会被追溯索引。 bash # ✅ 先创建索引 wrangler vectorize create-metadata-index my-index --property-name=category --type=string wrangler vectorize insert my-index --file=data.ndjson ### 索引配置不可变 创建后无法更改维度/度量标准。必须创建新索引并迁移。 ## 限制 (V2) | 资源 | 限制 | |----------|-------| | 每个索引的向量数 | 10,000,000 | | 最大维度 | 1536 | | 批量更新 (Workers) | **500** | | 索引字符串元数据 | **64 字节** | | 元数据索引 | 10 | | 命名空间 | 50,000 (付费) / 1,000 (免费) | ## 常见错误 1. **嵌入形状错误：** 从 Workers AI 提取 `result.data[0]` 2. **数据插入后创建元数据索引：** 需要重新插入所有向量 3. **Insert 与 Upsert：** `insert` 忽略重复项，`upsert` 会覆盖 4. **未进行批处理：** 单次插入约 1K/分钟，批处理约 200K+/分钟 ## 故障排除 **没有结果？** - 插入后等待 5-10 秒 - 检查命名空间拼写（区分大小写） - 验证元数据索引是否存在 - 检查维度不匹配 **元数据过滤无效？** - 必须在数据插入前存在索引 - 超过 64 字节的字符串会被截断 - 嵌套字段使用点号表示：`"product.category"` ## 模型维度 - `@cf/baai/bge-small-en-v1.5`: 384 - `@cf/baai/bge-base-en-v1.5`: 768 - `@cf/baai/bge-large-en-v1.5`: 1024