Hugging Face RankerCompatible with Milvus v2.6.20+

向量搜尋會根據向量距離對結果進行排序，但初始排序未必能反映各候選文本對查詢的回應程度。Hugging Face Ranker 會將查詢與候選文本傳送至託管的Hugging Face 推論提供者，並利用sentence-similarity 的評分來重新排序 Milvus 所回傳的候選結果。

此整合功能使用託管的 Hugging Face 路由器。若要透過獨立部署的文字嵌入推論 (TEI) 服務進行重新排序，請參閱TEI Ranker。

限制

• 該函式必須在 `input_field_names` 中精確引用一個不可為空的 `VARCHAR ` 欄位。
• queries 中的字串數量必須等於搜尋查詢的數量（nq ）。

運作原理

Hugging Face Ranker 工作流程

Hugging Face Ranker 會在初始向量搜尋後執行：

1. 擷取候選實體。Milvus 會搜尋已配置的向量欄位，並彙整候選實體。
2. 準備重新排序所需的文字。該函式會從 `params.queries ` 讀取查詢文字，並從 `input_field_names` 中指定的 `VARCHAR ` 欄位讀取候選文字。
3. 請求相似度分數。Milvus 透過hf-inference ，將查詢內容作為source_sentence 及候選文本作為sentences 傳送至 Hugging Face 的sentence-similarity 處理流程。
4. 重新排序候選文本。Hugging Face 針對每個候選文本返回一個分數。Milvus 將候選文本依分數由高至低排序，並返回重新排序後的結果。

相似度分數的計算方式

Hugging Face Ranker 如何計算相似度分數

Hugging Face 模型分三個階段計算分數：

1. 準備文字輸入。Ranker 從params.queries 讀取查詢文字，並從已設定的VARCHAR 欄位讀取候選文字。
2. 建立獨立的模型表徵。Milvus 將查詢文字傳送至source_sentence ，並將候選文字傳送至sentences 。模型會內部分別對查詢及每個候選文字進行編碼。
3. 進行比對並返回分數。模型會將查詢表徵與每個候選項表徵進行比對，並針對每個候選項返回一個相似度分數。

Hugging Face 模型所使用的嵌入向量或表徵，屬於模型處理過程中的中間結果。Hugging Face 返回的是分數，而非向量。因此，初始向量檢索與模型重新排序會使用各自獨立的表徵，且可能採用不同的模型。

開始之前

在使用 Hugging Face Ranker 之前，請確保您已具備：

• 2.6 發行版本線中的 Milvus 2.6.20 或更新版本。
• PyMilvus 2.6.16 或更高版本。
• 一個可呼叫推論提供者的 Hugging Face 使用者存取憑證。
• 目前由hf-inference 提供服務的模型，適用於 sentence-similarity 任務所提供的模型。
• 一個用於將候選文字儲存於VARCHAR 非空欄位的集合。

範例中僅使用 sentence-transformers/all-MiniLM-L6-v2 僅用於展示設定方式。該模型並非 Milvus 的推薦或認證。

設定憑證

您可以在milvus.yaml 上設定 Hugging Face 使用者存取憑證，或透過環境變數進行設定。

憑證的優先順序為：

Function credential label -> provider credential label in milvus.yaml -> environment variable

選項 1：配置檔

請在credential 的頂層區段中定義該憑證，然後將 Hugging Face 排名器提供者指向該憑證標籤：

# milvus.yaml
credential:
  huggingface_apikey:
    apikey: <YOUR_HUGGING_FACE_TOKEN>

function:
  rerank:
    model:
      providers:
        huggingface:
          credential: huggingface_apikey
          # url: https://router.huggingface.co

函式層級的credential 參數可覆寫提供者層級的標籤。其值必須是定義於milvus.yaml 中的憑證標籤，而非代碼本身。

選項 2：環境變數

若函式與提供者設定均未指定憑證標籤，請在 Milvus 服務環境中設定MILVUS_HUGGINGFACE_API_KEY ：

# docker-compose.yaml
standalone:
  environment:
    MILVUS_HUGGINGFACE_API_KEY: <YOUR_HUGGING_FACE_TOKEN>

使用 Hugging Face Ranker

Hugging Face Ranker 是在搜尋時定義並套用的。您可以在不變更集合架構的情況下，針對每次搜尋變更或省略該排序器。

步驟 1：準備一個集合

以下範例建立一個集合，其中包含用於重新排序的文字欄位，以及用於初始檢索的向量欄位：

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

collection_name = "hugging_face_rerank_demo"
schema = client.create_schema()
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=1000)
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=4)

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

client.create_collection(
    collection_name=collection_name,
    schema=schema,
    index_params=index_params,
)

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "document": "Recent renewable energy developments include improved solar efficiency.",
            "dense": [0.10, 0.20, 0.30, 0.40],
        },
        {
            "id": 2,
            "document": "Climate policy and carbon markets have evolved rapidly in recent years.",
            "dense": [0.11, 0.19, 0.28, 0.39],
        },
        {
            "id": 3,
            "document": "New battery technology helps stabilize wind and solar power generation.",
            "dense": [0.90, 0.10, 0.05, 0.02],
        },
        {
            "id": 4,
            "document": "Vector databases support similarity search for machine learning applications.",
            "dense": [0.01, 0.02, 0.03, 0.04],
        },
    ],
)

步驟 2：定義重新排序函式

定義一個 `RERANK ` 函式，該函式會從 `document ` 讀取候選文字，並使用 `queries` 中的查詢文字：

hugging_face_ranker = Function(
    name="hugging_face_semantic_ranker",
    input_field_names=["document"],
    function_type=FunctionType.RERANK,
    params={
        "reranker": "model",
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "queries": ["renewable energy developments"],
        "credential": "huggingface_apikey",
        "max_client_batch_size": 32,
    },
)

若僅使用供應商層級的憑證或環境變數，請從函式參數中省略 `credential `。

下表說明 Hugging Face Ranker 的參數：

參數	是否必填？	說明
reranker	是	重新排序的實作方式。請將此值設定為 `model`。
provider	是	模型提供者。請將此值設定為huggingface 。
model_name	是	透過hf-inference 提供服務的 Hugging Face 模型 ID，適用於sentence-similarity 任務。
queries	是	用於重新排序的查詢字串。每個搜尋查詢請精確提供一個字串，即使初始檢索使用查詢向量亦然。
hf_provider	否	Hugging Face 推論提供者的路徑。在 Milvus 2.6.20 中，預設且唯一受支援的值為hf-inference 。
credential	否	在 `milvus.yaml` 檔案的頂層 `credential ` 區段中定義的憑證標籤。此值並非代幣本身。
max_client_batch_size	否	單次 Hugging Face 請求中傳送的候選文本最大數量。預設值為32 ，且該值必須大於0 。

步驟 3：使用排名器進行搜尋

透過search() 的ranker 參數傳遞該函式：

query_vector = [0.12, 0.21, 0.29, 0.41]

results = client.search(
    collection_name=collection_name,
    data=[query_vector],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    ranker=hugging_face_ranker,
    consistency_level="Strong",
)

print(results)

Milvus 會先從dense 擷取候選結果，接著利用queries 中的查詢文字以及document 中的候選文字，計算句子相似度分數。回傳的候選結果將依照 Hugging Face 分數排序。

疑難排解

該模型無法用於句子相似度分析

請開啟 Hugging Face 上的模型頁面，並檢查「推論提供者 (Inference Providers)」區段。確認hf-inference 是否為sentence-similarity 提供模型服務。若非如此，請選擇另一個支援此任務的模型。

查詢字串的數量與搜尋請求不符

queries 中的字串數量必須等於搜尋查詢的數量（nq ）。若搜尋僅包含一個查詢向量，請提供精確一個查詢字串。

候選文字遺漏或可為空

請確保 `input_field_names ` 中包含且僅包含一個非可空的 `VARCHAR ` 欄位，且每個候選實體在該欄位中皆含有文字。

Milvus 報告 Hugging Face 憑證缺失

請確認milvus.yaml 中存在「Function」憑證標籤、提供者層級的標籤有效，或 Milvus 服務環境中已存在MILVUS_HUGGINGFACE_API_KEY 。

後續步驟

• 有關共享模型排名器的運作方式與限制，請參閱《模型排名器概覽》。
• 若要透過託管的 Hugging Face 推論提供者產生嵌入向量，請參閱《Hugging Face》。
• 若要將排序器應用於混合搜尋，請參閱《多向量混合搜尋》。