Übersicht über die EinbettungsfunktionCompatible with Milvus 2.6.x

Das Funktionsmodul in Milvus ermöglicht es Ihnen, Rohtextdaten in Vektor-Einbettungen umzuwandeln, indem es automatisch externe Einbettungsdienstleister (wie OpenAI, AWS Bedrock, Google Vertex AI usw.) aufruft. Mit dem Funktionsmodul müssen Sie nicht mehr manuell auf Einbettungs-APIs zugreifen – Milvus übernimmt den gesamten Prozess vom Senden der Anfragen an die Anbieter über den Empfang der Einbettungen bis hin zur Speicherung in Ihren Sammlungen. Für die semantische Suche müssen Sie lediglich die Rohdaten der Abfrage bereitstellen, keinen Abfragevektor. Milvus generiert den Abfragevektor mit demselben Modell, das Sie für die Datenaufnahme verwendet haben, vergleicht ihn mit den gespeicherten Vektoren und liefert die relevantesten Ergebnisse zurück.

Einschränkungen

  • Jedes Eingabefeld, das das Funktionsmodul einbettet, muss immer einen Wert enthalten; wird ein Nullwert angegeben, löst das Modul einen Fehler aus.

  • Das „Function“-Modul verarbeitet nur Felder, die explizit im Sammlungsschema definiert sind; es generiert keine Einbettungen für dynamische Felder.

  • Zu einbettende Eingabefelder müssen vom Typ „ VARCHAR “ sein.

  • Das Funktionsmodul kann ein Eingabefeld wie folgt einbetten:

    • FLOAT_VECTOR

    • INT8_VECTOR

    Konvertierungen in „ BINARY_VECTOR “, „ FLOAT16_VECTOR “ oder „ BFLOAT16_VECTOR “ werden nicht unterstützt.

Unterstützte Einbettungs-Service-Provider

Anbieter

Typische Modelle

Einbettungstyp

Authentifizierungsmethode

OpenAI

text-embedding-3-*

FLOAT_VECTOR

API-Schlüssel

Azure OpenAI

Bereitstellungsbasiert

FLOAT_VECTOR

API-Schlüssel

DashScope

text-embedding-v3

FLOAT_VECTOR

API-Schlüssel

Yandex Cloud

Yandex Cloud AI Studio – Modelle zur Textvektorisierung

FLOAT_VECTOR

API-Schlüssel

Bedrock

amazon.titan-embed-text-v2

FLOAT_VECTOR

AK/SK-Paar

Vertex AI

text-embedding-005

FLOAT_VECTOR

GCP-Dienstkonto – JSON-Anmeldedaten

Voyage AI

voyage-3, voyage-lite-02

FLOAT_VECTOR / INT8_VECTOR

API-Schlüssel

Cohere

embed-english-v3.0

FLOAT_VECTOR / INT8_VECTOR

API-Schlüssel

SiliconFlow

BAAI/bge-large-zh-v1.5

FLOAT_VECTOR

API-Schlüssel

Hugging Face TEI

Jedes von TEI bereitgestellte Modell

FLOAT_VECTOR

Optionaler API-Schlüssel

Hugging Face

Über hf-inference bereitgestellte Modelle zur Merkmalsextraktion

FLOAT_VECTOR

API-Schlüssel

So funktioniert es

Das folgende Diagramm zeigt, wie die Funktion in Milvus funktioniert.

  1. Eingabetext: Benutzer geben Rohdaten (z. B. Dokumente) in Milvus ein.

  2. Einbettungen generieren: Das Funktionsmodul in Milvus ruft automatisch den konfigurierten Modellanbieter auf, um die Rohdaten in Vektoreinbettungen umzuwandeln.

  3. Einbettungen speichern: Die resultierenden Einbettungen werden in explizit definierten Vektorfeldern innerhalb von Milvus-Sammlungen gespeichert.

  4. Suchtext: Benutzer senden Textabfragen an Milvus.

  5. Semantische Suche: Milvus wandelt die Suchanfragen intern in Vektor-Embeddings um, führt Ähnlichkeitssuchen anhand der gespeicherten Embeddings durch und liefert relevante Ergebnisse.

  6. Ergebnisse zurückgeben: Milvus gibt die am besten passenden Ergebnisse an die Anwendung zurück.

Embedding Function Overview Übersicht über die Einbettungsfunktion

Anmeldedaten konfigurieren

Bevor Sie eine Einbettungsfunktion mit Milvus verwenden, müssen Sie die Anmeldedaten für den Einbettungsdienst für den Zugriff auf Milvus konfigurieren.

Milvus bietet Ihnen zwei Möglichkeiten, die Anmeldedaten für den Einbettungsdienst anzugeben:

  • Konfigurationsdatei (milvus.yaml):

    Das Beispiel in diesem Abschnitt veranschaulicht die empfohlene Einrichtung mithilfe von „ milvus.yaml “.

  • Umgebungsvariablen:

    Einzelheiten zur Konfiguration der Anmeldedaten über Umgebungsvariablen finden Sie in der Dokumentation des Embedding-Dienstanbieters (z. B. OpenAI oder Azure OpenAI).

Das folgende Diagramm zeigt den Ablauf der Konfiguration von Anmeldeinformationen über die Milvus-Konfigurationsdatei (milvus.yaml) und den anschließenden Aufruf der Funktion innerhalb von Milvus.

Credential Config Overflow Konfiguration der Anmeldedaten in Milvus

Schritt 1: Anmeldeinformationen zur Milvus-Konfigurationsdatei hinzufügen

Bearbeiten Sie in Ihrer Datei „ milvus.yaml “ den Block „ credential “ mit Einträgen für jeden Anbieter, auf den Sie zugreifen möchten:

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

Schritt 2: Konfigurieren der Anbietereinstellungen

Bearbeiten Sie in derselben Konfigurationsdatei (milvus.yaml) den Block „ function “, um Milvus mitzuteilen, welcher Schlüssel für die Einbettung von Dienstaufrufen verwendet werden soll:

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

Weitere Informationen zur Anwendung der Milvus-Konfiguration finden Sie unter „Milvus on the Fly konfigurieren“.

Verwenden der Einbettungsfunktion

Sobald die Anmeldedaten in Ihrer Milvus-Konfigurationsdatei konfiguriert sind, führen Sie die folgenden Schritte aus, um Einbettungsfunktionen zu definieren und zu verwenden.

Schritt 1: Schemafelder definieren

Um eine Einbettungsfunktion zu verwenden, erstellen Sie eine Sammlung mit einem bestimmten Schema. Dieses Schema muss mindestens drei erforderliche Felder enthalten:

  • Das Primärfeld, das jede Entität in einer Sammlung eindeutig identifiziert.

  • Ein Skalarfeld, in dem die einzubettenden Rohdaten gespeichert werden.

  • Ein Vektorfeld, das für die Speicherung von Vektor-Einbettungen reserviert ist, die die Funktion für das Skalarfeld generiert.

Das folgende Beispiel definiert ein Schema mit einem Skalarfeld „ "document" “ zur Speicherung von Textdaten und einem Vektorfeld „ "dense" “ zur Speicherung der vom Funktionsmodul zu generierenden Einbettungen. Denken Sie daran, die Vektordimension (dim) so festzulegen, dass sie mit der Ausgabe Ihres gewählten Einbettungsmodells übereinstimmt.

from pymilvus import MilvusClient, DataType, Function, FunctionType

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
# For instance, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)
// java
// nodejs
// go
# restful

Schritt 2: Einbettungsfunktion zum Schema hinzufügen

Das „Function“-Modul in Milvus wandelt die in einem Skalarfeld gespeicherten Rohdaten automatisch in Einbettungen um und speichert diese im explizit definierten Vektorfeld.

Im folgenden Beispiel wird ein Funktionsmodul (openai_embedding) hinzugefügt, das das Skalarfeld „ "document" “ in Einbettungen umwandelt und die resultierenden Vektoren im zuvor definierten Vektorfeld „ "dense" “ speichert.

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_embedding",                  # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING, # Type of embedding function
    input_field_names=["document"],           # Scalar field to embed
    output_field_names=["dense"],             # Vector field to store embeddings
    params={                                  # Provider-specific configuration (highest priority)
        "provider": "openai",                 # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

# Add the embedding function to your schema
schema.add_function(text_embedding_function)
// java
// nodejs
// go
# restful

Parameter

Beschreibung

Beispielwert

name

Eindeutige Kennung für die Einbettungsfunktion innerhalb von Milvus.

"openai_embedding"

function_type

Art der verwendeten Funktion. Für die Text-Einbettung setzen Sie den Wert auf „ FunctionType.TEXTEMBEDDING “.

Hinweis: Milvus akzeptiert für diesen Parameter die Werte „ FunctionType.BM25 “ (für die Sparse-Embedding-Transformation) und „ FunctionType.RERANK “ (für das Reranking). Weitere Informationen finden Sie in den Übersichten zur Volltextsuche und zum Decay Ranker.

FunctionType.TEXTEMBEDDING

input_field_names

Skalarfeld, das die einzubettenden Rohdaten enthält. Derzeit akzeptiert dieser Parameter nur einen Feldnamen.

["document"]

output_field_names

Vektorfeld zum Speichern der generierten Einbettungen. Derzeit akzeptiert dieser Parameter nur einen Feldnamen.

["dense"]

params

Wörterbuch mit Einbettungskonfigurationen. Hinweis: Die Parameter innerhalb von „ params “ variieren je nach Anbieter des Einbettungsmodells.

{...}

provider

Der Anbieter des Einbettungsmodells.

"openai"

model_name

Gibt an, welches Einbettungsmodell verwendet werden soll.

"text-embedding-3-small"

credential

Die Bezeichnung einer Anmeldeinformation, die im obersten Abschnitt „ credential: “ unter milvus.yaml definiert ist.

  • Wenn diese Angabe erfolgt, ruft Milvus das passende Schlüsselpaar oder API-Token ab und signiert die Anfrage serverseitig.

  • Wird es weggelassen (None), greift Milvus auf die Anmeldeinformationen zurück, die in milvus.yaml explizit für den Zielmodellanbieter konfiguriert wurden.

  • Ist die Bezeichnung unbekannt oder fehlt der referenzierte Schlüssel, schlägt der Aufruf fehl.

"apikey1"

dim

Die Anzahl der Dimensionen für die Ausgabe-Embeddings. Bei den Modellen der dritten Generation von OpenAI können Sie den vollständigen Vektor verkürzen, um Kosten und Latenz zu reduzieren, ohne dabei nennenswerte semantische Informationen zu verlieren. Weitere Informationen finden Sie im entsprechenden Blogbeitrag von OpenAI.

Hinweis: Wenn Sie die Vektordimension verkürzen, stellen Sie sicher, dass der Wert „ dim “, der in der Methode „ add_field “ des Schemas für das Vektorfeld angegeben ist, mit der endgültigen Ausgabedimension Ihrer Einbettungsfunktion übereinstimmt.

"1536"

user

Eine Kennung auf Benutzerebene zur Nachverfolgung der API-Nutzung.

"user123"

Für Sammlungen mit mehreren Skalarfeldern, die eine Text-zu-Vektor-Konvertierung erfordern, fügen Sie dem Sammlungsschema separate Funktionen hinzu und stellen Sie sicher, dass jede Funktion einen eindeutigen Namen und einen eindeutigen „ output_field_names “-Wert hat.

Schritt 3: Index konfigurieren

Nachdem Sie das Schema mit den erforderlichen Feldern und der integrierten Funktion definiert haben, richten Sie den Index für Ihre Sammlung ein. Um diesen Vorgang zu vereinfachen, verwenden Sie „ AUTOINDEX “ als „ index_type “ – eine Option, die es Milvus ermöglicht, den am besten geeigneten Indextyp basierend auf der Struktur Ihrer Daten auszuwählen und zu konfigurieren.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)
// java
// nodejs
// go
# restful

Schritt 4: Sammlung erstellen

Erstellen Sie nun die Sammlung unter Verwendung der definierten Schema- und Indexparameter.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)
// java
// nodejs
// go
# restful

Schritt 5: Daten einfügen

Nachdem Sie Ihre Sammlung und Ihren Index eingerichtet haben, können Sie Ihre Rohdaten einfügen. Dabei müssen Sie lediglich den Rohtext bereitstellen. Das zuvor definierte Funktionsmodul generiert automatisch den entsprechenden Sparse-Vektor für jeden Texteintrag.

# Insert sample documents
client.insert('demo', [
    {'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.'},
])
// java
// nodejs
// go
# restful

Führen Sie nach dem Einfügen der Daten eine semantische Suche anhand des Rohtextes Ihrer Abfrage durch. Milvus wandelt Ihre Abfrage automatisch in einen Einbettungsvektor um, ruft relevante Dokumente auf der Grundlage der Ähnlichkeit ab und gibt die am besten passenden Ergebnisse zurück.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]
// java
// nodejs
// go
# restful

Weitere Informationen zu Such- und Abfragevorgängen finden Sie unter „Grundlagen der Vektorsuche und -abfrage“.

FAQ

Was ist der Unterschied zwischen der Konfiguration von Anmeldedaten in der Datei „milvus.yaml“ und der Verwendung von Umgebungsvariablen?

Beide Methoden funktionieren, jedoch wird die Verwendung von „ milvus.yaml “ empfohlen, da dies eine zentralisierte Verwaltung der Anmeldedaten und eine einheitliche Benennung der Anmeldedaten über alle Anbieter hinweg ermöglicht. Bei der Verwendung von Umgebungsvariablen variieren die Variablennamen je nach Anbieter des Einbettungsdienstes. Informieren Sie sich daher auf der jeweiligen Seite des Anbieters über die spezifischen Namen der erforderlichen Umgebungsvariablen (z. B. OpenAI oder Azure OpenAI).

Was passiert, wenn ich in der Funktionsdefinition keinen Anmeldeparameter angebe?

Milvus folgt dieser Reihenfolge bei der Auflösung von Anmeldeinformationen:

  1. Zunächst wird in der Datei „ milvus.yaml “ nach den für diesen Anbieter konfigurierten Standard-Anmeldedaten gesucht
  2. Wenn in der Datei „milvus.yaml“ keine Standard-Anmeldedaten vorhanden sind, greift das System auf Umgebungsvariablen zurück (sofern diese konfiguriert sind)
  3. Sind weder Anmeldedaten in „ milvus.yaml “ noch Umgebungsvariablen konfiguriert, löst Milvus einen Fehler aus

Wie kann ich überprüfen, ob die Embeddings korrekt generiert werden?

Sie können dies wie folgt überprüfen:

  1. Abfrage Ihrer Sammlung nach dem Einfügen, um zu sehen, ob das Vektorfeld Daten enthält
  2. Überprüfen, ob die Länge des Vektorfeldes mit den erwarteten Dimensionen übereinstimmt
  3. Führen Sie eine einfache Ähnlichkeitssuche durch, um zu überprüfen, ob die Einbettungen aussagekräftige Ergebnisse liefern

Kann ich bei einer Ähnlichkeitssuche einen Abfragevektor anstelle von Rohtext verwenden?

Ja, Sie können für die Ähnlichkeitssuche vorberechnete Abfragevektoren anstelle von Rohtext verwenden. Das Funktionsmodul wandelt zwar Rohtext-Abfragen automatisch in Einbettungen um, Sie können jedoch auch direkt Vektordaten an den Parameter „ data “ in Ihrer Suchoperation übergeben. Hinweis: Die Dimensionsgröße Ihres angegebenen Abfragevektors muss mit der Dimensionsgröße der von Ihrem Funktionsmodul generierten Vektor-Embeddings übereinstimmen.

Beispiel:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)
// java
// nodejs
// go
# restful