Начало работы с 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, зарегистрируйте бесплатный аккаунт и начните уже сегодня!
Читать далее
Zilliz Cloud Now Available in AWS Asia Pacific (Seoul)
Zilliz Cloud is now available in AWS Seoul — low-latency vector search, in-country data residency, and one-step migration for Korean AI teams. 31 regions across 5 clouds.
Why AI Databases Don't Need SQL
Whether you like it or not, here's the truth: SQL is destined for decline in the era of AI.
DeepSeek vs. OpenAI: A Battle of Innovation in Modern AI
Compare OpenAI's o1 and o3-mini with DeepSeek R1's open-source alternative. Discover which AI model offers the best balance of reasoning capabilities and cost efficiency.