Introdução à API REST da Zilliz
Zilliz Cloud é um serviço abrangente de banco de dados vetorial que possibilita e acelera aplicações de inteligência artificial (IA) e analytics em escala. Ele é construído sobre o Milvus, o banco de dados vetorial open-source robusto e escalável que pode lidar facilmente com bilhões de embeddings vetoriais.
O Milvus simplifica o manuseio de dados não estruturados, permitindo que as empresas analisem e obtenham insights de enormes quantidades de dados com eficiência. Ao fornecer a você um banco de dados vetorial escalável e pronto para a nuvem, o Zilliz Cloud serve como uma solução completa.
Os casos de uso para o Milvus e o Zilliz Cloud são amplos e variados. Eles podem impulsionar sistemas de recomendação para oferecer experiências de compra personalizadas ao analisar os padrões de navegação e compra de um cliente. Na área da saúde, eles podem ajudar na criação de modelos de IA que reconhecem padrões em grandes conjuntos de dados médicos, levando a diagnósticos mais precisos e planos de tratamento personalizados.
Um recurso que o Zilliz Cloud adiciona ao Milvus é uma API REST para gerenciar seus bancos de dados vetoriais, com métodos simples para manipular coleções, fazer upload e excluir dados, e enviar consultas. Este post mostrará como usar essas APIs. Vamos começar!
Antes de começarmos
Você precisará de algumas coisas para seguir este tutorial:
Primeiro, você precisará de uma conta do Zilliz Cloud. Se você já tiver uma, pode avançar para recuperar a URL e a chave de API do seu cluster.
Tudo o que é abordado neste post funciona com uma conta gratuita, então você só precisa ir aqui e clicar em Get Started Free. Em seguida, faça login no seu painel do Zilliz e siga as instruções para criar um cluster.
Criar novo cluster
Dê um nome a ele. As opções padrão são suficientes para este tutorial. Clique em Next: Create Collection.
Criar coleção para seu novo cluster
Selecione Example Collection e depois Create Collection and Cluster.
Conectar ao seu cluster
Esta caixa de diálogo tem a URL e a chave de API do seu cluster. Copie-as para uso posterior. Você também pode recuperá-las no seu painel selecionando o cluster.
Os exemplos neste tutorial conterão código do Visual Studio Code e do plugin vscode-restclient.
Você pode encontrar as consultas aqui, em um gist. Você pode acompanhar com qualquer cliente HTTP ou usar o Playground no seu painel do Zilliz.
Visão geral da API REST do Zilliz
A API REST do Zilliz tem métodos para gerenciar clusters, coleções e dados vetoriais. Vamos nos concentrar nas duas últimas categorias: criar coleções para armazenar dados e gerenciar os dados dentro da coleção.
As operações de coleção incluem:
List
Create
Describe
Drop
As operações vetoriais incluem:
Query
Get
Insert
Delete
Search
Componentes de chamada da API
A primeira parte de todos os seus endpoints de API é o endpoint público do seu cluster, que você copiou acima, seguido pela versão da API e /vector/, que é o diretório de nível superior para os métodos da API.
Por exemplo, a URL do meu cluster começou com isto:
https://in03-75204f04fc4368d.api.gcp-us-west1.zillizcloud.com/v1/vector
As chamadas de exemplo usarão $PUBLIC_ENDPOINT como um placeholder para o hostname do seu cluster.
Cada chamada de API requer dois cabeçalhos:
content_type - isto é sempre application/json. Isso informa ao servidor web que quaisquer dados que você enviar estão em JSON.
Authorization - todas as solicitações exigem este cabeçalho com sua chave de API.
As chamadas de exemplo usarão $YOUR_API_KEY como um placeholder para o hostname do seu cluster.
Vamos começar com coleções.
Introdução à API da Zilliz
Criar, descrever, remover e listar coleções
Primeiro, vamos listar as coleções no seu cluster.
O endpoint para operações de coleção é /collections. Uma chamada GET para ele retorna uma lista.
Aqui está a chamada no VS Code Rest Client:
GET https://$PUBLIC_ENDPOINT/v1/vector/collections HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
E aqui está a resposta, com todos os cabeçalhos. Vou omiti-los daqui em diante.
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"
]
}
O servidor retorna um código de sucesso 200 e um campo data com um vetor de nomes de coleções.
Vamos adicionar uma nova coleção e, em seguida, recuperar a nova lista.
Para isso, faça POST de um documento que descreve a coleção para /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"
}
Você pode especificar cinco campos para descrever sua coleção:
collectionName - o nome é obrigatório.
dimension - o número de dimensões para o campo vetorial também é obrigatório.
metricType - o tipo de métricas de similaridade usadas para medir a similaridade entre vetores. Neste exemplo, o tipo de métrica padrão é L2, representando a distância Euclidiana.
primaryField - o campo primário padrão é id.
vectorField - o campo vetorial padrão é vector.
Em caso de sucesso, a Zilliz responde com 200 e um documento vazio.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Liste suas coleções novamente, e você verá dois nomes.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
"medium_articles",
"large_articles"
]
}
Você pode recuperar uma descrição de uma coleção existente. Para isso, envie um GET com collectionName como um parâmetro de solicitação.
GET https://$PUBLIC_ENDPOINT/v1/vector/collections/describe?collectionName=medium_articles HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Esta resposta é uma descrição detalhada do estado atual da sua coleção.
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"
}
]
}
}
Por fim, vamos concluir excluindo a coleção que você acabou de criar. Esta é uma solicitação POST para /collections/drop, então, em vez de passar o nome como um parâmetro, use um 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"
}
A resposta é semelhante ao que a Zilliz envia ao criar uma coleção.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Solicite outra lista de coleções, e você verá que voltou a ter uma. Agora, vamos trabalhar com alguns dados.
Inserir dados
Para inserir dados, envie um POST para /insert com um documento descrevendo os dados.
Observando a descrição que você recuperou acima, a coleção de exemplo tem dois campos:
id - um valor inteiro
title_vector - um vetor com 768 floats
Então, você precisa de um documento com um valor que contenha esses dois campos no campo data da solicitação de inserção. Data é uma lista para que você possa inserir mais de um valor.
Aqui está uma solicitação com um 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
],
},
]
}
Envie este código. Sua resposta é o número de itens inseridos e seus ids.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"insertCount": 1,
"insertIds": [
"1"
]
}
}
Consultar, pesquisar e obter dados
A API REST da Zilliz tem três métodos para recuperar dados: consultar, pesquisar e obter.
Uma consulta vetorial usa critérios para corresponder entradas no banco de dados. Vamos começar com uma consulta baseada no campo id.
Para esta consulta, você envia via POST um documento de pesquisa para /query. Ele usa o operador in para corresponder entradas com ids 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)"
}
O Milvus responde com o valor que você acabou de inserir, junto com dados da coleção de exemplo.
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)...
]
}
}
Você pode usar outputFields para filtrar os resultados.
Vamos consultar mais alguns documentos enquanto reduzimos o tamanho dos 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 é muito mais fácil de ler:
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"
}
]
}
Uma busca vetorial encontra dados usando uma busca por similaridade em campos vetoriais.
Vamos enviar uma busca usando os mesmos valores que você usou para inserir o novo valor.
A busca oferece suporte aos mesmos campos filter e outputFields de uma consulta, juntamente com um campo vector para os critérios de busca, um limit para os resultados da busca e um offset. Omita o offset; você obterá pelo menos uma correspondência.
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 a busca a cinco valores, aqui está o resultado. O seu será diferente com base nos valores que você usou para adicionar a nova 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"
}
]
}
Por fim, você pode obter vetores publicando uma lista de ids em /get. Esta solicitação get produz os mesmos resultados que a consulta acima.
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"]
}
Excluir dados
Nossa última operação é excluir vetores. Assim como get, delete usa o campo id. Publique uma lista de ids em /delete para remover suas entradas do banco de dados.
POST https://$PUBLIC_ENDPOINT/v1/vector/delete HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1]
}
O resultado é um documento vazio.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Tente recuperar o id para verificar se ele desapareceu:
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 retornará um conjunto de resultados vazio.
Conclusão
Nesta publicação, abordamos a criação de um cluster Milvus usando o Zilliz Cloud e, em seguida, a consulta a ele usando a API REST da Zilliz. Vimos como criar, listar e remover uma coleção e depois como manipular dados com a nuvem Zilliz e os endpoints REST que ela cria para o seu cluster Milvus.
Agora que você viu como é fácil implantar e usar o Milvus com o Zilliz Cloud, cadastre-se para obter sua conta gratuita e comece hoje mesmo!
Continue lendo
From Vector Database to Vector Lakebase
Zilliz offers a fully managed Vector Lakebase powered by Milvus, unifying real-time vector search, lake-scale discovery, and Al data operations.
Demystifying the Milvus Sizing Tool
Explore how to use the Sizing Tool to select the optimal configuration for your Milvus deployment.
Milvus WebUI: A Visual Management Tool for Your Vector Database
Explore Milvus WebUI to monitor, manage, and optimize your vector database with real-time insights, performance tracking, and system health monitoring.