Erste Schritte mit der Zilliz REST API
Zilliz Cloud ist ein umfassender Vektordatenbank-Service, der Anwendungen für künstliche Intelligenz (KI) und Analytik in großem Maßstab ermöglicht und beschleunigt. Er basiert auf Milvus, der robusten und skalierbaren Open-Source-Vektordatenbank, die problemlos Milliarden von Vektoreinbettungen verarbeiten kann.
Milvus vereinfacht den Umgang mit unstrukturierten Daten und ermöglicht es Unternehmen, riesige Datenmengen effizient zu analysieren und daraus Erkenntnisse zu gewinnen. Indem Zilliz Cloud Ihnen eine skalierbare, cloudfähige Vektordatenbank bereitstellt, dient es als Komplettlösung.
Die Anwendungsfälle für Milvus und Zilliz Cloud sind breit gefächert und vielfältig. Sie können Empfehlungssysteme antreiben, um durch die Analyse des Browsing- und Kaufverhaltens eines Kunden personalisierte Einkaufserlebnisse anzubieten. Im Gesundheitswesen können sie beim Aufbau von KI-Modellen helfen, die Muster in großen medizinischen Datensätzen erkennen, was zu genaueren Diagnosen und personalisierten Behandlungsplänen führt.
Eine Funktion, die Zilliz Cloud zu Milvus hinzufügt, ist eine REST API zur Verwaltung Ihrer Vektordatenbanken, mit einfachen Methoden zum Manipulieren von Collections, Hochladen und Löschen von Daten sowie zum Einreichen von Abfragen. Dieser Beitrag zeigt Ihnen, wie Sie diese APIs verwenden. Legen wir los!
Bevor wir beginnen
Sie benötigen ein paar Dinge, um diesem Tutorial zu folgen:
Zunächst benötigen Sie ein Zilliz Cloud-Konto. Wenn Sie bereits eines haben, können Sie direkt zum Abrufen der URL und des API-Schlüssels Ihres Clusters springen.
Alles, was in diesem Beitrag behandelt wird, funktioniert mit einem kostenlosen Konto, daher müssen Sie nur hier hingehen und auf Get Started Free klicken. Melden Sie sich dann in Ihrem Zilliz-Dashboard an und folgen Sie den Anweisungen, um einen Cluster zu erstellen.
Neuen Cluster erstellen
Geben Sie ihm einen Namen. Die Standardoptionen sind für dieses Tutorial ausreichend. Klicken Sie auf Next: Create Collection.
Collection für Ihren neuen Cluster erstellen
Wählen Sie Example Collection und dann Create Collection and Cluster.
Mit Ihrem Cluster verbinden
Dieser Dialog enthält Ihre Cluster-URL und Ihren API-Schlüssel. Kopieren Sie sie für die spätere Verwendung. Sie können sie auch aus Ihrem Dashboard abrufen, indem Sie den Cluster auswählen.
Die Beispiele in diesem Tutorial enthalten Code aus Visual Studio Code und dem vscode-restclient-Plugin.
Sie finden die Abfragen hier, in einem Gist. Sie können mit jedem HTTP-Client mitmachen oder den Playground in Ihrem Zilliz-Dashboard verwenden.
Überblick über die Zilliz REST API
Die Zilliz REST API verfügt über Methoden zur Verwaltung von Clustern, Collections und Vektordaten. Wir konzentrieren uns auf die letzten beiden Kategorien: das Erstellen von Collections zum Speichern von Daten und das Verwalten der Daten innerhalb der Collection.
Collection-Operationen umfassen:
Auflisten
Erstellen
Beschreiben
Verwerfen
Vektoroperationen umfassen:
Abfragen
Abrufen
Einfügen
Löschen
Suchen
Komponenten eines API-Aufrufs
Der erste Teil all Ihrer API-Endpunkte ist der öffentliche Endpunkt Ihres Clusters, den Sie oben kopiert haben, gefolgt von der API-Version und /vector/, dem Verzeichnis der obersten Ebene für API-Methoden.
Zum Beispiel begann die URL meines Clusters damit:
https://in03-75204f04fc4368d.api.gcp-us-west1.zillizcloud.com/v1/vector
Die Beispielaufrufe verwenden $PUBLIC_ENDPOINT als Platzhalter für den Hostnamen Ihres Clusters.
Jeder API-Aufruf erfordert zwei Header:
content_type - dies ist immer application/json. Dies teilt dem Webserver mit, dass alle von Ihnen gesendeten Daten JSON sind.
Authorization - alle Anfragen benötigen diesen Header mit Ihrem API-Schlüssel.
Die Beispielaufrufe verwenden $YOUR_API_KEY als Platzhalter für den Hostnamen Ihres Clusters.
Beginnen wir mit Collections.
Erste Schritte mit der Zilliz API
Collections erstellen, beschreiben, löschen und auflisten
Zuerst wollen wir die Collections auflisten, die sich in Ihrem Cluster befinden.
Der Endpunkt für Collection-Operationen ist /collections. Ein GET-Aufruf dorthin liefert eine Liste.
Hier ist der Aufruf im VS Code Rest Client:
GET https://$PUBLIC_ENDPOINT/v1/vector/collections HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Und hier ist die Antwort, mit allen Headern. Ich werde sie im Folgenden weglassen.
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
Content-Length: 40
x-ratelimit-remaining-second: 999
x-ratelimit-limit-second: 1000
ratelimit-limit: 1000
ratelimit-remaining: 999
ratelimit-reset: 1 x-sso-plugin-version: v0.0.1
date: Mon, 10 Jul 2023 17:53:12 GMT
vary: Origin access-control-allow-origin: *
requestid: 8c5a2031-afbe-4fa2-9a28-8195e1f20357
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff via: 1.1 google Alt-Svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
Connection: close
{
"code": 200,
"data": [
"medium_articles"
]
}
Der Server gibt einen Erfolgscode von 200 und ein data-Feld mit einem Vektor von Collection-Namen zurück.
Lassen Sie uns eine neue Collection hinzufügen und anschließend die neue Liste abrufen.
Senden Sie dafür per POST ein Dokument, das die Collection beschreibt, an /collections/create.
POST https://$PUBLIC_ENDPOINT/v1/vector/collections/create HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "large_articles",
"dimension": 256,
"metricType": "L2",
"primaryField": "id",
"vectorField": "vector"
}
Sie können fünf Felder angeben, um Ihre Collection zu beschreiben:
collectionName - der Name ist erforderlich.
dimension - die Anzahl der Dimensionen für das Vektorfeld ist ebenfalls erforderlich.
metricType - der Typ der Ähnlichkeitsmetriken, die verwendet werden, um die Ähnlichkeit zwischen Vektoren zu messen. In diesem Beispiel ist der Standard-Metriktyp L2, der die euklidische Distanz darstellt.
primaryField - das standardmäßige Primärfeld ist id.
vectorField - das standardmäßige Vektorfeld ist vector.
Bei Erfolg antwortet Zilliz mit 200 und einem leeren Dokument.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Listen Sie Ihre Collections erneut auf, und Sie werden zwei Namen sehen.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
"medium_articles",
"large_articles"
]
}
Sie können eine Beschreibung für eine bestehende Collection abrufen. Senden Sie dafür ein GET mit collectionName als Anfrageparameter.
GET https://$PUBLIC_ENDPOINT/v1/vector/collections/describe?collectionName=medium_articles HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Diese Antwort ist eine detaillierte Beschreibung des aktuellen Zustands Ihrer Collection.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"collectionName": "medium_articles",
"shardsNum": 2,
"description": "demo collection",
"load": "loaded",
"enableDynamicField": true,
"fields": [
{
"name": "id",
"type": "int64",
"primaryKey": true,
"autoId": true,
"description": ""
},
{
"name": "title_vector",
"type": "floatVector(256)",
"primaryKey": false,
"autoId": false,
"description": ""
}
],
"indexes": [
{
"indexName": "vector_idx",
"fieldName": "vector",
"metricType": "L2"
}
]
}
}
Zum Schluss räumen wir auf, indem wir die gerade erstellte Collection löschen. Dies ist eine POST-Anfrage an /collections/drop. Anstatt den Namen als Parameter zu übergeben, verwenden Sie daher ein JSON-Dokument.
POST https://$PUBLIC_ENDPOINT/v1/vector/collections/drop HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "large_articles"
}
Die Antwort ähnelt der, die Zilliz beim Erstellen einer Collection sendet.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Fordern Sie eine weitere Liste von Collections an, und Sie werden sehen, dass Sie wieder bei einer sind. Arbeiten wir nun mit einigen Daten.
Daten einfügen
Um Daten einzufügen, senden Sie eine POST-Anfrage an /insert mit einem Dokument, das die Daten beschreibt.
Wenn Sie sich die oben abgerufene Beschreibung ansehen, hat die Beispiel-Collection zwei Felder:
id - ein Integer-Wert
title_vector - ein Vektor mit 768 Floats
Sie benötigen also ein Dokument mit einem Wert, der diese beiden Felder im data-Feld der Insert-Anfrage enthält. Data ist eine Liste, damit Sie mehr als einen Wert einfügen können.
Hier ist eine Anfrage mit einem Wert:
POST https://$PUBLIC_ENDPOINT/v1/vector/insert HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName":"medium_articles",
"data": [
{
"id": 1,
"title_vector": [
0.2109777665089908,
0.6424190129752343,
(768 values)...
0.9818514815450557
],
},
]
}
Senden Sie diesen Code ab. Ihre Antwort ist die Anzahl der eingefügten Elemente und deren IDs.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"insertCount": 1,
"insertIds": [
"1"
]
}
}
Daten abfragen, suchen und abrufen
Die Zilliz REST API verfügt über drei Methoden zum Abrufen von Daten: Abfragen, Suchen und Abrufen.
Eine Vektorabfrage verwendet Kriterien, um Einträge in der Datenbank abzugleichen. Beginnen wir mit einer Abfrage basierend auf dem id-Feld.
Für diese Abfrage senden Sie per POST ein Suchdokument an /query. Es verwendet den in-Operator, um Einträge mit IDs von 1 oder 2 abzugleichen.
POST https://$PUBLIC_ENDPOINT/v1/vector/query HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"filter": "id in (1, 2)"
}
Milvus antwortet mit dem Wert, den Sie gerade eingefügt haben, zusammen mit Daten aus der Beispiel-Collection.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
{
"id": 1,
"title_vector": [
0.21097776,
0.5381259,
0.48835102,
0.15038285,
0.94545513,
(768 values)...
]
},
{
"claps": 500,
"id": 2,
"link": "https://medium.com/swlh/how-can-we-best-switch-in-python-458fb33f7835",
"publication": "The Startup",
"reading_time": 6,
"responses": 7,
"title": "How Can We Best Switch in Python?",
"title_vector": [
0.031961977,
0.00047043373,
-0.018263113,
0.027324716,
-0.0054595284,
-0.014779159,
(768 values)...
]
}
}
Sie können outputFields verwenden, um die Ergebnisse zu filtern.
Fragen wir ein paar weitere Dokumente ab und reduzieren dabei die Größe der Ergebnisse.
POST https://$PUBLIC_ENDPOINT/v1/vector/query HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"filter": "id in (1, 2, 4, 99)",
"outputFields": ["id", "publication"]
}
Dieses Ergebnis ist viel leichter zu lesen:
HTTP/1.1 200 OK
{
"code": 200,
"data": [
{
"id": 1,
"publication": null
},
{
"id": 2,
"publication": "The Startup"
},
{
"id": 4,
"publication": "The Startup"
},
{
"id": 99,
"publication": "Towards Data Science"
}
]
}
Eine Vektorsuche findet Daten mithilfe einer Ähnlichkeitssuche in Vektorfeldern.
Senden wir eine Suche mit denselben Werten, die Sie zum Einfügen des neuen Werts verwendet haben.
Die Suche unterstützt dieselben Felder filter und outputFields wie eine Abfrage, zusammen mit einem vector-Feld für die Suchkriterien, einem limit für Suchergebnisse und einem offset. Lassen Sie den Offset weg; Sie erhalten mindestens einen Treffer.
POST https://$PUBLIC_ENDPOINT/v1/vector/search HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"filter": "id in (1,2,3,4,5,6,7,8,9,99)",
"limit": 5,
"outputFields": ["id", "publication"],
"vector": [
0.2109777665089908,
0.0375565730811388,
0.6424190129752343,
0.9818514815450557,
0.10598735548499805,
...
]
}
}
Da wir die Suche auf fünf Werte begrenzt haben, ist hier das Ergebnis. Ihres wird je nach den Werten abweichen, die Sie zum Hinzufügen des neuen Eintrags verwendet haben.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
{
"distance": 0,
"id": 1,
"publication": null
},
{
"distance": 211.61267,
"id": 2,
"publication": "The Startup"
},
{
"distance": 211.71194,
"id": 5,
"publication": "The Startup"
},
{
"distance": 211.719,
"id": 6,
"publication": "The Startup"
},
{
"distance": 211.9408,
"id": 7,
"publication": "The Startup"
}
]
}
Schließlich können Sie Vektoren abrufen, indem Sie eine Liste von ids an /get posten. Diese get-Anfrage liefert dieselben Ergebnisse wie die obige Abfrage.
POST https://$PUBLIC_ENDPOINT/v1/vector/get HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1, 2, 4, 99],
"outputFields": ["id", "publication"]
}
Daten löschen
Unsere letzte Operation ist das Löschen von Vektoren. Wie get verwendet delete das Feld id. Posten Sie eine Liste von ids an /delete, um deren Einträge aus der Datenbank zu entfernen.
POST https://$PUBLIC_ENDPOINT/v1/vector/delete HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1]
}
Das Ergebnis ist ein leeres Dokument.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Versuchen Sie, die id abzurufen, um zu überprüfen, dass sie verschwunden ist:
POST https://$PUBLIC_ENDPOINT/v1/vector/get HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1],
"outputFields": ["id", "publication"]
}
Milvus gibt eine leere Ergebnismenge zurück.
Fazit
In diesem Beitrag haben wir behandelt, wie man mit Zilliz Cloud einen Milvus-Cluster erstellt und ihn anschließend über die Zilliz REST API abfragt. Wir haben gesehen, wie man eine Collection erstellt, auflistet und entfernt und anschließend, wie man Daten mit der Zilliz Cloud und den REST-Endpunkten, die sie für deinen Milvus-Cluster erstellt, manipuliert.
Nachdem du nun gesehen hast, wie einfach es mit Zilliz Cloud ist, Milvus bereitzustellen und zu nutzen, registriere dich für dein kostenloses Konto und leg noch heute los!
Weiterlesen
Zilliz Cloud Just Landed in Claude Code
The Zilliz Cloud Plugin brings the full power of Zilliz Cloud directly into your Claude Code terminal as natural-language conversations.
Will Amazon S3 Vectors Kill Vector Databases—or Save Them?
AWS S3 Vectors aims for 90% cost savings for vector storage. But will it kill vectordbs like Milvus? A deep dive into costs, limits, and the future of tiered storage.
Milvus/Zilliz + Surveillance: How Vector Databases Transform Multi-Camera Tracking
See how Milvus vector database enhances multi-camera tracking with similarity-based matching for better surveillance in retail, warehouses and transport hubs.