StructArray を使用した基本的なベクトル検索

このページでは、StructArrayフィールド内のベクトルサブフィールドに対してベクトル検索を実行できます。StructArrayは、各エンティティに格納された埋め込みリストを評価する「EmbeddingList検索」と、各Struct要素を個別に検索する「要素レベル検索」という2つの基本的なベクトル検索モードをサポートしています。

このページでは、「StructArrayフィールドの作成」にあるtech_articles コレクションを使用します。このコレクションには、chunks という名前のStructArrayフィールドが含まれています。各チャンクには、テキスト、スカラーメタデータ、EmbeddingList検索用のインデックスを持つemb_list_vector という名前のベクトルサブフィールド、および要素レベル検索用のインデックスを持つemb という名前のベクトルサブフィールドが含まれています。

開始する前に

コレクションのスキーマ、データ、およびインデックスがすでに準備されていることを確認してください。

要件	準備場所
chunks などの StructArray フィールドを作成します。	StructArrayフィールドの作成
chunks フィールドにStructオブジェクトが含まれるエンティティを挿入します。	StructArrayフィールドへのデータの挿入
EmbeddingList検索用に、chunks[emb_list_vector] にMAX_SIM* インデックスを作成します。	StructArrayフィールドのインデックス作成
要素レベルの検索用に、chunks[emb] に対して通常のベクトルメトリックインデックスを作成します。	StructArrayフィールドのインデックス作成

検索モードの選択

アスペクト	EmbeddingList検索	要素レベル検索
対象サブフィールド	chunks[emb_list_vector]	chunks[emb]
クエリデータ	1つ以上のベクトルを含む埋め込みリスト。	通常のベクトル。
メトリックファミリー	MAX_SIM*、例えばMAX_SIM_COSINE など。	COSINE 、IP 、L2 などの通常のベクトルメトリック。
1つのヒットが表すもの	StructArray ベクトルサブフィールドがクエリの埋め込みリストと類似している、一致したエンティティ。	StructArray フィールド内の、一致した Struct 要素。
結果の粒度	エンティティレベル。	Struct 要素レベル。
オフセット	該当なし。	返される際、一致した Struct 要素の 0 を基点とする位置を識別します。
一般的な使用例	ColBERT、ColPali、およびその他の後期相互作用型検索パターン。	チャンクレベル、パッセージレベル、クリップレベル、パッチレベル、またはファクトレベルのリトリーブ。

EmbeddingList 検索の実行

クエリ自体に複数のベクトルが含まれており、対象の StructArray ベクトルのサブフィールドがMAX_SIM* メトリックでインデックス付けされている場合は、EmbeddingList 検索を使用します。結果はエンティティレベルの一致となります。

from pymilvus import MilvusClient
from pymilvus.client.embedding_list import EmbeddingList

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

query = EmbeddingList()
query.add([0.12, 0.21, 0.32, 0.44])
query.add([0.18, 0.23, 0.29, 0.36])

results = client.search(
    collection_name="tech_articles",
    data=[query],
    anns_field="chunks[emb_list_vector]",
    limit=3,
    output_fields=[
        "doc_id",
        "title",
        "category",
        "chunks[text]",
        "chunks[section]",
    ],
)

for hits in results:
    for hit in hits:
        print(hit["id"], hit["distance"], hit["entity"])

この検索モードでは、limit が各クエリに対して返されるエンティティの数を制御します。出力にはStructArrayのサブフィールドが含まれる場合がありますが、ヒット自体は特定のStruct要素ではなく、一致した親エンティティを表します。

要素レベルの検索を実行する

各Struct要素が個別にベクトル検索に参加する必要がある場合は、要素レベルの検索を使用します。クエリは通常のベクトルであり、対象となるベクトルサブフィールドには通常のベクトルメトリックによるインデックスが付けられている必要があります。

query_vector = [0.19, 0.24, 0.30, 0.37]

results = client.search(
    collection_name="tech_articles",
    data=[query_vector],
    anns_field="chunks[emb]",
    limit=5,
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[page]",
        "chunks[quality_score]",
    ],
)

for hits in results:
    for hit in hits:
        print(
            "doc_id:", hit["id"],
            "distance:", hit["distance"],
            "offset:", hit.get("offset"),
            "entity:", hit["entity"],
        )

要素レベル検索では、各ヒットは一致したStruct要素を表します。offset の値は、StructArrayフィールド内におけるその要素の0を基点とする位置です。クエリに一致するStruct要素が複数ある場合、同じエンティティが複数回出現する可能性があります。limit の値は、一意の親エンティティではなく、要素のヒットに適用されます。

結果の解釈

結果項目	EmbeddingList検索	要素レベルの検索
id	一致したエンティティの主キー。	一致した Struct 要素を含むエンティティの主キー。
distance またはスコア	クエリの埋め込みリストと保存済みの埋め込みリストとの間のスコアまたは距離。	クエリベクトルと一致した Struct 要素のベクトルとの間のスコアまたは距離。
offset	該当なし。	返される際の一致した Struct 要素の 0 を基点とする位置。
重複する主キー	結果はエンティティレベルであるため、単一のクエリでは発生しないことが予想されます。	同じエンティティ内の複数の Struct 要素が一致する可能性があるため、発生する可能性があります。
要求された StructArray 出力フィールド	一致したエンティティから返されます。	ターゲット API および SDK がサポートする要素レベルのヒットシェープで返されます。

よくある間違い

• 必須のサブフィールドパス構文 `chunks[emb]` の代わりに、chunks.emb を使用してしまう。

• 通常のベクトルメトリックでインデックス付けされたベクトルサブフィールドに対して、EmbeddingList クエリを使用すること。

• MAX_SIM* メトリックでインデックス化されたベクトルサブフィールドに対して、通常のベクトルクエリを使用すること。

• 要素レベルの検索（limit ）が、その数だけの一意な親エンティティを返すことを期待している。実際には、要素レベルのヒットが返されます。

• EmbeddingList検索が特定の要素オフセットを1つ返すことを期待している。しかし、エンティティレベルの一致が返される。

• 1つのベクトルサブフィールドを両方の検索モードで再利用している。各ベクトルサブフィールドは1つのインデックスのみを受け入れるため、別々のベクトルサブフィールドを使用する。

次の手順

1. スカラー条件による要素レベルの検索を制限するには、「StructArray を使用したフィルタリング検索」を参照してください。

2. スコアまたは距離の境界による検索については、「StructArray を使用した範囲検索」を参照してください。

3. 要素レベルの検索後、親エンティティごとに最大1つの結果を返すには、「StructArray を使用したグループ化検索」を参照してください。

4. StructArray 検索を他のベクトル検索と組み合わせるには、「StructArray を使用したハイブリッド検索」を参照してください。

5. サポートされているデータ型、メトリック、フィルター、およびバージョン固有の制限を確認するには、「StructArrayの制限」を参照してください。