Dans ce billet, nous allons voir comment construire un assistant RAG agentique en utilisant Mastra et une application web JavaScript légère pour interagir avec lui. En connectant cet agent à Elasticsearch, nous lui donnons accès aux données structurées des joueurs et la possibilité d'exécuter des agrégations statistiques en temps réel, afin de vous donner des recommandations fondées sur les statistiques des joueurs. Rendez-vous sur le repo GitHub pour suivre le processus ; le README fournit des instructions sur la manière de cloner et d'exécuter l'application par vos propres moyens.

Voici à quoi il devrait ressembler une fois assemblé :

Remarque : cet article de blog s'appuie sur "Building AI Agents with AI SDK and Elastic" ( Créer des agents d'intelligence artificielle avec AI SDK et Elastic). Si vous ne connaissez pas encore les agents d'intelligence artificielle en général et leur utilité, commencez par là.

Aperçu de l'architecture

Au cœur du système se trouve un grand modèle de langage (LLM), qui agit comme le moteur de raisonnement de l'agent (le cerveau). Il interprète les données de l'utilisateur, décide des outils à appeler et orchestre les étapes nécessaires pour générer une réponse pertinente.

L'agent lui-même est soutenu par Mastra, un cadre d'agent dans l'écosystème JavaScript. Mastra intègre le LLM à une infrastructure dorsale, l'expose en tant que point d'extrémité de l'API et fournit une interface pour définir les outils, les invites du système et le comportement de l'agent.

Sur le frontend, nous utilisons Vite pour mettre en place rapidement une application web React qui fournit une interface de chat pour envoyer des requêtes à l'agent et recevoir ses réponses.

Enfin, nous avons Elasticsearch, qui stocke les statistiques des joueurs et les données de correspondance que l'agent peut interroger et agréger.

Arrière-plan

Passons en revue quelques concepts fondamentaux :

Qu'est-ce que le RAG agentique ?

Les agents d'intelligence artificielle peuvent interagir avec d'autres systèmes, fonctionner de manière indépendante et effectuer des actions en fonction de paramètres définis. Le RAG agentique combine l'autonomie d'un agent d'intelligence artificielle avec les principes de la génération augmentée par récupération, ce qui permet à un LLM de choisir les outils à utiliser et les données à utiliser comme contexte pour générer une réponse. Pour en savoir plus sur le RAG , cliquez ici.

Pourquoi aller plus loin que AI-SDK dans le choix d'un framework ?

Il existe de nombreuses structures d'agents d'IA et vous avez probablement entendu parler des plus populaires comme CrewAI, AutoGen et LangGraph. La plupart de ces cadres partagent un ensemble commun de fonctionnalités, notamment la prise en charge de différents modèles, l'utilisation d'outils et la gestion de la mémoire.

Voici une fiche comparative de Harrison Chase (PDG de LangChain).

Ce qui a suscité mon intérêt pour Mastra, c'est qu'il s'agit d'un framework JavaScript conçu pour les développeurs full-stack afin d'intégrer facilement des agents dans leur écosystème. L'AI-SDK de Vercel permet également de réaliser la plupart de ces tâches, mais c'est lorsque vos projets incluent des flux de travail d'agents plus complexes que Mastra brille. Mastra améliore les modèles de base définis par l'AI-SDK et, dans ce projet, nous les utiliserons en tandem.

Cadres et considérations sur le choix du modèle

Si ces frameworks peuvent vous aider à créer rapidement des agents d'intelligence artificielle, ils présentent néanmoins certains inconvénients. Par exemple, l'utilisation d'autres cadres en dehors des agents d'IA ou de toute couche d'abstraction en général vous fait perdre un peu de contrôle. Si le LLM n'utilise pas les outils correctement ou fait quelque chose que vous ne voulez pas qu'il fasse, l'abstraction rend le débogage plus difficile. Cependant, à mon avis, ce compromis vaut la facilité et la rapidité que vous obtenez lors de la construction, en particulier parce que ces cadres gagnent du terrain et font l'objet d'itérations constantes.

Encore une fois, ces cadres sont agnostiques, ce qui signifie que vous pouvez brancher et utiliser différents modèles. N'oubliez pas que les modèles varient en fonction des ensembles de données sur lesquels ils ont été formés et qu'à leur tour, ils varient en fonction des réponses qu'ils donnent. Certains modèles ne prennent même pas en charge l'appel d'outils. Il est donc possible de changer et de tester différents modèles pour voir lequel vous donne les meilleures réponses, mais gardez à l'esprit que vous devrez probablement réécrire l'invite du système pour chacun d'entre eux. Par exemple, en utilisant Llama3.3 par rapport au GPT-4o, implique beaucoup plus d'invites et d'instructions spécifiques pour obtenir la réponse souhaitée.

Basket-ball fantaisie NBA

Le basket-ball fantaisie consiste à créer une ligue avec un groupe d'amis (attention, selon le degré de compétition de votre groupe, cela peut affecter le statut de vos amitiés), généralement avec de l'argent en jeu. Chacun d'entre vous constitue ensuite une équipe de 10 joueurs pour affronter les 10 joueurs d'un autre ami, en alternance chaque semaine. Les points qui contribuent à votre score global sont les résultats obtenus par chacun de vos joueurs contre leurs adversaires au cours d'une semaine donnée.

Si un joueur de votre équipe se blesse, est suspendu, etc., il y a une liste d'agents libres disponibles pour compléter votre équipe. C'est là qu'intervient une grande partie de la réflexion dans les sports fantastiques, car vous ne disposez que d'un nombre limité de choix et tout le monde est constamment à la recherche du meilleur joueur.

C'est là que notre assistant NBA AI va briller, en particulier dans les situations où vous devez rapidement décider quel joueur choisir. Au lieu de devoir rechercher manuellement les performances d'un joueur contre un adversaire spécifique, l'assistant peut trouver ces données rapidement et comparer les moyennes pour vous donner une recommandation éclairée.

Maintenant que vous connaissez les bases du RAG agentique et du basket-ball fantastique NBA, voyons ce qu'il en est dans la pratique.

Construire le projet

Si vous êtes bloqué à un moment ou à un autre ou si vous ne voulez pas le construire à partir de zéro, veuillez vous référer au repo.

Ce que nous allons couvrir

1. L'échafaudage du projet :

   1. Backend (Mastra) : Utilisez npx create mastra@latest pour échafauder le backend et définir la logique de l'agent.

   2. Frontend (Vite + React) : Utilisez npm create vite@latest pour construire l'interface de chat frontale pour interagir avec l'agent.

2. Mise en place de variables d'environnement

   1. Installer dotenv pour gérer les variables d'environnement.

   2. Créer un fichier .env et fournir les variables nécessaires.

3. Configuration d'Elasticsearch

   1. Mettre en place un cluster Elasticsearch (localement ou sur le cloud).

   2. Installer le client Elasticsearch officiel.

   3. S'assurer que les variables d'environnement sont accessibles.

   4. Établir la connexion avec le client.

4. Acquisition en masse de données NBA dans Elasticsearch

   1. Créez un index avec les mappings appropriés pour permettre les agrégations.

   2. Intégrez en masse les statistiques de jeu des joueurs à partir d'un fichier CSV dans un index Elasticsearch.

5. Définir les agrégations Elasticsearch

   1. Requête pour calculer les moyennes historiques contre un adversaire spécifique.

   2. Requête pour calculer les moyennes de la saison contre un adversaire spécifique.

6. Fichier utilitaire de comparaison des joueurs

   1. Consolidation des fonctions d'aide et des agrégations Elasticsearch.

7. Construction de l'agent

   1. Ajouter la définition de l'agent et l'invite du système.

   2. Installer les outils zod et define.

   3. Ajout d'une configuration intermédiaire pour gérer CORS.

8. Intégration de l'interface utilisateur

   1. Utilisation de la fonction useChat de l'AI-SDK pour interagir avec l'agent.

   2. Créer l'interface utilisateur pour tenir des conversations correctement formatées.

9. Exécution de l'application

   1. Démarrez le backend (serveur Mastra) et le frontend (application React).

   2. Exemples de requêtes et d'utilisation.

10. Et maintenant ? Rendre l'agent plus intelligent

    1. Ajout de capacités de recherche sémantique pour permettre des recommandations plus pertinentes.

    2. Activer l'interrogation dynamique en déplaçant la logique de recherche vers le serveur Elasticsearch MCP (Model Context Protocol).

Produits requis

• Node.js et npm: Le backend et le frontend fonctionnent tous deux sur Node. Assurez-vous d'avoir installé Node 18+ et npm v9+ (qui est fourni avec Node 18+).

• Cluster Elasticsearch : Un cluster Elasticsearch actif, soit localement, soit sur le cloud.

• Clé API OpenAI: Générez-en une sur la page des clés API du portail des développeurs d'OpenAI.

Structure du projet

Étape 1 : Échafaudage du projet

1. Tout d'abord, créez le répertoire nba-ai-assistant-js et naviguez à l'intérieur en utilisant :

Backend :

1. Utilisez l'outil de création Mastra avec la commande :

2. Vous devriez obtenir quelques invites dans votre terminal, pour la première, nous nommerons le projet backend :

3. Ensuite, nous conserverons la structure par défaut pour le stockage des fichiers Mastra, en saisissant src/.

4. Ensuite, nous choisirons OpenAI comme fournisseur LLM par défaut.

5. Enfin, il vous demandera votre clé API OpenAI. Pour l'instant, nous choisirons d'ignorer l'option et nous la fournirons plus tard dans un fichier .env.

Frontend :

1. Naviguez à nouveau vers le répertoire racine et exécutez l'outil de création Vite à l'aide de cette commande : npm create vite@latest frontend -- --template react

Cela devrait créer une application React légère nommée frontend avec un modèle spécifique pour React.

Si tout se passe bien, à l'intérieur de votre répertoire de projet, vous devriez trouver un répertoire backend qui contient le code Mastra et un répertoire frontend avec votre application React.

Étape 2 : Configuration des variables d'environnement

1. Pour gérer les clés sensibles, nous utiliserons le paquetage dotenv pour charger nos variables d'environnement à partir du fichier .env. fichier. Naviguez vers le répertoire backend et installez dotenv:

2. Dans le répertoire du backend, un fichier example.env est fourni avec les variables appropriées à remplir. Si vous créez le vôtre, veillez à inclure les variables suivantes :

Note : Assurez-vous que ce fichier est exclu de votre contrôle de version en ajoutant .env à .gitignore.

Étape 3 : Configuration d'Elasticsearch

Tout d'abord, vous devez disposer d'un cluster Elasticsearch actif. Deux options sont possibles :

• Option A : utiliser Elasticsearch Cloud

  • S'inscrire à Elastic Cloud

  • Créer un nouveau déploiement

  • Obtenez l'URL de votre point de terminaison et la clé API (encodée)

• Option B : Exécuter Elasticsearch localement

  • Installer et exécuter Elasticsearch localement

  • Utilisez http://localhost:9200 comme point d'arrivée

  • Générer une clé API

Installation du client Elasticsearch sur le backend :

1. Tout d'abord, installez le client Elasticsearch officiel dans votre répertoire backend :

2. Créez ensuite un répertoire lib pour contenir les fonctions réutilisables et naviguez-y :

3. À l'intérieur, créez un nouveau fichier appelé elasticClient.js. Ce fichier initialise le client Elasticsearch et l'expose pour qu'il soit utilisé dans votre projet.

4. Comme nous utilisons des modules ECMAScript (ESM), le nom de fichier __dirname and __n'est pas disponible. Pour vous assurer que vos variables d'environnement sont correctement chargées à partir du fichier .env dans le dossier backend, ajoutez cette configuration au début de votre fichier :

5. Maintenant, initialisez le client Elasticsearch en utilisant vos variables d'environnement et vérifiez la connexion :

Maintenant, nous pouvons importer cette instance client dans n'importe quel fichier qui doit interagir avec votre cluster Elasticsearch.

Étape 4 : Intégration en masse des données NBA dans Elasticsearch

Ensemble de données :

Pour ce projet, nous ferons référence aux ensembles de données disponibles dans le répertoire backend/data de la base de données. Notre assistant NBA utilisera ces données comme base de connaissances pour effectuer des comparaisons statistiques et générer des recommandations.

• sample_player_game_stats.csv - Exemple de statistiques de jeu d'un joueur (par exemple, points, rebonds, interceptions, etc.) par match et par joueur sur l'ensemble de sa carrière en NBA. Nous utiliserons cet ensemble de données pour effectuer des agrégations. (Remarque : il s'agit de données fictives, générées à des fins de démonstration et ne provenant pas de sources officielles de la NBA).

• playerAndTeamInfo.js - Remplace les métadonnées sur les joueurs et les équipes qui seraient normalement fournies par un appel à l'API afin que l'agent puisse faire correspondre les noms des joueurs et des équipes aux identifiants. Comme nous utilisons des données d'échantillon, nous ne voulons pas nous encombrer d'une API externe, c'est pourquoi nous avons codé en dur certaines valeurs auxquelles l'agent peut se référer.

Mise en œuvre :

1. Dans le répertoire backend/lib, créez un fichier nommé playerDataIngestion.js.

2. Configurer les importations, résoudre le chemin du fichier CSV et configurer l'analyse. Là encore, puisque nous utilisons ESM, nous devons reconstruire __dirname pour résoudre le chemin d'accès à l'échantillon CSV. Nous importerons également le module Node.js les modules intégrés, fs et readline, pour analyser le fichier CSV donné ligne par ligne.

Cela vous permet de lire et d'analyser efficacement le fichier CSV lorsque nous passons à l'étape de l'ingestion en masse.

3. Créez un index avec la correspondance appropriée. Bien qu'Elasticsearch puisse déduire automatiquement les types de champs avec le mappage dynamique, nous voulons être explicites ici pour que chaque statut soit traité comme un champ numérique. Ceci est important car nous utiliserons ces champs pour les agrégations par la suite. Nous voulons également utiliser le type float pour les statistiques telles que les points, les rebonds, etc., afin de nous assurer que nous incluons des valeurs décimales. Enfin, nous voulons ajouter la propriété de mappage dynamic: 'strict' afin qu'Elasticsearch ne mappe pas dynamiquement les champs non reconnus. 

4. Ajoutez la fonction permettant d'intégrer en masse les données CSV dans votre index Elasticsearch. À l'intérieur du bloc de code, nous sautons la ligne d'en-tête. Ensuite, divisez chaque ligne par une virgule et insérez-les dans l'objet document. Cette étape permet également de les nettoyer et de s'assurer qu'ils sont du bon type. Ensuite, nous plaçons les documents dans le tableau bulkBody avec les informations d'index, qui serviront de charge utile pour l'ingestion en masse dans Elasticsearch.

5. Ensuite, nous pouvons utiliser l'API Bulk d'Elasticsearch avec elasticClient.bulk() pour ingérer plusieurs documents en une seule demande. La gestion des erreurs ci-dessous est structurée de manière à vous indiquer le nombre de documents qui n'ont pas été ingérés et le nombre de documents qui ont été ingérés avec succès.

6. Exécutez la fonction main() ci-dessous pour exécuter séquentiellement les fonctions createIndex() et bulkIngestCsv().

Si vous voyez un journal de console indiquant que l'ingestion en masse a réussi, effectuez une vérification rapide de votre index Elasticsearch pour voir si les documents ont effectivement été ingérés avec succès.

Étape 5 : Définition des agrégations Elasticsearch et consolidation

Ce sont les principales fonctions qui seront utilisées lorsque nous définirons les outils de l'agent IA afin de comparer les statistiques des joueurs entre eux.

1. Naviguez jusqu'au répertoire backend/lib et créez un fichier appelé elasticAggs.js.

2. Ajoutez la requête ci-dessous pour calculer les moyennes historiques d'un joueur contre un adversaire spécifique. Cette requête utilise un filtre bool avec 2 conditions : l'une correspondant à player_id et l'autre à opponent_team_id, afin de récupérer uniquement les jeux pertinents. Nous n'avons pas besoin de renvoyer de documents, nous ne nous intéressons qu'aux agrégations, c'est pourquoi nous définissons size:0. Sous le bloc aggs, nous exécutons plusieurs agrégations métriques en parallèle sur des champs tels que points, rebounds, assists, steals, blocks et fg_percentage pour calculer leurs valeurs moyennes. Les LLM peuvent être aléatoires dans leurs calculs et ce processus est déchargé sur Elasticsearch, ce qui garantit à notre assistant NBA AI l'accès à des données exactes.

3. Pour calculer les moyennes saisonnières d'un joueur contre un adversaire spécifique, nous utiliserons pratiquement la même requête que la requête historique. La seule différence dans cette requête est que le filtre bool est assorti d'une condition supplémentaire pour game_date. Le champ game_date doit se situer dans la fourchette de la saison NBA en cours. Dans ce cas, la fourchette est comprise entre 2024-10-01 et 2025-06-30. Cette condition supplémentaire ci-dessous garantit que les agrégations qui suivent n'isoleront que les matchs de cette saison.

Étape 6 : Utilitaire de comparaison des joueurs

Pour que notre code reste modulaire et facile à maintenir, nous allons créer un fichier utilitaire qui consolide les fonctions d'aide aux métadonnées et les agrégations Elasticsearch. Il s'agit de l'outil principal utilisé par l'agent. Nous y reviendrons plus tard :

1. Créez un nouveau fichier comparePlayers.js dans le répertoire backend/lib.

2. Ajoutez la fonction ci-dessous pour consolider les aides aux métadonnées et la logique d'agrégation Elasticsearch en une seule fonction qui alimente l'outil principal utilisé par l'agent.

Étape 7 : Création de l'agent

Maintenant que vous avez créé les échafaudages frontend et backend, ingéré les données du jeu NBA et établi une connexion à Elasticsearch, nous pouvons commencer à assembler toutes les pièces pour construire l'agent.

Définition de l'agent

1. Accédez au fichier index.ts dans le répertoire backend/src/mastra/agents et ajoutez la définition de l'agent. Vous pouvez spécifier des champs tels que :

• Nom : Donnez à votre agent un nom qui sera utilisé comme référence lorsqu'il sera appelé sur le frontend.

• Instructions/Instructions du système : Une invite système donne au MLD le contexte initial et les règles à suivre pendant l'interaction. Il s'agit d'une invite similaire à celle que les utilisateurs envoient par l'intermédiaire de la boîte de dialogue, mais celle-ci est donnée avant toute entrée de l'utilisateur. Là encore, cela varie en fonction du modèle que vous choisissez.

• Modèle : Quel LLM utiliser (Mastra soutient OpenAI, Anthropic, les modèles locaux, etc.)

• Outils : Une liste de fonctions d'outils que l'agent peut appeler.

• Mémoire : (Facultatif) si nous voulons que l'agent se souvienne de l'historique des conversations, etc. Pour des raisons de simplicité, nous pouvons commencer sans mémoire persistante, bien que Mastra la prenne en charge.

Définition des outils

1. Naviguez jusqu'au fichier index.ts dans le répertoire backend/src/mastra/tools.

2. Installez Zod à l'aide de la commande :

3. Ajouter des définitions d'outils. Notez que nous importons la fonction dans le fichier comparePlayers.js en tant que fonction principale que l'agent utilisera lorsqu'il appellera cet outil. En utilisant la fonction createTool() de Mastra, nous enregistrerons notre playerComparisonTool. Les domaines concernés sont les suivants :

• id: Il s'agit d'une description en langage naturel qui aide l'agent à comprendre ce que fait l'outil.

• input schema: Pour définir la forme de l'entrée de l'outil, Mastra utilise le schéma Zod, qui est une bibliothèque de validation de schéma TypeScript. Zod s'assure que l'agent saisit des données correctement structurées et empêche l'outil de s'exécuter si la structure de l'entrée ne correspond pas.

• description: Il s'agit d'une description en langage naturel qui aide l'agent à comprendre quand il doit appeler et utiliser l'outil.

• execute: La logique qui s'exécute lorsque l'outil est appelé. Dans notre cas, nous utilisons une fonction d'aide importée pour renvoyer des statistiques de performance.

Ajout d'un logiciel intermédiaire pour gérer CORS

Ajouter un middleware dans le serveur Mastra pour gérer CORS. On dit qu'il y a trois choses dans la vie qu'on ne peut pas éviter : la mort, les impôts, et pour les développeurs web, c'est CORS. En bref, le partage des ressources inter-origines est une fonction de sécurité du navigateur qui empêche le front-end d'envoyer des requêtes à un back-end fonctionnant sur un domaine ou un port différent. Même si nous exécutons le backend et le frontend sur localhost, ils utilisent des ports différents, ce qui déclenche la politique CORS. Nous devons ajouter l'intergiciel spécifié dans la documentation de Mastra afin que notre backend autorise ces requêtes depuis le frontend.

1. Naviguez jusqu'au fichier index.ts dans le répertoire backend/src/mastra et ajoutez la configuration pour CORS :

• origin: ['http://localhost:5173']

  • Autorise les demandes provenant uniquement de cette adresse (adresse par défaut de Vite)

• allowMethods: ["GET", "POST"]

  • Méthodes HTTP autorisées. La plupart du temps, il utilisera POST.

• allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type, "x-highlight-request", "traceparent"],

  • Ils déterminent quels en-têtes personnalisés peuvent être utilisés dans les requêtes

Étape 8 : Intégration de l'interface utilisateur

Ce composant React fournit une interface de chat simple qui se connecte à l'agent IA Mastra en utilisant le hook useChat() de @ai-sdk/react. Nous allons également utiliser ce crochet pour afficher l'utilisation des jetons, les appels d'outils et pour rendre la conversation. Dans l'invite système ci-dessus, nous demandons également à l'agent de produire la réponse en format markdown, nous utiliserons donc react-markdown pour formater correctement la réponse.

1. Dans le répertoire frontend, installez le paquetage @ai-sdk/react pour utiliser le hook useChat().

2. Dans le même répertoire, installez React Markdown pour que nous puissions formater correctement la réponse générée par l'agent.

3. Mettre en œuvre useChat(). Ce hook va gérer l'interaction entre votre frontend et votre agent IA backend. Il gère l'état des messages, les entrées de l'utilisateur, l'état et vous donne des crochets de cycle de vie à des fins d'observabilité. Les options que nous transmettons sont les suivantes :

• api: Ceci définit le point final de votre agent Mastra AI. Le port par défaut est le port 4111 et nous voulons également ajouter la route qui prend en charge les réponses en continu.

• onToolCall: Cette fonction s'exécute chaque fois que l'agent appelle un outil ; nous l'utilisons pour savoir quels outils notre agent appelle.

• onFinish: Cette opération s'exécute après que l'agent a fourni une réponse complète. Même si nous avons activé le streaming, onFinish sera toujours exécuté après la réception du message complet et non après chaque morceau. Ici, nous l'utilisons pour suivre l'utilisation de nos jetons. Cela peut s'avérer utile pour contrôler et optimiser les coûts de la gestion du cycle d'apprentissage tout au long de la vie.

4. Enfin, nous nous rendons au composant ChatUI.jsx dans le répertoire frontend/components pour créer l'interface utilisateur de notre conversation. Ensuite, la réponse est enveloppée dans un composant ReactMarkdown afin de formater correctement la réponse de l'agent.

Étape 9 : Exécution de l'application

Félicitations ! Vous êtes maintenant prêt à exécuter l'application. Suivez ces étapes pour démarrer le backend et le frontend.

1. Dans une fenêtre de terminal, à partir du répertoire racine, naviguez jusqu'au répertoire backend et démarrez le serveur Mastra :

2. Dans une autre fenêtre de terminal, à partir du répertoire racine, naviguez jusqu'au répertoire frontend et démarrez l'application React :

3. Allez dans votre navigateur et naviguez jusqu'à :

http://localhost:5173

Vous devriez voir l'interface de chat. Essayez les exemples suivants :

• "Comparer LeBron James et Stephen Curry"

• "Qui choisir entre Jayson Tatum et Luka Doncic ?"

Et maintenant ? Rendre l'agent plus intelligent

Pour rendre l'assistant plus agentive et les recommandations plus perspicaces, j'ajouterai quelques améliorations clés dans la prochaine itération.

Recherche sémantique pour les nouvelles de la NBA

Il y a une tonne de facteurs qui peuvent affecter les performances des joueurs, dont beaucoup n'apparaissent pas dans les statistiques brutes. Des choses comme les rapports sur les blessures, les changements de composition, ou même une analyse d'après-match, vous ne pouvez les trouver que dans des articles de presse. Pour saisir ce contexte supplémentaire, j'ajouterai des capacités de recherche sémantique afin que l'agent puisse retrouver des articles pertinents de la NBA et tenir compte de ce récit dans ses recommandations.

Recherche dynamique avec le serveur Elasticsearch MCP

Le protocole MCP (Model Context Protocol) devient rapidement la norme pour la connexion des agents aux sources de données. Je vais migrer la logique de recherche dans le serveur Elasticsearch MCP, qui permet à l'agent de construire dynamiquement des requêtes plutôt que de s'appuyer sur les fonctions de recherche prédéfinies que nous fournissons. Cela nous permet d'utiliser davantage de flux de travail en langage naturel et de réduire la nécessité de rédiger manuellement chaque requête de recherche. Pour en savoir plus sur le serveur Elasticsearch MCP et l'état actuel de l'écosystème , cliquez ici.

Ces changements sont déjà en cours, restez à l'écoute !

Conclusion

Dans ce blog, nous avons construit un assistant RAG agentique qui fournit des recommandations personnalisées pour votre équipe de basket-ball fantasy en utilisant JavaScript, Mastra et Elasticsearch. Nous avons couvert :

• Les principes fondamentaux de la RAG agentique et la manière dont la combinaison de l'autonomie d'un agent d'intelligence artificielle avec les outils permettant d'utiliser efficacement la RAG peut déboucher sur des agents plus nuancés et plus dynamiques.

• Elasticsearch et comment ses capacités de stockage de données et ses puissantes agrégations natives en font un partenaire idéal en tant que base de connaissances pour un LLM.

• Le cadre Mastra et la manière dont il simplifie la construction de ces agents pour les développeurs de l'écosystème JavaScript.

Que vous soyez fanatique de basket-ball, que vous cherchiez à construire des agents d'intelligence artificielle, ou les deux comme moi, j'espère que ce blog vous a donné quelques éléments de base pour commencer. Le repo complet est disponible sur GitHub, n'hésitez pas à le cloner et à le modifier. Maintenant, allez gagner cette ligue de fantasy !

Nous ferons le point :

• Meilleures pratiques de production

  • Gestion des erreurs

  • Tests

• Environnements sans serveur

  • Exécuter le client sur Elastic Serverless

  • Exécution du client dans un environnement de services fonctionnels (function-as-a-service)

Vous pouvez consulter le code source avec les exemples ici.

Meilleures pratiques de production

Gestion des erreurs dans Elasticsearch

Une caractéristique utile du client Elasticsearch dans Node.js est qu'il expose des objets pour les erreurs possibles dans Elasticsearch afin que vous puissiez les valider et les traiter de différentes manières.

Pour les voir tous, cliquez ici : 

Revenons à l'exemple de la recherche et traitons certaines des erreurs possibles :

ResponseError en particulier, se produit lorsque la réponse est 4xx ou 5xx, ce qui signifie que la demande est incorrecte ou que le serveur n'est pas disponible.

Nous pouvons tester ce type d'erreur en générant des requêtes erronées, par exemple en essayant d'effectuer une recherche de terme sur un champ de type texte :

Erreur par défaut :

Erreur personnalisée :

Nous pouvons également capturer et traiter chaque type d'erreur d'une certaine manière. Par exemple, nous pouvons ajouter une logique de réessai dans un site TimeoutError.

Tests

Les tests sont essentiels pour garantir la stabilité de l'application. Pour tester le code d'une manière isolée d'Elasticsearch, nous pouvons utiliser la bibliothèque elasticsearch-js-mock lors de la création de notre cluster.

Cette bibliothèque nous permet d'instancier un client qui est très similaire au vrai client mais qui répondra à notre configuration en remplaçant seulement la couche HTTP du client par une couche fictive tout en gardant le reste identique à l'original.

Nous installerons la bibliothèque mocks et AVA pour les tests automatisés.

npm install @elastic/elasticsearch-mock

npm install --save-dev ava

Nous allons configurer le fichier package.json pour exécuter les tests. Veillez à ce qu'il en soit ainsi :

Créons maintenant un fichier test.js et installons notre client fictif :

Maintenant, ajoutez un simulacre de recherche sémantique :

Nous pouvons maintenant créer un test pour notre code, en nous assurant que la partie Elasticsearch renvoie toujours les mêmes résultats :

Exécutons les tests.

npm run test

C'est fait ! Désormais, nous pouvons tester notre application en nous concentrant à 100 % sur le code et non sur des facteurs externes.

Environnements sans serveur

Exécution du client avec Elastic Serverless

Nous avons abordé l'exécution d'Elasticsearch sur le Cloud ou sur site ; cependant, le client Node.js prend également en charge les connexions à Elastic Cloud Serverless.

Elastic Cloud Serverless vous permet de créer un projet dans lequel vous n'avez pas besoin de vous préoccuper de l'infrastructure puisqu'Elastic s'en charge en interne, et vous n'avez qu'à vous préoccuper des données que vous souhaitez indexer et de la durée pendant laquelle vous souhaitez y avoir accès.

Du point de vue de l'utilisation, Serverless découple le calcul du stockage, offrant des fonctionnalités d'autoscaling pour la recherche et l'indexation. Cela vous permet de n'augmenter que les ressources dont vous avez réellement besoin.

Le client effectue les adaptations suivantes pour se connecter à Serverless :

• Désactive le sniffing et ignore toutes les options liées au sniffing.

• Ignore tous les nœuds passés dans la configuration sauf le premier, et ignore toutes les options de filtrage et de sélection des nœuds.

• Active la compression et `TLSv1_2_method` (identique à la configuration pour Elastic Cloud)

• Ajoute un en-tête HTTP `elastic-api-version` à toutes les requêtes

• Utilise `CloudConnectionPool` par défaut au lieu de `WeightedConnectionPool`.

• Désactive les en-têtes `content-type` et `accept` en faveur des types MIME standard.

Pour connecter votre projet serverless, vous devez utiliser le paramètre serverMode : serverless.

Exécution du client sur une plateforme FaaS (Function-as-a-Service)

Dans l'exemple, nous avons utilisé un serveur Node.js, mais vous pouvez également vous connecter en utilisant un environnement de fonction en tant que service avec des fonctions telles que AWS lambda, GCP Run, etc.

Un autre exemple consiste à se connecter à des services comme Vercel, qui est également sans serveur. Vous pouvez consulter cet exemple complet de la manière de procéder, mais la partie la plus pertinente du point de terminaison de la recherche ressemble à ceci :

Ce point d'accès se trouve dans le dossier /api et est exécuté du côté du serveur, de sorte que le client ne contrôle que le paramètre "text" qui correspond au terme de la recherche.

L'utilisation de la fonction en tant que service implique que, contrairement à un serveur fonctionnant 24 heures sur 24 et 7 jours sur 7, les fonctions ne font appel qu'à la machine qui exécute la fonction et, une fois celle-ci terminée, la machine passe en mode repos afin de consommer moins de ressources.

Cette configuration peut être pratique si l'application ne reçoit pas trop de demandes ; dans le cas contraire, les coûts peuvent être élevés. Vous devez également tenir compte du cycle de vie des fonctions et des durées d'exécution (qui ne peuvent être que de quelques secondes dans certains cas).

Conclusion

Dans cet article, nous avons appris à gérer les erreurs, ce qui est crucial dans les environnements de production. Nous avons également abordé le test de notre application en simulant le service Elasticsearch, ce qui permet d'obtenir des tests fiables quel que soit l'état du cluster et de se concentrer sur notre code.

Enfin, nous avons montré comment mettre en place une pile entièrement sans serveur en provisionnant à la fois Elastic Cloud Serverless et une application Vercel.

Dans cette première partie, nous passerons en revue

• Environnement

  • Frontend, backend ou serverless ?

  • Connexion du client

• Indexation des documents

  • Client Elasticsearch

  • Correspondances sémantiques

  • Aide en vrac

• Recherche de données

  • Requête lexicale

  • Requête sémantique

  • Requête hybride

Vous pouvez consulter le code source avec les exemples ici.

Qu'est-ce que le client Elasticsearch Node.js ?

Le client Elasticsearch Node.js est une bibliothèque JavaScript qui transpose les appels HTTP REST de l'API Elasticsearch en JavaScript. Il est ainsi plus facile à manipuler et dispose d'assistants qui simplifient les tâches telles que l'indexation de documents par lots.

Environnement

Frontend, backend ou serverless ?

Pour créer notre application de recherche à l'aide du client JavaScript, nous avons besoin d'au moins deux composants : un cluster Elasticsearch et un moteur d'exécution JavaScript pour exécuter le client.

Le client JavaScript prend en charge toutes les solutions Elasticsearch (Cloud, on-prem et Serverless), et il n'y a pas de différences majeures entre elles puisque le client gère toutes les variations en interne, vous n'avez donc pas à vous soucier de savoir laquelle utiliser.

Le moteur d'exécution JavaScript doit toutefois être exécuté à partir du serveur et non directement à partir du navigateur.

En effet, en appelant Elasticsearch depuis le navigateur, l'utilisateur peut obtenir des informations sensibles telles que la clé API du cluster, l'hôte ou la requête elle-même. Elasticsearch recommande de ne jamais exposer le cluster directement à l'internet et d'utiliser une couche intermédiaire qui abstrait toutes ces informations de sorte que l'utilisateur ne puisse voir que les paramètres. Pour en savoir plus sur ce sujet , cliquez ici.

Nous suggérons d'utiliser un schéma comme celui-ci :

Dans ce cas, le client n'envoie que les termes de recherche et une clé d'authentification pour votre serveur, tandis que votre serveur contrôle totalement la requête et la communication avec Elasticsearch.

Connexion du client

Commencez par créer une clé API en suivant ces étapes.

En suivant l'exemple précédent, nous allons créer un simple serveur Express, et nous y connecter en utilisant un client depuis un serveur Node.JS.

Nous allons initialiser le projet avec NPM et installer le client Elasticsearch et Express. Cette dernière est une bibliothèque qui permet d'activer des serveurs dans Node.js. En utilisant Express, nous pouvons interagir avec notre backend via HTTP.

Initialisons le projet :

npm init -y

Installer les dépendances :

npm install @elastic/elasticsearch express split2 dotenv

Laissez-moi vous expliquer :

• @elastic/elasticsearch: C'est le client officiel Node.js

• express: Il nous permettra de faire tourner un serveur nodejs léger pour exposer Elasticsearch.

• split2: divise les lignes de texte en un flux. Utile pour traiter nos fichiers ndjson une ligne à la fois

• dotenv: Permet de gérer les variables d'environnement à l'aide d'un fichier .env fichier

Créer un fichier .env à la racine du projet et ajoutez les lignes suivantes :

Ainsi, nous pouvons importer ces variables à l'aide du paquetage dotenv.

Créer un fichier server.js:

Ce code met en place un serveur Express.js de base qui écoute sur le port 3000 et se connecte à un cluster Elasticsearch en utilisant une clé API pour l'authentification. Il comprend un point d'extrémité /ping qui, lorsqu'on y accède par une requête GET, interroge le cluster Elasticsearch pour obtenir des informations de base à l'aide de la méthode .info() du client Elasticsearch. 

Si la requête aboutit, elle renvoie les informations sur le cluster au format JSON ; dans le cas contraire, elle renvoie un message d'erreur. Le serveur utilise également un intergiciel d'analyseur de corps pour traiter les corps de requête JSON.

Exécutez le fichier pour lancer le serveur :

node server.js

La réponse devrait ressembler à ceci :

Et maintenant, consultons le point de terminaison /ping pour vérifier l'état de notre cluster Elasticsearch.

Indexation des documents

Une fois connectés, nous pouvons indexer les documents à l'aide de mappings tels que semantic_text pour la recherche sémantique et text pour les requêtes en texte intégral. Avec ces deux types de champs, nous pouvons également effectuer une recherche hybride.

Nous allons créer un nouveau fichier load.js pour générer les correspondances et télécharger les documents.

Client Elasticsearch

Nous devons d'abord instancier et authentifier le client :

Correspondances sémantiques

Nous allons créer un index contenant des données sur un hôpital vétérinaire. Nous stockons les informations concernant le propriétaire, l'animal et les détails de la visite.

Les données sur lesquelles nous voulons effectuer une recherche en texte intégral, telles que les noms et les descriptions, seront stockées sous forme de texte. Les données des catégories, telles que l'espèce ou la race de l'animal, seront stockées sous forme de mots-clés.

En outre, nous copierons les valeurs de tous les champs dans un champ semantic_text afin de pouvoir effectuer une recherche sémantique sur ces informations également.

Aide en vrac

Un autre avantage du client est qu'il est possible d'utiliser l'assistant de masse pour indexer par lots. L'assistant de masse nous permet de gérer facilement des choses comme la concurrence, les tentatives, et ce qu'il faut faire avec chaque document qui passe par la fonction et qui réussit ou échoue.

L'une des caractéristiques intéressantes de cette aide est qu'elle permet de travailler avec des flux. Cette fonction vous permet d'envoyer un fichier ligne par ligne au lieu de stocker le fichier complet dans la mémoire et de l'envoyer à Elasticsearch en une seule fois.

Pour télécharger les données vers Elasticsearch, créez un fichier appelé data.ndjson à la racine du projet et ajoutez les informations ci-dessous (vous pouvez également télécharger le fichier avec le jeu de données à partir d'ici) :

Nous utilisons split2 pour streamer les lignes de fichiers pendant que l'assistant bulk les envoie à Elasticsearch.

Le code ci-dessus lit un fichier .ndjson ligne par ligne et indexe en bloc chaque objet JSON dans un index Elasticsearch spécifié à l'aide de la méthode helpers.bulk. Il diffuse le fichier en utilisant createReadStream et split2, met en place des métadonnées d'indexation pour chaque document et enregistre tous les documents qui ne sont pas traités. Une fois l'opération terminée, il enregistre le nombre d'éléments indexés avec succès.

En lieu et place de la fonction indexData, vous pouvez télécharger le fichier directement via l'interface utilisateur à l'aide de Kibana et utiliser l'interface utilisateur de téléchargement des fichiers de données.

Nous exécutons le fichier pour télécharger les documents vers notre cluster Elasticsearch.

node load.js

Recherche de données dans Elasticsearch

En revenant à notre fichier server.js, nous allons créer différents points de terminaison pour effectuer une recherche lexicale, sémantique ou hybride.

En résumé, ces types de recherche ne s'excluent pas mutuellement, mais dépendent du type de question à laquelle vous devez répondre.

Type de requête

Cas d'utilisation

Exemple de question

Requête lexicale

Les mots ou racines de mots de la question sont susceptibles d'apparaître dans les documents de l'index. Similitude des jetons entre la question et les documents.

Je cherche un t-shirt de sport bleu.

Requête sémantique

Les mots de la question ne sont pas susceptibles de figurer dans les documents. Similitude conceptuelle entre la question et les documents.

Je cherche des vêtements pour le froid.

Recherche hybride

La question contient des éléments lexicaux et/ou sémantiques. Similitude toxique et sémantique entre les questions et les documents.

Je cherche une robe taille S pour un mariage sur la plage.

Les parties lexicales de la question sont susceptibles de faire partie de titres et de descriptions, ou de noms de catégories, tandis que les parties sémantiques sont des concepts liés à ces domaines. Le bleu sera probablement un nom de catégorie ou une partie de la description, et le mariage à la plage ne le sera probablement pas, mais il peut être sémantiquement lié aux vêtements en lin.

Requête lexicale (/search/lexic?q=<query_term>)

La recherche lexicale, également appelée recherche en texte intégral, consiste à effectuer une recherche basée sur la similarité des mots-clés, c'est-à-dire qu'après une analyse, les documents qui contiennent les mots-clés de la recherche seront renvoyés.

Vous pouvez consulter notre tutoriel pratique sur la recherche lexicale ici.

Nous testons avec : coupe-ongles

Réponse :

Requête sémantique (/search/semantic?q=<query_term>)

La recherche sémantique, contrairement à la recherche lexicale, permet de trouver des résultats similaires à la signification des termes de recherche par le biais d'une recherche vectorielle.

Vous pouvez consulter notre tutoriel pratique sur la recherche sémantique ici.

Nous testons avec : Qui s'est fait faire une pédicure ?

Réponse :

Requête hybride (/search/hybrid?q=<query_term>)

La recherche hybride nous permet de combiner la recherche sémantique et la recherche lexicale, et d'obtenir ainsi le meilleur des deux mondes : vous bénéficiez de la précision de la recherche par jeton, ainsi que de la proximité de sens de la recherche sémantique.

Nous testons avec "Qui a reçu une pédicure ou un traitement dentaire ?"

Réponse :

Conclusion

Dans cette première partie de notre série, nous avons expliqué comment configurer notre environnement et créer un serveur avec différents points de terminaison de recherche pour interroger les documents Elasticsearch en suivant les meilleures pratiques client/serveur. Consultez la deuxième partie de notre série, dans laquelle vous découvrirez les meilleures pratiques de production et comment exécuter le client Elasticsearch Node.js dans des environnements sans serveur.