DBAPI‑Anbindung an die Milvus‑Vektordatenbank: Praxisbeispiel zur Parameterzuordnung im HTTP‑Executor

Was ist Milvus?

Milvus ist eine Open‑Source‑Vektordatenbank, die speziell für KI‑Anwendungsfälle entwickelt wurde und die Speicherung, Indizierung sowie den Ähnlichkeitssuchbetrieb großer Vektordatensätze unterstützt. Sie findet breite Anwendung in Bereichen wie RAG (Retrieval‑Augmented Generation), semantischer Suche und Empfehlungssystemen.

Milvus stellt ein vollständiges RESTful‑API bereit, über das mittels des HTTP‑Protokolls Operationen wie das Einfügen, Abfragen und Suchen von Vektordaten durchgeführt werden können.

Warum DBAPI zur Anbindung an Milvus verwenden?

Die direkte Nutzung der HTTP‑APIs von Milvus erfordert das manuelle Zusammensetzen der Anforderungsadressen, das Konstruieren der Anfrageparameter sowie die Handhabung von Authentifizierung und Autorisierung. Durch die Anbindung an Milvus mithilfe des HTTP‑Executors von DBAPI profitieren Sie von:

• Einheitlicher API‑Verwaltung: Alle Milvus‑Operationen werden als DBAPI‑APIs zentral verwaltet; Berechtigungen, Rate‑Limiting und Monitoring sind sofort einsatzbereit.
• Vereinfachte Parameterzuordnung: Mit benutzerdefinierten Zuordnungsmodellen werden geschäftliche Parameter automatisch in das erforderliche Anfrageformat für Milvus konvertiert – der Aufrufer muss sich nicht um die Details der Milvus‑Schnittstelle kümmern.
• Sichere Kontrolle: Die Token‑Authentifizierung und IP‑Firewall‑Funktionen von DBAPI werden übernommen.
• Zero‑Code‑Integration: Es ist keine zusätzliche Integrationslogik erforderlich – alles wird rein über Konfiguration realisiert.

Schlüsselmerkmal: Benutzerdefinierte Parameterzuordnung im HTTP‑Executor

DBAPI Enterprise Edition 4.5.0 hat den HTTP‑Executor um einen benutzerdefinierten Zuordnungsmodus erweitert. Mithilfe eines JSON‑Templates mit ${}‑Platzhaltern und Groovy‑Ausdrücken können die vom Aufrufer übergebenen Parameter flexibel in das für die Ziel‑API erforderliche Anfrageformat umgewandelt werden.

Aufrufer gibt ein: { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
                │ Parameterzuordnung im HTTP‑Executor
                ▼  
Milvus empfängt: { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }

Praxisbeispiel: Anbindung an Milvus

Voraussetzungen

• DBAPI Enterprise Edition 4.5.0 oder höher
• Bereits bereitgestellter Milvus‑Dienst (dieses Beispiel verwendet Milvus HTTP API v2)
• In Milvus bereits erstellte Sammlung (Collection)

Schritt 1: Erstellung einer HTTP‑Datenquelle

Gehen Sie im DBAPI‑Admin‑Panel zum Abschnitt Datenquellenverwaltung und klicken Sie auf „Datenquelle erstellen“:

Konfiguration	Wert
Name	Milvus‑Dienst
Typ	HTTP
Adresse	http://192.168.1.100:19530

Die Adresse entspricht dem HTTP‑Port des Milvus‑Dienstes; standardmäßig ist dies Port 19530.

Schritt 2: Erstellung einer API zum Einfügen von Vektoren

Erstellen Sie innerhalb der gewünschten Gruppe eine API unter Verwendung des HTTP‑Executors.

Grundlegende Informationen

Konfiguration	Wert
API‑Name	Milvus‑Vektor‑Einfügen
API‑Pfad	/milvus/insert
Zugriffsrechte	private
Anfrageparameter	id (bigint), vector (string), text (string)

Der Parameter vector ist ein JSON‑String, etwa [0.1, 0.2, 0.3, ...].

Executor‑Konfiguration

Konfiguration	Wert
Executor‑Typ	HTTP‑Interface‑Proxy‑Executor
Datenquelle	Milvus‑Dienst
Methode	POST
URL‑Pfad	/v2/vectordb/entities/insert
Content‑Type	application/json
Übertragungsmodus	Benutzerdefinierte Zuordnung

Benutzerdefinierte Header:

Schlüssel	Wert
Authorization	YOUR_MILVUS_TOKEN

Wenn Milvus eine Authentifizierung aktiviert hat, kann das Token in den benutzerdefinierten Header eingetragen werden; der HTTP‑Executor fügt es automatisch in die Weiterleitungsanfrage ein.

Anfragekörper‑Template:

{"collectionName": "news_articles", "data": [{"id": ${_parameters.id}, "vector": ${_parameters.vector}, "text": ${_parameters.text}}]}

Der Parameter collectionName ist im Template fest codiert; der Aufrufer muss ihn nicht übermitteln. Der Parameter vector wird als JSON‑Array‑String übermittelt und entsprechend dem Feld vector in Milvus zugeordnet.

Ergebnis des Aufrufs

Der Aufrufer sendet folgende Anfrage:

POST https://127.0.0.1:8520/milvus/insert
Content-Type: application/json

{
  "id": 1001,
  "vector": [0.352, 0.187, 0.921, 0.453, 0.672],
  "text": "DBAPI‑Anbindung an die Vektordatenbank"
}

Das System ordnet die Parameter gemäß dem Template neu und leitet die Anfrage an Milvus weiter (der HTTP‑Executor fügt automatisch die benutzerdefinierten Header ein):

POST http://192.168.1.100:19530/v2/vectordb/entities/insert
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN

{"collectionName": "news_articles", "data": [{"id": 1001, "vector": [0.352, 0.187, 0.921, 0.453, 0.672], "text": "DBAPI‑Anbindung an die Vektordatenbank"}]}

Schritt 3: Erstellung einer API zur Vektorsuche

Grundlegende Informationen

Konfiguration	Wert
API‑Name	Milvus‑Vektorsuche
API‑Pfad	/milvus/search
Zugriffsrechte	private
Anfrageparameter	vector (string), limit (bigint)

Executor‑Konfiguration

Konfiguration	Wert
Executor‑Typ	HTTP‑Interface‑Proxy‑Executor
Datenquelle	Milvus‑Dienst
Methode	POST
URL‑Pfad	/v2/vectordb/entities/search
Content‑Type	application/json
Übertragungsmodus	Benutzerdefinierte Zuordnung

Anfragekörper‑Template:

{"collectionName": "news_articles", "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "outputFields": ["id", "text", "vector"]}

Der Parameter collectionName ist im Template fest codiert; der Aufrufer muss lediglich den Vektor und die maximale Anzahl der zurückzugebenden Ergebnisse übermitteln.

Ergebnis des Aufrufs

Der Aufrufer sendet folgende Anfrage:

POST https://127.0.0.1:8520/milvus/search
Content-Type: application/json

{
  "vector": [0.350, 0.190, 0.910, 0.450, 0.670],
  "limit": 5
}

Das System ordnet die Parameter gemäß dem Template neu und leitet die Anfrage an Milvus weiter:

POST http://192.168.1.100:19530/v2/vectordb/entities/search
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN

{"collectionName": "news_articles", "vector": [0.350, 0.190, 0.910, 0.450, 0.670], "limit": 5, "outputFields": ["id", "text", "vector"]}

Schritt 4: Erstellung einer API zur Abfrage nach ID

Grundlegende Informationen

Konfiguration	Wert
API‑Name	Milvus‑Vektor‑Abfrage
API‑Pfad	/milvus/query
Zugriffsrechte	private
Anfrageparameter	collection (string), id (bigint)

Executor‑Konfiguration

Konfiguration	Wert
Executor‑Typ	HTTP‑Interface‑Proxy‑Executor
Datenquelle	Milvus‑Dienst
Methode	POST
URL‑Pfad	/v2/vectordb/entities/query
Content‑Type	application/json
Übertragungsmodus	Benutzerdefinierte Zuordnung

Anfragekörper‑Template:

{"collectionName": ${_parameters.collection}, "filter": "id == " + ${_parameters.id}, "outputFields": ["id", "text", "vector"]}

Mithilfe eines Groovy‑Ausdrucks wird die Filterbedingung id == 1001 dynamisch zusammengesetzt – der Aufrufer muss die Abfragesyntax von Milvus nicht kennen.

Ergebnis des Aufrufs

Der Aufrufer sendet folgende Anfrage:

POST https://127.0.0.1:8520/milvus/query
Content-Type: application/json

{
  "id": 1001
}

Das System ordnet die Parameter gemäß dem Template neu und leitet die Anfrage an Milvus weiter:

POST http://192.168.1.100:19530/v2/vectordb/entities/query
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN

{"collectionName": "news_articles", "filter": "id == 1001", "outputFields": ["id", "text", "vector"]}

Weitere Tipps zur Parameterzuordnung

Komplexe verschachtelte Strukturen

Wenn eine Milvus‑Sammlung mehrere Vektorfelder oder verschachtelte Felder enthält, lassen sich diese flexibel im Template abbilden:

{"collectionName": ${_parameters.collection}, "data": [{"id": ${_parameters.id}, "titleVector": ${_parameters.titleVector}, "contentVector": ${_parameters.contentVector}, "metadata": {"author": ${_parameters.author}, "tags": ${_parameters.tags}}}]}

Parameterberechnungen

Parameter können vorab verarbeitet werden:

{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit + 10}, "offset": ${(_parameters.page - 1) * _parameters.pageSize}}

Bedingte Zuweisungen

Suchparameter können dynamisch abhängig von den übergebenen Werten gesetzt werden:

{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "params": {"nprobe": ${_parameters.precision == "high" ? 64 : 16}}}

Zusammenfassung

Mithilfe der Funktion zur benutzerdefinierten Parameterzuordnung im HTTP‑Executor von DBAPI gestaltet sich die Anbindung an die Milvus‑Vektordatenbank äußerst einfach:

• Der Aufrufer muss lediglich geschäftsbezogene Parameter übermitteln – Kenntnisse der Milvus‑API sind nicht erforderlich.
• Die Zuordnungsvorlagen werden zentral verwaltet; bei Änderungen der Milvus‑Schnittstelle müssen nur die Templates angepasst werden, ohne dass der Aufrufer betroffen ist.
• Die Schnittstelle nutzt sämtliche Unternehmensfunktionen von DBAPI, darunter Authentifizierung, Rate‑Limiting und Monitoring.
• Die Integration erfolgt komplett ohne Code – alles wird rein über Konfiguration realisiert.

Versionsempfehlung: DBAPI Enterprise Edition 4.5.0 oder höher unterstützt die Funktion zur benutzerdefinierten Parameterzuordnung im HTTP‑Executor.