Ü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_VECTORINT8_VECTOR
Konvertierungen in „
BINARY_VECTOR“, „FLOAT16_VECTOR“ oder „BFLOAT16_VECTOR“ werden nicht unterstützt.
Unterstützte Einbettungs-Service-Provider
Anbieter |
Typische Modelle |
Einbettungstyp |
Authentifizierungsmethode |
|---|---|---|---|
text-embedding-3-* |
|
API-Schlüssel |
|
Bereitstellungsbasiert |
|
API-Schlüssel |
|
text-embedding-v3 |
|
API-Schlüssel |
|
Yandex Cloud AI Studio – Modelle zur Textvektorisierung |
|
API-Schlüssel |
|
amazon.titan-embed-text-v2 |
|
AK/SK-Paar |
|
text-embedding-005 |
|
GCP-Dienstkonto – JSON-Anmeldedaten |
|
voyage-3, voyage-lite-02 |
|
API-Schlüssel |
|
embed-english-v3.0 |
|
API-Schlüssel |
|
BAAI/bge-large-zh-v1.5 |
|
API-Schlüssel |
|
Jedes von TEI bereitgestellte Modell |
|
Optionaler API-Schlüssel |
|
Über |
|
API-Schlüssel |
So funktioniert es
Das folgende Diagramm zeigt, wie die Funktion in Milvus funktioniert.
Eingabetext: Benutzer geben Rohdaten (z. B. Dokumente) in Milvus ein.
Einbettungen generieren: Das Funktionsmodul in Milvus ruft automatisch den konfigurierten Modellanbieter auf, um die Rohdaten in Vektoreinbettungen umzuwandeln.
Einbettungen speichern: Die resultierenden Einbettungen werden in explizit definierten Vektorfeldern innerhalb von Milvus-Sammlungen gespeichert.
Suchtext: Benutzer senden Textabfragen an Milvus.
Semantische Suche: Milvus wandelt die Suchanfragen intern in Vektor-Embeddings um, führt Ähnlichkeitssuchen anhand der gespeicherten Embeddings durch und liefert relevante Ergebnisse.
Ergebnisse zurückgeben: Milvus gibt die am besten passenden Ergebnisse an die Anwendung zurück.
Ü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.
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 |
|---|---|---|
|
Eindeutige Kennung für die Einbettungsfunktion innerhalb von Milvus. |
|
|
Art der verwendeten Funktion. Für die Text-Einbettung setzen Sie den Wert auf „ Hinweis: Milvus akzeptiert für diesen Parameter die Werte „ |
|
|
Skalarfeld, das die einzubettenden Rohdaten enthält. Derzeit akzeptiert dieser Parameter nur einen Feldnamen. |
|
|
Vektorfeld zum Speichern der generierten Einbettungen. Derzeit akzeptiert dieser Parameter nur einen Feldnamen. |
|
|
Wörterbuch mit Einbettungskonfigurationen. Hinweis: Die Parameter innerhalb von „ |
|
|
Der Anbieter des Einbettungsmodells. |
|
|
Gibt an, welches Einbettungsmodell verwendet werden soll. |
|
|
Die Bezeichnung einer Anmeldeinformation, die im obersten Abschnitt „
|
|
|
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 „ |
|
|
Eine Kennung auf Benutzerebene zur Nachverfolgung der API-Nutzung. |
|
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
Schritt 6: Vektorsuche durchführen
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:
- Zunächst wird in der Datei „
milvus.yaml“ nach den für diesen Anbieter konfigurierten Standard-Anmeldedaten gesucht - Wenn in der Datei „milvus.yaml“ keine Standard-Anmeldedaten vorhanden sind, greift das System auf Umgebungsvariablen zurück (sofern diese konfiguriert sind)
- 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:
- Abfrage Ihrer Sammlung nach dem Einfügen, um zu sehen, ob das Vektorfeld Daten enthält
- Überprüfen, ob die Länge des Vektorfeldes mit den erwarteten Dimensionen übereinstimmt
- 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