搜尋聚合Compatible with Milvus 3.0.x

當購物者搜尋「適合日常訓練的黑色跑鞋」時，近似最近鄰（ANN）搜尋會根據向量相似度對產品進行排序，並回傳一個平面的 Top-K 清單。搜尋結果雖具相關性，但可能過於重複：以下例中，前六項結果中有四項是 A 品牌產品，而 B 品牌和 C 品牌則各出現一次。

平鋪式清單無法直接提供以分桶為導向的摘要。應用程式可能需要根據保留候選項數量或平均價格來比較各品牌，檢視每個品牌中少數具代表性的產品，或將結果組織成多個分桶層級。

搜尋彙總功能會根據選定的標量欄位，將保留的 ANN 候選項目歸類至不同區間。在此範例中，每個品牌即成為一個獨立的區間。Milvus 可針對每個區間計算統計數據、對區間進行排序，並附上代表性產品。應用程式可透過 `result.agg_buckets` 方法取得此「區間優先」的回應結果。

原本平鋪的運動鞋搜尋結果，將轉化為一組可供比較的品牌分桶

搜尋聚合並不會執行精確的全集合聚合。桶組的存在、計數、指標、排序以及代表性搜尋結果，皆取決於人工神經網路（ANN）與分組階段所保留的候選項目。

運作原理

依桶鍵分組的 ANN 候選項，並隨同計數、指標及代表性搜尋結果一併返回

1. 檢索候選項。Milvus 執行 ANN 搜尋以找出最接近查詢向量的實體。隨後，分組階段會針對每個完整的複合鍵保留有限數量的候選項。此「每鍵候選項配額」即為聚合樹中任何位置的最大TopHits.size ，或當未設定top_hits 時，則為1 。

2. 建立桶（bucket）。 SearchAggregation.fields 定義桶鍵。每個字段值的唯一組合都會產生一個獨立的鍵。如圖所示，fields=["brand"] 會產生(Brand A) 、(Brand B) 以及(Brand C) 這些桶鍵。具有相同鍵的保留候選項屬於同一個桶，並計入該桶的count 。SearchAggregation.size 會限制 Milvus 返回的桶數量。

3. 計算並返回結果。每個返回的桶皆包含其金鑰及保留候選項的數量。Milvus 亦可計算已設定的指標、對桶進行排序、返回代表性實體，以及建立子桶。result.agg_buckets 中的每個AggregationBucket 皆會公開key 、count 、metrics 、hits 及sub_groups 。當啟用「搜尋聚合」時，一般的搜尋命中清單將為空。

如圖所示，TopHits.size=4 提供每個關鍵字四個候選項的預算，因此保留的四個「品牌 A」候選項產生count: 4 。為使圖表簡潔，完成的「品牌 A」卡片僅顯示四個回傳代表性搜尋結果中的兩個。

當sub_aggregation 生效時，Milvus 會在每個父桶內重複執行步驟 2 和 3。人工神經網路（ANN）的召回率或每鍵候選預算的變動，都可能改變桶的數量、指標、排序、搜尋結果以及嵌套結果。

限制

在使用「搜尋彙總」功能前，請注意以下限制：

• 嵌套聚合：單一請求可包含一個根層級的SearchAggregation ，以及最多三個嵌套的sub_aggregation 層級，總計最多四層。

• 用於建立桶鍵的欄位： SearchAggregation.fields 支援布林值、整數、VARCHAR 及TIMESTAMPTZ 欄位。不支援FLOAT 、DOUBLE 、ARRAY 、JSON 、GEOMETRY 、TEXT 、向量或動態欄位。

• 度量欄位： count 接受"*" 或任何非JSON 且非動態的欄位，並在指定欄位時跳過NULL 的值。sum 與avg 接受整數及浮點數欄位。min 與max 此外還接受字串及TIMESTAMPTZ 欄位。

• 「Top Hits」排序欄位： TopHits.sort 接受可比的布林值、整數、浮點數、字串及TIMESTAMPTZ 欄位，以及_score 。它不支援ARRAY 、JSON 、GEOMETRY 、向量或動態欄位。

• 候選預算：聚合樹中任何位置的最大TopHits.size 值，即為每個完整複合鍵所保留的候選項數量。若無任何層級設定top_hits ，Milvus 將為每個鍵保留一個候選項。分桶count 及指標皆根據這些保留的候選項計算得出，因此變更TopHits.size 可能會影響這些數值。

• 可為空的桶位欄位： NULL 的值會形成其自身的桶位鍵。若要排除空桶位，請在搜尋請求中加入如brand is not null 之類的篩選條件。

• 重複欄位：同一欄位不得出現在多個SearchAggregation.fields 清單中。例如，若根聚合使用fields=["category"] ，則嵌套的sub_aggregation 便不能同時使用fields=["category"] 。

• 不支援的組合：搜尋聚合無法與offset 、搜尋迭代器、混合搜尋、高亮顯示器或分組搜尋結合使用。

• 回傳的條目：請將設定的結果條目最大數量維持在 10,000 個或以下。此最大數量的計算方式如下：

  number of query vectors × size at every aggregation level × largest TopHits.size at any level

  當未設定任何層級的 `TopHits` 時，請將 `1 ` 作為最後一項因子。例如，一個查詢向量、10 個根桶、每個根桶有 5 個子桶，以及每個子桶有 2 個命中，其設定的最大值為：

  1 × 10 × 5 × 2 = 100

使用搜尋彙總

根據您的目標選擇一個範例：

以下範例使用一個包含品牌、類別、顏色、價格和評分欄位的產品集合。所有品牌名稱、產品名稱、價格、評分及搜尋結果均為合成範例資料。請展開以下區段以建立該集合並定義共用搜尋變數。

from pymilvus import DataType, MilvusClient, SearchAggregation, TopHits

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

collection_name = "product_search_aggregation"

if client.has_collection(collection_name):
    client.drop_collection(collection_name)

schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=5)
schema.add_field("name", DataType.VARCHAR, max_length=200)
schema.add_field("brand", DataType.VARCHAR, max_length=100)
schema.add_field("category", DataType.VARCHAR, max_length=100)
schema.add_field("color", DataType.VARCHAR, max_length=50)
schema.add_field("price", DataType.DOUBLE)
schema.add_field("rating", DataType.DOUBLE)
schema.add_field("in_stock", DataType.BOOL)

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="embedding",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

client.create_collection(
    collection_name=collection_name,
    schema=schema,
    index_params=index_params,
    # Make preceding writes visible to searches from this client.
    consistency_level="Session",
)

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "embedding": [0.12, 0.42, 0.18, 0.66, 0.31],
            "name": "Runner A1",
            "brand": "Brand A",
            "category": "running_shoes",
            "color": "black",
            "price": 129.99,
            "rating": 4.7,
            "in_stock": True,
        },
        {
            "id": 2,
            "embedding": [0.10, 0.39, 0.20, 0.61, 0.29],
            "name": "Trail A2",
            "brand": "Brand A",
            "category": "running_shoes",
            "color": "blue",
            "price": 139.99,
            "rating": 4.6,
            "in_stock": True,
        },
        {
            "id": 3,
            "embedding": [0.14, 0.44, 0.19, 0.68, 0.33],
            "name": "Runner B1",
            "brand": "Brand B",
            "category": "running_shoes",
            "color": "white",
            "price": 159.99,
            "rating": 4.8,
            "in_stock": True,
        },
        {
            "id": 4,
            "embedding": [0.16, 0.41, 0.22, 0.62, 0.30],
            "name": "Runner C1",
            "brand": "Brand C",
            "category": "running_shoes",
            "color": "red",
            "price": 119.99,
            "rating": 4.4,
            "in_stock": False,
        },
        {
            "id": 5,
            "embedding": [0.48, 0.20, 0.59, 0.15, 0.71],
            "name": "Jacket A1",
            "brand": "Brand A",
            "category": "jackets",
            "color": "black",
            "price": 99.99,
            "rating": 4.5,
            "in_stock": True,
        },
        {
            "id": 6,
            "embedding": [0.45, 0.18, 0.55, 0.17, 0.69],
            "name": "Jacket B1",
            "brand": "Brand B",
            "category": "jackets",
            "color": "blue",
            "price": 89.99,
            "rating": 4.3,
            "in_stock": True,
        },
        {
            "id": 7,
            "embedding": [0.09, 0.38, 0.17, 0.60, 0.27],
            "name": "Runner A3",
            "brand": "Brand A",
            "category": "running_shoes",
            "color": "black",
            "price": 159.99,
            "rating": 4.8,
            "in_stock": True,
        },
        {
            "id": 8,
            "embedding": [0.13, 0.43, 0.21, 0.65, 0.32],
            "name": "Runner A4",
            "brand": "Brand A",
            "category": "running_shoes",
            "color": "black",
            "price": 149.99,
            "rating": 4.9,
            "in_stock": True,
        },
    ],
)

client.load_collection(collection_name)

query_vector = [0.11, 0.40, 0.19, 0.64, 0.30]
search_params = {
    "metric_type": "COSINE",
    "params": {},
}

上述設定同時為向量索引和搜尋參數配置了COSINE 。因此，後續範例將使用{"_score": "desc"} 來優先顯示較高的餘弦相似度。若使用L2 等距離度量，請使用{"_score": "asc"} 。

比較與排序桶

當您需要使用計算出的統計數據比較一組檢索到的實體，並控制桶的回傳順序時，請使用此模式。在此範例中，Milvus 會根據brand 將檢索到的產品分組，為每個品牌桶計算價格指標，並按平均價格對桶進行排序。

若您的目標僅是透過針對每個欄位值返回一個或多個實體來提升結果多樣性，請改用「分組搜尋」。

以下設定會建立最多三個品牌區間，為每個區間計算指標，並根據平均價格對區間進行排序：

aggregation = SearchAggregation(
    # Form one bucket for each distinct brand value.
    fields=["brand"],
    # Return up to three buckets at this aggregation level.
    size=3,
    # Calculate named metrics for every selected bucket.
    metrics={
        "product_count": {"count": "*"},
        "avg_price": {"avg": "price"},
        "min_price": {"min": "price"},
    },
    # Sort buckets by average price, highest first.
    order=[
        {"avg_price": "desc"},
        # If average prices are equal, sort by bucket key in ascending order.
        {"_key": "asc"},
    ],
)

將物件傳遞至 `MilvusClient.search()` 的 `search_aggregation ` 參數：

result = client.search(
    collection_name=collection_name,
    data=[query_vector],
    anns_field="embedding",
    search_params=search_params,
    output_fields=[
        "name",
        "brand",
        "category",
        "color",
        "price",
        "rating",
        "in_stock",
    ],
    search_aggregation=aggregation,
)

當設定search_aggregation 時，PyMilvus 不會在result[0] 中返回任何一般實體命中結果。請改為從result.agg_buckets[0] 讀取桶回應。output_fields 參數控制哪些標量欄位會出現在每個返回的AggregationHit.fields 映射中；Milvus 仍可使用未列於output_fields 中的指標來源欄位和排序欄位。

[
  {
    "key": [
      {
        "field_id": 103,
        "field_name": "brand",
        "value": "Brand B"
      }
    ],
    "count": 1,
    "metrics": {
      "product_count": 1,
      "avg_price": 159.99,
      "min_price": 159.99
    },
    "hits": [],
    "sub_groups": []
  },
  {
    "key": [
      {
        "field_id": 103,
        "field_name": "brand",
        "value": "Brand A"
      }
    ],
    "count": 1,
    "metrics": {
      "product_count": 1,
      "avg_price": 129.99,
      "min_price": 129.99
    },
    "hits": [],
    "sub_groups": []
  },
  {
    "key": [
      {
        "field_id": 103,
        "field_name": "brand",
        "value": "Brand C"
      }
    ],
    "count": 1,
    "metrics": {
      "product_count": 1,
      "avg_price": 119.99,
      "min_price": 119.99
    },
    "hits": [],
    "sub_groups": []
  }
]

針對本指南中的單一查詢向量，請從 `result.agg_buckets[0]` 讀取回傳的頂層桶位。每個桶位會公開其有序的鍵組件、保留候選項 `count`、計算結果 `metrics`、代表性向量 `hits`，以及 `sub_groups` 中的嵌套桶位。

請參閱以下設定：

當設定 `search_aggregation ` 時，Milvus 會忽略 `limit `。請使用根 `SearchAggregation.size ` 值來控制頂層區間的數量。

根據這些設定，Milvus 會依avg_price 由高至低的順序，返回「品牌 B」、「品牌 A」和「品牌 C」的桶。_key 準則僅在各桶的平均價格相同時才適用。由於此配置未定義top_hits ，每個桶的hits 清單皆為空，且每個鍵的候選預算為1 。因此，顯示的計數和指標描述的是每個品牌保留的一位候選者。當彙總需要更寬的每個鍵指標視窗時，請將top_hits 設定為較大的TopHits.size 。

aggregation = SearchAggregation(
    fields=["brand"],
    size=3,
    metrics={"max_score": {"max": "_score"}},
    order=[{"max_score": "desc"}],
)

aggregation = SearchAggregation(
    # Combine brand and color to form a composite bucket key.
    fields=["brand", "color"],
    size=6,
)

以下範例重新定義了aggregation 。將更新後的物件傳遞給相同的search_aggregation 參數，並重新執行搜尋呼叫。

顯示每個桶位的代表性結果

當應用程式需要顯示每個桶中的實際產品時，請包含具代表性的實體。在此範例中，Milvus 會從每個品牌桶中返回最多兩項產品，並依評分排序，接著依向量分數排序。

請依下列方式設定 `TopHits `：

aggregation = SearchAggregation(
    fields=["brand"],
    size=3,
    # Return and sort representative entities for each selected bucket.
    top_hits=TopHits(
        # Return up to two entities per bucket.
        size=2,
        # Apply sort criteria in list order.
        sort=[
            {"rating": "desc"},
            {"_score": "desc"},
        ],
    ),
)

{
  "key": [
    {
      "field_id": 103,
      "field_name": "brand",
      "value": "Brand A"
    }
  ],
  "count": 2,
  "metrics": {},
  "hits": [
    {
      "pk": 1,
      "score": 0.99976646900177,
      "fields": {
        "brand": "Brand A",
        "category": "running_shoes",
        "color": "black",
        "in_stock": true,
        "name": "Runner A1",
        "price": 129.99,
        "rating": 4.7
      }
    },
    {
      "pk": 2,
      "score": 0.9997048377990723,
      "fields": {
        "brand": "Brand A",
        "category": "running_shoes",
        "color": "blue",
        "in_stock": true,
        "name": "Trail A2",
        "price": 139.99,
        "rating": 4.6
      }
    }
  ],
  "sub_groups": []
}

當應用程式需要代表性實體，或計數與指標需要更寬的「每鍵候選視窗」時，請設定 `top_hits `。較大的 `TopHits.size ` 值會同時增加候選預算，並提高「限制」中返回條目的最大計算量。

SearchAggregation.order 會對桶進行排序，而「TopHits.sort 」則會對每個桶內的保留實體進行排序。此排序順序不會改變為「count 」和指標所保留的候選項。TopHits.sort 接受受支援的可比較標量欄位名稱，以及代表人工智慧（ANN）相似度或距離的內建「_score 」欄位。Milvus 會從頭到尾評估「sort 」中的條目。 在此範例中，系統會依據rating 將產品從高到低排序，並僅在兩項評分相同時才使用_score 。由於設定中使用了COSINE ，因此降序的_score 會將相似度較高的產品排在首位。

metrics 或TopHits.sort 所使用的欄位無需出現在output_fields 中。Milvus 會在內部擷取這些欄位，但僅有output_fields 中明確列出的欄位才會被納入每個回傳結果的fields 映射中。主鍵和向量分數仍可透過AggregationHit.pk 和AggregationHit.score 取得。

每個回傳的AggregationHit 皆會於pk 中公開其主鍵、於score 中公開向量分數，並於fields 中公開所請求的輸出欄位。

多層級結果分組

當您需要在某個層級內建立另一個層級的桶時，請使用嵌套聚合。在此範例中，Milvus 會先建立類別桶，然後在每個類別內建立品牌桶。

子聚合僅接收指派給其父桶的實體。fields 控制各聚合層級的桶鍵，而sub_aggregation 則建立父子層級結構。

以下配置會建立一個鍵值為(running_shoes) 的類別儲存桶。在該父儲存桶內，子聚合會建立各自獨立的品牌儲存桶，其鍵值例如(Brand A) 、(Brand B) 以及(Brand C) 。

Parent bucket key:
(running_shoes)

Child bucket keys:
├── (Brand A)
├── (Brand B)
└── (Brand C)

每個層級均可獨立使用多個欄位。例如，在子聚合中使用fields=["brand", "color"] ，將產生如(Brand A, black) 這樣的複合子鍵。

以下配置實現了此層級結構：

aggregation = SearchAggregation(
    fields=["category"],
    size=2,
    metrics={
        "product_count": {"count": "*"},
        "avg_price": {"avg": "price"},
    },
    order=[{"product_count": "desc"}],
    # For each category bucket, group only its entities by brand.
    sub_aggregation=SearchAggregation(
        fields=["brand"],
        size=3,
        metrics={
            "brand_count": {"count": "*"},
            "avg_rating": {"avg": "rating"},
        },
        order=[{"avg_rating": "desc"}],
        top_hits=TopHits(
            size=2,
            sort=[{"rating": "desc"}],
        ),
    ),
)

{
  "key": [
    {
      "field_id": 104,
      "field_name": "category",
      "value": "running_shoes"
    }
  ],
  "count": 4,
  "metrics": {
    "avg_price": 137.49,
    "product_count": 4
  },
  "hits": [],
  "sub_groups": [
    {
      "key": [
        {
          "field_id": 103,
          "field_name": "brand",
          "value": "Brand B"
        }
      ],
      "count": 1,
      "metrics": {
        "avg_rating": 4.8,
        "brand_count": 1
      },
      "hits": [
        {
          "pk": 3,
          "score": 0.9994542598724365,
          "fields": {
            "brand": "Brand B",
            "category": "running_shoes",
            "color": "white",
            "in_stock": true,
            "name": "Runner B1",
            "price": 159.99,
            "rating": 4.8
          }
        }
      ],
      "sub_groups": []
    }
  ]
}

顯示的結果代表儲存桶路徑(running_shoes) → (Brand B) ，而非單一的複合儲存桶金鑰(running_shoes, Brand B) 。

Milvus 首先根據product_count 的順序，選取最多兩個類別儲存桶。接著，它在每個選定的類別中獨立執行sub_aggregation ，並根據avg_rating 的順序，返回最多三個品牌儲存桶。

在上述輸出中：

• 根級別的running_shoes 桶在其子複合鍵中包含四個保留候選項。其metrics 包含根級別的avg_price 和product_count 值。
• 根桶的「sub_groups 」清單包含子品牌桶。顯示的「Brand B」桶包含一個保留候選值，以及其自身的「avg_rating 」和「brand_count 」值。
• 由於根匣的hits 清單未設定top_hits ，因此該清單為空。品牌 B 子匣包含一個代表性命中，因為在sub_aggregation 中已設定top_hits 。

常見問題

桶的計數和指標的準確性如何？

搜尋彙總會彙總保留的 ANN 候選項，並不會執行全集合彙總。

候選項保留包含兩個近似階段。ANN 搜尋可能會遺漏相關的集合實體，而分組階段針對每個完整的複合鍵，最多僅保留TopHits.size 候選項。若無任何層級設定top_hits ，則此每鍵限制為一。

舉例來說，假設某集合包含 5,000 項「品牌 A」產品，其中許多與向量查詢相關。若彙總使用TopHits(size=4) ，則「品牌 A」桶位針對每個完整複合鍵最多可保留四個候選項。其count 和指標所描述的是這些被保留的候選項，而非所有相關的「品牌 A」產品，亦非集合中的全部 5,000 個實體。

當「order 」使用指標別名時，近似值的影響最為顯著。搜尋召回率的變化會改變指標值，進而改變哪些桶能符合「SearchAggregation.size 」的條件。嵌套聚合會放大此效應，因為每個子層級皆針對其父桶中的可用實體進行運算。

若您需要針對每個匹配實體取得精確統計資料，請使用「精確查詢彙總」工作流程，而非「搜尋彙總」。

「搜尋聚合」與「分組搜尋」有何不同？

請根據應用程式的首要結果格式進行選擇：

即使搜尋聚合設定了top_hits ，其主要回應仍為桶狀樹。當應用程式已能處理一般搜尋結果，且主要目標在於提升結果多樣性時，分組搜尋仍具實用價值。

這些 API 彼此互斥。當在同一請求中將 `search_aggregation ` 與 `group_by_field ` 或 `group_by_fields ` 結合使用時，PyMilvus 會拋出 `ParamError ` 異常。