Hugging FaceCompatible with Milvus v2.6.20+

Hugging Faceの埋め込みモデルを使用する場合、通常はアプリケーション側で認証情報を管理し、モデルを個別に呼び出し、挿入されたデータや検索クエリに対して一貫して埋め込みを生成する必要があります。テキスト埋め込み機能を使用すると、MilvusはホストされているHugging Face推論プロバイダーを呼び出し、データの挿入時および検索時に生テキストをベクトルに変換します。

この統合では、ホスト型 Hugging Face ルーターが使用されます。Milvus を別途デプロイされた Text Embeddings Inference (TEI) サービスに接続するには、「Hugging Face TEI」を参照してください。

制限事項

• Functionの出力フィールドには、FLOAT_VECTOR データ型を使用する必要があります。MilvusにおけるHugging Faceの埋め込み機能では、INT8_VECTOR 、BINARY_VECTOR 、FLOAT16_VECTOR 、またはBFLOAT16_VECTOR の出力フィールドはサポートされていません。
• 「Function」出力フィールドの次元は、選択したモデルの出力次元と一致している必要があります。

仕組み

Hugging Face テキスト埋め込みワークフロー

このワークフローは 3 つの段階で構成されています。

1. 生テキストの送信。アプリケーションは、挿入または検索リクエストで生テキストを提供します。
2. 埋め込みを生成します。「Text Embedding」関数は、hf-inference を経由して、Hugging Faceのfeature-extraction パイプラインにテキストを送信します。この関数はmodel_name を使用してモデルを選択し、正規化や切り捨てなどのサポートされている推論オプションを渡すことができます。
3. 埋め込みを使用します。Hugging Faceは、入力テキスト1件につき1つの浮動小数点型埋め込みを返します。挿入時には、Milvusがこのベクトルを関数の出力フィールドに格納します。検索時には、Milvusがこのベクトルをクエリベクトルとして使用します。

同じ関数設定で挿入と検索の両方を処理できるため、両操作においてモデルと推論パラメータの一貫性が保たれます。

開始する前に

Hugging Faceのホスト型テキスト埋め込み機能を使用する前に、以下の条件を満たしていることを確認してください：

• 2.6リリースラインのMilvus 2.6.20以降。
• PyMilvus 2.6.16 以降。
• 推論プロバイダーを呼び出せる Hugging Face ユーザーアクセストークン。
• hf-inference によって現在提供されている、 feature-extraction タスク用にxml-ph-0000@deepl.internalで現在提供されているモデル。

例では、 sentence-transformers/all-MiniLM-L6-v2を使用しており、384次元の埋め込みを生成します。このモデルは設定のデモ目的でのみ使用されており、Milvusによる推奨や認定を示すものではありません。

認証情報の設定

Milvusでは、ホスト型ルーターを呼び出すためにHugging Faceのユーザーアクセストークンが必要です。トークンはmilvus.yaml で設定するか、環境変数を通じて設定できます。

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

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

オプション 1: 設定ファイル

milvus.yaml の最上位セクションであるcredential 内にトークンを定義し、Hugging Face 埋め込みプロバイダーをその認証情報ラベルに指定します：

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

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

また、Functionパラメータでcredential を設定することもできます。値は、トークンそのものではなく、credential セクションの最上位レベルで定義されたラベルでなければなりません。Functionレベルの認証情報ラベルは、プロバイダーレベルのラベルよりも優先されます。

オプション 2: 環境変数

Function およびプロバイダーの設定のいずれにも認証情報ラベルが指定されていない場合、Milvus は `MILVUS_HUGGINGFACE_API_KEY` からトークンを読み取ります。

Docker Compose の場合、Milvus スタンドアロンサービス内で変数を設定します:

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

Docker Compose 設定の適用に関する詳細については、「Docker Compose を使用した Milvus の設定」を参照してください。

Hugging Faceのテキスト埋め込みを使用する

ステップ 1: テキスト埋め込み関数を含むコレクションを作成する

プライマリフィールド、VARCHAR 入力フィールド、およびFLOAT_VECTOR 出力フィールドを含むスキーマを作成します。出力次元は、選択したモデルと一致している必要があります。

from pymilvus import DataType, Function, FunctionType, MilvusClient

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

collection_name = "hugging_face_embedding_demo"
schema = client.create_schema()

schema.add_field(
    field_name="id",
    datatype=DataType.INT64,
    is_primary=True,
    auto_id=False,
)
schema.add_field(
    field_name="document",
    datatype=DataType.VARCHAR,
    max_length=9000,
)
schema.add_field(
    field_name="dense",
    datatype=DataType.FLOAT_VECTOR,
    dim=384,
)

`document ` から `dense` へ埋め込みを書き込む `TEXTEMBEDDING ` 関数を定義します：

text_embedding_function = Function(
    name="hugging_face_embedding",
    input_field_names=["document"],
    output_field_names=["dense"],
    function_type=FunctionType.TEXTEMBEDDING,
    params={
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "credential": "huggingface_apikey",
        "normalize": "true",
        "truncate": "true",
        "max_client_batch_size": 128,
    },
)

schema.add_function(text_embedding_function)

プロバイダーレベルの認証情報または環境変数のみを使用する場合は、関数パラメータからcredential を省略してください。

出力フィールドのインデックスを設定し、コレクションを作成します：

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,
)

次の表は、Hugging Face固有の関数パラメータについて説明しています：

パラメータ	必須？	説明
provider	はい	埋め込みモデルのプロバイダー。この値をhuggingface に設定してください。
model_name	はい	feature-extraction タスク向けにhf-inference を通じて提供されるモデルのHugging FaceモデルID。
hf_provider	いいえ	Hugging Face 推論プロバイダーのルート。Milvus 2.6.20 におけるデフォルト値かつ唯一サポートされている値はhf-inference です。
credential	いいえ	milvus.yaml の最上位セクションであるcredential で定義された認証情報のラベル。この値はトークンそのものではありません。
normalize	いいえ	Hugging Faceが正規化された埋め込みを返すかどうか。サポートされている値はtrue およびfalse です。省略された場合、Milvusはこのオプションをリクエストに設定しません。
prompt_name	いいえ	選択したモデルの Sentence Transformers 設定で定義されたプロンプトの名前。
truncate	いいえ	Hugging Faceが、モデルのサポートする長さを超える入力を切り捨てるかどうか。サポートされる値は、true およびfalse です。
truncation_direction	いいえ	Hugging Faceが入力を切り詰める方向。サポートされている値は、left およびright です。
max_client_batch_size	なし	1回のHugging Faceリクエストで送信される入力テキストの最大数。デフォルト値は128 であり、この値は0 より大きくなければなりません。

ステップ 2: 生テキストの挿入

ベクトルを指定せずにテキストを挿入します。MilvusはHugging Faceを呼び出し、生成されたエンベディングをdense に書き込みます。

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "document": "Milvus simplifies semantic search through embeddings.",
        },
        {
            "id": 2,
            "document": "Vector embeddings convert text into searchable numeric data.",
        },
        {
            "id": 3,
            "document": "Semantic search helps users find relevant information quickly.",
        },
    ],
)

ステップ 3: 生テキストでの検索

テキストクエリを使用して検索します。Milvusは、ベクトル検索を実行する前に、同じ関数設定を適用してクエリベクトルを作成します。

results = client.search(
    collection_name=collection_name,
    data=["How does Milvus handle semantic search?"],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    consistency_level="Strong",
)

print(results)

結果には、クエリテキストに最も関連性の高いドキュメントが、コサイン類似度順に表示されます。

トラブルシューティング

特徴量抽出にモデルが利用できません

Hugging Faceでモデルページを開き、「Inference Providers」セクションを確認してください。「hf-inference 」がfeature-extraction のモデルを提供していることを確認してください。そうでない場合は、別のモデルを選択し、必要に応じてベクトルフィールドの次元を更新してください。

返されたベクトルの次元がフィールドと一致しません

モデルの出力次元を確認し、「Function output」フィールドのdim と比較してください。Milvusは、ベクトルの次元がFLOAT_VECTOR フィールドの次元と異なるレスポンスを拒否します。

Milvus から Hugging Face の認証情報が不足していると報告される

トップレベルの「credential 」セクションに「Function」の認証情報ラベルが存在すること、プロバイダーレベルのラベルが有効であること、またはMilvusのサービス環境にMILVUS_HUGGINGFACE_API_KEY が存在することを確認してください。

次の手順

• Function の一般的な概念および挿入/検索の動作については、「Embedding Function の概要」を参照してください。
• ホスト型 Hugging Face の文類似度スコアを使用してベクトル検索の候補を再ランク付けするには、「Hugging Face Ranker」を参照してください。