Начало работы с Zilliz REST API
Zilliz Cloud — это комплексный сервис векторной базы данных, который обеспечивает и ускоряет работу приложений искусственного интеллекта (AI) и аналитики в масштабе. Он построен на Milvus — надежной и масштабируемой векторной базе данных с открытым исходным кодом, которая легко справляется с миллиардами векторных эмбеддингов.
Milvus упрощает работу с неструктурированными данными, позволяя компаниям эффективно анализировать огромные объемы данных и получать из них ценные сведения. Предоставляя вам масштабируемую, готовую к облаку векторную базу данных, Zilliz Cloud служит универсальным решением.
Сценарии использования Milvus и Zilliz Cloud широки и разнообразны. Они могут обеспечивать работу рекомендательных систем, предлагая персонализированный покупательский опыт за счет анализа истории просмотров и покупок клиента. В здравоохранении они могут помогать в создании AI-моделей, которые распознают закономерности в больших медицинских наборах данных, что приводит к более точным диагнозам и персонализированным планам лечения.
Одна из функций, которые Zilliz Cloud добавляет к Milvus, — это REST API для управления вашими векторными базами данных, с простыми методами для работы с коллекциями, загрузки и удаления данных, а также отправки запросов. В этой статье мы покажем, как использовать эти API. Начнем!
Прежде чем начать
Для прохождения этого руководства вам понадобится несколько вещей:
Во-первых, вам понадобится учетная запись Zilliz Cloud. Если она у вас уже есть, вы можете сразу перейти к получению URL вашего кластера и API-ключа.
Все, что рассматривается в этой статье, работает с бесплатной учетной записью, поэтому вам нужно только перейти сюда и нажать Get Started Free. Затем войдите в свою панель Zilliz и следуйте подсказкам, чтобы создать кластер.
Создать новый кластер
Дайте ему имя. Параметров по умолчанию достаточно для этого руководства. Нажмите Next: Create Collection.
Создать коллекцию для вашего нового кластера
Выберите Example Collection, а затем Create Collection and Cluster.
Подключиться к вашему кластеру
В этом диалоговом окне находятся URL вашего кластера и API-ключ. Скопируйте их для дальнейшего использования. Вы также можете получить их из своей панели, выбрав кластер.
Примеры в этом руководстве будут содержать код из Visual Studio Code и плагина vscode-restclient.
Запросы можно найти здесь, в gist. Вы можете выполнять шаги вместе с любым HTTP-клиентом или использовать Playground в своей панели Zilliz.
Обзор Zilliz REST API
Zilliz REST API содержит методы для управления кластерами, коллекциями и векторными данными. Мы сосредоточимся на последних двух категориях: создании коллекций для хранения данных и управлении данными внутри коллекции.
Операции с коллекциями включают:
List
Create
Describe
Drop
Операции с векторами включают:
Query
Get
Insert
Delete
Search
Компоненты API-вызова
Первая часть всех ваших конечных точек API — это публичная конечная точка вашего кластера, которую вы скопировали выше, за ней следуют версия API и /vector/, который является каталогом верхнего уровня для методов API.
Например, URL моего кластера начинался с этого:
https://in03-75204f04fc4368d.api.gcp-us-west1.zillizcloud.com/v1/vector
В примерах вызовов будет использоваться $PUBLIC_ENDPOINT как заполнитель для имени хоста вашего кластера.
Для каждого API-вызова требуются два заголовка:
content_type - это всегда application/json. Это сообщает веб-серверу, что любые отправляемые вами данные являются JSON.
Authorization - все запросы требуют этот заголовок с вашим API-ключом.
В примерах вызовов $YOUR_API_KEY будет использоваться как заполнитель для имени хоста вашего кластера.
Начнем с коллекций.
Начало работы с Zilliz API
Создание, описание, удаление и вывод списка коллекций
Сначала давайте выведем список коллекций в вашем кластере.
Эндпоинт для операций с коллекциями — /collections. Вызов GET к нему возвращает список.
Вот вызов в VS Code Rest Client:
GET https://$PUBLIC_ENDPOINT/v1/vector/collections HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
А вот ответ со всеми заголовками. В дальнейшем я буду их опускать.
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"
]
}
Сервер возвращает код успеха 200 и поле data с вектором имен коллекций.
Давайте добавим новую коллекцию, а затем получим новый список.
Для этого выполните POST документа, описывающего коллекцию, в /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"
}
Вы можете указать пять полей для описания вашей коллекции:
collectionName - имя является обязательным.
dimension - количество измерений для векторного поля также является обязательным.
metricType - тип метрик сходства, используемых для измерения сходства между векторами. В этом примере тип метрики по умолчанию — L2, представляющий евклидово расстояние.
primaryField - первичное поле по умолчанию — id.
vectorField - векторное поле по умолчанию — vector.
При успехе Zilliz отвечает 200 и пустым документом.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Снова выведите список ваших коллекций, и вы увидите два имени.
HTTP/1.1 200 OK
{
"code": 200,
"data": [
"medium_articles",
"large_articles"
]
}
Вы можете получить описание существующей коллекции. Для этого отправьте GET с collectionName в качестве параметра запроса.
GET https://$PUBLIC_ENDPOINT/v1/vector/collections/describe?collectionName=medium_articles HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
Этот ответ представляет собой подробное описание текущего состояния вашей коллекции.
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"
}
]
}
}
Наконец, давайте завершим, удалив коллекцию, которую вы только что создали. Это POST-запрос к /collections/drop, поэтому вместо передачи имени в качестве параметра используйте JSON-документ.
POST https://$PUBLIC_ENDPOINT/v1/vector/collections/drop HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "large_articles"
}
Ответ похож на тот, который Zilliz отправляет при создании коллекции.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Запросите еще один список коллекций, и вы увидите, что снова осталась одна. Теперь давайте поработаем с данными.
Вставка данных
Чтобы вставить данные, отправьте POST на /insert с документом, описывающим данные.
Глядя на описание, которое вы получили выше, пример коллекции имеет два поля:
id - целочисленное значение
title_vector - вектор с 768 числами с плавающей точкой
Итак, вам нужен документ со значением, которое содержит эти два поля в поле data запроса вставки. Data — это список, чтобы вы могли вставить более одного значения.
Вот запрос с одним значением:
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
],
},
]
}
Отправьте этот код. В ответе вы получите количество вставленных элементов и их идентификаторы.
HTTP/1.1 200 OK
{
"code": 200,
"data": {
"insertCount": 1,
"insertIds": [
"1"
]
}
}
Запрос, поиск и получение данных
Zilliz REST API имеет три метода для извлечения данных: запрос, поиск и получение.
Векторный запрос использует критерии для сопоставления записей в базе данных. Начнем с запроса на основе поля id.
Для этого запроса вы отправляете POST поисковый документ на /query. Он использует оператор in для сопоставления записей с id 1 или 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 отвечает значением, которое вы только что вставили, вместе с данными из примерной коллекции.
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)...
]
}
}
Вы можете использовать outputFields для фильтрации результатов.
Запросим еще несколько документов, одновременно сократив размер результатов.
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"]
}
Этот результат гораздо легче читать:
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"
}
]
}
Векторный поиск находит данные с помощью поиска по сходству в векторных полях.
Отправим поисковый запрос, используя те же значения, которые вы использовали для вставки нового значения.
Поиск поддерживает те же поля filter и outputFields, что и запрос, а также поле vector для критериев поиска, limit для результатов поиска и offset. Опустите offset; вы получите как минимум одно совпадение.
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,
...
]
}
}
Поскольку мы ограничили поиск пятью значениями, вот результат. Ваш результат будет отличаться в зависимости от значений, которые вы использовали для добавления новой записи.
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"
}
]
}
Наконец, вы можете получать векторы, отправляя список ids в /get. Этот запрос get возвращает те же результаты, что и запрос выше.
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"]
}
Удаление данных
Наша последняя операция — удаление векторов. Как и get, delete использует поле id. Отправьте список ids в /delete, чтобы удалить их записи из базы данных.
POST https://$PUBLIC_ENDPOINT/v1/vector/delete HTTP/1.1
content-type: application/json
Authorization: Bearer $YOUR_API_KEY
{
"collectionName": "medium_articles",
"id": [1]
}
Результатом является пустой документ.
HTTP/1.1 200 OK
{
"code": 200,
"data": {}
}
Попробуйте получить id, чтобы убедиться, что он удален:
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 вернет пустой набор результатов.
Заключение
В этом посте мы рассмотрели создание кластера Milvus с помощью Zilliz Cloud, а затем выполнение запросов к нему с использованием Zilliz REST API. Мы увидели, как создавать, просматривать список и удалять коллекцию, а затем как управлять данными с помощью Zilliz Cloud и REST-эндпоинтов, которые она создает для вашего кластера Milvus.
Теперь, когда вы увидели, насколько легко с Zilliz Cloud развернуть и использовать Milvus, зарегистрируйте бесплатный аккаунт и начните уже сегодня!
Читать далее
Why and How to Migrate from Self-Hosted Milvus to Zilliz Cloud
A simple, step-by-step guide to migrating from Milvus to Zilliz Cloud. Learn both endpoint and backup methods for a smooth, scalable vector database migration.
Announcing the General Availability of Zilliz Cloud BYOC on Google Cloud Platform
Zilliz Cloud BYOC on GCP offers enterprise vector search with full data sovereignty and seamless integration.
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.