Подключение DBAPI к векторной базе данных Milvus: практическое использование сопоставления параметров HTTP‑исполнителя
Что такое Milvus?
Milvus — это открытая векторная база данных, специально разработанная для задач ИИ; она поддерживает хранение, индексацию и поиск похожих векторов в больших объёмах. Широко применяется в таких сценариях, как RAG (Retrieval-Augmented Generation), семантический поиск, системы рекомендаций и других.
Milvus предоставляет полнофункциональный RESTful API, позволяющий через протокол HTTP выполнять операции вставки, запроса и поиска векторных данных.
Почему стоит использовать DBAPI для подключения к Milvus?
Прямое обращение к HTTP‑API Milvus требует сборки URL‑адреса запроса, формирования параметров, а также обработки аутентификации и авторизации. С помощью HTTP‑исполнителя DBAPI вы получаете:
- Единое управление API: все операции с Milvus управляются через API DBAPI; настройки доступа, ограничения трафика и мониторинг работают из коробки.
- Упрощённое сопоставление параметров: пользовательские шаблоны автоматически преобразуют бизнес‑параметры в формат запроса, необходимый для интерфейса Milvus; разработчику не нужно заботиться о деталях API Milvus.
- Безопасность: наследование возможностей аутентификации по токену и IP‑фильтрации, реализованных в DBAPI.
- Отсутствие кода интеграции: всё настраивается конфигурацией, без написания дополнительного кода.
Ключевая функция: пользовательское сопоставление параметров HTTP‑исполнителя
В версии 4.5.0 Enterprise Edition DBAPI расширила возможности HTTP‑исполнителя благодаря пользовательскому режиму сопоставления. С помощью JSON‑шаблона, дополняемого специальными маркерами ${} и выражениями Groovy, можно гибко преобразовывать входящие параметры вызывающей стороны в формат тела запроса, требуемый целевым интерфейсом.
Вызов: { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
│ Сопоставление параметров HTTP‑исполнителем
▼
Milvus получает: { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }Практическое подключение к Milvus
Предварительные условия
- DBAPI Enterprise Edition версии 4.5.0 или выше.
- Установленный сервис Milvus (в данном примере используется Milvus HTTP API v2).
- Созданная коллекция в Milvus.
Шаг 1: Создание источника данных HTTP
В админ‑панели DBAPI перейдите в раздел «Управление источниками данных» и нажмите «Создать источник данных»:
| Параметр | Значение |
|---|---|
| Имя | Milvus Service |
| Тип | HTTP |
| Адрес | http://192.168.1.100:19530 |
Адрес указывает на HTTP‑порт сервиса Milvus; по умолчанию он равен 19530.
Шаг 2: Создание API для вставки векторов
В соответствующей группе создайте новый API, используя HTTP‑исполнитель.
Основные сведения
| Параметр | Значение |
|---|---|
| Имя API | Milvus Insert Vector |
| Путь API | /milvus/insert |
| Доступ | private |
| Параметры | id (bigint), vector (string), text (string) |
Параметр
vectorпередаётся в виде строкового JSON‑массива, например:[0.1, 0.2, 0.3, ...].
Конфигурация исполнителя
| Параметр | Значение |
|---|---|
| Тип исполнителя | HTTP‑интерфейс с прокси‑вызовом |
| Источник данных | Milvus Service |
| Метод | POST |
| Путь URL | /v2/vectordb/entities/insert |
| Content-Type | application/json |
| Режим передачи параметров | Пользовательское сопоставление |
Пользовательские заголовки:
| Ключ | Значение |
|---|---|
Authorization | YOUR_MILVUS_TOKEN |
Если в Milvus включена аутентификация, токен можно добавить в пользовательские заголовки; HTTP‑исполнитель автоматически включит его в пересылку запроса.
Шаблон тела запроса:
{"collectionName": "news_articles", "data": [{"id": ${_parameters.id}, "vector": ${_parameters.vector}, "text": ${_parameters.text}}]}Поле
collectionNameзадаётся прямо в шаблоне; вызывающая сторона не обязана передавать его. Параметрvectorпередаётся как строковый массив JSON, который сопоставляется с полемvectorв Milvus.
Результат вызова
Вызов:
POST https://127.0.0.1:8520/milvus/insert
Content-Type: application/json
{
"id": 1001,
"vector": [0.352, 0.187, 0.921, 0.453, 0.672],
"text": "DBAPI connects to vector database"
}Система, согласно шаблону, преобразует запрос и пересылает его в Milvus (HTTP‑исполнитель автоматически добавляет пользовательские заголовки):
POST http://192.168.1.100:19530/v2/vectordb/entities/insert
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN
{"collectionName": "news_articles", "data": [{"id": 1001, "vector": [0.352, 0.187, 0.921, 0.453, 0.672], "text": "DBAPI connects to vector database"}]}Шаг 3: Создание API для поиска векторов
Основные сведения
| Параметр | Значение |
|---|---|
| Имя API | Milvus Vector Search |
| Путь API | /milvus/search |
| Доступ | private |
| Параметры | vector (string), limit (bigint) |
Конфигурация исполнителя
| Параметр | Значение |
|---|---|
| Тип исполнителя | HTTP‑интерфейс с прокси‑вызовом |
| Источник данных | Milvus Service |
| Метод | POST |
| Путь URL | /v2/vectordb/entities/search |
| Content-Type | application/json |
| Режим передачи параметров | Пользовательское сопоставление |
Шаблон тела запроса:
{"collectionName": "news_articles", "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "outputFields": ["id", "text", "vector"]}Поле
collectionNameзадаётся в шаблоне; вызывающая сторона должна передавать только вектор и количество результатов.
Результат вызова
Вызов:
POST https://127.0.0.1:8520/milvus/search
Content-Type: application/json
{
"vector": [0.350, 0.190, 0.910, 0.450, 0.670],
"limit": 5
}Система, согласно шаблону, преобразует запрос и пересылает его в Milvus:
POST http://192.168.1.100:19530/v2/vectordb/entities/search
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN
{"collectionName": "news_articles", "vector": [0.350, 0.190, 0.910, 0.450, 0.670], "limit": 5, "outputFields": ["id", "text", "vector"]}Шаг 4: Создание API для поиска по ID
Основные сведения
| Параметр | Значение |
|---|---|
| Имя API | Milvus Query Vector |
| Путь API | /milvus/query |
| Доступ | private |
| Параметры | collection (string), id (bigint) |
Конфигурация исполнителя
| Параметр | Значение |
|---|---|
| Тип исполнителя | HTTP‑интерфейс с прокси‑вызовом |
| Источник данных | Milvus Service |
| Метод | POST |
| Путь URL | /v2/vectordb/entities/query |
| Content-Type | application/json |
| Режим передачи параметров | Пользовательское сопоставление |
Шаблон тела запроса:
{"collectionName": ${_parameters.collection}, "filter": "id == " + ${_parameters.id}, "outputFields": ["id", "text", "vector"]}С помощью выражений Groovy формируется условие фильтрации
id == 1001; вызывающая сторона не нуждается в знании синтаксиса запросов Milvus.
Результат вызова
Вызов:
POST https://127.0.0.1:8520/milvus/query
Content-Type: application/json
{
"id": 1001
}Система, согласно шаблону, преобразует запрос и пересылает его в Milvus:
POST http://192.168.1.100:19530/v2/vectordb/entities/query
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN
{"collectionName": "news_articles", "filter": "id == 1001", "outputFields": ["id", "text", "vector"]}Дополнительные приёмы сопоставления параметров
Сложные вложенные структуры
Если в коллекции Milvus есть несколько векторных или вложенных полей, их можно гибко формировать с помощью шаблонов:
{"collectionName": ${_parameters.collection}, "data": [{"id": ${_parameters.id}, "titleVector": ${_parameters.titleVector}, "contentVector": ${_parameters.contentVector}, "metadata": {"author": ${_parameters.author}, "tags": ${_parameters.tags}}}]}Вычисления с параметрами
Можно выполнять предварительную обработку входящих параметров:
{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit + 10}, "offset": ${(_parameters.page - 1) * _parameters.pageSize}}Условные присваивания
Динамическое задание параметров поиска в зависимости от значений:
{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "params": {"nprobe": ${_parameters.precision == "high" ? 64 : 16}}}Заключение
Благодаря функции пользовательского сопоставления параметров HTTP‑исполнителя DBAPI подключение к векторной базе данных Milvus становится чрезвычайно простым:
- Вызывающая сторона передаёт лишь бизнес‑параметры, не зная деталей API Milvus.
- Шаблоны сопоставления централизованно управляются; при изменении интерфейса Milvus достаточно обновить шаблон — вызывающая сторона остаётся незатронутой.
- Интерфейс наследует корпоративные возможности DBAPI: аутентификацию, ограничение трафика, мониторинг и другие функции.
- Интеграция осуществляется полностью без написания кода — всё настраивается конфигурацией.
Требования к версии: функция пользовательского сопоставления параметров HTTP‑исполнителя поддерживается начиная с версии DBAPI Enterprise Edition 4.5.0.