Introduzione all'API REST di Zilliz
Zilliz Cloud è un servizio completo di database vettoriale che abilita e accelera applicazioni di intelligenza artificiale (AI) e di analisi su larga scala. È basato su Milvus, il robusto e scalabile database vettoriale open-source che può gestire facilmente miliardi di embedding vettoriali.
Milvus semplifica la gestione dei dati non strutturati, consentendo alle aziende di analizzare e ricavare insight da enormi quantità di dati in modo efficiente. Fornendoti un database vettoriale scalabile e pronto per il cloud, Zilliz Cloud funge da soluzione completa.
I casi d'uso di Milvus e Zilliz Cloud sono ampi e variegati. Possono alimentare sistemi di raccomandazione per offrire esperienze di acquisto personalizzate analizzando i modelli di navigazione e acquisto di un cliente. Nel settore sanitario, possono aiutare a costruire modelli di AI che riconoscono pattern in grandi dataset medici, portando a diagnosi più accurate e a piani di trattamento personalizzati.
Una funzionalità che Zilliz Cloud aggiunge a Milvus è una REST API per gestire i tuoi database vettoriali, con metodi semplici per manipolare le collection, caricare ed eliminare dati e inviare query. Questo post ti mostrerà come usare queste API. Iniziamo!
Prima di iniziare
Avrai bisogno di alcune cose per seguire questo tutorial:
Per prima cosa, avrai bisogno di un account Zilliz Cloud. Se ne hai già uno, puoi passare direttamente al recupero dell'URL e della chiave API del tuo cluster.
Tutto ciò che viene trattato in questo post funziona con un account gratuito, quindi devi solo andare qui e fare clic su Get Started Free. Poi, accedi alla tua dashboard Zilliz e segui le istruzioni per creare un cluster.
Create new cluster
Assegnagli un nome. Le opzioni predefinite sono sufficienti per questo tutorial. Fai clic su Next: Create Collection.
Create collection for your new cluster
Seleziona Example Collection e poi Create Collection and Cluster.
Connect to your cluster
Questa finestra di dialogo contiene l'URL del tuo cluster e la chiave API. Copiali per usarli in seguito. Puoi anche recuperarli dalla tua dashboard selezionando il cluster.
Gli esempi in questo tutorial conterranno codice da Visual Studio Code e dal plugin vscode-restclient.
Puoi trovare le query qui, in un gist. Puoi seguire con qualsiasi client HTTP o usare il Playground nella tua dashboard Zilliz.
Panoramica della REST API di Zilliz
La REST API di Zilliz dispone di metodi per gestire cluster, collection e dati vettoriali. Ci concentreremo sulle ultime due categorie: creare collection per archiviare dati e gestire i dati all'interno della collection.
Le operazioni sulle collection includono:
List
Create
Describe
Drop
Le operazioni sui vettori includono:
Query
Get
Insert
Delete
Search
Componenti di una chiamata API
La prima parte di tutti i tuoi endpoint API è l'endpoint pubblico del tuo cluster, che hai copiato sopra, seguito dalla versione dell'API e da /vector/, che è la directory di primo livello per i metodi API.
Ad esempio, l'URL del mio cluster iniziava con questo:
https://in03-75204f04fc4368d.api.gcp-us-west1.zillizcloud.com/v1/vector
Le chiamate di esempio useranno $PUBLIC_ENDPOINT come placeholder per l'hostname del tuo cluster.
Ogni chiamata API richiede due header:
content_type - questo è sempre application/json. Indica al server web che tutti i dati che invii sono JSON.
Authorization - tutte le richieste richiedono questo header con la tua chiave API.
Le chiamate di esempio useranno $YOUR_API_KEY come segnaposto per l'hostname del tuo cluster.
Iniziamo con le collection.
Guida introduttiva all'API Zilliz
Creare, descrivere, eliminare ed elencare le collection
Per prima cosa, elenchiamo le collection sul tuo cluster.
L'endpoint per le operazioni sulle collection è /collections. Una chiamata GET a esso restituisce un elenco.
Ecco la chiamata nel VS Code Rest Client:
GET https://$PUBLIC_ENDPOINT/v1/vector/collections HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Ed ecco la risposta, con tutti gli header. Da qui in avanti li ometterò.
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"
]
}
Il server restituisce un codice di successo 200 e un campo data con un vettore di nomi di collection.
Aggiungiamo una nuova collection, quindi recuperiamo il nuovo elenco.
Per farlo, invia con POST un documento che descrive la collection a /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"
}
Puoi specificare cinque campi per descrivere la tua collection:
collectionName - il nome è obbligatorio.
dimension - anche il numero di dimensioni per il campo vettoriale è obbligatorio.
metricType - il tipo di metriche di similarità usate per misurare la similarità tra vettori. In questo esempio, il tipo di metrica predefinito è L2, che rappresenta la distanza euclidea.
primaryField - il campo primario predefinito è id.
vectorField - il campo vettoriale predefinito è vector.
In caso di successo, Zilliz risponde con 200 e un documento vuoto.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Elenca di nuovo le tue collection e vedrai due nomi.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
"medium_articles",
"large_articles"
]
}
Puoi recuperare una descrizione di una collection esistente. Per farlo, invia una GET con collectionName come parametro della richiesta.
GET https://$PUBLIC_ENDPOINT/v1/vector/collections/describe?collectionName=medium_articles HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Questa risposta è una descrizione dettagliata dello stato attuale della tua 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"
}
]
}
}
Infine, concludiamo eliminando la collection che hai appena creato. Questa è una richiesta POST a /collections/drop, quindi invece di passare il nome come parametro, usa un documento 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 risposta è simile a quella che Zilliz invia per la creazione di una collection.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Richiedi un altro elenco di collection e vedrai che sei tornato a una. Ora, lavoriamo con alcuni dati.
Inserire dati
Per inserire dati, invia un POST a /insert con un documento che descrive i dati.
Guardando la descrizione che hai recuperato sopra, la collection di esempio ha due campi:
id - un valore intero
title_vector - un vettore con 768 float
Quindi, hai bisogno di un documento con un valore che contenga questi due campi nel campo data della richiesta di inserimento. Data è una lista così puoi inserire più di un valore.
Ecco una richiesta con un valore:
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
],
},
]
}
Invia questo codice. La tua risposta è il numero di elementi inseriti e i loro id.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"insertCount": 1,
"insertIds": [
"1"
]
}
}
Eseguire query, cercare e ottenere dati
Zilliz REST API ha tre metodi per recuperare dati: eseguire query, cercare e ottenere.
Una query vettoriale utilizza criteri per trovare corrispondenze con le voci nel database. Iniziamo con una query basata sul campo id.
Per questa query, invii con POST un documento di ricerca a /query. Usa l'operatore in per trovare corrispondenze con le voci con id 1 o 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 risponde con il valore che hai appena inserito, insieme ai dati della collection di esempio.
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)...
]
}
}
Puoi usare outputFields per filtrare i risultati.
Interroghiamo qualche altro documento riducendo al contempo le dimensioni dei risultati.
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"]
}
Questo risultato è molto più facile da leggere:
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"
}
]
}
Una ricerca vettoriale trova i dati usando una ricerca di similarità sui campi vettoriali.
Inviamo una ricerca usando gli stessi valori che hai utilizzato per inserire il nuovo valore.
La ricerca supporta gli stessi campi filter e outputFields di una query, insieme a un campo vector per i criteri di ricerca, un limit per i risultati della ricerca e un offset. Ometti l’offset; otterrai almeno una corrispondenza.
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,
...
]
}
}
Poiché abbiamo limitato la ricerca a cinque valori, ecco il risultato. Il tuo sarà diverso in base ai valori che hai usato per aggiungere la nuova voce.
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"
}
]
}
Infine, puoi ottenere i vettori inviando una lista di ids a /get. Questa richiesta get restituisce gli stessi risultati della query sopra.
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"]
}
Eliminare i dati
La nostra ultima operazione è eliminare i vettori. Come get, delete usa il campo id. Invia una lista di ids a /delete per rimuovere le relative voci dal database.
POST https://$PUBLIC_ENDPOINT/v1/vector/delete HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1]
}
Il risultato è un documento vuoto.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Prova a recuperare l’id per verificare che sia stato eliminato:
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 restituirà un set di risultati vuoto.
Conclusione
In questo post abbiamo illustrato come creare un cluster Milvus utilizzando Zilliz Cloud e poi interrogarlo tramite l'API REST di Zilliz. Abbiamo visto come creare, elencare e rimuovere una collection e poi come manipolare i dati con Zilliz Cloud e gli endpoint REST che crea per il tuo cluster Milvus.
Ora che hai visto quanto sia facile distribuire e usare Milvus con Zilliz Cloud, registrati per il tuo account gratuito e inizia oggi stesso!
Continua a leggere
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.
Similarity Metrics for Vector Search
Exploring five similarity metrics for vector search: L2 or Euclidean distance, cosine distance, inner product, and hamming distance.
DeepSeek-VL2: Mixture-of-Experts Vision-Language Models for Advanced Multimodal Understanding
Explore DeepSeek-VL2, the open-source MoE vision-language model. Discover its architecture, efficient training pipeline, and top-tier performance.