Hugging FaceCompatible with Milvus v2.6.20+

使用 Hugging Face 嵌入模型時，通常需要您的應用程式自行管理憑證、分別呼叫模型，並針對插入的資料和搜尋查詢一致地產生嵌入向量。透過「文字嵌入函式」，Milvus 會在插入和搜尋過程中呼叫託管的Hugging Face 推論提供者，將原始文字轉換為向量。

此整合功能使用託管的 Hugging Face 路由器。若要將 Milvus 連接到獨立部署的文字嵌入推論 (TEI) 服務，請參閱Hugging Face TEI。

限制

• 「函式輸出」欄位必須使用 `FLOAT_VECTOR ` 資料類型。Milvus 中的 Hugging Face 嵌入功能不支援 `INT8_VECTOR`、`BINARY_VECTOR`、`FLOAT16_VECTOR` 或 `BFLOAT16_VECTOR ` 輸出欄位。
• 「函式」的輸出欄位維度必須與所選模型的輸出維度相符。

運作原理

Hugging Face 文字嵌入工作流程

此工作流程包含三個階段：

1. 傳送原始文字。您的應用程式會在插入或搜尋請求中提供原始文字。
2. 產生嵌入向量。文字嵌入函式會將文字透過hf-inference 傳送至 Hugging Face 的feature-extraction 處理流程。該函式使用model_name 來選取模型，並可傳遞受支援的推論選項，例如正規化與截斷。
3. 使用嵌入向量。Hugging Face 會針對每段輸入文字返回一個浮點數嵌入向量。在插入操作期間，Milvus 會將該向量儲存於函數的輸出欄位中；在搜尋操作期間，Milvus 則會將該向量用作查詢向量。

相同的 Function 配置可同時處理插入與搜尋操作，確保模型與推論參數在兩項操作中保持一致。

開始之前

在使用 Hugging Face 託管文字嵌入功能之前，請確保您已具備：

• 2.6 發行版本線中的 Milvus 2.6.20 或更新版本。
• PyMilvus 2.6.16 或更新版本。
• 一個可呼叫推論提供者的 Hugging Face 使用者存取憑證。
• 目前由hf-inference 提供服務的模型，適用於 feature-extraction 任務所提供的模型。

範例中使用 sentence-transformers/all-MiniLM-L6-v2，該模型可產生 384 維的嵌入向量。此模型僅用於示範設定，並非 Milvus 的推薦或認證。

設定憑證

Milvus 需要一個 Hugging Face 使用者存取憑證（User Access Token）才能呼叫託管路由器。您可以在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

您亦可在函式參數中設定 `credential `。該值必須是 `credential ` 頂層區段中定義的標籤，而非憑證本身。函式層級的憑證標籤優先於提供者層級的標籤。

選項 2：環境變數

若函式或提供者設定中均未指定憑證標籤，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,
)

定義一個「TEXTEMBEDDING 」函式，將嵌入向量從 `document ` 寫入至 `dense`：

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	是	透過hf-inference 提供服務的 Hugging Face 模型 ID，適用於feature-extraction 任務。
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	無	單次 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 會套用相同的「Function」設定來建立查詢向量，然後執行向量搜尋。

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 提供模型服務。若非如此，請選擇另一個模型，並在必要時更新向量場維度。

回傳的向量維度與欄位不符

請檢查模型輸出維度，並與dim 上的「函數輸出欄位」進行比對。若向量維度與FLOAT_VECTOR 欄位維度不符，Milvus 將拒絕該回應。

Milvus 報告缺少 Hugging Face 憑證

請確認「Function」憑證標籤是否存在於頂層的「credential 」區段中，供應商層級的標籤是否有效，或 Milvus 服務環境中是否已配置「MILVUS_HUGGINGFACE_API_KEY 」。

後續步驟

• 有關 Function 的一般概念以及插入/搜尋行為，請參閱《嵌入式函數概覽》。
• 若要使用託管版 Hugging Face 的句子相似度分數對向量搜尋候選結果進行重新排序，請參閱《Hugging Face Ranker》。