Vectorize API 参考

本页介绍 Cloudflare Workers 中可用的 Vectorize API，包括用法示例。

let vectorsToInsert = [
	{ id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
	{ id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
];
let inserted = await env.YOUR_INDEX.insert(vectorsToInsert);

将向量插入索引。Vectorize 插入是异步的，插入操作返回该操作唯一的变更标识符。插入的向量通常需要数秒才能在 Vectorize 索引中可供查询。

若索引中已存在相同向量 ID 的向量，则仅插入具有新 ID 的向量。

若需更新现有向量，请使用 upsert 操作。

let vectorsToUpsert = [
	{ id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
	{ id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
	{ id: "768", values: [29.1, 5.7, 12.9, 15.4, 1.1] },
];
let upserted = await env.YOUR_INDEX.upsert(vectorsToUpsert);

将向量 upsert 到索引。Vectorize upsert 是异步的，upsert 操作返回该操作唯一的变更标识符。upsert 的向量通常需要数秒才能在 Vectorize 索引中可供查询。

若不存在相同 ID 的向量，upsert 操作会插入向量；若存在相同 ID，则会覆盖该向量。

Upsert 不会合并或组合现有向量与 upsert 向量的值或元数据：upsert 向量会完整替换现有向量。

let queryVector = [32.4, 6.55, 11.2, 10.3, 87.9];
let matches = await env.YOUR_INDEX.query(queryVector);

使用提供的向量查询索引，根据配置的距离度量返回最接近向量的分数。

• 通过设置 topK 配置返回匹配数（默认：5）
• 通过设置 returnValues: true 返回向量值（默认：false）
• 通过设置 returnMetadata: 'indexed' 或 returnMetadata: 'all' 返回向量元数据（默认：'none'）

let matches = await env.YOUR_INDEX.query(queryVector, {
	topK: 5,
	returnValues: true,
	returnMetadata: "all",
});

可配置 topK 以指定查询操作返回的匹配数。Vectorize 现在支持 topK 上限为 100。但是，当 returnValues 设为 true 或 returnMetadata 设为 all 时，topK 最大值为 50。

returnMetadata 字段提供三种在查询时获取向量元数据的方式：

1. none：不获取元数据。
2. indexed：仅获取已建立索引的元数据字段的元数据。此选项无延迟开销，但长文本字段可能被截断。
3. all：获取与向量关联的所有元数据。此选项可能使查询变慢，且 topK 限制为 50。

let matches = await env.YOUR_INDEX.queryById("some-vector-id");

使用索引中已存在的向量查询索引。

查询选项与上述 query 操作相同。

let matches = await env.YOUR_INDEX.queryById("some-vector-id", {
	topK: 5,
	returnValues: true,
	returnMetadata: "all",
});

let ids = ["11", "22", "33", "44"];
const vectors = await env.YOUR_INDEX.getByIds(ids);

按 ID 检索指定向量，包括值和元数据。

let idsToDelete = ["11", "22", "33", "44"];
const deleted = await env.YOUR_INDEX.deleteByIds(idsToDelete);

从当前索引中删除提供的向量 ID。Vectorize 删除是异步的，删除操作返回该操作唯一的变更标识符。向量通常需要数秒才能从 Vectorize 索引中移除。

const details = await env.YOUR_INDEX.describe();

直接检索给定索引的配置，包括配置的 dimensions 和距离 metric。

使用分页请求列出索引中的所有向量标识符，每页最多返回 1000 个向量标识符。

wrangler vectorize list-vectors <index-name> [--count=<number>] [--cursor=<cursor-string>]

参数：

• <index-name> - Vectorize 索引的名称
• --count（可选）- 每页返回的向量 ID 数量。必须在 1 到 1000 之间（默认：100）
• --cursor（可选）- 上一页响应中的分页游标，用于从该位置继续列出

有关分页行为和最佳实践的详细说明，请参阅列出向量最佳实践。

在指定属性上启用元数据过滤。最多 10 个属性。

运行以下 wrangler vectorize 命令：

wrangler vectorize create-metadata-index <index-name> --property-name='some-prop' --type='string'

允许 Vectorize 删除指定的元数据索引。

运行以下 wrangler vectorize 命令：

wrangler vectorize delete-metadata-index <index-name> --property-name='some-prop'

列出已启用元数据过滤的元数据属性。

运行以下 wrangler vectorize 命令：

wrangler vectorize list-metadata-index <index-name>

获取索引的更多详情。

运行以下 wrangler vectorize 命令：

wrangler vectorize info <index-name>

向量表示机器学习模型的向量嵌入输出。

• id - 索引中向量的唯一 string 标识符。应映射回生成向量值的文档、对象或数据库标识符的 ID。
• namespace - 索引内可选的分区键。操作按 namespace 执行，因此可用于在较大索引内创建隔离段。
• values - 作为向量嵌入本身的 number、Float32Array 或 Float64Array 数组。必须是稠密数组，且数组长度必须与索引上配置的 dimensions 匹配。
• metadata - 可选的键值对集合，可用于在向量旁存储额外元数据。

let vectorExample = {
	id: "12345",
	values: [32.4, 6.55, 11.2, 10.3, 87.9],
	metadata: {
		key: "value",
		hello: "world",
		url: "r2://bucket/some/object.json",
	},
};

绑定（binding） 允许你将资源（包括 Vectorize 索引或 R2 存储桶）附加到 Worker。

绑定在 Workers 项目关联的 Wrangler 配置文件 中定义，或通过项目的 Cloudflare 仪表板定义。

Vectorize 索引按名称绑定。名为 production-doc-search 的索引绑定如下所示：

{
	"vectorize": [
		{
			"binding": "PROD_SEARCH", // the index will be available as env.PROD_SEARCH in your Worker
			"index_name": "production-doc-search",
		},
	],
}

[[vectorize]]
binding = "PROD_SEARCH"
index_name = "production-doc-search"

更多详情请参阅绑定文档。

如果你使用 TypeScript，每当你修改 Wrangler 配置文件时，请运行 wrangler types。这将根据你的绑定生成 env 对象的类型，以及运行时类型。