Vectorize API 参考

# Vectorize API 参考 ## 类型 typescript interface VectorizeVector { id: string; // 最大 64 字节 values: number[]; // 必须匹配索引维度 namespace?: string; // 可选分区 (最大 64 字节) metadata?: Record; // 最大 10 KiB } ## 查询 typescript const matches = await env.VECTORIZE.query(queryVector, { topK: 10, // 最大 100 (若 returnValues/returnMetadata 为 "all" 则为 20) returnMetadata: "indexed", // "none" | "indexed" | "all" returnValues: false, namespace: "tenant-123", filter: { category: "docs" } }); // matches.matches[0] = { id, score, metadata? } **returnMetadata:** `"none"` (最快) → `"indexed"` (推荐) → `"all"` (topK 最大 20) **queryById (仅 V2):** 使用现有向量作为查询条件。 typescript await env.VECTORIZE.queryById("doc-123", { topK: 5 }); ## 插入/更新 (Insert/Upsert) typescript // Insert: 忽略重复 (保留第一个) await env.VECTORIZE.insert([{ id, values, metadata }]); // Upsert: 覆盖重复 (保留最后一个) await env.VECTORIZE.upsert([{ id, values, metadata }]); **每次调用最多 500 个向量。** 5-10 秒后可查询。 ## 其他操作 typescript // 通过 ID 获取 const vectors = await env.VECTORIZE.getByIds(["id1", "id2"]); // 删除 (每次调用最多 1000 个 ID) await env.VECTORIZE.deleteByIds(["id1", "id2"]); // 索引信息 const info = await env.VECTORIZE.describe(); // { dimensions, metric, vectorCount } ## 过滤 需要元数据索引。过滤操作符： | 操作符 | 示例 | |----------|---------| | `$eq` (隐式) | `{ category: "docs" }` | | `$ne` | `{ status: { $ne: "deleted" } }` | | `$in` / `$nin` | `{ tag: { $in: ["sale"] } }` | | `$lt`, `$lte`, `$gt`, `$gte` | `{ price: { $lt: 100 } }` | **约束：** 最大 2048 字节，键名不能包含点号或 `$`，值类型：字符串/数字/布尔值/null。 ## 性能 | 配置 | topK 限制 | 速度 | |--------------|------------|-------| | 无元数据 | 100 | 最快 | | `returnMetadata: "indexed"` | 100 | 快 | | `returnMetadata: "all"` | 20 | 较慢 | | `returnValues: true` | 20 | 较慢 | **批量操作：** 始终进行批量处理 (500/次调用) 以获得最佳吞吐量。 typescript for (let i = 0; i < vectors.length; i += 500) { await env.VECTORIZE.upsert(vectors.slice(i, i + 500)); }