メインコンテンツまでスキップ

Hugging Face

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

仕組み​

XCxpwN8JvhevN8bAvbzcI72Fngg

ワークフローは 3 つのステップで構成されます。

  1. 生のテキストを送信します。 アプリケーションは、挿入または検索リクエストで生のテキストを提供します。

  2. 埋め込みを生成します。 テキスト埋め込み関数は、integration_id を使用して Hugging Face モデルプロバイダーの統合を参照し、model_name を使用してモデルを選択します。Zilliz Cloud は、Feature Extraction タスクのために hf-inference を通じてテキストを Hugging Face に送信します。

  3. 埋め込みを使用します。 Hugging Face は浮動小数点の埋め込みベクトルを返します。挿入時、Zilliz Cloud はベクトルを関数の出力フィールドに格納します。検索時、Zilliz Cloud はベクトルをクエリベクトルとして使用します。

挿入と検索には同じ関数構成が使用されるため、両方の操作でモデルと推論パラメーターが一貫した状態に保たれます。

モデルの互換性​

Hugging Face モデルをテキスト埋め込み関数で使用するには、そのモデルに Feature Extraction 機能があり、構成された hf-inference 統合を通じて埋め込みを正常に返す必要があります。関数の出力フィールドは、dim がモデルの埋め込み次元と一致する FLOAT_VECTOR フィールドである必要があります。

次のモデルは、記載された日付に Zilliz Cloud との互換性テストに合格しました。

モデル機能次元最終テスト日
BAAI/bge-m3Feature Extraction10242026-07-27
BAAI/bge-large-zh-v1.5Feature Extraction10242026-07-27
BAAI/bge-large-en-v1.5Feature Extraction10242026-07-27
BAAI/bge-small-en-v1.5Feature Extraction3842026-07-27
dragonkue/snowflake-arctic-embed-l-v2.0-koFeature Extraction10242026-07-27
upskyy/bge-m3-koreanFeature Extraction10242026-07-27
Notes

この表は互換性のあるモデルの完全なリストではありません。記載されていないモデルでも、統合と互換性がある場合があります。

互換性の結果は、記載された日付のテストを反映しています。Zilliz Cloud は、モデルが引き続き hf-inference 経由で利用可能であるか、安定性、レイテンシ、出力品質に関する要件を満たしているかを管理するものではありません。Zilliz Cloud は、過去の結果を定期的に再テストすることを約束するものではありません。実稼働環境で使用する前に、Hugging Face で選択したモデルを確認し、ワークロードに適しているか評価してください。

事前準備​

Hugging Face のテキスト埋め込みを使用する前に、以下を確認してください。

  • Hugging Face モデルプロバイダーの統合を作成し、統合 ID をコピーして、Provider を hf-inference に設定すること。手順の詳細は Integrate with Model Providers に記載されていること。

  • モデルの Hugging Face ページを開き、Inference Providers セクションを確認して、hf-inference が現在 feature-extraction タスク用にそのモデルを提供していることを検証すること。

  • カスタム出力次元はサポートされていないため、モデルの出力次元を確認し、関数の出力フィールドが dim とモデル出力が一致する FLOAT_VECTOR フィールドであることを検証すること。

この例では BAAI/bge-small-en-v1.5 を使用しています。このモデルは執筆時点で hf-inference を通じて 384 次元の埋め込みを生成します。このモデルは構成を説明するためだけに使用されており、Zilliz Cloud による推奨または認定を示すものではありません。

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

ステップ 1: テキスト埋め込み関数を使用してコレクションを作成する​

スキーマフィールドを定義する​

以下を含むコレクションスキーマを作成します。

  • 各エンティティを一意に識別するプライマリフィールド。

  • 生のテキストを格納する VARCHAR フィールド。

  • 選択したモデルの出力次元と一致する次元を持つ FLOAT_VECTOR フィールド。

次の例では BAAI/bge-small-en-v1.5 を使用しています。このモデルは 384 次元のベクトルを生成します。

python
from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN",
)

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

# The vector dimension must match the model's output dimension.
schema.add_field(
    field_name="dense",
    datatype=DataType.FLOAT_VECTOR,
    dim=384,
)

テキスト埋め込み関数を定義する​

document フィールドの値を埋め込みに変換し、dense フィールドに書き込む TEXTEMBEDDING Function を定義します。

python
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": "BAAI/bge-small-en-v1.5",
        "integration_id": "YOUR_INTEGRATION_ID",
        "normalize": "true",
        "truncate": "true",
    },
)

schema.add_function(text_embedding_function)

次の表は、params でサポートされるすべてのエントリを説明しています。Hugging Face のリクエストオプションは Feature Extraction API specification に従います。provider、model_name、integration_id、および max_client_batch_size は Zilliz Cloud 統合を構成します。

パラメーター必須説明
providerはいZilliz Cloud のモデルプロバイダーです。この値には huggingface を設定します。
model_nameはい現在 feature-extraction タスク用に hf-inference 経由で提供されているモデルの Hugging Face Model ID です。
integration_idはいHugging Face モデルプロバイダー統合の ID です。手順の詳細は Integrate with Model Providers を参照してください。
normalizeいいえ正規化された埋め込みをリクエストするかどうかです。省略した場合、Zilliz Cloud は Hugging Face リクエストでこのオプションを設定しません。動作は選択したモデルに従います。
prompt_nameいいえ選択したモデルの Sentence Transformers 構成で定義されているプロンプトの名前です。Hugging Face はエンコード前に該当するプロンプトテキストを先頭に追加します。省略した場合、プロンプトはリクエストされません。
truncateいいえ入力がモデルのサポートする長さを超えた場合に切り捨てをリクエストするかどうかです。省略した場合、Zilliz Cloud は Hugging Face リクエストでこのオプションを設定しません。動作は選択したモデルに従います。
truncation_directionいいえHugging Face が入力を切り捨てる方向です。サポートされる値は left と right です。
max_client_batch_sizeいいえ1 回のリクエストで Hugging Face に送信する入力テキストの最大数です。デフォルト値は 128 です。値は 0 より大きい必要があります。

インデックスを構成する​

出力ベクトルフィールドのインデックスを構成します。次の例では AUTOINDEX とコサイン類似度を使用します。

python
index_params = client.prepare_index_params()

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

コレクションを作成する​

スキーマとインデックスパラメーターを指定してコレクションを作成します。

python
client.create_collection(
    collection_name="hugging_face_demo",
    schema=schema,
    index_params=index_params,
)

コレクションは、384 次元のベクトルを dense フィールドに書き込むテキスト埋め込み関数とともに作成されます。

ステップ 2: データを挿入する​

ベクトルを指定せずに生のテキストを挿入します。Zilliz Cloud は Hugging Face モデルを呼び出し、生成された埋め込みを dense フィールドに書き込みます。

python
client.insert(
    collection_name="hugging_face_demo",
    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.",
        },
    ],
)

挿入操作は生のテキストを格納し、各エンティティに対して 1 つの埋め込みを生成します。

ステップ 3: テキストで検索する​

生のクエリテキストを使用して検索します。Zilliz Cloud は、同じ Function、モデル、およびオプションの推論パラメーターを使用して、ベクトル検索を実行する前にクエリテキストを埋め込みに変換します。

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

print(results)

検索結果には、クエリテキストに最も関連するドキュメントがコサイン類似度順に含まれます。

トラブルシューティング​

feature-extraction タスクでモデルを利用できない​

Hugging Face でモデルページを開き、Inference Providers セクションを確認します。hf-inference が現在そのモデルを提供していること、およびモデルが feature-extraction をサポートしていることを確認してください。いずれかの要件が満たされていない場合は、別のモデルを選択し、そのモデルページで確認します。モデルの互換性の表は完全なリストではなく、記載されていないモデルでも互換性がある場合があります。モデルを変更する場合は、Function の出力フィールドの次元が置き換え後のモデルと一致していることを確認してください。

返されたベクトルの次元がスキーマと一致しない​

モデルの出力次元を確認し、Function の FLOAT_VECTOR 出力フィールドに構成されている dim と比較します。次元が異なるモデルを使用するには、互換性のあるベクトルフィールドまたはコレクションを作成します。カスタム出力次元はサポートされていません。

次のステップ​

Functions の一般的な情報については、Function Overview を参照してください。

Hugging Face Sentence Similarity スコアを使用してベクトル検索の候補を再ランク付けするには、Hugging Face Ranker を参照してください。

このページは役に立ちましたか？
Ctrl I