ベクトルをクエリする

インデックスのクエリ（ベクトル検索）では、入力ベクトルを渡し、設定した距離メトリクスに基づいて最も近いベクトルを返します。

任意で、メタデータフィルターや名前空間（namespace）を適用し、ベクトル検索の範囲を絞れます。

クエリの例

ベクトルをクエリとしてインデックスに渡すには、インデックス自身の query() メソッドを使います。

クエリベクトルは、JavaScript の数値配列、32 ビット浮動小数点、または 64 ビット浮動小数点です。型は number[]、Float32Array、Float64Array です。ベクトルを挿入するときと異なり、クエリベクトルに ID やメタデータは不要です。

// query vector dimensions must match the Vectorize index dimension being queried
let queryVector = [54.8, 5.5, 3.1, ...];
let matches = await env.YOUR_INDEX.query(queryVector);

Vectorize インデックスに設定した距離メトリクスに応じて、次のような一致結果が返ります。距離メトリクスが cosine の場合のレスポンス例です。

{
	"count": 5,
	"matches": [
		{ "score": 0.999909486, "id": "5" },
		{ "score": 0.789848214, "id": "4" },
		{ "score": 0.720476967, "id": "4444" },
		{ "score": 0.463884663, "id": "6" },
		{ "score": 0.378282232, "id": "1" }
	]
}

返す件数や、結果にメタデータと値を含めるかは、任意で変更できます。

// query vector dimensions must match the Vectorize index dimension being queried
let queryVector = [54.8, 5.5, 3.1, ...];
// topK defaults to 5; returnValues defaults to false; returnMetadata defaults to "none"
let matches = await env.YOUR_INDEX.query(queryVector, {
	topK: 1,
	returnValues: true,
	returnMetadata: "all",
});

Vectorize インデックスに設定した距離メトリクスに応じて、次のような一致結果が返ります。距離メトリクスが cosine の場合のレスポンス例です。

{
	"count": 1,
	"matches": [
		{
			"score": 0.999909486,
			"id": "5",
			"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316, ...],
			"metadata": { "url": "/products/sku/55519183" }
		}
	]
}

ほかの例は Vectorize API を参照してください。

ベクトル識別子でクエリする

Vectorize では、インデックスにすでに存在するベクトルに似たベクトルを、queryById() 操作で検索できます。これは getById() と query() を組み合わせた 1 回の操作と考えられます。

// the query operation would yield results if a vector with id `some-vector-id` is already present in the index.
let matches = await env.YOUR_INDEX.queryById("some-vector-id");

スコアの精度とクエリの正確さを制御する

ベクトルをクエリするとき、高精度スコアリングと近似スコアリングのどちらかを指定できます。高精度スコアリングは、一致スコアの精度とクエリ結果の正確さを上げます。近似スコアリングは応答時間を短くします。近似スコアリングでは、返されるスコアはクエリと返されたベクトルの実際の距離／類似度の近似値です。これはクエリのデフォルトで、正確さとレイテンシのバランスがよいためです。

高精度スコアリングは、クエリで returnValues: true を設定すると有効になります。この設定により、Vectorize は一致したベクトルの元の値を使い、正確な一致スコアを計算し、結果の正確さを上げます。処理するデータが増えるため、クエリのレイテンシは長くなります。

Workers AI

Workers AI のテキスト埋め込みモデルで埋め込み（embedding）を生成する場合、env.AI.run() のレスポンス型はオブジェクトです。レスポンスベクトルの shape（例: [1,768]）と、ベクトル配列としての data の両方が含まれます。

interface EmbeddingResponse {
	shape: number[];
	data: number[][];
}

let userQuery = "a query from a user or service";
const queryVector: EmbeddingResponse = await env.AI.run(
	"@cf/baai/bge-base-en-v1.5",
	{
		text: [userQuery],
	},
);

Vectorize インデックスの query() メソッドにベクトルを渡すときは、トップレベルのレスポンスではなく、.data サブオブジェクト上のベクトル埋め込みそのものを渡します。

例:

let matches = await env.TEXT_EMBEDDINGS.query(queryVector.data[0], { topK: 1 });

queryVector または queryVector.data を渡すと、query() はエラーを返します。

OpenAI

OpenAI の JavaScript クライアント API ↗ と Embeddings API ↗ を使う場合、embeddings.create のレスポンス型はオブジェクトです。モデル、利用状況、要求したベクトル埋め込みが含まれます。

const openai = new OpenAI({ apiKey: env.YOUR_OPENAPI_KEY });

let userQuery = "a query from a user or service";

let embeddingResponse = await openai.embeddings.create({
	input: userQuery,
	model: "text-embedding-ada-002",
});

Workers AI と同様に、Vectorize インデックスをクエリするときは EmbeddingResponse ラッパーではなく、ベクトル埋め込みそのもの（.embedding[0]）を渡します。

let matches = await env.TEXT_EMBEDDINGS.query(embeddingResponse.embedding[0], {
	topK: 1,
});