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 インデックスで照会可能になるまで、通常は数秒かかります。

upsert 操作は、同じ ID のベクトルがなければ挿入し、同じ 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 フィールドでは、照会時にベクトルのメタデータを取得する方法を 3 つ選べます。

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 も含まれます。

ページネーション付きリクエストで、インデックス内のすべてのベクトル識別子を一覧します。1 ページあたり最大 1000 件のベクトル識別子を返します。

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

パラメーター:

• <index-name> - Vectorize インデックスの名前
• --count（任意）- 1 ページあたり返すベクトル 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",
	},
};

バインディング を使うと、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 オブジェクトの型と、ランタイム型 が生成されます。