Intégration de DBAPI avec la base de données vectorielle Milvus : mise en pratique du mappage des paramètres de l’exécuteur HTTP

Qu’est-ce que Milvus ?

Milvus est une base de données vectorielle open source, conçue spécialement pour les applications d’IA, et permet le stockage, l’indexation ainsi que la recherche de similarité sur d’énormes volumes de données vectorielles. Elle est largement utilisée dans des scénarios tels que le RAG (Retrieval-Augmented Generation), la recherche sémantique et les systèmes de recommandation.

Milvus offre une API RESTful complète, permettant d’effectuer des opérations comme l’insertion, la requête et la recherche de vecteurs via le protocole HTTP.

Pourquoi utiliser DBAPI pour intégrer Milvus ?

Appeler directement l’API HTTP de Milvus implique d’assembler manuellement l’URL de la requête, de construire les paramètres requis et de gérer l’authentification et l’autorisation. Grâce à l’exécuteur HTTP de DBAPI, vous bénéficiez de :

• Une gestion unifiée des API : Toutes les opérations sur Milvus sont centralisées sous forme d’API DBAPI, avec authentification, limitation des accès et surveillance prêtes à l’emploi.
• Un mappage simplifié des paramètres : Un mode de mappage personnalisé convertit automatiquement les paramètres métier en le format requis par l’interface de Milvus, sans que l’appelant n’ait à se soucier des détails techniques de l’API de Milvus.
• Une sécurité renforcée : Les fonctionnalités d’authentification par jeton et de pare-feu IP héritées de DBAPI assurent une protection accrue.
• Une intégration sans code : Aucun développement d’intégration n’est nécessaire ; tout se fait par simple configuration.

Fonction clé : Mappage personnalisé des paramètres via l’exécuteur HTTP

La version 4.5.0 de DBAPI Enterprise a enrichi l’exécuteur HTTP d’un mode de mappage personnalisé. À l’aide d’un modèle JSON combiné à des placeholders ${} et à des expressions Groovy, vous pouvez mapper de manière flexible les paramètres transmis par l’appelant au format attendu par l’interface cible.

Paramètres transmis par l’appelant : { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
                │ Mappage des paramètres par l’exécuteur HTTP
                ▼  
Requête reçue par Milvus : { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }

Cas pratique : Intégration de Milvus

Prérequis

• DBAPI Enterprise 4.5.0 ou version ultérieure
• Un service Milvus déjà déployé (dans cet exemple, nous utilisons l’API HTTP v2 de Milvus)
• Une collection préalablement créée dans Milvus

Étape 1 : Création d’une source de données HTTP

Dans l’interface d’administration de DBAPI, accédez à la section Gestion des sources de données et cliquez sur « Créer une source de données » :

Paramètre	Valeur
Nom	Service Milvus
Type	HTTP
Adresse	http://192.168.1.100:19530

L’adresse correspond au port HTTP du service Milvus, par défaut 19530.

Étape 2 : Création d’une API d’insertion de vecteurs

Créez une API dans le groupe cible en utilisant l’exécuteur HTTP.

Informations de base

Paramètre	Valeur
Nom de l’API	Insertion de vecteurs dans Milvus
Chemin de l’API	/milvus/insert
Droits d’accès	Privé
Paramètres requis	id (bigint), vector (string), text (string)

Le paramètre vector doit être fourni sous forme de chaîne JSON, par exemple [0.1, 0.2, 0.3, ...].

Configuration de l’exécuteur

Paramètre	Valeur
Type d’exécuteur	Exécuteur proxy d’interface HTTP
Source de données	Service Milvus
Méthode	POST
Chemin URL	/v2/vectordb/entities/insert
Type de contenu	application/json
Mode de transmission des paramètres	Mappage personnalisé

En-têtes de requête personnalisés :

Clé	Valeur
Authorization	YOUR_MILVUS_TOKEN

Si Milvus utilise une authentification, configurez le jeton dans les en-têtes personnalisés ; l’exécuteur HTTP l’injectera automatiquement dans la requête transmise.

Modèle du corps de la requête :

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

Le champ collectionName est défini directement dans le modèle ; l’appelant n’a pas besoin de le transmettre. Le paramètre vector est fourni sous forme de chaîne de caractères représentant un tableau JSON, qui sera mappé au champ vector de Milvus.

Résultat de l’appel

L’appelant envoie la requête suivante :

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": "Intégration de DBAPI avec une base de données vectorielle"
}

Le système effectue le mappage selon le modèle et transfère la requête vers Milvus (l’exécuteur HTTP injecte automatiquement les en-têtes personnalisés) :

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": "Intégration de DBAPI avec une base de données vectorielle"}]}

Étape 3 : Création d’une API de recherche vectorielle

Informations de base

Paramètre	Valeur
Nom de l’API	Recherche vectorielle dans Milvus
Chemin de l’API	/milvus/search
Droits d’accès	Privé
Paramètres requis	vector (string), limit (bigint)

Configuration de l’exécuteur

Paramètre	Valeur
Type d’exécuteur	Exécuteur proxy d’interface HTTP
Source de données	Service Milvus
Méthode	POST
Chemin URL	/v2/vectordb/entities/search
Type de contenu	application/json
Mode de transmission des paramètres	Mappage personnalisé

Modèle du corps de la requête :

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

Le champ collectionName est fixé dans le modèle ; l’appelant n’a qu’à fournir le vecteur et le nombre maximal de résultats.

Résultat de l’appel

L’appelant envoie la requête suivante :

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
}

Le système effectue le mappage et transmet la requête à 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"]}

Étape 4 : Création d’une API de consultation par ID

Informations de base

Paramètre	Valeur
Nom de l’API	Consultation de vecteurs dans Milvus
Chemin de l’API	/milvus/query
Droits d’accès	Privé
Paramètres requis	collection (string), id (bigint)

Configuration de l’exécuteur

Paramètre	Valeur
Type d’exécuteur	Exécuteur proxy d’interface HTTP
Source de données	Service Milvus
Méthode	POST
Chemin URL	/v2/vectordb/entities/query
Type de contenu	application/json
Mode de transmission des paramètres	Mappage personnalisé

Modèle du corps de la requête :

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

La condition de filtrage est construite dynamiquement grâce à une expression Groovy (id == 1001), sans que l’appelant n’ait à connaître la syntaxe de requête de Milvus.

Résultat de l’appel

L’appelant envoie la requête suivante :

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

{
  "id": 1001
}

Le système effectue le mappage et transmet la requête à 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"]}

Autres astuces de mappage des paramètres

Structures imbriquées complexes

Si la collection de Milvus comporte plusieurs champs vectoriels ou des champs imbriqués, vous pouvez construire des modèles flexibles :

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

Calculs sur les paramètres

Effectuez des traitements préliminaires sur les paramètres transmis :

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

Assignation conditionnelle

Définissez dynamiquement les paramètres de recherche en fonction de la valeur des entrées :

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

Conclusion

Grâce à la fonction de mappage personnalisé des paramètres de l’exécuteur HTTP de DBAPI, l’intégration avec la base de données vectorielle Milvus devient extrêmement simple :

• L’appelant n’a qu’à transmettre les paramètres correspondant à son domaine métier, sans avoir à comprendre les détails de l’API de Milvus.
• Les modèles de mappage sont centralisés ; en cas de modification de l’API de Milvus, il suffit de mettre à jour le modèle, sans impact sur l’appelant.
• L’interface bénéficie des capacités d’authentification, de limitation des accès et de surveillance propres à DBAPI.
• L’intégration est entièrement réalisée sans écriture de code, uniquement par configuration.

Version requise : DBAPI Enterprise 4.5.0 ou version ultérieure prend en charge la fonction de mappage personnalisé des paramètres via l’exécuteur HTTP.