Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

メタデータフィルタリング

最終更新 Markdown で表示Agent セットアップ

クエリには入力ベクトルに加え、各ベクトルに付いた ベクトルメタデータ でも絞り込めます。クエリ結果には、filter 条件に一致するベクトルだけが含まれます。先に filter を適用し、絞り込んだ集合から topK 件を取ります。

メタデータフィルターでクエリ範囲を狭めれば、特定の顧客 ID、テナント、製品カテゴリなど、ベクトルに付けた任意のメタデータで絞り込めます。

メタデータインデックス

Vectorize は既定で 名前空間 による絞り込みに対応します。ベクトルの別のメタデータプロパティで絞り込むには、メタデータインデックスを作成します。Vectorize インデックスあたり、メタデータインデックスは最大 10 個まで作成できます。

string、number、boolean 型のプロパティ向けメタデータインデックスに対応しています。詳細は メタデータインデックスを作成する を参照してください。

ベクトルあたり最大 10KiB のメタデータを保存できます。制限の一覧は Vectorize の制限 を参照してください。

number 型のメタデータインデックスでは、インデックスする数値の精度は float64 です。

string 型のメタデータインデックスでは、各ベクトルは文字列データの先頭 64B をインデックスします。切り捨ては UTF-8 の文字境界で行い、その上限内で最も長い整形式の UTF-8 部分文字列にします。そのため、インデックスした各プロパティについて、値の先頭 64B でフィルターできます。

対応する操作

query() メソッドの任意の filter プロパティで、メタデータフィルターを指定します。

演算子 説明
$eq 等しい
$ne 等しくない
$in いずれかに含まれる
$nin いずれにも含まれない
$lt より小さい
$lte 以下
$gt より大きい
$gte 以上
  • filter は空でないオブジェクトで、コンパクトな JSON 表現が 2048 バイト未満である必要があります。
  • filter オブジェクトのキーは空にできません。" | . を含められず(ドットはネスト用に予約)、$ で始められず、512 文字を超えられません。
  • $eq と $ne では、filter オブジェクトの非ネスト値は string、number、boolean、または null にできます。
  • $in と $nin では、filter オブジェクトの値は string、number、boolean、または null の配列にできます。
  • 上限の範囲クエリ($lt と $lte)は、同じフィルター内で下限の範囲クエリ($gt と $gte)と組み合わせられます。ほかの組み合わせはできません。
  • 範囲クエリ($lt、$lte、$gt、$gte)では、filter オブジェクトの非ネスト値は string または number にできます。文字列は辞書順です。
  • ベクトル数が多い範囲クエリ(約 1,000 万件以上)では、精度が下がることがあります。

名前空間とメタデータフィルターの比較

名前空間 とメタデータフィルターは、どちらもクエリのベクトル検索空間を狭めます。両方のフィルターを検討するときは、次の点を考慮してください。

  • 名前空間フィルターは、メタデータフィルターより先に適用されます。
  • ベクトルが所属できる名前空間は 1 つで、記載の 制限 が適用されます。ベクトルメタデータには、ベクトルあたりのメタデータ上限 まで複数のキーと値のペアを含められます。メタデータ値は型(string、boolean など)が違うため、より柔軟です。

有効な filter の例

暗黙の $eq 演算子

{ "streaming_platform": "netflix" }

明示的な演算子

{ "someKey": { "$ne": "hbo" } }

$in 演算子

{ "someKey": { "$in": ["hbo", "netflix"] } }

$nin 演算子

{ "someKey": { "$nin": ["hbo", "netflix"] } }

数値の範囲クエリ

{ "timestamp": { "$gte": 1734242400, "$lt": 1734328800 } }

文字列の範囲クエリ

範囲クエリは、文字列メタデータフィールドで プレフィックス検索 を実現できます。starts_with フィルターに近い動きです。

たとえば、次のフィルターは "net" で始まるすべての値に一致します。

{ "someKey": { "$gte": "net", "$lt": "neu" } }

複数キーによる暗黙の論理 AND

{ "pandas.nice": 42, "someKey": { "$ne": "someValue" } }

.(ドット)でネストを表すキー

{ "pandas.nice": 42 }

// looks for { "pandas": { "nice": 42 } }

例

メタデータを追加する

次のインデックス定義で:

npx wrangler vectorize create tutorial-index --dimensions=32 --metric=cosine

メタデータインデックスを作成します。

npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string
npx wrangler vectorize create-metadata-index tutorial-index --property-name=streaming_platform --type=string

メタデータは、ベクトルの挿入または upsert 時に追加できます。

const newMetadataVectors: Array<VectorizeVector> = [
	{
		id: "1",
		values: [32.4, 74.1, 3.2, ...],
		metadata: { url: "/products/sku/13913913", streaming_platform: "netflix" },
	},
	{
		id: "2",
		values: [15.1, 19.2, 15.8, ...],
		metadata: { url: "/products/sku/10148191", streaming_platform: "hbo" },
	},
	{
		id: "3",
		values: [0.16, 1.2, 3.8, ...],
		metadata: { url: "/products/sku/97913813", streaming_platform: "amazon" },
	},
	{
		id: "4",
		values: [75.1, 67.1, 29.9, ...],
		metadata: { url: "/products/sku/418313", streaming_platform: "netflix" },
	},
	{
		id: "5",
		values: [58.8, 6.7, 3.4, ...],
		metadata: { url: "/products/sku/55519183", streaming_platform: "hbo" },
	},
];

// Upsert vectors with added metadata, returning a count of the vectors upserted and their vector IDs
let upserted = await env.YOUR_INDEX.upsert(newMetadataVectors);

クエリの例

query() メソッドを使います。

let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
let originalMatches = await env.YOUR_INDEX.query(queryVector, {
	topK: 3,
	returnValues: true,
	returnMetadata: 'all',
});

メタデータフィルターなしの結果:

{
	"count": 3,
	"matches": [
		{
			"id": "5",
			"score": 0.999909486,
			"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316],
			"metadata": {
				"url": "/products/sku/55519183",
				"streaming_platform": "hbo"
			}
		},
		{
			"id": "4",
			"score": 0.789848214,
			"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
			"metadata": {
				"url": "/products/sku/418313",
				"streaming_platform": "netflix"
			}
		},
		{
			"id": "2",
			"score": 0.611976262,
			"values": [15.100000381469727, 19.200000762939453, 15.800000190734863],
			"metadata": {
				"url": "/products/sku/10148191",
				"streaming_platform": "hbo"
			}
		}
	]
}

同じ query() メソッドに filter プロパティを付けると、メタデータフィルターを使えます。

let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
let metadataMatches = await env.YOUR_INDEX.query(queryVector, {
	topK: 3,
	filter: { streaming_platform: "netflix" },
	returnValues: true,
	returnMetadata: 'all',
});

メタデータフィルターありの結果:

{
	"count": 2,
	"matches": [
		{
			"id": "4",
			"score": 0.789848214,
			"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
			"metadata": {
				"url": "/products/sku/418313",
				"streaming_platform": "netflix"
			}
		},
		{
			"id": "1",
			"score": 0.491185264,
			"values": [32.400001525878906, 74.0999984741211, 3.200000047683716],
			"metadata": {
				"url": "/products/sku/13913913",
				"streaming_platform": "netflix"
			}
		}
	]
}

制限

  • 現時点では、メタデータフィルターを使うには、ベクトルを挿入する 前 に Vectorize インデックスへメタデータインデックスを作成する必要があります。
  • メタデータフィルターに対応するのは、2023-12-06 以降に作成したインデックスだけです。それ以前に作成したインデックスは、メタデータフィルター対応へ移行できません。

役に立ちましたか?