Hugging Face RankerCompatible with Milvus v2.6.20+

ベクトル検索では、結果がベクトル距離に基づいて並べ替えられますが、初期の順序は、各候補テキストがクエリにどの程度適切に応答しているかを必ずしも反映しているとは限りません。Hugging Face Rankerは、クエリと候補テキストをホスト型Hugging Face Inference Providersに送信し、sentence-similarity のスコアを用いて、Milvusから返された候補の順序を再編成します。

この統合では、ホスト型Hugging Faceルーターを使用します。別途デプロイされたText Embeddings Inference（TEI）サービスを使用して再ランク付けを行う場合は、TEI Rankerを参照してください。

制限事項

• この関数は、input_field_names 内のVARCHAR フィールドのうち、nullを許容しないものを正確に1つ参照する必要があります。
• queries 内の文字列の数は、検索クエリの数（nq ）と一致している必要があります。

仕組み

Hugging Face Rankerのワークフロー

Hugging Face Rankerは、初期のベクトル検索後に実行されます：

1. 候補エンティティを取得します。Milvusは設定されたベクトルフィールドを検索し、候補エンティティを収集します。
2. 再ランク付け用のテキストを準備します。Functionは、params.queries からクエリテキストを読み取り、input_field_names で指定されたVARCHAR フィールドから候補テキストを読み取ります。
3. 類似度スコアの要求。Milvusは、クエリをsource_sentence として、候補テキストをsentences として、hf-inference を経由してHugging Faceのsentence-similarity パイプラインに送信します。
4. 候補テキストの再ランク付けを行います。Hugging Faceは候補ごとに1つのスコアを返します。Milvusはスコアの高い順に候補を並べ替え、再ランク付けされた結果を返します。

類似度スコアの算出方法

Hugging Face Rankerによる類似度スコアの算出方法

Hugging Faceのモデルは、3つの段階でスコアを算出します：

1. テキスト入力の準備。Rankerは、params.queries からクエリテキストを読み取り、設定されたVARCHAR フィールドから候補テキストを読み取ります。
2. 個別のモデル表現を作成します。Milvusは、クエリをsource_sentence として、候補テキストをsentences として送信します。モデルは内部で、クエリと各候補を個別にエンコードします。
3. スコアを比較して返す。モデルは、クエリの表現と各候補の表現を比較し、候補ごとに1つの類似度スコアを返します。

Hugging Faceモデルが使用する埋め込みや表現は、モデル処理の中間段階のものです。Hugging Faceが返すのはスコアであり、ベクトルではありません。したがって、初期のベクトル検索とモデルによる再ランク付けでは、別々の表現が使用され、異なるモデルが使用される場合があります。

開始する前に

Hugging Face Ranker を使用する前に、以下の条件を満たしていることを確認してください：

• 2.6リリースラインのMilvus 2.6.20以降。
• PyMilvus 2.6.16以降。
• Inference Providers を呼び出せる Hugging Face ユーザーアクセストークン。
• hf-inference によって現在提供されている、 sentence-similarity タスク用にxml-ph-0000@deepl.internalによって現在提供されているモデル。
• VARCHAR の null 不可フィールドに候補テキストを格納するコレクション。

これらの例では、 sentence-transformers/all-MiniLM-L6-v2 は設定の説明のみを目的としています。このモデルは、Milvusによる推奨や認定を示すものではありません。

認証情報の設定

Hugging Face ユーザーアクセストークンは、milvus.yaml または環境変数を通じて設定できます。

認証情報の優先順位は次のとおりです：

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: リランキング関数の定義

document から候補テキストを読み取り、queries 内のクエリテキストを使用する `RERANK ` 関数を定義します：

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	はい	sentence-similarity タスク向けにhf-inference を通じて提供されるモデルのHugging FaceモデルID。
queries	はい	再ランク付けに使用されるクエリ文字列。初期の検索でクエリベクトルが使用される場合でも、検索クエリごとに厳密に1つの文字列を指定してください。
hf_provider	いいえ	Hugging Face 推論プロバイダーのルート。Milvus 2.6.20 におけるデフォルトかつ唯一サポートされている値はhf-inference です。
credential	いいえ	milvus.yaml の最上位セクションであるcredential で定義された認証情報のラベル。この値はトークンそのものではありません。
max_client_batch_size	いいえ	1回の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 ）と一致している必要があります。クエリベクトルが 1 つの検索の場合、クエリ文字列を正確に 1 つ指定してください。

候補テキストが欠落しているか、null 許容です

input_field_names に、NULL 不可のVARCHAR フィールドが正確に 1 つ含まれていること、およびすべての候補エンティティがそのフィールドにテキストを含んでいることを確認してください。

MilvusがHugging Faceの認証情報の欠落を報告している

milvus.yaml に「Function」という資格情報ラベルが存在すること、プロバイダーレベルのラベルが有効であること、または Milvus サービス環境にMILVUS_HUGGINGFACE_API_KEY が存在することを確認してください。

次の手順

• モデル・ランカーの動作および制限については、「モデル・ランカーの概要」を参照してください。
• ホスト型 Hugging Face 推論プロバイダーを通じて埋め込みを生成するには、「Hugging Face」を参照してください。
• ランカーをハイブリッド検索に適用するには、「マルチベクトル・ハイブリッド検索」を参照してください。