版本：v3.0.x

Basic Vector Search with StructArray

本页介绍如何在 StructArray 字段内的向量子字段上执行向量搜索。StructArray 支持两种基础向量搜索模式：EmbeddingList search，用于对每个 Entity 中存储的 embedding list 进行打分；以及 element-level search，用于独立搜索每个 Struct 元素。

本页使用 Create a StructArray Field 中的 tech_articles Collection。该 Collection 包含一个名为 chunks 的 StructArray 字段。每个 chunk 都包含文本、标量元数据、一个名为 emb_list_vector 且带有索引的向量子字段（用于 EmbeddingList search），以及一个名为 emb 且带有索引的向量子字段（用于 element-level search）。

开始前

确保已准备好 Collection Schema、数据和 Index。

要求	准备位置
创建一个 StructArray 字段，例如 `chunks`。	创建 StructArray 字段
插入 `chunks` 字段包含 Struct 对象的 Entity。	向 StructArray 字段插入数据
在 `chunks[emb_list_vector]` 上创建 `MAX_SIM*` Index，用于 EmbeddingList Search。	为 StructArray 字段创建 Index
在 `chunks[emb]` 上创建常规 vector-metric Index，用于 element-level search。	为 StructArray 字段创建 Index

警告

一个 vector field 或 vector subfield 只能接受一个 Index。如果你需要同时执行 EmbeddingList search 和 element-level search，请创建两个独立的 vector subfield。在本页中，chunks[emb_list_vector] 已为 EmbeddingList search 创建 Index，chunks[emb] 已为 element-level search 创建 Index。

选择搜索模式

维度	EmbeddingList search	Element-level search
目标子字段	`chunks[emb_list_vector]`	`chunks[emb]`
查询数据	包含一个或多个向量的 embedding list。	普通向量。
Metric 系列	`MAX_SIM*`，例如 `MAX_SIM_COSINE`。	常规向量 metric，例如 `COSINE`、`IP` 或 `L2`。
单条命中表示的内容	匹配到的 Entity，其 StructArray 向量子字段与查询 embedding list 相似。	StructArray 字段中匹配到的 Struct 元素。
结果粒度	Entity 级别。	Struct 元素级别。
Offset	不适用。	返回结果时用于标识匹配 Struct 元素从零开始的位置。
典型用途	ColBERT、ColPali 以及其他 late-interaction 检索模式。	chunk 级、passage 级、clip 级、patch 级或 fact 级检索。

Run EmbeddingList search

当查询本身包含多个向量，并且目标 StructArray 向量子字段使用 MAX_SIM* metric 建立索引时，使用 EmbeddingList search。搜索结果是 Entity 级别的匹配。

Python
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 控制每个查询返回的 Entity 数量。输出可以包含 StructArray 子字段，但命中的结果本身表示匹配的父 Entity，而不是某个特定的 Struct 元素。

如需完整的 ColBERT 或 ColPali 风格演示，请参阅 Search with Embedding Lists。本页仅介绍基本的 StructArray search 行为。

执行 element-level search

当每个 Struct 元素都需要独立参与 vector search 时，请使用 element-level search。查询是常规 vector，目标 vector 子字段必须使用常规 vector metric 建立索引。

Python
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"],
        )

在 element-level search 中，每个命中结果表示一个匹配的 Struct 元素。offset 值是该元素在 StructArray 字段中的从零开始的位置。如果多个 Struct 元素匹配查询，同一个 entity 可以出现多次。limit 值作用于元素命中结果，而不是唯一的父 entity。

Interpret results

Result item	EmbeddingList search	Element-level search
`id`	匹配 Entity 的主键。	包含匹配 Struct element 的 Entity 的主键。
`distance` or score	查询 embedding list 与已存储 embedding list 之间的 score 或 distance。	查询 vector 与匹配的 Struct element vector 之间的 score 或 distance。
`offset`	不适用。	返回时匹配 Struct element 的从零开始的位置。
Repeated primary keys	对于单次查询通常不会出现，因为结果是 entity-level。	可能出现，因为同一 Entity 中的多个 Struct element 都可能匹配。
Requested StructArray output fields	从匹配的 Entity 返回。	按目标 API 和 SDK 支持的 element-level 命中结果形态返回。

常见错误

使用 chunks.emb，而不是必需的子字段路径语法 chunks[emb]。
对使用常规向量 metric 建立索引的向量子字段发起 EmbeddingList 查询。
对使用 MAX_SIM* metric 建立索引的向量子字段发起常规向量查询。
期望元素级搜索的 limit 返回相同数量的唯一父 Entity。它返回的是元素命中结果。
期望 EmbeddingList 搜索返回某个特定元素 offset。它返回的是 Entity 级匹配结果。
复用同一个向量子字段支持两种搜索模式。请使用不同的向量子字段，因为每个向量子字段只能接受一个索引。

下一步

如需通过标量条件限制元素级搜索，请阅读 Filtered Search with StructArray。
如需按分数或距离边界搜索，请阅读 Range Search with StructArray。
如需在元素级搜索后为每个父 Entity 最多返回一条结果，请阅读 Grouping Search with StructArray。
如需将 StructArray search 与其他 vector search 结合使用，请阅读 Hybrid Search with StructArray。
如需查看支持的数据类型、指标、过滤器和特定版本限制，请阅读 StructArray Limits。

开始前​

选择搜索模式​

Run EmbeddingList search​

执行 element-level search​

Interpret results​

常见错误​

下一步​

开始前

选择搜索模式

Run EmbeddingList search

执行 element-level search

Interpret results

常见错误

下一步