Integración de DBAPI con la base de datos vectorial Milvus: Guía práctica de mapeo de parámetros del ejecutor HTTP

¿Qué es Milvus?

Milvus es una base de datos vectorial de código abierto, diseñada específicamente para aplicaciones de IA, que permite el almacenamiento, la indexación y la búsqueda de similitud en grandes volúmenes de datos vectoriales. Es ampliamente utilizada en escenarios como RAG (Recuperación Aumentada por Consulta), búsqueda semántica y sistemas de recomendación.

Milvus ofrece una completa interfaz API RESTful, permitiendo realizar operaciones como inserción, consulta y búsqueda de vectores mediante el protocolo HTTP.

¿Por qué usar DBAPI para integrar Milvus?

Llamar directamente a la API HTTP de Milvus requiere ensamblar manualmente la URL de la solicitud, construir los parámetros y gestionar la autenticación y autorización. Al integrar Milvus mediante el ejecutor HTTP de DBAPI, obtendrá:

• Gestión unificada de APIs: Todas las operaciones con Milvus se administran de forma centralizada a través de las APIs de DBAPI, con capacidades de control de permisos, limitación de tráfico y monitoreo listas para usar.
• Simplificación del mapeo de parámetros: Un modo de mapeo personalizado convierte automáticamente los parámetros del negocio al formato requerido por la interfaz de Milvus, eliminando la necesidad de que el consumidor se preocupe por los detalles de la API de Milvus.
• Control de seguridad: Hereda las capacidades de autenticación basada en tokens y el firewall de IP de DBAPI.
• Integración sin código: No es necesario escribir ninguna línea de código de integración; todo se configura mediante ajustes simples.

Funcionalidad clave: Mapeo personalizado de parámetros del ejecutor HTTP

DBAPI Enterprise 4.5.0 ha mejorado el modo de mapeo personalizado del ejecutor HTTP. Mediante una plantilla JSON que utiliza marcadores ${} y expresiones Groovy, puede mapear de manera flexible los parámetros enviados por el cliente al formato de cuerpo de solicitud requerido por la interfaz objetivo.

Parámetros enviados por el cliente: { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
                │ Mapeo de parámetros del ejecutor HTTP
                ▼  
Recepción por parte de Milvus: { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }

Implementación práctica: Integración con Milvus

Requisitos previos

• DBAPI Enterprise 4.5.0 o superior.
• Servicio Milvus desplegado (en este caso, se utiliza la API HTTP v2 de Milvus).
• Una colección ya creada en Milvus.

Paso 1: Crear una fuente de datos HTTP

En el panel de administración de DBAPI, acceda a Administración de fuentes de datos y haga clic en "Crear fuente de datos":

Configuración	Valor
Nombre	Servicio Milvus
Tipo	HTTP
Dirección	http://192.168.1.100:19530

La dirección corresponde al puerto HTTP del servicio Milvus, predeterminado en 19530.

Paso 2: Crear la API para insertar vectores

Cree una API dentro del grupo correspondiente utilizando el ejecutor HTTP.

Información básica

Configuración	Valor
Nombre de la API	Insertar vector en Milvus
Ruta de la API	/milvus/insert
Permisos de acceso	Privado
Parámetros de entrada	id (bigint), vector (string), text (string)

El parámetro vector debe ser una cadena JSON, por ejemplo: [0.1, 0.2, 0.3, ...].

Configuración del ejecutor

Configuración	Valor
Tipo de ejecutor	Ejecutor proxy de interfaz HTTP
Fuente de datos	Servicio Milvus
Método	POST
Ruta URL	/v2/vectordb/entities/insert
Tipo de contenido	application/json
Modo de transmisión de parámetros	Mapeo personalizado

Encabezados personalizados:

Clave	Valor
Authorization	YOUR_MILVUS_TOKEN

Si Milvus tiene habilitada la autenticación, configure el token en los encabezados personalizados; el ejecutor HTTP lo inyectará automáticamente en la solicitud reenviada.

Plantilla del cuerpo de solicitud:

{"collectionName": "news_articles", "data": [{"id": ${_parameters.id}, "vector": ${_parameters.vector}, "text": ${_parameters.text}}]}

El campo collectionName está definido directamente en la plantilla, por lo que el cliente no necesita enviarlo. El parámetro vector se pasa como una cadena de array JSON, que se mapea al campo vector de Milvus.

Resultado de la llamada

El cliente envía la solicitud:

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": "Integración de DBAPI con la base de datos vectorial"
}

Tras el mapeo según la plantilla, el sistema reenvía la solicitud a Milvus (el ejecutor HTTP añade automáticamente los encabezados personalizados):

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": "Integración de DBAPI con la base de datos vectorial"}]}

Paso 3: Crear la API para buscar vectores

Información básica

Configuración	Valor
Nombre de la API	Búsqueda de vectores en Milvus
Ruta de la API	/milvus/search
Permisos de acceso	Privado
Parámetros de entrada	vector (string), limit (bigint)

Configuración del ejecutor

Configuración	Valor
Tipo de ejecutor	Ejecutor proxy de interfaz HTTP
Fuente de datos	Servicio Milvus
Método	POST
Ruta URL	/v2/vectordb/entities/search
Tipo de contenido	application/json
Modo de transmisión de parámetros	Mapeo personalizado

Plantilla del cuerpo de solicitud:

{"collectionName": "news_articles", "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "outputFields": ["id", "text", "vector"]}

El campo collectionName está fijado en la plantilla, por lo que el cliente solo necesita proporcionar el vector y el límite de resultados.

Resultado de la llamada

El cliente envía la solicitud:

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
}

Tras el mapeo, el sistema reenvía la solicitud a 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"]}

Paso 4: Crear la API para consultar por ID

Información básica

Configuración	Valor
Nombre de la API	Consulta de vectores en Milvus
Ruta de la API	/milvus/query
Permisos de acceso	Privado
Parámetros de entrada	collection (string), id (bigint)

Configuración del ejecutor

Configuración	Valor
Tipo de ejecutor	Ejecutor proxy de interfaz HTTP
Fuente de datos	Servicio Milvus
Método	POST
Ruta URL	/v2/vectordb/entities/query
Tipo de contenido	application/json
Modo de transmisión de parámetros	Mapeo personalizado

Plantilla del cuerpo de solicitud:

{"collectionName": ${_parameters.collection}, "filter": "id == " + ${_parameters.id}, "outputFields": ["id", "text", "vector"]}

Utilizando expresiones Groovy, se construye dinámicamente la condición de filtro id == 1001, sin que el cliente tenga que conocer la sintaxis de consulta de Milvus.

Resultado de la llamada

El cliente envía la solicitud:

POST https://127.0.0.1:8520/milvus/query
Content-Type: application/json

{
  "id": 1001
}

Tras el mapeo, el sistema reenvía la solicitud a 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"]}

Más técnicas de mapeo de parámetros

Estructuras anidadas complejas

Si la colección de Milvus contiene múltiples campos vectoriales o campos anidados, puede construir estructuras flexibles mediante plantillas:

{"collectionName": ${_parameters.collection}, "data": [{"id": ${_parameters.id}, "titleVector": ${_parameters.titleVector}, "contentVector": ${_parameters.contentVector}, "metadata": {"author": ${_parameters.author}, "tags": ${_parameters.tags}}}]}

Cálculos con parámetros

Realice procesamientos preliminares sobre los parámetros recibidos:

{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit + 10}, "offset": ${(_parameters.page - 1) * _parameters.pageSize}}

Asignación condicional

Establezca parámetros de búsqueda dinámicamente según el valor de los parámetros:

{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "params": {"nprobe": ${_parameters.precision == "high" ? 64 : 16}}}

Resumen

Gracias a la función de mapeo personalizado de parámetros del ejecutor HTTP de DBAPI, integrar la base de datos vectorial Milvus resulta extremadamente sencillo:

• El cliente solo necesita proporcionar parámetros con significado comercial, sin necesidad de conocer los detalles de la API de Milvus.
• Las plantillas de mapeo se gestionan de forma centralizada; ante cambios en la interfaz de Milvus, basta con actualizar la plantilla sin afectar al cliente.
• La interfaz hereda las capacidades empresariales de DBAPI, como autenticación, control de tráfico y monitoreo.
• Todo se realiza sin escribir una sola línea de código; la integración se completa únicamente mediante configuraciones.

Requisitos de versión: DBAPI Enterprise 4.5.0 o superior admite la función de mapeo personalizado de parámetros del ejecutor HTTP.