Hugging FaceCompatible with Milvus v2.6.20+

Die Verwendung eines Hugging Face-Embedding-Modells erfordert normalerweise, dass Ihre Anwendung Anmeldedaten verwaltet, das Modell separat aufruft und Embeddings für eingefügte Daten und Suchanfragen konsistent generiert. Mit einer Text-Embedding-Funktion ruft Milvus gehostete Hugging Face-Inferenz-Provider auf, um Rohtext während des Einfügens und der Suche in Vektoren umzuwandeln.

Diese Integration nutzt den gehosteten Hugging Face-Router. Informationen zur Anbindung von Milvus an einen separat bereitgestellten Text Embeddings Inference (TEI)-Dienst finden Sie unter Hugging Face TEI.

Einschränkungen

• Das Ausgabefeld der Funktion muss den Datentyp „ FLOAT_VECTOR “ verwenden. Die Hugging-Face-Einbettung in Milvus unterstützt keine Ausgabefelder vom Typ „ INT8_VECTOR “, „ BINARY_VECTOR “, „ FLOAT16_VECTOR “ oder „ BFLOAT16_VECTOR “.
• Die Dimension des Ausgabefelds „Function“ muss mit der Ausgabedimension des ausgewählten Modells übereinstimmen.

So funktioniert es

Workflow für Hugging Face-Text-Embeddings

Der Workflow umfasst drei Schritte:

1. Rohtext senden. Ihre Anwendung stellt den Rohtext in einer Einfüge- oder Suchanfrage bereit.
2. Einbettung generieren. Die Text-Embedding-Funktion leitet den Text über „ hf-inference “ an die Hugging Face-Pipeline „ feature-extraction “ weiter. Die Funktion nutzt „ model_name “, um das Modell auszuwählen, und kann unterstützte Inferenzoptionen wie Normalisierung und Trunkierung übergeben.
3. Verwenden Sie die Einbettung. Hugging Face gibt pro Eingabetext eine Gleitkomma-Einbettung zurück. Beim Einfügen speichert Milvus den Vektor im Ausgabefeld der Funktion. Bei der Suche verwendet Milvus den Vektor als Abfragevektor.

Dieselbe Funktionskonfiguration übernimmt sowohl das Einfügen als auch die Suche, wodurch das Modell und die Inferenzparameter bei beiden Vorgängen konsistent bleiben.

Bevor Sie beginnen

Bevor Sie die gehostete Hugging-Face-Text-Einbettung verwenden, stellen Sie sicher, dass Sie über Folgendes verfügen:

• Milvus 2.6.20 oder höher aus der 2.6-Release-Reihe.
• PyMilvus 2.6.16 oder höher.
• Ein Hugging Face-Benutzerzugriffstoken, mit dem Inferenz-Provider aufgerufen werden können.
• Ein Modell, das derzeit von hf-inference für die feature-extraction Aufgabe bereitgestellt wird.

In den Beispielen wird sentence-transformers/all-MiniLM-L6-v2, das 384-dimensionale Einbettungen erzeugt. Das Modell dient lediglich zur Veranschaulichung der Konfiguration und stellt keine Empfehlung oder Zertifizierung durch Milvus dar.

Anmeldedaten konfigurieren

Milvus benötigt ein Hugging-Face-Benutzerzugriffstoken, um den gehosteten Router aufzurufen. Sie können das Token unter milvus.yaml oder über eine Umgebungsvariable konfigurieren.

Die Prioritätsreihenfolge der Anmeldedaten lautet:

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

Option 1: Konfigurationsdatei

Definieren Sie das Token im obersten Abschnitt „ credential “ unter milvus.yaml und verweisen Sie den Hugging-Face-Einbettungsanbieter auf dieses Anmelde-Label:

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

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

Sie können „ credential “ auch in den Funktionsparametern festlegen. Der Wert muss das im obersten Abschnitt „ credential “ definierte Label sein, nicht das Token selbst. Ein Anmelde-Label auf Funktionsebene hat Vorrang vor dem Label auf Anbieterebene.

Option 2: Umgebungsvariable

Wenn weder in der Funktions- noch in der Anbieter-Konfiguration ein Anmelde-Label angegeben ist, liest Milvus das Token aus „ MILVUS_HUGGINGFACE_API_KEY “ aus.

Für Docker Compose setzen Sie die Variable im Milvus-Standalone-Dienst:

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

Einzelheiten zur Anwendung von Docker-Compose-Einstellungen finden Sie unter „Milvus mit Docker Compose konfigurieren“.

Hugging Face-Text-Embedding verwenden

Schritt 1: Erstellen Sie eine Sammlung mit einer Text-Embedding-Funktion

Erstellen Sie ein Schema mit einem Primärfeld, einem Eingabefeld „ VARCHAR “ und einem Ausgabefeld „ FLOAT_VECTOR “. Die Ausgabedimension muss mit dem ausgewählten Modell übereinstimmen.

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

Definieren Sie eine „ TEXTEMBEDDING “-Funktion, die Einbettungen von „ document “ in „ dense “ schreibt:

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)

Wenn Sie nur die Anmeldeinformationen auf Anbieterebene oder die Umgebungsvariable verwenden, lassen Sie „ credential “ in den Funktionsparametern weg.

Konfigurieren Sie einen Index für das Ausgabefeld und erstellen Sie anschließend die Sammlung:

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

Die folgende Tabelle beschreibt die Hugging Face-spezifischen Funktionsparameter:

Parameter	Erforderlich?	Beschreibung
provider	Ja	Der Anbieter des Einbettungsmodells. Setzen Sie diesen Wert auf „ huggingface “.
model_name	Ja	Die Hugging-Face-Modell-ID für ein Modell, das über hf-inference für die Aufgabe „ feature-extraction “ bereitgestellt wird.
hf_provider	Nein	Die Route des Hugging Face-Inferenzanbieters. Der Standardwert und der einzige in Milvus 2.6.20 unterstützte Wert ist hf-inference.
credential	Nein	Die Bezeichnung einer Anmeldeinformation, die im obersten Abschnitt „ credential “ von „ milvus.yaml “ definiert ist. Dieser Wert ist nicht das Token selbst.
normalize	Nein	Gibt an, ob Hugging Face normalisierte Embeddings zurückgeben soll. Unterstützte Werte sind „ true “ und „ false “. Wird dieser Wert weggelassen, setzt Milvus diese Option in der Anfrage nicht.
prompt_name	Nein	Der Name eines Prompts, der in der „Sentence Transformers“-Konfiguration des ausgewählten Modells definiert ist.
truncate	Nein	Ob Hugging Face eine Eingabe kürzen soll, die die vom Modell unterstützte Länge überschreitet. Unterstützte Werte sind „ true “ und „ false “.
truncation_direction	Nein	Die Richtung, aus der Hugging Face eine Eingabe abschneidet. Unterstützte Werte sind „ left “ und „ right “.
max_client_batch_size	Nein	Die maximale Anzahl an Eingabetexten, die in einer Hugging-Face-Anfrage gesendet werden dürfen. Der Standardwert ist „ 128 “, und der Wert muss größer als „ 0 “ sein.

Schritt 2: Rohtext einfügen

Fügen Sie Text ein, ohne Vektoren anzugeben. Milvus ruft Hugging Face auf und schreibt die generierten Embeddings in „ 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.",
        },
    ],
)

Schritt 3: Suche mit Rohtext

Suche mit einer Textabfrage. Milvus wendet dieselbe Funktionskonfiguration an, um den Abfragevektor zu erstellen, bevor die Vektorsuche ausgeführt wird.

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)

Das Ergebnis enthält die für den Suchtext relevantesten Dokumente, sortiert nach Kosinus-Ähnlichkeit.

Fehlerbehebung

Das Modell ist für die Merkmalsextraktion nicht verfügbar

Öffnen Sie die Modellseite auf Hugging Face und überprüfen Sie den Abschnitt „Inference Providers “. Vergewissern Sie sich, dass „ hf-inference “ das Modell für „ feature-extraction “ bereitstellt. Ist dies nicht der Fall, wählen Sie ein anderes Modell aus und passen Sie gegebenenfalls die Vektorfelddimension an.

Die zurückgegebene Vektordimension stimmt nicht mit dem Feld überein

Überprüfen Sie die Ausgabedimension des Modells und vergleichen Sie diese mit dim im Feld „Function output“. Milvus lehnt eine Antwort ab, deren Vektordimension von der Felddimension unter FLOAT_VECTOR abweicht.

Milvus meldet fehlende Hugging-Face-Anmeldedaten

Stellen Sie sicher, dass das Label „Function credential“ im obersten Abschnitt „ credential “ vorhanden ist, dass das Label auf Anbieterebene gültig ist oder dass „ MILVUS_HUGGINGFACE_API_KEY “ in der Milvus-Serviceumgebung vorhanden ist.

Nächste Schritte

• Allgemeine Konzepte zu „Function“ sowie Informationen zum Einfüge- und Suchverhalten finden Sie unter „Embedding Function – Übersicht“.
• Informationen zum erneuten Ranking von Kandidaten bei der Vektorsuche mit gehosteten Hugging-Face-Satzähnlichkeitswerten finden Sie unter „Hugging Face Ranker“.