Premiers pas avec l’API REST Zilliz
Zilliz Cloud est un service complet de base de données vectorielle qui permet et accélère les applications d’intelligence artificielle (IA) et d’analytique à grande échelle. Il est construit sur Milvus, la base de données vectorielle open source robuste et évolutive qui peut facilement gérer des milliards d’embeddings vectoriels.
Milvus simplifie la gestion des données non structurées, permettant aux entreprises d’analyser et d’extraire efficacement des informations à partir d’énormes quantités de données. En vous fournissant une base de données vectorielle évolutive et prête pour le cloud, Zilliz Cloud sert de solution tout-en-un.
Les cas d’utilisation de Milvus et de Zilliz Cloud sont nombreux et variés. Ils peuvent alimenter des systèmes de recommandation afin d’offrir des expériences d’achat personnalisées en analysant les habitudes de navigation et d’achat d’un client. Dans le domaine de la santé, ils peuvent aider à créer des modèles d’IA qui reconnaissent des motifs dans de grands ensembles de données médicales, menant à des diagnostics plus précis et à des plans de traitement personnalisés.
Une fonctionnalité que Zilliz Cloud ajoute à Milvus est une API REST pour gérer vos bases de données vectorielles, avec des méthodes simples pour manipuler les collections, importer et supprimer des données, et soumettre des requêtes. Cet article vous montrera comment utiliser ces API. Commençons !
Avant de commencer
Vous aurez besoin de quelques éléments pour suivre ce tutoriel :
Tout d’abord, vous aurez besoin d’un compte Zilliz Cloud. Si vous en avez déjà un, vous pouvez passer directement à la récupération de l’URL et de la clé API de votre cluster.
Tout ce qui est couvert dans cet article fonctionne avec un compte gratuit, vous devez donc simplement aller ici et cliquer sur Get Started Free. Ensuite, connectez-vous à votre tableau de bord Zilliz et suivez les instructions pour créer un cluster.
Créer un nouveau cluster
Donnez-lui un nom. Les options par défaut sont suffisantes pour ce tutoriel. Cliquez sur Next: Create Collection.
Créer une collection pour votre nouveau cluster
Sélectionnez Example Collection, puis Create Collection and Cluster.
Se connecter à votre cluster
Cette boîte de dialogue contient l’URL et la clé API de votre cluster. Copiez-les pour une utilisation ultérieure. Vous pouvez également les récupérer depuis votre tableau de bord en sélectionnant le cluster.
Les exemples de ce tutoriel contiendront du code provenant de Visual Studio Code et du plugin vscode-restclient.
Vous pouvez trouver les requêtes ici, dans un gist. Vous pouvez suivre avec n’importe quel client HTTP ou utiliser le Playground dans votre tableau de bord Zilliz.
Présentation de l’API REST Zilliz
L’API REST Zilliz dispose de méthodes pour gérer les clusters, les collections et les données vectorielles. Nous nous concentrerons sur les deux dernières catégories : créer des collections pour stocker des données et gérer les données à l’intérieur de la collection.
Les opérations de collection incluent :
Lister
Créer
Décrire
Supprimer
Les opérations vectorielles incluent :
Interroger
Obtenir
Insérer
Supprimer
Rechercher
Composants d’un appel API
La première partie de tous vos points de terminaison API est le point de terminaison public de votre cluster, que vous avez copié ci-dessus, suivi de la version de l’API et de /vector/, qui est le répertoire de premier niveau pour les méthodes de l’API.
Par exemple, l’URL de mon cluster commençait par ceci :
https://in03-75204f04fc4368d.api.gcp-us-west1.zillizcloud.com/v1/vector
Les appels d’exemple utiliseront $PUBLIC_ENDPOINT comme espace réservé pour le nom d’hôte de votre cluster.
Chaque appel API nécessite deux en-têtes :
content_type - c’est toujours application/json. Cela indique au serveur web que toutes les données que vous envoyez sont du JSON.
Authorization - toutes les requêtes nécessitent cet en-tête avec votre clé API.
Les appels d’exemple utiliseront $YOUR_API_KEY comme placeholder pour le nom d’hôte de votre cluster.
Commençons par les collections.
Premiers pas avec l’API Zilliz
Créer, décrire, supprimer et lister des collections
Tout d’abord, listons les collections sur votre cluster.
Le point de terminaison pour les opérations sur les collections est /collections. Un appel GET vers celui-ci renvoie une liste.
Voici l’appel dans le VS Code Rest Client :
GET https://$PUBLIC_ENDPOINT/v1/vector/collections HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Et voici la réponse, avec tous les en-têtes. Je les omettrai à l’avenir.
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"
]
}
Le serveur renvoie un code de succès 200, ainsi qu’un champ data contenant un vecteur de noms de collections.
Ajoutons une nouvelle collection, puis récupérons la nouvelle liste.
Pour cela, envoyez en POST un document décrivant la collection à /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"
}
Vous pouvez spécifier cinq champs pour décrire votre collection :
collectionName - le nom est obligatoire.
dimension - le nombre de dimensions du champ vectoriel est également obligatoire.
metricType - le type de métriques de similarité utilisées pour mesurer la similarité entre les vecteurs. Dans cet exemple, le type de métrique par défaut est L2, représentant la distance euclidienne.
primaryField - le champ primaire par défaut est id.
vectorField - le champ vectoriel par défaut est vector.
En cas de succès, Zilliz répond avec 200 et un document vide.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Listez à nouveau vos collections, et vous verrez deux noms.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
"medium_articles",
"large_articles"
]
}
Vous pouvez récupérer une description d’une collection existante. Pour cela, envoyez une requête GET avec collectionName comme paramètre de requête.
GET https://$PUBLIC_ENDPOINT/v1/vector/collections/describe?collectionName=medium_articles HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Cette réponse est une description détaillée de l’état actuel de votre 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"
}
]
}
}
Enfin, terminons en supprimant la collection que vous venez de créer. Il s’agit d’une requête POST vers /collections/drop, donc au lieu de transmettre le nom comme paramètre, utilisez un document JSON.
POST https://$PUBLIC_ENDPOINT/v1/vector/collections/drop HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "large_articles"
}
La réponse est similaire à celle envoyée par Zilliz lors de la création d’une collection.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Demandez une autre liste de collections, et vous verrez que vous êtes revenu à une seule. Maintenant, travaillons avec quelques données.
Insérer des données
Pour insérer des données, envoyez une requête POST vers /insert avec un document décrivant les données.
En regardant la description que vous avez récupérée ci-dessus, la collection d’exemple comporte deux champs :
id - une valeur entière
title_vector - un vecteur avec 768 flottants
Vous avez donc besoin d’un document avec une valeur qui contient ces deux champs dans le champ data de la requête d’insertion. Data est une liste afin que vous puissiez insérer plus d’une valeur.
Voici une requête avec une valeur :
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
],
},
]
}
Soumettez ce code. Votre réponse est le nombre d’éléments insérés et leurs identifiants.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"insertCount": 1,
"insertIds": [
"1"
]
}
}
Interroger, rechercher et obtenir des données
L’API REST de Zilliz dispose de trois méthodes pour récupérer des données : interroger, rechercher et obtenir.
Une requête vectorielle utilise des critères pour faire correspondre les entrées dans la base de données. Commençons par une requête basée sur le champ id.
Pour cette requête, vous POST un document de recherche vers /query. Il utilise l’opérateur in pour faire correspondre les entrées dont les identifiants sont 1 ou 2.
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 répond avec la valeur que vous venez d’insérer, ainsi qu’avec des données de la collection d’exemple.
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)...
]
}
}
Vous pouvez utiliser outputFields pour filtrer les résultats.
Interrogeons quelques documents supplémentaires tout en réduisant la taille des résultats.
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"]
}
Ce résultat est beaucoup plus facile à lire :
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"
}
]
}
Une recherche vectorielle trouve des données à l’aide d’une recherche de similarité sur des champs vectoriels.
Soumettons une recherche en utilisant les mêmes valeurs que celles que vous avez utilisées pour insérer la nouvelle valeur.
La recherche prend en charge les mêmes champs filter et outputFields qu’une requête, ainsi qu’un champ vector pour les critères de recherche, un limit pour les résultats de recherche et un offset. Omettez l’offset ; vous obtenez au moins une correspondance.
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,
...
]
}
}
Comme nous avons limité la recherche à cinq valeurs, voici le résultat. Le vôtre différera en fonction des valeurs que vous avez utilisées pour ajouter la nouvelle entrée.
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"
}
]
}
Enfin, vous pouvez obtenir des vecteurs en publiant une liste d’ids vers /get. Cette requête get produit les mêmes résultats que la requête ci-dessus.
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"]
}
Supprimer des données
Notre dernière opération consiste à supprimer des vecteurs. Comme get, delete utilise le champ id. Publiez une liste d’ids vers /delete pour supprimer leurs entrées de la base de données.
POST https://$PUBLIC_ENDPOINT/v1/vector/delete HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1]
}
Le résultat est un document vide.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Essayez de récupérer l’id pour vérifier qu’il a disparu :
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 renverra un ensemble de résultats vide.
Conclusion
Dans cet article, nous avons abordé la création d’un cluster Milvus à l’aide de Zilliz Cloud, puis son interrogation à l’aide de l’API REST de Zilliz. Nous avons vu comment créer, lister et supprimer une collection, puis comment manipuler les données avec Zilliz Cloud et les points de terminaison REST qu’il crée pour votre cluster Milvus.
Maintenant que vous avez vu à quel point Zilliz Cloud facilite le déploiement et l’utilisation de Milvus, créez votre compte gratuit et commencez dès aujourd’hui !
Continuer à lire
How to Improve Retrieval Quality for Japanese Text with Sudachi, Milvus/Zilliz, and AWS Bedrock
Learn how Sudachi normalization and Milvus/Zilliz hybrid search improve Japanese RAG accuracy with BM25 + vector fusion, AWS Bedrock embeddings, and practical code examples.
Introducing Business Critical Plan: Enterprise-Grade Security and Compliance for Mission-Critical AI Applications
Discover Zilliz Cloud’s Business Critical Plan—offering advanced security, compliance, and uptime for mission-critical AI and vector database workloads.
Why Not All VectorDBs Are Agent-Ready
Explore why choosing the right vector database is critical for scaling AI agents, and why traditional solutions fall short in production.