Primeros pasos con la API REST de Zilliz
Zilliz Cloud es un servicio integral de base de datos vectorial que habilita y acelera aplicaciones de inteligencia artificial (IA) y analítica a escala. Está construido sobre Milvus, la robusta y escalable base de datos vectorial de código abierto que puede manejar fácilmente miles de millones de incrustaciones vectoriales.
Milvus simplifica el manejo de datos no estructurados, lo que permite a las empresas analizar y obtener información a partir de enormes cantidades de datos de manera eficiente. Al proporcionarte una base de datos vectorial escalable y lista para la nube, Zilliz Cloud funciona como una solución integral.
Los casos de uso de Milvus y Zilliz Cloud son amplios y variados. Pueden impulsar sistemas de recomendación para ofrecer experiencias de compra personalizadas mediante el análisis de los patrones de navegación y compra de un cliente. En el sector sanitario, pueden ayudar a construir modelos de IA que reconozcan patrones en grandes conjuntos de datos médicos, lo que conduce a diagnósticos más precisos y planes de tratamiento personalizados.
Una característica que Zilliz Cloud añade a Milvus es una API REST para gestionar tus bases de datos vectoriales, con métodos sencillos para manipular colecciones, cargar y eliminar datos, y enviar consultas. Esta publicación te mostrará cómo usar estas API. ¡Comencemos!
Antes de comenzar
Necesitarás algunas cosas para seguir este tutorial:
Primero, necesitarás una cuenta de Zilliz Cloud. Si ya tienes una, puedes pasar directamente a recuperar la URL y la clave API de tu clúster.
Todo lo que se cubre en esta publicación funciona con una cuenta gratuita, así que solo necesitas ir aquí y hacer clic en Get Started Free. Luego, inicia sesión en tu panel de Zilliz y sigue las indicaciones para crear un clúster.
Crear nuevo clúster
Dale un nombre. Las opciones predeterminadas son suficientes para este tutorial. Haz clic en Next: Create Collection.
Crear una colección para tu nuevo clúster
Selecciona Example Collection y luego Create Collection and Cluster.
Conectarse a tu clúster
Este cuadro de diálogo tiene la URL y la clave API de tu clúster. Cópialas para usarlas más tarde. También puedes recuperarlas desde tu panel seleccionando el clúster.
Los ejemplos de este tutorial contendrán código de Visual Studio Code y el plugin vscode-restclient.
Puedes encontrar las consultas aquí, en un gist. Puedes seguirlo con cualquier cliente HTTP o usar el Playground en tu panel de Zilliz.
Descripción general de la API REST de Zilliz
La API REST de Zilliz tiene métodos para gestionar clústeres, colecciones y datos vectoriales. Nos centraremos en las dos últimas categorías: crear colecciones para almacenar datos y gestionar los datos dentro de la colección.
Las operaciones de colección incluyen:
List
Create
Describe
Drop
Las operaciones vectoriales incluyen:
Query
Get
Insert
Delete
Search
Componentes de una llamada a la API
La primera parte de todos tus endpoints de API es el endpoint público de tu clúster, que copiaste anteriormente, seguido de la versión de la API y /vector/, que es el directorio de nivel superior para los métodos de la API.
Por ejemplo, la URL de mi clúster comenzaba con esto:
https://in03-75204f04fc4368d.api.gcp-us-west1.zillizcloud.com/v1/vector
Las llamadas de ejemplo usarán $PUBLIC_ENDPOINT como marcador de posición para el nombre de host de tu clúster.
Cada llamada a la API requiere dos encabezados:
content_type - esto siempre es application/json. Esto le indica al servidor web que cualquier dato que envíes es JSON.
Authorization - todas las solicitudes requieren este encabezado con tu clave de API.
Las llamadas de ejemplo usarán $YOUR_API_KEY como marcador de posición para el nombre de host de tu clúster.
Comencemos con las colecciones.
Primeros pasos con la API de Zilliz
Crear, describir, eliminar y listar colecciones
Primero, vamos a listar las colecciones en tu clúster.
El endpoint para las operaciones de colección es /collections. Una llamada GET a este devuelve una lista.
Aquí está la llamada en el VS Code Rest Client:
GET https://$PUBLIC_ENDPOINT/v1/vector/collections HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Y aquí está la respuesta, con todos los encabezados. Los omitiré de ahora en adelante.
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"
]
}
El servidor devuelve un código de éxito 200 y un campo data con un vector de nombres de colecciones.
Vamos a agregar una nueva colección, luego recuperaremos la nueva lista.
Para esto, haz POST de un documento que describa la colección 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"
}
Puedes especificar cinco campos para describir tu colección:
collectionName - el nombre es obligatorio.
dimension - el número de dimensiones para el campo vectorial también es obligatorio.
metricType - el tipo de métricas de similitud utilizadas para medir la similitud entre vectores. En este ejemplo, el tipo de métrica predeterminado es L2, que representa la distancia euclidiana.
primaryField - el campo principal predeterminado es id.
vectorField - el campo vectorial predeterminado es vector.
Si tiene éxito, Zilliz responde con 200 y un documento vacío.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Lista tus colecciones de nuevo y verás dos nombres.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
"medium_articles",
"large_articles"
]
}
Puedes recuperar una descripción de una colección existente. Para esto, envía un GET con collectionName como parámetro de solicitud.
GET https://$PUBLIC_ENDPOINT/v1/vector/collections/describe?collectionName=medium_articles HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Esta respuesta es una descripción detallada del estado actual de tu colección.
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"
}
]
}
}
Finalmente, terminemos eliminando la colección que acabas de crear. Esta es una solicitud POST a /collections/drop, así que, en lugar de pasar el nombre como parámetro, 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 respuesta es similar a la que Zilliz envía al crear una colección.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Solicita otra lista de colecciones y verás que vuelves a tener una. Ahora, trabajemos con algunos datos.
Insertar datos
Para insertar datos, envía un POST a /insert con un documento que describa los datos.
Al observar la descripción que recuperaste arriba, la colección de ejemplo tiene dos campos:
id - un valor entero
title_vector - un vector con 768 flotantes
Por lo tanto, necesitas un documento con un valor que contenga estos dos campos en el campo data de la solicitud de inserción. Data es una lista para que puedas insertar más de un valor.
Aquí tienes una solicitud con un valor:
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
],
},
]
}
Envía este código. Tu respuesta es el número de elementos insertados y sus ids.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"insertCount": 1,
"insertIds": [
"1"
]
}
}
Consultar, buscar y obtener datos
La API REST de Zilliz tiene tres métodos para recuperar datos: consultar, buscar y obtener.
Una consulta vectorial usa criterios para hacer coincidir entradas en la base de datos. Comencemos con una consulta basada en el campo id.
Para esta consulta, haces un POST de un documento de búsqueda a /query. Usa el operador in para hacer coincidir entradas con ids de 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 responde con el valor que acabas de insertar, junto con datos de la colección de ejemplo.
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)...
]
}
}
Puedes usar outputFields para filtrar los resultados.
Consultemos algunos documentos más mientras reducimos el tamaño de los resultados.
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"]
}
Este resultado es mucho más fácil de leer:
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 búsqueda vectorial encuentra datos usando una búsqueda por similitud en campos vectoriales.
Enviemos una búsqueda usando los mismos valores que usaste para insertar el nuevo valor.
La búsqueda admite los mismos campos filter y outputFields que una consulta, junto con un campo vector para los criterios de búsqueda, un limit para los resultados de búsqueda y un offset. Omite el offset; obtendrás al menos una coincidencia.
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,
...
]
}
}
Como limitamos la búsqueda a cinco valores, este es el resultado. El tuyo diferirá según los valores que usaste para añadir la nueva entrada.
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"
}
]
}
Finalmente, puedes obtener vectores enviando una lista de ids a /get. Esta solicitud get produce los mismos resultados que la consulta anterior.
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"]
}
Eliminar datos
Nuestra última operación es eliminar vectores. Al igual que get, delete usa el campo id. Envía una lista de ids a /delete para eliminar sus entradas de la base de datos.
POST https://$PUBLIC_ENDPOINT/v1/vector/delete HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1]
}
El resultado es un documento vacío.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Intenta recuperar el id para verificar que ya no está:
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 devolverá un conjunto de resultados vacío.
Conclusión
En esta publicación, cubrimos la creación de un clúster de Milvus usando Zilliz Cloud y luego su consulta mediante la API REST de Zilliz. Vimos cómo crear, listar y eliminar una colección y luego cómo manipular datos con Zilliz Cloud y los endpoints REST que crea para tu clúster de Milvus.
Ahora que has visto lo fácil que es implementar y usar Milvus con Zilliz Cloud, regístrate para obtener tu cuenta gratuita y comienza hoy mismo!
Sigue leyendo
Zilliz Cloud Now Available in AWS Europe (Ireland)
Zilliz Cloud launches in AWS eu-west-1 (Ireland) — bringing low-latency vector search, EU data residency, and full GDPR-ready infrastructure to European AI teams. Now live across 30 regions on five cloud providers.
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.
Cosmos World Foundation Model Platform for Physical AI
NVIDIA's Cosmos platform enables safe, digital twin training of GenAI models for physical applications, overcoming data scarcity and safety challenges.