Jeffrey Rengifo - Elasticsearch Labs

Comment mesurer et améliorer le rappel de recherche Elasticsearch : de 0,43 à 0,75 avec la recherche hybride

Jeffrey Rengifo — Mon, 04 May 2026 00:00:00 GMT

La recherche lexicale utilisant l’algorithme de classement BM25 est peu coûteuse, rapide et très efficace pour de nombreuses requêtes. Mais elle présente un inconvénient : les requêtes qui ne partagent pas de jetons avec vos documents. Dans cet article, vous allez mesurer exactement les points faibles de la BM25. Nous utiliserons l’API d’évaluation de classement (rank_eval) d’Elasticsearch et comblerons cet écart en ajoutant des embeddings Jina AI via Elastic Inference Service (EIS). Vous verrez le score de rappel passer de 0.43 à 0.75 et vous comprendrez pourquoi.

Qu'est-ce que le rappel ?

Le rappel mesure, sur une échelle allant de 0 à 1, le nombre de documents réellement souhaités par vos utilisateurs qui apparaissent quelque part dans vos résultats de recherche. Si une requête doit faire apparaître trois produits et que votre recherche ne renvoie que deux d’entre eux dans le top 10, recall@10 = 0.67 pour cette requête. C’est une métrique basée sur des ensembles : la position des documents pertinents dans ces k résultats n’a pas d’importance. Un document pertinent en position 10 compte autant qu’un document en position 1. Un taux de rappel élevé signifie que vous ne perdez pas de résultats pertinents.

Le diagramme montre deux ensembles : tous les documents pertinents (à gauche) et ce que BM25 a réellement récupéré (les 10 premiers, à droite). Seules les intersections comptent pour le rappel, prod_1 et prod_2 ont été trouvés, tandis que prod_3, prod_4 et prod_6 ont été totalement manqués. Résultat : Recall@10 = 2/5 = 0.40.

Produits requis

Entrons dans le vif du sujet pour mieux comprendre le fonctionnement du rappel. Cette démonstration utilise Python. Vous pouvez la suivre dans le cahier d’accompagnement (notebook.ipynb), où chaque bloc de code est une cellule prête à être exécutée.

Le code fourni utilise les éléments suivants :

Elasticsearch 9.3+
Python 3.10+

pip install elasticsearch pandas plotly python-dotenv

Un fichier .env avec vos identifiants Elasticsearch

ELASTICSEARCH_URL=https://your-cluster-url ELASTICSEARCH_API_KEY=your-api-key

L’ensemble de données

Nous utiliserons un catalogue de produits de 1 000 articles, couvrant des catégories telles que les chaussures, l’électronique, les outils, et bien d’autres.

Chaque document comporte quatre champs :

Champ

Type

`title`

Texte

description

Texte

marque

mot-clé

Catégorie

mot-clé

L’ensemble de données est chargé à partir de dataset.csv.

La puissance et les limites de la recherche lexicale

BM25 est l’algorithme de classement par défaut d’Elasticsearch et de la plupart des moteurs de recherche. Il attribue des scores aux documents en fonction de la fréquence d’apparition de vos termes de requête dans ceux-ci, ajustée en fonction de la longueur du document et de la fréquence de ces termes dans l’ensemble de l’index. Vous disposez d’analyseurs en plus : normalisation des minuscules, troncature et suppression des mots vides. Une requête pour « chaussures de course » correspondra à « Chaussures de course » et probablement aussi à « courir ».

Cette méthode fonctionne bien pour une grande catégorie de requêtes :

« chaussures de course » associe immédiatement les produits dont le titre correspond exactement à ces termes.
L’expression « enceinte Bluetooth » fait apparaître des produits audio portables, car les termes apparaissent tels quels.

Les résultats sont déterministes et explicables : un document est bien classé parce que les termes de la requête y apparaissent. La pertinence du débogage est simple.

Les cas d’échec

Essayons maintenant ces requêtes sur le même catalogue :

« Routine de soins de la peau » : Le mot « routine » n’apparaît dans aucun titre de produit. BM25 peut correspondre partiellement à la requête « soins de la peau », mais les sérums pour le visage, les huiles corporelles et les crèmes hydratantes sont décrits à l’aide de termes comme « vitamine C », « rétinol » ou « éclaircissant », dont aucun ne correspond à la requête. Les produits qui forment une routine de soins de la peau complète sont dispersés dans l’index sans aucun élément commun permettant de les regrouper.

ID: B06XX6DS3P, Score: 9.0552, Title: Replenix Retinol Smooth + Tighten Body Lotion - Collagen-Boosting, Regenerating Anti-Aging Body Cream, Reduces Appearance of Stretch Marks, 6.7 oz. ID: B08XMPKJ1L, Score: 5.2699, Title: Bio-Oil Skincare Body Oil (Natural) Serum for Scars and Stretchmarks, Face and Body Moisturizer Hydrates Skin, with Organic Jojoba Oil and Vitamin E, For All Skin Types, 6.7 oz ID: B01CY764KQ, Score: 5.0057, Title: Nike Up Or Down Men Deodorant - Pack of 2 | Long-Lasting Fragrance, Body Spray Combo for Men | Deodorant for Active Living | Nike Men's Deo Set | Ultimate Odor Protection | Grooming Essentials | Signature Nike Scent | High-Performance Men's Deodorant

« Accessoires de voyage pour animaux de compagnie » : il s’agit d’un regroupement de cas d’utilisation, et non d’une catégorie de produits. Un sac kangourou pour chien, un siège auto pour animal et une caisse de voyage sont tous pertinents, mais leurs descriptions parlent de portabilité, de sécurité et de confort plutôt que d’« accessoires de voyage ». BM25 trouve des correspondances pour le terme « animal de compagnie » au sens large, mais ne comporte aucun signal permettant de distinguer les produits spécifiques aux voyages du reste du catalogue pour animaux de compagnie.

ID: B0BVV7BKTW, Score: 7.4371, Title: Large Foldable Travel Duffel Bag with Shoes Compartment ID: B07TNPHYNV, Score: 6.6455, Title: 40 Pieces Christmas Bronze Jingle Bells Craft Small Bells ID: B08R8FRW53, Score: 6.6335, Title: CUBY Dog and Cat Sling Carrier ID: B08QMCQYGM, Score: 6.5259, Title: YTFGGY Whiteboard Pinstripe Tape 6 Rolls 1/8" ID: B0CP3LQSWM, Score: 6.2994, Title: Portable Dog Water Bottle 32 Oz

Il s'agit d'un problème de rappel. Les documents pertinents se trouvent dans votre index. BM25 ne peut tout simplement pas les trouver car les mots de l'utilisateur et les mots du document ne correspondent pas suffisamment étroitement.

L'ajout de synonymes est utile pour les cas connus. Mais vous ne pouvez pas énumérer toutes les façons dont un utilisateur pourrait exprimer une intention. C'est là que les vecteurs entrent en jeu.

Pourquoi il est conseillé de mesurer le rappel

Avant de résoudre un problème, il faut le quantifier.

Recall@k mesure combien de documents vos utilisateurs souhaitent réellement voir apparaître dans vos résultats de recherche. Au sens strict :

Recall@k = (relevant documents found in top k) / (total relevant documents)

Precision@k mesure les k premiers résultats et combien sont réellement pertinents :

Precision@k = (relevant documents in top k) / k

Une grande précision garantit la qualité des résultats obtenus. Dans le commerce électronique, l’absence d’un produit pertinent (faible taux de rappel) est souvent pire que l’affichage d’un résultat légèrement imparfait (précision moindre), car un produit caché est une vente perdue.

L’API d’Elasticsearch rank_eval vous permet de mesurer les deux de manière systématique. Vous fournissez une liste de requêtes, chacune avec un ensemble de documents évalués, et Elasticsearch calcule les métriques pour vous pour l’ensemble des requêtes.

Configuration de l'évaluation

L’API rank_eval nécessite un ensemble de données d’évaluations : un mappage des requêtes vers les documents pertinents pour chacune d’elles, accompagné d’un grade de pertinence (0 = non pertinent, 1 = pertinent, 2 = très pertinent).

Dans le cahier, il s’agit de la liste des jugements :

judgments = [ # Query 1: "running shoes" BM25 handles well (tokens appear in product titles) {"query_id": "q1", "doc_id": "B09NQJFRW6", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B08JMD4LMM", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B08VRJ6F2Q", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B07S8NRRWR", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B01HD620I8", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B07DX86321", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B0968YVLQ8", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B093QJ39ZS", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B096FGSC39", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B01GVQWVV2", "grade": 1, "query": "running shoes"}, # Query 2: "skincare routine" intent-based, "routine" never appears in product titles {"query_id": "q2", "doc_id": "B08XMPKJ1L", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B0BN3WQB92", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B0BT7B7P5T", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B00NPA2WEY", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B06XX6DS3P", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B07PDRD1KT", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B074J7869B", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B08JV31QW4", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B00K3TVJMQ", "grade": 1, "query": "skincare routine"}, # Query 3: "study desk setup" intent-based, products are desks/stands/organizers {"query_id": "q3", "doc_id": "B08CS35J2T", "grade": 2, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B09B3LFDXJ", "grade": 2, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B07W58LMND", "grade": 1, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B0CHYDX91L", "grade": 1, "query": "study desk setup"}, # Query 4: "pet travel accessories" use-case grouping, products are carriers/crates/seats {"query_id": "q4", "doc_id": "B08R8FRW53", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B01MYUYX33", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B003C5RKE4", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B09GF8GBF6", "grade": 1, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B0CP3LQSWM", "grade": 1, "query": "pet travel accessories"}, ]

Le mélange est intentionnel : q1 est une requête que BM25 gère bien (jetons exacts dans les titres des produits), tandis que q2, q3, et q4 sont des requêtes basées sur l’intention où l’intention de l’utilisateur est exprimée sous forme de concept plutôt que de mots-clés spécifiques sur les produits.

Mesurer le rappel de référence du BM25

Commencez par configurer le client Elasticsearch et indexez les données textuelles brutes :

import os import json import pandas as pd import plotly.graph_objects as go from elasticsearch import Elasticsearch, helpers from dotenv import load_dotenv load_dotenv() es = Elasticsearch( os.getenv("ELASTICSEARCH_URL"), api_key=os.getenv("ELASTICSEARCH_API_KEY") ) INDEX_NAME = "ecommerce-products"

Maintenant, créez la requête rank_eval pour BM25. Chaque requête dans la liste combine une requête avec ses notations :

judgments_df = pd.DataFrame(judgments) bm25_requests = [] for query_id, query_text in ( judgments_df[["query_id", "query"]].drop_duplicates().values ): relevant_docs = judgments_df[judgments_df["query_id"] == query_id] ratings = [ {"_index": INDEX_NAME, "_id": row["doc_id"], "rating": row["grade"]} for _, row in relevant_docs.iterrows() ] bm25_requests.append({ "id": query_id, "request": { "query": { "multi_match": { "query": query_text, "fields": ["title", "description"] } } }, "ratings": ratings, }) bm25_eval = { "requests": bm25_requests, "metric": {"recall": {"k": 10, "relevant_rating_threshold": 1}}, } bm25_result = es.rank_eval(index=INDEX_NAME, body=bm25_eval) print("BM25 Recall@10:", bm25_result.body["metric_score"])

Voici le résultat.

BM25 Recall@10: 0.43

0.43 Signifie que sur l’ensemble des quatre requêtes, BM25 ne trouve que 43 % des documents qu’il devrait trouver. Le problème se situe principalement dans les requêtes basées sur l’intention : « routine de soins de la peau » ne trouve pas les sérums pour le visage et les huiles corporelles car le mot « routine » n’apparaît jamais dans les titres des produits, et « accessoires de voyage pour animaux de compagnie » renvoie des produits pour animaux de compagnie hors sujet tout en ne trouvant pas les cages et les caisses de transport dont la description précise les fonctionnalités de portabilité et de sécurité plutôt que d’« accessoires de voyage ».

Ceci est notre référence. Nous avons maintenant un chiffre à battre.

Ajout de la recherche vectorielle avec les embeddings Jina

Vector search encode les documents et les requêtes sous forme de vecteurs de grande dimension, composés de centaines ou de milliers de valeurs numériques, chacune encodant une fonctionnalité spécifique des données représentées. Les documents ayant une signification similaire se retrouvent proches les uns des autres dans l’espace vectoriel, même s’ils ne partagent aucun mot. « Équipement de gym » et « kit d’haltères » seront proches l’un de l’autre, car les concepts sont liés. J’ai choisi Elasticsearch comme base vectorielle, car il prend en charge la recherche hybride, ce qui me permet de bénéficier d'emblée à la fois d’une compréhension sémantique et d’une précision par mot-clé.

EIS inclut une prise en charge prête à l’emploi pour l’intégration de modèles via son API d’inférence.

Étape 1 : utiliser les embeddings Jina v5 comme point de terminaison d’inférence

INFERENCE_ENDPOINT_ID = ".jina-embeddings-v5-text-small"

Si votre cluster dispose de ressources GPU (disponibles dans Elastic Cloud et Elasticsearch 9.3+), les embeddings sont générés sur GPU, ce qui est nettement plus rapide que l’inférence CPU, et supprime le compromis de performance qui rendait auparavant l’utilisation des vecteurs coûteuses à grande échelle.

Pourquoi spécifiquement les embeddings Jina ? jina-embeddings-v5-text est un modèle multilingue (plus de 119 langues) avec une fenêtre de contexte de 32 000 jetons et une prise en charge des adaptateurs Low-Rank Adaptation (LoRA) spécifiques à la tâche. Il fonctionne bien pour les courtes descriptions de produits prêtes à l’emploi. En savoir plus sur le modèle jina-embeddings-v5-text ici.

Étape 2 : créer l’index avec un champ sémantique

index_mappings = { "mappings": { "properties": { "title": {"type": "text", "copy_to": "semantic_field"}, "description": {"type": "text", "copy_to": "semantic_field"}, "brand": {"type": "keyword"}, "category": {"type": "keyword"}, "semantic_field": { "type": "semantic_text", "inference_id": INFERENCE_ENDPOINT_ID, }, } } } if not es.indices.exists(index=INDEX_NAME): es.indices.create(index=INDEX_NAME, body=index_mappings) print(f"Created index: {INDEX_NAME}")

Le type de champ semantic_text est ici la clé. C’est une abstraction de niveau supérieur par rapport à dense_vector : vous le dirigez vers un point de terminaison d’inférence, et Elasticsearch se charge de générer automatiquement les plongements.

La propriété copy_to sur title et description signifie que le contenu des deux champs est transmis à semantic_field pour intégration, de sorte qu’un seul vecteur capture la représentation complète du produit.

Étape 3 : indexer les produits

def bulk_index(products, index_name): actions = [] for product in products: doc_id = product.get("_id") source = {k: v for k, v in product.items() if k != "_id"} action = {"_index": index_name, "_source": source} if doc_id: action["_id"] = doc_id actions.append(action) success, failed = helpers.bulk(es, actions, raise_on_error=False) if failed: for error in failed: print(f"Error: {error}") else: print(f"Successfully indexed {success} documents") bulk_index(products, INDEX_NAME)

Au moment de l’indexation, Elasticsearch appelle le point de terminaison d’inférence pour chaque document et stocke le vecteur d’intégration résultant dans semantic_field. Aucun code supplémentaire n’est nécessaire de votre côté.

Recherche hybride : combinaison de BM25 et de vecteurs avec RRF

L'ajout de vecteurs améliore le taux de rappel, mais le recours exclusif aux vecteurs risque d'entraîner une perte de précision pour les requêtes en correspondance exacte. Les résultats pour « chaussures de course » devraient toujours classer en premier les correspondances exactes. La recherche hybride conserve la composante lexicale spécifiquement pour préserver cette précision.

La recherche hybride avec la Fusion des rangs réciproques (RRF) combine le meilleur des deux :

BM25 gère les requêtes exactes et quasi-exactes avec une grande précision.
La recherche sémantique gère les requêtes basées sur l’intention et multilingues avec un rappel élevé.
RRF fusionne les deux listes classées en un seul classement.

La formule RRF attribue à chaque document un score basé sur son classement dans chaque liste de résultats :

score = sum(1 / (rank_constant + rank))

Un document bien classé dans les deux listes obtient un score combiné plus élevé. Le paramètre rank_constant détermine le poids attribué aux documents moins bien classés.

hybrid_requests = [] for query_id, query_text in ( judgments_df[["query_id", "query"]].drop_duplicates().values ): relevant_docs = judgments_df[judgments_df["query_id"] == query_id] ratings = [ {"_index": INDEX_NAME, "_id": row["doc_id"], "rating": row["grade"]} for _, row in relevant_docs.iterrows() ] hybrid_requests.append({ "id": query_id, "request": { "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "multi_match": { "query": query_text, "fields": ["title", "description"], } } } }, { "standard": { "query": { "match": { "semantic_field": {"query": query_text} } } } }, ], "rank_window_size": 50, "rank_constant": 5, } } }, "ratings": ratings, }) hybrid_eval = { "requests": hybrid_requests, "metric": {"recall": {"k": 10, "relevant_rating_threshold": 1}}, } hybrid_result = es.rank_eval(index=INDEX_NAME, body=hybrid_eval) print("Hybrid Recall@10:", hybrid_result.body["metric_score"])

Voici le résultat.

Hybrid Recall@10: 0.75

Hybrid s’améliore nettement par rapport à BM25 (0.43) et préserve la précision des requêtes de correspondance exacte, comme « chaussures de course ».

Résultats : avant et après

Voici un comparatif complet des trois approches :

methods = { "BM25 (Lexical)": bm25_requests, "Hybrid (BM25 + Vectors)": hybrid_requests, } recall_metric = {"recall": {"k": 10, "relevant_rating_threshold": 1}} comparison_data = [] for method_name, requests in methods.items(): result = es.rank_eval( index=INDEX_NAME, body={"requests": requests, "metric": recall_metric} ) comparison_data.append({ "method": method_name, "recall@10": result.body["metric_score"] }) comparison_df = pd.DataFrame(comparison_data) print(comparison_df.to_string(index=False))

Voici le résultat.

Méthode

Recall@10

BM25 (Lexical)

0,43

Hybride (BM25 + vecteurs)

0,75

Répartition des données par requête :

Conclusion

Tout au long de cet article, nous avons vu que la recherche lexicale BM25 est fiable lorsque les utilisateurs tapent des requêtes exactes, mais qu’elle perd en rappel lorsqu’ils recherchent par intention plutôt que par mots-clés. En utilisant rank_eval, nous avons établi une base reproductible pour mesurer cet écart avec des nombres réels. Ensuite, nous avons ajouté un champ semantic_text alimenté par les embeddings Jina et relancé l’évaluation. Le résultat : la recherche hybride a amélioré le rappel de 0.43 à 0.75, tout en préservant la précision des requêtes à correspondance exacte, bien que la marge réelle dépende de la composition de vos requêtes.

Le modèle s’étend au-delà de cet exemple : collectez les jugements à partir des requêtes réelles de vos utilisateurs, exécutez rank_eval comme référence, ajoutez semantic_text, puis mesurez à nouveau. Vous saurez exactement ce qui s’est amélioré et de combien.

Étapes suivantes

Découvrez la recherche de rappel et de recherche vectorielle : quantification du rappel et de la recherche vectorielle par Jeff Vestal
Ajoutez le reclassement pour une précision encore meilleure sur les meilleurs résultats
Consultez la documentation sur la recherche hybride avec Elasticsearch
En savoir plus sur rank_evall’API

Création d'un serveur Elasticsearch MCP avec TypeScript

Jeffrey Rengifo — Fri, 27 Mar 2026 00:00:00 GMT

Lorsque vous travaillez avec de grandes bases de connaissances dans Elasticsearch, trouver des informations n’est que la moitié du travail. Les ingénieurs ont souvent besoin de synthétiser des résultats issus de plusieurs documents, de générer des résumés et de faire remonter les réponses à leur source. Model Context Protocol (MCP) fournit un moyen standardisé de connecter Elasticsearch à des applications alimentées par des grands modèles de langage (LLM) afin d’y parvenir. Bien qu’Elastic propose des solutions officielles, comme Elastic Agent Builder (qui inclut un point de terminaison MCP parmi ses fonctionnalités), la création d’un serveur MCP personnalisé vous offre un contrôle total sur la logique de recherche, la mise en forme des résultats et la manière dont le contenu récupéré est transmis à un LLM pour la synthèse, les résumés et les citations.

Dans cet article, nous examinerons les avantages de la création d’un serveur MCP Elasticsearch personnalisé et expliquerons comment en créer un en TypeScript pour connecter Elasticsearch aux applications alimentées par des modèles LLM.

Pourquoi créer un serveur Elasticsearch MCP personnalisé ?

Elastic propose quelques alternatives pour les serveurs MCP :

Si vous avez besoin de plus de contrôle sur la façon dont votre serveur MCP interagit avec Elasticsearch, la création de votre propre serveur personnalisé vous donne la flexibilité de l'adapter exactement à vos besoins. Par exemple, le point de terminaison MCP d'Agent Builder est limité aux requêtes du langage de requête Elasticsearch (ES|QL), tandis qu'un serveur personnalisé vous permet d'utiliser le langage de requête DSL complet. Vous gagnez également le contrôle sur la façon dont les résultats sont formatés avant d'être transmis au LLM et pouvez intégrer des étapes de traitement supplémentaires, comme la summarisation alimentée par OpenAI que nous mettrons en œuvre dans ce tutoriel.

À la fin de cet article, vous aurez un serveur MCP dans TypeScript qui recherche les informations stockées dans un index Elasticsearch, les résume et fournit des citations. Nous utiliserons Elasticsearch pour la récupération, le modèle gpt-4o-mini d'OpenAI pour résumer et générer des citations, et Claude Desktop comme client MCP et interface utilisateur pour recevoir les requêtes des utilisateurs et fournir des réponses. Le résultat final est un assistant de connaissances interne qui aide les ingénieurs à découvrir et à synthétiser les bonnes pratiques dans l'ensemble de la documentation technique de leur organisation.

Produits requis

Node.js 20 +
Elasticsearch
Clé API OpenAI
Claude Desktop

Qu'est-ce que le MCP ?

MCP est une norme ouverte, créée par Anthropic, qui fournit des connexions bidirectionnelles sécurisées entre les LLM et les systèmes externes, comme Elasticsearch. Vous pouvez en savoir plus sur l'état actuel du MCP dans cet article.

Le paysage des MCP évolue chaque jour, avec des serveurs disponibles pour un large éventail de cas d'utilisation. De plus, il est facile de créer votre propre serveur MCP personnalisé, comme nous le montrerons dans cet article.

Clients MCP

Il existe une longue liste de clients MCP disponibles, chacun ayant ses propres caractéristiques et limitations. Par souci de simplicité et de popularité, nous utiliserons Claude Desktop comme client MCP. Il servira d'interface de chat où les utilisateurs pourront poser des questions en langage naturel, et il invoquera automatiquement les outils exposés par notre serveur MCP pour rechercher des documents et générer des résumés.

Créer un serveur Elasticsearch MCP

Grâce au SDK TypeScript, nous pouvons facilement créer un serveur qui comprend comment interroger nos données Elasticsearch à partir d'une requête utilisateur.

Voici les étapes dans cet article pour intégrer le serveur Elasticsearch MCP avec le client Claude Desktop :

Configurez le serveur MCP pour Elasticsearch

Pour commencer, initialisons une application Node :

npm init -y

Cela créera un fichier package.json, et avec lui, nous pourrons commencer à installer les dépendances nécessaires pour cette application.

npm install @elastic/elasticsearch @modelcontextprotocol/sdk openai zod && npm install --save-dev ts-node @types/node typescript

@elastic/elasticsearch nous donnera accès à la bibliothèque de Node.js Elasticsearch.
@modelcontextprotocol/sdk fournit les outils du noyau pour créer et gérer un serveur MCP, enregistrer les outils et gérer la communication avec les clients MCP.
OpenAI permet d'interagir avec les modèles OpenAI pour générer des résumés ou des réponses en langage naturel.
ZODaide à définir et valider des schémas structurés pour les données d’entrée et de sortie dans chaque outil.

ts-node, @types/node et typescript seront utilisés pendant le développement pour écrire le code et compiler les scripts.

Configurer l’ensemble de données

Pour fournir les données que Claude Desktop peut interroger via notre serveur MCP, nous utiliserons un ensemble de données simulé de base de connaissances interne. Voici à quoi ressemblera un document issu de cet ensemble de données :

{ "id": 5, "title": "Logging Standards for Microservices", "content": "Consistent logging across microservices helps with debugging and tracing. Use structured JSON logs and include request IDs and timestamps. Avoid logging sensitive information. Centralize logs in Elasticsearch or a similar system. Configure log rotation to prevent storage issues and ensure logs are searchable for at least 30 days.", "tags": ["logging", "microservices", "standards"] }

Pour ingérer les données, nous avons préparé un script qui crée un index dans Elasticsearch et y charge l’ensemble de données. Vous pouvez le trouver ici.

Serveur MCP

Créez un fichier nommé index.ts et ajoutez le code suivant pour importer les dépendances et gérer les variables d’environnement :

// index.ts import { z } from "zod"; import { Client } from "@elastic/elasticsearch"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import OpenAI from "openai"; const ELASTICSEARCH_ENDPOINT = process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200"; const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? ""; const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? ""; const INDEX = "documents";

Aussi, initialisons les clients pour gérer les appels Elasticsearch et OpenAI :

const openai = new OpenAI({ apiKey: OPENAI_API_KEY, }); const _client = new Client({ node: ELASTICSEARCH_ENDPOINT, auth: { apiKey: ELASTICSEARCH_API_KEY, }, });

Pour rendre notre implémentation plus robuste et garantir des entrées et des sorties structurées, nous définirons des schémas en utilisant zod. Cela nous permet de valider les données au moment de l'exécution, de détecter les erreurs tôt et de rendre les réponses des outils plus faciles à traiter de manière programmatique :

const DocumentSchema = z.object({ id: z.number(), title: z.string(), content: z.string(), tags: z.array(z.string()), }); const SearchResultSchema = z.object({ id: z.number(), title: z.string(), content: z.string(), tags: z.array(z.string()), score: z.number(), }); type Document = z.infer; type SearchResult = z.infer;

Pour en savoir plus sur les sorties structurées, cliquez ici.

Maintenant, initialisons le serveur MCP :

const server = new McpServer({ name: "Elasticsearch RAG MCP", description: "A RAG server using Elasticsearch. Provides tools for document search, result summarization, and source citation.", version: "1.0.0", });

Définition des outils MCP

Une fois que tout est configuré, nous pouvons commencer à écrire les outils qui seront exposés par notre serveur MCP. Ce serveur expose deux outils :

search_docs: Recherche des documents dans Elasticsearch à l'aide de la recherche full-text.
summarize_and_cite: Résume et synthétise les informations provenant de documents précédemment récupérés pour répondre à la question d'un utilisateur. Cet outil ajoute également des citations faisant référence aux documents sources.

Ensemble, ces outils forment un workflow simple de « récupération puis synthèse », où un outil extrait les documents pertinents et l'autre utilise ces documents pour générer une réponse synthétisée et citée.

Format de réponse de l'outil

Chaque outil peut accepter des paramètres d'entrée arbitraires, mais il doit répondre avec la structure suivante :

Contenu : il s'agit de la réponse de l'outil dans un format non structuré. Ce champ est généralement utilisé pour renvoyer du texte, des images, de l’audio, des liens ou des plongements. Pour cette application, il sera utilisé pour renvoyer un texte formaté contenant les informations générées par les outils.
structuredContent : il s'agit d'un retour facultatif utilisé pour fournir les résultats de chaque outil dans un format structuré. Ceci est utile à des fins de programmation. Bien qu'il ne soit pas utilisé dans ce serveur MCP, il peut être utile si vous souhaitez développer d'autres outils ou traiter les résultats de manière programmée.

En gardant cette structure à l’esprit, entrons dans le vif du sujet en examinant chaque outil en détail.

Outil de recherche

Cet outil effectue une recherche full-text dans l’index Elasticsearch pour récupérer les documents les plus pertinents selon la requête de l’utilisateur. Il met en évidence les correspondances clés et offre un aperçu rapide avec des scores de pertinence.

server.registerTool( "search_docs", { title: "Search Documents", description: "Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.", inputSchema: { query: z .string() .describe("The search query terms to find relevant documents"), max_results: z .number() .optional() .default(5) .describe("Maximum number of results to return"), }, outputSchema: { results: z.array(SearchResultSchema), total: z.number(), }, }, async ({ query, max_results }) => { if (!query) { return { content: [ { type: "text", text: "Query parameter is required", }, ], isError: true, }; } try { const response = await _client.search({ index: INDEX, size: max_results, query: { bool: { must: [ { multi_match: { query: query, fields: ["title^2", "content", "tags"], fuzziness: "AUTO", }, }, ], should: [ { match_phrase: { title: { query: query, boost: 2, }, }, }, ], }, }, highlight: { fields: { title: {}, content: {}, }, }, }); const results: SearchResult[] = response.hits.hits.map((hit: any) => { const source = hit._source as Document; return { id: source.id, title: source.title, content: source.content, tags: source.tags, score: hit._score ?? 0, }; }); const contentText = results .map( (r, i) => `[${i + 1}] ${r.title} (score: ${r.score.toFixed( 2, )})\n${r.content.substring(0, 200)}...`, ) .join("\n\n"); const totalHits = typeof response.hits.total === "number" ? response.hits.total : (response.hits.total?.value ?? 0); return { content: [ { type: "text", text: `Found ${results.length} relevant documents:\n\n${contentText}`, }, ], structuredContent: { results: results, total: totalHits, }, }; } catch (error: any) { console.log("Error during search:", error); return { content: [ { type: "text", text: `Error searching documents: ${error.message}`, }, ], isError: true, }; } } );

Nous configurons fuzziness: “AUTO” pour que la tolérance aux fautes de frappe soit variable en fonction de la longueur du jeton analysé. Nous configurons également title^2 pour qu'il augmente le score des documents dont la correspondance se fait sur le champ du titre.

outil summarize_and_cite

Cet outil génère un résumé basé sur les documents récupérés lors de la recherche précédente. Il utilise le modèle gpt-4o-mini d’OpenAI pour synthétiser les informations les plus pertinentes afin de répondre à la question de l’utilisateur, en fournissant des réponses dérivées directement des résultats de recherche. Outre le résumé, il renvoie également les métadonnées de citation des documents sources utilisés.

server.registerTool( "summarize_and_cite", { title: "Summarize and Cite", description: "Summarize the provided search results to answer a question and return citation metadata for the sources used.", inputSchema: { results: z .array(SearchResultSchema) .describe("Array of search results from search_docs"), question: z.string().describe("The question to answer"), max_length: z .number() .optional() .default(500) .describe("Maximum length of the summary in characters"), max_docs: z .number() .optional() .default(5) .describe("Maximum number of documents to include in the context"), }, outputSchema: { summary: z.string(), sources_used: z.number(), citations: z.array( z.object({ id: z.number(), title: z.string(), tags: z.array(z.string()), relevance_score: z.number(), }) ), }, }, async ({ results, question, max_length, max_docs }) => { if (!results || results.length === 0 || !question) { return { content: [ { type: "text", text: "Both results and question parameters are required, and results must not be empty", }, ], isError: true, }; } try { const used = results.slice(0, max_docs); const context = used .map( (r: SearchResult, i: number) => `[Document ${i + 1}: ${r.title}]\\n${r.content}` ) .join("\n\n---\n\n"); // Generate summary with OpenAI const completion = await openai.chat.completions.create({ model: "gpt-4o-mini", messages: [ { role: "system", content: "You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.", }, { role: "user", content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`, }, ], max_tokens: Math.min(Math.ceil(max_length / 4), 1000), temperature: 0.3, }); const summaryText = completion.choices[0]?.message?.content ?? "No summary generated."; const citations = used.map((r: SearchResult) => ({ id: r.id, title: r.title, tags: r.tags, relevance_score: r.score, })); const citationText = citations .map( (c: any, i: number) => `[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join( ", ", )}, Score: ${c.relevance_score.toFixed(2)}`, ) .join("\n"); const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`; return { content: [ { type: "text", text: combinedText, }, ], structuredContent: { summary: summaryText, sources_used: citations.length, citations: citations, }, }; } catch (error: any) { return { content: [ { type: "text", text: `Error generating summary and citations: ${error.message}`, }, ], isError: true, }; } } );

Enfin, il faut démarrer le serveur avec stdio. Cela signifie que le client MCP communiquera avec notre serveur en lisant et en écrivant dans ses flux d'entrée et de sortie standard. StDIO est l’option de transport la plus simple et fonctionne bien pour les serveurs MCP locaux lancés en sous-processus par le client. Ajoutez le code suivant à la fin du fichier :

const transport = new StdioServerTransport(); server.connect(transport);

Compilez le projet en utilisant la commande suivante :

npx tsc index.ts --target ES2022 --module node16 --moduleResolution node16 --outDir ./dist --strict --esModuleInterop

Cela créera un dossier dist, dans lequel se trouvera un fichier index.js.

Chargez le serveur MCP dans Claude Desktop.

Suivez ce guide pour configurer le serveur MCP avec Claude Desktop. Dans le fichier de configuration Claude, nous devons définir les valeurs suivantes :

{ "mcpServers": { "elasticsearch-rag-mcp": { "command": "node", "args": [ "/Users/user-name/app-dir/dist/index.js" ], "env": { "ELASTICSEARCH_ENDPOINT": "your-endpoint-here", "ELASTICSEARCH_API_KEY": "your-api-key-here", "OPENAI_API_KEY": "your-openai-key-here" } } } }

La valeur args doit pointer vers le fichier compilé dans le dossier dist . Vous devez également définir les variables d'environnement dans le fichier de configuration avec les noms exacts définis dans le code.

Testez-le

Avant d’exécuter chaque outil, cliquez sur Recherche et Outils pour vous assurer que les outils sont activés. Vous pouvez également activer ou désactiver chaque option ici :

Enfin, testons le serveur MCP depuis le chat Claude Desktop et commençons à poser des questions :

Pour la question « Recherche de documents sur les méthodes d’authentification et le contrôle d’accès basé sur les rôles », l’outil search_docs est exécuté et renvoie les résultats suivants :

Most Relevant Documents: Access Control and Role Management (highest relevance) - This document covers role-based access control (RBAC) principles, including ensuring users only have necessary permissions, regular auditing of user roles, revoking inactive accounts, and implementing just-in-time access for sensitive operations. User Authentication with OAuth 2.0 - This document explains OAuth 2.0 authentication, which enables secure delegated access without credential sharing. It covers configuring identity providers, token management with limited scope and lifetime, and secure storage of refresh tokens. Container Security Guidelines - While primarily about container security, this document touches on access control aspects like running containers as non-root users and avoiding embedded credentials. Incident Response Playbook - This mentions role assignment during incidents (incident commander, communications lead, etc.), which relates to access control in emergency scenarios. Logging Standards for Microservices - This document includes guidance on avoiding logging sensitive information, which is relevant to authentication security.

La réponse est : « Super ! J'ai trouvé 5 documents pertinents sur les méthodes d'authentification et le contrôle d'accès basé sur les rôles. Voici ce qui a été découvert : »

L'appel d'outil renvoie les documents sources dans le cadre de sa charge utile de réponse, qui sont ensuite utilisés pour générer des citations.

Il est également possible d'enchaîner plusieurs outils dans une même interaction. Dans ce cas, Claude Desktop analyse la question de l’utilisateur et détermine qu’il doit d’abord appeler search_docs pour récupérer les documents pertinents, puis transmettre ces résultats à summarize_and_cite pour générer la réponse finale, le tout sans nécessiter d’invites séparées de la part de l’utilisateur :

Dans ce cas, pour la requête « Quelles sont les principales recommandations pour améliorer l’authentification et le contrôle d’accès dans l’ensemble de nos systèmes ? Veuillez inclure des références. », Nous avons obtenu les résultats suivants :

Based on the documentation, here are the main recommendations to improve authentication and access control across your systems: Key Recommendations 1. Implement Role-Based Access Control (RBAC) Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1] 2. Regular Access Audits Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1] 3. Just-in-Time (JIT) Access Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1] 4. OAuth 2.0 for Secure Authentication Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2] 5. Token Security and Management Configure your identity provider to issue tokens with limited scope and lifetime Store refresh tokens securely Validate access tokens consistently to maintain security [2] References Access Control and Role Management (Tags: security, access-control) User Authentication with OAuth 2.0 (Tags: authentication, oauth) These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.

Comme à l’étape précédente, nous pouvons voir la réponse de chaque outil à cette question :

Note : Si un sous-menu apparaît demandant si vous approuvez l’utilisation de chaque outil, sélectionnez Toujours autoriser ou Permettre une fois.

Conclusion

Les serveurs MCP représentent une étape importante vers la standardisation des outils LLM pour les applications locales et distantes. Bien que la compatibilité totale soit encore en cours de développement, nous avançons rapidement dans cette direction.

Dans cet article, nous avons appris à créer un serveur MCP personnalisé en TypeScript qui connecte Elasticsearch aux applications basées sur LLM. Notre serveur propose deux outils : search_docs pour récupérer les documents pertinents à l'aide de Query DSL ; et summarize_and_cite pour générer des résumés avec des citations via des modèles OpenAI et Claude Desktop comme interface utilisateur client.

L'avenir de la compatibilité entre les différents fournisseurs côté client et côté serveur semble prometteur. Les prochaines étapes consistent à ajouter davantage de fonctionnalités et de flexibilité à votre agent. Vous trouverez un article pratique expliquant comment paramétrer vos requêtes à l'aide de modèles de rechercher pour gagner en précision et en flexibilité.

Utilisation de l'API d'inférence Elasticsearch avec les modèles Hugging Face

Jeffrey Rengifo — Mon, 23 Mar 2026 00:00:00 GMT

Dans ses dernières mises à jour, Elasticsearch a introduit une intégration native permettant de se connecter aux modèles hébergés sur le service d'inférence Hugging Face. Dans cet article, nous verrons comment configurer cette intégration et effectuer des inférences via de simples appels d'API à l'aide d'un grand modèle de langage (LLM). Nous utiliserons SmolLM3-3B, un modèle léger et polyvalent offrant un bon compromis entre consommation de ressources et qualité des réponses.

Produits requis

Elasticsearch 9.3 ou Elastic Cloud Serverless : vous pouvez créer un déploiement dans le cloud en suivant ces instructions, ou utiliser le démarrage rapide start-local à la place.
Python 3.12 : téléchargez Python ici.
Jeton d'accès Hugging Face.

Complétions de chat utilisant un point de terminaison d'inférence Hugging Face

Nous allons d'abord créer un exemple pratique connectant Elasticsearch à un point de terminaison d'inférence Hugging Face afin de générer des recommandations alimentées par l'IA à partir d'une collection d'articles de blog. Pour la base de connaissances de l'application, nous utiliserons un ensemble de données d'articles de blogs d'entreprise, qui contiennent des informations précieuses mais souvent difficiles à consulter.

Avec ce point de terminaison, la recherche sémantique extrait les articles les plus pertinents pour une requête donnée, et un LLM Hugging Face génère de courtes recommandations contextuelles sur la base de ces résultats.

Examinons d'abord les grandes lignes du flux d'informations que nous allons mettre en place :

Dans cet article, nous allons tester la capacité de SmolLM3-3B àà allier sa taille compacte à de puissantes fonctionnalités de raisonnement multilingue et d'appel d'outils. À partir d'une requête de recherche, nous enverrons tous les contenus correspondants (en anglais et en espagnol) au LLM afin de générer une liste d'articles recommandés, accompagnés d'une description personnalisée basée sur la requête et les résultats de recherche.

Voici à quoi pourrait ressembler l'interface utilisateur d'un site d'articles doté d'un système de génération de recommandations par IA.

Vous trouverez la mise en œuvre complète de cette application dans le notebook associé.

Configuration des points de terminaison d’inférence Elasticsearch

Pour utiliser le point de terminaison d'inférence Hugging Face d'Elasticsearch, nous avons besoin de deux éléments importants : une clé API Hugging Face et une URL de point de terminaison Hugging Face en cours d'exécution. Cela devrait ressembler à ceci :

PUT _inference/chat_completions/hugging-face-smollm3-3b { "service": "hugging_face", "service_settings": { "api_key": "hugging-face-access-token", "url": "url-endpoint" } }

Le point de terminaison d'inférence Hugging Face dans Elasticsearch prend en charge différents types de tâches : text_embedding, completion, chat_completion et rerank. Dans cet article de blog, nous utilisons chat_completion, car nous avons besoin que le modèle génère des recommandations conversationnelles basées sur les résultats de recherche et un prompt système. Ce point de terminaison nous permet d'effectuer des complétions de chat directement depuis Elasticsearch de manière simple grâce à l'API Elasticsearch :

POST _inference/chat_completion/hugging-face-smollm3-3b/_stream { "messages": [ { "role": "user", "content": "" } ] }

Ceci va constituer le cœur de l'application, recevant la requête et les résultats de recherche qui seront ensuite traités par le modèle. La théorie étant posée, passons à la mise en œuvre de l'application.

Configuration du point de terminaison d'inférence sur Hugging Face

Pour déployer le modèle Hugging Face, nous allons utiliser le service de déploiement en un clic de Hugging Face, une solution simple et rapide pour déployer des points de terminaison de modèles. Notez qu'il s'agit d'un service payant et que son utilisation peut engendrer des coûts supplémentaires. Cette étape créera l'instance du modèle qui servira à générer les recommandations d'articles.

Vous pouvez choisir un modèle dans le catalogue accessible en un clic :

Sélectionnons le modèle SmolLM3-3B :

À partir d'ici, veuillez récupérer l'URL du point de terminaison Hugging Face :

Comme indiqué dans la documentation Elasticsearch relative aux points de terminaison d'inférence Hugging Face, la génération de texte nécessite un modèle compatible avec l'API OpenAI. Pour cette raison, nous devons ajouter le sous-chemin /v1/chat/completions à à l'URL de point de terminaison Hugging Face. Le résultat final ressemblera à ceci :

https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions

Une fois ces éléments en place, nous pouvons commencer à coder dans un notebook Python.

Génération de la clé API Hugging Face

Créez un compte Hugging Face et obtenez un jeton API en suivant ces instructions. Vous avez le choix entre trois types de jetons : un jeton granulaire (recommandé pour la production, car il ne donne accès qu'à des ressources spécifiques), un jeton de lecture (pour un accès en lecture seule) ou un jeton d'écriture (pour un accès en lecture et en écriture). Pour ce tutoriel, un jeton de lecture suffit, car nous n'avons besoin d'appeler que le point de terminaison d'inférence. Enregistrez cette clé pour la prochaine étape.

Configuration du point de terminaison d'inférence Elasticsearch

Tout d'abord, déclarons un client Elasticsearch Python :

os.environ["ELASTICSEARCH_API_KEY"] = "your-elasticsearch-api-key" os.environ["ELASTICSEARCH_URL"] = "https://xxxx.us-central1.gcp.cloud.es.io:443" es_client = Elasticsearch( os.environ["ELASTICSEARCH_URL"], api_key=os.environ["ELASTICSEARCH_API_KEY"] )

Ensuite, nous allons créer un point de terminaison d'inférence Elasticsearch qui utilise le modèle Hugging Face. Ce point de terminaison nous permettra de générer des réponses en fonction des articles de blog et du prompt transmis au modèle.

INFERENCE_ENDPOINT_ID = "smollm3-3b-pnz" os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"] = ( "https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions" ) os.environ["HUGGING_FACE_API_KEY"] = "hf_xxxxx" resp = es_client.inference.put( task_type="chat_completion", inference_id=INFERENCE_ENDPOINT_ID, body={ "service": "hugging_face", "service_settings": { "api_key": os.environ["HUGGING_FACE_API_KEY"], "url": os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"], }, }, )

Ensemble de données

L'ensemble de données contient les articles de blog sur lesquels des requêtes seront exécutées ; il s'agit d'un ensemble de contenus multilingues utilisé tout au long du workflow :

// Articles dataset document example: { "id": "6", "title": "Complete guide to the new API: Endpoints and examples", "author": "Tomas Hernandez", "date": "2025-11-06", "category": "tutorial", "content": "This guide describes in detail all endpoints of the new API v2. It includes code examples in Python, JavaScript, and cURL for each endpoint. We cover authentication, resource creation, queries, updates, and deletion. We also explain error handling, rate limiting, and best practices. Complete documentation is available on our developer portal." }

Mappings Elasticsearch

Une fois l'ensemble de données défini, nous devons créer un schéma de données adapté à la structure des articles de blog. Les mappings d'index suivants seront utilisés pour stocker les données dans Elasticsearch :

INDEX_NAME = "blog-posts" mapping = { "mappings": { "properties": { "id": {"type": "keyword"}, "title": { "type": "object", "properties": { "original": { "type": "text", "copy_to": "semantic_field", "fields": {"keyword": {"type": "keyword"}}, }, "translated_title": { "type": "text", "fields": {"keyword": {"type": "keyword"}}, }, }, }, "author": {"type": "keyword", "copy_to": "semantic_field"}, "category": {"type": "keyword", "copy_to": "semantic_field"}, "content": {"type": "text", "copy_to": "semantic_field"}, "date": {"type": "date"}, "semantic_field": {"type": "semantic_text"}, } } } es_client.indices.create(index=INDEX_NAME, body=mapping)

Ici, nous pouvons voir plus clairement comment les données sont structurées. Nous utiliserons la recherche sémantique pour récupérer les résultats basés sur le langage naturel, ainsi que la propriété copy_to pour copier le contenu du champ dans le champ semantic_text. De plus, le champ title contient deux sous-champs : le sous-champ original stocke le titre en anglais ou en espagnol, selon la langue d'origine de l'article, et le sous-champ translated_title n'est présent que pour les articles en espagnol et contient la traduction anglaise du titre original.

Ingestion des données

L'extrait de code suivant ingère l'ensemble de données des articles de blog dans Elasticsearch à l'aide de l'API Bulk :

def build_data(json_file, index_name): with open(json_file, "r") as f: data = json.load(f) for doc in data: action = {"_index": index_name, "_source": doc} yield action try: success, failed = helpers.bulk( es_client, build_data("dataset.json", INDEX_NAME), ) print(f"{success} documents indexed successfully") if failed: print(f"Errors: {failed}") except Exception as e: print(f"Error: {str(e)}")

Maintenant que nous avons intégré les articles dans Elasticsearch, nous devons créer une fonction capable de rechercher dans le champ semantic_text :

def perform_semantic_search(query_text, index_name=INDEX_NAME, size=5): try: query = { "query": { "match": { "semantic_field": { "query": query_text, } } }, "size": size, } response = es_client.search(index=index_name, body=query) hits = response["hits"]["hits"] return hits except Exception as e: print(f"Semantic search error: {str(e)}") return []

Nous avons également besoin d'une fonction qui appelle le point de terminaison d'inférence. Dans ce cas, nous appellerons le point de terminaison en utilisant le type de tâche chat_completionpour obtenir des réponses en streaming :

def stream_chat_completion(messages: list, inference_id: str = INFERENCE_ENDPOINT_ID): url = f"{ELASTICSEARCH_URL}/_inference/chat_completion/{inference_id}/_stream" payload = {"messages": messages} headers = { "Authorization": f"ApiKey {ELASTICSEARCH_API_KEY}", "Content-Type": "application/json", } try: response = requests.post(url, json=payload, headers=headers, stream=True) response.raise_for_status() for line in response.iter_lines(decode_unicode=True): if line: line = line.strip() if line.startswith("event:"): continue if line.startswith("data: "): data_content = line[6:] if not data_content.strip() or data_content.strip() == "[DONE]": continue try: chunk_data = json.loads(data_content) if "choices" in chunk_data and len(chunk_data["choices"]) > 0: choice = chunk_data["choices"][0] if "delta" in choice and "content" in choice["delta"]: content = choice["delta"]["content"] if content: yield content except json.JSONDecodeError as json_err: print(f"\nJSON decode error: {json_err}") print(f"Problematic data: {data_content}") continue except requests.exceptions.RequestException as e: yield f"Error: {str(e)}"

Nous pouvons maintenant écrire une fonction qui appelle la fonction de recherche sémantique, ainsi que le point de terminaison d'inférence chat_completions et le point de terminaison de recommandations, afin de générer les données qui seront allouées dans les fiches :

def recommend_articles(search_query, index_name=INDEX_NAME, max_articles=5): print(f"\n{'='*80}") print(f"🔍 Search Query: {search_query}") print(f"{'='*80}\n") articles = perform_semantic_search(search_query, index_name, size=max_articles) if not articles: print("❌ No relevant articles found.") return None, None print(f"✅ Found {len(articles)} relevant articles\n") # Build context with found articles context = "Available blog articles:\n\n" for i, article in enumerate(articles, 1): source = article.get("_source", article) context += f"Article {i}:\n" context += f"- Title: {source.get('title', 'N/A')}\n" context += f"- Author: {source.get('author', 'N/A')}\n" context += f"- Category: {source.get('category', 'N/A')}\n" context += f"- Date: {source.get('date', 'N/A')}\n" context += f"- Content: {source.get('content', 'N/A')}\n\n" system_prompt = """You are an expert content curator that recommends blog articles. Write recommendations in a conversational style starting with phrases like: - "If you're interested in [topic], this article..." - "This post complements your search with..." - "For those looking into [topic], this article provides..." FORMAT REQUIREMENTS: - Return ONLY a JSON array - Each element must have EXACTLY these three fields: "article_number", "title", "recommendation" - If the original title is in spanish, use the "translated_title" subfield in the "title" field Keep each recommendation concise (2-3 sentences max) and focused on VALUE to the reader. EXAMPLE OF CORRECT FORMAT: [ {"article_number": 1, "title": "Article title in english", "recommendation": "If you are interested in [topic], this article provides..."}, {"article_number": 2, "title": "Article title in english", "recommendation": " for those looking into [topic], this article provides..."} ] Return ONLY the JSON array following this exact structure.""" user_prompt = f"""Search query: "{search_query}" Generate recommendations for the following articles: {context} """ messages = [ {"role": "system", "content": "/no_think"}, {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ] # LLM generation print(f"{'='*80}") print("🤖 Generating personalized recommendations...\n") full_response = "" for chunk in stream_chat_completion(messages): print(chunk, end="", flush=True) full_response += chunk return context, articles, full_response

Enfin, nous devons extraire les informations et les mettre en forme pour l'impression :

def display_recommendation_cards(articles, recommendations_text): print("\n" + "=" * 100) print("📇 RECOMMENDED ARTICLES".center(100)) print("=" * 100 + "\n") # Parse JSON recommendations - clean tags and extract JSON recommendations_list = [] try: # Clean up tags cleaned_text = re.sub( r".*?", "", recommendations_text, flags=re.DOTALL ) # Remove markdown code blocks ( ... ``` or ``` ... ```) cleaned_text = re.sub(r"```(?:json)?", "", cleaned_text) cleaned_text = cleaned_text.strip() parsed = json.loads(cleaned_text) # Extract recommendations from list format for item in parsed: article_number = item.get("article_number") title = item.get("title", "") rec_text = item.get("recommendation", "") if article_number and rec_text: recommendations_list.append( { "article_number": article_number, "title": title, "recommendation": rec_text, } ) except json.JSONDecodeError as e: print(f"⚠️ Could not parse recommendations as JSON: {e}") return for i, article in enumerate(articles, 1): source = article.get("_source", article) # Card border print("┌" + "─" * 98 + "┐") # Find recommendation and title for this article number recommendation = None title = None for rec in recommendations_list: if rec.get("article_number") == i: recommendation = rec.get("recommendation") title = rec.get("title") break # Print title title_lines = textwrap.wrap(f"📌 {title}", width=94) for line in title_lines: print(f"│ {line}".ljust(99) + "│") # Card border print("├" + "─" * 98 + "┤") # Print recommendation if recommendation: recommendation_lines = textwrap.wrap(recommendation, width=94) for line in recommendation_lines: print(f"│ {line}".ljust(99) + "│") # Card bottom print("└" + "─" * 98 + "┘")

Faisons un test en posant une question sur les articles de blog relatifs à la sécurité :

search_query = "Security and vulnerabilities" context, articles, recommendations = recommend_articles(search_query) print("\nElasticsearch context:\n", context) # Display visual cards display_recommendation_cards(articles, recommendations)

Nous pouvons voir ici les fiches générées par le workflow dans la console :

Vous trouverez les résultats complets, y compris tous les résultats et la réponse du LLM dans ce fichier.

Nous recherchons des articles portant sur le thème "Security et vulnérabilités". Cette question est utilisée comme requête de recherche sur les documents stockés dans Elasticsearch. Les résultats récupérés sont ensuite transmis au modèle, qui génère des recommandations basées sur leur contenu. Comme nous pouvons le constater, le modèle a parfaitement réussi à générer des textes courts et attrayants qui incitent le lecteur à cliquer dessus.

Conclusion

Cet exemple illustre comment combiner Elasticsearch et Hugging Face pour créer un système centralisé, rapide et performant pour les applications d'IA. Cette approche réduit les interventions manuelles et offre une grande flexibilité grâce au vaste catalogue de modèles de Hugging Face. L'utilisation de SmolLM3-3B, en particulier, montre comment des modèles multilingues compacts peuvent fournir un raisonnement pertinent et une génération de contenu efficace lorsqu'ils sont associés à la recherche sémantique. Ensemble, ces outils constituent une base scalable et performante pour le développement d'applications d'analyse de contenu intelligentes et multilingues.

Créez un workflow de recherche IA financière avec LangGraph.js et Elasticsearch

Jeffrey Rengifo — Fri, 05 Dec 2025 00:00:00 GMT

La création d'applications de recherche IA implique souvent la coordination de plusieurs tâches, la récupération et l'extraction de données dans un workflow fluide. LangGraph simplifie ce processus en permettant aux développeurs d'orchestrer les agents d'IA à l'aide d'une structure basée sur des nodes. Dans cet article, nous allons construire une solution financière en utilisant LangGraph.js.

Qu'est-ce que LangGraph ?

LangGraph est un framework pour construire des agents d’IA et les orchestrer dans un workflow afin de créer des applications assistées par l’IA. LangGraph dispose d’une architecture de nodes où nous pouvons déclarer des fonctions représentant des tâches et les assigner comme nodes du workflow. Le résultat de l'interaction de plusieurs nodes sera un graphe. LangGraph fait partie du LangChain écosystème plus large, qui fournit des outils pour construire des systèmes d'IA modulaires et composables.

Pour mieux comprendre l’utilité de LangGraph, résolvons une situation problématique en l’utilisant.

Aperçu de la solution

Dans une société de capital-risque, les investisseurs ont accès à une vaste base de données avec de nombreuses options de filtrage, mais lorsqu'ils veulent combiner des critères, cela devient difficile et lent. Il se peut donc que certaines start-ups pertinentes ne soient pas trouvées pour l'investissement. Cela conduit à passer beaucoup de temps à essayer d'identifier les meilleurs candidats, voire à perdre des opportunités.

Avec LangGraph et Elasticsearch, vous pouvez effectuer des recherches filtrées en utilisant le langage naturel, ce qui évite aux utilisateurs de devoir construire manuellement des requêtes complexes avec des dizaines de filtres. Pour plus de flexibilité, le workflow choisit automatiquement, en fonction de l'entrée de l'utilisateur, entre deux types de requêtes :

Requêtes d’investissement : elles visent les données financières et de financement des start-up, notamment les tours de table, la valorisation ou le CA. Exemple : « Trouvez des startups avec un financement de série A ou série B entre 8 millions et 25 millions de dollars et un chiffre d’affaires mensuel supérieur à 500 000 $. »
Requêtes axées sur le marché: elles se concentrent sur les secteurs d’activité, les marchés géographiques ou les modèles économiques, en aidant à identifier des opportunités dans des secteurs ou régions spécifiques. Exemple : « Trouvez des startups de la fintech et de la santé à San Francisco, New York ou Boston. »

Pour garantir la robustesse des requêtes, nous allons faire en sorte que le LLM génère des modèles de recherche au lieu de requêtes DSL complètes. De cette façon, vous obtenez toujours la requête souhaitée, et le LLM n'a qu'à compléter les informations manquantes sans avoir à élaborer la requête dont vous avez besoin à chaque fois.

Ce dont vous avez besoin pour commencer

Clé API Elasticsearch
Clé d'API OpenAPI
Node 18 ou version ultérieure

Instructions étape par étape

Dans cette section, voyons comment l'application sera présentée. Nous utiliserons TypeScript, un sur-ensemble de JavaScript qui ajoute des types statiques. Cela rend le code plus fiable, plus facile à maintenir et plus sûr en détectant les erreurs dès le début, tout en assurant une compatibilité totale avec JavaScript.

Le flux des nœuds se présentera comme suit :

L'image ci-dessus est générée par LangGraph et représente le workflow qui définit l'ordre d'exécution et la logique conditionnelle entre les nodes :

decideStrategy : utilise un LLM pour rechercher la requête de l'utilisateur et choisir entre deux stratégies de recherche spécialisées, axée sur l'investissement ou axée sur le marché.
PrepareInvestmentSearch : extrait les valeurs de filtre de la requête et crée un modèle prédéfini mettant l'accent sur les paramètres financiers et liés au financement.
PrepareMarketSearch: extrait également les valeurs des filtres, mais crée dynamiquement des paramètres en mettant l'accent sur le marché, le secteur et le contexte géographique.
ExecuteSearch : envoie la recherche construite à Elasticsearch à l'aide d'un modèle de recherche et extrait les documents de démarrage correspondants.
VisualiserResults : met en forme les résultats finaux sous la forme d'un résumé clair et lisible présentant les principaux attributs de la start-up tels que le financement, le secteur d'activité et le chiffre d'affaires.

Ce flux comprend un branchement conditionnel, fonctionnant comme une instruction « si », qui détermine s'il faut rechercher le chemin d'investissement ou de recherche de marché en fonction de l'entrée de l'utilisateur. Cette logique de décision, pilotée par le LLM, rend le workflow adaptatif et conscient du contexte, un mécanisme que nous explorerons plus en détail dans les sections suivantes.

État de LangGraph

Avant de voir chaque node individuellement, nous devons comprendre comment les nodes communiquent et partagent les données. Pour cela, LangGraph nous permet de définir l'état du workflow. Cela définit l'état partagé qui sera transmis entre les nodes.

L’état agit comme un conteneur partagé stockant les données intermédiaires du workflow : il enregistre d’abord la requête en langage naturel de l’utilisateur, puis la stratégie de recherche choisie, les paramètres prêts pour Elasticsearch, les résultats de recherche et, pour finir, le résultat formaté.

Cette architecture permet à chaque nœud de lire et de modifier l’état, ce qui garantit un flux d’informations constant, de l’entrée de l’utilisateur jusqu’à la visualisation finale.

const VCState = Annotation.Root({ input: Annotation(), // User's natural language query searchStrategy: Annotation(), // Search strategy chosen by LLM searchParams: Annotation(), // Prepared search parameters results: Annotation(), // Search results final: Annotation(), // Final formatted response });

Configurer l'application

Tout le code de cette section se trouve dans le dépôt elasticsearch-labs.

Dans le dossier où l’application sera installée, ouvrez un terminal et initialisez une application Node.js avec la commande :

npm init -y

Nous pouvons maintenant installer les dépendances nécessaires à ce projet :

npm install @elastic/elasticsearch @langchain/langgraph @langchain/openai @langchain/core dotenv zod && npm install --save-dev @types/node tsx typescript

@elastic/elasticsearch: Permet de gérer les requêtes Elasticsearch, comme l’ingestion et la récupération des données.
@langchain/langgraph: Dépendance JS pour fournir tous les outils LangGraph.
@langchain/openai: Client OpenAI LLM pour LangChain.
@langchain/core : Offre les composantes de base essentielles aux applications LangChain, notamment les modèles d’invite.
dotenv: Dépendance nécessaire pour utiliser les variables d'environnement en JavaScript.
zod: Dépendance au type de données.

@types/node tsx typescript nous permet d'écrire et d'exécution du code TypeScript.

Créez maintenant les fichiers suivants :

elasticsearchSetup.ts: Créera les mapping d'index, chargera les données à partir d'un fichier JSON, et ingérera les données dans Elasticsearch.
main.ts: inclura l’application LangGraph.
.env: fichier pour stocker les variables d’environnement

Dans le fichier .env, ajoutons les variables d’environnement suivantes :

ELASTICSEARCH_ENDPOINT="your-endpoint-here" ELASTICSEARCH_API_KEY="your-key-here" OPENAI_API_KEY="your-key-here"

La clé APIK de l'OpenAPI ne sera pas utilisée directement dans le code ; elle sera utilisée en interne par la bibliothèque @langchain/openai.

Toute la logique concernant la création de mappages, la création de modèles de recherche et l’ingestion des ensembles de données se trouve dans le fichier elasticsearchSetup.ts. Dans les prochaines étapes, nous nous concentrerons sur le fichier main.ts. Vous pouvez également consulter l'ensemble de données pour mieux comprendre l'aspect des données sur le site dataset.json.

Application LangGraph

Dans le fichier main.ts, importons certaines dépendances nécessaires pour consolider l'application LangGraph. Dans ce fichier, vous devez également inclure les fonctions node et la déclaration d’état. La déclaration du graphe sera effectuée dans une méthode main dans les prochaines étapes. Le fichier elasticsearchSetup.ts contiendra les aides Elasticsearch que nous allons utiliser dans les Nodes dans les étapes suivantes.

import { writeFileSync } from "node:fs"; import { StateGraph, Annotation, START, END } from "@langchain/langgraph"; import { ChatOpenAI } from "@langchain/openai"; import { z } from "zod"; import { esClient, ingestDocuments, createSearchTemplates, INDEX_NAME, INVESTMENT_FOCUSED_TEMPLATE, MARKET_FOCUSED_TEMPLATE, createIndex, } from "./elasticsearchSetup.js"; const llm = new ChatOpenAI({ model: "gpt-4o-mini" });

Ainsi que nous l’avons vu, le client LLM sera mobilisé pour générer les paramètres du modèle de recherche Elasticsearch en fonction de la question de l’utilisateur.

async function saveGraphImage(app: any): Promise { try { const drawableGraph = app.getGraph(); const image = await drawableGraph.drawMermaidPng(); const arrayBuffer = await image.arrayBuffer(); const filePath = "./workflow_graph.png"; writeFileSync(filePath, new Uint8Array(arrayBuffer)); console.log(`📊 Workflow graph saved as: ${filePath}`); } catch (error: any) { console.log("⚠️ Could not save graph image:", error.message); } }

La méthode ci-dessus génère l'image du graphe au format png et utilise l'API Mermaid.INK en arrière-plan. Ceci est utile si vous souhaitez voir comment les nodes de l'application interagissent dans le cadre d'une visualisation stylisée.

Nodes LangGraph

À présent, voyons chaque node en détail :

Node decideSearchStrategy

Le node decideSearchStrategy analyse les entrées de l'utilisateur et détermine s'il convient d'effectuer une rechercher axée sur les investissements ou axée sur le marché. Il utilise un LLM avec un schéma de sortie structuré (défini avec Zod) pour classer le type de requête. Avant de prendre la décision, il récupère les filtres disponibles de l'index en utilisant une agrégation, en garantissant que le modèle dispose d'un contexte à jour sur les industries, les localisations et les données de financement.

Pour extraire les valeurs possibles des filtres et les envoyer au LLM, utilisons une requête d'agrégation pour les récupérer directement depuis l'index Elasticsearch. Cette logique est allouée dans une méthode appelée getAvailableFilters:

async function getAvailableFilters() { try { const response = await esClient.search({ index: INDEX_NAME, size: 0, aggs: { industries: { terms: { field: "industry", size: 100 }, }, locations: { terms: { field: "location", size: 100 }, }, funding_stages: { terms: { field: "funding_stage", size: 20 }, }, business_models: { terms: { field: "business_model", size: 10 }, }, lead_investors: { terms: { field: "lead_investor", size: 100 }, }, funding_amount_stats: { stats: { field: "funding_amount" }, }, }, }); return response.aggregations; } catch (error) { console.error("❌ Error getting available filters:", error); return {}; } }

Avec la requête d'agrégation ci-dessus, nous avons les résultats suivants :

{ "industries": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "logistics", "doc_count": 5 }, ... ] }, "locations": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "San Francisco, CA", "doc_count": 4 }, { "key": "New York, NY", "doc_count": 3 }, ... ] }, "funding_stages": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "Series A", "doc_count": 8 }, ... ] }, "business_models": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "B2B", "doc_count": 13 }, ... ] }, "lead_investors": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "Battery Ventures", "doc_count": 1 }, { "key": "Benchmark Capital", "doc_count": 1 }, ... ] }, "funding_amount_stats": { "count": 20, "min": 4500000, "max": 35000000, "avg": 14075000, "sum": 281500000 } }

Découvrez tous les résultats ici.

Pour les deux stratégies, nous allons utiliser la recherche hybride afin de détecter à la fois la partie structurée de la question (filtres) et les parties plus subjectives (sémantique). Voici un exemple des deux requêtes utilisant des modèles de recherche :

await esClient.putScript({ id: INVESTMENT_FOCUSED_TEMPLATE, script: { lang: "mustache", source: `{ "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "{{query_text}}" } } } }, { "standard": { "query": { "bool": { "filter": [ {"terms": {"funding_stage": {{#join}}{{#toJson}}funding_stage{{/toJson}}{{/join}}}}, {"range": {"funding_amount": {"gte": {{funding_amount_gte}}{{#funding_amount_lte}},"lte": {{funding_amount_lte}}{{/funding_amount_lte}}}}}, {"terms": {"lead_investor": {{#join}}{{#toJson}}lead_investor{{/toJson}}{{/join}}}}, {"range": {"monthly_revenue": {"gte": {{monthly_revenue_gte}}{{#monthly_revenue_lte}},"lte": {{monthly_revenue_lte}}{{/monthly_revenue_lte}}}}} ] } } } } ], "rank_window_size": 100, "rank_constant": 20 } } }`, }, });

Regardez les requêtes détaillées dans le fichier elasticsearchSetup.ts . Dans le node suivant, il sera décidé laquelle des deux requêtes sera utilisée :

// Node 1: Decide search strategy using LLM async function decideSearchStrategy(state: typeof VCState.State) { // Zod schema for specialized search strategy decision const SearchDecisionSchema = z.object({ search_type: z .enum(["investment_focused", "market_focused"]) .describe("Type of specialized search strategy to use"), reasoning: z .string() .describe("Brief explanation of why this search strategy was chosen"), }); const decisionLLM = llm.withStructuredOutput(SearchDecisionSchema); // Get dynamic filters from Elasticsearch const availableFilters = await getAvailableFilters(); const prompt = `Query: "${state.input}" Available filters: ${JSON.stringify(availableFilters, null, 2)} Choose between two specialized search strategies: - investment_focused: For queries about funding stages, funding amounts, monthly revenue, lead investors, financial performance - market_focused: For queries about industries, locations, business models, market segments, geographic markets Analyze the query intent and choose the most appropriate strategy. `; try { const result = await decisionLLM.invoke(prompt); console.log( `🤔 Search strategy: ${result.search_type} - ${result.reasoning}` ); return { searchStrategy: result.search_type, }; } catch (error: any) { console.error("❌ Error in decideSearchStrategy:", error.message); return { searchStrategy: "investment_focused", }; } }

Nodes prepareInvestmentSearch et prepareMarketSearch

Les deux nœuds utilisent une fonction d’assistance partagée, extractFilterValues, qui exploite le LLM pour identifier les filtres pertinents mentionnés dans les entrées de l’utilisateur, tels que l’industrie, la localisation, le stade de financement, le modèle économique, etc. Nous utilisons ce schéma pour construire notre modèle de recherche.

// Extract all possible filter values from user input async function extractFilterValues(input: string) { const FilterValuesSchema = z.object({ // Investment-focused filters funding_stage: z .array(z.string()) .default([]) .describe("Funding stage values mentioned in query"), funding_amount_gte: z .number() .default(0) .describe("Minimum funding amount in USD"), funding_amount_lte: z .number() .default(100000000) .describe("Maximum funding amount in USD"), lead_investor: z .array(z.string()) .default([]) .describe("Lead investor values mentioned in query"), monthly_revenue_gte: z .number() .default(0) .describe("Minimum monthly revenue in USD"), monthly_revenue_lte: z .number() .default(10000000) .describe("Maximum monthly revenue in USD"), industry: z .array(z.string()) .default([]) .describe("Industry values mentioned in query"), location: z .array(z.string()) .default([]) .describe("Location values mentioned in query"), business_model: z .array(z.string()) .default([]) .describe("Business model values mentioned in query"), }); const extractorLLM = llm.withStructuredOutput(FilterValuesSchema); const availableFilters = await getAvailableFilters(); const extractPrompt = `Extract ALL relevant filter values from: "${input}" Available options: ${JSON.stringify(availableFilters, null, 2)} Extract only values explicitly mentioned in the query. Leave fields empty if not mentioned.`; return await extractorLLM.invoke(extractPrompt); }

Selon l'intention détectée, le workflow sélectionne l'un des deux chemins :

prepareInvestmentSearch : définit des paramètres de rechercher orientés sur la finance, notamment l''étape du financement, le montant du financement, les informations relatives à l''investisseur et au renouvellement. Vous pouvez trouver le modèle complet de requête dans le fichier elasticsearchSetup.ts :

// Node 2A: Prepare Investment-Focused Search Parameters async function prepareInvestmentSearch(state: typeof VCState.State) { console.log( "💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis..." ); try { // Extract all filter values from input const values = await extractFilterValues(state.input); let searchParams: any = { template_id: INVESTMENT_FOCUSED_TEMPLATE, query_text: state.input, ...values, }; return { searchParams }; } catch (error) { console.error("❌ Error preparing investment-focused params:", error); return { searchParams: {}, }; } }

prepareMarketSearch : crée des paramètres orientés vers le marché, axés sur les industries, les régions géographiques et les modèles économiques. Voir l’intégralité de la requête dans le fichier elasticsearchSetup.ts :

// Node 2B: Prepare Market-Focused Search Parameters async function prepareMarketSearch(state: typeof VCState.State) { console.log( "🔍 Preparing MARKET-FOCUSED search parameters with market emphasis..." ); try { // Extract all filter values from input const values = await extractFilterValues(state.input); let searchParams: any = { template_id: MARKET_FOCUSED_TEMPLATE, query_text: state.input, ...values, }; return { searchParams }; } catch (error) { console.error("❌ Error preparing market-focused params:", error); return {}; } }

Node executeSearch

Ce node prend les paramètres de rechercher générés à partir de l'état et les envoie d'abord à Elasticsearch, en utilisant l'API _render pour visualiser la requête à des fins de débogage, puis envoie une demande pour récupérer les résultats.

// Node 3: Execute Search async function executeSearch(state: typeof VCState.State) { const { searchParams } = state; try { // getting formed query from template for debugging const renderedTemplate = await esClient.renderSearchTemplate({ id: searchParams.template_id, params: searchParams, }); console.log( "📋 Complete query:", JSON.stringify(renderedTemplate.template_output, null, 2) ); const results = await esClient.searchTemplate({ index: INDEX_NAME, id: searchParams.template_id, params: searchParams, }); return { results: results.hits.hits.map((hit: any) => hit._source), }; } catch (error: any) { console.error(`❌ ${state.searchParams.search_type} search error:`, error); return { results: [] }; } }

Node visualizeResults

Enfin, ce node affiche les résultats d’Elasticsearch.

// Node 4: Visualize results async function visualizeResults(state: typeof VCState.State) { const results = state.results || []; let formattedResults = `🎯 Found ${results.length} startups matching your criteria:\n\n`; results.forEach((startup: any, index: number) => { formattedResults += `${index + 1}. **${startup.company_name}**\n`; formattedResults += ` 📍 ${startup.location} | 🏢 ${startup.industry} | 💼 ${startup.business_model}\n`; formattedResults += ` 💰 ${startup.funding_stage} - $${( startup.funding_amount / 1000000 ).toFixed(1)}M\n`; formattedResults += ` 👥 ${startup.employee_count} employees | 📈 $${( startup.monthly_revenue / 1000 ).toFixed(0)}K MRR\n`; formattedResults += ` 🏦 Lead: ${startup.lead_investor}\n`; formattedResults += ` 📝 ${startup.description}\n\n`; }); return { final: formattedResults, }; }

Par programmation, l'ensemble du graphe ressemble à ceci :

const workflow = new StateGraph(VCState) // Register nodes - these are the processing functions .addNode("decideStrategy", decideSearchStrategy) .addNode("prepareInvestment", prepareInvestmentSearch) .addNode("prepareMarket", prepareMarketSearch) .addNode("executeSearch", executeSearch) .addNode("visualizeResults", visualizeResults) // Define execution flow with conditional branching .addEdge(START, "decideStrategy") // Start with strategy decision .addConditionalEdges( "decideStrategy", (state: typeof VCState.State) => state.searchStrategy, // Conditional function { investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation market_focused: "prepareMarket", // If market focused -> dynamic query preparation } ) .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute .addEdge("prepareMarket", "executeSearch") // Market prep -> execute .addEdge("executeSearch", "visualizeResults") // Execute -> visualize .addEdge("visualizeResults", END); // End workflow

Comme vous pouvez le constater, nous avons une arête conditionnelle où l'application décide quel « chemin » ou node sera exécuté ensuite. Cette fonctionnalité est utile lorsque les workflows nécessitent une logique de branchement, comme le choix entre plusieurs outils ou l’inclusion d’une étape humaine dans la boucle.

Maintenant que vous maîtrisez les fonctionnalités clés de LangGraph, nous pouvons préparer l’application qui exécutera le code :

Rassemblons tout dans une méthode main , ici nous déclarons le graphe avec tous les éléments sous la variable workflow :

async function main() { await createIndex(); await createSearchTemplates(); await ingestDocuments(); // Create the workflow graph with shared state const workflow = new StateGraph(VCState) // Register nodes - these are the processing functions .addNode("decideStrategy", decideSearchStrategy) .addNode("prepareInvestment", prepareInvestmentSearch) .addNode("prepareMarket", prepareMarketSearch) .addNode("executeSearch", executeSearch) .addNode("visualizeResults", visualizeResults) // Define execution flow with conditional branching .addEdge(START, "decideStrategy") // Start with strategy decision .addConditionalEdges( "decideStrategy", (state: typeof VCState.State) => state.searchStrategy, // Conditional function { investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation market_focused: "prepareMarket", // If market focused -> dynamic query preparation } ) .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute .addEdge("prepareMarket", "executeSearch") // Market prep -> execute .addEdge("executeSearch", "visualizeResults") // Execute -> visualize .addEdge("visualizeResults", END); // End workflow const app = workflow.compile(); await saveGraphImage(app); const query = "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"; const marketResult = await app.invoke({ input: query }); console.log(marketResult.final); }

La variable de requête simule l'entrée utilisateur saisie dans une barre de recherche hypothétique :

D’après la phrase en langage naturel « Trouvez des startups avec un financement de la série A ou de la série B entre 8 millions et 25 millions de dollars et un chiffre d’affaires mensuel supérieur à 500 000 $ », tous les filtres seront extraits.

Enfin, invoquez la méthode principale :

main().catch(console.error);

Résultats

🔍 Checking if index exists... 🏗️ Creating index... ✅ Index created successfully! Ingesting documents... ✅ Documents ingested successfully! ✅ Investment-focused template created successfully! ✅ Market-focused template created successfully! 📊 Workflow graph saved as: ./workflow_graph.png 🔍 Query: "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K" 🤔 Search strategy: investment_focused - The query specifically seeks profitable fintech startups with defined funding amounts and high monthly revenue, which aligns closely with financial performance metrics and investment-related criteria. 💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis... 📋 Complete query: { "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K" } } } }, { "standard": { "query": { "bool": { "filter": [ { "terms": { "funding_stage": [ "Series A", "Series B" ] } }, { "range": { "funding_amount": { "gte": 8000000, "lte": 25000000 } } }, { "terms": { "lead_investor": [] } }, { "range": { "monthly_revenue": { "gte": 500000, "lte": 0 } } } ] } } } } ], "rank_window_size": 100, "rank_constant": 20 } } } 🎯 Found 5 startups matching your criteria: 1. **TechFlow** 📍 San Francisco, CA | 🏢 logistics | 💼 B2B 💰 Series A - $8.0M 👥 45 employees | 📈 $500K MRR 🏦 Lead: Sequoia Capital 📝 TechFlow optimizes supply chain operations using AI-powered route optimization and real-time tracking. Founded in 2023, shows remarkable growth with $500K monthly revenue. 2. **DataViz** 📍 New York, NY | 🏢 enterprise software | 💼 B2B 💰 Series A - $10.0M 👥 42 employees | 📈 $450K MRR 🏦 Lead: Battery Ventures 📝 DataViz creates intuitive data visualization tools for enterprise customers. No-code platform allows business users to create dashboards without technical expertise. 3. **FinanceAI** 📍 San Francisco, CA | 🏢 fintech | 💼 B2C 💰 Series C - $25.0M 👥 120 employees | 📈 $1200K MRR 🏦 Lead: Tiger Global Management 📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users. 4. **UrbanMobility** 📍 New York, NY | 🏢 logistics | 💼 B2B2C 💰 Series B - $15.0M 👥 78 employees | 📈 $750K MRR 🏦 Lead: Kleiner Perkins 📝 UrbanMobility revolutionizes urban transportation through autonomous delivery drones and smart logistics hubs. Partners with major retailers for same-day delivery across Manhattan and Brooklyn. 5. **HealthTech Solutions** 📍 Boston, MA | 🏢 healthcare | 💼 B2B 💰 Series B - $18.0M 👥 95 employees | 📈 $900K MRR 🏦 Lead: General Catalyst 📝 HealthTech Solutions develops medical devices and software for remote patient monitoring. Comprehensive telehealth platform reducing hospital readmissions by 30%. ✨ Done in 18.80s.

Pour l'entrée envoyée, l'application choisit le chemin axé sur l'investissement et, par conséquent, nous pouvons voir la requête Elasticsearch générée par le workflow, qui extrait les valeurs et les plages de l'entrée de l'utilisateur. Nous pouvons également voir la requête envoyée à Elasticsearch avec les valeurs extraites appliquées, et enfin, les résultats formatés par le nœud visualizeResults avec les résultats.

Testons maintenant le node axé sur le marché en utilisant la requête « Trouver des startups fintech et de la santé à San Francisco, New York ou Boston » :

... 🔍 Query: Find fintech and healthcare startups in San Francisco, New York, or Boston 🤔 Search strategy: market_focused - The query is focused on finding fintech startups in San Francisco that are disrupting traditional banking and payment systems, which pertains to specific industries (fintech) and locations (San Francisco). Thus, a market-focused strategy is more appropriate. 🔍 Preparing MARKET-FOCUSED search parameters with market emphasis... 📋 Complete query: { "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "Find fintech and healthcare startups in San Francisco, New York, or Boston" } } } }, { "standard": { "query": { "bool": { "filter": [ { "terms": { "industry": [ "fintech", "healthcare" ] } }, { "terms": { "location": [ "San Francisco, CA", "New York, NY", "Boston, MA" ] } }, { "terms": { "business_model": [] } } ] } } } } ], "rank_window_size": 50, "rank_constant": 10 } } } 🎯 Found 5 startups matching your criteria: 1. **FinanceAI** 📍 San Francisco, CA | 🏢 fintech | 💼 B2C 💰 Series C - $25.0M 👥 120 employees | 📈 $1200K MRR 🏦 Lead: Tiger Global Management 📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users. 2. **CryptoWallet** 📍 Miami, FL | 🏢 fintech | 💼 B2C 💰 Series B - $16.0M 👥 73 employees | 📈 $820K MRR 🏦 Lead: Coinbase Ventures 📝 CryptoWallet provides secure digital wallet solutions for cryptocurrency trading and storage. Multi-chain support with enterprise-grade security features. ... ✨ Done in 7.41s.

Enseignements

Pendant le processus d'écriture, j'ai appris :

Nous devons montrer au LLM les valeurs exactes des filtres, sinon nous attendons de l'utilisateur qu'il saisisse les valeurs exactes des éléments. Pour une faible cardinalité, cette approche convient, mais lorsque la cardinalité est élevée, nous avons besoin d'un mécanisme pour filtrer les résultats
Utiliser des modèles de recherche rend les résultats bien plus cohérents que de laisser le LLM écrire la requête Elasticsearch, et c’est aussi plus rapide
Les arêtes conditionnelles constituent un mécanisme puissant pour construire des applications avec de multiples variantes et chemins de branchement.
La sortie structurée est extrêmement utile lors de la génération d'informations avec des LLM, car elle applique des réponses prévisibles et sécurisées. Cela améliore la fiabilité et réduit les erreurs d'interprétation.

La combinaison de la recherche sémantique et de la recherche structurée par le biais d'une recherche hybride produit des résultats meilleurs et plus pertinents, en équilibrant précision et compréhension du contexte.

Conclusion

Dans cet exemple, nous combinons LangGraph.js avec Elasticsearch pour créer un workflow dynamique capable d'interpréter les requêtes en langage naturel et de décider entre des stratégies de recherche axées sur la finance ou le marché. Cette approche réduit la complexité de la création de requêtes manuelles tout en améliorant la flexibilité et la précision pour les analystes en capital-risque.

Tableaux de bord alimentés par l'IA : D'une vision à Kibana

Jeffrey Rengifo,Tomás Murúa — Wed, 16 Jul 2025 00:00:00 GMT

Kibana Lens simplifie le glisser-déposer des tableaux de bord, mais lorsque vous avez besoin de dizaines de panneaux, les clics s'accumulent. Et si vous pouviez dessiner un tableau de bord, en faire une capture d'écran et laisser un LLM terminer tout le processus à votre place ?

Dans cet article, nous allons y parvenir. Nous allons créer une application qui prend une image d'un tableau de bord, analyse nos mappings et génère un tableau de bord sans que nous ayons à toucher à Kibana !

Les étapes:

Contexte & flux de travail de l'application

La première idée qui m'est venue à l'esprit a été de laisser le LLM générer l'ensemble des objets sauvegardés au format NDJSON dans Kibana, puis de les importer dans Kibana.

Nous avons essayé une poignée de modèles :

Gemini 2.5 pro
GPT o3 / o4-mini-high / 4.1
Sonnet de Claude 4
Grok 3
Deepseek (Deepthink R1)

En ce qui concerne les messages-guides, nous avons commencé par une phrase simple :

You are an Elasticsearch Saved-Object generator (Kibana 9.0). INPUTS ===== 1. PNG screenshot of a 4-panel dashboard (attached). 2. Index mapping (below) – trimmed down to only the fields present in the screenshot. 3. Example NDJSON of *one* metric visualization (below) for reference. TASK ==== Return **only** a valid NDJSON array that recreates the dashboard exactly: * 2 metric panels (Visits, Unique Visitors) * 1 pie chart (Most used OS) * 1 vertical bar chart (State Geo Dest) * Use index pattern `kibana_sample_data_logs`. * Preserve roughly the same layout (2×2 grid). * Use `panelIndex` values 1-4 and random `id` strings. * Kibana version: 9.0

Bien que nous ayons parcouru des exemples en quelques images et des explications détaillées sur la manière de construire chaque visualisation, nous n'avons pas eu de chance. Si vous êtes intéressé par cette expérimentation, vous pouvez trouver des détails ici.

Le résultat de cette approche était l'apparition de ces messages lorsque l'on essayait de télécharger vers Kibana les fichiers produits par le LLM :

Cela signifie que le JSON généré est invalide ou mal formaté. Les problèmes les plus fréquents étaient que le LLM produisait des NDJSON incomplets, des paramètres hallucinants ou retournait du JSON normal au lieu de NDJSON, même si nous essayions de faire en sorte qu'il en soit autrement.

Inspirés par cet article - où les modèles de recherche ont mieux fonctionné que le LLM freestyle - nous avons décidé de donner des modèles au LLM au lieu de demander de générer le fichier NDJSON complet et ensuite nous, dans le code, utilisons les paramètres donnés par le LLM pour créer les visualisations appropriées.

Le processus de candidature sera le suivant :

Nous omettons une partie du code pour des raisons de simplicité, mais vous pouvez trouver le code de travail de l'application complète sur ce carnet.

Produits requis

Avant de commencer à développer, vous aurez besoin des éléments suivants :

Python 3.8 ou supérieur
Un environnement Venv Python
Une instance Elasticsearch en cours d'exécution, ainsi que son point d'accès et sa clé API
Une clé d'API OpenAI stockée dans la variable d'environnement OPENAI_API_KEY :

export OPENAI_API_KEY="your-openai-api-key"

Préparer les données

Pour les données, nous resterons simples et utiliserons les journaux web de l'échantillon Elastic. Pour savoir comment importer ces données dans votre cluster , cliquez ici.

Chaque document contient des informations sur l'hôte qui a envoyé des demandes à l'application, ainsi que des informations sur la demande elle-même et l'état de sa réponse. Vous trouverez ci-dessous un exemple de document :

{ "agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24", "bytes": 8509, "clientip": "70.133.115.149", "extension": "css", "geo": { "srcdest": "US:IT", "src": "US", "dest": "IT", "coordinates": { "lat": 38.05134111, "lon": -103.5106908 } }, "host": "cdn.elastic-elastic-elastic.org", "index": "kibana_sample_data_logs", "ip": "70.133.115.149", "machine": { "ram": 5368709120, "os": "osx" }, "memory": null, "message": "70.133.115.149 - - [2018-08-30T23:35:31.492Z] \"GET /styles/semantic-ui.css HTTP/1.1\" 200 8509 \"-\" \"Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24\"", "phpmemory": null, "referer": "http://twitter.com/error/john-phillips", "request": "/styles/semantic-ui.css", "response": 200, "tags": [ "success", "info" ], "@timestamp": "2025-07-03T23:35:31.492Z", "url": "https://cdn.elastic-elastic-elastic.org/styles/semantic-ui.css", "utc_time": "2025-07-03T23:35:31.492Z", "event": { "dataset": "sample_web_logs" }, "bytes_gauge": 8509, "bytes_counter": 51201128 }

Prenons maintenant les mappings de l'index que nous venons de charger, kibana_sample_data_logs:

INDEX_NAME = "kibana_sample_data_logs" es_client = Elasticsearch( [os.getenv("ELASTICSEARCH_URL")], api_key=os.getenv("ELASTICSEARCH_API_KEY"), ) result = es_client.indices.get_mapping(index=INDEX_NAME) index_mappings = result[list(result.keys())[0]]["mappings"]["properties"]

Nous allons transmettre les mappings avec l'image que nous chargerons plus tard.

Configuration LLM

Configurons le LLM pour qu'il utilise la sortie structurée afin d'entrer une image et de recevoir un JSON contenant les informations que nous devons transmettre à notre fonction pour produire les objets JSON.

Nous installons les dépendances :

pip install elasticsearch pydantic langchain langchain-openai -q

Elasticsearch nous aidera à récupérer les mappages d'index. Pydantic nous permet de définir des schémas en Python pour demander au LLM de les suivre, et LangChain est le cadre qui facilite l'appel aux LLM et aux outils d'IA.

Nous allons créer un schéma pydantique pour définir les résultats que nous voulons obtenir du LLM. Ce que nous devons savoir à partir de l'image, c'est le type de graphique, le champ, le titre de la visualisation et le titre du tableau de bord :

class Visualization(BaseModel): title: str = Field(description="The dashboard title") type: List[Literal["pie", "bar", "metric"]] field: str = Field( description="The field that this visualization use based on the provided mappings" ) class Dashboard(BaseModel): title: str = Field(description="The dashboard title") visualizations: List[Visualization]

Pour la saisie de l'image, nous enverrons un tableau de bord que je viens de dessiner :

Nous déclarons maintenant l'appel au modèle LLM et le chargement de l'image. Cette fonction recevra les mappings de l'index Elasticsearch et une image du tableau de bord que nous voulons générer.

Avec with_structured_output, nous pouvons utiliser notre schéma Pydantic Dashboard comme objet de réponse que le LLM produira. Avec Pydantic, nous pouvons définir des modèles de données avec validation, ce qui garantit que la sortie LLM correspond à la structure attendue.

Pour convertir l'image en base64 et l'envoyer en entrée, vous pouvez utiliser un convertisseur en ligne ou le faire en code.

prompt = f""" You are an expert in analyzing Kibana dashboards from images for the version 9.0.0 of Kibana. You will be given a dashboard image and an Elasticsearch index mapping. Below are the index mappings for the index that the dashboard is based on. Use this to help you understand the data and the fields that are available. Index Mappings: {index_mappings} Only include the fields that are relevant for each visualization, based on what is visible in the image. """ message = [ { "role": "user", "content": [ {"type": "text", "text": prompt}, { "type": "image", "source_type": "base64", "data": image_base64, "mime_type": "image/png", }, ], } ] try: llm = init_chat_model("gpt-4.1-mini") llm = llm.with_structured_output(Dashboard) dashboard_values = llm.invoke(message) print("Dashboard values generated by the LLM successfully") print(dashboard_values) except Exception as e: print(f"Failed to analyze image and match fields: {str(e)}")

Le LLM connaît déjà le contexte des tableaux de bord Kibana, nous n'avons donc pas besoin de tout expliquer dans l'invite, juste quelques détails pour s'assurer qu'il n'oublie pas qu'il travaille avec Elasticsearch et Kibana.

Décortiquons l'invitation :

Section

Raison

Vous êtes un expert en analyse de tableaux de bord Kibana à partir d'images pour la version 9.0.0 de Kibana.

En insistant sur le fait qu'il s'agit d'Elasticsearch et de la version d'Elasticsearch, nous réduisons la probabilité que le LLM hallucine des paramètres anciens/invalides.

Vous recevrez une image de tableau de bord et un mappage d'index Elasticsearch.

Nous expliquons que l'image concerne les tableaux de bord afin d'éviter toute interprétation erronée de la part du LLM.

Vous trouverez ci-dessous les correspondances d'index pour l'index sur lequel le tableau de bord est basé, ce qui vous aidera à comprendre les données et les champs disponibles. Mappages d'index : {index_mappings}

Il est essentiel de fournir les correspondances afin que le LLM puisse sélectionner les champs valides de manière dynamique. Sinon, nous pourrions coder en dur les correspondances ici, ce qui est trop rigide, ou compter sur le fait que l'image contienne les bons noms de champs, ce qui n'est pas fiable.

N'incluez que les champs pertinents pour chaque visualisation, en fonction de ce qui est visible dans l'image.

Nous avons dû ajouter ce renforcement parce qu'il arrive que l'on essaie d'ajouter des champs qui ne sont pas pertinents pour l'image.

Cela renvoie un objet contenant un tableau de visualisations à afficher :

"Dashboard values generated by the LLM successfully title=""Client, Extension, OS, and Response Keyword Analysis""visualizations="[ "Visualization(title=""Count of Client IP", "type="[ "metric" ], "field=""clientip"")", "Visualization(title=""Extension Keyword Distribution", "type="[ "pie" ], "field=""extension.keyword"")", "Visualization(title=""Most Used OS", "type="[ "bar" ], "field=""machine.os.keyword"")", "Visualization(title=""Response Keyword Distribution", "type="[ "bar" ], "field=""response.keyword"")" ]

Traitement de la réponse au mécanisme d'apprentissage tout au long de la vie

Nous avons créé un exemple de tableau de bord 2x2 panneaux à l'adresseet l'avons exporté en JSON à l'aide de l'API Get a dashboard, puis nous avons stocké les panneaux en tant que modèles de visualisation (camembert, barre, métrique) dans lesquels nous pouvons remplacer certains paramètres pour créer de nouvelles visualisations avec différents champs en fonction de la question.

Vous pouvez consulter les fichiers JSON du modèle ici. Notez que nous avons modifié les valeurs de l'objet que nous voulons remplacer plus tard par {variable_name}

Grâce aux informations fournies par le mécanisme d'apprentissage tout au long de la vie, nous pouvons décider du modèle à utiliser et des valeurs à remplacer.

fill_template_with_analysis recevra les paramètres pour un seul panneau, y compris le modèle JSON de la visualisation, un titre, un champ et les coordonnées de la visualisation sur la grille.

Ensuite, il remplacera les valeurs du modèle et renverra la visualisation JSON finale.

def fill_template_with_analysis( template: Dict[str, Any], visualization: Visualization, grid_data: Dict[str, Any], ): template_str = json.dumps(template) replacements = { "{visualization_id}": str(uuid.uuid4()), "{title}": visualization.title, "{x}": grid_data["x"], "{y}": grid_data["y"], } if visualization.field: replacements["{field}"] = visualization.field for placeholder, value in replacements.items(): template_str = template_str.replace(placeholder, str(value)) return json.loads(template_str)

Pour faire simple, nous aurons des coordonnées statiques que nous assignerons aux panneaux que le LLM décidera de créer et nous produirons un tableau de bord à grille 2x2 comme l'image ci-dessus.

# Filling templates fields panels = [] grid_data = [ {"x": 0, "y": 0}, {"x": 12, "y": 0}, {"x": 0, "y": 12}, {"x": 12, "y": 12}, ] i = 0 for vis in dashboard_values.visualizations: for vis_type in vis.type: template = templates.get(vis_type, templates.get("bar", {})) filled_panel = fill_template_with_analysis(template, vis, grid_data[i]) panels.append(filled_panel) i += 1

En fonction du type de visualisation décidé par le LLM, nous choisirons un modèle de fichier JSON et remplacerons les informations pertinentes à l'aide de fill_template_with_analysis , puis nous ajouterons le nouveau panneau à un tableau que nous utiliserons ultérieurement pour créer le tableau de bord.

Lorsque le tableau de bord est prêt, nous utilisons l'API Create a dashboard pour envoyer le nouveau fichier JSON à Kibana afin de générer le tableau de bord :

try: dashboard_id = str(uuid.uuid4()) # post request to create the dashboard endpoint url = f"{os.getenv('KIBANA_URL')}/api/dashboards/dashboard/{dashboard_id}" dashboard_config = { "attributes": { "title": dashboard_values.title, "description": "Generated by AI", "timeRestore": True, "panels": panels, # Visualizations with the values generated by the LLM "timeFrom": "now-7d/d", "timeTo": "now", }, } headers = { "Content-Type": "application/json", "kbn-xsrf": "true", "Authorization": f"ApiKey {os.getenv('ELASTICSEARCH_API_KEY')}", } requests.post( url, headers=headers, json=dashboard_config, ) # Url to the generated dashboard dashboard_url = f"{os.getenv('KIBANA_URL')}/app/dashboards#/view/{dashboard_id}" print("Dashboard URL: ", dashboard_url) print("Dashboard ID: ", dashboard_id) except Exception as e: print(f"Failed to create dashboard: {str(e)}")

Pour exécuter le script et générer le tableau de bord, exécutez la commande suivante dans la console :

python .py

Le résultat final sera le suivant :

Conclusion

Les LLM démontrent leurs fortes capacités visuelles lorsqu'ils transforment du texte en code ou des images en code. L'API des tableaux de bord permet également de transformer des fichiers JSON en tableaux de bord, et avec un LLM et un peu de code, nous pouvons transformer des images en tableau de bord Kibana.

L'étape suivante consiste à améliorer la flexibilité des visuels des tableaux de bord en utilisant différents paramètres de grille, différentes tailles de tableau de bord et différentes positions. De plus, la prise en charge de visualisations et de types de visualisation plus complexes serait un ajout utile à cette application.

Elasticsearch en JavaScript dans les règles de l'art, partie II

Jeffrey Rengifo — Mon, 19 May 2025 00:00:00 GMT

Voici la deuxième partie de notre série Elasticsearch en JavaScript. Dans la première partie, nous avons appris à mettre en place notre environnement correctement, à configurer le client Node.js, à indexer les données et à effectuer des recherches. Dans cette deuxième partie, nous allons apprendre à mettre en œuvre les meilleures pratiques de production et à exécuter le client Elasticsearch Node.js dans des environnements Serverless.

Nous ferons le point :

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 :

const { errors } = require('@elastic/elasticsearch') console.log(errors)

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

app.get("/search/lexic", async (req, res) => { .... } catch (error) { if (error instanceof errors.ResponseError) { let errorMessage = "Response error!, query malformed or server down, contact the administrator!"; if (error.body.error.type === "parsing_exception") { errorMessage = "Query malformed, make sure mappings are set correctly"; } res.status(error.meta.statusCode).json({ erroStatus: error.meta.statusCode, success: false, results: null, error: errorMessage, }); } res.status(500).json({ success: false, results: null, error: error.message, }); } });

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 :

{ "success": false, "results": null, "error": "parsing_exception\n\tRoot causes:\n\t\tparsing_exception: [terms] query does not support [visit_details]" }

Erreur personnalisée :

{ "erroStatus": 400, "success": false, "results": null, "error": "Response error!, query malformed or server down; contact the administrator!" }

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.

app.get("/search/semantic", async (req, res) => { try { ... } catch (error) { if (error instanceof errors.TimeoutError) { // Retry logic... res.status(error.meta.statusCode).json({ erroStatus: error.meta.statusCode, success: false, results: null, error: "The request took more than 10s after 3 retries. Try again later.", }); } } });

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 :

"type": "module", "scripts": { "test": "ava" }, "devDependencies": { "ava": "^5.0.0" }

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

const { Client } = require('@elastic/elasticsearch') const Mock = require('@elastic/elasticsearch-mock') const mock = new Mock() const client = new Client({ node: 'http://localhost:9200', Connection: mock.getConnection() })

Maintenant, ajoutez un simulacre de recherche sémantique :

function createSemanticSearchMock(query, indexName) { mock.add( { method: "POST", path: `/${indexName}/_search`, body: { query: { semantic: { field: "semantic_field", query: query, }, }, }, }, () => { return { hits: { total: { value: 2, relation: "eq" }, hits: [ { _id: "1", _score: 0.9, _source: { owner_name: "Alice Johnson", pet_name: "Buddy", species: "Dog", breed: "Golden Retriever", vaccination_history: ["Rabies", "Parvovirus", "Distemper"], visit_details: "Annual check-up and nail trimming. Healthy and active.", }, }, { _id: "2", _score: 0.7, _source: { owner_name: "Daniel Kim", pet_name: "Mochi", species: "Rabbit", breed: "Mixed", vaccination_history: [], visit_details: "Nail trimming and general health check. No issues.", }, }, ], }, }; } ); }

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

import test from 'ava'; test("performSemanticSearch must return formatted results correctly", async (t) => { const indexName = "vet-visits"; const query = "Which pets had nail trimming?"; createSemanticSearchMock(query, indexName); async function performSemanticSearch(esClient, q, indexName = "vet-visits") { try { const result = await esClient.search({ index: indexName, body: { query: { semantic: { field: "semantic_field", query: q, }, }, }, }); return { success: true, results: result.hits.hits, }; } catch (error) { if (error instanceof errors.TimeoutError) { return { success: false, results: null, error: error.body.error.reason, }; } return { success: false, results: null, error: error.message, }; } } const result = await performSemanticSearch(esClient, query, indexName); t.true(result.success, "The search must be successful"); t.true(Array.isArray(result.results), "The results must be an array"); if (result.results.length > 0) { t.true( "_source" in result.results[0], "Each result must have a _source property" ); t.true( "pet_name" in result.results[0]._source, "Results must include the pet_name field" ); t.true( "visit_details" in result.results[0]._source, "Results must include the visit_details field" ); } });

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.

const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'ELASTICSEARCH_ENDPOINT', auth: { apiKey: 'ELASTICSEARCH_API_KEY' }, 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.

'use strict' const { Client } = require('@elastic/elasticsearch') const client = new Client({ // client initialisation }) exports.handler = async function (event, context) { // use the client }

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 :

const response = await client.search( { index: INDEX, // You could directly send from the browser // the Elasticsearch's query DSL, but it will // expose you to the risk that a malicious user // could overload your cluster by crafting // expensive queries. query: { match: { field: req.body.text }, }, }, { headers: { Authorization: `ApiKey ${token}`, }, } );

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.

Elasticsearch en JavaScript dans les règles de l'art, partie I

Jeffrey Rengifo — Thu, 15 May 2025 00:00:00 GMT

Cet article est le premier d'une série qui traite de l'utilisation d'Elasticsearch avec JavaScript. Dans cette série, vous apprendrez les bases de l'utilisation d'Elasticsearch dans un environnement JavaScript et passerez en revue les fonctionnalités les plus pertinentes et les meilleures pratiques pour créer une application de recherche. À la fin, vous saurez tout ce dont vous avez besoin pour exécuter Elasticsearch à l'aide de JavaScript.

Dans cette première partie, nous passerons en revue

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 :

ELASTICSEARCH_ENDPOINT="Your Elasticsearch endpoint" ELASTICSEARCH_API_KEY="Your Elasticssearch API"

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 :

Server running on port 3000

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

curl http://localhost:3000/ping { "success": true, "clusterInfo": { "name": "instance-0000000000", "cluster_name": "61b7e19eec204d59855f5e019acd2689", "cluster_uuid": "BIfvfLM0RJWRK_bDCY5ldg", "version": { "number": "9.0.0", "build_flavor": "default", "build_type": "docker", "build_hash": "112859b85d50de2a7e63f73c8fc70b99eea24291", "build_date": "2025-04-08T15:13:46.049795831Z", "build_snapshot": false, "lucene_version": "10.1.0", "minimum_wire_compatibility_version": "8.18.0", "minimum_index_compatibility_version": "8.0.0" }, "tagline": "You Know, for Search" } }

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 :

const { Client } = require("@elastic/elasticsearch"); const ELASTICSEARCH_ENDPOINT = "cluster/project_endpoint"; const ELASTICSEARCH_API_KEY = "apiKey"; const esClient = new Client({ node: ELASTICSEARCH_ENDPOINT, auth: { apiKey: ELASTICSEARCH_API_KEY }, });

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) :

{"owner_name":"Alice Johnson","pet_name":"Buddy","species":"Dog","breed":"Golden Retriever","vaccination_history":["Rabies","Parvovirus","Distemper"],"visit_details":"Annual check-up and nail trimming. Healthy and active."} {"owner_name":"Marco Rivera","pet_name":"Milo","species":"Cat","breed":"Siamese","vaccination_history":["Rabies","Feline Leukemia"],"visit_details":"Slight eye irritation, prescribed eye drops."} {"owner_name":"Sandra Lee","pet_name":"Pickles","species":"Guinea Pig","breed":"Mixed","vaccination_history":[],"visit_details":"Loss of appetite, recommended dietary changes."} {"owner_name":"Jake Thompson","pet_name":"Luna","species":"Dog","breed":"Labrador Mix","vaccination_history":["Rabies","Bordetella"],"visit_details":"Mild ear infection, cleaning and antibiotics given."} {"owner_name":"Emily Chen","pet_name":"Ziggy","species":"Cat","breed":"Mixed","vaccination_history":["Rabies","Feline Calicivirus"],"visit_details":"Vaccination update and routine physical."} {"owner_name":"Tomás Herrera","pet_name":"Rex","species":"Dog","breed":"German Shepherd","vaccination_history":["Rabies","Parvovirus","Leptospirosis"],"visit_details":"Follow-up for previous leg strain, improving well."} {"owner_name":"Nina Park","pet_name":"Coco","species":"Ferret","breed":"Mixed","vaccination_history":["Rabies"],"visit_details":"Slight weight loss; advised new diet."} {"owner_name":"Leo Martínez","pet_name":"Simba","species":"Cat","breed":"Maine Coon","vaccination_history":["Rabies","Feline Panleukopenia"],"visit_details":"Dental cleaning. Minor tartar buildup removed."} {"owner_name":"Rachel Green","pet_name":"Rocky","species":"Dog","breed":"Bulldog Mix","vaccination_history":["Rabies","Parvovirus"],"visit_details":"Skin rash, antihistamines prescribed."} {"owner_name":"Daniel Kim","pet_name":"Mochi","species":"Rabbit","breed":"Mixed","vaccination_history":[],"visit_details":"Nail trimming and general health check. No issues."}

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

const { createReadStream } = require("fs"); const split = require("split2"); const indexData = async (filePath, indexName) => { try { console.log(`Indexing data from ${filePath} into ${indexName}...`); const result = await esClient.helpers.bulk({ datasource: createReadStream(filePath).pipe(split()), onDocument: () => { return { index: { _index: indexName }, }; }, onDrop(doc) { console.error("Error processing document:", doc); }, }); console.log("Bulk indexing successful elements:", result.items.length); } catch (error) { console.error("Error indexing data:", error); throw error; } }; await indexData("./data.ndjson", INDEX_NAME);

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

Creating mappings for index vet-visits... Index created successfully: { acknowledged: true, shards_acknowledged: true, index: 'vet-visits' } Indexing data from ./data.ndjson into vet-visits... Bulk indexing completed. Total documents: 10, Failed: 0

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=)

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.

app.get("/search/lexic", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, size: 5, body: { query: { multi_match: { query: q, fields: ["owner_name", "pet_name", "visit_details"], }, }, }, }); res.status(200).json({ success: true, results: result.hits.hits }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

Nous testons avec : coupe-ongles

curl http://localhost:3000/search/lexic?q=nail%20trimming

Réponse :

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 2.7075968, "_source": { "pet_name": "Mochi", "owner_name": "Daniel Kim", "species": "Rabbit", "visit_details": "Nail trimming and general health check. No issues.", "breed": "Mixed", "vaccination_history": [] } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 2.560356, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } } ] }

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

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.

app.get("/search/semantic", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, size: 5, body: { query: { semantic: { field: "semantic_field", query: q }, }, }, }); res.status(200).json({ success: true, results: result.hits.hits, }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

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

curl http://localhost:3000/search/semantic?q=Who%20got%20a%20pedicure?

Réponse :

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 4.861466, "_source": { "owner_name": "Daniel Kim", "pet_name": "Mochi", "species": "Rabbit", "breed": "Mixed", "vaccination_history": [], "visit_details": "Nail trimming and general health check. No issues." } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 4.7152824, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } }, { "_index": "vet-visits", "_id": "9RY6RJYBLe2GoFQ6-9n9", "_score": 1.6717153, "_source": { "pet_name": "Rex", "owner_name": "Tomás Herrera", "species": "Dog", "visit_details": "Follow-up for previous leg strain, improving well.", "breed": "German Shepherd", "vaccination_history": [ "Rabies", "Parvovirus", "Leptospirosis" ] } }, { "_index": "vet-visits", "_id": "9xY6RJYBLe2GoFQ6-9n9", "_score": 1.5600781, "_source": { "pet_name": "Simba", "owner_name": "Leo Martínez", "species": "Cat", "visit_details": "Dental cleaning. Minor tartar buildup removed.", "breed": "Maine Coon", "vaccination_history": [ "Rabies", "Feline Panleukopenia" ] } }, { "_index": "vet-visits", "_id": "-BY6RJYBLe2GoFQ6-9n9", "_score": 1.2696637, "_source": { "pet_name": "Rocky", "owner_name": "Rachel Green", "species": "Dog", "visit_details": "Skin rash, antihistamines prescribed.", "breed": "Bulldog Mix", "vaccination_history": [ "Rabies", "Parvovirus" ] } } ] }

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

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.

app.get("/search/hybrid", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, body: { retriever: { rrf: { retrievers: [ { standard: { query: { bool: { must: { multi_match: { query: q, fields: ["owner_name", "pet_name", "visit_details"], }, }, }, }, }, }, { standard: { query: { bool: { must: { semantic: { field: "semantic_field", query: q, }, }, }, }, }, }, ], }, }, size: 5, }, }); res.status(200).json({ success: true, results: result.hits.hits, }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

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

curl http://localhost:3000/search/hybrid?q=who%20got%20a%20pedicure%20or%20dental%20treatment

Réponse :

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "9xY6RJYBLe2GoFQ6-9n9", "_score": 0.032522473, "_source": { "pet_name": "Simba", "owner_name": "Leo Martínez", "species": "Cat", "visit_details": "Dental cleaning. Minor tartar buildup removed.", "breed": "Maine Coon", "vaccination_history": [ "Rabies", "Feline Panleukopenia" ] } }, { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 0.016393442, "_source": { "pet_name": "Mochi", "owner_name": "Daniel Kim", "species": "Rabbit", "visit_details": "Nail trimming and general health check. No issues.", "breed": "Mixed", "vaccination_history": [] } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 0.015873017, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } }, { "_index": "vet-visits", "_id": "9RY6RJYBLe2GoFQ6-9n9", "_score": 0.015625, "_source": { "pet_name": "Rex", "owner_name": "Tomás Herrera", "species": "Dog", "visit_details": "Follow-up for previous leg strain, improving well.", "breed": "German Shepherd", "vaccination_history": [ "Rabies", "Parvovirus", "Leptospirosis" ] } }, { "_index": "vet-visits", "_id": "8xY6RJYBLe2GoFQ6-9n9", "_score": 0.015384615, "_source": { "pet_name": "Luna", "owner_name": "Jake Thompson", "species": "Dog", "visit_details": "Mild ear infection, cleaning and antibiotics given.", "breed": "Labrador Mix", "vaccination_history": [ "Rabies", "Bordetella" ] } } ] }

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.

Utiliser Ollama avec l'API d'inférence

Jeffrey Rengifo — Fri, 14 Feb 2025 00:00:00 GMT

Dans cet article, nous allons apprendre à connecter des modèles locaux au modèle d'inférence d'Elasticsearch à l'aide d'Ollama, puis à poser des questions à vos documents à l'aide de Playground.

Elasticsearch permet aux utilisateurs de se connecter aux LLM à l'aide de l'API Open Inference, qui prend en charge des fournisseurs tels qu'Amazon Bedrock, Cohere, Google AI, Azure AI Studio, HuggingFace - en tant que service, entre autres.

Ollama est un outil qui vous permet de télécharger et d'exécuter des modèles LLM en utilisant votre propre infrastructure (votre machine/serveur local). Vous trouverez ici une liste des modèles disponibles qui sont compatibles avec Ollama.

Ollama est une excellente option si vous souhaitez héberger et tester différents modèles open source sans avoir à vous soucier des différentes façons dont chacun des modèles pourrait être configuré, ou de la façon de créer une API pour accéder aux fonctions du modèle, car Ollama s'occupe de tout.

L'API d'Ollama étant compatible avec l'API d'OpenAI, nous pouvons facilement intégrer le modèle d'inférence et créer une application RAG à l'aide de Playground.

Produits requis

Elasticsearch 8.17
Kibana 8.17
Python

Étapes

Mise en place du serveur Ollama LLM

Nous allons mettre en place un serveur LLM pour le connecter à notre instance Playground en utilisant Ollama. Nous en aurons besoin :

Téléchargez et exécutez Ollama.
Utilisez ngrok pour accéder à votre serveur web local qui héberge Ollama sur Internet.

Télécharger et lancer Ollama

Pour utiliser Ollama, il faut d'abord le télécharger. Ollama est compatible avec Linux, Windows et macOS. Il vous suffit donc de télécharger la version d'Ollama compatible avec votre système d'exploitation ici. Une fois Ollama installé, nous pouvons choisir un modèle dans cette liste de LLMs supportés. Dans cet exemple, nous utiliserons le modèle llama3.2, un modèle général multilingue. Dans le processus d'installation, vous activerez l'outil de ligne de commande pour Ollama. Une fois qu'il est téléchargé, vous pouvez exécuter la ligne suivante :

ollama pull llama3.2

Ce qui produira un résultat :

pulling manifest pulling dde5aa3fc5ff... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 2.0 GB pulling 966de95ca8a6... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 1.4 KB pulling fcc5a6bec9da... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 7.7 KB pulling a70ff7e570d9... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 6.0 KB pulling 56bb8bd477a5... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 96 B pulling 34bb5ab01051... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 561 B verifying sha256 digest writing manifest success

Une fois installé, vous pouvez le tester avec cette commande :

ollama run llama3.2

Posons une question :

Une fois le modèle en cours d'exécution, Ollama active une API qui s'exécute par défaut sur le port "11434". Faisons une demande à cette API, en suivant la documentation officielle :

curl http://localhost:11434/api/generate -d '{ "model": "llama3.2", "prompt": "What is the capital of France?" }'

Voici la réponse que nous avons reçue :

{"model":"llama3.2","created_at":"2024-11-28T21:48:42.152817532Z","response":"The","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.251884485Z","response":" capital","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.347365913Z","response":" of","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.446837322Z","response":" France","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.542367394Z","response":" is","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.644580384Z","response":" Paris","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.739865362Z","response":".","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.834347518Z","response":"","done":true,"done_reason":"stop","context":[128006,9125,128007,271,38766,1303,33025,2696,25,6790,220,2366,18,271,128009,128006,882,128007,271,3923,374,279,6864,315,9822,30,128009,128006,78191,128007,271,791,6864,315,9822,374,12366,13],"total_duration":6948567145,"load_duration":4386106503,"prompt_eval_count":32,"prompt_eval_duration":1872000000,"eval_count":8,"eval_duration":684000000}

Notez que la réponse spécifique pour ce point d'accès est un flux.

Exposer un point de terminaison à l'internet en utilisant ngrok

Comme notre point d'extrémité fonctionne dans un environnement local, il n'est pas possible d'y accéder à partir d'un autre point, comme notre instance Elastic Cloud, via l'internet. ngrok nous permet d'exposer un port en offrant une IP publique. Créez un compte dans ngrok et suivez le guide d'installation officiel.

Une fois l'agent ngrok installé et configuré, nous pouvons exposer le port utilisé par Ollama :

ngrok http 11434 --host-header="localhost:11434"

Remarque : l'en-tête --host-header="localhost:11434" garantit que l'en-tête "Host" dans les demandes correspond à "localhost:11434."

L'exécution de cette commande renverra un lien public qui fonctionnera tant que le ngrok et le serveur Ollama fonctionneront localement.

Session Status online Account xxxx@yourEmailProvider.com (Plan: Free) Version 3.18.4 Region United States (us) Latency 561ms Web Interface http://127.0.0.1:4040 Forwarding https://your-ngrok-url.ngrok-free.app -> http://localhost:11434 Connections ttl opn rt1 rt5 p50 p90 0 0 0.00 0.00 0.00 0.00 ```

Dans "Forwarding", nous pouvons voir que ngrok a généré une URL. Gardez-le pour plus tard.

Essayons à nouveau de faire une requête HTTP vers le point d'accès, en utilisant maintenant l'URL générée par le moteur de recherche :

curl https://your-ngrok-endpoint.ngrok-free.app/api/generate -d '{ "model": "llama3.2", "prompt": "What is the capital of France?" }'

La réponse devrait être similaire à la précédente.

Création de mappings

Point final ELSER

Pour cet exemple, nous allons créer un point de terminaison d'inférence à l'aide de l'API d'inférence d'Elasticsearch. En outre, nous utiliserons ELSER pour générer les enchâssements.

PUT _inference/sparse_embedding/medicines-inference { "service": "elasticsearch", "service_settings": { "num_allocations": 1, "num_threads": 1, "model_id": ".elser_model_2_linux-x86_64" } }

Pour cet exemple, imaginons que vous ayez une pharmacie qui vend deux types de médicaments :

Médicaments nécessitant une ordonnance.
Médicaments qui ne nécessitent pas d'ordonnance.

Cette information serait incluse dans le champ de description de chaque médicament.

Le LLM doit interpréter ce champ, c'est donc le mappage des données que nous utiliserons :

PUT medicines { "mappings": { "properties": { "name": { "type": "text", "copy_to": "semantic_field" }, "semantic_field": { "type": "semantic_text", "inference_id": "medicines-inference" }, "text_description": { "type": "text", "copy_to": "semantic_field" } } } }

Le champ text_description stockera le texte brut des descriptions tandis que semantic_field, qui est un champ de type semantic_text, stockera les enchâssements générés par ELSER.

La propriété copy_to copiera le contenu des champs name et text_description dans le champ sémantique afin de générer les embeddings pour ces champs.

Indexation des données

Maintenant, indexons les données à l'aide de l'API _bulk.

POST _bulk {"index":{"_index":"medicines"}} {"id":1,"name":"Paracetamol","text_description":"An analgesic and antipyretic that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":2,"name":"Ibuprofen","text_description":"A nonsteroidal anti-inflammatory drug (NSAID) available WITHOUT a prescription."} {"index":{"_index":"medicines"}} {"id":3,"name":"Amoxicillin","text_description":"An antibiotic that requires a prescription."} {"index":{"_index":"medicines"}} {"id":4,"name":"Lorazepam","text_description":"An anxiolytic medication that strictly requires a prescription."} {"index":{"_index":"medicines"}} {"id":5,"name":"Omeprazole","text_description":"A medication for stomach acidity that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":6,"name":"Insulin","text_description":"A hormone used in diabetes treatment that requires a prescription."} {"index":{"_index":"medicines"}} {"id":7,"name":"Cold Medicine","text_description":"A compound formula to relieve flu symptoms available WITHOUT a prescription."} {"index":{"_index":"medicines"}} {"id":8,"name":"Clonazepam","text_description":"An antiepileptic medication that requires a prescription."} {"index":{"_index":"medicines"}} {"id":9,"name":"Vitamin C","text_description":"A dietary supplement that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":10,"name":"Metformin","text_description":"A medication used for type 2 diabetes that requires a prescription."}

Réponse :

{ "errors": false, "took": 34732020848, "items": [ { "index": { "_index": "medicines", "_id": "mYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 0, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "mooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 1, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "m4oeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 2, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nIoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 3, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 4, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 5, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "n4oeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 6, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oIoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 7, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 8, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 9, "_primary_term": 1, "status": 201 } } ] }

Poser des questions à l'aide de l'aire de jeu

Playground est un outil Kibana qui vous permet de créer rapidement un système RAG en utilisant des index Elasticsearch et un fournisseur LLM. Vous pouvez lire cet article pour en savoir plus.

Connecter le programme local d'éducation et de formation tout au long de la vie à l'aire de jeux

Nous devons d'abord créer un connecteur qui utilise l'URL publique que nous venons de créer. Dans Kibana, allez sur Search>Playground et cliquez sur "Connect to an LLM".

Cette action fait apparaître un menu sur le côté gauche de l'interface Kibana. Cliquez ensuite sur "OpenAI".

Nous pouvons maintenant commencer à configurer le connecteur OpenAI.

Allez sur "Connector settings" et pour le fournisseur OpenAI, sélectionnez "Other (OpenAI Compatible Service)":

Configurons maintenant les autres champs. Pour cet exemple, nous nommerons notre modèle "medicines-llm". Dans le champ URL, utilisez celle générée par ngrok (/v1/chat/completions). Dans le champ "Modèle par défaut", sélectionnez "llama3.2". Nous n'utiliserons pas de clé API, vous pouvez donc saisir n'importe quel texte au hasard :

Cliquez sur "Sauvegarder" et ajoutez les médicaments de l'index en cliquant sur "Ajouter des sources de données":

Excellent ! Nous avons maintenant accès à Playground en utilisant le LLM que nous exécutons localement en tant que moteur RAG.

Avant de le tester, ajoutons des instructions plus spécifiques à l'agent et augmentons le nombre de documents envoyés au modèle à 10, afin que la réponse dispose du plus grand nombre possible de documents. Le champ contextuel sera semantic_field, qui comprend le nom et la description des médicaments, grâce à la propriété copy_to.

Posons maintenant la question : Puis-je acheter du Clonazepam sans ordonnance ? et voir ce qui se passe :

Comme prévu, nous avons obtenu la bonne réponse.

Étapes suivantes

L'étape suivante consiste à créer votre propre application ! Playground fournit un code script en Python que vous pouvez exécuter sur votre machine et adapter à vos besoins. Par exemple, en le plaçant derrière un serveur FastAPI pour créer un chatbot d'assurance qualité consommé par votre interface utilisateur.

Vous pouvez trouver ce code en cliquant sur le bouton Voir le code dans la partie supérieure droite de l'aire de jeux :

Et vous utilisez les clés de l'API Endpoints & pour générer la variable d'environnement ES_API_KEY requise dans le code.

Pour cet exemple particulier, le code est le suivant :

## Install the required packages ## pip install -qU elasticsearch openai import os from elasticsearch import Elasticsearch from openai import OpenAI es_client = Elasticsearch( "https://your-deployment.us-central1.gcp.cloud.es.io:443", api_key=os.environ["ES_API_KEY"] ) openai_client = OpenAI( api_key=os.environ["OPENAI_API_KEY"], ) index_source_fields = { "medicines": [ "semantic_field" ] } def get_elasticsearch_results(): es_query = { "retriever": { "standard": { "query": { "nested": { "path": "semantic_field.inference.chunks", "query": { "sparse_vector": { "inference_id": "medicines-inference", "field": "semantic_field.inference.chunks.embeddings", "query": query } }, "inner_hits": { "size": 2, "name": "medicines.semantic_field", "_source": [ "semantic_field.inference.chunks.text" ] } } } } }, "size": 3 } result = es_client.search(index="medicines", body=es_query) return result["hits"]["hits"] def create_openai_prompt(results): context = "" for hit in results: inner_hit_path = f"{hit['_index']}.{index_source_fields.get(hit['_index'])[0]}" ## For semantic_text matches, we need to extract the text from the inner_hits if 'inner_hits' in hit and inner_hit_path in hit['inner_hits']: context += '\n --- \n'.join(inner_hit['_source']['text'] for inner_hit in hit['inner_hits'][inner_hit_path]['hits']['hits']) else: source_field = index_source_fields.get(hit["_index"])[0] hit_context = hit["_source"][source_field] context += f"{hit_context}\n" prompt = f""" Instructions: - You are an assistant specializing in answering questions about the sale of medicines. - Answer questions truthfully and factually using only the context presented. - If you don't know the answer, just say that you don't know, don't make up an answer. - You must always cite the document where the answer was extracted using inline academic citation style [], using the position. - Use markdown format for code examples. - You are correct, factual, precise, and reliable. Context: {context} """ return prompt def generate_openai_completion(user_prompt, question): response = openai_client.chat.completions.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": user_prompt}, {"role": "user", "content": question}, ] ) return response.choices[0].message.content if __name__ == "__main__": question = "my question" elasticsearch_results = get_elasticsearch_results() context_prompt = create_openai_prompt(elasticsearch_results) openai_completion = generate_openai_completion(context_prompt, question) print(openai_completion)

Pour que cela fonctionne avec Ollama, vous devez modifier le client OpenAI pour qu'il se connecte au serveur Ollama au lieu du serveur OpenAI. Vous pouvez trouver la liste complète des exemples OpenAI et des points de terminaison compatibles ici.

openai_client = OpenAI( # you can use http://localhost:11434/v1/ if running this code locally. base_url='https://your-ngrok-url.ngrok-free.app/v1/', # required but ignored api_key='ollama', )

Il faut également changer le modèle en llama3.2 lors de l'appel de la méthode d'achèvement :

def generate_openai_completion(user_prompt, question): response = openai_client.chat.completions.create( model="llama3.2", messages=[ {"role": "system", "content": user_prompt}, {"role": "user", "content": question}, ] ) return response.choices[0].message.content

Ajoutons notre question : Puis-je acheter du Clonazepam sans ordonnance ? Pour la requête Elasticsearch :

def get_elasticsearch_results(): es_query = { "retriever": { "standard": { "query": { "nested": { "path": "semantic_field.inference.chunks", "query": { "sparse_vector": { "inference_id": "medicines-inference", "field": "semantic_field.inference.chunks.embeddings", "query": "Can I buy Clonazepam without a prescription?" } }, "inner_hits": { "size": 2, "name": "medicines.semantic_field", "_source": [ "semantic_field.inference.chunks.text" ] } } } } }, "size": 3 } result = es_client.search(index="medicines", body=es_query) return result["hits"]["hits"]

Et aussi à l'appel d'achèvement avec quelques impressions, pour que nous puissions confirmer que nous envoyons les résultats d'Elasticsearch dans le cadre du contexte de la question :

if __name__ == "__main__": question = "Can I buy Clonazepam without a prescription?" elasticsearch_results = get_elasticsearch_results() context_prompt = create_openai_prompt(elasticsearch_results) print("========== Context Prompt START ==========") print(context_prompt) print("========== Context Prompt END ==========") print("========== Ollama Completion START ==========") openai_completion = generate_openai_completion(context_prompt, question) print(openai_completion) print("========== Ollama Completion END ==========")

Exécutons maintenant la commande

pip install -qU elasticsearch openai

python main.py

Vous devriez voir quelque chose comme ceci :

========== Context Prompt START ========== Instructions: - You are an assistant specializing in answering questions about the sale of medicines. - Answer questions truthfully and factually using only the context presented. - If you don't know the answer, just say that you don't know, don't make up an answer. - You must always cite the document where the answer was extracted using inline academic citation style [], using the position. - Use markdown format for code examples. - You are correct, factual, precise, and reliable. Context: Clonazepam --- An antiepileptic medication that requires a prescription.A nonsteroidal anti-inflammatory drug (NSAID) available WITHOUT a prescription. --- IbuprofenAn anxiolytic medication that strictly requires a prescription. --- Lorazepam ========== Context Prompt END ========== ========== Ollama Completion START ========== No, you cannot buy Clonazepam over-the-counter (OTC) without a prescription [1]. It is classified as a controlled substance in the United States due to its potential for dependence and abuse. Therefore, it can only be obtained from a licensed healthcare provider who will issue a prescription for this medication. ========== Ollama Completion END ==========

Conclusion

Dans cet article, nous pouvons voir la puissance et la polyvalence d'outils comme Ollama lorsque nous les utilisons avec l'API d'inférence Elasticsearch et Playground.

Après quelques étapes simples, nous avions une application RAG fonctionnelle avec un chat qui utilisait un LLM fonctionnant dans notre propre infrastructure à un coût nul. Cela nous permet également de mieux contrôler les ressources et les informations sensibles, tout en nous donnant accès à une variété de modèles pour différentes tâches.