Integração do DBAPI com o banco de dados vetorial Milvus: prática de mapeamento de parâmetros do executor HTTP

O que é o Milvus?

O Milvus é um banco de dados vetorial de código aberto, projetado especificamente para aplicações de IA, suportando armazenamento, indexação e busca por similaridade de grandes volumes de dados vetoriais. É amplamente utilizado em cenários como RAG (Recuperação Aumentada por Geração), busca semântica e sistemas de recomendação.

O Milvus oferece uma interface completa baseada em API RESTful, permitindo operações como inserção, consulta e busca de dados vetoriais via protocolo HTTP.

Por que usar o DBAPI para integrar o Milvus?

Ao chamar diretamente a API HTTP do Milvus, é necessário concatenar manualmente os endereços das requisições, construir os parâmetros e lidar com autenticação e autorização. Com o executor HTTP do DBAPI, você obtém:

• Gerenciamento unificado de APIs: Todas as operações do Milvus são gerenciadas de forma unificada através da API do DBAPI, com recursos de permissões, limitação de taxa e monitoramento prontos para uso.
• Simplificação do mapeamento de parâmetros: Um modo de mapeamento personalizado converte automaticamente os parâmetros de negócio no formato de solicitação exigido pelo Milvus, eliminando a necessidade de o desenvolvedor se preocupar com os detalhes da interface do Milvus.
• Controle de segurança: Herda as capacidades de autenticação por token e firewall de IP do DBAPI.
• Integração sem codificação: Não é necessário escrever nenhum código de integração; tudo é configurado apenas por meio de configurações.

Função-chave: Mapeamento personalizado de parâmetros do executor HTTP

A versão 4.5.0 do DBAPI Enterprise ampliou o recurso de modo de mapeamento personalizado do executor HTTP. Usando um modelo JSON combinado com placeholders ${} e expressões Groovy, é possível mapear flexivelmente os parâmetros enviados pelo chamador para o formato de corpo de solicitação exigido pela interface alvo.

Parâmetros enviados pelo chamador: { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
                │ Mapeamento de parâmetros pelo executor HTTP
                ▼  
Recebidos pelo Milvus: { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }

Prática: Integração com o Milvus

Pré-requisitos

• Versão 4.5.0 ou superior do DBAPI Enterprise
• Serviço Milvus já implantado (neste exemplo, utilizamos a API HTTP v2 do Milvus)
• Coleção criada previamente no Milvus

Passo 1: Criar uma fonte de dados HTTP

No painel administrativo do DBAPI, acesse o Gerenciamento de Fontes de Dados e clique em “Criar Fonte de Dados”:

Configuração	Valor
Nome	Serviço Milvus
Tipo	HTTP
Endereço	http://192.168.1.100:19530

O endereço corresponde à porta HTTP do serviço Milvus, padrão 19530.

Passo 2: Criar a API de inserção de vetores

Crie uma API dentro do grupo desejado, utilizando o executor HTTP.

Informações básicas

Configuração	Valor
Nome da API	Inserir Vetores no Milvus
Caminho da API	/milvus/insert
Permissão	privada
Parâmetros	id (bigint), vector (string), text (string)

O parâmetro vector deve ser fornecido como uma string JSON, por exemplo: [0.1, 0.2, 0.3, ...].

Configuração do executor

Configuração	Valor
Tipo de Executor	Executor de Proxy de Interface HTTP
Fonte de Dados	Serviço Milvus
Método	POST
Caminho da URL	/v2/vectordb/entities/insert
Content-Type	application/json
Modo de Transmissão de Parâmetros	Mapeamento Personalizado

Cabeçalhos personalizados:

Chave	Valor
Authorization	YOUR_MILVUS_TOKEN

Se o Milvus estiver habilitado para autenticação, configure o token nos cabeçalhos personalizados; o executor HTTP injetará automaticamente esse token na requisição encaminhada.

Modelo do corpo da solicitação:

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

O campo collectionName está definido diretamente no modelo, não sendo necessário que o chamador o forneça. O parâmetro vector é passado como uma string de array JSON, mapeando-se ao campo vector do Milvus.

Efeito da chamada

Requisição do chamador:

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": "Integração do DBAPI com banco de dados vetorial"
}

Após o mapeamento conforme o modelo, o sistema encaminha a requisição ao Milvus (com o executor HTTP adicionando automaticamente os cabeçalhos 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": "Integração do DBAPI com banco de dados vetorial"}]}

Passo 3: Criar a API de busca vetorial

Informações básicas

Configuração	Valor
Nome da API	Busca Vetorial no Milvus
Caminho da API	/milvus/search
Permissão	privada
Parâmetros	vector (string), limit (bigint)

Configuração do executor

Configuração	Valor
Tipo de Executor	Executor de Proxy de Interface HTTP
Fonte de Dados	Serviço Milvus
Método	POST
Caminho da URL	/v2/vectordb/entities/search
Content-Type	application/json
Modo de Transmissão de Parâmetros	Mapeamento Personalizado

Modelo do corpo da solicitação:

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

O campo collectionName está fixo no modelo; o chamador precisa apenas informar o vetor e o número máximo de resultados.

Efeito da chamada

Requisição do chamador:

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
}

Após o mapeamento, o sistema encaminha a requisição ao 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"]}

Passo 4: Criar a API de consulta por ID

Informações básicas

Configuração	Valor
Nome da API	Consulta Vetorial no Milvus
Caminho da API	/milvus/query
Permissão	privada
Parâmetros	collection (string), id (bigint)

Configuração do executor

Configuração	Valor
Tipo de Executor	Executor de Proxy de Interface HTTP
Fonte de Dados	Serviço Milvus
Método	POST
Caminho da URL	/v2/vectordb/entities/query
Content-Type	application/json
Modo de Transmissão de Parâmetros	Mapeamento Personalizado

Modelo do corpo da solicitação:

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

Utiliza-se uma expressão Groovy para concatenar a condição de filtro id == 1001, sem que o chamador precise conhecer a sintaxe de consulta do Milvus.

Efeito da chamada

Requisição do chamador:

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

{
  "id": 1001
}

Após o mapeamento, o sistema encaminha a requisição ao 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"]}

Mais técnicas de mapeamento de parâmetros

Estruturas aninhadas complexas

Se a coleção do Milvus possuir múltiplos campos vetoriais ou campos aninhados, é possível construir modelos flexíveis:

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

Operações com parâmetros

Realize pré-processamento dos parâmetros recebidos:

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

Atribuição condicional

Defina dinamicamente parâmetros de busca com base no valor dos parâmetros:

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

Conclusão

Com o recurso de mapeamento personalizado de parâmetros do executor HTTP do DBAPI, integrar o banco de dados vetorial Milvus torna-se extremamente simples:

• O chamador só precisa fornecer os parâmetros com significado de negócio, sem precisar entender os detalhes da API do Milvus.
• Os modelos de mapeamento de parâmetros são centralizados; ao mudar a interface do Milvus, basta atualizar o modelo, sem impactar o chamador.
• A interface herda as funcionalidades corporativas do DBAPI, como autenticação, limitação de taxa e monitoramento.
• Tudo é feito sem codificação — a integração ocorre exclusivamente por meio de configurações.

Requisitos de versão: A versão 4.5.0 ou superior do DBAPI Enterprise suporta o recurso de mapeamento personalizado de parâmetros do executor HTTP.