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 :

• Serveur MCP Elastic Agent Builder pour Elasticsearch 9.2+
• Serveur MCP Elasticsearch pour les anciennes versions (Python)

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 :

1. Configurer le serveur MCP pour Elasticsearch.
2. Chargez le serveur MCP dans Claude Desktop.
3. Testez-le.

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.
• ZOD aide à 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é.

C'est précisément pour cela que nous avons créé des tableaux de bord en lecture seule. C'est le niveau de contrôle que vous attendiez. Partagez vos tableaux de bord en toute confiance, sans craindre que la prochaine personne qui dispose d'un accès en modification ne les modifie ou ne les altère.

Remarque : les autorisations en lecture seule sont disponibles dans Elastic Cloud Serverless et à partir de la version 9.3 pour Elastic Cloud Hosted et Elastic autogéré.

Quand l'option "tout le monde peut modifier" pose problème

Dans Kibana, le partage est généralement synonyme d'autorisations au niveau de l'espace. Si quelqu'un peut créer des tableaux de bord dans un espace, il peut également modifier ou supprimer ceux des autres. C'est génial pour collaborer jusqu'à ce que ce ne soit plus le cas. Une modification accidentelle peut entraîner de mauvaises décisions, une perte de confiance et beaucoup de nettoyage.

Nous avons entendu les solutions de contournement : "On ajoute "lecture seule" dans le nom du tableau de bord et on espère que les gens le remarqueront." Ou encore : "On les étiquette et on croise les doigts." L'espoir n'est pas un modèle d'autorisations. Il vous fallait un moyen efficace de verrouiller un tableau de bord sans en interdire l'accès à tous.

Ce qui ne va pas

Deb et Kevin ont tous deux un accès en modification au tableau de bord de surveillance des logs dans l'espace Opérations. Kevin apporte quelques modifications aux graphiques. À son retour, Deb constate que les chiffres ne correspondent plus à ce qu'elle a présenté. Elle doit alors rechercher ce qui a été modifié (souvent de mémoire), le corriger et se demander combien de rapports erronés ont été diffusés.

Tableaux de bord en lecture seule : droits d'accès et contrôle adaptés

Les tableaux de bord en lecture seule résolvent ce problème en vous permettant de contrôler si d'autres utilisateurs peuvent les modifier. Lorsque vous partagez un tableau de bord, vous avez le choix entre : modifier (par défaut, comme aujourd'hui) ou afficher. En mode affichage, vous seul (et les administrateurs de Kibana) pouvez le modifier ou le supprimer. Tous les autres peuvent l'ouvrir, l'utiliser et lui faire confiance, mais ils ne peuvent pas le modifier.

Ce que vous obtenez

• Intégrité du tableau de bord : en mode affichage, les autres utilisateurs disposant d'un accès en modification dans l'espace ne peuvent ni modifier ni supprimer le tableau de bord. S'ils tentent de le faire, un message leur indique qu'il est verrouillé. Vos graphiques et votre logique restent intacts.
• Vous gardez le contrôle : vous êtes le propriétaire. Vous pouvez toujours modifier, affiner et mettre à jour. Le partage en lecture seule ne vous empêche pas d'accéder au contenu ; il verrouille la version visible par tous les autres utilisateurs.
• Cycle de vie flexible : vous pouvez à tout moment repasser un tableau de bord en mode "modifiable". Et les administrateurs Kibana peuvent toujours gérer tous les tableaux de bord (par exemple, si le propriétaire quitte l'entreprise). Il n'y a pas d'impasse.

Vous pouvez partager largement des tableaux de bord finalisés et stratégiques, en ayant l'assurance qu'ils resteront cohérents. Cette fonctionnalité est disponible dans tous les niveaux et offres Elastic, y compris Serverless.

Qui peut faire quoi ?

Référence rapide par rôle :

• Propriétaire du tableau de bord : vous l'avez créé ; vous disposez d'un accès complet en modification.
• Administrateur Kibana : peut gérer tous les tableaux de bord.
• Utilisateur avec droit de modification dans l'espace : peut créer et modifier ses tableaux de bord ; ne peut ni modifier ni supprimer les tableaux de bord en mode lecture seule.
• Utilisateur avec droit d'affichage dans l'espace : peut uniquement consulter (et afficher) les tableaux de bord.

Comment activer le mode lecture seule

Vous pouvez activer le mode lecture seule lors de l'enregistrement d'un nouveau tableau de bord ou ultérieurement depuis le menu Partager.

Lors de l’enregistrement d’un nouveau tableau de bord

• Créez votre tableau de bord, puis cliquez sur Enregistrer.
• Dans la fenêtre modale "Enregistrer en tant que nouveau tableau de bord", recherchez Autorisations.
• Passez de Peut modifier à Peut afficher.
• Cliquez sur Save (Enregistrer). Et le tour est joué ! C'est en lecture seule pour tous les autres utilisateurs.

Pour un tableau de bord que vous possédez déjà

• Ouvrez le tableau de bord.
• Ouvrez le menu Partager le tableau de bord.

• Dans la fenêtre de partage, recherchez Autorisations et sélectionnez Affichage uniquement. La modification s'applique immédiatement ; les autres utilisateurs dans l'espace ne peuvent plus le modifier ni le supprimer.

• Vous pouvez survoler l'action Partager avec la souris pour voir le type d'autorisations dont dispose un tableau de bord donné.

Voir quels tableaux de bord sont verrouillés

Dans la liste principale des tableaux de bord, les tableaux de bord que vous ne pouvez ni modifier ni supprimer sont signalés par une case à cocher désactivée. Cela permet de repérer facilement les tableaux de bord en lecture seule.

Sur le tableau de bord, vous constaterez également que l'action Modifier est désactivée et qu'une info-bulle apparaît, expliquant que le tableau de bord a été configuré en lecture seule.

Faites l'essai

Les tableaux de bord en lecture seule sont désormais disponibles. Créez un tableau de bord, passez-le en mode Affichage uniquement et partagez-le. Votre équipe dispose ainsi d'une source unique d'information fiable, et vous avez l'esprit tranquille. Fini les mentions "Ne pas modifier" dans le titre.

Nous aimerions savoir comment vous utilisez les tableaux de bord en lecture seule. Partagez vos commentaires sur notre forum communautaire.

Ce billet se concentre sur la question suivante : quelles sont les bonnes interfaces de recherche dont un agent a besoin pour construire son propre contexte ? Il couvre d'abord les compromis entre les outils de shell et les outils de base de données dédiés. Il propose ensuite un framework pratique pour trouver les interfaces adaptées aux besoins de votre agent.

Que signifie concrètement pour un agent le terme « contexte de construction » ?

Dans les premiers pipelines de Retrieval-Augmented Generation (RAG), le développeur concevait un pipeline de recherche fixe, et le grand modèle de langage (LLM) était un récepteur passif du contexte. C'était une limitation fondamentale : le contexte était récupéré à chaque requête, qu'il soit nécessaire ou non, sans vérification qu'il aidait réellement.

Avec le passage au RAG agentique, les agents ont désormais accès à un ensemble d’outils de recherche pour construire leur propre contexte. Par exemple, Claude Code [1] et Cursor [2] permettent tous deux à l’agent de choisir entre différents outils de recherche et même de les combiner pour des requêtes chaînées, en fonction de ce que la tâche exige réellement.

Quelles interfaces de recherche existent pour l'ingénierie contextuelle ?

Le contexte peut se trouver à différents endroits, par exemple sur le Web, dans un système de fichiers local ou dans une base de données. Un agent peut interagir avec chacune de ces sources de données hors contexte à l'aide de différents outils :

• Les outils Shell peuvent exécuter des commandes shell et accéder au système de fichiers local. Quelques exemples d’outils shell intégrés sont l’outil bash de Claude API, l’outil exécutif d’OpenClaw, et l’outil shell de LangChain.
• Les outils de base de données dédiés, tels que les outils d’un serveur Model Context Protocol (MCP) (par exemple, le serveur MCP Elastic Agent Builder) ou les outils personnalisés (par exemple, run_esql(query) ou db_list_index()), peuvent interroger les bases de données.
• Les outils de recherche de fichiers dédiés peuvent rechercher et lire des fichiers locaux (ou téléchargés) (sans accès complet au shell). Quelques exemples d'outils de recherche de fichiers intégrés sont l'outil de recherche de fichiers de Gemini API ou l'outil de recherche de fichiers d'OpenAI.
• Les outils de recherche Web peuvent extraire des informations du web.
• Les outils de mémoire stockent et rappellent la mémoire à long terme (quelle que soit la manière dont elle est stockée).

Comme vous pouvez le voir, l’outil shell est polyvalent et peut être utilisé pour récupérer du contexte à partir de différentes sources de données, notamment :

• Système de fichiers : l'agent explore la structure des répertoires (ls, find), recherche le contenu pertinent (grep, cat) et répète l'opération jusqu'à ce qu'il ait construit un contexte suffisant.
• Base de données : l’agent peut utiliser des outils d’interface en ligne de commande (CLI) de base de données (par exemple, elasticsearch-sql-cli), appeler des API HTTP via curl, ou exécuter des scripts, ce qui est particulièrement utile en combinaison avec les compétences de l’agent, qui sont des exemples réutilisables et documentés injectés dans le contexte de l’agent pour guider l’utilisation correcte des outils (par exemple, Elastic Agent Skills pour Elasticsearch).
• Web : l’agent peut exécuter des recherches web via une commande curl à travers l’API d’un fournisseur de recherche.

Cependant, l'outil shell fournit un accès système direct et nécessite donc des mesures de sécurité, telles que l'exécution dans un environnement sandbox isolé et le logging de toutes les commandes exécutées.

Quand utiliser quelles interfaces de recherche

L'interface de recherche appropriée dépend de vos données, de vos modèles de requête et de votre cas d'utilisation. Cette section constitue un point de départ pratique.

Les systèmes de fichiers ne rendent pas les bases de données obsolètes

Le débat entre systèmes de fichiers et bases de données ne porte pas sur la couche de stockage. Par exemple, LangChain explique que son système de mémoire ne stocke pas réellement la mémoire dans un véritable système de fichiers. Au lieu de cela, il stocke la mémoire dans une base de données et la représente sous la forme d'un ensemble de fichiers pour l'agent [3].

Les systèmes de fichiers sont particulièrement adaptés aux cas d'utilisation natifs basés sur les fichiers, tels que les agents de codage. Ils fonctionnent également bien comme bloc-notes temporaire ou mémoire de travail pour les scénarios à utilisateur unique ou à agent unique où la concurrence n'est pas une préoccupation. Dans ces cas, un système de fichiers physique ou la représentation des données sous forme de système de fichiers vous offre une certaine flexibilité avant de vous engager dans une interface dédiée.

Mais le stockage par système de fichiers présente de réels inconvénients, tels qu'une faible concurrence, l'application manuelle du schéma et les transactions atomiques. Ces problèmes deviennent plus évidents lorsque votre application doit scaler ou passer à un scénario multi-agents. Quiconque ignore ces inconvénients est condamné à réinventer péniblement des bases de données de moindre qualité, sans bénéficier des décennies d'ingénierie qui sous-tendent la sécurité des transactions ou le contrôle d'accès que les bases de données de production offrent déjà. De plus, dans la plupart des contextes d'entreprise, on ne choisit pas d'utiliser ou non une base de données puisqu'elle est déjà en place et stocke des données essentielles à l'activité.

Outil shell + système de fichiers

Un outil shell est le point de départ naturel pour la recherche dans le système de fichiers. Actuellement, les agents de codage sont à l'origine de nombreux progrès dans le champ. Parce qu'ils travaillent avec du code dans des fichiers locaux, ce sont naturellement des cas d'utilisation gourmands en fichiers. Par conséquent, les LLM sont affinés lors de la phase de post-entraînement pour les tâches de codage. C'est pourquoi de nombreux LLM savent non seulement écrire du code, mais aussi utiliser des commandes shell et naviguer dans les systèmes de fichiers.

L'utilisation d'un outil shell avec des CLI intégrées, comme ls et grep, pour rechercher des fichiers est efficace. Avec grep, une requête comme « Trouver tous les fichiers qui importent matplotlib» est rapide, précise et peu coûteuse. Mais lorsque l'agent doit gérer des requêtes conceptuelles, comme « Comment notre application gère-t-elle une authentification défaillante ? », La correspondance de motifs avec grep peut rapidement atteindre ses limites. Plusieurs alternatives qui apportent des capacités de recherche sémantique à la ligne de commande ont émergé pour combler ce manque, notamment jina-grep.

Cependant, grep et plusieurs de ses alternatives de recherche sémantique fonctionnent en O(n) sur le corpus. Pour les cas d'utilisation sur des bases de code, cela peut convenir. Cependant, si vos données s'accumulent, la latence deviendra perceptible. Dans ce cas, un datastore indexé devient nécessaire pour assurer la maintenance des performances.

Outil shell + base de données

Une autre façon d'ajouter des capacités de recherche, telles que la recherche sémantique ou hybride, à vos données est de les stocker dans une base de données, comme le fait Cursor, par exemple. De plus, lorsque les données nécessitent des jointures relationnelles complexes ou des agrégations, une interface de base de données est non négociable.

Lorsque les données se trouvent dans une base de données plutôt que dans le système de fichiers, un outil shell peut servir d'interface de base de données légère pour certains cas d'utilisation. Si vos requêtes sont assez simples pour une interface de ligne de commande ou un appel curl, un outil de base de données dédié peut ajouter de la complexité inutile.

Cette approche est également adaptée aux premières étapes de l’exploration, lorsque vous ne savez pas encore quels modèles de requête votre agent développera réellement. Dans ce cas, les compétences des agents peuvent donner à l’agent suffisamment de structure pour effectuer des requêtes correctement sans avoir recours à un outil spécialement conçu. Cependant, lorsque l'agent doit effectuer de nombreuses itérations pour déterminer la meilleure façon d'interroger la base de données pour des tâches répétitives, la surcharge de jetons associée à l'utilisation d'un outil shell comme interface ne justifie plus l'avantage de simplicité qu'offre l'évitement d'un outil supplémentaire.

Outil de base de données dédié

Des outils de base de données spécialisés deviennent nécessaires, surtout lorsque les modèles de requêtes répétées sont structurés ou analytiques. Un article de blog de Vercel et Braintrust a comparé des agents utilisant différents ensembles d'outils de recherche pour des tâches de récupération réelles sur des données semi-structurées, telles que les tickets de service client et les transcriptions d'appels de vente (par exemple : « Combien de problèmes ouverts mentionnent la « sécurité » ? » ou « Trouver les problèmes où quelqu'un a signalé un bug et où quelqu'un a ensuite soumis une PR prétendant le corriger ? »). [4].

Les agents utilisant des outils de base de données dédiés consommaient moins de jetons, étaient plus rapides et faisaient moins d'erreurs que ceux utilisant uniquement un outil shell et un système de fichiers. La leçon à retenir est que les outils de base de données directs constituent le meilleur choix lorsque la requête exige un raisonnement analytique sur des données semi-structurées.

Combinaison d'interfaces de recherche

Aucune interface de recherche unique ne traite correctement toutes les requêtes. Par exemple, Cursor combine des outils shell (pour les recherches via grep) et des outils de recherche sémantique, et permet à l'agent de sélectionner l'outil approprié en fonction de la requête de l'utilisateur. Ils indiquent que l'agent choisit grep pour faire correspondre des symboles ou des chaînes spécifiques, la recherche sémantique pour les questions conceptuelles ou liées au comportement, et les deux pour les tâches exploratoires.

L'expérience Vercel rapporte la même chose : son agent hybride, ayant accès à la fois à un outil en ligne de commande (shell) et à un outil de base de données dédié, a obtenu les meilleures performances parmi tous les agents testés, en utilisant d'abord les outils de base de données dédiés, puis en vérifiant les résultats en parcourant le système de fichiers avec la commande « grep ». Cependant, cette approche utilise plus de tokens et de temps pour le choix et la vérification des outils.

Le schéma est identique dans les deux exemples : la composition Beats toute interface unique, mais elle implique un compromis en termes de coût et de latence supplémentaires.

Recommandations pratiques pour trouver les bons outils

Le bon ensemble d'interfaces de recherche est restreint, ciblé et spécifique aux schémas de requêtes réels de votre agent. La bonne pratique actuelle est d'avoir un agent avec le moins d'outils possible au lieu d'avoir un agent avec des centaines d'outils MCP. En effet, le fait d'exposer d'emblée tous les outils possibles a pour inconvénient de gonfler la fenêtre contextuelle et d'embrouiller l'agent quant à l'outil à utiliser. Par exemple, Claude Code ne disposerait que d'une vingtaine d'outils.

L'idée de la divulgation progressive est plutôt de commencer avec un ensemble minimal d'outils et de laisser l'agent découvrir des capacités supplémentaires uniquement lorsqu'il en a besoin. Les recherches menées par Anthropic [5] et Cursor [6] ont montré que cette approche permet de réaliser une économie de tokens de 47%–85%. Claude Code, par exemple, implémente cela directement, permettant à l'agent de découvrir progressivement comment interroger une API ou une base de données, sans que cette connaissance ne consomme du contexte à chaque appel de LLM.

Une fois que vous vous êtes familiarisé avec les modèles de requête de l’agent, vous pouvez revoir l’ensemble des outils de recherche auxquels l’agent a accès par défaut. Une façon utile d'envisager ce compromis est le principe « plancher bas, plafond haut » pour décider quels outils doivent être retenus. Les outils à haut plafond ne limitent pas le potentiel de l’agent. Par exemple, un outil shell polyvalent permet à l’agent d’écrire des requêtes de base de données complètes, y compris celles ambiguës, mais au prix d’une surcharge de raisonnement, d’une latence plus élevée et d’une fiabilité moindre.

Les outils à plancher surbaissé sont à l'opposé. Ce sont des outils spécialisés qui répondent à des requêtes spécifiques et sont immédiatement accessibles à l'agent avec un minimum de frais de raisonnement, ce qui permet de réduire les coûts et d'accroître la fiabilité. Mais ils nécessitent un travail d’ingénierie préalable, ne peuvent pas couvrir toutes les requêtes possibles, et peuvent compliquer le choix du bon outil pour l’agent.

Pensez à chaque outil sur un spectre : les outils à seuil bas sont faciles à utiliser correctement par l'agent mais sont limités en portée. Les outils à haut potentiel sont polyvalents, mais nécessitent davantage de réflexion pour être utilisés efficacement.

La plupart des agents ont besoin d'une combinaison de différents outils de recherche. Mais chaque outil doit mériter son ajout. Nous recommandons de commencer par un outil de recherche polyvalent (par exemple un outil search_database() ou un outil shell). Réutilisez ensuite les logs de commandes que vous conservez déjà à des fins de sécurité pour suivre ce que votre agent fait réellement, y compris les appels d’outils, les nouvelles tentatives et le nombre d’appels par requête utilisateur. Et, lorsque vous voyez un modèle de requête se répéter ou échouer, c'est le signal pour créer un outil spécialement conçu à cet effet.

Résumé

Le débat système de fichiers contre base de données détourne l'attention de la véritable question que les ingénieurs doivent se poser : quelles sont les bonnes interfaces de recherche dont un agent a besoin pour construire son propre contexte ? La réponse est, selon toute vraisemblance, pas une seule.

Un outil shell est un outil polyvalent pour interagir avec différentes sources hors contexte et constitue ainsi un bon point de départ. Mais il est moins efficace et précis pour les cas d'utilisation avec des requêtes analytiques structurées que les outils de base de données dédiés.

L'objectif est de trouver l'ensemble minimal d'outils de recherche qui gère bien les modèles de requêtes réels de votre agent. Commencez avec un outil shell, et consignez ce que fait réellement votre agent dans les logs. Lorsque vous constatez qu'un schéma de requête se répète et échoue, il est temps de concevoir des outils spécialisés.

Références

1. Thariq (Anthropic). Leçons tirées de la construction du code Claude : voir comme un agent (2026).

2. Cursor : Documentation. Recherche sémantique et agentique (2026).

3. Harrison Chase (LangChain). Comment nous avons construit le système de mémoire d'Agent Builder (2026).

4. Ankur Goyal (Braintrust) et Andrew Qu (Vercel). Tester si « bash est tout ce dont vous avez besoin » (2026).

5. Anthropic. Présentation de l'utilisation d'outils avancés sur la plateforme de développement Claude (2025).

6. Cursor. Découverte dynamique du contexte (2026).

La soirée commence à s'animer

Vous organisez une fête de pizza. Vous avez quelques amis qui vous aident à servir, chacun posté à différents endroits dans la pièce. Vous offrez une pizza à chaque ami, et ils commencent à distribuer des tranches aux clients affamés à leur arrivée.

Au début, tout se passe bien. Les invités arrivent au compte-gouttes, vos amis servent des parts de pizza, tout le monde est content. Mais bientôt, la nouvelle de vos pizzas au levain se répand. On n'arrête pas de sonner à la porte. Les invités affluent. Très vite, une foule se forme autour de l'un de vos amis, celui qui tient la pizza pepperoni que tout le monde semble vouloir.

Votre ami avec la pizza au pepperoni est débordé. Les clients attendent, deviennent impatients et une longue file d'attente s'est formée. Pendant ce temps, votre ami avec la pizza margherita reste debout et presque personne ne lui demande une part.

Que faire ?

Vous commandez encore deux pizzas pepperoni et vous en distribuez à d'autres amis. Maintenant, trois amis ont de la pizza pepperoni au lieu d'un seul. La foule se disperse, et, tout à coup, vous pouvez servir trois fois plus d'invités à la fois.

Certains éléments deviennent clairs à mesure que vous organisez des fêtes :

• Les pizzas n'ont pas toutes le même succès. Certaines sont très demandées, d'autres moins. Inutile de prévoir des "exemplaires" supplémentaires de celles qui sont peu appréciées. Il vous faut davantage de celles qui attirent les foules.
• Commandez d'autres pizzas avant que la file d'attente ne devienne trop longue. Si vous attendez que votre ami soit complètement dépassé et que les invités partent mécontents, vous avez attendu trop longtemps. Mieux vaut commander une pizza supplémentaire quand vous voyez une foule se former.
• Ne jetez pas les pizzas trop vite. Ce n'est pas parce que la foule autour de la pizza pepperoni s'est clairsemée pendant cinq minutes que l'affluence est terminée. Peut-être sont-ils simplement en train de se resservir à boire, ou même de discuter entre eux (est-ce que ça se fait encore ?). Prévoyez des pizzas supplémentaires. Si l'accalmie se prolonge, vous pourrez les mettre de côté.
• Vous ne pouvez distribuer autant de pizzas que vous avez d'amis qui vous aident. Si vous n'avez que quatre amis pour vous aider, dix pizzas ne changeront rien au résultat. Seules quatre peuvent être servies à la fois. Adaptez le nombre de pizzas à vos serveurs disponibles.
• Quand un ami s'en va, prenez sa pizza. Si l'un de vos amis doit partir, prenez sa pizza immédiatement. Vous ne pouvez pas laisser les pizzas sans surveillance. Donnez-la à quelqu'un d'autre, ou mettez-la de côté.

Des pizzas aux répliques

Faisons le lien avec Elasticsearch.

Dans notre analogie, les pizzas sont des répliques (copies de vos shards d'index), vos amis qui aident à servir sont des nœuds de recherche, les invités affamés sont des requêtes de recherche, et cette pizza très prisée autour de laquelle se presse la foule correspond à un index très sollicité (hot) avec une charge de recherche élevée.

Lorsque le trafic de recherche augmente sur un indice donné, nous créons des répliques supplémentaires et les distribuons sur vos nœuds de recherche. Toute réplique peut traiter n'importe quelle requête pour cet index, tout comme un ami tenant une pizza pepperoni peut en distribuer des parts. Plus de répliques signifie un débit plus élevé : trois répliques peuvent traiter trois fois plus de requêtes par seconde qu'une seule réplique.

Mesurer la faim

Avant de décider du nombre de pizzas à commander, nous devons connaître l'appétit de la foule.

Elasticsearch suit la charge de recherche pour chaque partition. Cet indicateur mesure l'activité de recherche gérée par une partition. Nous agrégeons ces données pour l'ensemble des partitions d'un index afin d'appréhender la demande de recherche totale.

Ce qui importe le plus, c'est la charge de recherche relative : quelle proportion du trafic de recherche total de votre projet est allouée à chaque index ? Si un index reçoit 60 % des recherches tandis qu'un autre n'en reçoit que 5 %, nous savons où augmenter la capacité.

Les mathématiques derrière les pizzas

Nous calculons le nombre optimal de répliques en suivant cette formule :

desired_replicas = min(ceil(L × N / (S × X)), N)

Où :

• L = la charge de recherche relative de l'index (entre 0 et 1).
• N = le nombre de nœuds de recherche souhaités dans votre projet.
• S = le nombre de partitions dans l'index.
• X = un seuil pour éviter les points chauds (0,5 par défaut).

Un exemple : quatre nœuds de recherche, un index avec deux shards primaires recevant 80 % du trafic de recherche :

desired_replicas = min(ceil(0.8 × 4 / (2 × 0.5)), 4)
                 = min(4, 4)
                 = 4

Cet index hot obtient quatre répliques réparties sur les nœuds de recherche.

Le seuil X (0,5 par défaut) est important. Nous n'attendons pas qu'une réplique soit complètement saturée ; nous augmentons la capacité lorsqu'elle en est à la moitié. Distribuez les pizzas supplémentaires dès que vous voyez le monde arriver, et non lorsque les clients sont déjà partis.

Augmenter la capacité rapidement, la réduire lentement

Lorsque la charge de recherche augmente, nous ajoutons immédiatement des répliques. Inutile de faire attendre les utilisateurs.

Lorsque la charge de recherche diminue, nous attendons un peu avant d'agir. Nous devons observer une faible demande stable pendant environ 30 minutes avant de réduire le nombre de répliques. (Ceci afin de gérer les pics de trafic, où une période d'accalmie ne signifie pas que la charge est terminée.)

C'est important, car l'ajout d'une réplique a un coût. La nouvelle réplique copie les données et initialise ses caches avant de traiter efficacement les requêtes. Supprimer des répliques trop rapidement signifie payer constamment ce coût initial, car le trafic fluctue naturellement.

Respecter les limites de la topologie

Le nombre de répliques ne peut jamais dépasser le nombre de nœuds de recherche. Avoir plus de répliques que de nœuds n'apporte aucun avantage (vous ne pouvez servir qu'autant de pizzas que vous avez d'amis qui vous aident à en servir des parts).

Lorsque des nœuds sont retirés de votre projet, nous réduisons immédiatement le nombre de répliques en conséquence. Pas besoin d'attendre la fin du cooldown, car il ne peut y avoir de répliques non attribuées. Dès qu'un ami s'en va, nous retirons sa part.

Une vision plus globale du Serverless

Les répliques pour l'équilibrage de charge de recherche fonctionnent de pair avec d'autres systèmes d'autoscaling :

• L'autoscaling de la recherche ajuste le nombre de nœuds de recherche (combien d'amis aident).
• Les répliques pour l'équilibrage de la charge de recherche distribuent le trafic en ajustant le nombre de répliques par index (le nombre de pizzas de chaque type dont nous avons besoin).
• Le partitionnement automatique du flux de données optimise le nombre de partitions pour les écritures (comment découper chaque pizza, abordé dans l'article précédent).

Un principe de conception important : les répliques pour l'équilibrage de charge ne déclenchent pas directement l'autoscaling de la recherche. En répartissant les requêtes de recherche sur un plus grand nombre de répliques, nous pouvons augmenter l'utilisation des ressources sur l'ensemble de vos nœuds de recherche. Cette utilisation accrue active ensuite notre logique d'autoscaling existante afin d'ajouter de la capacité si nécessaire. Les répliques pour l'équilibrage de charge permettent à l'autoscaling de remplir sa fonction, en garantissant que vos nœuds de recherche sont effectivement utilisés, au lieu de voir tout le trafic se concentrer sur une seule réplique tandis que les autres nœuds restent inactifs.

Ce que cela signifie pour vous

Vous n'avez pas besoin de prédire quels index seront les plus sollicités. Vous n'avez pas besoin d'ajuster manuellement les répliques lorsque les schémas de trafic changent. Vous n'avez pas besoin de vous réveiller à 3 heures du matin parce qu'un pic de trafic a saturé votre index le plus sollicité.

Le système surveille les zones d'affluence et commande des pizzas supplémentaires pour ces zones. Les index peu sollicités ne gaspillent pas de ressources en répliques inutiles. Les index très sollicités obtiennent la capacité dont ils ont besoin. Votre budget est ainsi investi là où c'est le plus important.

Conclusion

Dans l'article sur le partitionnement automatique, nous avons veillé à ce que vos pizzas soient découpées correctement. Désormais, grâce aux répliques pour l'équilibrage de charge de recherche, nous nous assurons que vous ayez suffisamment de pizzas, entre de bonnes mains, lorsque la foule affamée arrive.

Essayez Elastic Cloud Serverless et laissez-nous nous occuper la logistique des pizzas.

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_completion pour 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.

Pour résoudre ce problème, les moteurs de recherche comme Elasticsearch utilisent deux stratégies d'optimisation principales :

1. Recherche approximative (hierarchical navigable small world [HNSW]) : au lieu de parcourir chaque document, nous construisons un graphe de navigation pour accéder rapidement au voisinage probable de la réponse.
2. Quantification : nous compressons les vecteurs (par exemple, de nombres flottants 32 bits à des entiers 8 bits ou même à des valeurs binaires 1 bit) afin de réduire l'utilisation de la mémoire et d'accélérer les calculs.

Mais l'optimisation s'accompagne souvent d'une taxe : la précision.

La crainte est légitime : "Si je compresse mes données et que je prends des raccourcis pendant la recherche, vais-je manquer les meilleurs résultats ?" "Cette optimisation dégrade-t-elle la pertinence de mon moteur de recherche ?"

Pour prouver que la quantification d'Elastic ne dégrade pas les résultats, nous avons construit un banc d'essai reproductible utilisant l'ensemble de données DBPedia-14 pour calculer exactement la précision (en particulier le rappel) que nous sacrifions pour la vitesse lorsque nous utilisons les optimisations par défaut dans Elasticsearch.

tldr : c'est probablement beaucoup moins cher que vous ne le pensez. Consultez le notebook ici, et essayez par vous-même.

Définitions (pour les non-experts)

Avant d'examiner le code, clarifions certains termes.

• Pertinence ou rappel : la pertinence est subjective (ai-je trouvé des choses intéressantes ?). Le rappel est mathématique. Si la base de données contient 10 documents qui correspondent parfaitement à votre requête sur le plan mathématique et que le moteur de recherche en trouve neuf, votre rappel est de 90 % (ou 0,9).
• Recherche exacte (à plat) : parfois appelée méthode "force brute". Le moteur de recherche analyse chaque document dans un index et calcule la distance.
  • Avantages : rappel parfait à 100 %.
  • Inconvénients : coût de calcul élevé et lenteur à grande échelle.
• Recherche approximative (HNSW) : la méthode "raccourci". Le moteur de recherche construit un graphe HNSW. Il parcourt le graphe pour trouver les voisins les plus proches.
  • Avantages : extrêmement rapide et scalable.
  • Inconvénients : vous risquez de manquer un voisin si le parcours du graphe s'arrête trop tôt.

L'expérience : exact versus approximatif

Pour tester le rappel, nous avons utilisé l'ensemble de données DBPedia-14, un grand ensemble de données de titres et de résumés répartis en 14 classes ontologiques, couramment utilisé pour l'entraînement et l'évaluation des modèles de catégorisation de texte. Plus précisément, nous nous concentrerons sur la catégorie "Film". Nous voulions comparer les paramètres de production optimisés à une vérité terrain mathématiquement parfaite.

Pour cette expérience, nous utilisons le modèle jina-embeddings-v5-text-small, un modèle multilingue de pointe qui fait référence dans le secteur de la représentation textuelle. Nous avons choisi ce modèle car il définit la norme actuelle pour les plongements lexicaux haute performance. En combinant l'excellente précision de Jina v5 avec la quantification native d'Elasticsearch, nous pouvons démontrer une architecture de recherche à la fois efficace en termes de calcul et garantissant une qualité de récupération optimale.

Nous avons configuré un index avec un double mapping. Nous avons ingéré le même texte dans deux champs différents simultanément :

1. content.raw avec le type : flat. Cela force Elasticsearch à effectuer une analyse exhaustive de l'ensemble des vecteurs Float32. Cette analyse renvoie des résultats de correspondance exacte qui serviront de référence.
2. content avec le type semantic_text. Paramètres par défaut utilisant HNSW + Better Binary Quantization (BBQ). Il s'agit du paramétrage standard optimisé pour la production, permettant une correspondance approximative.

Le test Recall@10

Pour notre métrique, nous avons utilisé Recall@10.

Nous avons choisi 50 films au hasard et lancé la même requête sur les deux champs.

• Si la recherche exacte (à plat) indique que les 10 premiers voisins sont les ID [1, 2, 3... 10].
• Et que la recherche approximative (HNSW) renvoie les identifiants [1, 2, 3… 9, 99].
• Nous avons trouvé neuf des 10 premiers correctement. Le score est 0,9.

Voici le mapping que nous avons utilisé :

# The "Control Group": Forces exact brute-force scan
"raw": {
    "type": "semantic_text",
    "inference_id": ".jina-embeddings-v5-text-small",
    "index_options": {
        "dense_vector": {
            "type": "flat"
        }
    }
}

Les résultats : la "ligne plate" du succès

Nous avons effectué un test d'échelle, en rechargeant l'ensemble de données complet et en le testant par rapport à des index de 1 000 à 40 000 documents.

Voici ce qui est arrivé au score de rappel :

Les résultats étaient incroyablement stables. Même en augmentant l'échelle, la recherche approximative correspondait à la recherche exacte par force brute >99 % du temps.

Pourquoi cela a-t-il si bien fonctionné ?

On pourrait s'attendre à ce que la compression des vecteurs en valeurs binaires nuise davantage à la précision. La raison en est liée à la façon dont Elasticsearch gère la récupération.

La plupart des modèles de plongement actuels génèrent des vecteurs Float32 en sortie, qui sont de grande taille. Pour optimiser la recherche, Elasticsearch utilise la quantification pour les vecteurs de grande dimension. Plus précisément, depuis la version 9.2, il utilise BBQ par défaut.

BBQ utilise un mécanisme de rescoring :

1. Parcours : le moteur de recherche utilise les vecteurs compressés (quantifiés) pour parcourir rapidement le graphe HNSW. Grâce à la petite taille des vecteurs, il peut effectuer un suréchantillonnage efficace, générant ainsi une liste plus longue de candidats (par exemple, les 100 documents les plus similaires) sans dégradation des performances.
2. Rescoring : une fois ces candidats identifiés, le système récupère les valeurs de pleine précision pour ces quelques documents uniquement afin de calculer le classement final et précis.

Vous obtenez le meilleur des deux mondes : la rapidité de la quantification pour les opérations les plus lourdes et la précision des nombres à virgule flottante pour le tri final.

Pouvons-nous faire mieux ?

Il est important de noter que les résultats présentés ici utilisent les paramètres par défaut et un échantillon aléatoire de données. Considérez-les comme un point de départ performant. Bien que Jina v5 soit extrêmement puissant, ces scores de rappel ne constituent pas une garantie universelle pour tous les ensembles de données. Chaque ensemble de données présente ses propres spécificités, et même s'il est possible d'optimiser davantage les paramètres pour obtenir des performances encore meilleures, il est toujours conseillé de réaliser des tests comparatifs avec vos propres données afin d'en déterminer les limites.

Conclusion

Il s'agit d'un test à très petite échelle. L'objectif de cet exercice n'est pas de mesurer le modèle d'intégration ou BBQ en particulier, mais de démontrer comment mesurer facilement le rappel de votre ensemble de données avec une configuration minimale.

Si vous souhaitez effectuer ce test sur vos propres données, vous pouvez consulter le notebook ici et essayer par vous-même.

L'extension est disponible en tant que projet open source ici.

Qu'est-ce que Gemini CLI et comment l'installer ?

Gemini CLI est un agent d’IA open source qui intègre les modèles Gemini de Google directement dans la ligne de commande. Il permet aux développeurs d’interagir avec l’IA depuis le terminal pour effectuer des tâches telles que générer du code, éditer des fichiers, exécuter des commandes shell et récupérer des informations sur le web.

Contrairement aux interfaces de chat classiques, Gemini CLI s'intègre à votre environnement de développement local, ce qui signifie qu'il peut comprendre le contexte du projet, modifier des fichiers, assurer l'exécution des compilations ou des tests et automatiser les workflows directement dans le terminal. Il est donc utile aux développeurs, aux ingénieurs de fiabilité des sites (SRE) et aux ingénieurs qui souhaitent un codage assisté par l'IA et une automatisation sans quitter leur workflow en ligne de commande.

Le CLI Gemini s’installe à l’aide de plusieurs gestionnaires de paquets. La méthode la plus courante passe par npm :

npm install -g @google/gemini-cli

Si vous souhaitez connaître d’autres options d’installation, consultez la page officielle d’installation.

Après l’installation, lancez la CLI en exécutant :

gemini

Vous voyez un écran, comme illustré sur la figure 1 :

Configurer Elasticsearch

Nous avons besoin d'une instance Elasticsearch en cours d'exécution. Si vous souhaitez utiliser le serveur Model Context Protocol (MCP), vous devez également installer Kibana 9.3+. Pour utiliser le langage de requête Elasticsearch (ES|QL) (esql) décrit ci-dessous, Kibana n’est pas requise.

Vous pouvez activer un essai gratuit sur Elastic Cloud ou l’installer localement en utilisant le script start-local :

curl -fsSL https://elastic.co/start-local | sh

Cela installera Elasticsearch et Kibana sur votre ordinateur et générera une clé API à utiliser pour configurer Gemini CLI.

La clé API sera affichée comme sortie de la commande précédente et stockée dans un fichier .env fichier dans le dossier elastic-start-local.

Si vous utilisez Elasticsearch sur site (par exemple, en utilisant start-local), et que vous souhaitez utiliser Elastic Agent Builder avec MCP, vous devez aussi connecter un grand modèle de langage (LLM). Vous pouvez consulter cette page de documentation pour comprendre les différentes options.

Si vous utilisez Elastic Cloud (ou Elastic Cloud Serverless), vous disposez déjà d’une connexion LLM préconfigurée.

Installez l'extension Elasticsearch

Vous pouvez installer l'extension Elasticsearch pour Gemini CLI avec la commande suivante :

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

Vous pouvez vérifier que les extensions ont été installées avec succès en ouvrant Gemini et en exécutant la commande suivante :

/extensions list

L'extension Elasticsearch devrait être disponible.

Si vous souhaitez utiliser l'intégration MCP, vous devez avoir une version d'Elasticsearch 9.3+ installée. Vous avez besoin de l’URL de votre serveur MCP depuis Kibana :

• Obtenez l'URL de votre serveur MCP dans Agents > Voir tous les outils > Gérer MCP > Copier l'URL du serveur MCP.
• L'URL se présentera comme suit : https://your-kibana-instance/api/agent_builder/mcp

Vous avez besoin de l’URL de l'endpoint Elasticsearch. Ce message apparaît généralement en haut de la page Elasticsearch de Kibana. Si vous utilisez Elasticsearch avec start-local, vous avez déjà l'endpoint dans la clé ES_LOCAL_URL dans le fichierstart-local .env.

Vous avez également besoin d’une clé API. Si vous exécutez Elasticsearch avec start-local, vous avez déjà le ES_LOCAL_API_KEY dans le fichier start-local .env. Sinon, vous pouvez créer une clé API en utilisant l’interface Kibana, comme indiqué ici :

• Dans Kibana : Stack Management > Security > Clés API > Créer une clé API.
• Nous suggérons de définir uniquement les privilèges de lecture pour la clé API, en activant le privilège feature_agentBuilder.read comme indiqué ici.
• Copiez la valeur de la clé API encodée.

Définissez les variables d'environnement requises dans votre shell :

export ELASTIC_URL="your-elasticsearch-url"
export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
export ELASTIC_API_KEY="your-encoded-api-key"

Installer l'ensemble de données d'exemple

Vous pouvez installer l'ensemble de données eCommerce orders disponible dans Kibana. Il comprend un seul index nommé kibana_sample_data_ecommerce, contenant des informations sur 4 675 commandes provenant d'un site web. Pour chaque commande, nous disposons des informations suivantes :

• Informations client (nom, identifiant, date de naissance, e-mail, etc.).
• Date de la commande.
• ID de commande.
• Produits (liste de tous les produits avec prix, quantité, identification, catégorie, réduction et autres détails).
• SKU.
• Prix total (hors taxes, taxes incluses).
• Quantité totale.
• Informations géographiques (ville, pays, continent, localisation, région).

Pour installer les données d'exemple, ouvrez la page Intégrations dans Kibana (recherchez « Intégrations » dans la barre de recherche supérieure) et installez l'ensemble de données « Échantillons de données ». Pour plus de détails, consultez la documentation ici.

Le but de cet article est de montrer à quel point il est facile de configurer la CLI Gemini pour se connecter à Elasticsearch et interagir avec l'index kibana_sample_data_ecommerce.

Comment utiliser le MCP d’Elasticsearch

Vous pouvez vérifier la connexion à l'aide de la commande suivante dans Gemini :

/mcp list

Le elastic-agent-builder devrait être activé, comme le montre la figure 2 :

Elasticsearch fournit un ensemble d'outils par défaut. Voir la description ici.

Grâce à ces outils, vous pouvez interagir avec Elasticsearch, en posant des questions telles que :

• Give me the list of all the indexes available in Elasticsearch.
• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

En fonction de la question, Gemini utilisera un ou plusieurs des outils disponibles pour tenter d'y répondre.

Les commandes /elastic

Dans l’extension Elasticsearch pour Gemini CLI, nous avons également ajouté /elastic commandes.

Si vous exécutez la commande /help, vous verrez toutes les options /elastic disponibles (Figure 3) :

Ces commandes peuvent être utiles si vous souhaitez exécuter directement un outil spécifique du serveur MCP elastic-agent-builder. Par exemple, en utilisant la commande suivante, vous pouvez obtenir le mapping de kibana_sample_data_ecommerce :

/elastic:get-mapping kibana_sample_data_ecommerce

Ces commandes sont essentiellement des raccourcis permettant d’exécuter des outils spécifiques, plutôt que de s’en remettre au modèle Gemini pour déterminer l’outil à invoquer.

Comment utiliser les compétences Elasticsearch

Cette extension inclut également une compétence d’agent pour ES|QL, le langage de requête canalisé d’Elasticsearch (ES|QL) disponible dans Elasticsearch. Agent Skills est un format ouvert qui fournit aux agents IA de codage, comme Gemini CLI, des instructions personnalisées pour des tâches spécifiques. Ils utilisent un concept appelé divulgation progressive, ce qui signifie que seule une brève description de la compétence est ajoutée au prompt système initial. Lorsque vous demandez à l’agent d’effectuer une tâche, comme interroger Elasticsearch, il fait correspondre la requête à la compétence pertinente et charge dynamiquement les instructions détaillées. Il s’agit d’un moyen efficace de gérer les budgets de tokens tout en fournissant à l’IA exactement le contexte dont elle a besoin.

La compétence esqlest conçue pour permettre à Gemini CLI d’écrire et d’exécuter des requêtes ES|QL directement sur votre cluster. ES|QL est un langage de requête puissant qui rend l'exploration des données, l'analyse des logs et les agrégations très intuitives. Avec cette compétence activée, vous n'avez pas besoin de rechercher la syntaxe ES|QL ; vous pouvez simplement poser des questions en langage naturel à l'interface en ligne de commande Gemini sur vos données, et l'agent se chargera du reste.

Les exécutions sont réalisées à l'aide de simples commandes curl lancées dans un terminal. L’intégration d’Elasticsearch à n’importe quelle architecture est simplifiée par la richesse de ses API REST.

Ce que la compétenceesql offre :

• Recherche d'index et de schémas : L'agent peut utiliser les outils intégrés de la compétence pour dresser la liste des index disponibles et récupérer le mapping des champs. Par exemple, avant d’écrire une requête pour l’ensemble de données eCommerce, l’agent peut effectuer une exécution de vérification de schéma sur kibana_sample_data_ecommerce afin de comprendre les champs disponibles, comme taxful_total_price ou category.
• Traduction transparente en langage naturel : La compétence donne à l'agent plus qu'un simple manuel de référence ; elle lui fournit un guide spécifique pour interpréter l'intention de l'utilisateur. Dès que vous tapez une demande en langage naturel, par exemple « Afficher le temps de réponse moyen groupé par service », l’agent s’appuie sur les modèles intégrés de la compétence pour convertir vos mots en commandes, filtres et agrégations ES|QL appropriés.
• Autocorrection : en cas d’échec d’une requête (erreur de syntaxe ou de type, par exemple), la compétence transmet la requête ainsi que l’erreur Elasticsearch précise. L’agent peut alors la rectifier immédiatement et retenter l’opération sans que vous ayez à intervenir.

Comme la compétence esql est également disponible sous forme d'outil sur le serveur MCP elastic-agent-builder, nous devons désactiver ce serveur temporairement. Vous pouvez utiliser la commande suivante pour le désactiver :

/mcp disable elastic-agent-builder

Ensuite, vous pouvez simplement taper une invite comme celle-ci dans votre interface de ligne de commande Gemini :

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

L’agent devra :

• Reconnaissez la nécessité de la compétence esql.
• Consultez le schéma de kibana_sample_data_ecommerce.
• Construisez une requête ES|QL, comme : FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.
• Exécutez la requête auprès de l’API Elasticsearch.
• Présentez la réponse finale directement dans le terminal.

Nous avons cité ici un exemple de réponse de Gemini à la question précédente :

───────────────────────────────────────────────────────────
> Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index   ───────────────────────────────────────────────────────────
✓  Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices,  …
Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: 
Showing up to 200 items (files + folders).                                                                     /home/user/.gemini/extensions/elasticsearch/skills/esql/                                                            ├───SKILL.md 
└───references/
├───esql-reference.md 
├───generation-tips.md 
└───query-patterns.md

✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue.

✓  Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS…                                                                                                                       {  
   "kibana_sample_data_ecommerce": { 
     "mappings": { 
       "properties": {
         "category": { 
           "type": "text", 
           "fields": {
             "keyword": {
               "type": "keyword"
             }
           }
         }, 
         "currency": {
           "type": "keyword"
         }, 

✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue.

✓  Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \  -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \  -H …
{ 
   "took": 62,
   "is_partial": false, 
   "completion_time_in_millis": 1772805644164,
   "documents_found": 4675,
   "values_loaded": 12084, 
   "start_time_in_millis": 1772805644102, 
   "expiration_time_in_millis": 1773237644087,  
   "columns": [ 
     { 
       "name": "total_revenue",    
       "type": "double"  
     }, 
     {   
       "name": "products.category.keyword",

✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a   user-friendly list.

 ✓  Shell 
                             
 Top 5 product categories by total sales revenue: 
 1. Men's Clothing: 149393.91
 2. Women's Clothing: 135099.91
 3. Women's Shoes: 105479.17
 4. Men's Shoes: 91797.92
 5. Women's Accessories: 60830.31 

✦ I've found the answer; now I'll format it for clarity.

 ✓  Shell 

 Here are the top 5 product categories by total sales revenue:                                                        
                                                                      
 | Rank | Category              | Total Revenue | 
 |------|-----------------------|---------------| 
 | 1    | Men's Clothing        | 149,393.91    |
 | 2    | Women's Clothing      | 135,099.91    |
 | 3    | Women's Shoes         | 105,479.17    |
 | 4    | Men's Shoes           | 91,797.92     | 
 | 5    | Women's Accessories   | 60,830.31     | 

✦ I've formatted and presented the answer. I'm finished.
 ───────────────────────────────────────────────────────────

Il est intéressant de noter comment le modèle Gemini génère la réponse finale en montrant toutes les étapes qu’il suit. On peut voir ici l’influence de la compétence sur la démarche de réflexion du modèle. Dès que le modèle identifie la nécessité d’utiliser une compétence ou d’exécuter une commande shell, il sollicite une autorisation via l’approche supervision humaine dans la boucle.

Grâce à la gestion automatisée de la découverte de schéma, de la génération de requêtes et de leur exécution, la compétence esql vous libère des contraintes techniques pour vous focaliser uniquement sur l’analyse des résultats. Vous obtiendrez les données dont vous avez besoin, correctement formatées et directement dans votre terminal, sans jamais écrire une seule ligne de code ni basculer vers une autre application.

Conclusion

Dans cet article, nous avons présenté l'extension Elasticsearch pour Gemini CLI que nous avons récemment publiée. Cette extension vous permet d'interagir avec votre instance Elasticsearch en utilisant Gemini et le serveur Elasticsearch MCP fourni par Elastic Agent Builder, disponible à partir de la version 9.3.0, ainsi que la commande /elastic.

De plus, l'extension comprend également une compétence esql qui convertit la demande d'un utilisateur en langage naturel en une requête ES|QL. Cette compétence est très pratique quand l’usage du serveur MCP est impossible, puisque les échanges s’appuient sur l’exécution de commandes curl basiques dans le terminal. L’intégration d’Elasticsearch à tous vos projets est simplifiée par la richesse de ses API REST. C’est particulièrement utile lors du développement d’applications d’IA agentique.

Pour plus d’informations sur notre extension Gemini CLI, visitez le dépôt de projets ici.

C'est pourquoi nous mettons en open source les compétences Elastic Agent : une expertise native de la plateforme pour Elasticsearch, Kibana, Elastic Observability et Elastic Security. Ajoutez-les dans l'environnement d'exécution de l'agent que vous utilisez déjà, et améliorez votre agent en le faisant passer d'un statut de "généraliste" qui devine un grand nombre de syntaxes à un statut d'expert, capable par exemple d'utiliser un grand nombre de normes architecturales comme le font les équipes d'ingénieurs d'Elastic. Cette première version technique se concentre sur les compétences avec une compatibilité maximale pour Elastic Cloud Serverless, mais évoluera rapidement pour inclure une meilleure prise en charge des anciennes versions de la pile.

De plus, Elastic résout ce problème sur les deux fronts. Pour les agents sur la plateforme Elastic, Elastic Agent Builder (désormais disponible en version générale) vous permet de créer et de discuter avec des agents IA qui héritent des contrôles d'accès de vos données, utilisent des outils de recherche et d'analyse intégrés, et travaillent en contexte aux côtés de vos tableaux de bord, alertes et investigations. Nous travaillons dur pour garantir des expériences exceptionnelles d’agent sur la plateforme Elastic. Mais tous les agents ne se trouvent pas au sein d’Elastic. Votre équipe utilise déjà Cursor, Claude Code ou d'autres environnements d'exécution, et ces agents doivent également maîtriser Elastic. C'est là que les compétences des agents entrent en jeu.

Pourquoi les agents rencontrent-ils des difficultés avec les plateformes spécialisées

Les grands modèles de langage (LLM) sont des généralistes remarquablement compétents. Ils peuvent écrire en Python, expliquer les manifestes Kubernetes et restructurer les composants React car leurs données d'entraînement sont riches en exemples. Mais lorsqu’il s’agit de travaux spécifiques à la plateforme, ceux qui impliquent des langages de requête propriétaires, des interfaces API complexes et des bonnes pratiques spécifiques à un domaine, ils échouent de manière prévisible.

Pour Elasticsearch, l'écart se manifeste concrètement :

• Le langage de requête Elasticsearch (ES|QL) est un nouveau domaine. Les LLM sont fortement entraînés au SQL, mais ES|QL est un langage de requête canalisé avec une syntaxe différente, des fonctions différentes et une sémantique différente. Les agents écrivent fréquemment des requêtes qui semblent plausibles mais ne s'analysent pas. Ils confondent WHERE et | WHERE, inventent des fonctions qui n'existent pas et passent complètement à côté du modèle de composition canalisé.
• Les surfaces API sont larges et profondes. Elasticsearch, Kibana et Elastic Security exposent des centaines d'API dans les domaines de la recherche, de l'ingestion, de l'alerting, des règles de détection, de la gestion des cas, des tableaux de bord et plus encore. Un agent ne disposant que de données d'entraînement générales doit deviner quel point de terminaison appeler, à quoi ressemble le corps de la requête et comment gérer la réponse. Il se trompe suffisamment souvent pour éroder la confiance.
• Les bonnes pratiques ne figurent pas dans les données d'entraînement. Quand devez-vous utiliser semantic_text plutôt qu'un pipeline de plongement personnalisé ? Comment structurer un pipeline d'ingestion pour un CSV de 10 Go ? Quelle est la bonne syntaxe de règle de détection pour une technique MITRE ATT&CK ? Les agents polyvalents ne disposent pas de connaissances spécifiques à Elastic organisées et structurées de manière fiable et chargées par défaut. Ils devraient aller les chercher, et même s'ils le faisaient, les documents bruts ne reflètent pas toujours les jugements et les bonnes pratiques que les praticiens qualifiés appliquent.

Résultat : les développeurs passent plus de temps à corriger les sorties des agents qu'à écrire le code eux-mêmes. Ce n'est pas l'expérience pour laquelle ils se sont engagés.

Compétences des agents : connaissances de la plateforme, destinées aux agents

Les compétences des agents sont des répertoires autonomes d'instructions, de scripts et de matériel de référence que les environnements d'exécution des agents peuvent charger de manière dynamique. Lorsqu’une compétence est active, l’agent a accès au bon contexte au bon moment : syntaxe de requête, modèles d’API, logique de validation, exemples pratiques, afin de pouvoir exécuter correctement les tâches du premier coup.

Chaque compétence suit la spécification ouverte agentskills.io : un dossier avec un fichier SKILL.md contenant des métadonnées et des instructions structurées. Aucun format propriétaire, pas de dépendance. Les compétences fonctionnent à travers les environnements d'exécution des agents, notamment Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini CLI, Cline, Codex, et bien d’autres.

Contenu de la version initiale v0.1.0

Le premier ensemble de compétences couvre cinq domaines de l’Elastic Stack :

• Interagir avec les API Elasticsearch (recherche, indexation, clustering)
• Création et gestion de contenu Kibana tels que les tableaux de bord, les alertes, les connecteurs et plus encore.
• Expertise de domaine pour Elastic Observability
• Expertise de domaine pour Elastic Security
• Créer des agents efficaces dans Agent Builder

Les compétences sont composables

Les compétences ne sont pas monolithiques. Elles sont modulaires de par leur conception. Votre agent charge uniquement les compétences pertinentes pour la tâche en cours. Vous travaillez sur une requête ES|QL ? La compétence ES|QL est activée. Vous souhaitez créer un tableau de bord à partir de ces résultats ? La compétence tableaux de bord se lance. Évaluer la santé de votre application ? La compétence de santé des services entre en jeu. Enquêter sur une alerte de sécurité ? Les compétences de triage s'enchaînent avec celles de gestion de cas et de réponse au fur et à mesure que l'enquête progresse.

Cette composabilité signifie que vous n'avez pas besoin d'une invite unique et massive qui tente de tout couvrir. Chaque compétence comporte exactement le contexte requis par son domaine, ni plus ni moins.

Pour les développeurs d'applications de recherche et d'IA

Si vous chargez des données dans Elasticsearch, que vous rédigez des requêtes ou que vous migrez des index, les compétences réduisent le cycle de génération de code, de détection d'erreurs et de recherche dans la documentation pour trouver ce qui n'a pas fonctionné.

Demandez à votre agent de charger un fichier CSV ; celui-ci utilisera un outil d’ingestion en continu qui gérera la contre-pression et déduira les mapping à partir des données. Il ne s'agit pas d'une boucle _bulk exécutée à la main qui épuise la mémoire dès le premier fichier volumineux. Demandez-lui de faire une requête auprès d’ES|QL, et il découvre vos véritables noms d’index et schémas de champs, puis écrit des requêtes valides canalisées avec la bonne syntaxe, les agrégations appropriées et la sélection de fonctionnalités adaptée à la version, et non une supposition SQL nécessitant trois tours de débogage. Demandez-lui de réindexer sur plusieurs clusters, et il suit le workflow complet : il crée la destination avec des mappings explicites, ajuste les paramètres de débit, effectue l'exécution de la tâche de manière asynchrone et restaure les paramètres de production une fois celle-ci terminée, et non pas un simple appel _reindex qui saute la moitié des étapes qu’un opérateur expérimenté suivrait.

Au lieu d'un agent qui vous donne un point de départ plausible à corriger, vous en obtenez un qui encode la discipline opérationnelle qui permet à la sortie de fonctionner réellement.

Exemples d'impacts de l'utilisation des compétences d'Elastic Agent

Pour les équipes de sécurité

Security répète quotidiennement les mêmes workflows opérationnels : trier les alertes, ajuster les règles de détection, gérer les dossiers. Les compétences de l'agent encodent ces connaissances procédurales afin que votre agent IA puisse exécuter correctement ces workflows, en appelant les bonnes API dans le bon ordre et avec les bons noms de champ. Pour une présentation pratique qui vous permettra de passer de zéro à un environnement Elastic Security complet sans quitter votre IDE, consultez la section Prise en main d'Elastic Security depuis votre agent d'IA.

Pour les équipes d'observabilité et d'opérations

Les nouvelles compétences des agents pour Elastic Observability réduisent les tâches opérationnelles liées à l'instrumentation de systèmes complexes, à la gestion des SLO, au tri des données complexes et à l'évaluation de l'état des services. L'intégration de l'expertise native d'Elastic directement dans les agents IA permet aux équipes d'exécuter des workflows d'observabilité complexes en utilisant un langage naturel simple. Cela permet aux équipes SRE et chargées des opérations de résoudre les incidents plus rapidement et d'assurer la maintenance de systèmes fiables plus facilement. Pour en savoir plus, consultez cet article de blog.

Open source, spécifications ouvertes, piloté par la communauté

Nous publions les compétences d'agent sous la licence Apache 2.0, car nous pensons que les connaissances des agents doivent être ouvertes. La spécification agentskills.io que suivent les compétences est un standard ouvert, et non un format propriétaire d'Elastic. Nous voulons que les compétences soient le fruit d'un effort communautaire, et non d'un lieu clos.

Une partie d'un tableau plus vaste

Agent Skills fait partie d'une initiative plus vaste visant à faire d'Elasticsearch la plateforme de données la plus adaptée aux agents disponible sur le marché. Pour les agents hébergés sur la plateforme Elasticsearch, Agent Builder va plus loin en reprenant les contrôles d'accès et les autorisations de vos données, en fournissant des outils intégrés et personnalisés pour la recherche et l'analyse, et en permettant aux utilisateurs d'interagir avec les agents en contexte, au sein de leurs tableaux de bord, alertes et enquêtes. Enfin, la prise en charge des compétences sera bientôt disponible dans Agent Builder, offrant aux développeurs la flexibilité nécessaire pour tirer parti des compétences Elastic Agent ainsi que de celles provenant de toute autre source, afin de permettre un chat sécurisé et enrichi par le contexte, ainsi qu'une automatisation sur la plateforme Elasticsearch.

Pour les agents qui vivent ailleurs, nous investissons dans l'écosystème ouvert :

• Extension du serveur Model Context Protocol (MCP) : Extension du point de terminaison MCP dans Agent Builder avec davantage d'outils au-delà des opérations actuelles de recherche, ES|QL et d'index.
• Améliorations de l'authentification : faciliter la connexion sécurisée des agents, dans le but d'éliminer le copier-coller manuel des clés API.
• Documentation lisible par LLM : publication des fichiers llms.txt et AGENTS.md afin que les agents puissent découvrir et comprendre les API Elastic par eux-mêmes.
• Une interface de ligne de commande (CLI) pour les flux de travail des agents : Un outil de ligne de commande qui facilite la gestion des connexions et les opérations courantes pour les agents.

Les compétences sont la partie que vous pouvez utiliser aujourd'hui. Le reste est à venir.

Lancez-vous

Avant de commencer : Les agents de codage d’IA fonctionnent avec de vraies informations d’identification, un véritable accès au shell et, souvent, avec toutes les autorisations de l’utilisateur qui les exécute. Lorsque ces agents sont orientés vers des workflows de sécurité, les enjeux sont plus élevés : vous confiez à un système automatisé l’accès à la logique de détection, aux actions de réponse et aux télémétries sensibles. Le profil de risque de chaque organisation est différent. Avant d’activer les workflow de sécurité pilotés par l’IA, évaluez les données auxquelles l’agent peut accéder, les actions qu’il peut entreprendre et ce qui se passe s’il se comporte de manière inattendue.

Installez les compétences Elastic Agent dans votre environnement d'exécution de l'agent :

npx skills add elastic/agent-skills

Cela détecte automatiquement vos agents d'exécution installés et place les compétences dans le répertoire de configuration approprié. A partir de là, votre agent les récupère automatiquement.

Vous pouvez également consulter directement le catalogue de compétences et installer manuellement des compétences individuelles en copiant le dossier de compétences dans le répertoire de configuration de votre agent.

Vous n'avez pas encore de cluster Elasticsearch ? Démarrer un essai gratuit d'Elastic Cloud. Il faut environ une minute pour obtenir un environnement entièrement configuré.

Explorez le projet :

• Répertoire des compétences des agents
• Spécifications d'agentskills.io
• Documentation Elasticsearch
• Essai gratuit d'Elastic Cloud

Comme nous l’avons vu dans l’article précédent, cette régularité, permise par l’appel de fonctions, constitue la pierre angulaire de la fiabilité du système, bien au-delà d’un simple gain d’efficacité. Une fois que nous avons éliminé les erreurs structurelles de la boucle d'évaluation, les résultats sur les scénarios standards (tels que ceux du jeu de données de niveau 4) se sont considérablement améliorés.

Il reste cependant une interrogation manifeste à laquelle il nous faut répondre :

Cette méthode est-elle toujours viable lorsque les données et les processus s’avèrent véritablement désordonnés ?

En pratique, ce ne sont pas les cas élémentaires qui mettent en défaut les systèmes de réconciliation d’entités. La résolution d’entités s’effondre dès que les noms se heurtent à la diversité des langues, des contextes culturels, des alphabets, des périodes historiques ou des structures administratives différentes. Le système s’effondre quand l’identification repose sur des titres honorifiques, des changements de noms de sociétés ou des translittérations aléatoires, et que seul le contexte environnant permet d’identifier l’entité physique derrière la mention textuelle.

Donc, pour le dernier billet de cette série, nous avons soumis le système à ce que nous avons appelé le défi ultime.

Qu’est-ce qui fait de ce test le « défi ultime » ?

Nous avons soumis le système à des tests progressifs, en employant des ensembles de données de plus en plus sophistiqués au fil des étapes de validation. Au moment d’atteindre le palier 4, le système gérait déjà des données hybrides mêlant appellations familières, titres honorifiques et variantes linguistiques, exigeant une analyse contextuelle fine. Les tests ont prouvé la pertinence de l’architecture globale, tout en révélant que des erreurs de structure de données, comme des syntaxes JSON incorrectes, bridaient artificiellement les performances de récupération.

Avec les appels de fonctions en place, nous avions enfin une base stable. Cela nous a donné l'occasion de poser une question plus intéressante :

Un pipeline unifié peut-il gérer plusieurs types de problèmes de résolution d'entités simultanément ?

Cet ensemble de données de test a été élaboré spécifiquement pour mettre à l’épreuve cette variable critique, en ne laissant aucune place à l’approximation.

Au lieu de se concentrer sur une seule difficulté (comme les surnoms ou la translittération), cet ensemble de données combine plus de 50 types de défis distincts, notamment :

• Conventions de dénomination culturelles.
• Références basées sur les titres.
• Relations commerciales et changements historiques de nom.
• Mentions multilingues et systèmes d’écriture croisés.
• Des défis complexes qui combinent plusieurs des éléments ci-dessus.

L'essentiel, ce n'est pas d'optimiser pour un cas d'utilisation restreint. Il s'agit de vérifier si le modèle de conception tient la route lorsque les règles changent d'une entité à l'autre.

L'ensemble de données en un coup d’œil

L'ensemble de données du défi ultime consiste en :

• 50 entités, couvrant des personnes, des organisations et des institutions.
• ~60 articles, dont la structure et la complexité linguistique varient.
• 51 catégories de défis distinctes, regroupées globalement en :
  • Conventions de dénomination culturelles.
  • Titres et contexte professionnel.
  • Relations commerciales et organisationnelles.
  • Les défis du multilinguisme et de la translittération.
  • Scénarios combinés et cas limites.

Plus tôt dans cette série, nous avons vu que l’utilisation de l’IA générative (GenAI) pour créer des jeux de données peut s’avérer être une arme à double tranchant. Sans elle, il serait extrêmement difficile de rassembler des données de test suffisamment vastes et diversifiées. Toutefois, sans un contrôle rigoureux, le modèle incline naturellement vers la simplification des cas de test.

On a remarqué, lors d’un premier passage de génération, que l’IA avait inséré des mentions telles que « le président russe » comme synonymes directs dans la fiche d’identité de Vladimir Poutine. Bien que cela paraisse logique à première vue, une telle approche invalide le test en supprimant la nécessité de comprendre le contexte pour identifier l’entité. Que se passe-t-il si l’article traite de la Russie des années 1990 ? L’objectif est que l’intelligence du moteur réside dans sa capacité d’inférence contextuelle plutôt que dans une simple table de correspondance statique.

C'est pourquoi cet ensemble de données a été délibérément conçu pour que les raccourcis ne fonctionnent pas. Les alias ne sont pas explicitement énumérés lorsque le système est censé en déduire la signification. Les phrases descriptives ne sont pas pré-liées à des entités. Les bonnes correspondances dépendent souvent du contexte de l'article, et pas seulement du texte local.

Remarque importante : bien que nous démontrions les capacités du système dans divers scénarios, il s'agit toujours d'un prototype éducatif. Les systèmes de production gérant la surveillance d'entités sanctionnées dans le monde réel nécessiteraient une validation supplémentaire, des contrôles de conformité, des pistes d'audit et une gestion spécialisée pour les cas d'utilisation sensibles.

Pourquoi ces scénarios sont difficiles

Dès le premier article de cette série, nous avons introduit un exemple simple mais ambigu : « La nouvelle mise à jour de Swift est arrivée ! » Le défi réside dans le fait que « Swift » peut renvoyer à plusieurs entités du monde réel, selon le contexte. Cet exemple illustre une vérité plus profonde : le langage naturel est intrinsèquement ambigu.

La résolution d’entités n’est donc pas seulement un problème de correspondance de chaînes de caractères. Nous utilisons instinctivement notre bagage culturel et le contexte immédiat pour interpréter les références, une opération mentale si fluide qu’elle nous semble totalement naturelle.

Voici quelques cas courants :

• L’expression « le président » est une coquille vide si elle n’est pas ancrée dans une géographie et une époque données.
• Le nom d’une entreprise peut désigner une société mère, une filiale ou une ancienne marque, selon la date à laquelle l’article a été rédigé.
• Le nom d’une personne peut apparaître dans des ordres différents, des alphabets variés ou des translittérations diverses, selon la langue et la culture.
• La même phrase peut légitimement faire référence à des entités différentes dans des contextes différents, et le système doit être en mesure de rejeter les correspondances avec autant d'assurance qu'il les accepte.

Aucun système de règles figées ne peut, à lui seul, traiter l’intégralité de ces nuances de manière satisfaisante. Cette approche explique pourquoi ce prototype applique une séparation des préoccupations aussi stricte :

• Elasticsearch réduit l'espace réservé aux candidats de manière efficace et transparente.
• Le LLM n’est utilisé que là où un jugement est requis, et il est contraint de justifier sa décision.
• La récupération et le raisonnement demeurent des étapes distinctes.

Cette distinction devient encore plus importante à mesure que la diversité des types de défis augmente.

Comment le système gère la diversité sans recourir à des cas particuliers

L'un des résultats les plus intéressants de cette évaluation est ce qui n’a pas changé :

• Nous n'avons pas ajouté de logique spéciale pour les noms japonais.
• Nous n'avons pas ajouté de règles personnalisées pour les patronymes arabes.
• Nous n'avons pas ajouté de mapping codé en dur pour les noms d'entreprises historiques.

À la place, le système s’est appuyé sur les mêmes ingrédients fondamentaux présentés plus tôt dans cette série :

• Entités enrichies par le contexte et indexées pour la recherche sémantique.
• La récupération hybride (exacte, alias et sémantique) dans Elasticsearch.
• Un ensemble restreint et bien défini de candidats.
• Le jugement du LLM est contraint par l’appel de fonctions et des schémas minimaux.

Cela suggère que la flexibilité du système provient de la représentation et de l'architecture, et non d'une collection de règles qui ne cesse de croître.

Lorsque le système réussit, c’est parce que les bons candidats ont été récupérés et que le LLM dispose d’assez de contexte pour expliquer pourquoi une référence correspond (ou non) à une entité spécifique.

Résultats : Comment s’est-il comporté ?

Sur l’ensemble de données du défi ultime, le système a produit les résultats globaux suivants :

• Précision : ~91 %
• Rappel : ~86 %
• Score F1 : ~89 %
• Taux d'acceptation des LLM : ~72 %

Performances selon les types de défis

L’analyse des résultats par type de défi révèle des forces et des limites bien précises :

Les performances les plus solides (un score F1 de 100 %) ont été observées dans des domaines tels que :

• Appariement entre différents systèmes d’écriture (entités commerciales en cyrillique, coréen ou chinois).
• Scénarios en hébreu (patronymes, titres professionnels, titres religieux, translittération).
• Hiérarchies d’entreprises (aérospatiale, industrie diversifiée, conglomérats multidivisionnels).
• Titres professionnels (académiques, militaires, politiques, religieux).
• Scénarios japonais combinés impliquant plusieurs systèmes d'écriture.

Une performance solide (score F1 de 80 à 99 %) a été enregistrée dans les catégories suivantes :

• Personnalités politiques internationales (98 %).
• Changements de noms historiques (90 %).
• Hiérarchies d’entreprise complexes (89 %).
• Noms de sociétés japonais (93 %).
• Translittération entre différents systèmes d’écriture (86 %).
• Patronymes arabes (86 %).

Les domaines les plus difficiles sont les suivants :

• Translittération avancée (chinois, coréen) : 0 % F1.
• Certains scénarios japonais (titres honorifiques, ordre des noms, variations du système d’écriture) : ~67 % F1.
• Quelques scénarios en arabe (noms d'entreprises, références institutionnelles) : ~40 % F1.

Ce qui importe ici, c’est de comprendre pourquoi le système a éprouvé des difficultés dans ces cas précis. Les échecs n’étaient pas dus à une défaillance de l’approche globale, mais à des limitations de composants spécifiques, tout particulièrement le modèle de vecteurs denses utilisé pour la recherche sémantique dans certains scénarios multilingues.

La recherche et le jugement étant clairement séparés, il n’est pas nécessaire de réécrire le système pour améliorer les performances. L’intégration d’un modèle d’embedding multilingue plus performant, l’enrichissement du contexte des entités ou l’affinement des stratégies de récupération amélioreraient les résultats dans ces catégories sans modifier l’architecture de noyau.

Du point de vue architectural, c’est le véritable indicateur de réussite.

Ce que ces résultats nous révèlent sur l'architecture du système

Si l'on considère l'ensemble de la série, quelques tendances se dégagent :

• La préparation est plus importante qu'une combinaison intelligente. L’enrichissement des entités avec leur contexte dès le départ réduit considérablement l’ambiguïté par la suite.
• Les LLM sont bien plus précieux en tant que juges qu’en tant qu’outils de recherche. Leur demander d'expliquer pourquoi une correspondance est logique est bien plus efficace que de leur demander de rechercher.
• La fiabilité permet la précision. L'appel de fonction n'a pas seulement nettoyé le JSON ; il a débloqué la récupération qui était déjà latente dans l'étape de récupération.
• La généralisation l’emporte sur la spécialisation. Un petit nombre d’abstractions bien choisies a permis de gérer des dizaines de types de défis sans avoir recours à une logique personnalisée.

Cette approche explique pourquoi le prototype s’appuie nativement sur Elasticsearch tout en limitant l’usage des modèles de langage à une stricte nécessité. L’objectif n’est pas de se substituer aux moteurs de recherche classiques, mais d’apporter une couche d’explication quand la compréhension du contexte est cruciale.

Conclusions

L’enjeu final n’était pas d’atteindre des statistiques idéales, mais de s’attaquer à une interrogation bien plus essentielle :

Une architecture transparente, axée sur rechercher et assistée par LLM, peut-elle gérer l'ambiguïté des entités du monde réel sans s'effondrer en règles ou en boîtes noires ?

Pour ce prototype pédagogique, la réponse est oui, avec des réserves explicites concernant la mise en production, la conformité, la surveillance et la qualité des données. Si vous concevez des systèmes devant justifier pourquoi une correspondance d’entités a été établie, ce modèle mérite une attention toute particulière. J’espère que cette série de publications a démontré que la résolution d’entités n’a rien d’un processus mystérieux. Avec une séparation adéquate des responsabilités, la résolution d’entités devient un processus que l’on peut analyser, mesurer et améliorer.

Ce travail suggère également un modèle d’architecture plus large. On voit apparaître ici un glissement méthodologique important par rapport à l’architecture RAG classique. Au lieu de laisser la recherche alimenter directement la génération, nous introduisons une étape d’évaluation explicite. Le LLM est d’abord utilisé pour juger et vérifier la pertinence des candidats récupérés, et seuls les résultats approuvés sont autorisés à enrichir la génération. Vous pouvez voir cela comme un « Generation-Augmented Retrieval-Augmented Generation with Evaluation », ou GARAGE, parce que tout le monde adore les bons acronymes.

Quels autres cas d'utilisation pourraient bénéficier de ce modèle ? Les systèmes exigeant de la confiance, de la transparence et un raisonnement défendable sont des candidats naturels pour ce modèle. Les travaux futurs dans ce domaine s’annoncent tout aussi passionnants que les résultats présentés ici, et j’ai hâte de voir comment la communauté s’en emparera pour la suite.

Prochaines étapes : À vous de jouer

Envie de voir comment ce système relève le défi le plus complexe ? Consultez le carnet de notes Ultimate Challenge pour une présentation complète avec des implémentations réelles, des explications détaillées et des exemples pratiques.

Le pipeline complet de résolution d'entités démontre les concepts fondamentaux et l'architecture nécessaires à une utilisation en production. Cette structure sert de fondation pour bâtir des outils de veille médiatique capables d’identifier des entités et de justifier chaque correspondance, garantissant ainsi la traçabilité des informations extraites.

Dans HNSW, la recherche s'effectue par expansion itérative des nodes candidats dans le graphe, en conservant un ensemble limité des voisins les plus proches découverts jusqu'à présent. Chaque expansion a un coût (opérations vectorielles, recherches aléatoires sur disque, etc.), et le bénéfice marginal de ce coût tend à diminuer à mesure que la recherche progresse.

Une façon d'optimiser le parcours du graphe HNSW est d'interrompre la recherche lorsque la probabilité marginale de trouver de nouveaux les plus proches n'augmente plus. C'est pourquoi, dans Elasticsearch 9.2, nous avons introduit un nouveau mécanisme d'arrêt précoce. Ce mécanisme interrompt la recherche lorsque la visite des nodes du graphe ne fournit pas suffisamment de nouveaux voisins les plus proches, de façon consécutive, pendant un nombre déterminé de fois.

Cet article explique comment nous avons amélioré le mécanisme mentionné d'arrêt précoce dans HNSW afin de mieux l'adapter à différents ensembles de données et distributions de données.

Arrêt précoce dans HNSW

Dans HNSW, la recherche se déroule en étendant itérativement les nodes candidats dans le graphe de proximité, en conservant un ensemble limité des voisins les plus proches découverts jusqu'à présent, jusqu'à avoir exploré l'ensemble du graphe ou répondu à certains critères d'arrêt précoce.

L'arrêt précoce n'est donc pas toujours une optimisation ; il fait partie intégrante de l'algorithme de recherche lui-même. Le moment où nous décidons d'interrompre la recherche détermine l'équilibre entre l'efficacité et le rappel. Dans Elasticsearch, il existe déjà plusieurs façons d'interrompre prématurément une requête sur HNSW :

• Un nombre maximal déterminé de nodes est exploré.
• Un délai d'expiration déterminé est atteint.

Bien que simples et prévisibles, ces règles sont largement indépendantes de ce qu'effectue réellement la recherche. De plus, elles servent principalement à garantir que la requête se termine dans un délai raisonnable pour l'utilisateur final.

Dans un article de blog précédent, nous avons introduit le concept de redondance dans HNSW. En bref, les calculs redondants se produisent lorsque HNSW continue d'évaluer de nouveaux nodes candidats qui ne permettent pas de trouver davantage de voisins les plus proches.

Patience : mesurer les progrès plutôt que les efforts

La notion de patience recadre l'arrêt précoce sur le progrès plutôt que sur l'effort.

Au lieu de demander :

"Combien d'étapes avons-nous franchies ?"

La nouvelle question devient :

« Quelle est la quantité de calcul que nous acceptons de gaspiller, jusqu'à ce que nous perdions espoir ? »

Lors d'une recherche HNSW, l'exploration précoce génère généralement des améliorations maximales de l'ensemble des k meilleurs candidats. Au cours des premières étapes de l'exploration du graphe HNSW, l'ensemble des voisins est mis à jour en continu à mesure que l'algorithme découvre des voisins de plus en plus proches du vecteur de requête. Avec le temps, ces améliorations deviennent plus rares à mesure que la recherche converge. L'arrêt basé sur la patience surveille ce schéma et interrompt la recherche lorsque les améliorations cessent de se produire pendant une période prolongée.

En pratique, lors de l'exploration du graphe HNSW, nous calculons également le taux de saturation de la file d'attente à chaque étape du parcours des nodes candidats. Ce taux mesure le pourcentage de voisins les plus proches restés inchangés lors de la visite du dernier node du graphe (ou l'inverse du nombre de nouveaux voisins introduits lors de la dernière itération). Si ce taux devient trop élevé pendant plusieurs itérations consécutives, l'exploration du graphe est interrompue.

D'un point de vue conceptuel, la patience considère la recherche HNSW comme un processus à rendements décroissants. Lorsque les rendements se stabilisent, continuer à explorer le graphe apporte peu d'avantages.

Ce recadrage est puissant car il lie directement l'arrêt aux résultats observables plutôt qu'à des limites fixes arbitraires.

L'avantage de cette technique d'arrêt précoce intelligent est que les explorations de graphes HNSW ont tendance à visiter un nombre plus restreint de nodes tout en conservant un rappel relatif quasi parfait.

Pour visualiser cela, nous pouvons tracer le nombre de rappels par node visité que nous avons obtenus avec l'arrêt précoce basé sur la patience (étiqueté et=static), par rapport au comportement par défaut du HNSW (étiqueté et=no) sur quelques ensembles de données, FinancialQA et Quora, ainsi que des modèles JinaV3 et E5-small.

Seuils statiques et dynamiques HNSW

Dans Elasticsearch, cela se traduit concrètement par l'utilisation de seuils statiques. Le premier seuil correspond au seuil de saturation, c'est-à-dire le niveau de saturation que nous considérons comme sous-optimal. Le second seuil correspond au nombre de nodes consécutifs du graphe pouvant être visités tout en maintenant une saturation de la file d'attente sous-optimale, soit le seuil de patience.

Lors de l'introduction de cette stratégie d'arrêt précoce dans Elasticsearch 9.2, nous avons opté pour des valeurs par défaut prudentes afin de maximiser le rappel tout en optimisant la latence et la consommation de mémoire. C'est pourquoi nous avons fixé le seuil de saturation à 100 % et le seuil de patience à 30 % (limité) de la valeur de num_candidates dans la requête KNN.

Dans de nombreux cas, ces paramètres ont donné de bons résultats. Cependant, deux requêtes demandant le même nombre de voisins peuvent avoir des comportements de convergence radicalement différents. Certaines requêtes rencontrent des voisinages locaux denses et saturent rapidement ; d'autres doivent parcourir de longs chemins épars avant de trouver des candidats compétitifs. Ces dernières se sont avérées les plus difficiles à gérer efficacement.

De ce fait, nous avons parfois constaté :

• Une surexploration pour les requêtes simples.
• Un arrêt prématuré pour les requêtes complexes.

Nous avons donc estimé que les valeurs de seuil déterminées codifiaient des hypothèses globales sur la convergence, alors que nous pouvions mieux adapter le HNSW à différentes dynamiques.

Rendre l'arrêt précoce de HNSW adaptatif

L'arrêt précoce adaptatif aborde ce problème sous un angle différent. Au lieu d'imposer des seuils d'arrêt prédéfinis, l'algorithme détermine le moment où il doit s'arrêter à partir de la dynamique de recherche elle-même.

Ainsi, au lieu de comparer le taux de saturation de la file d'attente entre deux candidats consécutifs, nous avons décidé d'introduire à la fois un taux de découverte lissé instantané $d_{q,i} $ (combien de nouveaux voisins ont été introduits pour une requête q lors de la dernière visite i), ainsi qu'une moyenne glissante $\mu_{q,i}$ et un écart-type $\sigma_{q,i}$ d'un tel taux de découverte pendant la visite du graphe (en utilisant l'algorithme de Welford). Ces statistiques sur le taux de découverte sont calculées par requête, permettant ainsi de déterminer différents niveaux de patience pour chacune d'entre elles.

Les seuils auparavant statiques deviennent adaptatifs aux statistiques du taux de découverte : le seuil de saturation devient la moyenne mobile plus l'écart type, tandis que nous faisons en sorte que la patience s'adapte et évolue inversement avec l'écart type.

Les règles de sortie précoce restent les mêmes ; la saturation survient lorsque le taux de découverte instantané est inférieur au seuil de saturation adaptatif. La visite du graphe s'arrête si la saturation persiste pendant un nombre d'explorations de candidats consécutives supérieur au seuil de patience adaptatif.

De cette façon, nous obtenons un comportement qui ne dépend pas du paramètre num_candidates dans la requête KNN (qui peut toujours être défini ou laissé par défaut, indépendamment d'une sortie anticipée) et qui s'adapte mieux à chaque requête et distribution vectorielle de manière dynamique.

Le rappel par node visité sur FinancialQA et Quora avec la stratégie adaptative (étiquetée et=adaptive) indique un rappel plus élevé par node visité, par rapport à la stratégie statique (et=static) et au comportement par défaut de HNSW (et=no).

L'arrêt précoce adaptatif est activé par défaut dans Elasticsearch 9.3 pour les champs vectoriels denses HNSW (et peut éventuellement être désactivé via le même paramètre de niveau d'index).

Les intégrations configurent une ou plusieurs entrées Filebeat pour assurer la collecte des données. Pour collecter des données via des API HTTP, nous avons souvent utilisé l’entrée HTTP JSON. Cependant, même les API de type listing les plus simples peuvent varier considérablement dans leurs détails. Le modèle de transformations configurées en YAML de l’entrée HTTP JSON peut alors devenir contraignant, voire parfois insuffisant pour exprimer la logique de collecte requise.

L’entrée Common Expression Language (CEL) a été introduite afin de permettre une interaction plus souple avec les API HTTP. CEL est un langage conçu pour être intégré dans des applications nécessitant un moyen rapide, sûr et extensible d’exprimer des conditions et des transformations de données. L’entrée CEL permet au créateur d’intégration d’écrire une expression unique capable de lire les paramètres, de suivre son propre état, d’effectuer des requêtes, de traiter les réponses et, au final, de renvoyer des événements prêts à être ingérés.

Dans cet article, nous examinons les différences entre CEL et d’autres langages de programmation, les extensions apportées pour l’entrée CEL, ainsi que la puissance et la souplesse qu’il apporte à l’expression de votre logique de collecte de données.

CEL et son fonctionnement dans l’entrée

CEL est un langage d’expressions. Il ne comporte pas d’instructions. Lorsque vous écrivez en CEL, vous ne décrivez pas une suite d’actions à exécuter à l’aide d’instructions. Vous indiquez plutôt la valeur à produire en rédigeant une expression. Chaque expression CEL renvoie une valeur. De petites expressions peuvent être combinées pour former une expression plus large, capable de produire un résultat selon des règles plus complexes. Nous verrons plus loin comment utiliser des expressions pour des usages généralement exprimés à l’aide d’instructions dans d’autres langages.

CEL est volontairement un langage non Turing-complet. Il n’autorise pas les boucles non bornées. Nous verrons également comment traiter des listes et des maps à l’aide de macros. En évitant les boucles non bornées, le langage garantit un temps d’exécution prévisible et limité pour chaque expression.

L’entrée CEL est configurée avec un programme CEL (une expression) et un état initial. L’état est fourni en entrée au programme. Le programme est évalué afin de produire un état de sortie. Si l’état de sortie comprend une liste d’événements, ceux-ci sont extraits puis publiés. Le reste de l’état de sortie est utilisé comme entrée pour l’évaluation suivante. Si l’état de sortie contient un ou plusieurs événements et que l’indicateur want_more: true, l’évaluation suivante est effectuée immédiatement ; sinon, l’entrée attend la fin de l’intervalle configuré avant de poursuivre. Voici un schéma simplifié du flux de contrôle de l’entrée :

La sortie de chaque évaluation est transmise comme entrée à l’évaluation suivante, tant que l’entrée s’exécute. Les données de sortie sous la clé « cursor» sont persistées sur disque et rechargées après le redémarrage de l’entrée, mais le reste de l’état n’est pas conservé entre les redémarrages.

Le langage CEL lui-même offre des fonctionnalités limitées et évite les effets de bord, mais il est extensible. L’implémentation cel-go ajoute certaines fonctionnalités, comme la prise en charge des syntaxes et des types optionnels. La bibliothèque Mito s’appuie sur cel-go et enrichit ses capacités, notamment en permettant l’exécution de requêtes HTTP. L’entrée CEL utilise la version de CEL fournie par Mito.

Travailler avec Mito

Pour créer ou déboguer une intégration à l’aide de l’entrée CEL, il est essentiel de comprendre l’état de sortie que votre programme CEL produira à partir d’un état d’entrée donné. Pendant le développement, il peut être contraignant d’exécuter votre programme CEL via l’entrée, au sein de l’ensemble de la Suite Elastic. Pour accélérer la boucle de rétroaction, vous pouvez utiliser l’outil de commande en ligne de Mito. Il vous permet d’exécuter un programme CEL directement et d’observer la sortie générée pour une entrée donnée.

Mito est écrit en Go et peut être installé comme suit :

go install github.com/elastic/mito/cmd/mito@latest

Lorsque vous exécutez un programme CEL avec Mito, vous lui fournissez généralement deux fichiers : un fichier JSON contenant l’état d’entrée initial, et un autre fichier avec le code source de votre programme CEL :

mito -data state.json src.cel

Pour faciliter le copier-coller, les exemples de cet article sont écrits sous forme de commandes uniques qui permettent au shell de créer des fichiers temporaires à la volée, en enveloppant le contenu de chaque fichier dans <(echo '...content...'). Dans votre propre développement, travailler avec des fichiers réels sera plus facile.

Récupération des tickets depuis GitHub

L'exemple suivant inclut un programme CEL complet qui récupérera des données sur les problèmes depuis l'API GitHub. Son état d'entrée initial contient l'URL du point de terminaison de l'API et quelques informations sur la manière dont il doit gérer la pagination. Le programme CEL utilise les données dans l’état d’entrée pour générer une requête. Il va décoder la réponse, produire des événements à partir de celle-ci, et les renvoyer en tant que partie de son état de sortie.

mito -data <(echo '
  {
    "url": "https://api.github.com/repos/elastic/integrations/issues",
    "per_page": 3,
    "max_pages": 3
  }
') <(echo '
  int(state.?cursor.page.orValue(1)).as(page,
    (
      state.url + "?" + {
        "state": ["all"],
        "sort": ["created"],
        "direction": ["asc"],
        "per_page": [string(state.per_page)],
        "page": [string(page)],
      }.format_query()
    ).as(full_url,
      request("GET", full_url).with({
        "Header": {
          "Accept": ["application/vnd.github+json"],
          "X-GitHub-Api-Version": ["2022-11-28"],
        }
      }).do_request().as(resp,
        resp.Body.decode_json().as(data,
          state.with({
            "events": data.map(i, {
              "html_url": i.html_url,
              "title": i.title,
              "created_at": i.created_at,
            }),
            "cursor": { "page": page + 1 },
            "want_more": size(data) == state.per_page && page < state.max_pages,
          })
        )
      )
    )
  )
')

Sa première évaluation produit la sortie suivante :

{
  "cursor": {
    "page": 2
  },
  "events": [
    {
      "created_at": "2018-09-14T09:47:35Z",
      "html_url": "https://github.com/elastic/integrations/issues/3250",
      "title": "Increase support of log formats in haproxy filebeat module"
    },
    {
      "created_at": "2019-02-06T12:37:37Z",
      "html_url": "https://github.com/elastic/integrations/issues/487",
      "title": "ETCD Metricbeat module needs polishing and grooming"
    },
    {
      "created_at": "2019-08-13T11:33:11Z",
      "html_url": "https://github.com/elastic/integrations/pull/1",
      "title": "Initial structure"
    }
  ],
  "max_pages": 3,
  "per_page": 3,
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "want_more": true
}

Les événements seront supprimés et, lorsqu’ils seront exécutés dans l’entrée CEL, ils seront publiés pour ingestion. Le reste de la sortie sera transmis à l’évaluation suivante du programme CEL en tant qu’état d’entrée.

Pour comprendre le fonctionnement de ce programme CEL, nous allons examiner quelques exemples CEL plus simples et détailler davantage le fonctionnement de l’entrée CEL.

Les bases de CEL

Dans le langage CEL, il n’y a pas d’instructions ; uniquement des expressions. Toute expression CEL valide est évaluée pour produire une valeur finale. Voici l’une des plus petites expressions CEL que vous puissiez écrire, ainsi que sa sortie :

mito <(echo '
  "hello" + " " + "world"
')

"hello world"

De nombreuses expressions simples sont intuitives. Les opérations mathématiques ne sont prises en charge que sur des valeurs de même type (par exemple, int avec int), convertissez donc les types selon vos besoins (ici de int à double) :

mito <(echo '
  double((1 + 2) * (3 + 4)) / 2.0
')

10.5

Il n’y a pas de variables dans le langage CEL, mais une expression peut recevoir un nom et être utilisée dans une expression plus large grâce à la macro as de Mito. Dans cet exemple, l’expression (1 + 1) évalue la valeur 2, et .as(n, ...) donne à cette valeur le nom n pour l’utilisation dans l’expression "one plus one is "+string(n):

mito <(echo '
  (1 + 1).as(n, "one plus one is "+string(n))
')

"one plus one is 2"

Il est également possible d’accumuler des informations dans une carte et de les utiliser plus tard dans l’expression, comme démontré ici avec with:

mito <(echo '
  { "key": "value" }.with({ "key2": "value2" }).as(data,
    {
      "data": data,
      "size": size(data),
    }
  )
')

{
  "data": {
    "key": "value",
    "key2": "value2"
  },
  "size": 2
}

Regardez à nouveau cet exemple. Remarquez que la partie imbriquée, ({ "data": data, "size": size(data), }), nous donne la forme de la valeur finale. C'est une carte avec les clés "data" et "size". Les valeurs de ces clés dépendent de data, qui est défini par la partie extérieure de l’expression. Lire les expressions CEL de l'intérieur vers l'extérieur peut aider à voir rapidement ce qu'elles renverront.

CEL ne possède pas d’instructions de flux de contrôle, comme if, mais le branchement conditionnel peut être réalisé avec l’opérateur ternaire :

mito <(echo '
  1 + 1 < 12 ? "few" : "many"
')

"few"

Les boucles non bornées et la récursion ne sont pas prises en charge, car CEL n’est pas un langage Turing-complet. Le temps d’exécution est donc prévisible et proportionnel à la taille des données d’entrée et à la complexité de l’expression.

Bien que les boucles non bornées ne soient pas possibles dans des expressions CEL individuelles, vous pouvez traiter des listes et des cartes à l’aide de macros comme map :

mito <(echo '
  [1, 2, 3].map(x, x * 2)
')

[2, 4, 6]

Dans cette section, nous avons abordé les points suivants :

• Les chaînes de caractères, les nombres, les listes et les maps.
• La concaténation de chaînes.
• Les opérations mathématiques.
• Le transtypage.
• Les conditions.
• La nomination des sous-expressions.
• Le traitement des collections.

Ensuite, nous verrons comment effectuer des requêtes HTTP.

Requêtes

Mito étend CEL en lui donnant la possibilité d'effectuer des requêtes HTTP :

mito <(echo '
  get("https://example.com").as(resp, string(resp.Body))
')

"..."

Les requêtes peuvent être construites explicitement avant leur exécution. Cela permet d’utiliser différentes méthodes HTTP et d’ajouter des en-têtes ainsi qu’un corps de requête.

Dans cet exemple, nous construisons une URL avec l’aide de format_query, ajoutons un en-tête à la requête, et analysons le corps de la réponse avec decode_json. Lorsque l'option -log_requests est sélectionnée, Mito log des informations détaillées au format JSON sur chaque demande et réponse.

mito -log_requests <(echo '
  request("GET",
    "https://postman-echo.com/get?" + {
        "q": ["query value"]
     }.format_query()
  ).with({
    "Header": { "Accept": ["application/json"] }
  }).do_request().as(resp, {
    "status": resp.StatusCode,
    "data": resp.Body.decode_json(),
  })
')

{"time":"...","level":"INFO","msg":"HTTP request",...}
{"time":"...","level":"INFO","msg":"HTTP response",...}
{
  "data": {
    "args": {
      "q": "query value"
    },
    "headers": {
      "accept": "application/json",
      "accept-encoding": "gzip, br",
      "host": "postman-echo.com",
      "user-agent": "Go-http-client/2.0",
      "x-forwarded-proto": "https"
    },
    "url": "https://postman-echo.com/get?q=query+value"
  },
  "status": 200
}

Gestion de l’état et des évaluations

Maintenant que nous avons vu comment effectuer des requêtes et passé en revue les bases de CEL nécessaires pour produire l’état de sortie souhaité, examinons de plus près ce que nous devons placer dans l’état de sortie et comment cela nous permet d’orienter les traitements ultérieurs.

Le programme CEL d'une intégration doit s'assurer que son état de sortie peut être utilisé comme entrée de l'évaluation suivante. La configuration définit l'état initial, qui doit être répété dans la sortie avec toutes les modifications appropriées. Une façon simple de le faire est d’utiliser state.with({ ... }), pour répéter la carte d’état avec quelques dérogations. Un modèle courant pour les petits programmes consiste à envelopper l'ensemble du programme dans state.with(), de sorte que la propagation de l'état ne doive pas être répétée dans chaque branche qui génère des données de sortie (par exemple, succès, erreurs).

Lorsque des valeurs d’état sont initialisées par une évaluation plutôt que codées en dur dans l’état d’entrée initial, le programme devra vérifier la présence d’une valeur existante avant de définir la valeur initiale. La prise en charge de la syntaxe et des types optionnels peut aider à résoudre ce problème. En utilisant un point d'interrogation avant le nom du champ dans une clé de carte, l'accès devient facultatif : il peut ou non aboutir à une valeur, mais d'autres accès facultatifs sont possibles et il est facile de fournir une valeur par défaut si aucune valeur n'est présente :

mito -data <(echo '{}') <(echo '
  int(state.?counter.orValue(0)).as(counter,
    state.with({
      "counter": counter + 1,
      "want_more": counter + 1 < 3,
    })
  )
')

{ "counter": 1, "want_more": true }
{ "counter": 2, "want_more": true }
{ "counter": 3, "want_more": false }

Dans cet exemple, la valeur du compteur lue à partir de l'état est convertie en int car tous les nombres sont sérialisés dans l'état sous forme de nombres à virgule flottante, conformément aux conventions établies par JSON et le type Number de JavaScript. Il convient également de noter que "want_more": true est respecté ici par Mito, mais lorsqu’elle est exécutée dans l’entrée CEL, l’évaluation ne sera répétée que si la sortie contient également des événements.

C’est une exigence des programmes CEL exécutés par l’entrée CEL de retourner une clé "events" dans leur carte de sortie. Sa valeur peut être une liste de cartes d’événements, une liste vide ou une carte d’événement unique. Le cas d’événement unique est généralement utilisé pour les erreurs. L’événement sera publié par l’entrée, mais sa valeur sera également journalisée, et s’il définit une valeur error.message, celle-ci sera utilisée pour mettre à jour l’état de santé de la Fleet de l’intégration. Si votre programme ne produit qu’un seul événement sans erreur, il est préférable de l’inclure dans une liste.

Reprenons la sortie de notre programme de récupération des tickets GitHub présenté précédemment :

{
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "per_page": 3,
  "max_pages": 3,
  "cursor": {
    "page": 2
  },
  "events": [
    { ... },
    { ... },
    { ... }
  ],
  "want_more": true
}

Le programme gérait effectivement son état de la manière suivante :

• Répétition des valeurs d’état initiales dans url, per_page, et max_pages.
• Ajout d’état qui devrait être maintenu lors des redémarrages dans cursor.page.
• Les événements prêts à être publiés dans la liste events.
• Demande de réévaluation immédiate avec want_more: true.

Maintenant que vous maîtrisez l’accès optionnel, la gestion de l’état, les bases de CEL et les requêtes HTTP, le programme complet de récupération des tickets GitHub devrait être plus clair. Essayez de l’exécuter avec Mito et d’expérimenter quelques modifications.

Conclusion et ressources

Dans cet article, nous avons expliqué ce qu’est le langage CEL et comment il a été étendu dans la bibliothèque Mito pour une utilisation dans l’entrée CEL. Nous avons illustré la flexibilité de CEL à travers un programme exemple qui récupère des informations sur des tickets via l’API GitHub, et détaillé les éléments nécessaires à sa compréhension : accès aux paramètres dans l’état initial, interaction avec les API HTTP, renvoi d’événements destinés à l’ingestion et gestion de l’état pour les exécutions ultérieures du programme.

Pour aller plus loin et créer des intégrations à l’aide de l’entrée CEL, plusieurs ressources méritent votre attention :

• Entrée CEL - Documentation Filebeat
• Documentation Mito
• Langage d'expression commun - site web cel.dev
• Créer une intégration - Documentation Elastic

Et sans doute la ressource la plus précieuse pour créer des intégrations avec l’entrée CEL reste le code CEL des intégrations Elastic existantes, disponible sur GitHub :

cel.yml.hbs fichiers du dépôt des intégrations Elastic – GitHub

1. La nouvelle mise à jour de Swift est arrivée ! Les développeurs sont impatients de tester les nouvelles fonctionnalités.
2. La nouvelle mise à jour de Swift est arrivée ! Le nouvel album sortira le mois prochain.

Avec ce contexte supplémentaire, nous devrions être en mesure d’associer le nom « Swift » à la bonne entité.

Dans l'article précédent, nous avons constitué notre liste de surveillance et enrichi les entités avec un contexte supplémentaire. En reprenant nos exemples ci-dessus, nous devons disposer au minimum des deux entités suivantes dans la liste : Taylor Swift et le langage de programmation Swift. Nous avons également expliqué comment extraire les mentions d’entités à partir d’un texte. Dans ces deux exemples, la mention extraite serait « Swift ». Avec ces éléments en place — la liste de surveillance enrichie et les entités extraites — nous sommes enfin prêts à introduire la vedette du moment : la mise en correspondance des entités.

Rappel : il s’agit d’un prototype pédagogique conçu pour illustrer les concepts de mise en correspondance d’entités. En production, les systèmes peuvent utiliser différents grands modèles de langage (LLM), des règles de correspondance personnalisées, des pipelines d’évaluation spécialisés ou encore des approches d’ensemble combinant plusieurs stratégies de correspondance.

Le problème : pourquoi la mise en correspondance est complexe

Le langage humain est une chose remarquable. L’une de ses caractéristiques les plus intéressantes est sa créativité sans fin. Nous pouvons générer et comprendre un nombre infini de nouvelles phrases. Dès lors, est-il surprenant que les correspondances exactes soient rares en résolution d’entités ? Les auteurs s’efforcent d’être créatifs dès qu’ils le peuvent. Il serait vite fastidieux de devoir écrire et lire les noms complets chaque fois qu’une entité est mentionnée. Ainsi, si les correspondances exactes sont simples, la réalité est que nous avons besoin d’une approche plus sophistiquée de la résolution d’entités : une approche suffisamment robuste pour gérer au moins une partie de la créativité sans limite des auteurs humains. C’est pourquoi nous décomposons le problème en deux étapes : utiliser Elasticsearch pour récupérer des candidats plausibles à grande échelle, puis recourir à un LLM pour déterminer si ces candidats renvoient réellement à la même entité du monde réel.

La solution : une mise en correspondance en trois étapes avec un jugement LLM transparent

Nous vivons un changement de paradigme dans notre manière d’utiliser les ordinateurs. Tout comme l’essor d’Internet nous a fait passer d’une informatique localisée à un réseau mondialement connecté, l’IA générative transforme en profondeur la façon dont le contenu, le code et l’information sont créés. En réalité, le prototype pédagogique qui accompagne cette série a été presque entièrement « vibe codé » à l’aide d’un LLM, avec des instructions soigneusement rédigées par l’auteur. Cela ne signifie pas que les LLM atteignent — ou atteindront — le niveau de productivité propre au langage humain, mais cela veut dire que nous disposons désormais d’une ressource puissante pour faciliter la résolution d’entités.

Un schéma courant avec l'IA générative est la génération augmentée par récupération (RAG). Ici, récupération signifie que l’on récupère des candidats d’entités (et non que l’on génère des réponses), et que le LLM est utilisé exclusivement pour évaluer les correspondances et en expliquer la logique. Bien que je puisse demander à un LLM de prendre en charge l’ensemble du processus de résolution d’entités, de bout en bout, cette approche serait coûteuse, tant en temps qu’en ressources financières. La RAG aide les LLM à accomplir leur tâche en leur fournissant du contexte de manière plus efficace, ce qui leur permet de contribuer plus efficacement à la résolution d’entités.

Pour la partie récupération de la RAG, nous faisons à nouveau appel à Elasticsearch. Nous identifions d’abord des correspondances potentielles en combinant la correspondance exacte, la correspondance sur des alias et la recherche hybride, qui associe recherche par mots-clés et recherche sémantique. Une fois ces correspondances potentielles identifiées, nous les transmettons à un LLM pour évaluation. Le LLM agit comme évaluateur final des correspondances. Nous demandons également au LLM d’expliquer son raisonnement, un élément différenciant important par rapport à d’autres systèmes de résolution d’entités. Sans ces explications, la résolution d’entités reste une boîte noire ; avec elles, nous pouvons comprendre pourquoi une correspondance est pertinente.

Concepts clés : mise en correspondance en trois étapes, recherche hybride et jugement LLM transparent

Qu’est-ce que la mise en correspondance en trois étapes ? Au début de ce projet, nous avons émis l’hypothèse que la recherche sémantique jouerait un rôle clé dans le système, mais toutes les correspondances ne nécessitent pas un niveau de recherche aussi sophistiqué. Afin de trouver des correspondances efficacement, nous adoptons une approche progressive du problème. Tout d’abord, nous vérifions les correspondances exactes à l’aide de la recherche par mots-clés. Si nous trouvons une telle correspondance, le travail est terminé et nous pouvons passer à l’étape suivante. Si la correspondance exacte échoue, nous passons à la correspondance par alias. Dans le prototype, la correspondance par alias est également effectuée à l’aide d’une correspondance exacte sur des mots-clés, par souci de simplicité. En production, cette étape peut être enrichie par des règles de normalisation, de translittération, de correspondance approximative (fuzzy matching) ou par des tables d’alias maintenues. Si, après ces deux premières étapes, aucune correspondance potentielle n’a été trouvée, nous faisons appel à la recherche sémantique via la recherche hybride d’Elasticsearch, utilisant la méthode Reciprocal Rank Fusion (RRF).

Qu’est-ce que la recherche hybride ? Dans Elasticsearch, nous pouvons utiliser la recherche sémantique pour identifier des correspondances pertinentes en tenant compte du contexte. Elasticsearch est largement utilisé pour la recherche vectorielle et la récupération hybride. La similarité sémantique est puissante pour capter le sens, mais elle ne remplace pas le filtrage structuré (par exemple, par plages temporelles, emplacements ou identifiants). Elle est souvent inutile lorsqu’une correspondance exacte est disponible. Elasticsearch s’est d’abord imposé grâce à la recherche lexicale, particulièrement efficace lorsque la recherche sémantique n’est pas adaptée. Pour tirer pleinement parti des deux approches, nous combinons la recherche lexicale et la recherche sémantique au sein d’une requête hybride unique. Nous fusionnons ensuite les résultats afin d’identifier les correspondances les plus probables à l’aide de la méthode RRF. Dans le prototype, les deux premiers résultats deviennent des correspondances potentielles pouvant être soumises à l’évaluation du LLM.

Pourquoi faire appel au jugement LLM ? Les jugements et explications fournis par le LLM permettent à notre système de gérer l’ambiguïté et le contexte de manière transparente. C’est essentiel pour des cas comme « le président », qui peut désigner plusieurs entités selon le contexte. Cela permet également de gérer efficacement les surnoms et les variations culturelles. Enfin, lorsque nous traitons des tâches critiques — comme l’identification d’entités figurant sur des listes de sanctions — il est indispensable de comprendre pourquoi une correspondance a été acceptée afin de pouvoir faire confiance au système. Point essentiel : le LLM ne parcourt pas l’intégralité du corpus. Il évalue uniquement le petit ensemble de candidats renvoyé par Elasticsearch.

Résultats concrets : mise en correspondance avec raisonnement du LLM

Un défi majeur pour toute tâche de traitement automatique du langage naturel est la création d’un document de référence, une « answer key » indiquant quels sont les résultats attendus. Sans cela, il est quasiment impossible d’évaluer la performance d’un système sur une tâche donnée. Or, la création d’un tel document peut s’avérer laborieuse. Pour le prototype de résolution d’entités, nous avons de nouveau fait appel à l'IA générative afin de générer des données sur lesquelles nous pourrions effectuer des tests.

Nous avons d’abord défini plusieurs types de défis, comme les surnoms et la translittération, puis demandé au LLM de créer une collection hiérarchisée de jeux de données, devenant progressivement plus volumineux et plus complexes pour le système. La création des jeux de données s’est révélée moins simple qu’on aurait pu l’espérer. Le LLM avait une forte tendance à « tricher » en rendant la bonne réponse trop facile à trouver. Par exemple, l’un des types de défis portait sur le contexte sémantique. Ce type incluait des cas tels que faire correspondre « auteur russe » à « Leo Tolstoy ». Le LLM a incorrectement défini « auteur russe » comme un alias de « Leo Tolstoy », ce qui supprimait la nécessité d’une recherche hybride pour identifier la correspondance.

Après plusieurs refactorisations pour corriger ce type de problèmes, nous disposions de cinq niveaux d’ensembles de données. Les niveaux 1 à 4 devenaient progressivement plus volumineux et intégraient davantage de types de défis. Le niveau 5 constituait le « défi ultime », composé des exemples les plus complexes issus de tous les types de défis. L’ensemble des données de test est disponible dans un répertoire d’évaluation complet.

Pour évaluer notre approche de résolution d’entités basée sur des prompts, nous avons concentré notre analyse sur le jeu de données de niveau 4. Il est important de noter que l’évaluation a été menée dans le cadre d’une expérience contrôlée afin de nous concentrer sur la qualité de mise en correspondance des entités. Les données de la liste de correspondances ont été préalablement enrichies avec du contexte, et les entités ont été extraites de l’article en amont. Cela a permis de s’assurer que l’évaluation se concentrait sur la correspondance plutôt que sur la précision de l’extraction. Cela isole la qualité de correspondance ; les performances de bout en bout dépendraient en outre du rappel d'extraction et de la qualité d'enrichissement.

Ensemble de données d’évaluation

L'ensemble de données d'évaluation de niveau 4 fournit un test complet des capacités du système : [1]

• Entités de la liste de surveillance : 66 entités couvrant différents types (personnes, organisations, lieux).
• Articles de test : 69 articles couvrant des scénarios réels de résolution d’entités.
• Correspondances attendues : 206 correspondances attendues pour l'ensemble des articles.
• Types de défis : 15 types de défis différents mettant à l'épreuve divers aspects de la résolution d'entités.

Les types de défis inclus dans l’ensemble de données sont les suivants :

• Surnoms : « Bob Smith » → « Robert Smith » (sept articles).
• Titres et titres honorifiques : « Dr. » Sarah Williams » → « Sarah Williams » (cinq articles).
• Contexte sémantique : « auteur russe » → « Leo Tolstoy » (huit articles).
• Noms multilingues : traitement des noms dans différentes écritures (six articles).
• Entités commerciales : variations de noms d’entreprises (sept articles).
• Références exécutives : « PDG de Microsoft » → « Satya Nadella » (cinq articles).
• Dirigeants politiques : références basées sur un titre (cinq articles).
• Initiales : « J. Smith » → « John Smith » (trois articles).
• Variations dans l’ordre des noms : différentes conventions d’ordre des noms (trois articles).
• Noms tronqués : correspondances partielles de noms (trois articles).
• Découpage des noms : noms séparés dans le texte (trois articles).
• Espaces ou tirets manquants : variations de mise en forme (deux articles).
• Translittération : correspondance de noms entre différents systèmes d’écriture (deux articles).
• Défis combinés : plusieurs défis dans un même article (six articles).
• Cas d’entreprise complexes : relations hiérarchiques entre entités commerciales (cinq articles).

Examinons comment la résolution d’entités basée sur des prompts s’est comportée.

Performance globale

Les résultats montrent un fort potentiel pour l’évaluation des correspondances assistée par LLM, mais ils mettent également en évidence un problème significatif de fiabilité. Chaque paire candidate doit être évaluée par le LLM. Des erreurs dans la sortie structurée peuvent réduire la précision et le rappel, même lorsque la phase de récupération fonctionne correctement.

Le problème du taux d'erreur

Rappelons que la première étape du prototype consiste à créer des paires de correspondances potentielles à l’aide d’Elasticsearch. Chacune de ces correspondances potentielles doit ensuite être évaluée par le LLM. Pour traiter efficacement l’ensemble de ces correspondances, nous regroupons les appels au LLM par lots. Cela réduit les coûts d’API et la latence, mais augmente également le risque d’obtenir un JSON mal formé en sortie. À mesure que la taille des lots augmente, le JSON devient plus long et plus complexe, ce qui accroît la probabilité que le LLM génère un JSON invalide. C’est de là que provient le taux d’erreur de 30 %. Dans cette évaluation, nous avons utilisé une taille de lot de cinq correspondances par requête. Même avec cette taille de lot conservatrice, nous constatons toujours des échecs d'analyse JSON, ce qui fausse considérablement les résultats de l'évaluation.

Prochaine étape : optimiser l’intégration des LLM

Maintenant que nous avons mis en correspondance des entités à l’aide de la recherche sémantique et du jugement d’un LLM, nous disposons d’un pipeline complet de résolution d’entités. Cependant, cette approche introduit un nouveau mode de défaillance : le jugement du modèle peut être correct, mais sa sortie inutilisable. Nous pouvons optimiser l’intégration du LLM afin d’améliorer la fiabilité et la rentabilité. Dans le prochain article, nous verrons comment utiliser le function calling pour produire une sortie structurée, garantissant une structure et un typage sûrs, tout en réduisant les erreurs et les coûts.

Essayez par vous-même

Envie de voir la mise en correspondance d’entités en action ? Consultez le carnet de notes sur l'appariement des entités pour une présentation complète avec des implémentations réelles, des explications détaillées et des exemples pratiques. Le carnet vous montre exactement comment faire correspondre les entités à l'aide de la recherche en trois étapes, de la recherche hybride avec RRF et du jugement raisonné basé sur le LLM.

Rappel : il s’agit d’un prototype pédagogique conçu pour illustrer les concepts. Lors de la mise en œuvre d’un système en production, tenez compte de facteurs supplémentaires tels que la sélection du modèle, l’optimisation des coûts, les exigences en matière de latence, la validation de la qualité, la gestion des erreurs et la supervision — des aspects qui ne sont pas couverts dans ce prototype à visée pédagogique.

Remarques

1. Ces ensembles de données sont synthétiques et conçus à des fins pédagogiques. Ils reflètent des défis réels, mais ne représentent aucun domaine de production spécifique.

Sur un corpus de 20 millions de documents, nos benchmarks révèlent qu’Elasticsearch multiplie par 8 le débit d’OpenSearch en recherche vectorielle filtrée, avec un Recall@100 supérieur dans toutes les configurations évaluées. L’ingénierie de contexte va au-delà de la performance brute de la récupération vectorielle. Une pertinence maîtrisée (recherche hybride, filtrage), une exploitation simplifiée et des performances constantes sont tout aussi essentielles pour les équipes lors de l’évolution de leurs workflows. Comme les agents effectuent fréquemment des cycles itératifs de récupération et de raisonnement pour chaque demande, la latence de recherche agit comme un facteur multiplicatif. Toute optimisation ici améliore donc instantanément la réactivité de bout en bout et diminue les coûts d’exploitation.

Pour l'ingénierie du contexte, la récupération n'est pas une étape unique. Les agents et les applications effectuent de manière répétée des exécutions de boucles, telles que récupérer → raisonner → récupérer, pour affiner les requêtes, vérifier les faits, assembler un contexte étayé et accomplir les tâches. Ce schéma est courant dans les workflows d'agents et la Retrieval-Augmented Generation (RAG) itérative. Comme la récupération peut être sollicitée de nombreuses fois pour une seule requête utilisateur, elle ajoute un délai à la réponse et/ou augmente les coûts d’infrastructure.

Pourquoi la performance de la recherche vectorielle est-elle critique ?

Imaginez la réponse d’un assistant d’achat à cette requête : « Il me faut un sac à dos de type bagage à main à moins de 60 $, adapté à un ordinateur de 15 pouces, résistant à l’eau et disponible en livraison d’ici vendredi. »

Dans un environnement de production, il est rare que l’assistant lance une unique recherche vectorielle et en reste là. L’assistant lance une boucle de recherche afin d’élaborer le bon contexte, chaque phase étant soumise à des filtres précis : disponibilité, zone géographique, délais de livraison, image de marque ou encore conformité aux politiques internes.

Étape 1 : interpréter l'intention et traduire en contraintes.

L’agent transforme la requête en filtres structurés et en une recherche sémantique, comme suit :

• Filtres : en stock, livrable à l'utilisateur à son code postal, livraison avant vendredi, prix inférieur à 60 $, annonce valide
• Requête vectorielle : « Sac à dos cabine ordinateur 15 pouces résistant à l’eau »

Étape 2 : récupérer les candidats, puis affiner.

Elle répète souvent la récupération avec des variantes afin de ne pas manquer de bonnes correspondances :

• « sac à dos de voyage cabine compartiment ordinateur »
• « sac à dos de trajet quotidien, résistant à l’eau, ordinateur 15 pouces »
• « sac à dos de cabine léger »

Chaque requête utilise les mêmes filtres d’éligibilité, car récupérer des éléments non pertinents ou indisponibles constitue un gaspillage de contexte.

Étape 3 : Élargir la recherche pour confirmer les détails et réduire les risques.

L’agent effectue une récupération supplémentaire pour valider les attributs déterminants du résultat final :

• Formulation concernant les matériaux et la résistance à l’eau
• Dimensions et compatibilité du compartiment pour ordinateur portable
• Modalités de retour et clauses de garantie
• Options alternatives en cas de stock faible

Ceci est l'ingénierie contextuelle en plusieurs étapes : Récupérer, raisonner, récupérer, assembler.

L’importance de la latence et du rappel dans l’ingénierie de contexte

Ces interactions peuvent impliquer des dizaines d’appels de récupération filtrés par session utilisateur. La latence par appel est donc un multiplicateur direct du temps de réponse de bout en bout, et un faible taux de rappel oblige à des tentatives supplémentaires ou amène l'agent à manquer des éléments éligibles, ce qui dégrade la qualité de la réponse.

À retenir : Dans les systèmes d’ingénierie de contexte, la recherche filtrée des plus proches voisins (ANN) n’est pas une simple requête unique. C’est une suite d’opérations sous contraintes : la performance de la recherche vectorielle se traduit donc directement en termes de latence, de débit et de coûts, alors même que le LLM capte toute l’attention en surface.

Évaluation comparative

Résultats

Dans le graphe 2, chaque point représente une configuration de test. Les performances optimales apparaissent dans le coin supérieur gauche : c’est là que le rappel est le plus important et la latence la plus réduite. Les données d’Elasticsearch se rapprochent davantage du coin supérieur gauche que celles d’OpenSearch, signe d’une vitesse et d’une précision accrues pour une même charge de travail.

Quelques informations clés

• s_n_r_value: Abréviation pour size_numCandidates_rescoreOversample (k et numCandidates sont égaux à numCandidates dans ces tests) ; par exemple, 100_500_1 signifie taille=100, candidats=500 et k=500, rescore oversample=1
• Rappel : Mesure du Rappel@100 pour cette configuration spécifique
• Latence moyenne (ms) : Temps de réponse moyen de bout en bout par requête
• Débit : requêtes par seconde (QPS)
• Pourcentage de rappel : Amélioration relative du rappel pour Elasticsearch comparativement à OpenSearch ((Elasticsearch - OpenSearch) / OpenSearch)
• Latence Xs : latence moyenne d'OpenSearch divisée par la latence moyenne d'Elasticsearch
• Débit Xs : débit Elasticsearch divisé par le débit OpenSearch

Par exemple, à 100_9000_1, OpenSearch enregistre en moyenne 687 millisecondes par extraction, contre 90 millisecondes pour Elasticsearch, et dans une boucle de récupération en 10 étapes, cela représente environ 10 × (687 - 90) = six secondes de temps d’attente supplémentaire.

Découvrez les résultats complets.

Méthodologie

À l’aide de Python pour l’envoi des requêtes et le suivi de la latence ainsi que des données statistiques, nous avons soumis les requêtes suivantes aux moteurs. N’oubliez pas que l’efficacité d’un moteur vectoriel repose sur l’ajustement de ses paramètres clés : le nombre de candidats analysés, le niveau d’agressivité du score de pertinence et la quantité de contexte fournie en retour. Ces configurations agissent directement sur le rappel (l’assurance de ne pas manquer la réponse adéquate) et sur la latence (la vélocité du traitement).

Pour nos tests, nous avons conservé les mêmes réglages de sélection de candidats, de nouveau calcul de score et de dimension de contexte que ceux d’un cycle de récupération itératif, puis nous avons mesuré l’efficacité d’Elasticsearch face à ce volume de données. Par la suite, nous avons testé OpenSearch avec une configuration identique afin d’établir un point de comparaison.

OpenSearch

GET /_search
{
  "query": {
    "knn": {
      "": {
        "vector": [...],
        "k": ,
        "method_parameters": {
          "ef_search": 
        },
        "rescore": {
          "oversample_factor": 
        },
        "filter": {
          
        }
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: Nombre de résultats renvoyés au client. Pour ce benchmark, nous avons défini une taille de résultat de 100 pour l’évaluation du Rappel@100.
• "k": <NUMBER_OF_CANDIDATES>: Le nombre de candidats voisins les plus proches.
• "ef_search": <NUMBER_OF_CANDIDATES>: Lle nombre de vecteurs à examiner.
• "oversample_factor": <OVERSAMPLE>: Combien de vecteurs candidats sont récupérés avant réévaluation.

Elasticsearch

GET /_search
{
  "query": {
    "knn": {
      "field": "",
      "query_vector": [...],
      "k": ,
      "num_candidates": ,
      "rescore_vector": {
        "oversample": 
      },
      "filter": {
        
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: Nombre de résultats renvoyés au client. Pour ce benchmark, nous avons défini une taille de résultat de 100 pour l’évaluation du Rappel@100.
• "k": <NUMBER_OF_CANDIDATES>: Nombre de voisins les plus proches à renvoyer de chaque partition.
• "num_candidates": <NUMBER_OF_CANDIDATES>: Nombre de candidats au plus proche voisin à considérer par partition lors d'une opération de recherche knn.
• "oversample": <OVERSAMPLE>: Combien de vecteurs candidats sont récupérés avant réévaluation.

Exemple

Knn la requête, (100_500_1), serait la suivante :

OpenSearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "search_catalog_embedding": {
        "vector": [...],
        "k": 500,
        "method_parameters": {
          "ef_search": 500
        },
        "rescore": {
          "oversample_factor": 1
        },
        "filter": {
          "term": {
            "valid": true
          }
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

Elasticsearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "field": "search_catalog_embedding",
      "query_vector": [...],
      "k": 500,
      "num_candidates": 500,
      "rescore_vector": {
        "oversample": 1
      },
      "filter": {
        "term": {
          "valid": true
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

La configuration complète, ainsi que les scripts Terraform, les manifestes Kubernetes et le code de test de performance, sont disponibles dans ce dépôt dans le dossier es-9.3-vs-os-3.5-vector-search.

Configuration du clustering

Nous avons utilisé six instances cloud de type e2-standard-16 pour nos tests, chacune équipée de 16 vCPUs et de 64 Go de mémoire vive. Nous avons configuré chaque pod Kubernetes hébergeant un node du moteur avec 15 vCPUs et 56 Go de RAM, en réservant 28 Go pour la mémoire de la JVM.

Les tests ont été effectués sur les versions 9.3.0 d’Elasticsearch et 3.5.0 d’OpenSearch. (Lucene 10,3,2). Comme les deux solutions reposent sur la même version de Lucene pour ce test, les écarts de performance constatés au niveau du débit et de la latence ne s’expliquent pas par le moteur de base, mais par la façon dont chaque plateforme orchestre la recherche kNN filtrée et les étapes de calcul de score. Pour ce test, nous avons configuré un index unique comportant trois shards primaires et une réplique (ce qui donne 6 partitions au total, soit 1 par node).

Nous avons par ailleurs mobilisé un serveur séparé, situé dans la même région, afin de faire tourner le client de test et de compiler les données de performance.

L’ensemble de données

Pour ce test de performance, nous avons exploité un catalogue e-commerce de 20 millions de documents (embeddings), afin de simuler une recherche vectorielle avec filtres à l’échelle d’une application de production.

Chaque document représente un élément de catalogue et comprend :

• Un vecteur dense à 128 dimensions utilisé pour la recherche approximative par kNN.
• Champs de métadonnées structurés servant au filtrage (disponibilité, validité des produits, etc.), afin de simuler la récupération de vecteurs voisins restreinte à une sélection de données qualifiées, comme c’est souvent le cas en environnement réel.

Nous avons opté pour ces données car elles reflètent la problématique critique des systèmes de production actuels : le besoin de filtrage systématique qui vient s’ajouter à la recherche vectorielle, exigeant une efficacité maximale tant en termes de précision que de rapidité. Par rapport à des bases de données de petite taille, l’utilisation de 20 millions de documents permet de mieux simuler la charge de travail et la complexité de sélection des candidats rencontrées par les moteurs de recherche vectorielle filtrée dans un environnement réel.

Conclusion

Pour les systèmes d’IA de nouvelle génération, notamment ceux qui reposent sur la gestion dynamique du contexte, la performance brute de la recherche par vecteurs est un élément structurant de l’expérience utilisateur. C’est un facteur multiplicateur. Dans les architectures où les agents enchaînent les étapes de recherche et de réflexion, l’efficacité de la récupération détermine non seulement la rapidité de la réponse finale, mais aussi la pertinence des informations transmises au LLM.

Elasticsearch a fait preuve d’une supériorité constante lors de nos tests, affichant un meilleur rappel et une latence réduite par rapport à OpenSearch, particulièrement lorsque la précision de la recherche repose sur l’identification du document spécifique plutôt que sur une vague ressemblance vectorielle. Sur un ensemble de données contrôlé, la différence est nette, et en production, ces gains s’accumulent au fil de volumes massifs d’appels de récupération, améliorant la réactivité, augmentant la marge de capacité et réduisant les coûts d’infrastructure.

Lecture complémentaire

1. Qu'est-ce que l'ingénierie contextuelle ?
2. L'évolution du rechercher hybride et de l'ingénierie contextuelle
3. L'impact de la pertinence dans l'ingénierie du contexte pour les agents IA

La famille comprend deux modèles :

• jina-embeddings-v5-text-small
• jina-embeddings-v5-text-nano

Ces modèles sont le fruit d’une nouvelle méthode d’entraînement innovante pour les modèles d’embeddings. Tous deux surpassent des modèles bien plus volumineux, tout en réduisant les besoins en mémoire et en ressources de calcul, et en accélérant les temps de réponse.

Le modèle jina-embeddings-v5-text-small compte 677 millions de paramètres, prend en charge une fenêtre de contexte d’entrée de 32 768 tokens et génère par défaut des embeddings de 1 024 dimensions.

jina-embeddings-v5-text-nano pèse environ un tiers de la taille de son homologue, avec 239 millions de paramètres et une fenêtre de contexte d’entrée de 8 192 tokens, offrant des embeddings de 768 dimensions.

Ces deux modèles se classent parmi les meilleurs pour les performances globales au benchmark MTEB (Massive Text Embedding Benchmark) et au benchmark multilingue MTEB. Parmi les modèles ayant moins de 500 millions de paramètres, jina-embeddings-v5-text-nano est le plus performant, malgré moins de 250 millions de paramètres, et jina-embeddings-v5-text-small est le leader parmi les modèles d’embeddings multilingues de moins de 750 millions de paramètres.

Ces modèles sont disponibles via Elastic Inference Service (EIS), via une API en ligne, et peuvent également être déployés en local. Pour savoir comment accéder aux modèles jina-embeddings-v5-text, consultez la section « Commencer » ci-dessous.

Les modèles d’embeddings et l’indexation sémantique améliorent considérablement la précision des algorithmes de recherche, tout en répondant à de nombreux autres cas d’usage liés à la similarité sémantique et à l’extraction de sens, par exemple :

• Détection de textes en double.
• Reconnaissance des paraphrases et des traductions.
• Découverte de thématiques.
• Moteurs de recommandation.
• Analyse des sentiments et des intentions.
• Filtrage des spams.
• Et bien d'autres encore.

Fonctionnalités

Cette nouvelle famille de modèles propose un ensemble de fonctionnalités conçues pour améliorer la pertinence et réduire les coûts.

Optimisation des tâches

Nous avons optimisé les modèles jina-embeddings-v5-text pour quatre grands types de tâches :

Optimiser un modèle pour une tâche implique généralement de faire des compromis sur une autre. La plupart des modèles d’embeddings n’offrent donc des performances compétitives que pour un seul type de tâche. En revanche, les modèles jina-embeddings-v5-text peuvent se spécialiser dans les quatre catégories sans compromettre l’entraînement, grâce à des adaptateurs Low-Rank Adaptation (LoRA) spécifiques à chaque tâche.

Les adaptateurs LoRA sont une sorte de plugin pour un modèle d’IA, qui en modifie fortement le comportement tout en n’augmentant que légèrement sa taille totale. Au lieu d’avoir un modèle distinct pour chaque tâche, chacun comportant des centaines de millions de paramètres, la famille de modèles jina-embeddings-v5-text vous permet d’utiliser un seul modèle, associé à un adaptateur LoRA compact pour chaque tâche. Cela permet d’économiser de la mémoire, de l’espace de stockage et de réduire les coûts d’inférence.

Troncature des embeddings

Nous avons entraîné les modèles jina-embeddings-v5-text avec Matryoshka Representation Learning (MRL), ce qui vous permet de réduire la taille de vos embeddings tout en limitant l’impact sur leur qualité.

Par défaut, jina-embeddings-v5-text-small génère des vecteurs d’embeddings de 1 024 dimensions, chaque valeur étant représentée sur 16 bits, ce qui porte la taille de chaque embedding à 2 Ko. Pour une vaste collection de documents, cela peut représenter un volume de données important à stocker. La recherche dans une base de données vectorielle remplie d’embeddings est proportionnelle à la taille de la base et au nombre de dimensions de chaque vecteur stocké.

Vous pouvez toutefois réduire de moitié la taille des embeddings (en supprimant 512 des 1 024 dimensions), diminuer l’espace occupé de moitié et doubler la vitesse de recherche. Cela a un impact sur les performances. Supprimer des informations réduit la précision. Mais comme le montre le graphique ci-dessous, supprimer la moitié de l’embedding n’entraîne qu’une légère baisse des performances :

Tant que vos embeddings comportent au moins 256 dimensions, la perte de précision devrait rester relativement faible. En dessous de ce seuil, en revanche, la pertinence et la précision se dégradent rapidement.

La troncature des embeddings de cette manière vous permet de gérer vos arbitrages entre précision et coûts de calcul. Vous disposez ainsi des leviers nécessaires pour obtenir des gains d’efficacité significatifs et réduire sensiblement les coûts de votre Search AI.

Quantification robuste

La quantification constitue une autre méthode pour réduire la taille des embeddings. Au lieu de supprimer une partie de chaque embedding, la quantification diminue la précision des valeurs numériques qui le composent. Les modèles jina-embeddings-v5-text génèrent des embeddings avec des valeurs sur 16 bits, mais nous pouvons arrondir ces valeurs, ce qui réduit leur précision ainsi que le nombre de bits nécessaires pour les stocker. Dans le cas le plus extrême, il est possible de ramener chaque valeur à un seul bit (0 ou 1), ce qui compresse les embeddings par défaut de 1 024 dimensions de jina-embeddings-v5-textde 2 kilooctets à 128 octets, soit une réduction de 94 % grâce à la seule quantification binaire. Comme pour la troncature, cela permet de réaliser d’importantes économies de mémoire et de ressources de calcul. Cependant, à l’instar de la troncature, la quantification réduit la précision des embeddings.

Nous avons entraîné les modèles jina-embeddings-v5-text pour fonctionner avec la Better Binary Quantization (BBQ) d’Elasticsearch, en minimisant la perte de précision. Les tests comparatifs des embeddings binarisés issus de ces modèles montrent des performances presque équivalentes à celles de leurs versions non binarisées. Consultez le rapport technique pour accéder à des études d’ablation détaillées sur les performances de la binarisation.

Performance multilingue

De nombreux modèles d’embeddings sont multilingues, car ils ont été entraînés sur des corpus couvrant un grand nombre de langues. Cela ne signifie pas pour autant qu’ils offrent des performances équivalentes dans toutes les langues prises en charge.

Nous avons identifié 211 langues dans le benchmark multilingue MTEB et les avons isolées afin de comparer nos modèles à des modèles similaires, langue par langue. L’image ci-dessous synthétise nos résultats sous la forme d’une carte thermique. Chaque zone correspond à une langue (identifiée par son code ISO-639) et plus la couleur est verte, meilleures sont les performances du modèle par rapport à la moyenne des modèles similaires :

Bien que la précision varie selon les langues, les modèles jina-embeddings-v5-text atteignent des performances de pointe, ou proches de l’état de l’art, dans la majorité des langues du monde.

Pour en savoir plus sur les performances multilingues, consultez le rapport techniquejina-embeddings-v5-text .

Jina in Elastic : une IA native de pointe pour la recherche

Avec les modèles jina-embeddings-v5-text sur EIS, vous exécutez des modèles d’embeddings multilingues hautes performances de manière native dans Elasticsearch, avec une inférence entièrement gérée, accélérée par GPU, et sans infrastructure à provisionner ni à faire évoluer. Les modèles jina-embeddings-v5-text enrichissent le catalogue de modèles EIS en proposant des modèles multilingues compacts, tirant parti des dernières avancées en matière d’IA. Ces modèles affichent des performances de pointe sur les benchmarks de recherche d’information et d’analyse de données standard, tout en offrant une prise en charge multilingue inégalée à l’échelle mondiale.

Avec deux modèles de tailles très différentes, vous pouvez déterminer celui qui convient le mieux à vos applications et à votre budget. De plus, grâce à des embeddings robustes qui restent performants lorsqu’ils sont tronqués à des tailles plus réduites ou quantifiés avec une précision moindre, les modèles jina-embeddings-v5-text offrent des opportunités supplémentaires d’économies concrètes en matière de stockage, de coûts de calcul et de latence de traitement.

Avec la famille jina-embeddings-v5-text, Jina Reranker et la recherche vectorielle rapide et BM25 d’Elastic, vous bénéficiez désormais d’une recherche hybride de bout en bout, de pointe, proposée par Elastic. Lorsque vous avez besoin des résultats les plus pertinents, que ce soit pour des pipelines de génération augmentée par récupération (RAG), des applications de recherche ou des analyses de données, Elastic associé aux modèles Search AI de Jina vous garantit une qualité robuste et un excellent rapport coût-efficacité.

Premiers pas

Les modèles jina-embeddings-v5-text sont entièrement intégrés dans EIS, et vous pouvez les utiliser en définissant le champ typesur semantic_text lors de la création de votre index et en spécifiant le modèle (jina-embeddings-v5-text-small ou jina-embeddings-v5-text-nano) dans le champ inference_id, comme dans cet exemple :

PUT multilingual-semantic-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": ".jina-embeddings-v5-text-small"
      }
    }
  }
}

# Ingest data about France
POST multilingual-semantic-index/_doc
{
  "content": "The capital of France is Paris"}

GET multilingual-semantic-index/_search
{
  "query": {
    "semantic": {
      "field": "content",
      "query": "What is the French capital?"
    }
  }
}

Elasticsearch sélectionne automatiquement l’adaptateur LoRA approprié lors de l’indexation et de la recherche. Les dimensions de l'intégration (voir la section « Troncature des intégrations » ci-dessus) peuvent être définies lors de la création d'un point de terminaison d'inférence personnalisé.

Consultez la documentation Elasticsearch pour plus d'informations sur l'utilisation des modèles jina-embeddings-v5-text .

Plus d'informations

Pour en savoir plus sur les modèles jina-embeddings-v5-text, lisez les notes de publication sur le blog de Jina AI et le rapport technique, qui contiennent des informations techniques détaillées sur les performances et la nouvelle procédure de formation innovante de Jina AI. Pour plus d'informations sur le téléchargement et l'exécution de ces modèles localement, consultez la jina-embeddings-v5-text page de la collection sur Hugging Face.

Les modèles Jina AI sont disponibles sous licence CC-BY-NC-4.0, vous êtes donc libre de les télécharger et de les essayer, mais pour un usage commercial, veuillez contacter les ventes d’Elastic.

Dans cet article, vous apprendrez comment utiliser le paramètre de score minimum pour augmenter la précision de vos résultats de recherche sémantique. Si vous souhaitez tester les exemples fournis dans cet article de blog, accédez au notebook Jupyter associé.

Contexte : précision et rappel

En matière de pertinence de recherche, la précision et le rappel sont des concepts clés. Nous encourageons vivement les lecteurs qui ne les connaissent pas encore à se familiariser avec ces concepts. Voici un résumé.

• Précision : la fraction des résultats de recherche renvoyés qui sont pertinents pour l'utilisateur.
• Rappel : la fraction de tous les documents pertinents du corpus inclus dans l'ensemble des résultats de recherche.

En d'autres termes, la précision consiste à ne renvoyer que les résultats pertinents, tandis que le rappel consiste à renvoyer tous les résultats pertinents. Comme vous pouvez l'imaginer, ces deux exigences sont souvent contradictoires. La recherche sémantique a généralement un rappel très élevé, mais peut être à la peine en termes de précision. Poursuivez votre lecture pour découvrir comment contourner ce problème.

Présentation du paramètre de score minimum

Le paramètre "min_score" nous permet d'améliorer la précision en fixant un score minimum, ce qui tronquera le résultat en supprimant toutes les correspondances dont le score est inférieur au seuil défini. Voici un exemple simple :

GET search-movies/_search
{
  "retriever": {
    "linear": {
      "min_score": 4,
      "retrievers": [
        ...
      ]
    }
  }
}

Normalisation du score

Définir un score minimum est une bonne chose ; cependant, tous les modèles sémantiques ne renvoient pas un score adapté à un seuil statique. ELSER, par exemple, renvoie un score qui n'est pas limité. Certains scores de modèles denses sont fortement regroupés et n'ont de sens que dans le contexte de la requête spécifique.

Pour la plupart des cas de recherche sémantique, nous recommandons d'utiliser une approche de normalisation avant d'appliquer le "min_score". La normalisation garantit que le score du document se situe dans un intervalle défini. Les extracteurs Elasticsearch proposent deux normalisateurs de ce type, "l2_norm" et "minmax". Le plus couramment utilisé est "minmax", car il est facile à comprendre et fonctionne bien dans de nombreux scénarios. Voici les principales propriétés de "minmax" :

• Les scores des documents sont distribués entre 0 et 1.
• Le document ayant le score le plus élevé est toujours noté 1.
• Le document ayant obtenu le score le plus bas est toujours noté 0.
  • Cela peut le rendre moins adapté à la recherche par mots-clés. Voir la section "Recherche hybride" pour plus de détails.

Voici un exemple de requête sémantique normalisée avec min_score. La taille de la fenêtre de classement a été augmentée à 500 pour nous permettre de renvoyer une liste plus longue de résultats de recherche, en commençant à 100.

GET search-movies/_search
{
  "size": 100,
  "_source": [
    "title", "overview"
  ],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        }
      ]
    }
  }
}

La taille a été définie sur une valeur plus élevée que celle habituellement observée en production. Cela nous permet de contrôler la qualité des résultats de recherche et de les optimiser.

Recherche hybride utilisant l'extracteur linéaire

Pour la recherche hybride, l'approche la plus simple consiste à normaliser tous les scores, à leur attribuer des pondérations et à appliquer un score minimal. Notez qu'en choisissant des pondérations dont la somme est égale à 1, le score total reste compris entre 0 et 1. Cela facilite l'interprétation des scores finaux et l'ajustement de min_score. Voici un exemple :

GET search-movies/_search
{
  "size": 100,
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "weight": 0.6,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        },
        {
          "weight": 0.4,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "multi_match": {
                  "query": "superhero movie",
                  "fields": ["overview","keywords", "title"],
                  "type": "cross_fields",
                  "minimum_should_match": "2"
                }
              }
            }
          }
        }
      ]
    }
  }
}

Recherche hybride à l'aide de la RRF

Avec le BM25, nous contrôlons souvent la précision par d'autres moyens, par exemple en utilisant l'opérateur AND ou minimum_should_match. De plus, les requêtes composées de termes uniques, précis et rares entraîneront naturellement des résultats de recherche peu nombreux, souvent tous très pertinents. Cela peut causer les problèmes suivants :

• Les résultats situés plus loin dans le classement reçoivent un score normalisé faible dans l'extracteur BM25, même si le score BM25 absolu est proche des meilleurs résultats.
• Si l'on ajoute un score BM25 très faible au score sémantique, le total peut être considéré comme le score sémantique.
• L'absence de contribution au score BM25 peut entraîner la suppression du document par le min_score threshold.

Comme solution, nous pouvons plutôt utiliser la fusion des rangs réciproques (RRF) pour combiner les résultats BM25 et sémantiques. RRF contourne la difficulté de comparer les scores de différents algorithmes de recherche en se concentrant plutôt sur la position dans chaque ensemble de résultats. Dans ce scénario, le min_score est uniquement appliqué à l'extracteur sémantique.

GET search-movies/_search
{
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "rrf": {
      "rank_window_size": 500,
      "retrievers": [
        {
          "linear": {
            "rank_window_size": 500,
            "min_score": 0.25,
            "retrievers": [
              {
                "normalizer": "minmax",
                "retriever": {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "overview_vector",
                        "query": "superhero movie"
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "standard": {
            "query": {
              "multi_match": {
                "query": "superhero movie",
                "fields": ["overview", "keywords","title"],
                "type": "cross_fields",
                "minimum_should_match": "2"
              }
            }
          }
        }
      ]
    }
  }
}

Conclusion

En utilisant min_score, nous avons montré comment réduire le nombre de faux positifs dans nos ensembles de résultats causés par le fort rappel des algorithmes de recherche sémantique. Pour en savoir plus sur les extracteurs, veuillez consulter cet article de blog et la documentation d'Elasticsearch.

Gestion des dépendances chez Elastic

Chez Elastic, nous devons gérer des centaines, voire des milliers de référentiels privés et publics. Lorsqu'une CVE critique est découverte, nous avons besoin de réponses et d'actions immédiates : quels référentiels sont vulnérables ? Dans quel délai pouvons-nous les réparer ? Outre la sécurité, des questions de productivité se posent également : comment transmettre rapidement la publication d'une nouvelle version d'un package à tous les référentiels qui en dépendent, sans passer trop de temps à effectuer des tâches manuelles ?

La recherche de méthodes de gestion des dépendances a été motivée à l'origine par la nécessité d'établir une base sécurisée avec des mises à jour automatisées pour réduire les CVE. Après avoir soigneusement réfléchi aux solutions de gestion des dépendances, nous avons d'abord commencé à travailler sur une infrastructure auto-hébergée. Nous utilisions notre propre cluster Kubernetes pour exécuter Mend Renovate Community auto-hébergé. L'idée était de pouvoir fournir une plateforme de gestion des dépendances à laquelle nos utilisateurs pourraient accéder en libre-service.

L'expérience initiale s'est avérée fructueuse, si bien que de plus en plus d'équipes ont commencé à adopter notre plateforme et à l'utiliser dans le cycle de vie quotidien de leurs référentiels pour les mises à jour et les correctifs CVE. Cela s'est passé si vite que nous avons rapidement atteint les limites de notre installation auto-hébergée.

Le défi : comment pouvons-nous scaler une plateforme de gestion des dépendances dans une grande organisation disposant d'un nombre important de référentiels ?

Notre plateforme de gestion des dépendances traitait un référentiel à la fois et le modèle de traitement séquentiel ne pouvait pas suivre le rythme, compte tenu du grand nombre de référentiels que nous gérons. Nous avions déjà constaté que le problème provenait du fait qu'une seule instance de notre outil de gestion des dépendances pouvait traiter notre liste importante et toujours croissante de référentiels. Les référentiels attendaient parfois pendant plusieurs heures dans une file d'attente. Plus de 50 % de nos référentiels n'étaient même pas traités quotidiennement. Autrement dit, plus de la moitié de nos référentiels attendaient plus de 24 heures entre les analyses.

Les grands référentiels ont créé des goulots d'étranglement plus importants, en raison de leurs bases de code volumineuses et de leurs multiples requêtes pull ouvertes. Les événements du webhook GitHub ont perturbé la séquence. La fusion automatique est devenue peu fiable car le moment des analyses était imprévisible. Nous avions fait une promesse à nos utilisateurs concernant la fréquence des analyses, mais nous n'avons pas pu la tenir.

La décision de développer en interne : répondre aux besoins uniques de scalabilité et de sécurité d'Elastic

Bien que nous envisagions des options commerciales, dont l'édition auto-hébergée Renovate Enterprise de Mend, nous avions en interne chez Elastic quelques initiatives clés en cours de développement.

Notre décision de créer une plateforme en interne a été motivée par la prise de conscience que seule une solution hautement personnalisée pouvait répondre aux exigences spécifiques et non négociables d'Elastic :

1. Investissement dans notre plateforme de développement interne : à l'époque, nous avions déjà investi massivement dans notre plateforme de développement interne. Nous réfléchissions à la manière d'intégrer chacun de nos services à cette plateforme et nous concevions des solutions pour y parvenir. Cela impliquait de tester nos propres règles et pratiques pour notre plateforme de gestion des dépendances. De plus, de nouvelles directives entraient en vigueur et nous souhaitions concevoir la plateforme en amont.
2. Intégration native et personnalisation du workflow : nous avions besoin d'une intégration simple à nos outils et processus internes. Par exemple, nous souhaitions centraliser la configuration sous forme de code avec notre catalogue de services (Backstage). L'utilisation de Backstage nous impose des exigences spécifiques avec lesquelles nous voulions que notre plateforme soit compatible. Ainsi, bien qu'il soit possible d'utiliser les API auto-hébergées de Renovate en complément de notre automatisation Backstage, cela ne couvrirait pas entièrement nos processus internes.
3. Sécurité renforcée par défense en profondeur spécifique à Elastic : notre conformité stricte en matière de sécurité exigeait des mécanismes de sécurité sur mesure, adaptés à notre écosystème. Nous nous efforcions de renforcer la sécurité de notre utilisation des "identités non humaines". Ce renforcement des accès impliquait que les méthodes d'authentification non standard auprès de GitHub ne fonctionneraient pas avec un outil standard qui ne prenait pas en charge cette implémentation interne. Notre workflow comprenait la mise en œuvre d'un modèle de chiffrement des secrets de workflow parent-enfant et l'utilisation de jetons GitHub temporaires à usage unique. Le développement en interne était la seule solution pratique pour intégrer ces couches de sécurité uniques et minimiser la surface d'attaque dans notre environnement multicloud complexe.

La solution : l'orchestration des workflows pour la gestion des dépendances

Notre solution est née de notre volonté de tirer parti de l'outil de gestion des dépendances que nous utilisions déjà plutôt que de le remplacer et rechercher d'autres solutions. Cet outil avait démontré son potentiel, et sa flexibilité est essentielle pour répondre aux différents besoins de notre organisation. Nous avons examiné différentes solutions, et ce qui a guidé notre choix, ce sont les besoins importants et parfois spécifiques que nous devons satisfaire. Nous avons donc décidé de créer une plateforme de gestion des dépendances fiable et évolutive, où chaque référentiel est traité individuellement, éliminant ainsi les goulots d'étranglement et nous préparant à la croissance.

Nous avons conçu la plateforme en respectant trois principes fondamentaux :

1. Traitement parallèle

Chaque référentiel est doté de son propre environnement de gestion des dépendances. Plus de files d'attente. Notre simultanéité d'exécution n'est limitée que par le nombre de ressources que nous utilisons. Nous avons également appliqué une programmation distribuée intelligente pour éviter d'être limité par GitHub.

2. Libre-service

Nous utilisons notre catalogue de services (Backstage) pour intégrer et gérer automatiquement les nouveaux référentiels. Grâce à notre propre système de définition des ressources, l'utilisateur final peut choisir la fréquence de traitement des référentiels, le nombre de ressources à allouer à ses planifications, et activer ou désactiver le traitement à tout moment. Nous prévoyons d'ajouter d'autres options à mesure que les besoins de nos utilisateurs évoluent et qu'ils se familiarisent avec la nouvelle installation.

3. Réduction de la portée des secrets et de l’isolation des espaces de noms

Pour une sécurité accrue, nous fournissons à nos modules de gestion des dépendances des jetons GitHub éphémères qui sont générés au début de chaque workflow. En outre, nous isolons nos charges de travail dans des espaces de noms spécifiques afin de ne leur fournir que les secrets nécessaires. Nous contrôlons les secrets qui peuvent être accessibles par chaque workflow de gestion des dépendances en utilisant le RBAC de Kubernetes. Nous utilisons également le chiffrement pour transmettre le jeton GitHub du workflow parent au workflow enfant.

Nous avons reconstruit notre plateforme en utilisant Kubernetes et en exploitant sa puissance. Argo Workflows gère la logique de nos processus et Renovate CLI est configuré pour analyser et traiter un référentiel à la fois.

L'intérêt de ce modèle : nous utilisons des projets open source éprouvés d'une manière originale, en fournissant de nouveaux exemples fonctionnels pour tous ces projets et, en même temps, en amplifiant la vitesse de développement et en consolidant la réduction des CVE pour nos équipes.

Architecture de gestion des dépendances : Quatre microservices

La plateforme comprend quatre composants conçus sur mesure :

Opérateur de workflow (Go/Kubebuilder)

Un opérateur Kubernetes gérant le cycle de vie du workflow à travers trois définitions de ressources personnalisées (CRD) :

• CRD RepoConfig : source unique de référence pour la configuration du référentiel.

Voici comment RepoConfig est défini dans l'opérateur :

// RepoConfig is the Schema for the repoconfigs API
type RepoConfig struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of RepoConfig
	// +required
	Spec RepoConfigSpec `json:"spec"`

	// status defines the observed state of RepoConfig
	// +optional
	Status RepoConfigStatus `json:"status,omitempty,omitzero"`
}

Et voici à quoi ressemblerait une instance de RepoConfig :

apiVersion: workflows.elastic.co/v1
kind: RepoConfig
metadata:
  generation: 3
  name: elastic-test-repo
  namespace: dependency-management-operator
spec:
  owner: group:my-team
  renovate:
    config:
      resourceGroup: SMALL
      runFrequency: 4h
    enabled: true
  repository: elastic/test-repo

• CRD parent : gère les workflows Cron pour les analyses programmées.

À l'intérieur de la boucle de rapprochement du contrôleur parent, nous nous assurons que les paramètres du workflow sont créés et maintenus à jour, voire supprimés si nécessaire.

Tout d'abord, le contrôleur parent obtient certains paramètres configurés globalement pour les workflows :

func (r *ParentReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, parent *workflowsv1.Parent) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Parent", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		RunFrequency:   parent.Spec.RunFrequency,
		ResourceGroups: "parent",
	}

Il s'assure que la configuration du mutex est à jour afin d'empêcher l'exécution simultanée de workflows similaires :

	cfMngr := resources.NewConfigMapManager(r.Client, r.Scheme, r.OperatorConfig.ParentNamespace)
	err := cfMngr.CreateOrUpdateSyncMutexConfigmap(ctx, fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), strings.TrimPrefix(parent.Spec.Repository, "elastic/"), r.OperatorConfig.SemaphoreConcurrencyLimit)

Ensuite, il crée un gestionnaire de workflow qui est la structure qui va créer ou mettre à jour les workflows Cron et les modèles de workflow :

	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(parent.Spec.Repository, "/", "-"),
		),
		parent.Namespace,
		"parent-workflow",
		false).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithRepoName(parent.Spec.Repository).
		Init(true, true).
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithWfTemplateName(r.OperatorConfig.ParentWorkflowTemplate).
		WithResources(wfSet.GetResourceCategory()).
		WithSchedule(wfSet.GetCronSchedule()).
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddArgument(true, true, "extra_cli_args").
		SetArgument(true, false, "extra_cli_args", "none").
		AddTemplate(resources.NewParentDAGTemplateInstance()).
		AddTemplate(resources.NewWorkflowsTemplateInstance("check-child-workflows", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("security", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("submit-child-workflow", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector))
	wfMngr.OverWriteCommand("submit-child-workflow", r.OperatorConfig.ChildNamespace)
	wfMngr.OverwriteWfTemplateName("parent-wftmpl")
	wfMngr.AddSynchronization(fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), "{{workflow.parameters.repo_name}}")
	err = wfMngr.CreateOrUpdateCronWorkflow(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update cron workflow: %w", err)
	}
	err = wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil

• CRD enfant : gère les modèles de workflow avec des ressources par référentiel.

Le contrôleur enfant a une mission de rapprochement similaire à celle du parent, mais ici, il est responsable des modèles de workflow dans l'espace de noms enfant qui seront déclenchés par les workflows parents.

func (r *ChildReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, child *workflowsv1.Child) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Child", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		ResourceGroups: child.Spec.ResourceCategory,
	}
	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(child.Spec.Repository, "/", "-"),
		),
		child.Namespace,
		"runner",
		true).
		Init(false, true). // only manage workflow template
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithSuffix("-child-wftmpl").
		WithRepoName(child.Spec.Repository).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithResources(wfSet.GetResourceCategory()). // will override resources of presets if set
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddTemplate(resources.NewWorkflowsTemplateInstance("runner", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddArgument(false, true, "repo_full_name").
		AddArgument(false, true, "repo_name").
		AddArgument(false, true, "encrypted_token").
		AddArgument(false, true, "extra_cli_args")
	wfMngr.OverWriteCommand("runner", r.OperatorConfig.ChildNamespace)
	err := wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil
}

Le modèle multicontrôleur offre une séparation claire : le contrôleur RepoConfig gère l'intégration/dissociation, le contrôleur parent gère la planification, et le contrôleur enfant gère les modèles d'exécution.

Portail d'événements GitHub (Go)

Proxy sécurisé de webhook qui reçoit les webhooks GitHub, vérifie les signatures, filtre par organisation/référentiel, et redirige vers Argo Events. Nous avons conçu 10 capteurs distincts répondant aux interactions du tableau de bord des dépendances, aux événements de requêtes pull (PR) et aux mises à jour des packages.

Cette passerelle permet l'intégration aux applications GitHub par :

• Vérification de la sécurité des signatures des webhooks GitHub entrants.
• Transmission des événements valides à l'EventSource Argo Events avec tous les en-têtes correspondants et l'authentification.
• Nous configurons également un authSecret sur l'EventSource et le fournissons comme en-tête Bearer dans les requêtes transférées.
• Fourniture de logging, indicateurs, et logique de tentatives.

Le webhook effectue diverses validations sur chaque requête d'événement GitHub.

Il s'assure que certains attributs HTTP sont présents :

// ValidateRequestMethod checks if the request method is POST.
func ValidateRequestMethod(r *http.Request) error {
	if r.Method != http.MethodPost {
		return fmt.Errorf("method not allowed, only POST is accepted")
	}
	return nil
}

// ValidateRequiredHeaders checks for required GitHub headers.
func ValidateRequiredHeaders(r *http.Request) error {
	eventType := r.Header.Get("X-GitHub-Event")
	deliveryID := r.Header.Get("X-GitHub-Delivery")
	signature := r.Header.Get("X-Hub-Signature-256")
	if eventType == "" || deliveryID == "" || signature == "" {
		return fmt.Errorf("missing required GitHub headers")
	}
	return nil
}

// ValidateUserAgent checks that the User-Agent header starts with GitHub-Hookshot/
func ValidateUserAgent(r *http.Request) error {
	userAgent := r.Header.Get("User-Agent")
	if !strings.HasPrefix(userAgent, "GitHub-Hookshot/") {
		return fmt.Errorf("invalid User-Agent")
	}
	return nil
}

Tout en validant également la signature de chaque requête et son organisation :

// ValidateSignature verifies the GitHub webhook signature.
func ValidateSignature(r *http.Request, secret string) ([]byte, error) {
	payload, err := GitHub.ValidatePayload(r, []byte(secret))
	if err != nil {
		return nil, fmt.Errorf("invalid GitHub signature: %w", err)
	}
	return payload, nil
}

// ValidateAllowedOwner checks if the organization login is in the allowed organizations list.
func ValidateAllowedOwner(payload []byte, allowedGitHubOrganizations []string) (string, error) {
	var orgLogin string
	var payloadMap map[string]any
	if err := json.Unmarshal(payload, &payloadMap); err == nil {
		if orgObj, ok := payloadMap["organization"].(map[string]any); ok {
			if login, ok := orgObj["login"].(string); ok {
				orgLogin = login
			} else if name, ok := orgObj["name"].(string); ok {
				orgLogin = name
			}
		}
	}
	if !slices.Contains(allowedGitHubOrganizations, orgLogin) {
		return orgLogin, fmt.Errorf("organization login not allowed")
	}
	return orgLogin, nil
}

Enfin, il redirige vers Argo Events en fonction du type d'événement :

	// Map eventType to Argo `EventSource` path
	var endpoint string
	switch eventType {
	case "push":
		endpoint = "/push"
	case "issues":
		endpoint = "/issues"
	case "pull_request":
		endpoint = "/pull-requests"
	default:
		slog.Info("Ignoring unhandled event type", "event_type", eventType, "delivery_id", deliveryID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}
	forwardURL := h.config.ArgoEventSourceForwardURL + endpoint

Du côté d'Argo Events, 10 capteurs surveillent l'EventBus d'Argo pour détecter les nouveaux événements.

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: {{ .Values.sensors.packageUpdateOnDefaultBranch.name }}
  namespace: {{ .Release.Namespace }}
spec:
  eventBusName: {{ .Values.eventBus.name }}

Le script applique ensuite la logique de chaque capteur :

script: |
          local e = event
          if not e or not e.body or not e.body.repository then
            return false
          end

          -- e.g., "refs/heads/main"
          local ref = e.body.ref
          local default_branch = e.body.repository.default_branch
          if not ref or not default_branch then
            return false
          end

          local expected = "refs/heads/" .. default_branch
          if ref ~= expected then
            return false
          end

        {{- if .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}
          patterns = { {{- range $i, $f := .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}{{ if $i }}, {{ end }}"{{ $f }}"{{- end }} }
        {{- end }}

          local function anyMatch(path)
            if type(path) ~= "string" then return false end
            for _, pat in ipairs(patterns) do
              -- match filename at repo root, or anywhere under subdirs
              if path:match(pat) or path:match(".+/" .. pat) then
                return true
              end
            end
            return false
          end

          local function filesContainPackage(paths)
            if type(paths) ~= "table" then return false end
            for _, p in ipairs(paths) do
              if anyMatch(p) then return true end
            end
            return false
          end

          -- Inspect all commits (GitHub includes added/modified/removed lists)
          local commits = e.body.commits
          if type(commits) ~= "table" then
            -- Fallback: some payloads include only head_commit
            commits = {}
            if type(e.body.head_commit) == "table" then
              table.insert(commits, e.body.head_commit)
            end
          end

          for _, c in ipairs(commits) do
            if filesContainPackage(c.added) or filesContainPackage(c.modified) or filesContainPackage(c.removed) then
              return true
            end
          end

          return false

Backstage Syncer (Go)

Ce composant interroge notre catalogue de services (Backstage) pour obtenir les entités de ressources réelles du référentiel, les transforme en CRD RepoConfig et maintient la plateforme synchronisée avec les modifications de configuration. Celles-ci sont appliquées en trois minutes.

repoMap := make(map[string]map[string]interface{})
			for i := range entities {
				entity := &entities[i]
				if entity.Spec.Type != "GitHub-repository" {
					continue
				}

				implRaw, err := json.Marshal(entity.Spec.Implementation)
				if err != nil {
					logger.Error("Failed to marshal implementation", "error", err)
					continue
				}

				var implMap map[string]interface{}
				err = json.Unmarshal(implRaw, &implMap)
				if err != nil {
					logger.Error("Failed to unmarshal implementation map", "error", err)
					continue
				}
				var repoName string
				if specMap, ok := implMap["spec"].(map[string]interface{}); ok {
					if repo, ok := specMap["repository"].(string); ok {
						repoName = repo
					}
				}
				if repoName == "" {
					continue
				}

				var workflowsRaw []byte
				if v, ok := implMap["spec"].(map[string]interface{}); ok {
					if r, ok := v["renovate"]; ok {
						workflowsRaw, _ = json.Marshal(r)
					} else {
						workflowsRaw = []byte(`{}`)
					}
				} else {
					workflowsRaw = []byte(`{}`)
				}

				var workflowsWithDefaults schema.WorkflowsMetadata
				err = json.Unmarshal(workflowsRaw, &rworkflowsWithDefaults)
				if err != nil {
					logger.Error("Failed to unmarshal workflows config", "error", err)
					continue
				}

				workflowsMap := map[string]interface{}{
					"enabled":        workflowsWithDefaults.Enabled,
					"require_pr":     workflowsWithDefaults.RequirePr,
					"resource_group": string(workflowsWithDefaults.ResourceGroup),
					"run_frequency":  string(workflowsWithDefaults.RunFrequency),
				}
				repoMap[repoName] = map[string]interface{}{
					"renovate": workflowsMap,
					"owner":    entity.Spec.Owner,
				}
			}
			logger.Info("Fetched GitHub Repository data from Backstage", "repository_count", len(repoMap), "status_code", resp.StatusCode)

Enfin, il écrit ces données dans des instances RepoConfig.

Base de workflows (mixte : JavaScript, Go, Helm)

La couche de base contient des charts Helm, des configurations JavaScript, un wrapper Go pour Renovate CLI avec prise en charge du chiffrement et un indexeur APK personnalisé pour les packages Alpine.

Configuration en libre-service

Les équipes configurent leurs référentiels de manière déclarative via Backstage :

spec:
  renovate:
    enabled: true
    config:
      resourceGroup: LARGE      # SMALL | MEDIUM | LARGE  
      runFrequency: "0 */4 * * *"  # Every 4 hours

Les groupes de ressources allouent le processeur et la mémoire en fonction de la taille du référentiel :

• SMALL : CPU 500 m, mémoire 1 Go.
• MEDIUM : CPU 1000 m, mémoire 2 Go.
• LARGE : CPU 2000 m, mémoire 4 Go.

La configuration est versionnée, auditable et s'applique automatiquement.

Le modèle parent-enfant

Le modèle d'exécution utilise un modèle de workflow parent-enfant :

• Workflow parent : workflow Cron léger qui s'exécute comme prévu. Chiffre les secrets, détermine si une analyse doit être exécutée, transmet la configuration à l'enfant.
• Workflow enfant : pod éphémère où s'exécute Renovate CLI. Allocation dynamique des ressources, déchiffrement des secrets de manière isolée, arrêt après exécution.

Cette séparation offre sécurité (secrets chiffrés au niveau parent), optimisation des ressources (les parents utilisent des ressources minimales) et scalabilité (les enfants s'exécutent en parallèle).

Résultats

Transformation des performances

• Avant : un référentiel à la fois, certains référentiels n'étaient pas traités, parfois même pendant un jour ou plus, moins de 1 000 analyses par jour.
• Après : plus de 100 analyses simultanées, généralement 8 000 analyses et jusqu'à 10 000 analyses enregistrées par jour, limitées uniquement par la quantité de ressources que nous sommes prêts à consacrer et par la façon dont nous gérons les limites de débit de GitHub.

Rentabilité

Cependant, aussi étrange que cela puisse paraître, exécuter 8 000 pods par jour peut permettre d'obtenir le même résultat à moindre coût qu'avec un seul pod fonctionnant en continu pour tenter d'atteindre le même résultat.

Dans la configuration précédente, nous utilisions une seule instance qui, en conditions optimales, effectuait 500 à 600 analyses. Par ailleurs, comme différents types de référentiels étaient exécutés sur le même pod, nous devions dimensionner celui-ci pour les plus volumineux. Ce dimensionnement était bien supérieur à notre offre actuelle "extra large", qui utilise 8 cœurs de processeur et 16 Go de mémoire par pod.

Pour traiter le volume quotidien actuel, le pod unique devrait s'exécuter pendant 12 jours. Ainsi, en comparant le coût de ce pod unique fonctionnant pendant 12 jours à celui de 8 000 pods de taille "MEDIUM" s'exécutant chaque jour, notre nouvelle architecture est bien plus efficace pour un même volume d'analyses.

Cependant, prenons en considération le fait que notre valeur par défaut pour nos charges de travail est définie sur "SMALL", la grande majorité fonctionnant correctement avec une utilisation CPU de 0,5 Go et 1 Go de RAM, et seules quelques-unes nécessitant une configuration moyenne ou grande. Voyons ce qui se passe si 60 % de nos charges de travail s'exécutent sur "SMALL", 30 % sur "MEDIUM" et 10 % sur "LARGE", ce qui est plus proche de la réalité.

Nous pouvons constater que, pour le même volume, nous sommes beaucoup plus rentables dans notre configuration actuelle.

Sécurité renforcée

• Jetons GitHub éphémères (minutes d'exposition contre plusieurs jours).
• Isolation d'espace de nom avec limites de contrôle d'accès basé sur les rôles (RBAC).
• Chiffrement des secrets au repos dans les workflows parents.
• Accès direct au coffre-fort supprimé.

Performance prévisible

Grâce à une fréquence d'analyse garantie, nous pouvons enfin définir des objectifs de niveau de service (SLO). La fusion automatique fonctionne de manière fiable. Les équipes ont confiance en la plateforme pour tenir ses promesses.

Décisions architecturales clés

Voici quelques-unes des décisions de conception majeures qui ont façonné l'apparence de la plateforme.

• Pourquoi des workflows parent-enfant ?

Nous avons adopté ce modèle pour mettre en œuvre une stratégie de défense en profondeur. En limitant les identifiants sensibles (tels que les secrets d'applications GitHub) à un espace de noms dédié et sécurisé, nous utilisons le RBAC pour garantir que les pods d'exécution éphémères ne puissent pas accéder arbitrairement aux données sensibles. De récentes vulnérabilités de la chaîne d'approvisionnement (par exemple, les attaques "Shai Hulud" ciblant l'intégration continue et le déploiement continu [CI/CD]) ont démontré l'importance cruciale d'isoler les environnements d'exécution qui exécutent des scripts dynamiques depuis le magasin d'identifiants.

Simultanément, ce découplage permet une optimisation granulaire des ressources. Les workflows "parents" agissent comme des orchestrateurs légers avec un encombrement minimal, tandis que les workflows "enfants" gèrent l'analyse des dépendances gourmande en ressources IT. Cette séparation simplifie la gestion du cycle de vie en nous permettant d'appliquer une logique de rapprochement distincte à chaque couche, offrant ainsi aux utilisateurs le contrôle des paramètres d'exécution (enfants) tout en conservant le contrôle administratif sur l'infrastructure de planification et de sécurité (parents).

• Pourquoi en libre-service ?

Il était essentiel d'éliminer notre équipe comme goulot d'étranglement pour la configuration des référentiels. Notre mission était de concevoir une plateforme scalable et en libre-service, capable de prendre en charge divers cas d'utilisation. Nous avons constaté qu'il était impossible, compte tenu du nombre considérable de référentiels, de jouer le rôle de contrôleur d'accès pour chaque modification de configuration. Nous avons donc adopté une approche axée sur l'enablement : fournir les "rails" (l'infrastructure et les garde-fous), tout en donnant aux utilisateurs les moyens d'agir et de conduire les "trains" (l'exécution et la personnalisation). Nous pensons que cette évolution vers l'autonomie des équipes améliore considérablement la productivité en permettant aux utilisateurs d'adapter le système à leurs besoins opérationnels spécifiques.

• Pourquoi le modèle d'opérateur Kubernetes ?

Comme indiqué précédemment, un principe de conception fondamental consistait à garantir que la plateforme soit entièrement en libre-service. Nous avions besoin d'un mécanisme automatisé pour capturer les intentions de l'utilisateur (par exemple, activer/désactiver les analyses, ajuster la fréquence de planification ou paramétrer les limites des ressources d'exécution) et transmettre instantanément ces modifications aux workflows sous-jacents. Afin d'anticiper les besoins futurs, le système devait aussi être facilement extensible.

Pour ce faire, nous avons développé un opérateur Kubernetes de gestion des dépendances personnalisé. En utilisant les CRD comme interface de configuration, nous avons établi une boucle de rapprochement native Kubernetes. Cet opérateur surveille en permanence l'état souhaité défini par l'utilisateur et orchestre automatiquement les mises à jour nécessaires de l'infrastructure de workflow. Ceci garantit un fonctionnement transparent et piloté par les événements, où la logique de la plateforme gère toute la complexité en arrière-plan.

• Pourquoi concevoir une passerelle d’événements GitHub ?

L'adoption d'une architecture pilotée par les événements (EDA) était essentielle à la réactivité de la plateforme. Si les workflows Cron fournissaient une planification de base fiable, nous avions besoin d'agilité pour gérer les exécutions ad hoc, comme le déclenchement manuel d'analyses par les utilisateurs via le tableau de bord. Pour ce faire, nous avions besoin d'une passerelle d'ingestion dédiée afin de valider l'intégrité des données et acheminer intelligemment les requêtes.

Nous avons évalué les solutions existantes, notamment l'EventSource natif de GitHub pour Argo, mais nous avons identifié des risques importants liés à la surcharge opérationnelle et aux quotas stricts de l'API GitHub (par exemple, les limites de webhook par référentiel). Par conséquent, nous avons développé une passerelle personnalisée afin de découpler notre infrastructure de ces limitations.

Cette passerelle s'est avérée cruciale en tant que point de contrôle du trafic lors de notre migration. Elle a agi comme un commutateur, nous permettant d'effectuer un déploiement progressif et granulaire (transfert de trafic) de l'ancien système vers la nouvelle infrastructure. Ainsi, l'intégration de milliers de référentiels s'est déroulée de manière contrôlée et sans risque, plutôt que par une transition brutale.

Enseignements

Certains enseignements que nous avons tirés vont de pair avec le code source d'Elastic :

1. Priorité au client : les plateformes sont conçues pour les utilisateurs. Il est donc essentiel de placer leurs besoins au cœur de nos priorités. Cela permet de concevoir une infrastructure et des applications performantes qui réduisent les obstacles pour les utilisateurs, simplifient le scaling de la plateforme et facilitent son adoption.
2. Espace, temps : parfois, la voie de la facilité mène à des sables mouvants. Nous avons d'abord tenté d'optimiser le modèle de traitement séquentiel existant, mais cela n'a pas résolu nos problèmes ; au contraire, cela n'a fait qu'accroître la complexité et créer des zones d'ombre. La décision audacieuse de repenser l'architecture de la plateforme avec un traitement parallèle a nécessité un investissement initial important. Cependant, elle a finalement ouvert la voie à une croissance durable de la plateforme et a quasiment éliminé les tâches administratives quotidiennes fastidieuses.
3. Informatique, dépendances : une plateforme ne peut pas fonctionner de manière isolée ; son succès dépend de la manière dont elle s'intègre dans un écosystème plus large. Dans notre cas, l'intégration à Backstage était essentielle, car elle constitue la source de référence pour une intégration fluide des services. De même, la connexion à Artifactory nous a permis de gérer efficacement les mises à jour des packages privés, et la liste des intégrations essentielles ne s'arrête pas là.
4. Progrès, perfection SIMPLE : tout au long de la mise en œuvre, nous avons constamment testé nos hypothèses initiales et nous nous sommes adaptés aux nouveaux obstacles à mesure qu'ils apparaissaient. Plutôt que de nous laisser paralyser par le perfectionnisme, nous avons adopté une approche itérative, en relevant les défis les uns après les autres et en ajustant notre stratégie de migration aux conditions réelles.

Prochaines étapes

La mise en place de la plateforme nous permet de nous consacrer à des tâches plus importantes qui contribueront à améliorer l'expérience utilisateur et l'efficacité de notre plateforme. En voici quelques exemples :

• Renforcer et garantir l'adoption de la fusion automatique

La fonctionnalité de fusion automatique accélère considérablement la rapidité de l'équipe en éliminant les tâches manuelles fastidieuses. Toutefois, il est essentiel de mettre en place des garde-fous stricts afin de garantir que cette rapidité accrue ne s'obtienne pas au détriment de la sécurité.

• Améliorer la visibilité sur l'expérience des utilisateurs finaux

L'une des priorités essentielles de notre feuille de route est l'amélioration de l'observabilité, non seulement au niveau de la plateforme, mais aussi du point de vue de l'utilisateur final. Si la collecte des indicateurs d'infrastructure est simple, la compréhension de l'expérience utilisateur réelle exige une analyse plus approfondie. Nous travaillons à la définition d'indicateurs clés de performance (KPI) centrés sur l'utilisateur afin que notre système de télémétrie puisse détecter les points de friction et les problèmes de performance avant qu'ils ne se transforment en plaintes d'utilisateurs.

• Supprimer les obstacles à une plus grande adoption

Pour l'avenir, notre priorité est d'identifier et de lever les obstacles à l'adoption de la plateforme. Qu'il s'agisse de développer de nouvelles intégrations ou de déployer des fonctionnalités spécifiques, nous privilégions une planification fondée sur les données. Nous avons développé avec succès une plateforme conçue pour évoluer ; notre objectif est désormais d'en maximiser le potentiel.

Le tableau d'ensemble

Le projet de workflows de gestion des dépendances illustre un principe plus large : lorsque vous devez scaler des outils open source au-delà de leur modèle de déploiement par défaut, les modèles natifs Kubernetes offrent une voie à suivre.

En adoptant :

• Les CRD pour la configuration.
• Les opérateurs pour la gestion du cycle de vie.
• Une architecture basée sur les événements pour une meilleure réactivité
• GitOps pour le déploiement.

Nous avons conçu une orchestration qui scale indépendamment du nombre de référentiels gérés. Les performances d'analyse d'un seul référentiel restent identiques, que nous en gérions 100 ou 1 000.

Lorsqu'une CVE critique est annoncée, nous obtenons désormais des réponses en quelques minutes, et non plus en quelques heures. C'est ce qui fait la différence entre un goulot d'étranglement et un avantage concurrentiel.

Remerciements

Cette plateforme s'appuie sur d'excellents outils open source :

• Kubebuilder : le framework open source que nous avons utilisé pour lancer nos opérateurs Kubernetes qui démarrent et orchestrent nos workflows. [1][2]
• Backstage : le framework open source sur lequel nous avons construit notre catalogue de services et que nous utilisons comme source de référence. [1][2]
• Argo Workflows et Argo Events : la suite open source que nous avons utilisée pour orchestrer des processus complexes et ajouter un traitement dynamique basé sur des événements. [1][2][3][4]
• Renovate CLI : l'outil open source de gestion des dépendances qui traite nos référentiels. [1][2]

* Le modèle de tarification AWS Fargate a été utilisé comme référence pour le coût d'un seul pod, bien que nos charges de travail ne s'exécutent pas nécessairement sur AWS et s'exécutent sur des clusters Kubernetes complets.

Lors de l'optimisation d'Elasticsearch pour des charges de travail à forte simultanéité, l'approche standard consiste à maximiser la RAM afin de conserver l'ensemble des documents de travail en mémoire et d'obtenir une faible latence de recherche. Par conséquent, best_compression est rarement l'option choisie pour les charges de travail de recherche, car il est principalement perçu comme une mesure d'économie d'espace pour les cas d'utilisation d'Elastic Observability et d'Elastic Security où l'efficacité du stockage est prioritaire.

Dans ce blog, nous démontrons que lorsque la taille de l'ensemble de données dépasse nettement le cache de page du système d'exploitation, best_compression améliore les performances de recherche et l'efficacité des ressources en réduisant le goulot d'étranglement des E/S.

La configuration

Notre cas d'utilisation est une application de recherche à forte simultanéité qui s'exécute sur des instances Elastic Cloud optimisées pour le processeur.

• Volume de données : ~500 millions de documents
• Infrastructure : 6 instances Elastic Cloud (Elasticsearch Service) (chaque instance : 1,76 To de stockage | 60 Go de RAM | 31,9 vCPU)
• Rapport mémoire/stockage : la RAM peut recevoir environ 5 % du volume total de données

Les symptômes : latence élevée

Nous avons constaté qu'aux alentours de 19:00, lorsque le nombre de requêtes augmentait fortement, la latence de recherche s'est considérablement dégradée. Comme le montrent les figures 1 et 2, lorsque le trafic atteignait un pic d'environ 400 requêtes par minute et par instance Elasticsearch, le temps de réponse moyen des requêtes chutait à plus de 60 ms.

L'utilisation du processeur est restée relativement faible après le traitement initial des connexions, indiquant que le calcul n'était pas le facteur limitant.

Une forte corrélation est apparue entre le volume de requêtes et les défauts de page. À mesure que les requêtes augmentaient, nous avons observé une hausse proportionnelle des défauts de page, avec un pic aux alentours de 400k/minute. Cela indique que l'ensemble de données actif ne pouvait pas être contenu dans le cache de pages.

Parallèlement, l'utilisation du tas JVM semblait normale et saine. Cela a permis d'exclure les problèmes de récupération de mémoire et de confirmer que le goulot d'étranglement était lié aux entrées/sorties.

Le diagnostic : I/O bound

Le système était limité par les E/S. Elasticsearch s'appuie sur le cache de pages du système d'exploitation pour fournir les données d'index depuis la mémoire. Lorsque l'index est trop volumineux pour le cache, les requêtes entraînent des lectures disque coûteuses. Bien que la solution classique consiste à effectuer un scaling horizontal (ajout de nœuds/RAM), nous souhaitions d'abord optimiser au maximum nos ressources existantes.

La solution

Par défaut, Elasticsearch utilise la compression LZ4 pour ses segments d'index, qui offre un bon compromis entre vitesse et taille. Nous avons émis l'hypothèse que le passage à best_compression (qui utilise zstd) réduirait la taille des index. Une empreinte mémoire plus faible permet d'intégrer une plus grande partie de l'index dans le cache de pages, moyennant une augmentation négligeable de la charge CPU (pour la décompression) au profit d'une réduction des E/S disque.

Pour activer best_compression, nous avons réindexé les données avec le paramètre d'index index.codec: best_compression. Sinon, le même résultat pourrait être obtenu en fermant l'index, en réinitialisant le codec d'index à best_compression, puis en effectuant une fusion de segments.

POST my-index/_close
PUT my-index/_settings
{
    "codec": "best_compression"
}
  
POST my-index/_open  
POST my-index/_forcemerge?max_num_segments=1

Résultats

Les résultats ont confirmé notre hypothèse : l'amélioration de l'efficacité du stockage s'est directement traduite par une augmentation substantielle des performances de recherche sans augmentation concomitante de l'utilisation du processeur.

L'application de best_compression a réduit la taille de l'index d'environ 25 %. Bien qu'inférieure à la réduction observée dans les données de log répétitives, cette réduction de 25 % a effectivement augmenté la capacité de notre cache de pages dans les mêmes proportions.

Lors du test de charge suivant (à partir de 17:00), le trafic était encore plus élevé, avec un pic de 500 requêtes par minute et par nœud Elasticsearch.

Malgré la charge plus élevée, l'utilisation du processeur était inférieure à celle de l'exécution précédente. L'utilisation élevée dans le test précédent était probablement due à la surcharge liée à la gestion excessive des défauts de page et à la gestion des E/S de disque.

Surtout, le nombre de défauts de page diminue de manière significative. Même à un débit plus élevé, les erreurs se situent autour de <200k par minute, contre >300k dans le test de référence.

Bien que les résultats concernant les défauts de page soient encore loin d'être optimaux, le temps de réponse aux requêtes a été réduit d'environ 50 %, se maintenant sous la barre des 30 ms même en cas de charge plus importante.

Conclusion : best_compression pour la recherche

Pour les cas d'utilisation de recherche où le volume de données dépasse la mémoire physique disponible, best_compression est un levier puissant d'optimisation des performances.

La solution classique aux erreurs de cache consiste à scaler pour augmenter la RAM. Cependant, en réduisant l'empreinte de l'index, nous avons atteint le même objectif : maximiser le nombre de documents dans le cache de pages. Notre prochaine étape consistera à explorer l'index trié afin d'optimiser davantage l'espace de stockage et d'améliorer encore les performances de nos ressources existantes.

Les agents gagnent du terrain en raison de leur potentiel d'amélioration de l'efficacité et de l'expérience client. Mais dans la pratique, il est difficile de fournir aux agents le bon contexte, en particulier lorsqu'ils travaillent sur des données d'entreprise hétérogènes et non structurées. Les développeurs doivent gérer les outils, les prompts, l'état, la logique de raisonnement, les modèles, et surtout récupérer un contexte pertinent à partir des sources métier pour garantir des résultats et des actions précis. Elastic Agent Builder fournit ces composants essentiels pour développer des agents sécurisés, fiables et contextuels.

Fonctionnalités principales d'Agent Builder

Agent Builder est le résultat des investissements à long terme d'Elastic dans la pertinence de la recherche et la génération augmentée par récupération, et contribue à faire d'Elasticsearch la meilleure base de données vectorielle pour simplifier le développement d'agents d'IA contextuels et axés sur les données.

Agent Builder vous permet de :

• Commencer immédiatement avec un agent conversationnel intégré capable de répondre aux questions, d'effectuer des analyses et de mener des investigations sur n'importe quelles données dans Elasticsearch.
• Passer rapidement des données non structurées complexes à un agent personnalisé grâce à une expérience de développement basée sur la configuration.
• Bénéficier de la pertinence d'une recherche hybride de pointe grâce à ES|QL intégré ou à des outils personnalisés pour améliorer la qualité du contexte et la fiabilité des agents.
• Exécuter des workflows complexes (préversion) sous forme d'outils réutilisables pour enrichir les données, mettre à jour les enregistrements, envoyer des messages et plus encore pour l'automatisation basée sur des règles.
• Vous connecter à des sources de données externes à Elasticsearch à l'aide de workflows et de MCP pour corréler et combiner le contexte pour les agents.
• Intégrer à n'importe quel framework agentique ou d'application à l'aide d'outils intégrés et personnalisés exposés via MCP, et possibilité de se connecter à un MCP externe (préversion), prise en charge d'A2A et support technique API complet.
• Étendre les capacités d'Agent Builder avec l'intégration de solutions tierces comme LlamaIndex pour le traitement complexe de documents ou Arcade.dev pour un accès sécurisé et structuré aux outils.

Pour étendre les fonctionnalités d'Agent Builder, nous lançons Elastic Workflows, notre nouvelle solution d'automatisation basée sur des règles, actuellement disponible en préversion technique. Pour les tâches organisationnelles, les agents ont parfois besoin de la certitude et de la fiabilité des actions basées sur des règles, qui sont souvent nécessaires pour mettre en œuvre une logique métier spécifique. Elastic Workflows offre aux agents une méthode simple et déclarative pour orchestrer des systèmes internes et externes afin d'effectuer des actions, de collecter des données et du contexte, et de les transformer. Entièrement composables, pilotés par les événements et flexibles, les workflows peuvent être exposés comme outils à un agent via MCP.

Passez des données à l'agent en quelques minutes

Le développement d'agents peut prendre des semaines de travail préparatoire pour consolider des datastores distincts, construire des pipelines manuels, optimiser les requêtes et gérer une orchestration complexe. Agent Builder réduit le temps de développement des agents en supprimant le besoin de datastores séparés, de bases vectorielles, de pipelines RAG, de couches de recherche, de traducteurs de requêtes et d'orchestrateurs d'outils, vous permettant ainsi de vous concentrer sur la logique de l'agent et la livraison de l'application.

Agent Builder intègre nativement les primitives de la plateforme Elasticsearch pour accélérer le développement d'agents.

• Commencez avec un agent conversationnel intégré qui peut immédiatement discuter et raisonner avec vos données indexées.
• Intégrez des agents dans des applications, des tableaux de bord ou des systèmes CI/CD avec un accès interactif via Kibana, des API, ou MCP et A2A.
• Utilisez des outils par défaut pour comprendre la structure de vos données, sélectionner l'index approprié, générer des requêtes hybrides, sémantiques et structurées optimisées, et créer des visualisations configurables à l'aide d'ES|QL basées sur des prompts en langage naturel.

Pour aller plus loin, essayez une procédure pas à pas complète.

Développez sur Elasticsearch, une plateforme de données complète pour l'ingénierie du contexte

En matière d'agents d'IA, la qualité du contexte est essentielle pour un raisonnement efficace et pour limiter les risques d'hallucinations. Dans de nombreux cas, les données métier nécessaires à l'exécution d'une tâche constituent l'élément de contexte le plus crucial. Elasticsearch, base de données vectorielle hautement scalable et leader en matière de pertinence, offre déjà de nombreuses primitives performantes d'ingénierie du contexte. L'ingénierie du contexte va au-delà de la simple génération augmentée par récupération : elle permet de personnaliser et de dimensionner la manière dont les données sont extraites, classées, filtrées et présentées aux agents, contribuant ainsi à réduire le bruit et l'ambiguïté.

Elasticsearch fournit un moteur de contexte qui combine la recherche lexicale, la recherche vectorielle et le filtrage structuré pour la récupération, ce qui améliore considérablement les performances des LLM en garantissant que le modèle opère sur un contexte pertinent et précis. Cette fonctionnalité est prise en charge par la récupération agentique, ainsi que par des outils intégrés et une logique de recherche qui sélectionnent automatiquement les index appropriés et transforment le langage naturel en requêtes optimisées pour le contexte.

Avec Agent Builder, vous avez l'assurance que les agents reçoivent en priorité le contexte le plus pertinent grâce à des options de contrôle de la pertinence et du classement afin d'affiner la logique de notation, de classement et de filtrage. Elasticsearch vous permet de contrôler ce qui est important, pourquoi c'est important et comment l'ordre de priorité est établi, au lieu de vous fier à un comportement de récupération opaque. L'ensemble repose sur Elasticsearch, une plateforme de données scalable qui permet de stocker et de gérer toutes vos données (texte, vecteurs, métadonnées, logs, etc.) sur une seule et même plateforme, simplifiant ainsi la gestion du contexte pour les agents.

Exécutez des workflows complexes en tant qu'outils réutilisables

Si les agents d'IA permettent de raisonner sur des tâches complexes, l'automatisation repose en grande partie sur l'exécution fiable d'actions basées sur des règles qui appliquent une logique métier spécifique. Elastic Workflows offre une méthode simple et déclarative pour orchestrer les systèmes internes et externes afin d'effectuer des actions, collecter du contexte ou des données et les intégrer aux agents. Définis en YAML, les workflows sont entièrement composables de manière à les rendre aussi simples ou complexes que l'exige la tâche à accomplir. Les agents disposent ainsi d'un moyen efficace d'interagir avec la plateforme et les solutions Elasticsearch, de même qu'avec des applications tierces.

L'intégration d'un workflow avec Agent Builder peut se faire en trois étapes (prérequis : activez les workflows avec les détails fournis ici)

1. Créez et enregistrez un nouveau workflow à l'aide de l'éditeur simple basé sur YAML avec autocomplétion et tests intégrés.

2. Créez un nouvel outil dans Agent Builder avec le type "Workflow" et fournissez une description pour aider l'agent à déterminer quand utiliser l'outil de workflow.

3. Ajoutez l'outil de workflow à votre agent personnalisé.

4. Et voilà ! L'agent peut maintenant déclencher le workflow directement depuis une conversation.

Votre agent, vos règles

Agent Builder ne vous enferme pas dans un seul paradigme de développement. Au contraire, il est conçu pour permettre des approches de développement ouvertes et flexibles pour les agents avec un contrôle total des données, de la pertinence, des modèles, de l'interopérabilité, de la sécurité et de la conception des agents.

Les définitions d'agents personnalisés vous permettent de choisir précisément les outils auxquels un agent peut accéder, d'intégrer des prompts système personnalisés, d'adapter ses instructions et de définir des limites de sécurité. Les agents restent indépendants du modèle, ce qui vous permet de configurer avec flexibilité un LLM de votre choix, qu'il soit natif ou issu de l'écosystème étendu, sans être lié à un fournisseur unique.

Créez des outils extensibles qui encapsulent la logique spécifique au domaine (par exemple, des filtres d'index spécifiques, des jointures ES|QL, des pipelines analytiques) et sécurisez leur utilisation en production. La prise en charge API complète assure l'interopérabilité avec d'autres frameworks d'agents, grâce à une compatibilité native avec le protocole MCP (Model Context Protocol). L'intégration A2A vous permet d'exposer vos agents Elastic à d'autres frameworks, services et applications clientes, en réutilisant la même logique d'ingénierie des données et du contexte.

Agent Builder permet un développement flexible et ouvert, et il est conçu pour s'intégrer facilement aux frameworks et plateformes d'agents les plus populaires. Ces intégrations peuvent être essentielles pour fournir des agents efficaces. Comme l'explique Sam Partee, cofondateur d'Arcade.dev,

"Les systèmes agentiques échouent aujourd'hui, car la connexion de l'IA aux outils et aux données est complexe. Elastic Agent Builder avec Arcade.dev offre aux développeurs un moyen structuré et sécurisé de gérer la manière dont les agents récupèrent le contexte, raisonnent et agissent, permettant ainsi de passer de la démo à la phase de production."

Agent Builder tire également parti de l'extensibilité d'Elasticsearch pour gérer des données complexes. Comme le décrit Jerry Liu, PDG de LlamaIndex ,

"L'extraction du contexte d'entreprise à partir de sources de données non structurées est essentielle à la création d'agents performants. Elastic Agent Builder, associé au traitement de documents complexes de LlamaIndex, renforce la couche de contexte critique, aidant les équipes à récupérer, traiter et préparer les données afin que les agents puissent raisonner avec plus de précision et obtenir de meilleurs résultats."

Que pouvez-vous construire ?

Agent Builder est déjà exploité dans de nombreux cas d'utilisation. Vous trouverez ci-dessous quelques exemples et architectures de référence pour vous familiariser avec les agents :

• Automatiser l'infrastructure : dans les scénarios de support, les agents sont utilisés pour lire, analyser et dialoguer, mais jusqu'à présent, ils ne peuvent pas interagir directement avec l'infrastructure qu'ils sont appelés à gérer. L'équipe d'ingénierie d'Elastic a développé un agent pour la gestion automatisée de l'infrastructure dans le cadre d'un hackathon. L'agent enquête activement sur les problèmes liés à l'infrastructure des applications et prend des mesures automatisées. Il utilise des workflows pour optimiser les configurations, répondre aux problèmes et scaler les ressources, le tout basé sur une compréhension intelligente des logs d'infrastructure.
• Analyse des menaces de sécurité : un agent de vulnérabilité de sécurité a été développé avec Elastic Agent Builder, MCP et Elasticsearch. Il automatise l'analyse des menaces en corrélant les données de sécurité internes avec les renseignements sur les menaces externes. L'agent effectue une recherche sémantique sur les incidents et configurations historiques, enrichit les résultats avec des données Internet en temps réel et applique un raisonnement LLM pour évaluer la pertinence environnementale, hiérarchiser les risques et proposer des mesures correctives concrètes. Voir l'architecture de référence.
• Support technique client : les agents peuvent effectuer de nombreuses tâches de support, notamment la synthèse des cas, la déduplication et la création de tickets, ainsi que des investigations techniques approfondies. Agent Builder facilite ces opérations grâce à une recherche hybride en plusieurs étapes permettant de trouver uniquement les problèmes, solutions et procédures les plus pertinents, de formuler des hypothèses sur les causes profondes et de proposer des plans de remédiation. Agent Builder peut simplifier l'architecture des systèmes de support complexes et accélérer les délais de livraison.
• Découverte de produits et de contenus : Agent Builder simplifie le processus d'exposition de catalogues produits complexes pour des expériences conversationnelles, tout en permettant aux organisations de conserver la flexibilité nécessaire pour inclure leur propre logique métier et leurs propres exigences.
• Créez le vôtre : participez au hackathon Agent Builder, qui se déroulera du 22 janvier au 27 février 2026. Collaborez avec la communauté pour créer des agents d'IA contextuels à plusieurs étapes qui combinent la recherche, les workflows, les outils et le raisonnement pour automatiser des tâches concrètes*

Commencez à créer des agents personnalisés dès maintenant

Commencez avec un essai Elastic Cloud, et consultez la documentation ici. Pour les clients existants, Agent Builder est disponible dans Cloud Serverless et avec le niveau Enterprise dans Elastic Cloud Hosted et autogéré.

* Cliquez ici pour connaître les modalités, conditions et critères d'éligibilité pour le hackathon

L’un des moyens de briser la vitre : adopter des agents vocaux, autrement dit des agents IA capables de comprendre la voix humaine et de produire un son de synthèse. Grâce à l’essor des transcriptions à faible latence, des modèles de langage de grande taille (LLM) rapides et des systèmes de synthèse vocale au rendu naturel, cette vision devient réalité.

Pour réellement créer de la valeur, les agents vocaux doivent aussi avoir accès aux données métier. Dans ce billet, nous verrons comment fonctionnent les agents vocaux et comment en créer un pour ElasticSport, une boutique fictive d’équipements de sport de plein air, à l’aide de LiveKit et Elastic Agent Builder. Notre agent vocal sera sensible au contexte et s’appuiera sur nos données.

Fonctionnement

Le monde des agents vocaux repose sur deux grands paradigmes : le premier s’appuie sur des modèles de conversion vocale directe (speech-to-speech), le second sur une chaîne vocale composée de reconnaissance vocale, de LLM et de synthèse vocale. Les modèles speech-to-speech ont leurs avantages, mais les chaînes vocales permettent une personnalisation bien plus poussée des technologies employées et de la gestion du contexte, ainsi qu’un contrôle plus fin du comportement de l’agent. Nous allons nous concentrer sur le modèle basé sur la chaîne vocale.

Composants clés

Transcription (reconnaissance vocale)

La transcription est le point d’entrée de la chaîne vocale. Le composant de transcription reçoit des trames audio brutes en entrée, convertit la voix en texte, puis restitue ce texte en sortie. Le texte transcrit est mis en mémoire tampon jusqu’à ce que le système détecte la fin de la prise de parole de l’utilisateur – c’est alors que la génération par le LLM démarre. Plusieurs prestataires tiers proposent des transcriptions à faible latence. Lors de votre sélection, tenez compte de la latence et de la précision de transcription, et vérifiez que le fournisseur prend en charge les transcriptions en flux continu.

Exemples d’API tierces : AssemblyAI, Deepgram, OpenAI, ElevenLabs

Détection de prise de parole

La détection de prise de parole est le composant de la chaîne qui identifie la fin de l’intervention de l’utilisateur, déclenchant ainsi la génération. Une méthode courante consiste à utiliser un modèle de détection d’activité vocale (VAD), comme Silero VAD. Le VAD s’appuie sur le niveau d’énergie du signal audio pour détecter la présence de parole et identifier la fin de l’intervention. Cependant, un VAD seul ne peut pas distinguer une pause de la fin d’une prise de parole. C’est pourquoi on l’associe souvent à un modèle de fin d’énoncé, capable de prédire si l’utilisateur a terminé de parler, en se basant sur la transcription provisoire ou l’audio brut.

Exemples (Hugging Face) : livekit/turn-detector, pipecat-ai/smart-turn-v3

Agent

L’agent constitue le cœur de la chaîne vocale. Il est chargé de comprendre l’intention, de récupérer le bon contexte et de formuler une réponse sous forme de texte. Elastic Agent Builder, avec ses fonctions de raisonnement intégrées, sa bibliothèque d’outils et son intégration aux workflows, permet de créer un agent capable d’exploiter vos données et d’interagir avec des services externes.

LLM (texte à texte)

Pour choisir un LLM dans Elastic Agent Builder, deux critères principaux sont à prendre en compte : les benchmarks de raisonnement du LLM et le temps jusqu’au premier jeton (TTFT).

Les benchmarks de raisonnement mesurent la capacité du LLM à produire des réponses pertinentes. Les benchmarks à privilégier sont ceux qui évaluent la cohérence des conversations à plusieurs tours et les capacités cognitives, comme MT-Bench et le jeu de données Humanity’s Last Exam, respectivement.

Les benchmarks TTFT évaluent la rapidité avec laquelle le modèle génère son premier jeton en sortie. Il existe d’autres types de benchmarks de latence, mais le TTFT est particulièrement crucial pour les agents vocaux, car la synthèse vocale peut démarrer dès réception du premier jeton. Résultat : une latence réduite entre les prises de parole et une conversation plus naturelle.

Il faut souvent faire un compromis entre ces deux critères, car les modèles plus rapides obtiennent généralement de moins bons résultats aux tests de raisonnement.

Exemples (Hugging Face) : openai/gpt-oss-20b, openai/gpt-oss-120b

Synthèse (texte à la parole)

La dernière étape de la chaîne consiste à convertir le texte en parole grâce à un modèle de synthèse vocale. Ce composant est chargé de convertir le texte généré par le LLM en parole audible. Comme pour les LLM, la latence est un critère important lors du choix d’un fournisseur de synthèse vocale. La latence de la synthèse vocale se mesure au temps jusqu’au premier octet (TTFB). C’est le délai nécessaire pour recevoir le tout premier octet audio. Un TTFB plus court permet aussi de réduire la latence entre les prises de parole.

Exemples : ElevenLabs, Cartesia, Rime

Construction du pipeline vocal

Elastic Agent Builder peut s’intégrer dans une chaîne vocale à différents niveaux :

1. Outils Agent Builder uniquement : reconnaissance vocale → LLM (avec outils Agent Builder) → synthèse vocale
2. Agent Builder en tant que MCP : reconnaissance vocale → LLM (avec accès Agent Builder via MCP) → synthèse vocale
3. Agent Builder comme noyau central : reconnaissance vocale → Agent Builder → synthèse vocale

Pour ce projet, j’ai choisi d’utiliser Agent Builder comme solution centrale. Cette approche permet de tirer pleinement parti des fonctionnalités d’Agent Builder et des workflows. Le projet s’appuie sur LiveKit pour orchestrer la reconnaissance vocale, la détection de prise de parole et la synthèse vocale. Il implémente également un nœud LLM personnalisé, directement intégré à Agent Builder.

Agent vocal de support technique Elastic

Nous allons créer un agent vocal de support personnalisé pour une boutique de sport fictive, appelée ElasticSport. Les clients pourront appeler la ligne d’assistance, demander des recommandations de produits, consulter les fiches produit, vérifier le statut de leurs commandes, et recevoir les informations par message texte. Pour cela, nous devons commencer par configurer un agent personnalisé et créer des outils permettant d’exécuter des requêtes Elasticsearch Query Language (ES|QL) ainsi que des workflows.

Configuration de l'agent

Invite

L’invite détermine la personnalité que doit adopter l’agent et la façon dont il doit répondre. Il existe également quelques invites spécifiques à la voix, qui garantissent une synthèse vocale fluide et permettent de gérer élégamment les incompréhensions.

You are a Sales Assistant at ElasticSport, an outdoor sport shop specialized in hiking and winter equipment. 

[Profile]
- name: Iva
- company: ElasticSport
- role: Sales Assistant
- language: en-GB
- description: ElasticSport virtual sales assistant

[Context]
- Ask clarifying questions to understand the context.
- Use available tools to answer the user's question.
- Use the knowledge base to retrieve general information

[Style]
- Be informative and comprehensive.
- Maintain a professional, friendly and polite tone.
- Mimic human behavior and speech patterns.
- Be concise. Do not over explain initially

[Response Guideline]
- Present dates in spelled-out month date format (e.g., January fifteenth, two thousand and twenty-four).
- Avoid the use of unpronounceable punctuation such as bullet points, tables, emojis.
- Respond in plain text, avoid any formatting.
- Spell out numbers as words for more natural-sounding speech.
- Respond in short and concise sentences. Responses should be 1 or 2 sentences long.

[ERROR RECOVERY]
### Misunderstanding Protocol
1. Acknowledge potential misunderstanding
2. Request specific clarification

Workflows

Nous allons ajouter un petit workflow permettant d’envoyer un SMS via l’API de messagerie de Twilio. Ce workflow sera exposé à l’agent personnalisé sous forme d’outil, afin que l’agent puisse envoyer un SMS à l’appelant pendant l’appel. Cela permet à l’appelant, par exemple, de demander : « Pouvez-vous m’envoyer plus de détails sur X par SMS ? »

name: send sms
enabled: true
triggers:
  - type: manual
inputs:
  - name: message
    type: string
    description: The message to send to the phone number.

  - name: phone_number
    type: string
    description: The phone number to send the message to.

consts:
  TWILIO_ACCOUNT: "****"
  BASIC_AUTH: "****"
  FROM_PHONE_NNUMBER: "****"
steps:
  - name: http_step
    type: http
    with:
      url: https://api.twilio.com/2010-04-01/Accounts/{{consts.TWILIO_ACCOUNT}}/Messages.json
      method: POST
      headers:
        Content-Type: application/x-www-form-urlencoded
        Authorization: Basic {{consts.BASIC_AUTH | base64_encode}}
      body: From={{consts.FROM_PHONE_NNUMBER}}&To={{inputs.phone_number}}&Body={{inputs.message}}
      timeout: 30s

Outils ES|QL

Les outils suivants permettent à l’agent de fournir des réponses pertinentes, basées sur des données réelles. Le dépôt d’exemple contient un script d’initialisation de Kibana avec des jeux de données produits, commandes et base de connaissances.

• Product.search

Le jeu de données produit contient 65 produits fictifs. Voici un exemple de document :

{
      "sku": "ort3M7k",
      "name": "Ortovox Free Rider 26 Backpack",
      "price": 189,
      "currency": "USD",
      "image": "https://via.placeholder.com/150",
      "description": "The Ortovox Free Rider 26 is a technical freeride backpack with a dedicated safety compartment and diagonal ski carry system. Perfect for backcountry missions.\n\nKey Features:\n- 26L capacity\n- Diagonal ski carry system\n- Safety equipment compartment\n- Helmet holder\n- Hydration system compatible",
      "category": "Accessories",
      "subCategory": "Backpacks",
      "brand": "Ortovox",
      "sizes": ["One Size"],
      "colors": ["Black", "Blue", "Orange"],
      "materials": ["Nylon", "Polyester"]
    }

Les champs « name » et « description » sont mappés sur semantic_text, ce qui permet au LLM d’effectuer une recherche sémantique via ES|QL pour retrouver les produits pertinents. La requête de recherche hybride effectue une correspondance sémantique sur les deux champs, en appliquant une pondération légèrement supérieure au champ « name » grâce à un boost.

La requête récupère d’abord les 20 meilleurs résultats, classés selon leur score de pertinence initial. Ces résultats sont ensuite reclassés en fonction de leur champ « description » à l’aide du modèle d’inférence .rerank-v1-elasticsearch , puis réduits aux cinq produits les plus pertinents.

type: ES|QL
toolId: products.search
description: Use this tool to search through the product catalogue by keywords.
query: |
    FROM products
        METADATA _score
      | WHERE
          MATCH(name, ?query, {"boost": 0.6}) OR
            MATCH(description, ?query, {"boost": 0.4})
      | SORT _score DESC
      | LIMIT 20
      | RERANK ?query
            ON description
            WITH {"inference_id": ".rerank-v1-elasticsearch"}
      | LIMIT 5

parameters:
    query: space separated keywords to search for in catalogue

• Knowledgebase.search

Les jeux de données de la base de connaissances contiennent des documents structurés comme suit, avec les champs de titre et de contenu stockés sous forme de texte sémantique :

{
        id: "8273645",
        createdAt: "2025-11-14",
        title: "International Orders",
        content: `International orders are processed through our international shipping partner. Below are the countries we ship to and average delivery times.
        Germany: 3-5 working days
        France: 3-5 working days
        Italy: 3-5 working days
        Spain: 3-5 working days
        United Kingdom: 3-5 working days
        United States: 3-5 working days
        Canada: 3-5 working days
        Australia: 3-5 working days
        New Zealand: 3-5 working days
        `
}

L’outil utilise une requête similaire à celle de product.search :

type: "ES|QL"
toolId: knowledgebase.search
description: Use this tool to search the knowledgebase.
query: |
  FROM knowledge_base
    METADATA _score
  | WHERE
      MATCH(title, ?query, {"boost": 0.6}) OR
      MATCH(content, ?query, {"boost": 0.4})
  | SORT _score DESC
  | LIMIT 20
  | RERANK ?query
      ON content
      WITH {"inference_id": ".rerank-v1-elasticsearch"}
  | LIMIT 5

parameters:
  query: space separated keywords or natural language phrase to semantically search for in the knowledge base

• Orders.search

Le dernier outil que nous allons ajouter permet de récupérer les commandes à partir de order_id :

type: "ES|QL"
toolId: order.search
description: Use this tool to retrieve an order by its ID.
query: |
  FROM orders
    METADATA _score
  | WHERE order_id == ?order_id
  | SORT _score DESC
  | LIMIT 1

parameters:
  order_id: "the ID of the order"

Une fois l’agent configuré et les workflows ainsi que les outils ES|QL associés, vous pouvez tester l’agent dans Kibana.

Au-delà de l’agent de support ElasticSport, l’agent, les workflows et les outils peuvent être adaptés à d’autres cas d’usage, comme un agent commercial pour qualifier des prospects, un agent de dépannage à domicile, un système de réservation pour restaurant ou encore un agent de planification de rendez-vous.

La dernière étape consiste à connecter l’agent que nous venons de créer à LiveKit, à la synthèse vocale et à la reconnaissance vocale. Le dépôt mentionné à la fin de ce billet contient un nœud LLM personnalisé pour Elastic Agent Builder, compatible avec LiveKit. Il vous suffit de remplacer AGENT_ID par le vôtre et de le connecter à votre instance Kibana.

Premiers pas

Consultez le code et testez-le vous-même ici.

Nous avons tous été témoins de l’essor des agents d’IA. Ils se révèlent particulièrement performants pour le résumé de textes, l’écriture de scripts et l’extraction de réponses issues de bases documentaires. Pourtant, dans les domaines du DevOps et de la fiabilité système (SRE), nous faisions face à un obstacle particulièrement frustrant. L’immense majorité des agents reste confinée au modèle du support client ; s’ils analysent et échangent, ils demeurent incapables d’intervenir directement sur les couches d’infrastructure dont ils ont la charge.

Lors de notre récent hackathon, nous avons pris le parti de briser définitivement cette contrainte.

Nous avons conçu l’Infrastructure augmentée : un copilote d’infrastructure qui ne se contente pas de vous conseiller, mais qui crée, déploie, surveille et répare également votre environnement de production.

Le problème : copier, reformater, coller

Les agents standards fonctionnent en vase clos. Face à une panne majeure représentant une perte de 5 millions de dollars, l’assistance d’un agent standard se limite à la simple lecture du protocole de remise en service. Mais c’est toujours à vous d’effectuer le travail. Il vous reste encore à extraire le code, à en assurer la compatibilité avec votre environnement, puis à procéder manuellement à sa saisie dans la console.

Nous recherchions un agent capable de faire la part des choses entre le discours sur Kubernetes et l’exécution technique sur Kubernetes.

Au cœur du système : présentation d’Elastic Agent Builder.

Pour concevoir cette solution, nous ne sommes pas partis d’une page blanche. Nous l’avons conçue sur la base d’Elastic Agent Builder. À titre de rappel, Elastic Agent Builder est une architecture logicielle dédiée au développement rapide d’agents, agissant comme interface entre un modèle de langage (LLM), tel que Google Gemini, et les données propriétaires hébergées dans Elasticsearch.

Agent Builder peut être utilisé pour l’IA conversationnelle en l’ancrant sur des données internes, comme des documents ou des logs. Mais sa fonctionnalité la plus puissante est la possibilité d’assigner des outils. Ces outils permettent au LLM de sortir de l’interface de discussion pour accomplir des tâches spécifiques. Nous avons compris qu’en exploitant tout le potentiel de cette fonction, l’Agent Builder pourrait devenir un véritable pilier de l’automatisation.

Le faire fonctionner : création de la première version

Dès le début du projet, notre ambition était de permettre aux agents d’exercer une action concrète sur leur environnement externe. Une idée a germé : pourquoi ne pas créer un « runner », un logiciel chargé d’exécuter sur la machine hôte toutes les instructions générées par l’agent ? Puis, nous avons envisagé ceci : et si les « runners », Elastic Agent Builder et l’utilisateur communiquaient en temps réel, comme lors d’une conférence téléphonique ?

Nous avons commencé par concevoir un projet Python, Augmented Infrastructure Runners, qui consistait essentiellement en une boucle while(true) interrogeant chaque seconde l’API des conversations d’Elastic Agent Builder pour y détecter une syntaxe spécifique que nous avions créée :

{
	"tool_name": "my_tool",
       "tool_arguments": "\{stringified json arguments\}"
}

Nous avons ensuite mis à jour l'invite pour l'enseigner sur notre nouvelle syntaxe d'appel d'outil. Bill contribue à la maintenance de FastMCP, la solution de référence en Python pour le développement de serveurs conformes au Model Context Protocol (MCP). Il a entrepris d’utiliser le client FastMCP conjointement avec ce nouveau runner afin de coupler les serveurs MCP et d’exposer leurs outils au sein de l’environnement d’exécution. Lorsque l’agent voyait cela, il exécutait l’appel de l’outil et POST les résultats dans la conversation, comme si l’utilisateur lui-même les avait envoyés. Cela incitait le LLM à répondre au résultat, et c’est ainsi que tout a commencé !

C'était génial mais cela posait deux problèmes principaux :

1. L’agent se contenterait de projeter l’intégralité des données JSON au beau milieu de l’échange avec l’utilisateur.
2. Dans l’API des conversations, les messages n’étaient accessibles qu’une fois le tour de parole terminé, soit après l’émission de la réponse par le LLM.

Nous nous sommes alors attachés à trouver comment déporter cette tâche en tâche de fond.

Nous avons ensuite donné à l'agent un outil appelé call_external_tool avec deux arguments : le tool_name et les arguments JSON sous forme de chaîne. Bien que cet appel d’outil externe ne produise aucun retour, il resterait néanmoins détectable au sein de la requête GET envoyée à l’API des conversations. L’étape suivante a consisté à donner aux runners la permission d’alimenter Elasticsearch en documents, que l’agent d’Elastic Agent Builder pouvait alors consulter à la demande. L'agent fonctionne toujours en réponse à un message d'utilisateur, nous devons donc démarrer l'agent avec un message d'utilisateur afin qu'il recherche des résultats et poursuive le traitement. Nous avons donc demandé aux agents d’insérer un petit message dans le chat pour reprendre la conversation :

Ainsi, nous avions désormais des appels d'outils externes. Cependant, en raison du deuxième problème mentionné ci-dessus, nous avons dû supprimer cette dernière partie de démarrage. Sinon, chaque appel à un outil externe nécessitait un cycle complet de conversation pour récupérer les résultats !

Pour aller plus loin : présentation des workflows

En plus des appels d’outils via ES|QL et la recherche d’index, les agents d’Agent Builder peuvent solliciter des outils Elastic basés sur des workflows. Les workflows Elastic offrent une méthode flexible et simple à gérer pour exécuter une séquence arbitraire d’actions et de logiques. Dans notre cas, le rôle du workflow se limite à l’enregistrement d’une demande d’outil externe dans Elasticsearch et à la transmission d’un identifiant (ID) pour le suivi des résultats. Le résultat est une définition de workflow simple, articulée comme suit :

name: ai-tool-call
enabled: true
triggers:
  - type: manual
inputs:
  - name: runner_id
    type: string
  - name: tool_calls
    type: string

steps:
  - name: store_request
    type: elasticsearch.create
    with:
      index: distributed-tool-requests
      id: "{{inputs.runner_id}}_{{ execution.id }}"
      document:
        request_id: "{{ execution.id }}"
        runner_id: "{{inputs.runner_id}}"
        tool_call: "{{inputs.tool_calls}}"
        status: "unhandled"

  - name: output_result
    type: console
    with:
      message: "Called tool, with execution id: {{ execution.id }}. Use this ID to poll the results."

Ainsi, au lieu de compter sur l’écriture de la requête d’appel d’outil dans la conversation, les runners peuvent simplement interroger l’index distributed-tool-requests d’Elasticsearch pour de nouvelles requêtes d’outils externes et faire un rapport des résultats dans un autre index Elasticsearch avec le execution.id fourni.

Cela élimine les deux principaux problèmes mentionnés ci-dessus :

1. L’historique de la conversation n’est plus encombré par les données de transfert des appels d’outils externes.
2. Comme les runners interrogent l’index Elasticsearch au lieu de l’historique de conversation, ils ne sont plus bloqués par l’achèvement du cycle d’échange pour que les requêtes d’outils externes deviennent visibles.

L’intérêt principal de ce deuxième point est que l’exécution des requêtes vers les outils externes débute pendant que l’agent « réfléchit », sans attendre que le tour de parole soit terminé. Cela nous permet d’instruire le LLM, via le prompt système, d’interroger les résultats de l’outil externe jusqu’à ce qu’ils soient disponibles, éliminant ainsi le besoin d’un message de relance. Dans l’ensemble, cette approche fluidifie l’interaction : le LLM est désormais capable de gérer simultanément plusieurs appels d’outils externes lors d’une seule itération. Cela lui permet de traiter des requêtes utilisateur complexes de manière groupée, plutôt que de fragmenter le processus.

Mise en commun

Pour combler le fossé entre le LLM et la baie de serveurs, nous avons développé une architecture spécifique en exploitant les fonctionnalités des outils d'Agent Builder :

1. Les runners de l'infrastructure augmentée : Nous avons déployé des runners légers à l'intérieur des environnements cibles (serveurs, clusters Kubernetes, comptes cloud). Ces exécuteurs sont connectés directement à Elastic, en utilisant des endpoints sécurisés et des secrets accessibles uniquement à chacun des runners.
2. Recherche ES|QL : Le copilote utilise ES|QL d'Elastic pour effectuer des recherches hybrides. Il ne se contente pas de rechercher des connaissances ; il recherche des capacités. Il interroge les exécuteurs connectés pour voir quels outils sont disponibles (par exemple, list_ec2_instances, install_helm_chart).
3. Exécution du workflow : Une fois que l'agent a décidé d'un plan d'action, il crée un workflow structuré.
4. Boucle de rétroaction : Les runners exécutent la commande localement et rapportent les résultats dans Elasticsearch. Le copilote lit le résultat de l’index et décide de l’étape suivante.

Démonstration : transformer un incident critique en levier d’observabilité

Dans la vidéo, nous avons présenté deux scénarios distincts démontrant la puissance de cette architecture.

Scénario 1 : DevOps à la rescousse

Le point de départ est un incident critique : un utilisateur confronté à une perte de 5 millions de dollars due à un défaut de visibilité dans son cluster Kubernetes.

• La demande : « Comment m'assurer que cela ne se reproduise plus ? »
• Action : L’agent ne s’est pas contenté de fournir un tutoriel. Il a identifié le cluster, créé les espaces de nom nécessaires, généré des secrets Kubernetes, installé l’opérateur OpenTelemetry et a immédiatement fourni un lien vers un tableau de bord APM en direct.
• Le résultat : Une observabilité complète de Kubernetes et des informations sur les applications sans que l'utilisateur n'écrive une seule ligne de YAML.

Scénario 2 : Transfert de Security

En sécurité des infrastructures, un principe de base prévaut : l’impossibilité de protéger ce qui échappe à notre visibilité. En pleine intervention de secours DevOps, l’agent identifie une occasion d’optimiser la sécurité globale de l’infrastructure.

En s’appuyant sur une alerte générée lors d’une analyse Elastic Observability, nous illustrons la capacité d’un analyste sécurité à interagir en langage naturel avec son infrastructure. L’objectif est double : recenser précisément les ressources cloud existantes et mettre en œuvre les solutions de protection indispensables.

• Découverte : Le copilote a énuméré les ressources AWS pour le spécialiste de la sécurité et a identifié une lacune critique : une instance Amazon Elastic Compute Cloud (EC2) et un cluster Amazon Elastic Kubernetes Service (EKS) avec des points de terminaison publics dépourvus de protection des points de terminaison.
• Remédiation : Avec une simple approbation, le copilote a déployé Elastic Security détection et réponse étendues (XDR) et détection et réponse cloud (CDR) sur les ressources vulnérables, assurant la sécurité de l'environnement en temps réel.
• Le résultat : Protection des ressources AWS déployées avec une sécurité totale à l’exécution.

Perspectives : vers une infrastructure intégralement augmentée

Ce projet démontre la capacité d’Elastic Agent Builder à agir comme le centre de pilotage de vos opérations distribuées. Notre champ d’action dépasse désormais le cadre strict de l’infrastructure. Les capacités de notre technologie de runner s’étendent à :

• Synthetics augmenté : Diagnostiquer les erreurs TLS chez les runners du monde entier.
• Développement augmenté : Création de requêtes d'extraction et implémentation de CAPTCHA sur les services frontend.
• Opérations augmentées : reconfiguration automatique des résolveurs DNS en cas de panne.

Essayez par vous-même

Nous pensons que l'avenir de l'IA ne se limite pas à l'assistance par chat, mais aussi à une infrastructure augmentée. Il s'agit d'avoir un partenaire qui peut déployer, réparer, observer et protéger à vos côtés.

Consultez le code et essayez-le par vous-même avec les runners distribués (GitHub) et Elastic Agent Builder sur Elastic Cloud Serverless dès aujourd'hui !

• Créez un projet sans serveur sur Elastic Cloud.
• Déployer le code vers un runner.
• Configurer le runner.
• Configurer votre fichier mcp.json.
• Démarrer l'agent, qui créera automatiquement votre agent et ses outils.
• Dialoguez avec un agent capable de raisonner, de planifier et d’exécuter des actions sur vos runners distribués !

L’équipe : Alex, Bill, Gil, Graham et Norrie

Pourquoi c'est important

La plupart des workflows analytiques classiques se résument finalement à regrouper des données. Qu'il s'agisse de calculer la consommation moyenne de données par hôte, de compter les événements par utilisateur ou d'agréger des indicateurs selon différentes dimensions, l'opération de base reste la même : associer des clés à des groupes et mettre à jour les agrégats en cours.

À petite échelle, presque n'importe quelle table de hachage convenable fonctionne bien. À grande échelle (des centaines de millions de documents et des millions de groupes distincts), les détails commencent à avoir leur importance. Les facteurs de charge, la stratégie de sondage, l'organisation de la mémoire et le comportement du cache peuvent faire la différence entre des performances linéaires et une avalanche d'erreurs de cache.

Elasticsearch prend en charge ces charges de travail depuis des années, mais nous cherchons constamment à moderniser ses algorithmes de base. C'est pourquoi nous avons évalué une nouvelle approche inspirée des tables suisses et l'avons appliquée au calcul des statistiques par ES|QL.

Que sont exactement les tables suisses ?

Les tables suisses sont une famille de tables de hachage modernes popularisées par SwissTable de Google, puis adoptées par Abseil et d'autres bibliothèques.

Les tables de hachage traditionnelles passent beaucoup de temps à rechercher des pointeurs ou à charger des clés pour finalement constater qu'elles ne correspondent pas. La caractéristique principale des tables suisses est leur capacité à rejeter la plupart des requêtes grâce à une structure de tableau en cache de petite taille, stockée séparément des clés et des valeurs et appelée octets de contrôle, ce qui réduit considérablement le trafic mémoire.

Chaque octet de contrôle représente un emplacement unique et, dans notre cas, encode deux éléments : si l'emplacement est vide et une courte empreinte numérique dérivée du hachage. Ces octets de contrôle sont disposés de manière contiguë en mémoire, généralement par groupes de 16, idéal pour le traitement SIMD (Single Instruction, Multiple Data).

Au lieu de sonder un emplacement à la fois, les tables suisses parcourent un bloc entier d'octets de contrôle à l'aide d'instructions vectorielles. En une seule opération, le processeur compare l'empreinte de la clé entrante à 16 emplacements et élimine les entrées vides. Seuls les candidats retenus après ce parcours rapide nécessitent le chargement et la comparaison des clés réelles.

Cette conception privilégie une meilleure localité du cache et réduit considérablement les chargements aléatoires, au détriment d'une petite quantité de métadonnées supplémentaires. À mesure que la table s'agrandit et que les chaînes de détection s'allongent, ces avantages deviennent de plus en plus précieux.

SIMD au centre

La vraie star de la série est l'architecture SIMD.

Les octets de contrôle sont non seulement compacts, mais aussi conçus spécifiquement pour être traités par des instructions vectorielles. Une seule comparaison SIMD peut vérifier simultanément 16 empreintes, transformant ainsi une boucle classique en quelques opérations étendues. Exemple :

En pratique, cela signifie :

• Moins de branches.
• Des chaînes de détection plus courtes.
• Moins de chargements depuis la mémoire des clés et des valeurs.
• Une bien meilleure utilisation des unités d'exécution du processeur.

La plupart des recherches ne dépassent jamais l'étape de l'analyse de l'octet de contrôle. Lorsqu'elles y parviennent, le travail restant est ciblé et prévisible. C'est précisément le type de charge de travail pour lequel les processeurs modernes excellent.

SIMD sous le capot

Pour les lecteurs qui aiment jeter un œil sous le capot, voici ce qui se passe lors de l'insertion d'une nouvelle clé dans la table. Nous utilisons l'API Panama Vector avec des vecteurs de 128 bits, opérant ainsi sur 16 octets de contrôle en parallèle.

L'extrait suivant montre le code généré sur un processeur Intel Rocket Lake avec AVX-512. Bien que les instructions reflètent cet environnement, la conception ne dépend pas d'AVX-512. Les mêmes opérations vectorielles de haut niveau sont émises sur d'autres plateformes en utilisant des instructions équivalentes (par exemple, AVX2, SSE ou NEON).

; Load 16 control bytes from the control block
vmovdqu xmm0, XMMWORD PTR [r9+r10*1+0x10]

; Broadcast the 7-bit fingerprint of the new key across the vector
vpbroadcastb xmm1, r11d

; Compare all 16 control bytes to the new fingerprint
vpcmpeqb k7, xmm0, xmm1
kmovq rbx, k7

; Check if any matches were found
test rbx, rbx
jne 

Chaque instruction a un rôle clair dans le processus d'insertion :

• vmovdqu: Charge 16 octets de contrôle consécutifs dans le registre xmm0 de 128 bits.
• vpbroadcastb: Réplique l'empreinte 7 bits de la nouvelle clé sur toutes les voies du registre xmm1.
• vpcmpeqb: Compare chaque octet de contrôle à l'empreinte diffusée, produisant un masque de correspondances potentielles.
• kmovq + test : Déplace le masque vers un registre à usage général et vérifie rapidement si une correspondance existe.

Enfin, nous avons opté pour le sondage de groupes de 16 octets de contrôle à la fois, car les tests comparatifs ont montré que l'extension à 32 ou 64 octets avec des registres plus larges n'apportait aucun avantage mesurable en termes de performances.

Intégration dans ES|QL

L'adoption du hachage suisse dans Elasticsearch n'a pas été une simple solution de remplacement. ES|QL impose des exigences strictes de gestion de la mémoire, de sécurité et d'intégration au reste du moteur de calcul.

Nous avons étroitement intégré la nouvelle table de hachage à la gestion de la mémoire d'Elasticsearch, notamment au recycleur de pages et à la comptabilisation des coupures, afin de garantir la visibilité et la limitation des allocations. Les agrégations d'Elasticsearch sont stockées de manière dense et indexées par un identifiant de groupe, ce qui optimise la structure de la mémoire et la rapidité d'itération, tout en autorisant certaines optimisations de performance grâce à l'accès aléatoire.

Pour les clés binaires de longueur variable, nous mettons en cache le hachage complet ainsi que l'identifiant du groupe. Cela évite le recalcul coûteux des codes de hachage lors du sondage et améliore la localité du cache en regroupant les métadonnées associées. Lors du rehachage, nous pouvons nous appuyer sur le hachage et les octets de contrôle mis en cache sans avoir à examiner les valeurs elles-mêmes, ce qui réduit les coûts de redimensionnement.

Une simplification importante de notre implémentation est que les entrées ne sont jamais supprimées. Cela élimine le besoin de marqueurs (pour identifier les emplacements précédemment occupés) et permet aux emplacements vides de rester véritablement vides, ce qui améliore encore le comportement de sondage et maintient l'efficacité des analyses d'octets de contrôle.

Le résultat est une conception qui s'intègre naturellement dans le modèle d'exécution d'Elasticsearch tout en préservant les caractéristiques de performance qui rendent les tables suisses attrayantes.

Quelles sont ses performances ?

Pour les petites cardinalités, les tables suisses offrent des performances globalement équivalentes à celles de l'implémentation existante. Ce résultat est normal : lorsque les tables sont petites, les effets de cache sont moins importants et il y a peu de détections à optimiser.

À mesure que la cardinalité augmente, la situation change rapidement.

La carte thermique ci-dessus montre les facteurs d'amélioration du temps de traitement pour différentes tailles de clés (8, 32, 64 et 128 octets) pour des cardinalités allant de 1 000 à 10 000 000 de groupes. À mesure que la cardinalité augmente, le facteur d'amélioration s'accroît régulièrement, jusqu'à 2 à 3 fois pour les distributions uniformes.

Cette tendance correspond exactement aux prévisions de conception. Une cardinalité plus élevée entraîne des chaînes de détection plus longues dans les tables de hachage traditionnelles, tandis que le mode de sondage de type suisse continue de résoudre la plupart des recherches dans des blocs d'octets de contrôle compatibles SIMD.

Le comportement du cache raconte l'histoire

Pour mieux comprendre les gains de vitesse, nous avons exécuté le même JMH benchmarks sous Linux perf et capturé les statistiques du cache et du TLB.

Comparée à l'implémentation originale, la version suisse effectue environ 60 % d'accès au cache en moins. Les chargements du cache de dernier niveau sont 4 fois moins nombreux, et les défauts de chargement du cache LLC 6 fois moins. Étant donné que ces défauts se traduisent souvent directement par des accès à la mémoire principale, cette réduction explique à elle seule une grande partie de l'amélioration globale des performances.

Plus on se rapproche du processeur, moins on observe d'échecs de cache de données L1 et près de 6 fois moins d'échecs de TLB de données, ce qui indique une localité spatiale plus étroite et des schémas d'accès à la mémoire plus prévisibles.

C'est l'avantage concret des octets de contrôle compatibles SIMD. Au lieu de charger sans cesse des clés et des valeurs depuis des emplacements mémoire dispersés, la plupart des requêtes sont résolues par l'analyse d'une structure compacte résidant dans le cache. Moins de mémoire utilisée signifie moins d'échecs de lecture, et moins d'échecs de lecture signifient des requêtes plus rapides.

Conclusion

En adoptant une conception de table de hachage de style suisse et en misant fortement sur le sondage compatible SIMD, nous avons obtenu des gains de vitesse de 2 à 3 fois pour les charges de travail statistiques ES|QL à cardinalité élevée, ainsi que des performances plus stables et prévisibles.

Ce travail met en lumière comment les structures de données modernes optimisées pour le processeur peuvent générer des gains substantiels, même pour des problèmes complexes comme les tables de hachage. Il reste encore beaucoup à explorer, notamment en matière de spécialisation des types primitifs et d'utilisation dans d'autres opérations à forte cardinalité, telles que les jointures. Ces pistes s'inscrivent dans le cadre d'un effort plus vaste et continu de modernisation du fonctionnement interne d'Elasticsearch.

Si vous êtes intéressé par les détails ou souhaitez suivre le travail, consultez cette pull request et la meta issue qui suit les progrès sur Github.

Bon hachage !

Après tout, tout ce qui figure dans le contexte influence les réponses de l’IA. Le principe de l'entrée et de la sortie des déchets est vrai.

Dans cet article, nous allons présenter ce que signifie la mémoire à court et à long terme pour les agents IA, en particulier :

• La différence entre la mémoire à court terme et la mémoire à long terme.
• Comment elles se rapportent aux techniques de génération augmentée de récupération (RAG) avec des bases vectorielles, comme Elasticsearch, et pourquoi une gestion attentive de la mémoire est nécessaire.
• Les risques liés à la négligence de la mémoire, y compris le débordement de contexte et l'empoisonnement contextuel.
• Les bonnes pratiques, telles que l'élagage du contexte, la synthèse et la récupération uniquement des informations pertinentes, permettent de maintenir la mémoire de l'agent à la fois utile et sécurisée.
• Enfin, nous examinerons comment la mémoire peut être partagée et propagée dans les systèmes multi-agents pour permettre une collaboration sans confusion grâce à Elasticsearch.

Mémoire à court terme versus mémoire à long terme dans les agents d’IA

La mémoire à court terme dans un agent IA fait généralement référence au contexte ou à l’état immédiat de la conversation — essentiellement, l’historique de discussion actuel ou les messages récents dans la session active. Cela inclut la dernière requête de l’utilisateur et les échanges récents d’allers-retours. C’est très similaire aux informations qu’une personne garde en tête lors d’une conversation en cours.

Les frameworks d'IA maintiennent souvent cette mémoire transitoire dans l'état de l'agent (par exemple, en utilisant un pointeur de contrôle pour stocker l'état de la conversation, comme le montre cet exemple de LangGraph). La mémoire à court terme est limitée à une session, c'est-à-dire qu'elle existe dans le cadre d'une conversation ou d'une tâche unique et qu'elle est réinitialisée ou effacée à la fin de cette session, à moins qu'elle ne soit explicitement sauvegardée ailleurs. Un exemple de mémoire à court terme liée à une session serait le chat temporaire disponible dans ChatGPT.

La mémoire à long terme, en revanche, désigne les informations qui persistent au fil des conversations ou des sessions. Il s'agit des connaissances qu'un agent conserve au fil du temps, des faits qu'il a appris précédemment, des préférences de l'utilisateur ou de toute autre donnée que nous lui avons demandé de garder en mémoire de manière permanente.

La mémoire à long terme est généralement mise en œuvre en stockant et en récupérant les données à partir d'une source externe, telle qu'un fichier ou une base vectorielle située en dehors de la fenêtre contextuelle immédiate. Contrairement à l'historique de discussion à court terme, la mémoire à long terme n’est pas automatiquement incluse dans chaque requête. Au lieu de cela, sur la base d'un scénario donné, l'agent doit le rappeler ou le retrouver lorsque les outils pertinents sont invoqués. En pratique, la mémoire à long terme peut inclure les informations de profil de l’utilisateur, des réponses ou analyses antérieures produites par l’agent, ou une base de connaissances que l’agent peut consulter.

Par exemple, si vous avez un agent planificateur de voyage, la mémoire à court terme contiendrait les détails de la demande de voyage actuelle (dates, destination, budget) et toutes les questions de suivi dans cette conversation ; tandis que la mémoire à long terme pourrait stocker les préférences générales de voyage de l'utilisateur, les itinéraires passés et d'autres faits partagés lors de sessions précédentes. Lorsque l'utilisateur revient plus tard, l'agent peut puiser dans cette base de données à long terme (par exemple, l'utilisateur aime les plages et les montagnes, dispose d'un budget moyen de 100 000 INR, a une liste de lieux à visiter et préfère découvrir l'histoire et la culture plutôt que les attractions pour enfants) afin de ne pas traiter l'utilisateur comme une page blanche à chaque fois.

La mémoire à court terme (historique des conversations) fournit un contexte immédiat et une continuité, tandis que la mémoire à long terme fournit un contexte plus large dans lequel l'agent peut puiser en cas de besoin. Les cadres d'agents d'IA les plus avancés permettent les deux : ils gardent la trace des dialogues récents pour maintenir le contexte et proposent des mécanismes pour rechercher ou stocker des informations dans un référentiel à plus long terme. La gestion de la mémoire à court terme garantit qu'elle reste dans la fenêtre de contexte, tandis que la gestion de la mémoire à long terme aide l'agent à ancrer les réponses sur la base d'interactions et de personas antérieures.

Mémoire et RAG en ingénierie contextuelle

Comment pouvons-nous donner à un agent IA une mémoire à long terme utile en pratique ?

La mémoire sémantique, souvent mise en œuvre par le biais de la retrieval-augmented generation (RAG), constitue l'une des principales approches pour la mémoire à long terme. Cela consiste à couler le LLM avec un stockage de connaissances externe ou un datastore vectoriel, comme Elasticsearch. Lorsque le LLM a besoin d'informations au-delà de ce qui est contenu dans l'invite ou dans son entraînement intégré, il effectue une récupération sémantique contre Elasticsearch et injecte les résultats les plus pertinents dans l'invite en tant que contexte. Ainsi, le contexte effectif du modèle inclut non seulement la conversation récente (mémoire à court terme), mais aussi des faits pertinents à long terme récupérés à la volée. Le LLM fonde ensuite sa réponse sur son propre raisonnement et les informations récupérées, combinant efficacement la mémoire à court terme et la mémoire à long terme pour produire une réponse plus précise et contextuelle.

Elasticsearch peut être utilisé pour mettre en place une mémoire à long terme pour les agents d’IA. Voici un exemple de haut niveau montrant comment le contexte peut être récupéré depuis Elasticsearch pour la mémoire à long terme.

De cette façon, l’agent « se souvient » en recherchant des données pertinentes plutôt que de tout stocker dans son invite limitée, ce qui entraîne différents risques.

L'utilisation de RAG avec Elasticsearch ou tout stockage de vecteurs offre de multiples avantages :

Premièrement, il étend la connaissance du modèle au-delà de son seuil d'apprentissage. L’agent peut récupérer des informations à jour ou des données spécifiques au domaine que le LLM pourrait ne pas connaître. Ceci est crucial pour les questions concernant des événements récents ou des sujets spécialisés.

Deuxièmement, récupérer le contexte à la demande aide à réduire les hallucinations, surtout que les LLM ne sont pas entraînés sur des données propriétaires ou très spécialisées par rapport à votre cas d'utilisation spécifique, ce qui est très susceptible de les exposer à des hallucinations. Au lieu que le LLM devine ou invente de nouvelles informations comme il a été incité par évaluation, comme l’a souligné un article récent d’OpenAI (Why Language Models Hallucinate), le modèle peut être fondé sur des références factuelles provenant d’Elasticsearch. Bien entendu, le LLM dépend de la fiabilité des données du référentiel vectoriel pour prévenir véritablement la désinformation, et les données pertinentes sont extraites conformément aux mesures de pertinence fondamentales.

Troisièmement, RAG permet à un agent de travailler avec des bases de connaissances bien plus vastes que tout ce que vous pourriez inclure dans une invite. Au lieu d'insérer des documents entiers, comme de longs documents de recherche ou des documents politiques, dans la fenêtre contextuelle et de risquer une surcharge ou un empoisonnement du contexte du raisonnement du modèle par une information non pertinente, RAG s'appuie sur le découpage. Les documents volumineux sont divisés en morceaux plus petits et sémantiquement significatifs, et le système ne récupère que les quelques segments les plus pertinents pour la requête. Ainsi, le modèle n'a pas besoin d'un contexte d'un million de mots pour paraître bien informé ; il lui suffit d'avoir accès aux bons morceaux d'un corpus beaucoup plus vaste.

Il est important de noter qu’à mesure que les fenêtres contextuelles des LLM se sont agrandies (certains modèles supportent désormais des centaines de milliers, voire des millions de jetons), un débat a surgi sur la question de savoir si RAG est « mort ». Pourquoi ne pas intégrer toutes les données dans l'invite ? Si vous êtes du même avis, reportez-vous à cet excellent article de mes collègues Jeffrey Rengifo et Eduard Martin, Longer context ≠ better : Why RAG still matters. Cela évite le problème du « déchets en entrée, déchets en sortie » : le LLM reste concentré sur les quelques morceaux qui comptent, plutôt que de parcourir du bruit.

Cela dit, l'intégration d'Elasticsearch ou de n'importe quelle mémoire vectorielle dans une architecture d'agent d'IA offre une mémoire à long terme. L'agent stocke les connaissances à l'extérieur et les intègre au contexte de la mémoire en cas de besoin. Cela pourrait être implémenté sous forme d’architecture, où après chaque requête utilisateur, l’agent effectue une recherche sur Elasticsearch pour des informations pertinentes puis ajoute les premiers résultats à l’invite avant d’appeler le LLM. La réponse peut également être enregistrée dans le stockage à long terme si elle contient de nouvelles informations utiles (création d'une boucle d'apprentissage). En utilisant cette mémoire basée sur la récupération, l’agent reste informé et à jour, sans avoir à tout condenser dans chaque invite, même si la fenêtre de contexte prend en charge un million de tokens. Cette technique est une pierre angulaire de l'ingénierie contextuelle, combinant les forces de la récupération d'informations et de l'IA générative.

Voici un exemple d'état de conversation géré en mémoire utilisant le système de points de contrôle de LangGraph pour la mémoire à court terme pendant la session. (Reportez-vous à notre application d'ingénierie contextuelle.)

# Initialize chat memory (Note: This is in-memory only, not persistent)
memory = MemorySaver()

# Create a LangGraph agent
langgraph_agent = create_react_agent(model=llm, tools=tools, checkpointer=memory)

...
...
# Only process and display checkpoints if verbose mode is enabled
if args.verbose:
    # List all checkpoints that match a given configuration
    checkpoints = memory.list({"configurable": {"thread_id": "1"}})
    # Process the checkpoints
    process_checkpoints(checkpoints)

Voici comment il stocke les points de contrôle :

Checkpoint:
Timestamp: 2025-12-30T09:19:41.691087+00:00
Checkpoint ID: 1f0e560a-c2fa-69ec-8001-14ee5373f9cf
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)
Agent:  (Message ID: lc_run--019b6e8e-553f-7b52-8796-a8b1fbb206a4-0)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.350507+00:00
Checkpoint ID: 1f0e560a-b631-6a08-8000-7796d108109a
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.349027+00:00
Checkpoint ID: 1f0e560a-b62e-6010-bfff-cbebe1d865f6

Pour la mémoire à long terme, voici comment nous effectuons une recherche sémantique sur Elasticsearch pour récupérer des conversations précédentes pertinentes en utilisant des vecteurs d'intégration après la résumé et l'indexation des points de contrôle dans Elasticsearch.

Functions: 
retrieve_from_elasticsearch() 

# Enhanced Elasticsearch retrieval with rank_window and verbose display
def retrieve_from_elasticsearch(query: str, k: int = 5, rank_window: int = None) -> tuple[List[Dict[str, Any]], str]:
    """
    Retrieve context from Elasticsearch with score-based ranking
    
    Args:
        query: Search query
        k: Number of results to return
        rank_window: Number of candidates to retrieve before ranking (default: args.rank_window)
        
    Returns:
        Tuple of (retrieved_documents, formatted_context_string)
    """
    if not es_client or not es_index_name:
        return [], "Elasticsearch is not available. Cannot search long-term memory."
    
    if rank_window is None:
        rank_window = args.rank_window
    
    try:
        # Check if index exists and has documents
        if not es_client.indices.exists(index=es_index_name):
            return [], "No previous conversations stored in long-term memory yet."
        
        # Get document count
        try:
            doc_count = es_client.count(index=es_index_name)["count"]
            if doc_count == 0:
                return [], "Long-term memory is empty. No previous conversations to search."
        except Exception as e:
            return [], f"Error checking memory: {str(e)}"
        
        # Generate embedding for the query
        try:
            query_embedding = embeddings.embed_query(query)
        except Exception as e:
            return [], f"Error generating embedding: {str(e)}"
        
        # Perform semantic search using kNN with rank_window
        try:
            search_body = {
                "knn": {
                    "field": "vector",
                    "query_vector": query_embedding,
                    "k": k,
                    "num_candidates": rank_window  # Retrieve more candidates, then rank top k
                },
                "_source": ["text", "content", "message_type", "timestamp", "thread_id"],
                "size": k
            }
            
            response = es_client.search(index=es_index_name, body=search_body)
            
            if not response.get("hits") or len(response["hits"]["hits"]) == 0:
                return [], "No relevant previous conversations found in long-term memory."
            
            # Extract documents with scores
            retrieved_docs = []
            for hit in response["hits"]["hits"]:
                source = hit["_source"]
                score = hit["_score"]
                retrieved_docs.append({
                    "content": source.get("content", source.get("text", "")),
                    "message_type": source.get("message_type", "unknown"),
                    "timestamp": source.get("timestamp", "unknown"),
                    "thread_id": source.get("thread_id", "unknown"),
                    "score": score
                })
            
            # Format context string
            context_parts = []
            for i, doc in enumerate(retrieved_docs, 1):
                context_parts.append(doc["content"])
            
            context_string = "\n\n".join(context_parts)
            
            # Verbose display
            if args.verbose:
                rich.print(f"\n[bold yellow]🔍 RETRIEVAL ANALYSIS[/bold yellow]")
                rich.print("="*80)
                rich.print(f"[blue]Query:[/blue] {query}")
                rich.print(f"[blue]Retrieved:[/blue] {len(retrieved_docs)} documents (from {rank_window} candidates)")
                rich.print(f"[blue]Total context length:[/blue] {len(context_string)} characters\n")
                
                for i, doc in enumerate(retrieved_docs, 1):
                    rich.print(f"[cyan]📄 Document {i} | Score: {doc['score']:.4f} | Type: {doc['message_type']}[/cyan]")
                    rich.print(f"[cyan]   Timestamp: {doc['timestamp']} | Thread: {doc['thread_id']}[/cyan]")
                    content_preview = doc['content'][:200] + "..." if len(doc['content']) > 200 else doc['content']
                    rich.print(f"[cyan]   Content: {content_preview}[/cyan]")
                    rich.print("-" * 80)
            
            return retrieved_docs, context_string
            
        except Exception as e:
            return [], f"Error searching memory: {str(e)}"
            
    except Exception as e:
        return [], f"Error accessing long-term memory: {str(e)}"

Maintenant que nous avons exploré comment la mémoire à court terme et la mémoire à long terme sont indexées et récupérées à l’aide des points de contrôle de LangGraph dans Elasticsearch, prenons un moment pour comprendre pourquoi l'indexation et le vidage des conversations complètes peut être risqué.

Risques liés à une mauvaise gestion de la mémoire de contexte

Alors que nous parlons beaucoup d’ingénierie du contexte, ainsi que de la mémoire à court et à long terme, comprenons ce qui se passe si nous ne gérons pas bien la mémoire et le contexte d’un agent.

Malheureusement, de nombreux problèmes peuvent survenir lorsque le contexte d’une IA devient extrêmement long ou contient des informations erronées. Au fur et à mesure que les fenêtres contextuelles s’agrandissent, de nouveaux modes de défaillance apparaissent, comme :

• Empoisonnement contextuel
• Distraction contextuelle
• Confusion de contexte
• Conflit de contexte
• Fuite de contexte et conflits de connaissances
• Hallucinations et désinformation.

Examinons ces problèmes et les autres risques qui découlent d'une mauvaise gestion du contexte :

Empoisonnement contextuel

L'empoisonnement du contexte fait référence au fait que des informations incorrectes ou nuisibles apparaissent dans le contexte et « empoisonne » les sorties ultérieures du modèle. Un exemple courant est une hallucination du modèle qui est traitée comme un fait et insérée dans l'historique de la conversation. Le modèle pourrait alors s'appuyer sur cette erreur dans les réponses ultérieures, aggravant la faute. Dans les boucles itératives d'agents, une fois qu'une fausse information s'est intégrée dans le contexte partagé (par exemple, dans un résumé des notes de travail de l'agent), elle peut être renforcée à maintes reprises.

Les chercheurs de DeepMind, dans la publication du rapport Gemini 2.5 (TL;DR, consultez ici), ont observé ce phénomène chez un agent joueur de Pokémon delongue date : si l'agent hallucinait un état de jeu erroné et que celui-ci était enregistré dans son contexte (sa mémoire des objectifs), il formait des stratégies absurdes autour d'un objectif impossible et se retrouvait bloqué. En d'autres termes, une mémoire empoisonnée peut envoyer l'agent sur la mauvaise voie indéfiniment.

L'empoisonnement du contexte peut se produire de manière innocente (par erreur) ou même de manière malveillante, par exemple via des attaques par injection de requêtes où un utilisateur ou un tiers introduit une instruction cachée ou une fausse information que l'agent mémorise ensuite et suit.

Contre-mesures recommandées :

S’appuyant sur les informations de Wiz, Zerlo et Anthropic, les contre-mesures contre l’empoisonnement du contexte visent à empêcher que des informations erronées ou trompeuses ne pénètrent dans l’invite, la fenêtre de contexte ou le pipeline de récupération d’un LLM. Parmi les principales étapes, citons :

• Vérifiez constamment le contexte : surveillez la conversation ou le texte récupéré afin de détecter tout élément suspect ou nuisible, et pas seulement l’invite de départ.
• Utilisez des sources fiables : attribuez une note ou un label aux documents en fonction de leur crédibilité afin que le système privilégie les informations fiables et ignore les données mal notées.
• Repérez les données inhabituelles : utilisez des outils qui détectent les contenus bizarres, déplacés ou manipulés, et supprimez-les avant que le modèle ne les utilise.
• Filtrez les entrées et les sorties : ajoutez des garde-fous pour que les textes nuisibles ou trompeurs ne puissent pas facilement entrer dans le système ou être répétés par le modèle.
• Mettez le modèle à jour avec des données propres : actualisez régulièrement le système avec des informations vérifiées afin de corriger les éventuelles données erronées.
• Supervision humaine : faites examiner les sorties importantes par des personnes ou comparez-les à des sources connues et fiables.

De simples habitudes utilisateur sont également utiles : réinitialiser les longues conversations, ne partager que les informations pertinentes, découper les tâches complexes en étapes plus simples et conserver des notes claires en dehors du modèle.

Ensemble, ces mesures créent une défense en couches qui protège les LLM contre l'empoisonnement du contexte et maintient les sorties précises et dignes de confiance.

Sans les contre-mesures mentionnées ici, un agent pourrait se souvenir d'instructions, comme ignorer des lignes directrices antérieures ou des faits triviaux insérés par un attaquant, ce qui conduirait à des sorties nuisibles.

Distraction contextuelle

On parle de distraction contextuelle lorsqu'un contexte devient si long que le modèle se concentre excessivement sur le contexte, négligeant ce qu'il a appris pendant la formation. Dans les cas extrêmes, cela ressemble à un oubli catastrophique, c'est-à-dire que le modèle « oublie » effectivement ses connaissances sous-jacentes et s'attache excessivement aux informations qui lui sont présentées. Des études précédentes ont montré que les LLM perdent souvent leur concentration lorsque l'invite est extrêmement longue.

L'agent Gemini 2.5, par exemple, prenait en charge une fenêtre d'un million de jetons, mais dès que son contexte dépassait un certain seuil (de l'ordre de 100 000 jetons dans une expérience), il commençait à s'attacher à répéter ses actions passées au lieu de proposer de nouvelles solutions. En un sens, l’agent est devenu prisonnier de sa longue histoire. Il a continué à regarder son long log de mouvements précédents (le contexte) et à les imiter, plutôt que d'utiliser ses connaissances d'entraînement sous-jacentes pour concevoir des stratégies nouvelles et inédites.

C'est contreproductif. Nous voulons que le modèle utilise un contexte pertinent pour faciliter le raisonnement, et non qu'il prenne le pas sur sa capacité de réflexion. Fait notable, même les modèles disposant de fenêtres très larges présentent une forme de dégradation du contexte : leurs performances se détériorent de manière non uniforme à mesure que le nombre de jetons augmente. Il semble exister un budget d’attention : tout comme les humains ont une mémoire de travail limitée, un LLM dispose d’une capacité finie pour traiter les jetons, et plus ce budget est sollicité, plus sa précision et sa concentration diminuent.

Pour atténuer ce problème, vous pouvez empêcher la distraction contextuelle en utilisant la segmentation, en concevant les bonnes informations, en résumant régulièrement le contexte et en appliquant des techniques d’évaluation et de surveillance pour mesurer la précision de la réponse à l’aide de la notation.

Ces méthodes permettent au modèle de rester ancré dans un contexte pertinent et dans sa formation sous-jacente, ce qui réduit le risque de distraction et améliore la qualité globale du raisonnement.

Confusion de contexte

La confusion contextuelle se produit lorsque le modèle utilise du contenu superflu dans le contexte pour générer une réponse de faible qualité. Un bon exemple est de fournir à un agent un large éventail d'outils ou de définitions d'API qu'il peut utiliser. Si bon nombre de ces outils n'ont aucun rapport avec la tâche en cours, le modèle peut tout de même essayer de les utiliser de manière inappropriée, simplement parce qu'ils sont présents dans le contexte. Les expériences ont montré que fournir plus d'outils ou de documents peut nuire aux performances s'ils ne sont pas tous nécessaires. L’agent commence à faire des erreurs, comme appeler la mauvaise fonction ou référer un texte sans importance.

Dans un cas, un petit modèle Llama 3.1 8B a échoué à une tâche lorsqu'on lui a donné 46 outils à prendre en compte, mais a réussi lorsqu'on ne lui a donné que 19 outils. Ces outils supplémentaires ont créé de la confusion, même si le contexte respectait les limites de longueur. Le problème sous-jacent est que toute information contenue dans l'invite sera prise en compte par le modèle. Si un système ne sait pas ignorer quelque chose, ce quelque chose pourrait influencer sa sortie de manière indésirable. Des éléments non pertinents peuvent « détourner » une partie de l'attention du modèle et l'induire en erreur (par exemple, un document non pertinent pourrait amener l'agent à répondre à une question différente de celle posée). La confusion contextuelle se manifeste souvent par la production, par le modèle, d'une réponse de faible qualité intégrant un contexte non pertinent. Se référer à l'article de recherche : Less is More: Optimizing Function Calling for LLM Execution on Edge Devices.

Cela nous rappelle qu'il n'est pas toujours préférable d'avoir plus de contexte, surtout si ce n'est pas organisé pour des raisons de pertinence.

Conflit de contexte

Il y a conflit de contexte lorsque des éléments du contexte se contredisent, provoquant des incohérences internes qui font dérailler le raisonnement du modèle. Un conflit peut survenir si l'agent accumule plusieurs éléments d'information qui sont en conflit.

Par exemple, imaginez un agent qui a récupéré des données de deux sources : l'une dit Le vol A part à 17 h, et l'autre dit Le vol A part à 18 h. Si les deux faits se retrouvent dans le contexte, le modèle pauvre n'a aucun moyen de savoir lequel est correct ; il peut s'embrouiller ou produire une réponse incorrecte ou non similaire.

Le conflit de contexte se produit aussi fréquemment dans les conversations à plusieurs tours, lorsque les tentatives de réponse antérieures du modèle sont encore présentes dans le contexte avec des informations affinées ultérieurement.

Une étude menée par Microsoft et Salesforce montre que si l'on divise une requête complexe en plusieurs échanges avec un chatbot (en ajoutant progressivement des détails), la précision finale diminue considérablement, comparée à la fourniture de tous les détails en une seule requête. Pourquoi ? Parce que les premiers tours contiennent des réponses intermédiaires partielles ou incorrectes du modèle, et que celles-ci restent dans le contexte. Lorsque le modèle tente par la suite de répondre avec toutes les informations, sa mémoire contient encore ces tentatives erronées, qui entrent en conflit avec les informations corrigées et l'éloignent de la bonne voie. En substance, le contexte de la conversation entre en conflit avec lui-même. Le modèle peut utiliser par inadvertance un élément de contexte obsolète (d'un tour précédent) qui ne s'applique plus après l'ajout de nouvelles informations.

Dans les systèmes agents, le conflit de contexte est particulièrement dangereux, car un agent peut combiner des sorties provenant de différents outils ou sous-agents. Si ces sorties divergent, le contexte agrégé est incohérent. L'agent pourrait alors se retrouver bloqué ou produire des résultats absurdes en essayant de réconcilier les contradictions. Prévenir les conflits de contexte implique de s’assurer que le contexte est frais et cohérent, par exemple en effaçant .ou en mettant à jour toute information obsolète et en ne mélangeant pas les sources qui n’ont pas été vérifiées pour leur cohérence.

Fuite de contexte et conflits de connaissances

Dans les systèmes où plusieurs agents ou utilisateurs partagent un stockage de mémoire, il existe un risque de fuite d'informations entre les contextes.

Par exemple, si les intégrations de données de deux utilisateurs distincts résident dans la même base vectorielle sans un contrôle d’accès approprié, un agent répondant à la requête de l’utilisateur A pourrait accidentellement récupérer une partie de la mémoire de l’utilisateur B. Cette fuite intercontextuelle peut révéler des informations privées ou simplement créer de la confusion dans les réponses.

Selon le Top 10 de l'OWASP pour les applications LLM, les bases vectorielles multitenant doivent se prémunir contre de telles fuites :

Selon LLM08:2025 Vector and Embedding Weaknesses, l'un des risques courants est la fuite de contexte :

Dans les environnements multi-locataires où plusieurs classes d’utilisateurs ou d’applications partagent la même base vectorielle, il existe un risque de fuite de contexte entre utilisateurs ou requêtes. Les erreurs de conflit de connaissances dans la fédération de données peuvent survenir lorsque les données provenant de sources multiples se contredisent les unes les autres. Cela peut également se produire lorsqu'un LLM ne peut pas remplacer les anciennes connaissances qu'il a acquises pendant la formation par les nouvelles données issues de l'augmentation de la récupération.

Un autre aspect est qu'un LLM peut avoir du mal à remplacer ses connaissances intégrées par de nouvelles informations de mémoire. Si le modèle a été formé sur la base d'un fait et que le contexte retrouvé dit le contraire, le modèle peut ne pas savoir à quoi se fier. Sans une conception appropriée, l'agent pourrait confondre les contextes ou ne pas mettre à jour les anciennes connaissances avec de nouvelles preuves, conduisant à des réponses obsolètes ou incorrectes.

Hallucinations et désinformation.

Si l'hallucination (le LLM invente des informations plausibles mais fausses) est un problème connu, même sans contexte prolongé, une mauvaise gestion de la mémoire peut l'amplifier.

Si la mémoire de l'agent manque d'un fait crucial, le modèle peut simplement combler cette lacune par une supposition, et si cette supposition entre ensuite dans le contexte (en l'empoisonnant), l'erreur persiste.

Le rapport de sécurité OWASP LLM (LLM09:2025 Désinformation) met en évidence la désinformation comme une vulnérabilité fondamentale : les LLM peuvent produire des réponses confiantes mais fabriquées, et les utilisateurs peuvent leur accorder trop de crédit. Un agent dont la mémoire à long terme est mauvaise ou obsolète peut citer en toute confiance une information qui était vraie l'année dernière mais qui est fausse aujourd'hui, à moins que sa mémoire ne soit mise à jour.

Une dépendance excessive à la sortie de l'IA (par l'utilisateur ou l'agent lui-même dans la boucle) peut aggraver cette situation. Si personne ne vérifie jamais les informations en mémoire, l'agent peut accumuler de fausses informations. C’est pourquoi la méthode RAG est souvent utilisée pour réduire les hallucinations : en se référant à une source faisant autorité, le modèle n’a pas besoin d’inventer des faits. Mais si votre recherche aboutit au mauvais document (par exemple, un document contenant des informations erronées) ou si une hallucination précoce n'est pas élaguée, le système peut propager ces informations erronées dans toutes ses actions.

En résumé : une mauvaise gestion de la mémoire peut conduire à des sorties incorrectes et trompeuses, ce qui peut être préjudiciable, surtout si les enjeux sont importants (par exemple, de mauvais conseils dans le domaine financier ou médical). Un agent doit disposer de mécanismes pour vérifier ou corriger le contenu de sa mémoire, et non simplement faire confiance de manière inconditionnelle à ce qui se trouve dans le contexte.

En résumé, doter un agent d'IA d'une mémoire infiniment longue ou déverser tout ce qui est possible dans son contexte n' est pas une recette pour le succès.

Bonnes pratiques pour la gestion de la mémoire dans les applications LLM

Pour éviter les pièges ci-dessus, les développeurs et les chercheurs ont élaboré un certain nombre de bonnes pratiques pour gérer le contexte et la mémoire dans les systèmes d'IA. Ces pratiques visent à maintenir le contexte de travail de l'IA allégé, pertinent et actualisé. Voici quelques-unes des stratégies clés, accompagnées d'exemples de leur utilité.

RAG : utiliser le contexte ciblé.

Une grande partie de RAG a déjà été abordée dans la section précédente, ceci constitue donc un rappel pratique et concis :

• Utilisez une récupération ciblée, pas un chargement en masse : récupérez uniquement les extraits les plus pertinents au lieu d'insérer des documents entiers ou des historiques de conversation complets dans l'invite.
• Considérez RAG comme un rappel de mémoire à la demande : récupérez le contexte uniquement lorsqu’il est nécessaire, plutôt que de tout conserver d’un échange à l’autre.
• Privilégiez des stratégies de récupération sensibles à la pertinence : des approches telles que la recherche sémantique top-k, la fusion de rangs réciproques (Reciprocal Rank Fusion) ou le filtrage par configuration d’outils permettent de réduire le bruit et d’améliorer l’ancrage.
• Des fenêtres de contexte plus larges ne suppriment pas le besoin de RAG : deux paragraphes hautement pertinents sont presque toujours plus efficaces que 20 pages vaguement liées.

Cela dit, RAG ne vise pas à ajouter plus de contexte ; il s’agit d’ajouter le bon contexte.

Chargement des outils

Le loadout d’outils consiste à donner à un modèle uniquement les outils dont il a réellement besoin pour une tâche. Le terme vient du jeu : vous choisissez une configuration qui convient à la situation. Trop d'outils vous ralentissent ; les mauvais sont à l'origine de l'échec. Les LLM se comportent de la même manière, selon l'article de recherche Less is more. Une fois que vous dépassez ~30 outils, les descriptions commencent à se chevaucher et le modèle se trouve dérouté. Plus de 100 outils, l'échec est presque garanti. Ce n’est pas un problème de fenêtre contextuelle, c’est une confusion de contexte.

Une solution simple et efficace est RAG-MCP. Au lieu de saisir tous les outils dans l'invite, les descriptions d'outils sont stockées dans une base vectorielle et seuls les outils les plus pertinents sont récupérés par demande. En pratique, cela permet de réduire la taille de l'équipement et de le concentrer, de raccourcir considérablement les instructions et d'améliorer la précision de la sélection des outils jusqu'à 3 fois.

Les modèles plus petits atteignent ce plafond encore plus tôt. La recherche montre qu'un modèle 8B échoue avec des dizaines d'outils mais réussit une fois que la configuration est réduite. La sélection dynamique des outils, parfois précédée d’une réflexion par un LLM sur ce dont il pense avoir besoin, peut améliorer les performances de 44 %, tout en réduisant la consommation d’énergie et la latence. La principale leçon est que la plupart des agents n’ont besoin que de quelques outils, mais à mesure que votre système se développe, la configuration des outils et le RAG-MCP deviennent des choix de conception de premier ordre.

Élagage du contexte : limiter la longueur de l'historique de conversation

Si une conversation se poursuit sur de nombreux tours, l'historique de discussion accumulé peut devenir trop volumineux pour tenir, entraînant un débordement de contexte ou devenant trop distrayant pour le modèle.

Le rognage consiste à supprimer ou à raccourcir par programmation les parties les moins importantes du dialogue au fur et à mesure qu'il grandit. Une forme simple consiste à supprimer les tours de parole les plus anciens lorsque vous atteignez une certaine limite, en ne conservant que les N derniers messages. Un élagage plus sophistiqué pourrait supprimer les digressions non pertinentes ou les instructions précédentes devenues inutiles. L'objectif est de ne pas encombrer la fenêtre contextuelle par les anciennes actualités.

Par exemple, si l’agent a résolu un sous-problème il y a 10 échanges et que nous sommes passés à autre chose depuis, nous pourrions supprimer cette partie de l’historique du contexte (en supposant qu’elle ne sera plus nécessaire). De nombreuses implémentations basées sur le chat font cela : elles assurent la maintenance d'une fenêtre dynamique de messages récents.

La suppression peut être aussi simple que le fait d’« oublier » les premières parties d’une conversation une fois qu’elles ont été résumées ou jugées non pertinentes. Ce faisant, nous réduisons le risque d'erreurs de débordement du contexte et nous réduisons également la distraction du contexte, de sorte que le modèle ne voit pas et ne se laisse pas distraire par un contenu ancien ou hors sujet. Cette approche ressemble beaucoup à celle des humains, qui ne se souviennent peut-être pas de chaque mot d’une conférence d’une heure, mais en retiennent les points essentiels.

Si vous avez des doutes sur l'élagage de contexte, comme le souligne l'auteur Drew Breunig ici, l'utilisation du modèle Provence (`naver/provence-reranker-debertav3-v1`), un élagueur de contexte léger (1,75 Go), efficace et précis pour la réponse aux questions, peut faire la différence. Il peut réduire de gros documents à seulement le texte le plus pertinent pour une requête donnée. Vous pouvez l'appeler à des intervalles précis.

Voici comment nous invoquons le modèle `provence-reranker` dans notre code pour élaguer le contexte :

# Context pruning with Provence
def prune_with_provence(query: str, context: str, threshold: Optional[float] = None) -> str:
    """
    Prune context using Provence reranker model
    
    Args:
        query: User's query/question
        context: Original context to prune
        threshold: Relevance threshold (0-1) for Provence reranker.
                   If None, uses args.pruning_threshold.
                   0.1 = conservative (recommended, no performance drop)
                   0.3-0.5 = moderate to aggressive pruning
    
    Returns:
        Pruned context with only relevant sentences
    """
    if provence_model is None:
        return context
    
    if threshold is None:
        threshold = args.pruning_threshold
    
    try:
        # Use Provence's process method
        provence_output = provence_model.process(
            question=query,
            context=context,
            threshold=threshold,
            always_select_title=False,
            enable_warnings=False
        )
        
        # Extract pruned context from output
        pruned_context = provence_output.get('pruned_context', context)
        reranking_score = provence_output.get('reranking_score', 0.0)
        
        # Log statistics
        original_length = len(context)
        pruned_length = len(pruned_context)
        reduction_pct = ((original_length - pruned_length) / original_length * 100) if original_length > 0 else 0
        
        if args.verbose:
            rich.print(f"[cyan]📊 Pruning stats: {pruned_length}/{original_length} chars ({reduction_pct:.1f}% reduction, threshold={threshold:.2f}, rerank_score={reranking_score:.3f})[/cyan]")
        
        return pruned_context if pruned_context else context
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in Provence pruning: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

Nous utilisons le modèle de reranker Provence (`naver/provence-reranker-debertav3-v1`) pour évaluer la pertinence des phrases. La filtration basée sur des seuils conserve les phrases au-dessus du seuil de pertinence. Nous introduisons également un mécanisme de repli, qui permet de revenir au contexte d'origine en cas d'échec de l'élagage. Enfin, le logging des statistiques permet de suivre le pourcentage de réduction en mode verbeux.

Synthèse du contexte : condenser les anciennes informations au lieu de les supprimer entièrement

Le résumé va de pair avec le découpage. Lorsque l’historique ou la base de connaissances devient trop vaste, vous pouvez utiliser le LLM pour générer un bref résumé des points importants et utiliser ce résumé à la place du contenu complet par la suite, comme nous l’avons fait dans notre code ci-dessus.

Par exemple, si un assistant IA a eu une conversation de 50 tours, au lieu d'envoyer tous les 50 tours au modèle au tour 51 (ce qui ne rentrera probablement pas), le système pourrait prendre les tours 1 à 40, demander au modèle de les résumer en un paragraphe, et ensuite ne fournir que ce résumé plus les 10 derniers tours dans la prochaine invite. De cette façon, le modèle reste conscient de ce qui a été discuté sans avoir besoin de tous les détails. Les premiers utilisateurs de chatbots faisaient cela manuellement en demandant : « Pouvez-vous résumer ce dont nous avons parlé jusqu'à présent ? » puis en continuant dans une nouvelle session avec le résumé. Maintenant, cela peut être automatisé. Le résumé permet non seulement d'économiser de l'espace dans la fenêtre contextuelle, mais aussi de réduire la confusion et la distraction en éliminant les détails supplémentaires et en ne conservant que les faits saillants.

Voici comment nous utilisons les modèles OpenAI (vous pouvez utiliser n’importe quel LLM) pour condenser le contexte tout en préservant toutes les informations pertinentes, en éliminant la redondance et la duplication.

# Context summarization
def summarize_context(query: str, context: str) -> str:
    """
    Summarize context using LLM to reduce duplication and focus on relevant information
    
    Args:
        query: User's query/question
        context: Context to summarize
        
    Returns:
        Summarized context
    """
    try:
        summary_prompt = f"""You are an expert at summarizing conversation context.

Your task: Analyze the provided conversation context and produce a condensed summary that fully answers or supports the user's specific question.

The summary must:
1. Preserve every fact, detail, and information that directly relates to the question
2. Eliminate redundancy and duplicate information
3. Maintain chronological flow when relevant
4. Focus on information that helps answer: "{query}"

Context to summarize:
{context}

Provide a concise summary that preserves all relevant information:"""

        summary = llm.invoke(summary_prompt).content
        
        if args.verbose:
            original_length = len(context)
            summary_length = len(summary)
            reduction_pct = ((original_length - summary_length) / original_length * 100) if original_length > 0 else 0
            rich.print(f"[cyan]📝 Summarization stats: {summary_length}/{original_length} chars ({reduction_pct:.1f}% reduction)[/cyan]")
        
        return summary
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in context summarization: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

Il est important de noter que lorsque le contexte est résumé, le modèle est moins susceptible d'être submergé par des détails insignifiants ou des erreurs passées (en supposant que le résumé soit exact).

Cependant, le résumé doit être fait avec soin. Un mauvais résumé peut omettre un détail crucial ou même introduire une erreur. Il s’agit essentiellement d’une autre invite adressée au modèle (« résumez ceci »), ce qui peut entraîner des hallucinations ou une perte de nuances. Une bonne pratique consiste à résumer de manière incrémentielle et peut-être conserver certains faits canoniques non résumés.

Néanmoins, il s'est avéré très utile. Dans le scénario de l'agent Gemini, le fait de résumer le contexte tous les 100 000 jetons environ a permis de contrecarrer la tendance du modèle à se répéter. Le résumé agit comme une mémoire compressée de la conversation ou des données. En tant que développeurs, nous pouvons mettre cela en œuvre en demandant à un agent d'appeler périodiquement une fonction de résumé (peut-être un LLM plus petit ou une routine dédiée) sur l'historique de la conversation ou un long document. Le résumé résultant remplace le contenu original dans la consigne. Cette tactique est largement utilisée pour limiter les contextes et distiller l'information.

Quarantaine contextuelle : isolez les contextes lorsque c'est possible

Cela est plus pertinent dans les systèmes d'agents complexes ou les workflows à plusieurs étapes. L'idée de la segmentation du contexte est de diviser une grande tâche en sous-tâches plus petites et isolées, chacune ayant son propre contexte, de sorte que vous n'accumuliez jamais un contexte énorme qui contient tout. Chaque sous-agent ou sous-tâche travaille sur une partie du problème dans un contexte précis, puis un agent de niveau supérieur, un superviseur ou un coordinateur intègre les résultats.

La stratégie de recherche d’Anthropic utilise plusieurs sous-agents, chacun examinant un aspect différent d’une question, avec ses propres fenêtre de contexte, et un agent principal qui lit les résultats synthétisés de ces sous-agents. Cette approche parallèle et modulaire signifie qu'aucune fenêtre contextuelle unique ne devient trop volumineuse. Cela réduit également le risque de mélange d'informations non pertinentes, chaque fil de discussion reste sur le sujet (pas de confusion de contexte), et il ne transporte pas de bagages superflus lors de la réponse à sa sous-question spécifique. Dans un sens, c'est comme suivre des fils de réflexion distincts qui ne partagent que leurs résultats, et non l'ensemble de leur processus de réflexion.

Dans les systèmes multi-agents, cette approche est essentielle. Si l'agent A gère la tâche A et l'agent B gère la tâche B, il n'y a aucune raison pour que l'un ou l'autre agent consomme le contexte complet de l'autre, sauf si c'est vraiment nécessaire. Les agents ne peuvent échanger que les informations nécessaires. Par exemple, l'agent A peut transmettre un résumé consolidé de ses résultats à l'agent B via un agent superviseur, tandis que chaque sous-agent assure la maintenance de son propre fil de contexte dédié. Cette configuration ne nécessite pas d'intervention humaine ; elle repose sur un agent de supervision doté d'outils activés avec un partage de contexte minimal et contrôlé.

Néanmoins, concevoir votre système de manière à ce que les agents ou les outils fonctionnent avec un chevauchement minimal du contexte nécessaire peut grandement améliorer la clarté et les performances. Pensez-y comme à des microservices pour l'IA, chaque composant s'occupe de son contexte, et vous passez des messages entre eux de manière contrôlée, au lieu d'un contexte monolithique. Ces bonnes pratiques sont souvent utilisées de manière combinée. Cela vous offre également la possibilité de supprimer l'historique trivial, de résumer les anciens messages ou conversations importants, de décharger les logs détaillés vers Elasticsearch pour un contexte à long terme et d'utiliser la récupération pour retrouver tout élément pertinent en cas de besoin.

Comme indiqué ici, le principe directeur est que le contexte est une ressource limitée et précieuse. Vous souhaitez que chaque élément de l'invite soit utile, c'est-à-dire qu'il contribue à la qualité de la sortie. Si quelque chose en mémoire ne joue pas son rôle (ou pire, provoque activement de la confusion), alors il devrait être élagué, résumé ou tenu à l'écart.

En tant que développeurs, nous pouvons désormais programmer le contexte comme nous programmons du code, en décidant quelles informations inclure, comment les formater et quand les omettre ou les mettre à jour. En suivant ces pratiques, nous pouvons fournir aux agents LLM le contexte indispensable pour effectuer des tâches sans être victimes des modes de défaillance décrits précédemment. Le résultat : des agents qui retiennent ce qu’ils doivent, oublient ce qui leur est inutile et récupèrent ce dont ils ont besoin juste à temps.

Conclusion

La mémoire n'est pas quelque chose que l'on ajoute à un agent, c'est quelque chose que l'on développe. La mémoire à court terme est le bloc-notes de travail de l'agent, et la mémoire à long terme est son stock de connaissances durable. RAG est le pont entre les deux, transformant un datastore passif, comme Elasticsearch, en un mécanisme de rappel actif qui peut ancrer les sorties et maintenir l'agent à jour.

Mais la mémoire est une arme à double tranchant. Dès que vous laissez le contexte se développer sans contrôle, vous invitez l'empoisonnement, la distraction, la confusion et les conflits, et dans les systèmes partagés, même des fuites de données. C’est pourquoi le travail de mémoire le plus important n’est pas de « stocker davantage », mais de « mieux sélectionner » : récupérer de manière sélective, élaguer avec rigueur, résumer avec soin et éviter de mélanger des contextes non liés, sauf si la tâche l’exige réellement.

En pratique, une bonne ingénierie du contexte ressemble à une bonne conception de systèmes : des contextes plus petits et suffisants, des interfaces contrôlées entre les composants, et une séparation claire entre l'état brut et l'état distillé que vous voulez réellement que le modèle voie. Si l'on procède correctement, on ne se retrouve pas avec un agent qui se souvient de tout, mais avec un agent qui se souvient des bonnes choses, au bon moment et pour la bonne raison.

Nous avons effectué une mise à niveau majeure de l'infrastructure pour tous les projets Elastic Cloud Serverless exécutés sur AWS, en migrant vers du matériel plus récent et plus performant. Cette modification a été déployée automatiquement sur tous les projets sans serveur. Vous bénéficiez maintenant d'un débit plus élevé et d'une latence plus faible pour les projets sans serveur Elasticsearch, Elastic Observability et Elastic Security sur AWS.

Principaux avantages en termes de performances pour les développeurs

La nouvelle infrastructure matérielle d'AWS sous-tend tout ce que vous faites avec Elastic Cloud Serverless, ce qui se traduit par des avantages tangibles au niveau de la vitesse et de la réactivité de vos applications.

Latence des requêtes réduite… débit accru

Le matériel amélioré augmente considérablement la vitesse des ressources de calcul ; vos requêtes de recherche sont ainsi traitées plus rapidement que jamais.

• Recherche et recherche vectorielle : que vous exécutiez des recherches full text traditionnelles ou que vous utilisiez la recherche vectorielle de pointe pour vos applications d'IA générative et de génération augmentée par récupération (RAG), vous constaterez une diminution notable de la latence. Une analyse comparative interne a révélé une diminution moyenne de 35 % de la latence de recherche.
• Indexation plus rapide : les taux d'ingestion de données sont optimisés, vous permettant d'indexer d'énormes volumes de données et des documents complexes avec un débit accru. Ceci est crucial pour les applications qui nécessitent une visibilité des données en temps quasi‑réel. L'évaluation comparative interne a montré une augmentation moyenne de 26 % du débit d'indexation.

Performances constantes sous charge

Elastic Cloud Serverless est conçu pour s'adapter automatiquement et dynamiquement en temps réel à la demande, minimisant ainsi la latence, quelle que soit votre charge de travail. Grâce à cette amélioration matérielle, le scaling est désormais plus performant et réactif.

• Gestion facile des pics de charge : qu'il s'agisse d'une augmentation soudaine du trafic utilisateur ou d'une ingestion massive de données par lots, la nouvelle infrastructure garantit un scaling vertical plus efficace sur vos ressources de recherche et d'indexation afin de maintenir une latence faible de façon constante.
• Découplage optimisé calcul‑stockage : l'architecture sans serveur sépare le calcul et le stockage, ce qui permet aux charges de travail de scaler indépendamment pour des performances et une rentabilité optimales. Le matériel plus rapide améliore la couche de calcul, maximisant l'efficacité de cette conception découplée.

Sous le capot : résultats des analyses comparatives internes

Pour quantifier l'impact de la mise à niveau de notre infrastructure AWS, l'équipe d'ingénierie d'Elastic a mené des tests de performance internes complets sur un large éventail de charges de travail sans serveur. Ces charges de travail ont fourni des preuves concrètes des améliorations de performances que vous pouvez attendre de vos applications, quel que soit votre cas d'utilisation.

L'approche d'analyse comparative

Nous avons concentré nos tests sur les indicateurs clés qui influencent directement l'expérience développeur et la réactivité des applications : le temps de réponse (c'est-à-dire la latence) et le débit lors des opérations de recherche et d'indexation.

• Test des charges de travail : les tests comprenaient des opérations de recherche à haute simultanéité typiques des applications destinées aux utilisateurs, des requêtes de recherche vectorielle complexes et l'ingestion/l'indexation de données à fort volume pour des cas d'utilisation d'observabilité et de sécurité. Plus précisément, notre méthodologie de test a utilisé des ensembles de données accessibles au public pour Rally, l'outil d'évaluation comparative d'Elastic.
  • wikipedia: Un ensemble de données issu d'un instantané du contenu textuel de Wikipédia, pour mesurer les performances de recherche textuelle à usage général.
  • MSMARCO-Passage-Ranking: Un ensemble de données issu de Microsoft Machine Reading Comprehension (MS MARCO), pour mesurer les performances de recherche sur des champs vectoriels épars.
  • OpenAI_Vector: Un ensemble de données issu du NQ de BEIR et enrichi d'embeddings générés par le modèle text-embedding-ada-002 d'OpenAI, pour évaluer les performances de recherche sur des champs vectoriels denses.
• Mesure : nous avons comparé les performances de l'ancienne et de la nouvelle infrastructure, en mesurant la latence au 99e percentile (P99) afin de capturer les performances les plus mauvaises et le nombre d'opérations par seconde, en tenant compte de la latence de queue. Chaque piste a été exécutée cinq fois pour chaque profil de matériel afin de garantir la cohérence des résultats.
• L'objectif : Notre objectif était de valider la capacité de l'infrastructure à fournir des performances plus rapides et plus prévisibles de manière constante, même pendant les périodes d'autoscaling rapide.

Résumé des données de performance

Les résultats confirment des gains d'efficacité et de rapidité significatifs. Ces gains se traduisent directement par des temps de réponse plus courts pour vos utilisateurs et par une réduction des coûts opérationnels grâce à la possibilité d'effectuer la même quantité de travail avec moins de ressources de calcul.

Les tableaux suivants décrivent en détail les améliorations quantitatives. Plus les valeurs sont élevées, meilleur est le débit ; plus les valeurs sont faibles, meilleure est la latence.

Résultats des recherches de référence :

Résultats de référence de l'indexation :

L'avantage supplémentaire : réduction des coûts

Bien que notre priorité soit de fournir des performances à faible latence, l'efficacité du nouveau matériel a également un impact direct et positif sur les coûts des projets Elasticsearch.

La tarification d'Elasticsearch Serverless est basée sur l'utilisation : vous ne payez que pour les ressources d'ingestion et de recherche que vous consommez. Grâce à un matériel plus récent et plus rapide, vos charges de travail s'exécuteront souvent avec moins de ressources, ce qui se traduit par une réduction des coûts pour la plupart des projets. Vous bénéficiez ainsi de performances optimales sans le surcoût : l'efficacité par excellence.

Qu'est-ce que cela signifie pour vous, le développeur ?

Cette mise à niveau de l'infrastructure est entièrement gérée par Elastic ; vous n'avez donc rien à faire, aucune migration ni modification de configuration. L'amélioration est immédiate et automatique pour tous vos projets sans serveur sur AWS.

Cette mise à niveau vous permet de :

• Créez des applications plus rapides : concentrez-vous sur la vélocité des fonctionnalités, en sachant que votre plateforme de recherche sous-jacente offre la vitesse exigée par vos utilisateurs.
• Innovez en confiance : déployez de nouvelles fonctionnalités de recherche, d'observabilité et de sécurité, y compris des capacités d'IA complexes telles que la recherche vectorielle et le classement par pertinence, sachant que la plateforme peut gérer la charge à des performances optimales.
• Simplifiez votre stack : utilisez un service entièrement géré qui prend en charge l'infrastructure, la planification de la capacité et le scaling, et concentrez‑vous sur votre code et vos données.
  

Conditions

• NodeJS version 18 ou plus récente
• Clé API OpenAI
• Déploiement Elasticsearch 8.x+

Pourquoi utiliser LangGraph pour des systèmes HITL en production

Dans un article précédent, nous avons présenté LangGraph et ses avantages pour construire un système RAG à l’aide de LLM et d’arêtes conditionnelles permettant de prendre automatiquement des décisions et d’afficher les résultats. Parfois, on ne souhaite pas que le système fonctionne de manière totalement autonome : on préfère que les utilisateurs puissent faire des choix et prendre des décisions dans la boucle d’exécution. C’est ce qu’on appelle la « supervision humaine ».

Supervision humaine ou humain dans la boucle

Il s’agit d’un concept d’IA qui permet à une personne réelle d’interagir avec des systèmes d’IA pour enrichir le contexte, évaluer ou modifier les réponses, demander des précisions, etc. Ce mécanisme est particulièrement utile dans des contextes à faible tolérance à l’erreur, comme la conformité, la prise de décision ou la génération de contenu, car il renforce la fiabilité des résultats produits par les modèles de langage (LLM).

Un exemple courant est celui d’un assistant de développement qui demande votre autorisation avant d’exécuter une commande dans le terminal, ou vous présente son raisonnement pas à pas avant de commencer à coder.

Elasticsearch + LangGraph : Comment ils interagissent

LangChain permet d’utiliser Elasticsearch comme magasin vectoriel et d’effectuer des requêtes dans des applications LangGraph – ce qui est particulièrement utile pour exécuter des recherches en texte intégral ou sémantiques –, tandis que LangGraph permet de définir le workflow, les outils et les interactions spécifiques. Cette architecture ajoute également la supervision humaine en tant que couche d’interaction supplémentaire avec l’utilisateur.

Mise en pratique : supervision humaine dans la boucle

Prenons l’exemple d’un avocat qui se pose une question sur une affaire qu’il vient d’accepter. Sans les bons outils, il devrait parcourir manuellement les textes juridiques et les précédents, les lire en intégralité, puis interpréter leur pertinence par rapport à son cas. Avec LangGraph et Elasticsearch, on peut créer un système capable d’interroger une base de données de précédents juridiques et de produire une analyse adaptée au cas en intégrant les détails et le contexte fournis par l’avocat.

Le workflow démarre lorsque l’avocat soumet une question juridique. Le système effectue une recherche vectorielle dans Elasticsearch, identifie les précédents les plus pertinents et les présente à l’avocat sous forme de texte en langage naturel. Une fois les documents sélectionnés, le modèle de langage génère une première analyse et vérifie si les informations sont complètes. À ce stade, deux chemins sont possibles : si tout est clair, le système génère directement une analyse finale ; sinon, il interrompt le processus pour demander des précisions à l’avocat. Une fois les informations manquantes ajoutées, le système complète l’analyse en tenant compte des précisions apportées.

Voici un graphique généré par LangGraph qui illustre le fonctionnement de l’application une fois finalisée. Chaque nœud représente un outil ou une fonctionnalité :

Ensemble de données

Voici l’ensemble de données utilisé dans cet exemple. Cet ensemble de données regroupe plusieurs précédents juridiques, chacun décrivant un cas de retard de service, les motifs invoqués par la cour et la décision finale.

[
  {
    "pageContent": "Legal precedent: Case B - Service delay not considered breach. A consulting contract used term 'timely delivery' without specific dates. A three-week delay occurred but contract lacked explicit schedule. Court ruled no breach as parties had not defined concrete timeline and delay did not cause demonstrable harm.",
    "metadata": {
      "caseId": "CASE-B-2022",
      "contractType": "consulting agreement",
      "delayPeriod": "three weeks",
      "outcome": "no breach found",
      "reasoning": "no explicit deadline defined, no demonstrable harm",
      "keyTerms": "timely delivery, open terms, schedule definition",
      "title": "Case B: Delay Without Explicit Schedule"
    }
  },
  ...
]

Ingestion et configuration de l'index

La configuration de l’index et la logique d’ingestion des données sont définies dans le fichier dataIngestion.ts, dans lequel on déclare les fonctions de création de l’index. Cette configuration est compatible avec l’interface de magasin vectoriel LangChain pour Elasticsearch.

Remarque : la configuration du mapping est également incluse dans le fichier dataIngestion.ts.

Installation des packages et configuration des variables d’environnement

Initialisons un projet Node.js avec les paramètres par défaut :

• @elastic/elasticsearch : client Elasticsearch pour Node.js Utilisé pour se connecter, créer des index et exécuter des requêtes.
• @langchain/community : propose des intégrations avec des outils soutenus par la communauté, y compris le magasin ElasticVectorSearch.
• @langchain/core : composants de base de LangChain, tels que les chaînes, prompts et utilitaires.
• @langchain/langgraph : permet l’orchestration basée sur des graphes, avec des workflows reposant sur des nœuds, des arêtes et une gestion d’état.
• @langchain/openai : fournit un accès aux modèles OpenAI (LLM et embeddings) via LangChain.
• dotenv : charge les variables d’environnement à partir d’un fichier .env dans process.env. fichier dans process.env.
• tsx : outil pratique pour exécuter du code TypeScript.

Exécutez la commande suivante dans la console pour les installer tous :

npm install @elastic/elasticsearch @langchain/community @langchain/core @langchain/langgraph @langchain/openai dotenv --legacy-peer-deps && npm install --save-dev tsx

Créez un fichier .env pour configurer les variables d’environnement :

ELASTICSEARCH_ENDPOINT=
ELASTICSEARCH_API_KEY=
OPENAI_API_KEY=

Nous utiliserons TypeScript pour écrire le code, car il offre une meilleure sécurité de typage et une expérience développeur plus fiable. Créez un fichier TypeScript nommé main.ts et insérez-y le code présenté dans la section suivante.

Importation des packages

Dans le fichier main.ts, nous commençons par importer les modules nécessaires et initialiser la configuration des variables d’environnement. Cela inclut les composants essentiels de LangGraph, les intégrations de modèles OpenAI et le client Elasticsearch.

Nous importons également les éléments suivants depuis le fichier dataIngestion.ts :

• ingestData : fonction qui crée l’index et ingère les données.
• Document et DocumentMetadata : interfaces définissant la structure des documents de l’ensemble de données.

Client du magasin vectoriel Elasticsearch, client d’embeddings et client OpenAI

Ce code initialise le magasin vectoriel, le client d’embeddings et un client OpenAI.

const VECTOR_INDEX = "legal-precedents";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const esClient = new Client({
  node: process.env.ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: process.env.ELASTICSEARCH_API_KEY ?? "",
  },
});

const vectorStore = new ElasticVectorSearch(embeddings, {
  client: esClient,
  indexName: VECTOR_INDEX,
});

Le schéma d’état du workflow applicatif facilite la communication entre les nœuds :

const LegalResearchState = Annotation.Root({
  query: Annotation(),
  analyzedConcepts: Annotation(),
  precedents: Annotation(),
  selectedPrecedent: Annotation(),
  draftAnalysis: Annotation(),
  ambiguityDetected: Annotation(),
  userClarification: Annotation(),
  finalAnalysis: Annotation(),
});

L’objet d’état fera transiter, via les nœuds, la requête de l’utilisateur, les concepts extraits, les précédents juridiques identifiés et les éventuelles zones d’ambiguïté. Il conserve également une trace du précédent choisi par l’utilisateur, de l’analyse préliminaire générée en cours de route et de l’analyse finale, une fois toutes les clarifications apportées.

Nœuds

searchPrecedents : ce nœud effectue une recherche de similarité dans le magasin vectoriel d’Elasticsearch, en se basant sur les données saisies par l’utilisateur. Il récupère jusqu’à 5 documents pertinents et les affiche afin qu’ils puissent être examinés par l’utilisateur.

async function searchPrecedents(state: typeof LegalResearchState.State) {
  console.log(
    "📚 Searching for relevant legal precedents with query:\n",
    state.query
  );

  const results = await vectorStore.similaritySearch(state.query, 5);
  const precedents = results.map((d) => d as Document);

  console.log(`Found ${precedents.length} relevant precedents:\n`);

  for (let i = 0; i < precedents.length; i++) {
    const p = precedents[i];
    const m = p.metadata;
    console.log(
      `${i + 1}. ${m.title} (${m.caseId})\n` +
        `   Type: ${m.contractType}\n` +
        `   Outcome: ${m.outcome}\n` +
        `   Key reasoning: ${m.reasoning}\n` +
        `   Delay period: ${m.delayPeriod}\n`
    );
  }

  return { precedents };
}

precedentSelection : ce nœud permet à l’utilisateur de sélectionner, en langage naturel, le cas d’usage correspondant le mieux à sa requête parmi ceux trouvés par la recherche par similarité. À ce stade, l’application interrompt le workflow et attend une entrée utilisateur.

function precedentSelection(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #1: Human input needed\n");
  const question = "👨‍⚖️  Which precedent is most similar to your case? ";
  const userChoice = interrupt({ question });

  return { userChoice };
}

selectPrécédent : ce nœud transmet la saisie de l’utilisateur ainsi que les documents récupérés, afin d’en interpréter le contenu et d’en sélectionner un. Le LLM accomplit cette tâche en renvoyant un numéro correspondant au document qu’il estime le plus pertinent à partir de la saisie en langage naturel.

async function selectPrecedent(state: typeof LegalResearchState.State) {
  const precedents = state.precedents || [];
  const userInput = (state as any).userChoice || "";

  const precedentsList = precedents
    .map((p, i) => {
      const m = p.metadata;
      return `${i + 1}. ${m.caseId}: ${m.title} - ${m.outcome}`;
    })
    .join("\n");

  const structuredLlm = llm.withStructuredOutput({
    name: "precedent_selection",
    schema: {
      type: "object",
      properties: {
        selected_number: {
          type: "number",
          description:
            "The precedent number selected by the lawyer (1-based index)",
          minimum: 1,
          maximum: precedents.length,
        },
      },
      required: ["selected_number"],
    },
  });

  const prompt = `
    The lawyer said: "${userInput}"

    Available precedents:
    ${precedentsList}

    Which precedent number (1-${precedents.length}) matches their selection?
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are an assistant that interprets lawyer's selection and returns the corresponding precedent number.",
    },
    { role: "user", content: prompt },
  ]);

  const selectedIndex = response.selected_number - 1;
  const selectedPrecedent = precedents[selectedIndex] || precedents[0];

  console.log(`✅ Selected: ${selectedPrecedent.metadata.title}\n`);
  return { selectedPrecedent };
}

createDraft : ce nœud génère une première analyse juridique à partir du précédent choisi par l’utilisateur Le modèle LLM évalue dans quelle mesure le précédent s’applique à la question posée par l’avocat et détermine si les informations disponibles sont suffisantes pour continuer.

Si le précédent est directement applicable, le nœud produit une analyse préliminaire et, en suivant la branche de droite, passe au nœud final. Si le LLM détecte des ambiguïtés – termes contractuels non définis, détails temporels manquants ou conditions floues –, il signale qu’une clarification est nécessaire et fournit la liste des informations à compléter. Dans ce cas, l’ambiguïté déclenche la branche gauche du graphe.

async function createDraft(state: typeof LegalResearchState.State) {
  console.log("📝 Drafting initial legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { draftAnalysis: "" };

  const m = precedent.metadata;

  const structuredLlm = llm.withStructuredOutput({
    name: "draft_analysis",
    schema: {
      type: "object",
      properties: {
        needs_clarification: {
          type: "boolean",
          description:
            "Whether the analysis requires clarification about contract terms or context",
        },
        analysis_text: {
          type: "string",
          description: "The draft legal analysis or the ambiguity explanation",
        },
        missing_information: {
          type: "array",
          items: { type: "string" },
          description:
            "List of specific information needed if clarification is required (empty if no clarification needed)",
        },
      },
      required: ["needs_clarification", "analysis_text", "missing_information"],
    },
  });

  const prompt = `
    Based on this precedent:
    Case: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    Key terms: ${m.keyTerms}

    And the lawyer's question: "${state.query}"

    Draft a legal analysis applying this precedent to the question.
    
    If you need more context about the specific contract terms, timeline details, 
    or other critical information to provide accurate analysis, set needs_clarification 
    to true and list what information is missing.
    
    Otherwise, provide the legal analysis directly.
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant that analyzes cases and identifies when additional context is needed.",
    },
    { role: "user", content: prompt },
  ]);

  let displayText: string;
  if (response.needs_clarification) {
    const missingInfoList = response.missing_information
      .map((info: string, i: number) => `${i + 1}. ${info}`)
      .join("\n");
    displayText = `AMBIGUITY DETECTED:\n${response.analysis_text}\n\nMissing information:\n${missingInfoList}`;
  } else {
    displayText = `ANALYSIS:\n${response.analysis_text}`;
  }

  console.log(displayText + "\n");

  return {
    draftAnalysis: displayText,
    ambiguityDetected: response.needs_clarification,
  };
}

Voici les deux chemins que le graphe peut suivre :

La branche gauche comprend un nœud supplémentaire chargé de gérer la clarification.

requestClarification : ce nœud active la seconde étape de supervision humaine lorsque le système estime que l’analyse préliminaire manque de contexte essentiel. Le workflow est interrompu et l’utilisateur est invité à préciser les éléments contractuels manquants détectés par le nœud précédent.

function requestClarification(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #2: Additional context needed\n");
  const userClarification = interrupt({
    question: "👨‍⚖️  Please provide clarification about your contract terms:",
  });
  return { userClarification };
}

generateFinalAnalysis : ce nœud génère l’analyse juridique finale en combinant le précédent sélectionné avec les informations supplémentaires fournies par l’utilisateur, si nécessaire. Grâce aux clarifications obtenues lors de l’étape précédente de supervision humaine, le LLM synthétise le raisonnement juridique, les éléments contractuels fournis par l’utilisateur et les conditions permettant d’établir s’il y a eu violation.

Le nœud final fournit une analyse complète, intégrant l’interprétation juridique et des recommandations concrètes.

async function generateFinalAnalysis(state: typeof LegalResearchState.State) {
  console.log("📋 Generating final legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { finalAnalysis: "" };

  const m = precedent.metadata;

  const prompt = `
    Original question: "${state.query}"
    
    Selected precedent: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    
    Lawyer's clarification: "${state.userClarification}"
    
    Provide a comprehensive legal analysis integrating:
    1. The selected precedent's reasoning
    2. The lawyer's specific contract context
    3. Conditions for breach vs. no breach
    4. Practical recommendations
  `;

  const response = await llm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant providing comprehensive analysis.",
    },
    { role: "user", content: prompt },
  ]);

  const finalAnalysis = response.content as string;

  console.log(
    "\n" +
      "=".repeat(80) +
      "\n" +
      "⚖️  FINAL LEGAL ANALYSIS\n" +
      "=".repeat(80) +
      "\n\n" +
      finalAnalysis +
      "\n\n" +
      "=".repeat(80) +
      "\n"
  );

  return { finalAnalysis };
}

Construction du graphe :

const workflow = new StateGraph(LegalResearchState)
  .addNode("analyzeQuery", analyzeQuery)
  .addNode("searchPrecedents", searchPrecedents)
  .addNode("precedentSelection", precedentSelection)
  .addNode("selectPrecedent", selectPrecedent)
  .addNode("createDraft", createDraft)
  .addNode("requestClarification", requestClarification)
  .addNode("generateFinalAnalysis", generateFinalAnalysis)
  .addEdge("__start__", "analyzeQuery")
  .addEdge("analyzeQuery", "searchPrecedents")
  .addEdge("searchPrecedents", "precedentSelection") // HITL #1
  .addEdge("precedentSelection", "selectPrecedent")
  .addEdge("selectPrecedent", "createDraft")
  .addConditionalEdges(
    "createDraft",
    (state: typeof LegalResearchState.State) => {
      // If ambiguity detected, request clarification (HITL #2)
      if (state.ambiguityDetected) return "needsClarification";
      // Otherwise, generate final analysis
      return "final";
    },
    {
      needsClarification: "requestClarification",
      final: "generateFinalAnalysis",
    }
  )
  .addEdge("requestClarification", "generateFinalAnalysis") // HITL #2
  .addEdge("generateFinalAnalysis", "__end__");

Dans le graphe, on observe que l’arête conditionnelle définit le critère permettant de choisir la branche « finale ». Comme on le voit, la décision repose désormais sur la détection ou non d’ambiguïtés dans l’analyse préliminaire, nécessitant des clarifications supplémentaires.

Mise en œuvre de l’ensemble :

await ingestData();

// Compile workflow
const app = workflow.compile({ checkpointer: new MemorySaver() });
const config = { configurable: { thread_id: "hitl-circular-thread" } };

await saveGraphImage(app);

// Execute workflow
const legalQuestion =
    "Does a pattern of repeated delays constitute breach even if each individual delay is minor?"; 

console.log(`⚖️  LEGAL QUESTION: "${legalQuestion}"\n`);

let currentState = await app.invoke({ query: legalQuestion }, config);

// Handle all interruptions in a loop
while ((currentState as any).__interrupt__?.length > 0) {
  console.log("\n💭 APPLICATION PAUSED WAITING FOR USER INPUT...");

  const interruptQuestion = (currentState as any).__interrupt__[0]?.value
    ?.question;
  const userChoice = await getUserInput(
    interruptQuestion || "👤 YOUR CHOICE: "
  );

  currentState = await app.invoke(
    new Command({ resume: userChoice }),
    config
  );
}

Exécutez le script :

Tout étant prêt, exécutez le fichier main.ts en saisissant la commande suivante dans le terminal :

tsx main.ts

Une fois le script lancé, la question « Une série de retards répétés constitue-t-elle une violation, même si chaque retard est mineur ? » est envoyée à Elasticsearch pour une recherche par similarité. Les résultats extraits de l’index s’affichent ensuite. L’application détecte que plusieurs précédents juridiques pertinents correspondent à la requête. Elle suspend donc l’exécution et sollicite l’utilisateur pour identifier le précédent le plus approprié :

📚 Searching for relevant legal precedents with query:
 Does a pattern of repeated delays constitute breach even if each individual delay is minor?
Found 5 relevant precedents:

1. Case H: Pattern of Repeated Delays (CASE-H-2021)
   Type: ongoing service agreement
   Outcome: breach found
   Key reasoning: pattern demonstrated failure to perform, cumulative effect
   Delay period: multiple instances

2. Case E: Minor Delay Quality Maintained (CASE-E-2022)
   Type: service agreement
   Outcome: minor breach only
   Key reasoning: delay minimal, quality maintained, termination unjustified
   Delay period: five days

3. Case A: Delay Breach with Operational Impact (CASE-A-2023)
   Type: service agreement
   Outcome: breach found
   Key reasoning: delay affected operations and caused financial harm
   Delay period: two weeks

4. Case B: Delay Without Explicit Schedule (CASE-B-2022)
   Type: consulting agreement
   Outcome: no breach found
   Key reasoning: no explicit deadline defined, no demonstrable harm
   Delay period: three weeks

5. Case C: Justified Delay External Factors (CASE-C-2023)
   Type: construction service
   Outcome: no breach found
   Key reasoning: external factors beyond control, force majeure applied
   Delay period: one month

⚖️  HITL #1: Human input needed

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? 

Ce qui rend cette application intéressante, c’est qu’il est possible d’utiliser le langage naturel pour faire un choix, le LLM interprétant l’entrée utilisateur pour identifier la bonne option. Voyons ce qui se passe si l’on saisit « Case H »

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? Case H

✅ Selected: Case H: Pattern of Repeated Delays

📝 Drafting initial legal analysis...

AMBIGUITY DETECTED:
Based on Case H, a pattern of repeated delays can indeed constitute a breach of contract, even if each individual delay is minor. The outcome in Case H indicates that the cumulative effect of these minor delays led to a significant failure to perform the contractual obligations adequately. The reasoning emphasizes that consistent performance is critical in fulfilling the terms of a contract. Therefore, if the repeated delays create a situation where the overall performance is hindered, this pattern could be interpreted as a breach. However, the interpretation may depend on the specific terms of the contract at issue, as well as the expectations of performance set forth in that contract.

Missing information:
1. Specific contract terms regarding performance timelines
2. Details on the individual delays (duration, frequency)
3. Context on consequences of delays stated in the contract
4. Other parties' expectations or agreements related to performance


⚖️  HITL #2: Additional context needed


💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms:

Le modèle intègre les précisions fournies par l’utilisateur dans le workflow, puis poursuit avec l’analyse finale dès que le contexte est jugé suffisant. À ce stade, le système exploite également l’ambiguïté identifiée plus tôt : l’analyse préliminaire avait révélé des éléments contractuels manquants, susceptibles d’influencer l’interprétation juridique. Ces éléments « manquants » guident le modèle pour identifier les clarifications indispensables à lever les incertitudes et formuler une analyse finale fiable.

L’utilisateur doit fournir les précisions demandées dans la saisie suivante. Essayons avec : « Le contrat exige une “livraison rapide” sans calendrier. Huit retards de 2 à 4 jours sur six mois. 50 000 $ de pertes dues à trois délais clients non respectés. Le fournisseur a été prévenu, mais le schéma s’est répété. »

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms: Contract requires "prompt delivery" without timelines. 8 delays of 2-4 days over 6 months. $50K in losses from 3 missed client deadlines. Vendor notified but pattern continued.

📋 Generating final legal analysis...

================================================================================
⚖️  FINAL LEGAL ANALYSIS
================================================================================

To analyze the question of whether a pattern of repeated minor delays constitutes a breach of contract, we need to combine insights from the selected precedent, the specifics of the lawyer's contract situation, conditions that typically govern breach versus non-breach, and practical recommendations for the lawyer moving forward.

### 1. Selected Precedent's Reasoning

The precedent case, referred to as Case H, found that a pattern of repeated delays amounted to a breach of contract. The court reasoned that even minor individual delays, when considered cumulatively, demonstrated a failure to perform as stipulated in the contract. The underlying rationale was that the cumulative effect of these minor delays could significantly undermine the purpose of the contract, which typically aims for timely performance and reliable delivery.

### 2. Lawyer's Specific Contract Context

In the lawyer's situation, the contract specified "prompt delivery" but did not provide a strict timeline. The vendor experienced 8 delays ranging from 2 to 4 days over a period of 6 months. These delays culminated in $50,000 in losses due to three missed client deadlines. The vendor was notified regarding these delays; however, the pattern of delays persisted.

Key considerations include:
- **Nature of the Obligations**: While “prompt delivery” does not define a strict timeline, it does imply an expectation for timely performance.
- **Material Impact**: The missed client deadlines indicate that these delays had a material adverse effect on the lawyer's ability to fulfill contractual obligations to third parties, likely triggering damages.

### 3. Conditions for Breach vs. No Breach

**Conditions for Breach**:
- **Pattern and Cumulative Effect**: Similar to the reasoning in Case H, evidence of a habitual pattern of delays can amount to a breach. Even if individual delays are minor, when combined, they may show a lack of diligence or reliability by the vendor.
- **Materiality**: The impact of these delays is crucial. If the cumulative delays adversely affect the contract's purpose or cause significant losses, this reinforces the case for a breach.
- **Notification and Opportunity to Cure**: The fact that the vendor was notified of the delays and failed to rectify the behavior can often be interpreted as a further indication of breach.

**Conditions for No Breach**:
- **Non-Material Delays**: If the delays did not affect the overall contractual performance or client obligations, this may lessen the likelihood of establishing a breach. However, given the risks and losses involved, this seems less relevant in this scenario.
- **Force Majeure or Justifiable Delays**: If the vendor could show that these delays were due to justify circumstances not within their control, it may potentially provide a defense against breach claims.

### 4. Practical Recommendations

1. **Assess Damages**: Document the exact nature of the financial losses incurred due to the missed deadlines to substantiate claims of damages.
  
2. **Gather Evidence**: Collect all communication regarding the delays, including any notifications sent to the vendor about the issues.

3. **Consider Breach of Contract Action**: Based on the precedent and accumulated delays, consider formalized communication to the vendor regarding a breach of contract claim, highlighting both the pattern and the impact of these repeated delays.

4. **Evaluate Remedies**: Depending upon the contract specifics, the lawyer may wish to pursue several remedies, including:
   - **Compensatory Damages**: For the financial losses due to missed deadlines.
   - **Specific Performance**: If timely delivery is critical and can still be enforced.
   - **Contract Termination**: Depending on the severity, terminating the contract and seeking replacements may be warranted.

5. **Negotiate Terms**: If continuing to work with the current vendor is strategic, the lawyer should consider renegotiating terms for performance guarantees or penalties for further delays.

6. **Future Contracts**: In future contracts, consider including explicit timelines and conditions for prompt delivery, as well as specified damages for delays to better safeguard against this issue.

By integrating the legal principles from the precedent with the specific context and conditions outlined, the lawyer can formulate a solid plan to address the repeated delays by the vendor effectively.

Ce résultat correspond à la dernière étape du workflow : le modèle y intègre le précédent sélectionné (Case H) ainsi que les précisions de l’avocat pour produire une analyse juridique complète. Le système explique pourquoi le schéma de retards observé constitue vraisemblablement une violation, identifie les facteurs à l’appui de cette interprétation et propose des recommandations concrètes. Au final, le résultat montre comment les clarifications liées à la supervision humaine permettent de lever les ambiguïtés et de générer une analyse juridique contextualisée et solide.

Autres cas d’usage concrets

Ce type d’application, reposant sur Elasticsearch, LangGraph et la supervision humaine, peut également être utile dans d’autres types d’applications, comme :

• Examen préalable des appels d’outils avant leur exécution : par exemple, en finance, une personne valide les ordres d’achat/vente avant leur passage.
• Ajout de paramètres complémentaires si nécessaire : par exemple, dans le tri des tickets en support client, où un agent humain choisit la bonne catégorie de problème lorsque l’IA propose plusieurs interprétations possibles.

Et de nombreux cas d’usage restent à explorer, dans lesquels la supervision humaine pourrait véritablement changer la donne.

Conclusion

Avec LangGraph et Elasticsearch, il est possible de créer des agents capables de prendre des décisions de manière autonome et de suivre un workflow linéaire, ou d’adapter leur cheminement selon certaines conditions. Avec la supervision humaine, les agents peuvent faire intervenir l’utilisateur dans le processus de décision pour combler les lacunes contextuelles et valider les choix dans des systèmes où la tolérance aux erreurs est critique.

L’un des atouts de cette approche, c’est qu’elle permet de filtrer un vaste ensemble de données via Elasticsearch, puis d’utiliser un LLM pour extraire un seul document correspondant à la sélection de l’utilisateur. Cette dernière étape serait bien plus complexe avec Elasticsearch seul, car un humain peut exprimer une même intention de recherche de multiples façons en langage naturel.

Cette approche rend le système plus rapide et économe en jetons, car seul le strict nécessaire est transmis au LLM pour prendre la décision finale, et non l’ensemble du jeu de données. Dans le même temps, cette approche reste très efficace pour détecter l’intention de l’utilisateur et affiner les itérations jusqu’à obtenir l’option souhaitée.

Notre objectif était de passer à une approche automatisée et adaptative capable de gérer à la fois l’analyse des logs (extraction de champs) et le partitionnement des logs (identification de la source). Nous avons émis l’hypothèse que les grands modèles de langage (LLM), grâce à leur compréhension inhérente de la syntaxe du code et des modèles sémantiques, pourraient automatiser ces tâches avec une intervention humaine minimale.

Nous sommes heureux d'annoncer que cette fonctionnalité est déjà disponible dans Streams.

Description de l'ensemble de données

Nous avons choisi une Loghub collection de logs à des fins de PoC. Pour notre enquête, nous avons sélectionné des échantillons représentatifs issus des domaines clés suivants :

• Systèmes distribués : nous avons utilisé le HDFS (Hadoop Distributed File System) et les ensembles de données Spark. Ils contiennent un mélange de messages d'information, de débogage et d'erreur typiques des plateformes de big data.
• Applications serveur et web : les logs des serveurs web Apache et d’OpenSSH ont constitué une source précieuse d’informations sur les accès, les erreurs et les événements liés à la security. Ces éléments sont essentiels pour surveiller le trafic web et détecter les menaces potentielles.
• Systèmes d'exploitation : nous avons inclus les logs de Linux et Windows. Ces ensembles de données représentent les événements communs et semi-structurés au niveau du système auxquels les équipes d’opérations sont confrontés quotidiennement.
• Systèmes mobiles : pour garantir que notre modèle puisse gérer les logs provenant d'environnements mobiles, nous avons inclus l'ensemble de données Android. Ces logs sont souvent volumineux et capturent un large éventail d'activités au niveau de l'application et du système sur les appareils mobiles.
• Superordinateurs : pour tester les performances sur des environnements de calcul haute performance (HPC), nous avons intégré l'ensemble de données BGL (Blue Gene/L), qui présente des logs très structurés avec une terminologie de domaine spécifique.

L'un des principaux avantages de la collection Loghub est que les logs sont en grande partie non nettoyés et non étiquetés, reflétant un environnement de production en direct bruyant avec une architecture de microservices.

Exemples de logs :

[Sun Dec 04 20:34:21 2005] [notice] jk2_init() Found child 2008 in scoreboard slot 6
[Sun Dec 04 20:34:25 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
[Mon Dec 05 11:06:51 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
17/06/09 20:10:58 INFO output.FileOutputCommitter: Saved output of task 'attempt_201706092018_0024_m_000083_1138' to hdfs://10.10.34.11:9000/pjhe/test/1/_temporary/0/task_201706092018_0024_m_000083
17/06/09 20:10:58 INFO mapred.SparkHadoopMapRedUtil: attempt_201706092018_0024_m_000083_1138: Committed

De plus, nous avons créé un cluster Kubernetes avec une application web typique et une base de données pour extraire des logs supplémentaires dans le domaine le plus courant.

Exemple de champs de log communs : horodatage, niveau de log (INFO, AVERTISSEMENT, ERREUR), source, message.

Analyse de logs en few-shot avec un LLM

Notre premier ensemble d'expériences s'est concentré sur une question fondamentale : Un LLM peut-il identifier de manière fiable les champs clés et générer des règles de parsing cohérentes pour les extraire ?

Nous avons demandé à un modèle d'analyser des échantillons de journaux bruts et de générer des règles d'analyse de journaux sous forme d'expressions régulières (regex) et de formats Grok. Nos résultats ont montré que cette approche présente beaucoup de potentiel, mais aussi des défis importants dans sa mise en œuvre.

Confiance élevée et conscience du contexte

Les premiers résultats étaient prometteurs. Le LLM a démontré une forte capacité à générer des règles d'analyse qui correspondaient aux exemples fournis avec une grande confiance. Outre la simple correspondance de modèles, le modèle a démontré une capacité de compréhension des logs — il pouvait identifier et nommer correctement la source du log (par exemple, application de suivi de santé, application web Nginx, base de données Mongo).

Le dilemme des échantillons d'entrée « Boucles d'or »

Nos expériences ont rapidement mis en évidence un manque important de robustesse en raison d'une sensibilité extrême à l'échantillon d'entrée. Les performances du modèle fluctuent considérablement en fonction des exemples de logs spécifiques inclus dans l'invite. Nous avons observé un problème de similitude des logs, dans lequel l'échantillon de log devait inclure juste assez de logs diversifiés  :

• Trop homogène (surapprentissage) : si les logs d'entrée sont trop similaires, le LLM a tendance à surspécifier. Il traite les données variables — telles que des noms spécifiques de classes Java dans une trace de pile — comme des parties statiques du modèle. Il en résulte des règles fragiles qui ne couvrent qu'une infime partie des logs et extraient des champs inutilisables.
• Trop hétérogène (confusion) : à l'inverse, si l'échantillon contient une variance de formatage significative, ou pire, des « logs poubelles » comme des barres de progression, des tableaux de mémoire ou de l'art ASCII, le modèle peine à trouver un dénominateur commun. Il en vient souvent à générer des regex complexes et cassés ou à généraliser paresseusement toute la ligne en un seul champ de bloc de message.

La contrainte de la fenêtre contextuelle

Nous avons également rencontré un goulot d'étranglement au niveau de la fenêtre contextuelle. Lorsque les logs d'entrée étaient longs, hétérogènes, ou riches en champs extractibles, la sortie du modèle se détériorait souvent, devenant « désordonnée » ou trop longue pour s'intégrer dans la fenêtre de contexte de sortie. Bien entendu, le découpage aide dans ce cas. En divisant les logs à l'aide de délimiteurs basés sur les caractères et sur les entités, nous pourrions aider le modèle à se concentrer sur l'extraction des champs principaux sans être submergé par le bruit.

L'écart de cohérence et de standardisation

Même lorsque le modèle a généré des règles avec succès, nous avons noté de légères incohérences :

• Variantes de dénomination des services : le modèle propose différents noms pour une même entité (par exemple, en étiquetant la source « Spark », « Apache Spark » et « Spark Log Analytics » dans différentes exécutions).
• Variations dans la dénomination des champs : les noms des champs n'étaient pas normalisés (par exemple, id vs. service.id vs. device.id). Nous avons normalisé les noms en utilisant une nomenclature de champ Elastic standardisée.
• Variance de résolution : la résolution de l'extraction de champ variait en fonction de la similarité des logs d'entrée les uns avec les autres.

Empreinte de format de log

Pour relever le défi de la similarité des logs, nous introduisons une heuristique haute performance : l'empreinte de format de log (LFF).

Au lieu d'introduire des logs bruts et bruyants directement dans un LLM, nous appliquons d'abord une transformation déterministe pour révéler la structure sous-jacente de chaque message. Cette étape de pré-traitement rend abstraites les données variables, générant une « empreinte » simplifiée qui nous permet de regrouper les logs connexes.

La logique de mapping est simple pour garantir la vitesse et la cohérence :

1. Abstraction des chiffres : toute séquence de chiffres (0-9) est remplacée par un simple ‘0’.
2. Abstraction du texte : toute séquence de caractères alphabétiques avec des espaces blancs est remplacée par un seul « a ».
3. Normalisation des espaces blancs : toutes les séquences d'espaces blancs (espaces, tabulations, nouvelles lignes) sont regroupées en un seul espace.
4. La préservation des symboles : la ponctuation et les caractères spéciaux (par exemple, :, [, ], /) sont préservés, car ils sont souvent les indicateurs les plus forts de la structure des logs.

Nous introduisons l'approche de mapping des logs. Les modèles de mapping de base comprennent les éléments suivants :

• Chiffres 0 à 9, quelle que soit leur longueur, de > à « 0 ».
• Texte (caractères alphabétiques avec espaces) de n'importe quelle longueur -> à 'a'.
• Espaces blancs, onglets et nouvelles lignes : > pour un seul espace.

Examinons un exemple de la manière dont ce mapping nous permet de transformer les logs.

Par conséquent, nous obtenons les masques de log suivants :

Remarquez les empreintes digitales des deux premiers logs. Malgré des horodatages, des classes de sources et un contenu de message différents, leurs préfixes (0/0/0 0:0:0 a a.a:) sont identiques. Cet alignement structurel nous permet de regrouper automatiquement ces logs dans le même cluster.

Le troisième log, cependant, produit une empreinte digitale complètement divergente (0-0-0...). Cela nous permet de le séparer algorithmiquement du premier groupe avant même d' invoquer un LLM.

Partie bonus : implémentation instantanée avec ES|QL

C'est aussi simple que de passer cette requête dans Discover.

FROM loghub |
EVAL pattern = REPLACE(REPLACE(REPLACE(REPLACE(raw_message, "[ \t\n]+", " "), "[A-Za-z]+", "a"), "[0-9]+", "0"), "a( a)+", "a") |
STATS total_count = COUNT(), ratio = COUNT() / 2000.0, datasources=VALUES(filename), example=TOP(raw_message, 3, "desc") BY SUBSTRING(pattern, 0, 15) |
SORT total_count DESC |
LIMIT 100

Décomposition de la requête :

FROM loghub : cible notre index contenant les données de journal brut.

EVAL pattern = ... : la logique du mapping de base. Nous enchaînons les fonctions REPLACE pour effectuer l'abstraction (par exemple, les chiffres en '0', le texte en 'a', etc.) et enregistrons le résultat dans un champ "pattern".

STATS [column1 =] expression1, … BY SUBSTRING(pattern, 0, 15) :

Ceci est une étape du clustering. Nous regroupons les logs qui partagent les 15 premiers caractères de leur schéma et créons des champs agrégés tels que le nombre total de logs par groupe, la liste des sources de données des logs, le préfixe du schéma, 3 exemples de logs

SORT total_count DESC | LIMIT 100 : affiche les 100 schémas de log les plus fréquents

Les résultats de la requête sur LogHub sont affichés ci-dessous :

Comme démontré dans la visualisation, cette approche « sans LLM » partitionne les logs avec une grande précision. Elle a réussi à clusterer complètement 10 sources de données sur 16 (basées sur les étiquettes LogHub) (>90 %) et a atteint un clustering majoritaire dans 13 sources sur 16 (>60 %) — le tout sans nécessiter de nettoyage, de prétraitement ou de réglage fin supplémentaire.

L'empreinte digitale du format du log offre une alternative pragmatique et à fort impact, ainsi qu'un complément aux solutions de ML sophistiquées telles que l'analyse du modèle de log. Il offre des informations immédiates sur les relations entre les logs et gère efficacement les grands ensembles de logs.

• Polyvalence en tant que primitif

Grâce à la mise en œuvre d'ES|QL, LFF sert à la fois d'outil autonome pour des diagnostics/visualisations rapides des données, et d'élément de base dans les pipelines d'analyse des journaux pour les cas d'utilisation à grand volume.

• Flexibilité

LFF est facile à personnaliser et à étendre pour capturer des modèles spécifiques, c'est-à-dire des nombres hexadécimaux et des adresses IP.

• Stabilité déterministe

Contrairement aux algorithmes de clustering basés sur le ML, la logique LFF est simple et déterministe. Les nouveaux logs entrants n'affectent pas rétroactivement les clusters de logs existants.

• Performance et mémoire

Il nécessite peu de mémoire, pas de formation ni de GPU, ce qui le rend idéal pour les environnements à haut débit et en temps réel.

Combiner une empreinte digitale au format log avec un LLM

Pour valider l'architecture hybride proposée, chaque expérience contenait un sous-ensemble aléatoire de 20 % des logs de chaque source de données. Cette contrainte simule un environnement de production réel où les logs sont traités par lots plutôt que comme un bloc monolithique de données historiques.

L’objectif était de démontrer que le LFF agit comme une couche de compression efficace. Nous avons cherché à prouver que des règles d’analyse à haute couverture pouvaient être générées à partir de petits échantillons sélectionnés et généralisées avec succès à l’ensemble de l’ensemble de données.

Pipeline d'exécution

Nous avons mis en œuvre un pipeline à plusieurs étapes qui filtre, regroupe et applique un échantillonnage stratifié aux données avant qu'elles n'atteignent le LLM.

1. clustering hiérarchique en deux étapes

• Sous-classes (correspondance exacte) : les logs sont agrégés par empreintes identiques. Tous les logs d'une sous-classe partagent exactement la même structure de format.
• Nettoyage des aberrations. Nous écartons toutes les sous-classes qui représentent moins de 5 % du volume total des logs. Cela garantit que le LLM se concentre sur le signal dominant et ne sera pas distrait par le bruit ou les logs malformés.
• Métaclasses (correspondance avec le préfixe) : les sous-classes restantes sont regroupées en métaclasses en fonction des N premiers caractères de l'empreinte digitale du format. Nous avons choisi N=5 pour le Log parsing et N=15 pour le Log partitioning lorsque les sources de données sont inconnues.

2. Échantillonnage stratifié. Une fois l'arbre hiérarchique établit, nous construisons l'échantillon de log pour le LLM. L'objectif stratégique est de maximiser la couverture de variance tout en minimisant l'utilisation des jetons.

• Nous sélectionnons des logs représentatifs de chaque sous-classe valide au sein de la métaclasse plus large.
• Pour gérer un cas limite de sous-classes trop nombreuses, nous appliquons un échantillonnage aléatoire pour s'adapter à la taille de la fenêtre cible.

3. Génération de règles Finally, nous demandons au LLM de générer une règle d'analyse regex qui convient à tous les logs dans l'échantillon fourni pour chaque Métaclasse. Pour notre PoC, nous avons utilisé le mini-modèle GPT-4o.

Résultats expérimentaux et observations

Nous avons atteint une précision de parsing de 94 % et une précision de partitionnement de 91 % sur l'ensemble de données Loghub.

La matrice de confusion ci-dessus illustre les résultats du partitionnement des logs. L’axe vertical représente les sources de données réelles, et l’axe horizontal représente les sources de données prédites. L'intensité de la carte thermique correspond au volume de logs, les vignettes plus claires indiquant un nombre plus élevé. L'alignement diagonal démontre la haute fidélité du modèle dans l'attribution des sources, avec un minimum de dispersion.

Nos informations sur les benchmarks de performance :

• Base optimale : une fenêtre contextuelle de 30 à 40 échantillons de logs par catégorie s'est avérée être le « point idéal », produisant régulièrement une analyse syntaxique robuste avec des motifs Regex et Grok.
• Minimisation de l'entrée : nous avons réduit la taille de l'entrée à 10 logs par catégorie pour les motifs Regex et n'avons observé qu'une baisse de 2 % des performances d'analyse, ce qui confirme que l'échantillonnage basé sur la diversité est plus critique que le volume brut.

Les modèles Jina se répartissent en trois grandes catégories, conçues pour faciliter le traitement, l’organisation et la recherche d’informations :

• Modèles d’embedding sémantique
• Modèles de reclassification
• Petits modèles de langage génératif

Modèles d’embedding sémantique

L’idée derrière les embeddings sémantiques est qu’un modèle d’IA peut apprendre à représenter certains aspects du sens d’une entrée en s’appuyant sur la géométrie d’espaces à très grande dimension.

On peut considérer un embedding sémantique comme un point (techniquement un vecteur) dans un espace à plusieurs dimensions. Un modèle d’embedding est un réseau de neurones qui reçoit des données numériques en entrée (souvent du texte ou une image) et renvoie l’emplacement du point correspondant dans un espace multidimensionnel, sous forme de coordonnées numériques. Si le modèle est efficace, la distance entre deux embeddings sémantiques est proportionnelle à la similarité de sens des objets correspondants.

Pour comprendre l’intérêt de cette approche dans les applications de recherche, imaginez les embeddings des mots « chien » et « chat » comme des points dans l’espace :

Un bon modèle d’embedding générera une représentation du mot « félin » bien plus proche de « chat » que de « chien », tandis que « canidé » sera plus proche de « chien » que de « chat », car ces mots partagent un sens très proche :

Si un modèle est multilingue, nous nous attendrions à la même chose pour les traductions de « chat » et « chien » :

Les modèles d’embedding traduisent la similarité ou la différence de sens entre des éléments en relations spatiales entre leurs représentations vectorielles. Les illustrations ci-dessus sont en deux dimensions pour faciliter la visualisation, mais les modèles d’embedding produisent des vecteurs comportant des dizaines, voire des milliers de dimensions. Cela leur permet de capturer les subtilités du sens dans des textes entiers, en leur associant un point dans un espace comportant des centaines, voire des milliers de dimensions, pour des documents pouvant contenir des milliers de mots.

Embeddings multimodaux

Les modèles multimodaux étendent le principe des embeddings sémantiques à d’autres types de contenu que le texte – notamment les images. On s’attend donc à ce qu’un embedding d’image soit proche de celui d’une description fidèle de cette image :

Les embeddings sémantiques offrent de nombreux cas d’usage. Ils peuvent notamment servir à créer des classificateurs efficaces, à regrouper les données (data clustering), ou encore à effectuer des tâches comme la déduplication ou l’analyse de la diversité des données – des fonctionnalités clés dans les environnements big data où les volumes à traiter sont trop importants pour être gérés manuellement.

L’usage principal des embeddings concerne la recherche d’informations. Elasticsearch peut stocker des objets de récupération avec des embeddings comme clés. Les requêtes sont converties en vecteurs d’embedding, et une recherche renvoie les objets stockés dont les clés sont les plus proches du vecteur d’embedding de la requête.

Là où la recherche vectorielle traditionnelle (par vecteur unique ou vecteur clairsemé) utilise des vecteurs basés sur les mots ou les métadonnées dans les documents et les requêtes, la recherche par embeddings (ou vecteurs denses) utilise des significations évaluées par l’IA plutôt que des mots. Cela les rend en général plus flexibles et plus précis que les méthodes de recherche classiques.

Apprentissage par représentation de type matriochka

Le nombre de dimensions d’un embedding et la précision des valeurs qu’il contient ont un impact significatif sur les performances. Les espaces très dimensionnels et les nombres de très grande précision permettent de représenter des informations très complexes et détaillées, mais nécessitent des modèles d’IA plus coûteux à entraîner et à exécuter. Les vecteurs générés occupent également plus d’espace de stockage et nécessitent davantage de ressources de calcul pour mesurer les distances entre eux. L’utilisation de modèles d’embedding sémantique implique donc un compromis important entre précision et consommation de ressources.

Pour maximiser la flexibilité côté utilisateur, les modèles Jina sont entraînés avec une technique appelée Matryoshka Representation Learning. Cette méthode pousse le modèle à prioriser les distinctions sémantiques importantes dans les premières dimensions du vecteur, ce qui permet ensuite de tronquer les dimensions les plus élevées sans perte significative de performance.

Concrètement, cela signifie que les utilisateurs des modèles Jina peuvent choisir le nombre de dimensions qu’ils souhaitent attribuer à leurs embeddings. Réduire le nombre de dimensions entraîne une perte de précision, mais la dégradation des performances reste mineure. Pour la plupart des tâches, les performances des modèles Jina diminuent d’environ 1 à 2 % chaque fois que l’on réduit la taille des embeddings de 50 %, jusqu’à une réduction d’environ 95 %.

Récupération asymétrique

La similarité sémantique est généralement mesurée de façon symétrique. La valeur obtenue en comparant « chat » à « chien » est la même que celle obtenue en comparant « chien » à « chat ». Mais lorsqu’on utilise des embeddings pour la recherche d’informations, les résultats sont meilleurs si l’on casse cette symétrie et qu’on encode les requêtes différemment des objets à retrouver.

Cela tient à la façon dont les modèles d’embedding sont entraînés. Les données d’entraînement contiennent des éléments similaires, comme des mots, dans des contextes variés, et les modèles apprennent à en déduire le sens en comparant les similitudes et les différences contextuelles entre ces éléments.

Ainsi, il se peut par exemple que le mot « animal » apparaisse rarement dans les mêmes contextes que « chat » ou « chien », et que l’embedding du mot « animal » ne soit donc pas particulièrement proche de ceux de « chat » ou « chien ».

Cela réduit la probabilité qu’une requête sur le mot « animal » retourne des documents traitant de chats et de chiens — ce qui est précisément l’effet inverse de l’objectif recherché. On encode donc le mot « animal » différemment selon qu’il s’agit d’une requête ou d’un objet cible à retrouver :

La recherche asymétrique consiste à utiliser un modèle différent pour les requêtes, ou à entraîner un modèle d’embedding de façon spécifique pour encoder différemment les éléments selon qu’ils sont stockés pour la recherche ou utilisés comme requêtes.

Embeddings multi-vecteurs

Les embeddings simples sont efficaces pour la recherche d’informations car ils s’intègrent bien au fonctionnement d’une base indexée : les objets à retrouver sont stockés avec un unique vecteur d’embedding utilisé comme clé de recherche. Lorsque les utilisateurs interrogent le magasin de documents, leurs requêtes sont converties en vecteurs d’embedding, et les documents dont la clé est la plus proche de celle de la requête (dans l’espace vectoriel de haute dimension) sont retournés comme correspondances candidates.

Les embeddings multi-vecteurs fonctionnent différemment. Au lieu de générer un vecteur de longueur fixe pour représenter une requête ou un objet stocké, ils produisent une séquence d’embeddings représentant des parties plus petites de ces éléments. Ces parties sont généralement des jetons ou mots pour les textes, ou des fragments d’image pour les données visuelles. Ces embeddings traduisent le sens de chaque élément dans son contexte.

Par exemple, prenons ces phrases:

• She had a heart of gold.
• She had a change of heart.
• She had a heart attack.

En apparence, ces phrases sont très similaires, mais un modèle multi-vecteur générerait probablement des embeddings très différents pour chaque occurrence du mot « heart », car son sens varie dans le contexte de chaque phrase:

Comparer deux objets à l’aide de leurs embeddings multi-vecteurs revient souvent à calculer leur distance de Chamfer : on compare chaque élément d’un embedding avec ceux de l’autre, puis on additionne les distances minimales. D’autres systèmes, y compris les modules de reclassification Jina présentés plus bas, transmettent ces données à un modèle d’IA spécifiquement entraîné à évaluer leur similarité. Ces deux approches offrent généralement une précision supérieure à la simple comparaison de vecteurs uniques, car les embeddings multi-vecteurs capturent beaucoup plus d’informations contextuelles.

Toutefois, les embeddings multivecteurs sont peu adaptés à l’indexation. Ils sont souvent utilisés dans les tâches de reclassification, comme illustré dans le modèle jina-colbert-v2 présenté dans la section suivante.

Modèles d’embedding Jina

Jina Embeddings v4

jina-embeddings-v4 est un modèle multilingue et multimodal de 3,8 milliards de paramètres (3,8 × 10⁹), compatible avec des textes dans une grande diversité de langues. Il repose sur une architecture innovante qui exploite les connaissances visuelles et linguistiques pour améliorer les performances dans les deux domaines, en particulier dans les tâches de recherche d’images — notamment la recherche de documents visuels. Cela signifie qu’il est capable de traiter des images comme des graphiques, des présentations, des captures d’écran, des pages scannées ou des schémas — des types d’images courants contenant souvent du texte embarqué, en dehors du champ des modèles de vision entraînés sur des scènes du monde réel.

Nous avons optimisé ce modèle pour différentes tâches à l’aide d’adaptateurs compacts LoRA (Low-Rank Adaptation). Cette approche nous permet d’entraîner un modèle unique capable de se spécialiser dans plusieurs tâches sans perte de performance, pour un coût mémoire ou calculatoire minimal.

Principales fonctionnalités :

• Des performances de pointe en recherche de documents visuels, avec en plus une excellente prise en charge du texte multilingue et des images classiques — surpassant des modèles bien plus volumineux.
• Prise en charge de contextes d’entrée étendus : 32 768 jetons correspondent à environ 80 pages de texte en anglais double interligne, et 20 mégapixels équivalent à une image de 4 500 × 4 500 pixels.
• Taille des embeddings sélectionnée par l’utilisateur, allant de 2048 dimensions au maximum jusqu’à 128 dimensions. Nous avons constaté empiriquement une forte dégradation des performances en dessous de ce seuil.
• Compatibilité avec les embeddings simples et multi-vecteurs. Pour le texte, la sortie multivecteur se compose d’un embedding de 128 dimensions pour chaque jeton d’entrée. Pour les images, un embedding de 128 dimensions est généré pour chaque bloc de 28 × 28 pixels nécessaires à la couverture de l’image.
• Optimisation pour la recherche asymétrique grâce à une paire d’adaptateurs LoRA spécialement entraînés à cet effet.
• Un adaptateur LoRA optimisé pour le calcul de similarité sémantique.
• Prise en charge spécifique des langages de programmation et des frameworks IT, également via un adaptateur LoRA.

Nous avons développé jina-embeddings-v4 comme outil polyvalent pour toute une gamme de tâches : recherche, compréhension du langage naturel et analyse basée sur l’IA. C’est un modèle relativement compact au vu de ses capacités, mais qui demande tout de même des ressources importantes pour être déployé, et convient mieux à une utilisation via une API cloud ou dans un environnement haute performance.

Jina Embeddings v3

jina-embeddings-v3 est un modèle d’embedding multilingue, léger, performant, axé sur le texte, avec moins de 600 millions de paramètres. Il prend en charge jusqu’à 8 192 jetons de texte en entrée et génère des embeddings vectoriels simples, avec des tailles personnalisables (de 1 024 à 64 dimensions).

Nous avons entraînerjina-embeddings-v3 non seulement pour la recherche d’informations et la similarité sémantique, mais aussi pour des tâches de classification, comme l’analyse de sentiments, la modération de contenu, le clustering, l’agrégation de nouvelles et la recommandation. Comme jina-embeddings-v4, ce modèle utilise des adaptateurs LoRA spécialisés pour les cas d’usage suivants :

• Récupération asymétrique
• Similarité sémantique
• Classification
• Clustering

jina-embeddings-v3 est un modèle beaucoup plus compact que jina-embeddings-v4 , avec une taille de contexte en entrée considérablement réduite, mais qui est aussi moins coûteux à exécuter. Malgré cela, il offre des performances très compétitives (bien qu’uniquement sur du texte) et représente un choix pertinent pour de nombreux cas d’usage.

Embeddings de code Jina

Les modèles Jina spécialisés pour l’embedding de code — jina-code-embeddings (0,5 Md et 1,5 Md de paramètres) — prennent en charge 15 langages de programmation ainsi que des textes en anglais dans le domaine de l’informatique et des technologies de l’information. Ce sont des modèles compacts, avec respectivement 500 millions et 1,5 milliard de paramètres. Les deux modèles acceptent jusqu’à 32 768 jetons en entrée et permettent à l’utilisateur de définir la taille des embeddings générés : de 896 à 64 dimensions pour le plus petit, et de 1 536 à 128 pour le plus grand.

Ces modèles prennent en charge la recherche asymétrique, pour cinq spécialisations par type de tâche, en utilisant une méthode de réglage par préfixe plutôt que des adaptateurs LoRA :

• Code vers code. Récupère du code similaire entre différents langages de programmation. Utilisé pour l’alignement de code, l’élimination des doublons, la migration et le refactoring.
• Langage naturel vers code. Permet de retrouver du code correspondant à une requête en langage naturel, un commentaire ou une description.
• Code vers langage naturel. Associe du code source à de la documentation ou à d’autres textes en langage naturel.
• Complétion de code à partir de code. Suggère du code pertinent pour compléter ou améliorer un extrait existant.
• Questions-réponses techniques. Fournit des réponses en langage naturel sur des sujets technologiques, idéal pour des cas d’usage liés à l’assistance technique.

Ces modèles offrent des performances supérieures pour les tâches portant sur la documentation technique et les ressources de développement, à un coût computationnel relativement faible. Ils s’intègrent facilement dans les environnements de développement et les assistants de programmation.

Jina ColBERT v2

jina-colbert-v2 est un modèle d’embedding multivecteur de 560 millions de paramètres. Il est multilingue, entraîné à partir de données couvrant 89 langues, et prend en charge les tailles d’embedding variables et la recherche asymétrique.

Comme mentionné précédemment, les plongements multivecteurs sont peu adaptés à l’indexation mais sont très utiles pour augmenter la précision des résultats d’autres stratégies de recherche. En utilisant jina-colbert-v2, vous pouvez calculer à l’avance les embeddings multivecteurs, puis les utiliser pour reclasser les candidats lors de la recherche, au moment de la requête. Cette méthode est moins précise que l’utilisation directe d’un modèle de reclassification, mais beaucoup plus efficace, car elle consiste uniquement à comparer les embeddings multivecteurs déjà stockés, sans faire appel au modèle d’IA à chaque requête ou comparaison de candidats. Elle est particulièrement adaptée aux cas d’usage où la latence et le coût de calcul d’un modèle de reclassification seraient trop élevés, ou lorsque le nombre de documents candidats est trop important.

Ce modèle produit une séquence d’embeddings, un par jeton d’entrée, et les utilisateurs peuvent choisir des embeddings de 128, 96 ou 64 dimensions. Les correspondances candidates sont limitées à 8 192 jetons. Les requêtes sont encodées de manière asymétrique, ce qui impose à l’utilisateur de spécifier si un texte est une requête ou une correspondance candidate, et de limiter la requête à 32 jetons.

Jina CLIP v2

jina-clip-v2 est un modèle d’embedding multimodal de 900 millions de paramètres, entraîné pour produire des embeddings proches entre un texte et une image décrivant le même contenu. Son usage principal est la recherche d’images à partir de requêtes textuelles, mais c’est aussi un modèle textuel performant. Il permet de réduire les coûts liés à la gestion de modèles distincts pour la recherche texte-texte et texte-image.

Ce modèle prend en charge un contexte d’entrée textuel de 8 192 jetons, et les images sont redimensionnées à 512 × 512 pixels avant génération des embeddings.

Les architectures CLIP (Contrastive Language–Image Pretraining) sont simples à entraîner, produisent des modèles compacts, mais présentent des limites structurelles importantes. Elles ne permettent pas de transférer la connaissance d’un support à un autre pour améliorer les performances. Elles ne peuvent pas utiliser un support pour améliorer leurs performances sur un autre. Ainsi, même si le modèle sait que les mots « chien » et « chat » sont plus proches en sens que ne l’est « voiture », il ne saura pas forcément qu’une image de chien est plus proche d’une image de chat qu’elle ne l’est d’une image de voiture.

Cependant, ce modèle souffre également d’un problème connu sous le nom de décalage de modalité : par exemple, un texte sur les chiens pourrait être plus proche, en termes d’embedding, d’un texte sur les chats que d’une image de chien. À cause de cette limitation, nous recommandons d’utiliser CLIP soit pour la recherche texte-image, soit comme modèle textuel seul, mais pas pour combiner les deux dans une même requête.

Modèles de reclassification

Les modèles de reclassification prennent une ou plusieurs correspondances candidates, ainsi qu’une requête en entrée, et les comparent directement, produisant ainsi des correspondances beaucoup plus précises.

En théorie, on pourrait utiliser un reranker directement pour la recherche d’informations, en comparant chaque requête à chaque document stocké, mais cela serait extrêmement coûteux en calcul et peu réaliste, sauf pour de très petites collections. En pratique, les rerankers sont donc surtout utilisés pour réévaluer des listes restreintes de correspondances candidates identifiées par d’autres moyens, comme une recherche par embeddings ou d’autres algorithmes de recherche. Les modèles de reclassification conviennent parfaitement aux architectures de recherche hybrides ou fédérées, où une requête peut être envoyée à plusieurs systèmes de recherche distincts, chacun interrogeant ses propres ensembles de données et retournant des résultats différents. Ils sont très efficaces pour fusionner des résultats hétérogènes en une seule réponse de haute qualité.

La recherche basée sur des embeddings peut représenter un engagement important : elle implique de réindexer toutes vos données stockées et de revoir les attentes des utilisateurs sur les résultats. L’ajout d’un reranker à une solution de recherche existante permet de bénéficier des avantages de l’IA sans avoir à réarchitecturer toute la solution.

Modèles de reclassification Jina

Jina Reranker m0

jina-reranker-m0 est un reclassificateur multimodal de 2,4 milliards de paramètres, qui prend en charge des requêtes textuelles et des candidats textuels et/ou visuels. C’est le modèle de référence pour la recherche documentaire visuelle, idéal pour interroger des bases contenant des PDF, captures d’écran, images modifiées ou documents semi-structurés, qu’ils soient textuels, visuels ou mixtes.

Ce modèle prend une requête et une correspondance candidate, et retourne un score. Lorsque la même requête est utilisée avec différents candidats, les scores sont comparables et peuvent être utilisés pour les classer. Il prend en charge une taille d’entrée totale allant jusqu’à 10 240 jetons, incluant la requête et le texte ou l’image candidat(e). Chaque bloc d’image de 28 × 28 pixels utilisé pour couvrir l’image compte comme un jeton pour le calcul de la taille d’entrée.

Jina Reranker v3

jina-reranker-v3 est un reclassificateur textuel de 600 millions de paramètres avec des performances de pointe pour sa taille. Contrairement à jina-reranker-m0, il traite une requête unique et une liste pouvant aller jusqu’à 64 candidats, puis renvoie leur ordre de classement. Il prend en charge un contexte d’entrée de 131  000 jetons, incluant la requête et tous les candidats.

Jina Reranker v2

jina-reranker-v2-base-multilingual est un modèle compact et polyvalent, intégrant des fonctionnalités supplémentaires comme le support de l’appel de fonction et des requêtes SQL. Pesant moins de 300 millions de paramètres, ce modèle offre un reclassement multilingue rapide, efficace et précis, avec un support supplémentaire pour la sélection de tables SQL et de fonctions externes associées aux requêtes textuelles, ce qui le rend adapté aux cas d’usage orientés agent.

Petits modèles de langage génératif

Les modèles de langage génératif sont des modèles comme ChatGPT d’OpenAI, Google Gemini et Claude d’Anthropic, qui acceptent des entrées textuelles ou multimédias et renvoient des sorties textuelles. Il n’existe pas de frontière claire entre les grands modèles de langage (LLM) et les petits modèles de langage (SLM), mais les difficultés pratiques liées au développement, à l’exploitation et à l’usage de LLM de pointe sont bien connues. Les modèles les plus connus ne sont pas distribués publiquement, donc nous ne pouvons qu’estimer leur taille : ChatGPT, Gemini et Claude seraient dans la fourchette des 1 à 3 milliards de milliards de paramètres (1–3×10¹²).

Exécuter ces modèles, même lorsqu’ils sont en accès libre, dépasse largement les capacités du matériel conventionnel et requiert les puces les plus avancées, organisées en réseaux massivement parallèles. Il est possible d’utiliser des LLM via des API payantes, mais cela implique des coûts importants, une forte latence, et pose des défis en matière de protection des données, de souveraineté numérique et de rapatriement hors du cloud. En outre, les coûts liés à l’entraînement et à la personnalisation de modèles de cette taille peuvent être conséquents.

C’est pourquoi de nombreuses recherches portent sur le développement de modèles plus petits qui, bien qu’ils n’offrent pas toutes les capacités des plus grands LLM, peuvent exécuter certaines tâches spécifiques avec une qualité équivalente et à moindre coût. Les entreprises déploient généralement des logiciels pour répondre à des besoins spécifiques, et les logiciels d’IA n’échappent pas à cette règle : les solutions basées sur des SLM sont souvent préférées aux LLM. Ils peuvent généralement être exécutés sur du matériel standard, sont plus rapides, consomment moins d’énergie et sont beaucoup plus faciles à personnaliser.

L’offre SLM de Jina se développe à mesure que nous cherchons à intégrer l’IA dans des solutions de recherche concrètes.

Jina SLMs

ReaderLM v2

ReaderLM-v2 est un modèle de langage génératif capable de convertir du HTML en Markdown ou en JSON, selon des schémas JSON fournis par l’utilisateur et des instructions en langage naturel.

Le prétraitement et la normalisation des données sont des étapes clés dans le développement de solutions de recherche performantes pour les données numériques, mais les données issues du web sont souvent désordonnées, et les stratégies simples de conversion montrent vite leurs limites. Au contraire, ReaderLM-v2 propose une solution d’IA intelligente, capable de comprendre le chaos d’un arbre DOM brut issu d’une page web, et d’identifier avec robustesse les éléments utiles.

Avec 1,5 milliard de paramètres (1,5 × 10⁹), ils sont mille fois plus compacts que les LLM de dernière génération tout en offrant des performances comparables sur des tâches ciblées.

Jina VLM

jina-vlm est un modèle de langage génératif de 2,4 milliards de paramètres (2,4×10⁹), conçu pour répondre à des questions en langage naturel à propos d’images. Il offre un excellent support pour l’analyse de documents visuels, c’est-à-dire la réponse à des questions sur des captures d’écran, des présentations, des schémas ou d’autres images non naturelles.

Par exemple :

Ils sont également très performants pour la lecture de texte dans des images:

Mais là où jina-vlm excelle vraiment, c'est dans la compréhension du contenu des images informatives et artificielles :

Ou :

jina-vlm Ils conviennent parfaitement pour la génération automatique de légendes, les descriptions de produits, les balises alt pour les images, et les applications d’accessibilité pour les personnes malvoyantes. Ils ouvrent aussi la voie à des systèmes RAG (retrieval-augmented generation) capables d’utiliser des données visuelles et de permettre à des agents d’IA de traiter des images sans intervention humaine.

Elastic Agent Builder simplifie la création d’agents IA connectés aux données. Nous vous expliquons comment faire dans cet article de blog. Voici toutes les étapes pour créer un agent avec un outil MCP capable d’accéder aux données stockées dans Elastic. Nous utiliserons ensuite le SDK Strands Agents et ses fonctionnalités Agent2Agent (A2A) pour piloter l’agent. Le SDK Strands Agents est une plateforme de développement d’IA multi-agents, conçue pour créer des applications autonomes avec juste ce qu’il faut de code pour obtenir les résultats souhaités.

Construisons un agent IA capable de jouer à RPS+, une version revisitée du jeu classique « Pierre, feuille, ciseaux », enrichie de quelques choix supplémentaires pour les joueurs.

Produits requis

Voici ce dont vous avez besoin pour suivre les étapes décrites dans cet article de blog :

• Un éditeur de texte fonctionnant sur votre ordinateur local
  • Nous utiliserons Visual Studio Code pour suivre les exemples présentés dans cet article de blog.
• Python 3.10 ou version supérieure installé localement sur votre machine

Créez un projet sans serveur

La première étape consiste à créer un projet Elasticsearch Serverless, qui inclut Elastic Agent Builder.

Accédez à cloud.elastic.co et créez un nouveau projet Elasticsearch Serverless.

Créer un index et ajouter des données

Ensuite, nous allons ajouter des données à notre projet Elasticsearch. Ouvrez les Developer Tools pour exécuter des commandes : nous allons créer un nouvel index et y insérer des données. Dans le menu principal, sélectionnez Developer Tools.

Copiez-collez la commande PUT suivante dans la zone de saisie de requêtes de la console Developer Tools. Cette commande crée un index Elasticsearch nommé « game-docs ».

PUT /game-docs
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { 
        "type": "text"
      },
      "filename": { "type": "keyword" },
      "last_modified": { "type": "date" }
    }
  }
}

Cliquez sur le bouton Envoyer la requête à droite de l’instruction dans Developer Tools. Une notification doit confirmer que l’index game-docs a bien été créé, dans la zone de réponse de Developer Tools.

L’index nommé game-docs est l’endroit idéal pour stocker les données du jeu que nous créons. Ajoutons maintenant un document nommé rps++-md dans cet index, contenant toutes les données nécessaires au jeu. Copiez-collez la commande PUT suivante dans la console Developer Tools.

PUT /game-docs/_doc/rps+-md
{
  "title": "Rock Paper Scissors +",
  "content": "
# Game Name
RPS+

# Starting Prompt
Let's play RPS+ !
---
What do you choose?

# Game Objects
1. Rock 🪨 👊
2. Paper 📜 🖐
3. Scissors ✄ ✌️
4. Light ☼ 👍
5. Dark Energy ☄ 🫱

# Judgement of Victory
* Rock beats Scissors
  * because rocks break scissors
* Paper beats Rock
  * because paper covers rock
* Scissors beat Paper
  * because scissors cut paper
* Rock beats Light
  * because you can build a rock structure to block out light
* Paper beats Light
  * because knowledge stored in files and paper books helps us understand light
* Light beats Dark Energy
  * because light enables humans to lighten up and laugh in the face of dark energy as it causes the eventual heat death of the universe
* Light beats Scissors
  * because light is needed to use scissors safely
* Dark Energy beats Rock
  * because dark energy rocks more than rocks. It rocks rocks and everything else in its expansion of the universe
* Dark Energy beats Paper
  * because humans, with their knowledge stored in files and paper books, can't explain dark energy 
* Scissors beat Dark Energy
  * because a human running with scissors is darker than dark energy

# Invalid Input
I was hoping for an worthy opponent
  - but alas it appears that time has past
  - but alas there's little time for your todo list when [todo:fix this] is so vast

# Cancel Game
The future belongs to the bold. Goodbye..
",
  "filename": "RPS+.md",
  "last_modified": "2025-11-25T12:00:00Z"
}

Cliquez sur le bouton Envoyer la requête à côté de l’instruction pour l’exécuter et ajouter le document rps++-md à l’index game-docs.

Nous avons maintenant des données à interroger, et avec Agent Builder, c’est plus simple que jamais.

Dans le menu de navigation principal, sélectionnez Agents.

Ensuite, il vous suffit de demander à l'agent Elastic AI par défaut, « Quelles données ai-je ? »

L’agent IA Elastic analyse les données et fournit une explication claire des informations disponibles.

Créer un outil

Nous avons maintenant des données dans Elastic, mettons-les à profit. Agent Builder inclut un support natif pour créer des outils MCP, qui permettent aux agents d’accéder aux données dont ils ont besoin pour disposer du bon contexte. Créons un outil simple pour récupérer les données de notre jeu.

Cliquez sur le menu des actions dans Agent Builder.

Dans les options du menu, sélectionnez Afficher tous les outils.

Cliquez sur + Nouvel outil.

Dans le formulaire Créer un outil , sélectionnez ES|QL Saisissez l'outil et entrez les valeurs suivantes.

Pour Tool ID :

example.get_game_docs

Pour Description :

Get RPS+ doc from Elasticsearch game-docs index.

Pour Configuration, saisissez la requête suivante dans la zone de texte ES|QL Query :

FROM game-docs | WHERE filename == "RPS+.md"

Le formulaire Créer outil complété devrait ressembler à ceci. Cliquez sur Enregistrer pour créer l'outil.

Un nouvel outil a été ajouté à notre tableau de bord. Les outils ne sont pas faits pour rester inutilisés : ils doivent être mis à profit. Créons un agent qui saura exploiter notre nouvel outil personnalisé.

Créez un agent et attribuez-lui un outil

Créer un agent est d’une simplicité rafraîchissante avec Agent Builder. Il vous suffit de saisir quelques instructions pour l’agent, avec quelques détails : c’est tout. Créons un agent dès maintenant.

Cliquez sur Gérer les agents.

Cliquez + Nouvel agent.

Saisissez les informations suivantes dans le formulaire Nouvel agent.

Pour l'identification de l'agent, saisissez le texte ci-dessous :

rps_plus_agent

Dans la section texte Instructions personnalisées , saisissez les instructions suivantes :

When prompted, if the prompt contains an integer, then select the corresponding numbered item in the list of "Game Objects" from your documents. Otherwise select a random game object. This is your chosen game object for a single round of the game.

# General Game Rules
* 2 players
    - the user: the person playing the game
    - you: the agent playing the game and serving as the game master
* Each player chooses a game object which will be compared and cause them to tie, win or lose.

# Start the game
1. This is the way each new game always starts. You make the first line of your response only the name of your chosen game object. 

2. The remainder of your response should be the "Starting Prompt" text from your documents and generate a list of "Game Objects" for the person playing the game to choose a game object from.  

# End of Game: The game ends in one of the following three outcomes:
1. Invalid Input: If the player responds with an invalid game object choice, respond with variations of the "Invalid Input" text from your documents and then end the game.

2. Tie: The game ends in a tie if the user chooses the same game object as your game object choice.

3. Win or Lose: The game winner is decided based on the "Judgement of Victory" conditions from your documents. Compare the user's game object choice and your game object choice and determine who chose the winning game object.

# Game conclusion
Respond with a declaration of the winner of the game by outputting the corresponding text in the "Judgement of Victory" section of your documents.

Pour le Nom d'affichage, entrez le texte ci-dessous :

RPS+ Agent

Pour la Description de l’affichage, saisissez le texte ci-dessous :

An agent that plays the game RPS+

Donnez à l'agent l'outil personnalisé que nous avons créé précédemment en cliquant sur l'onglet Outils.

Sélectionnez uniquement example.get_game_docs, l'outil que nous avons créé précédemment.

Cliquez sur Enregistrer pour créer le nouvel agent.

Testons notre nouvel agent. Un lien pratique vous permet de démarrer une conversation avec n’importe quel agent de la liste.

Saisissez simplement « start game » pour lancer la partie. Ça fonctionne !

L’agent affiche son choix pour la partie en haut de sa réponse. Cela permet de visualiser le choix de l’agent et de vérifier que le jeu fonctionne comme prévu. Cela dit, connaître le choix de votre adversaire avant de jouer n’est pas idéal pour une partie de pierre-feuille-ciseaux. Pour peaufiner le jeu, on peut utiliser une plateforme d’orchestration d’agents capable de les piloter via du code.

Le SDK Strands Agents entre en scène.

Strands Agents SDK

Si vous souhaitez essayer de nouveaux frameworks de développement d'agents, le SDK Strands Agents vaut la peine d'être essayé. Le SDK Strands Agents a été publié par AWS (mai 2025) en tant qu'implémentation Python open source, et il existe désormais une version Typescript.

Premiers pas avec le SDK Strands Agents en Python

Lancez vos environnements de développement : nous allons cloner et exécuter une application d’exemple qui utilise Strands Agents pour piloter l’agent RPS+ via le protocole A2A. Créons une version personnalisée du jeu RPS+ dans laquelle le choix de l’agent est révélé après votre propre décision, afin de préserver l’effet de surprise et le côté ludique du jeu Pierre-Feuille-Ciseaux.

Sur votre ordinateur local, ouvrez Visual Studio Code et ouvrez un nouveau terminal.

Dans le terminal que vous venez d’ouvrir, exécutez la commande suivante pour cloner le dépôt Elasticsearch Labs :

git clone https://github.com/elastic/elasticsearch-labs

Exécution de la commande cd suivante pour changer de répertoire dans le répertoire Elasticsearch Labs :

cd elasticsearch-labs

Ensuite, exécutez cette commande pour ouvrir le dépôt dans Visual Studio Code :

code .

Dans l'explorateur de fichiers de Visual Studio, développez les dossiers supporting-blog-content et agent-builder-a2a-strands-agents , puis ouvrez le fichier elastic_agent_builder_a2a_rps+.py. Voici à quoi ressemble le fichier ouvert dans Visual Studio Code :

Voici le contenu de elastic_agent_builder_a2a_rps+.py que vous devriez voir dans votre éditeur de texte :

import asyncio
from dotenv import load_dotenv
from uuid import uuid4
import httpx
import os
import random
from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
from a2a.types import Message, Part, Role, TextPart

DEFAULT_TIMEOUT = 60  # set request timeout to 1 minute


def create_message(*, role: Role = Role.user, text: str, context_id=None) -> Message:
    return Message(
        kind="message",
        role="user",
        parts=[Part(TextPart(kind="text", text=text))],
        message_id=uuid4().hex,
        context_id=context_id,
    )


async def main():
    load_dotenv()
    a2a_agent_host = os.getenv("ES_AGENT_URL")
    a2a_agent_key = os.getenv("ES_API_KEY")
    custom_headers = {"Authorization": f"ApiKey {a2a_agent_key}"}

    async with httpx.AsyncClient(
        timeout=DEFAULT_TIMEOUT, headers=custom_headers
    ) as httpx_client:
        # Get agent card
        resolver = A2ACardResolver(httpx_client=httpx_client, base_url=a2a_agent_host)
        agent_card = await resolver.get_agent_card(
            relative_card_path="/rps_plus_agent.json"
        )
        # Create client using factory
        config = ClientConfig(
            httpx_client=httpx_client,
            streaming=True,
        )
        factory = ClientFactory(config)
        client = factory.create(agent_card)
        # Use the client to communicate with the agent
        print("\nSending 'start game' message to Elastic A2A agent...")
        random_game_object = random.randint(1, 5)
        msg = create_message(text=f"start with game object {random_game_object}")
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                context_id = event.context_id
                response_complete = event.parts[0].root.text
                # Get agent choice from the first line of the response
                parsed_response = response_complete.split("\n", 1)
                agent_choice = parsed_response[0]
                print(parsed_response[1])
        # User choice sent for game results from the agent
        prompt = input("Your Choice  : ")
        msg = create_message(text=prompt, context_id=context_id)
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                print(f"Agent Choice : {agent_choice}")
                print(event.parts[0].root.text)


if __name__ == "__main__":
    asyncio.run(main())

Examinons ce qui se passe dans ce code. En commençant par la méthode main() , le code commence par accéder aux variables d’environnement pour l’URL de l’agent et la clé API. Ensuite, nous utilisons ces valeurs pour créer un httpx client que nous pouvons utiliser pour obtenir la carte d'agent de l'agent. Le client utilise ensuite les détails de la carte d’agent pour envoyer une demande de « démarrer la partie » à l’agent. Il est intéressant de noter que nous incluons la valeur random_game_object dans la requête "start game". Cette valeur est un nombre aléatoire généré par le module aléatoire de la bibliothèque standard de Python. La raison pour laquelle nous faisons cela est qu'il s'avère que les puissants LLM (qui rendent possibles les agents IA) ne sont pas très doués pour le hasard. Pas de problème, Python vient à la rescousse.

En poursuivant dans le code, une fois que l’agent a répondu à la requête start game, le code extrait le choix de l’agent et le stocke dans la variable agent_choice. Le reste de la réponse est affiché sous forme de texte à destination de l’utilisateur final. L’utilisateur est ensuite invité à saisir son propre choix d’objet de jeu, qui est envoyé à l’agent. Le code affiche ensuite le choix de l’agent, ainsi que le résultat final du jeu selon l’agent.

Définir l’URL de votre agent et la clé API comme variables d’environnement

Comme l’application d’exemple sera exécutée en local, nous devons fournir au SDK Strands Agents une URL A2A et une clé API pour communiquer avec notre agent. L’application d’exemple utilise un fichier nommé .env pour stocker ces valeurs.

Faites une copie du fichier env.example et nommez le nouveau fichier .env

Retournez dans Elastic Agent Builder pour récupérer les deux valeurs nécessaires.

Sélectionnez Afficher tous les outils dans le menu d'action d'Agent Builder en haut à droite de la page.

Cliquez sur le menu déroulant MCP Server en haut de la page Outils et sélectionnez Copier l’URL MCP Server.

Collez l’URL du serveur MCP dans le fichier .env fichier en remplacement de la valeur d'espace réservé <YOUR-ELASTIC-AGENT-BUILDER-URL> . Nous devons maintenant apporter une modification à l'URL, à savoir remplacer le texte final « mcp » par « a2a », car le protocole A2A est celui que le SDK Agent Strands utilisera pour communiquer avec l'agent exécuté dans Elastic Agent Builder.

L’URL modifiée devrait ressembler à ceci :

https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2a

L'autre valeur dont nous avons besoin d'obtenir pendant que nous sommes ici dans Elastic Cloud est une clé d'API. Cliquez sur Elasticsearch dans la navigation principale.

Cliquez sur le bouton Copier la clé API pour copier la clé API.

Maintenant, de retour dans Visual Studio Code, collez la Clé d'API dans le fichier .env fichier pour remplacer le texte de l'espace réservé <YOUR-ELASTIC-API-KEY> . Votre .env Le fichier devrait ressembler à ceci :

Lancer l’application d’exemple

Ouvrez un nouveau terminal dans Visual Studio Code.

Commencez par exécuter la commande cd suivante dans le terminal :

cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agents

Exécutez la commande suivante pour créer un environnement virtuel Python.

python -m venv .venv

Selon le système d’exploitation de votre machine, exécutez la commande suivante pour activer l’environnement virtuel.

• MacOS/Linux

source .venv/bin/activate

• Windows

.venv\Scripts\activate

L’application d’exemple utilise le SDK Strands Agents, et nous arrivons à l’étape où il faut l’installer. Exécutez la commande suivante pour installer le SDK Strands Agents avec toutes ses dépendances Python.

pip install -r requirements.txt

Il est temps de dégager la rampe de lancement et de commencer le compte à rebours. Nous sommes prêts à lancer cette application. Reculez un peu. Lançons-la avec la commande suivante :

python elastic_agent_builder_a2a_rps+.py

Le défi ? Une partie de RPS+ vous attend. Bravo et bonne chance pour la suite !

Créez vos applications d'IA avec un contexte pertinent

La création d'un agent IA fait désormais partie de vos compétences. Vous avez vu aussi combien il est facile d'utiliser Elastic Agent Builder via A2A dans des frameworks de développement d'agents comme les SDK Strands Agents. Essayez Elastic pour créer des agents IA connectés au contexte pertinent dans vos données personnalisées.

Nous avons récemment contribué au projet open source Google MCP Toolbox for Databases en ajoutant la prise en charge d'Elasticsearch en tant que base de données.

Grâce à cette nouvelle fonctionnalité, vous pouvez désormais utiliser Google MCP Toolbox pour vous connecter à Elasticsearch et "dialoguer" directement avec vos données.

Elasticsearch

Nous avons besoin d'une instance Elasticsearch en cours d'exécution. Vous pouvez activer un essai gratuit sur Elastic Cloud ou l'installer localement via le script start-local :

curl -fsSL https://elastic.co/start-local | sh

Cela installera Elasticsearch et Kibana sur votre ordinateur et générera une clé API à utiliser pour configurer Google MCP Toolbox.

La clé API sera affichée comme sortie de la commande précédente et stockée dans un fichier .env dans le dossier elastic-start-local.

Installer l'ensemble de données d'exemple

Après l'installation, connectez-vous à Kibana en utilisant le nom d'utilisateur elastic et le mot de passe généré par le script "start-local" (stocké dans un fichier .env).

Vous pouvez installer l'ensemble de données eCommerce orders disponible dans Kibana. Il comprend un seul index nommé kibana_sample_data_ecommerce contenant des informations sur 4 675 commandes provenant d'un site web. Pour chaque commande, nous disposons des informations suivantes :

• Informations client (nom, identifiant, date de naissance, e-mail, etc.)
• Date de la commande
• ID de la commande
• Produits (liste de tous les produits avec prix, quantité, ID, catégorie, réduction, etc.)
• SKU
• Prix total (hors taxes, taxes incluses)
• Quantité totale
• Informations géographiques (ville, pays, continent, localisation, région)

Pour installer les données d'exemple, ouvrez la page Intégrations dans Kibana (recherchez "Integration" dans la barre de recherche supérieure), puis installez l'ensemble de données "Sample Data". Pour plus de détails, consultez la documentation ici : https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

Cet article a pour but de montrer combien il est facile de configurer Google MCP Toolbox pour se connecter à Elasticsearch et interagir avec l'index kibana_sample_data_ecommerce en utilisant le langage naturel.

Google MCP Toolbox

Google MCP Toolbox est un serveur MCP open source conçu pour faciliter l'interaction sécurisée et efficace des applications et des agents IA avec les bases de données. Auparavant appelé "GenAI Toolbox for Databases", le projet a été renommé après l'adoption d'une compatibilité totale avec le protocole MCP (Model Context Protocol). Son objectif est de supprimer les tâches complexes traditionnellement requises lors de la connexion d'agents à des bases de données en gérant en arrière-plan les pools de connexion, l'authentification, l'observabilité et d'autres aspects opérationnels.

Essentiellement, la boîte à outils permet aux développeurs de définir des outils réutilisables de haut niveau qui encapsulent les interactions avec la base de données. Ces outils peuvent ensuite être invoqués par n'importe quel client compatible MCP, tel qu'un agent IA, sans que le client n'ait à implémenter des requêtes SQL de bas niveau ni à gérer des connexions de base de données. Cette approche réduit considérablement la quantité de code répétitif nécessaire à la création d'agents compatibles avec les bases de données, permettant ainsi d'intégrer des opérations de données avancées en seulement quelques lignes de logique applicative. Une fois qu'un outil est défini, il peut être partagé entre plusieurs agents, frameworks, ou langages (Figure 1).

L'un des principaux avantages de la boîte à outils est le modèle de sécurité intégré. Les flux d'authentification tels que OAuth2 et OIDC sont pris en charge de manière native, ce qui permet aux développeurs d'éviter de manipuler ou de stocker des informations sensibles d'identification de base de données dans les agents. La plateforme fournit également des fonctionnalités d'observabilité via OpenTelemetry, y compris les métriques et le traçage, ce qui est essentiel pour le débogage, la surveillance et les déploiements en production. De manière générale, MCP Toolbox sert d'interface unifiée, sécurisée et extensible pour interagir avec vos données depuis n'importe quel système compatible MCP.

Comment installer MCP Toolbox

Vous pouvez installer le serveur MCP Toolbox sur Linux en utilisant la commande suivante :

export VERSION=0.21.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Si vous souhaitez l'installer sur macOS ou Windows, vous pouvez suivre les instructions détaillées ici.

Configurer Toolbox pour Elasticsearch

Pour configurer MCP Toolbox pour Elasticsearch, nous devons créer un fichier tools.yaml comme suit :

sources:
  my-cluster:
    kind: elasticsearch
    addresses:
      - http://localhost:9200
    apikey: 

tools:
  customer-orders:
    kind: elasticsearch-esql
    source: my-cluster
    description: Get the orders made by a customer identified by name.
    query: |
    	FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"})
    parameters:
      - name: name
        type: string
        description: The customer name.

toolsets:
  elasticsearch-tools:
    - customer-orders

Vous devez remplacer la valeur <insert-here-api-key> par une clé API Elasticsearch valide. Si vous exécutez Elasticsearch localement avec la commande "start-local", vous trouverez la clé API dans le fichier .env généré par start-local, sous la variable ES_LOCAL_API_KEY. Si vous utilisez Elastic Cloud, vous pouvez générer une clé API en suivant la procédure décrite ici.

Les outils précédents contiennent la requête ES|QL suivante pour Elasticsearch :

FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name)

Si vous ne connaissez pas ES|QL, il s'agit d'un langage de requête développé par Elastic, similaire à SQL, qui peut être utilisé pour effectuer des recherches sur un ou plusieurs indices. Pour en savoir plus sur ES|QL, consultez la documentation officielle ici.

La requête ci-dessus recherche toutes les commandes stockées dans l'index kibana_sample_data_ecommerce qui contiennent le nom du client spécifié, en utilisant le paramètre ?name (le point d'interrogation indique un paramètre).

Le nom du client est défini dans la configuration YAML précédente en utilisant le type chaîne et la description "The customer name" (nom du client).

Cet outil peut être utilisé pour répondre à des questions sur les commandes d'un client, par exemple : Combien de commandes le client Foo a-t-il passées en octobre 2025 ?

Les descriptions des outils et de leurs paramètres sont essentielles pour extraire les informations pertinentes de la requête en langage naturel de l'utilisateur. Cette extraction est réalisée à l'aide de la capacité d'appel de fonctions d'un grand modèle de langage (LLM). En pratique, un LLM peut déterminer quelle fonction (outil) doit être exécutée pour obtenir les informations nécessaires, ainsi que les paramètres appropriés pour cette fonction.

Pour plus d'informations sur les appels de fonctions, nous vous invitons à lire l'article OpenAI function calling with Elasticsearch (en anglais) par Ashish Tiwari.

Exécuter le serveur Toolbox

Vous pouvez exécuter le serveur MCP Toolbox à l'aide du fichier "tools.yaml" précédent avec la commande suivante :

./toolbox --tools-file tools.yaml --ui

Le paramètre –ui exécute une application web à l'adresse http://127.0.0.1:5000/ui (Figure 2).

Sélectionnez Tools (Outils) > customer-orders et insérez un nom de client dans le paramètre name (par ex. Gwen Sanders), puis cliquez sur le bouton Run Tool (Exécuter l'outil). Une réponse JSON devrait s'afficher comme illustré dans la figure 3.

La configuration est terminée et MCP Toolbox peut exécuter l'outil customer-orders pour communiquer avec Elasticsearch, en lançant la requête ES|QL.

Utiliser MCP Toolbox avec Gemini CLI

Nous pouvons utiliser n'importe quel client MCP pour communiquer avec MCP Toolbox for Databases. Par exemple, nous pouvons choisir Gemini CLI, un outil en ligne de commande permettant d'utiliser Gemini. Si vous souhaitez installer Gemini CLI, suivez les instructions indiquées ici.

Gemini CLI propose une extension préconfigurée pour MCP Toolbox, disponible sur gemini-cli-extensions/mcp-toolbox. Vous pouvez installer cette extension en exécutant la commande suivante :

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Après l'installation, vous devez accéder au répertoire dans lequel vous avez stocké le fichier de configuration "tools.yaml" pour MCP Toolbox et exécuter Gemini CLI comme suit (cette étape est nécessaire pour que Gemini CLI soit automatiquement configuré avec MCP Toolbox) :

gemini

Un message de sortie devrait s'afficher comme illustré dans la figure 4.

Vous pouvez vérifier si la boîte à outils MCP est connectée en utilisant la commande suivante :

/mcp list

Vous devriez voir s'afficher mcp_toolbox avec les outils customer-orders répertoriés (Figure 5).

Si MCP Toolbox est connecté à Gemini CLI, nous pouvons maintenant poser quelques questions, telles que : "Indiquez-moi les commandes pour la cliente Gwen Sanders". Gemini CLI demande alors l'autorisation d'exécuter l'outil "customer-orders" depuis le serveur mcp_toolbox (voir Figure 6).

Après confirmation, Gemini CLI exécute la requête dans MCP Toolbox, reçoit une réponse JSON et l'utilise pour mettre en forme la réponse (Figure 7).

La réponse de Gemini CLI indique que Gwen Sanders a passé une seule commande de 2 produits, pour un prix total de 132 EUR.

SDK MCP Toolbox

Google MCP Toolbox propose également un SDK pour accéder à toutes les fonctionnalités depuis un programme écrit en Go, Python et Javascript.

Par exemple, le SDK Python est disponible sur Github à la page suivante : https://github.com/googleapis/mcp-toolbox-sdk-python.

Nous devons créer un agent simple pour nous connecter à MCP Toolbox. Nous devons installer les packages suivants :

pip install toolbox-core
pip install google-adk

Et créer un nouveau projet d'agent à l'aide la commande suivante :

adk create my_agent

Cela créera un nouveau répertoire nommé my_agent contenant un fichier agent.py.

Mettez à jour le fichier my_agent/agent.py avec le contenu suivant pour vous connecter à Toolbox :

from google.adk import Agent
from google.adk.apps import App
from toolbox_core import ToolboxSyncClient

client = ToolboxSyncClient("http://127.0.0.1:5000")

root_agent = Agent(
    name='root_agent',
    model='gemini-2.5-flash',
    instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.",
    tools=client.load_toolset(),
)

app = App(root_agent=root_agent, name="my_agent")

Créez un fichier .env avec votre clé API Google :

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

Enfin, nous pouvons lancer l'exécution de l'agent et observer les résultats. Pour ce faire, exécutez la commande suivante :

adk run my_agent

Ou, vous pouvez le servir via une interface web :

adk web --port 8000

Dans les deux cas, vous pouvez interagir avec MCP Toolbox à l'aide d'une interface de questions-réponses. Par exemple, vous pouvez poser la question précédente : Indiquez-moi les commandes de la cliente Gwen Sanders.

Pour plus d'informations sur les différents SDK, consultez cette page de documentation.

Conclusion

Dans cet article, nous avons démontré l'intégration d'Elasticsearch pour Google MCP Toolbox for Databases. À l'aide d'un simple fichier de configuration YAML, nous pouvons définir un ensemble d'outils qui traduisent les questions en langage naturel en requêtes Elasticsearch en utilisant le langage ES|QL.

Nous avons montré comment interagir avec l'ensemble de données "kibana_sample_data_ecommerce", qui contient des commandes provenant d'un site web. Avec ce fichier de configuration, nous pouvons simplement lancer l'exécution du serveur MCP Toolbox et nous y connecter depuis n'importe quel client MCP.

Enfin, nous avons démontré comment utiliser Gemini CLI en tant que client pour nous connecter à MCP Toolbox for Databases et interroger les données e-commerce stockées dans Elasticsearch. Nous avons exécuté une requête en langage naturel pour récupérer des informations sur les commandes d'un client spécifique identifié par son nom.

À mesure que l'écosystème MCP se développe, ce modèle – des définitions d'outils légères soutenues par une infrastructure sécurisée et prête pour la production – crée de nouvelles possibilités pour construire des agents de plus en plus performants et sensibles aux données avec un minimum d'efforts. Qu'il s'agisse d'expérimenter localement les ensembles de données Elastic ou d'intégrer des fonctionnalités de recherche dans une application plus vaste, MCP Toolbox fournit une base fiable et extensible pour interagir avec vos données Elasticsearch en langage naturel.

Pour en savoir plus sur le développement d'applications d'IA agentique, consultez l'article Construire des workflows d'IA agentique avec Elasticsearch par Anish Mathur et Dana Juratoni.

Pour plus d'informations sur Google MCP Toolbox, consultez la page vhttps://googleapis.github.io/genai-toolbox/getting-started/introduction/.

Mais en corrigeant ce cas précis, vous risquez de détériorer d’autres requêtes, faute de pouvoir tester chaque cas manuellement. Mais comment vérifier, vous ou votre équipe QA, si une modification d’une requête a un effet en cascade sur les autres ? Et surtout, comment s’assurer que les modifications apportées ont réellement amélioré une requête ?

Vers une évaluation systématique

C’est là que les listes de jugement prennent tout leur sens. Plutôt que de recourir à des tests manuels et subjectifs à chaque changement, vous pouvez définir un ensemble fixe de requêtes pertinentes pour votre cas d’usage, avec leurs résultats attendus.

Cet ensemble vous sert de référence. À chaque modification, vous l’utilisez pour déterminer si votre recherche s’est effectivement améliorée ou non.

Ce qui rend cette approche si précieuse :

• Élimine l’incertitude : plus besoin de vous demander si vos changements impactent d’autres requêtes – les données vous le diront.
• Met fin aux tests manuels : une fois les ensembles de jugement enregistrés, le test devient automatique.
• Accompagne les changements : vous pouvez mettre en évidence des métriques claires qui confirment les bénéfices d’une modification.

Comment constituer votre liste de jugement

L’une des façons les plus simples de commencer consiste à choisir une requête représentative et à sélectionner manuellement les documents pertinents. Deux approches sont possibles pour construire cette liste :

• Jugements binaires : Chaque document associé à une requête reçoit une étiquette simple : pertinent (1) ou non pertinent (0).
• Jugements gradués : chaque document reçoit ici un score selon différents niveaux. Exemple : une échelle de 0 à 4, semblable à une échelle de Likert, où 0 signifie « pas du tout pertinent » et 4 « totalement pertinent », avec des nuances comme « pertinent », « plus ou moins pertinent », etc.

Les jugements binaires sont adaptés lorsque l’intention de recherche est bien définie : ce document doit-il apparaître dans les résultats ou non ?

Les jugements gradués sont utiles lorsque la frontière est plus floue : certains résultats sont meilleurs que d’autres. On peut ainsi distinguer des résultats « très pertinents », « pertinents » ou « inutiles », et utiliser des métriques qui prennent en compte l’ordre des résultats ainsi que les retours des utilisateurs. Mais les échelles graduées présentent aussi des inconvénients : les évaluateurs peuvent interpréter différemment les niveaux de notation, ce qui nuit à la cohérence des jugements. De plus, comme les métriques graduées accordent plus de poids aux notes élevées, une légère variation (par exemple, noter 3 au lieu de 4) peut entraîner un changement bien plus important dans la métrique que ce que l’évaluateur avait anticipé. Cette part de subjectivité rend les jugements gradués plus bruyants et plus difficiles à gérer dans le temps.

Dois-je classer les documents moi-même ?

Pas forcément, car il existe plusieurs façons de créer votre liste de jugement, chacune avec ses avantages et ses inconvénients :

• Jugements explicites : des experts métier examinent chaque couple requête/document et évaluent manuellement le niveau de pertinence. Cela garantit qualité et contrôle, mais c’est moins scalable.
• Jugements implicites : cette méthode déduit les documents pertinents à partir du comportement réel des utilisateurs : clics, taux de rebond, achats, etc. Elle permet de collecter automatiquement des données, mais celles-ci peuvent être biaisées. Par exemple, les utilisateurs ont tendance à cliquer plus souvent sur les premiers résultats, même s’ils ne sont pas pertinents.
• Jugements générés par l’IA : cette dernière option utilise des modèles (comme les LLM) pour évaluer automatiquement les requêtes et les documents – on parle souvent de jurys LLM. C’est rapide et facilement scalable, mais la qualité des données dépend du modèle utilisé et de la pertinence de ses données d’entraînement vis-à-vis de vos objectifs métier. Comme pour les évaluations humaines, les jurys LLM peuvent introduire leurs propres biais ou incohérences. Il est donc essentiel de valider leurs résultats à l’aide d’un ensemble restreint de jugements de confiance. Les modèles LLM sont de nature probabiliste, il n’est donc pas rare de voir un modèle LLM attribuer des scores différents à un même résultat, même avec un paramètre de température réglé sur 0.

Voici quelques recommandations pour choisir la méthode la plus adaptée à la création de votre ensemble de jugement :

• Décidez des fonctionnalités critiques pour lesquelles seuls les utilisateurs peuvent vraiment juger (prix, marque, langue, style, détails du produit, etc.). Si ces éléments sont critiques, vous avez besoin de jugements explicites – au moins pour une partie de votre liste de jugement.
• Utilisez des jugements implicites lorsque votre moteur de recherche génère déjà suffisamment de trafic pour que vous puissiez exploiter les clics, conversions et temps passés comme métriques de tendance. Il reste essentiel d’interpréter ces résultats avec prudence, en les comparant à des jugements explicites afin d’éviter tout biais (ex. : les utilisateurs ont tendance à cliquer sur les premiers résultats, même si des documents plus pertinents apparaissent plus bas).

Pour y remédier, des techniques de réduction des biais de position permettent d’ajuster ou de repondérer les données de clics afin de mieux refléter l’intérêt réel des utilisateurs. Parmi les approches possibles :

• Changement d’ordre des résultats : permet de modifier l’ordre des résultats de recherche pour un sous-ensemble d’utilisateurs afin d’évaluer l’effet de la position sur les clics.
• Les modèles de clic incluent : Dynamic Bayesian Network (DBN), User Browsing Model (UBM), etc. Ces modèles statistiques estiment la probabilité qu’un clic reflète un véritable intérêt et non simplement une position dans la page, en prenant en compte des facteurs comme le défilement, la durée du clic, la séquence de navigation, et le retour aux résultats.

Exemple : application de notation de films

Produits requis

Pour exécuter cet exemple, vous avez besoin d'un cluster Elasticsearch 8.x en cours d'exécution, en local ou sur Elastic Cloud Hosted (hébergé ou sans serveur), ainsi que d'un accès à l'API REST ou à Kibana.

Imaginez une application dans laquelle les utilisateurs peuvent publier leurs avis sur des films et aussi rechercher des films à regarder. Comme ces textes sont rédigés par les utilisateurs eux-mêmes, ils peuvent contenir des fautes de frappe ou de nombreuses variations dans la façon de s’exprimer. Il est donc essentiel que le moteur de recherche puisse interpréter cette diversité et fournir des résultats utiles aux utilisateurs.

Afin de pouvoir tester différentes requêtes sans impacter le comportement global de la recherche, l’équipe métier de votre entreprise a créé l’ensemble de jugement binaire suivant, basé sur les recherches les plus fréquentes :

Création de l'index :

PUT movies
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text"
      }
    }
  }
}

Requête BULK :

POST /movies/_bulk
{ "index": { "_id": "doc1" } }
{ "text": "DiCaprio performance in The Revenant was breathtaking." }
{ "index": { "_id": "doc2" } }
{ "text": "Inception shows Leonardo DiCaprio in one of his most iconic roles." }
{ "index": { "_id": "doc3" } }
{ "text": "Brad Pitt delivers a solid performance in this crime thriller." }
{ "index": { "_id": "doc4" } }
{ "text": "An action-packed adventure with stunning visual effects." }
{ "index": { "_id": "doc5" } }
{ "text": "A heartbreaking story of love and loss that made me cry for hours." }
{ "index": { "_id": "doc6" } }
{ "text": "One of the saddest movies ever made -- bring tissues!" }
{ "index": { "_id": "doc7" } }
{ "text": "A lighthearted comedy that will make you laugh." }
{ "index": { "_id": "doc8" } }
{ "text": "A science-fiction epic full of action and excitement." }

Voici la requête Elasticsearch utilisée par l’application :

GET movies/_search
{
 "query": {
   "match": {
     "text": {
       "query": "DiCaprio performance",
       "minimum_should_match": "100%"
     }
   }
 }
}

Du jugement aux métriques

À elles seules, les listes de jugement fournissent peu d’informations : elles ne font qu’exprimer une attente vis-à-vis des résultats de nos requêtes. Elles révèlent tout leur intérêt lorsqu’elles servent à calculer des métriques objectives pour évaluer les performances de la recherche.

Aujourd’hui, la plupart des métriques les plus courantes incluent

• Précision : mesure la proportion de résultats réellement pertinents parmi tous les résultats de recherche.
• Rappel : mesure la proportion de documents pertinents que le moteur de recherche a trouvés parmi tous les résultats.
• Gain Cumulé Actualisé (DCG) : mesure la qualité du classement des résultats, en tenant compte du fait que les documents les plus pertinents devraient apparaître en haut de la liste.
• Rang réciproque moyen (MRR) : mesure la position du premier résultat pertinent. Plus un document est haut dans la liste, plus son score est élevé.

En reprenant l’exemple de l’application de notation de films, nous allons calculer la métrique de rappel pour vérifier si des informations sont ignorées par nos requêtes.

Dans Elasticsearch, nous pouvons utiliser les listes de jugement pour calculer ces métriques via l’API Ranking Evaluation. Cette API prend en entrée la liste de jugement, la requête et la métrique à évaluer, puis retourne une valeur qui correspond à une comparaison du résultat de la requête avec la liste de jugement.

Lançons la liste de jugement pour les deux requêtes dont nous disposons :

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

Nous allons utiliser deux requêtes avec rank_eval : une pour la requête sur DiCaprio et une autre pour les films tristes. Chaque requête est accompagnée de sa propre liste de jugement (notations). Il n’est pas nécessaire d’évaluer tous les documents : ceux qui ne figurent pas dans la liste de notation sont simplement considérés comme non jugés. Pour effectuer les calculs, la métrique de rappel ne prend en compte que l’« ensemble pertinent », c’est-à-dire les documents jugés pertinents dans l’évaluation.

Dans ce cas, la requête sur DiCaprio obtient un rappel de 1, tandis que celle sur les films tristes obtient 0. Autrement dit, nous avons récupéré tous les résultats pertinents pour la première requête, et aucun pour la seconde. Le rappel moyen est donc de 0,5.

{
 "metric_score": 0.5,
 "details": {
   "dicaprio-performance": {
     "metric_score": 1,
     "unrated_docs": [],
     "hits": [
       {
         "hit": {
           "_index": "movies",
           "_id": "doc1",
           "_score": 2.4826927
         },
         "rating": 1
       },
       {
         "hit": {
           "_index": "movies",
           "_id": "doc2",
           "_score": 2.0780432
         },
         "rating": 1
       }
     ],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 2,
         "relevant_docs": 2
       }
     }
   },
   "sad-movies": {
     "metric_score": 0,
     "unrated_docs": [],
     "hits": [],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 0,
         "relevant_docs": 2
       }
     }
   }
 },
 "failures": {}
}

Peut-être que nous sommes trop stricts avec le paramètre minimum_should_match : en exigeant que 100 % des mots de la requête soient présents dans les documents, nous risquons d’écarter des résultats pertinents. Supprimons le paramètre minimum_should_match, afin qu’un document soit considéré comme pertinent dès qu’un seul mot de la requête est présent.

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

Comme vous pouvez le constater, en supprimant le paramètre minimum_should_match dans l'une des deux requêtes, nous obtenons maintenant un rappel moyen de 1 dans les deux cas.

{
  "metric_score": 1,
  "details": {
    "dicaprio-performance": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc1",
            "_score": 2.0661702
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc3",
            "_score": 0.732218
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc2",
            "_score": 0.6271719
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    },
    "sad-movies": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc7",
            "_score": 2.1307156
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc5",
            "_score": 1.3160692
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc6",
            "_score": 1.190063
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    }
  },
  "failures": {}
}

En résumé, supprimer la clause minimum_should_match : 100 % permet d’obtenir un rappel parfait pour les deux requêtes.

Nous l'avons fait ! N'est-ce pas ?

Pas si vite !

En augmentant le rappel, on élargit la gamme des résultats possibles. Cependant, chaque ajustement implique un compromis. D’où l’importance de définir des cas de test complets, en utilisant plusieurs métriques pour évaluer les changements.

Les listes de jugement et les métriques vous évitent d’avancer à l’aveugle lorsque vous apportez des modifications, car vous disposez désormais de données pour les justifier. La validation n’est plus manuelle ni répétitive, et vous pouvez tester vos changements sur plusieurs cas d’usage, et non plus un seul. Les tests A/B vous permettent également de tester en conditions réelles la configuration qui convient le mieux à vos utilisateurs et à votre cas d’utilisation, bouclant ainsi la boucle entre métriques techniques et résultats concrets.

Recommandations finales pour l’utilisation des listes de jugement

Travailler avec des listes de jugement ne consiste pas seulement à mesurer : c’est aussi construire un cadre vous permettant d’itérer en toute confiance. Pour y parvenir, voici quelques recommandations :

1. Démarrez petit, mais démarrez. Il n’est pas nécessaire d’avoir 10 000 requêtes avec 50 listes de jugement chacune. Vous devez seulement identifier les 5 à 10 requêtes les plus critiques pour votre cas d’utilisation, et définir les documents que vous attendez en haut des résultats. Cela vous donne déjà une base de travail. En général, on commence par les principales requêtes et celles qui ne renvoient aucun résultat. Vous pouvez aussi tester en partant d’une métrique simple comme la précision, puis monter en complexité.
2. Validez avec les utilisateurs. Complétez les résultats chiffrés par des tests A/B en production. De cette façon, vous saurez si les modifications prometteuses dans les métriques ont aussi un véritable impact.
3. Gardez la liste vivante. Votre cas d’utilisation évoluera, tout comme vos requêtes critiques. Mettez régulièrement à jour votre liste de jugement pour refléter les nouveaux besoins.
4. Intégrez-la à vos workflows. Intégrez les listes de jugement dans vos pipelines de développement. Assurez-vous que chaque modification de configuration, de synonymes ou d’analyse de texte soit automatiquement validée à partir de votre liste de référence.
5. Connectez les savoir-faire techniques à la stratégie. Ne vous limitez pas à des métriques techniques comme la précision ou le rappel. Utilisez les résultats d’évaluation pour éclairer vos décisions métier.

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.

Qu'est-ce que les contrôles variables ?

Si vous avez déjà travaillé avec des tableaux de bord Kibana, vous connaissez probablement nos contrôles de tableau de bord classiques : ces menus déroulants pratiques affichent des valeurs extraites de vos données pour vous permettre de les filtrer en quelques clics.

Les contrôles variables semblent similaires à première vue, mais ils comportent une particularité astucieuse : au lieu de filtrer automatiquement chaque panneau de votre tableau de bord, ils peuvent être directement intégrés dans des requêtes ES|QL au sein de visualisations individuelles.

Cela signifie que vous décidez où chaque contrôle s'applique. Mieux encore, vous pouvez les utiliser pour toutes sortes de choses, comme ajuster les intervalles de temps, changer les champs de répartition ou modifier les paramètres de visualisation à la volée. En résumé, ils offrent une expérience véritablement interactive pour vos tableaux de bord et permettent ainsi d'obtenir des informations plus rapidement et plus facilement.

Cas d'utilisation des contrôles variables

Les contrôles variables semblent utiles, mais qu'offrent-ils vraiment ? Voici quelques exemples de la manière dont ils améliorent vos tableaux de bord :

Filtrez les visualisations sélectionnées

Vous souhaitez filtrer certaines visualisations seulement ? C'est possible avec les contrôles variables. Choisissez les panneaux sur lesquels vous souhaitez agir et connectez-les dans les requêtes ES|QL à l'origine de vos visualisations.

Sélectionnez différents intervalles de temps

Donnez à vos utilisateurs la possibilité de choisir entre « 5 minutes », « 1 heure », « 1 jour », ou tout autre intervalle temporel souhaité. Créez un contrôle variable avec des intervalles prédéfinis et connectez-le à votre requête de série temporelle.

Modifier les fonctions

Au lieu de créer plusieurs graphiques pour chaque opération, les utilisateurs du tableau de bord peuvent choisir s'ils veulent voir le maximum, la moyenne, différents centiles ou tout autre agrégateur.

Grouper par différents champs

Il est parfois nécessaire de décomposer les données selon différents facteurs lors d'une enquête. Grâce aux contrôles variables, vous pouvez définir plusieurs champs « grouper par » et permettre aux utilisateurs du tableau de bord de choisir celui qui les aidera à obtenir les informations souhaitées.

Comment faire ?

Le moyen le plus simple (et probablement le plus agréable) de créer un contrôle variable est directement depuis l'éditeur de requêtes ES|QL dans votre visualisation. Commencez simplement à taper votre requête, utilisez le menu de saisie automatique et Kibana vous fournira la structure de contrôle nécessaire.

Mais si vous préférez partir de la variable elle-même, vous pouvez également aller dans : Add panel → Controls → Variable control (Ajouter un panneau → Contrôles → Contrôle de variable) et ajouter la variable à vos visualisations après avoir créé le contrôle.

Exemple 1 : Contrôle de filtrage avec sélection à valeurs multiples

1. Choisissez une visualisation alimentée par une requête ES|QL et cliquez sur « Create control » (Créer un contrôle) dans la clause WHERE

2. Vous serez automatiquement redirigé vers le menu de création de variable, où le type « Values from a query » (Valeurs d’une requête) sera sélectionné pour vous, et le nom de la variable déjà pré-rempli. N’oubliez pas que le nom d’un contrôle doit toujours commencer par « ?... » pour fonctionner dans la requête de visualisation.

Vous aurez traditionnellement besoin d'une requête comme celle-ci pour obtenir les valeurs d'un champ et les mettre à jour selon l'intervalle de temps sélectionné dans le tableau de bord :

FROM 
| WHERE @timestamp <=?_tend and @timestamp >?_tstart
| STATS BY 

3. Lorsque vous enregistrez le contrôle, vous le verrez apparaître en haut du tableau de bord et votre requête de visualisation sera mise à jour avec le nom du contrôle variable.

4. Si vous souhaitez ajouter une sélection à valeurs multiples au contrôle, vous devez utiliser la fonction MV_CONTAINS dans la requête et sélectionner « Allow multiple selections » (Autoriser les sélections multiples) lors de la création du contrôle à l’étape 2 (disponible à partir de la version 9.3).

Exemple 2 : contrôle de l'intervalle de temps

Si vous créez une série temporelle, vous pouvez facilement ajouter un contrôle variable pour l'intervalle de votre histogramme de dates :

1. Lors de la rédaction d'une requête ES|QL pour votre série temporelle, cliquez sur « Create control » (Créer un contrôle). Lorsque vous créez une variable pour des intervalles, il est préférable d'utiliser TBUCKET au lieu de BUCKET pour prendre en charge des intervalles plus lisibles tels que « 1 heure », « 1 jour », etc. Une option automatique sera bientôt disponible pour TBUCKET afin qu'il puisse s'adapter automatiquement aux périodes de temps.

2. Définissez les intervalles pour remplir les options dans le menu déroulant.

3. Sélectionnez différents intervalles dans le menu déroulant et observez comment votre visualisation change.

Exemple 3 : variables pour les fonctions

1. Créez une variable en utilisant le type de contrôle « Static values » (Valeurs statiques) et ajoutez des noms de fonctions à vos valeurs déroulantes. Il est important d'utiliser un nom de variable qui commence par « ??… » pour remplacer les fonctions.

2. Incluez le nom de la variable dans votre requête ES|QL.

Exemple 4 : variables pour les champs

1. Vous pouvez utiliser le type de contrôle « Static values » (Valeurs statiques) et indiquer les noms des champs que vous souhaitez. Le nom de variable doit commencer par « ??… » pour les champs.

2. Référencez la variable souhaitée dans la requête de visualisation.

Contrôles variables dans Discover

Les contrôles variables ne sont pas seulement une fonctionnalité du tableau de bord. Ils sont également disponibles directement dans l'éditeur ES|QL de Discover. Vous pouvez créer des contrôles pour accélérer l'exploration des données dans Discover, les intégrer au tableau de bord et inversement.

Détails techniques

Vous avez probablement remarqué que les contrôles de variables sont assortis de quelques règles, telles que les éléments d'une requête auxquels ils peuvent faire référence et les préfixes que vous devez utiliser (« ?... » pour les valeurs et « ??... » pour les champs ou les fonctions). En effet, les variables ne sont pas de simples remplacements de chaînes effectués sur le client. Ce sont des éléments essentiels du langage de requête (connus sous le nom de paramètres dans ES|QL).

Cette conception apporte de grands avantages. D'une part, Kibana peut comprendre le contexte de chaque variable, ce qui nous permet de générer et de pré-remplir automatiquement sa configuration pour vous. C’est aussi beaucoup plus sécurisé : le langage valide strictement les entrées variables et empêche ainsi les injections malveillantes tout en signalant toute erreur. De plus, il améliore les performances et la stabilité en transférant la validation complexe et la gestion des erreurs vers le serveur plutôt que vers le client. Une note sur les performances : une bonne pratique consiste à créer des variables qui incluent des requêtes rapides, car elles se chargent avant le tableau de bord. Ainsi, des requêtes lentes peuvent affecter les performances globales du tableau de bord.

Bien sûr, cette architecture présente aussi quelques limites, pour le moment. Les variables ne prennent pas encore en charge l'option « Tout » pour le filtrage, et elles ne peuvent actuellement pas être utilisées avec certains opérateurs tels que LIKE ou FROM (pour changer de source de données). La bonne nouvelle ? Nous travaillons activement à l'ajout de ces fonctionnalités.

Ce que l'avenir réserve aux contrôles

Nous ne nous arrêtons pas là ! Parmi les améliorations que nous suivons de près, citons :

✨ La possibilité de placer des contrôles n'importe où sur le tableau de bord

✨ Chaînage de vos contrôles, ce qui signifie que la sortie d'un contrôle devient l'entrée du suivant

✨ De meilleures options de sélection comme la sélection « Tout » pour les variables

✨ Nouveaux types de contrôle (contrôle de type rechercher et variables pour vos sources de données)

✨ Et d'autres améliorations de l'expérience utilisateur que vous avez demandées, comme le pré-filtrage des contrôles normaux

Si vous avez des idées ou des commentaires, n'hésitez pas à nous en faire part.

Récapitulatif

Tout d'abord, faisons le point sur la situation. Elasticsearch s'est imposé comme une base de données vectorielle puissante, offrant un ensemble complet de fonctionnalités et des performances élevées pour la recherche de similitudes à grande échelle. Avec des capacités telles que la quantification scalaire, la quantification binaire améliorée (BBQ), les opérations vectorielles SIMD et des algorithmes plus efficaces en termes d'espace disque comme DiskBBQ, il offre déjà des options efficaces et flexibles pour gérer les charges de travail vectorielles.

En intégrant NVIDIA cuVS en tant que module accessible pour les tâches de recherche vectorielle, nous visons à améliorer considérablement les performances et l'efficacité de l'indexation vectorielle afin de mieux prendre en charge les charges de travail vectorielles à grande échelle.

Le défi

L'un des défis les plus complexes dans la création d'une base de données vectorielle haute performance est la construction de l'index vectoriel, le graphe HNSW. La construction de l'index est rapidement dominée par des millions, voire des milliards d'opérations arithmétiques, car chaque vecteur est comparé à de nombreux autres. De plus, les opérations liées au cycle de vie des index, telles que la compression et les fusions, peuvent augmenter davantage la charge de calcul globale liée à l'indexation. À mesure que les volumes de données et les intégrations vectorielles associées augmentent de manière exponentielle, les GPU de calcul accéléré, conçus pour le parallélisme massif et les calculs mathématiques à haut débit, sont idéalement positionnés pour gérer ces charges de travail.

Installez le plugin Elasticsearch-GPU

NVIDIA cuVS est une bibliothèque open source CUDA-X pour la recherche vectorielle accélérée par GPU et le clustering de données, permettant une création rapide d'index et une récupération d'embeddings pour les charges de travail liées à l'IA et aux recommandations.

Elasticsearch utilise cuVS via cuvs-java, une bibliothèque open-source développée par la communauté et gérée par NVIDIA. La bibliothèque cuvs-java est légère et repose sur l'API cuVS C en utilisant Panama Foreign Function pour exposer les fonctionnalités cuVS d'une manière idiomatique Java, tout en restant moderne et performante.

La bibliothèque cuvs-java est intégrée dans un nouveau plug-in Elasticsearch ; par conséquent, l'indexation vectorielle sur le GPU peut être effectuée sur le même node et processus Elasticsearch, sans qu'il soit nécessaire de provisionner du code ou du matériel externe. Lors de la création d'index, si la bibliothèque cuVS est installée et qu'un GPU est présent et configuré, Elasticsearch utilisera le GPU pour accélérer le processus d'indexation vectorielle. Les vecteurs sont transmis au GPU, qui crée un un graphe CAGRA. Ce graphe est ensuite converti au format HNSW, ce qui le rend immédiatement disponible pour la rechercher vectorielle sur le processeur. Le format final du graphe construit est identique à celui qui serait construit sur le CPU ; cela permet à Elasticsearch d'exploiter les GPU pour une indexation vectorielle à haut débit lorsque le matériel sous-jacent le prend en charge, tout en libérant la puissance du CPU pour d'autres tâches (recherche simultanée, traitement des données, etc.).

Accélération de la création d'index

Dans le cadre de l'intégration de l'accélération GPU dans Elasticsearch, plusieurs améliorations ont été apportées à cuvs-java, en mettant l'accent sur l'efficacité de l'entrée/sortie de données et l'invocation de fonctions. L'une des principales améliorations est l'utilisation de cuVSMatrix pour modéliser de manière transparente les vecteurs, qu'ils se trouvent sur le tas Java, hors tas ou dans la mémoire du GPU. Cela permet aux données de se déplacer efficacement entre la mémoire et le GPU, en évitant les copies inutiles de milliards de vecteurs potentiels.

Grâce à cette abstraction sous-jacente sans copie, le transfert vers la mémoire GPU et la récupération du graphe peuvent être effectués directement. Pendant l'indexation, les vecteurs sont d'abord mis en mémoire tampon sur le tas Java, puis envoyés au GPU pour construire le graphe CAGRA. Le graphe est ensuite récupéré à partir du GPU, converti au format HNSW et persisté sur le disque.

Au moment de la fusion, les vecteurs sont déjà stockés sur le disque, contournant ainsi entièrement le tas Java. Les fichiers d'index sont mappés en mémoire et les données sont transférées directement dans la mémoire du GPU. La conception s'adapte également facilement à différentes largeurs de bits, telles que float32 ou int8, et s'étend naturellement à d'autres schémas de quantification.

Roulement de tambour... alors, comment ça fonctionne ?

Avant d'examiner les chiffres, un peu de contexte s'impose. La fusion des segments dans Elasticsearch s'exécute généralement automatiquement en arrière-plan pendant l'indexation, ce qui rend difficile l'évaluation comparative de manière isolée. Pour obtenir des résultats reproductibles, nous avons utilisé la fusion forcée pour déclencher explicitement la fusion des segments dans une expérience contrôlée. Comme la fusion forcée effectue les mêmes opérations de fusion sous-jacentes que la fusion en arrière-plan, ses performances servent d'indicateur utile des améliorations attendues, même si les gains exacts peuvent différer selon les charges de travail d'indexation réelles.

Passons maintenant aux chiffres.

Nos premiers résultats de référence sont très prometteurs. Nous avons exécuté une évaluation comparative sur une instance AWS g6.4xlarge avec un stockage NVMe connecté localement. Un seul node d'Elasticsearch a été configuré pour utiliser le nombre optimal par défaut de threads d'indexation (8, soit un pour chaque noyau physique) et pour désactiver la limitation de fusion (qui est moins applicable avec les disques NVMe rapides).

Pour l'ensemble de données, nous avons utilisé 2,6 millions de vecteurs avec 1 536 dimensions provenant de l' OpenAI Rally vector track, encodés sous forme de chaînes base64 et indexés sous forme de float32 hnsw. Dans tous les scénarios, les graphes créés atteignent des niveaux de rappel allant jusqu'à 95 %. Voici nos conclusions :

• Débit d'indexation : en transférant la construction des graphiques vers le GPU pendant les vidages de mémoire tampon, nous multiplions le débit par environ 12.
• Fusion forcée : une fois l'indexation terminée, le GPU continue d'accélérer la fusion des segments, multipliant par environ 7 la vitesse de la phase de fusion forcée.

• Utilisation du processeur : le transfert de la construction du graphe vers le GPU réduit considérablement l'utilisation moyenne et maximale du processeur. Les graphiques ci-dessous illustrent l'utilisation du CPU pendant l'indexation et la fusion, et mettent en évidence à quel point elle est plus faible lorsque ces opérations sont exécutées sur le GPU. La réduction de l'utilisation du CPU pendant l'indexation GPU permet de libérer des cycles CPU qui peuvent être réaffectés à l'amélioration des performances de recherche.

• Rappel : la précision reste pratiquement identique entre les exécutions CPU et GPU, le graphique généré par le GPU affichant un rappel légèrement supérieur.

Comparaison selon un autre critère : le prix

La comparaison précédente utilisait intentionnellement un matériel identique, la seule différence étant l'utilisation ou non du GPU lors de l'indexation. Cette configuration est utile pour isoler les effets du calcul brut, mais nous pouvons également examiner la comparaison du point de vue des coûts.

Pour un prix horaire à peu près équivalent à celui de la configuration accélérée par GPU, il est possible de provisionner une configuration uniquement sur processeur avec environ deux fois plus de ressources CPU et mémoire comparables : 32 vCPU (AMD EPYC) et 64 Go de RAM, permettant de doubler le nombre de threads d’indexation à 16.

Afin de garantir l'équité et la cohérence de la comparaison, nous avons réalisé cette expérience uniquement sur processeur sur une instance AWS g6.8xlarge, avec le GPU explicitement désactivé. Cela nous a permis de maintenir toutes les autres caractéristiques matérielles constantes tout en évaluant le compromis coût-performance entre l'accélération GPU et l'indexation uniquement sur processeur.

L'instance de processeur plus puissante montre effectivement une performance améliorée par rapport aux benchmarks de la section ci-dessus, comme on pouvait s'y attendre. Cependant, lorsque nous comparons cette instance de processeur plus puissante aux résultats originaux accélérés par GPU, le GPU offre toujours des gains de performance substantiels : ~5x d'amélioration dans le débit d'indexation, et ~6x dans la fusion forcée, tout en construisant des graphes qui atteignent des niveaux de rappel allant jusqu'à 95%.

Conclusion

Dans les scénarios de bout en bout, l'accélération GPU avec NVIDIA cuVS permet d'améliorer de près de 12 fois le débit d'indexation et de réduire de 7 fois la latence de fusion forcée, tout en diminuant considérablement l'utilisation du processeur. Cela démontre que l'indexation vectorielle et les charges de travail de fusion bénéficient considérablement de l'accélération GPU. Sur une comparaison ajustée en fonction des coûts, l'accélération GPU continue d'offrir des gains de performances substantiels, avec un débit d'indexation environ 5 fois supérieur et des opérations de fusion forcée 6 fois plus rapides.

L'indexation vectorielle accélérée par GPU est actuellement prévue pour la préversion technique dans Elasticsearch 9.3, dont la sortie est prévue début 2026.

Plus d'informations à venir.

Découvrez les fonctionnalités d’Elasticsearch 9.2 qui révolutionneront votre analyse de données avec ES|QL.

Révolutionner la corrélation des données : un Lookup Join plus intelligent, plus rapide et plus flexible

La commande LOOKUP JOIN dans ES|QL a subi une transformation importante dans Elasticsearch 9.2, elle devient considérablement plus efficace et polyvalente. LOOKUP JOIN fusionne les données issues de la table de résultats de votre requête ES|QL avec les enregistrements concordants d’un index de mode de recherche que vous avez désigné. Cela permet d’ajouter des champs de l’index de recherche en tant que nouvelles colonnes à votre table de résultats, en faisant correspondre les valeurs du champ de jointure. Auparavant, la jointure des données était limitée à un seul champ et à une simple égalité. Plus maintenant ! Ces améliorations vous permettent de gérer facilement des scénarios complexes de corrélation de données.

Les principales améliorations de Lookup Join incluent :

• Jointures multi-champs : Effectuez facilement des jointures sur plusieurs champs. Par exemple, pour joindre application_logs à service_registry sur service_name, environment et version:

FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment, version

• Utilisation d’expressions pour des prédicats de jointure complexes (aperçu technologique) :

Vous n'êtes plus limité à la simple égalité. LOOKUP JOIN permet désormais de spécifier plusieurs critères de corrélation et d’incorporer une gamme d’opérateurs binaires, notamment ==, !=, <, >, <=et >=. Cela signifie que vous pouvez créer des conditions de jointure très nuancées, vous permettant de poser des questions beaucoup plus sophistiquées à vos données.

Exemple 1 : Recherche des métriques d’application avec un seuil de SLA par service

FROM application_metrics
| LOOKUP JOIN sla_thresholds
      ON service_name == sla_service AND response_time > sla_response_time

Exemple 2 : Cette requête calcule le montant dû, en se basant sur les politiques tarifaires régionales qui évoluent au fil du temps. Cela relie trois ensembles de données basés sur des périodes complexes et des conditions d’égalité pour calculer un due_amountfinal. La deuxième jonction de recherche utilise le champ measurement_date de l’indice meter_readings et le champ region_id de l’indice customers pour joindre l’indice pricing_policies et trouver la politique de tarification appropriée pour le region et le measurement_date particuliers.

FROM meter_readings
| LOOKUP JOIN customers
      ON meter_id
| LOOKUP JOIN pricing_policies
      ON
        region_id == region AND
          measurement_date >= policy_begin_date AND
          measurement_date < policy_end_date
| EVAL due_amount = (kwh_consumed * rate_per_kwh + base_charge) * (1 + tax_rate)
| EVAL period = policy_name
| KEEP customer_name, period, due_amount, measurement_date, kwh_consumed,
    rate_per_kwh, base_charge, tax_rate
| SORT measurement_date

• Des gains de performances considérables pour les jointures filtrées :

Nous avons amélioré les performances des « jointures en expansion » qui sont filtrées à l'aide de conditions de table de recherche. Les jointures en expansion produisent plusieurs correspondances par ligne d'entrée, ce qui peut créer de grands ensembles de résultats intermédiaires. Cela s’aggrave lorsqu’un filtre ultérieur écarte un grand nombre de ces lignes. Avec la version 9.2, nous optimisons ces jointures en excluant les lignes superflues lorsqu’un filtre est appliqué aux données de recherche, ce qui permet d’éviter de traiter des lignes vouées à être éliminées. Dans certains scénarios, ces jointures peuvent être jusqu'à 1000 fois plus rapides !

Cette optimisation est déterminante pour gérer les « jointures à résultats multiples », là où une consultation initiale peut produire de nombreux résultats potentiels. La transmission intelligente des filtres garantit que seules les données pertinentes sont traitées, réduisant ainsi fortement le temps d’exécution des requêtes pour une analyse en temps réel sur des ensembles de données gigantesques. Cela signifie que vous obtenez vos informations beaucoup plus rapidement, même avec des opérations de jointure très volumineuses ou complexes.

Recherchez la compatibilité de Lookup Join avec la rechercher inter-clusters (CCS) :

Lorsque Lookup Join est devenu disponible en version générale dans les versions 8.19 et 9.1, il manquait le support de la recherche inter-clusters (CCS). LOOKUP JOIN s’intègre parfaitement à CCS en 9.2, ce qui est un atout majeur pour les entreprises gérant plusieurs clusters. Placez simplement votre index de recherche sur tous les clusters distants où vous souhaitez effectuer une jointure, et ES|QL utilisera automatiquement ces index de recherche distants pour la jointure avec vos données distantes. Cela simplifie l'analyse distribuée des données et garantit un enrichissement constant sur l'ensemble de votre déploiement Elasticsearch.

Ces améliorations vous permettent de corréler divers ensembles de données avec une précision, une rapidité et une facilité sans précédent, afin de découvrir des informations plus approfondies et plus exploitables sans solutions complexes ni étapes de prétraitement.

Enrichissez vos données en toute simplicité : Kibana Discover UX pour les index de recherche

L’enrichissement des données doit rester simple, et non constituer un problème. Une fantastique nouvelle expérience utilisateur a été ajoutée à Discover (Kibana) pour créer et gérer les index de recherche.

Workflow intuitif : la fonction de saisie semi-automatique complète de Discover vous guidera tout au long du processus, en suggérant des index de recherche et des champs de jointure dans l’éditeur ES|QL, ce qui facilite grandement la connexion de vos données téléchargées avec les index existants. Tapez le nom d'un index de recherche qui n'existe pas et accédez directement à l'éditeur de recherche en un seul clic pour créer l'index. Tapez le nom d'un index de recherche existant, et nous vous suggérerons une option pour le modifier :

Gestion en ligne (CRUD) : maintenez vos ensembles de données de référence à jour grâce à des fonctionnalités d'édition en ligne (création, lecture, mise à jour, suppression) directement dans Discover.

Téléchargement de fichiers sans effort : vous pouvez désormais télécharger directement des fichiers, tels que des CSV, dans Discover et les utiliser instantanément dans vos LOOKUP JOIN. Plus besoin de changer constamment de contexte en naviguant entre les différentes zones de Kibana !

Cette fonctionnalité démocratise l’enrichissement des données, que vous mappiez des ID utilisateur à des noms, ajoutiez des métadonnées d’entreprise ou joigniez des fichiers de référence statiques. La puissance des jointures est désormais à la portée de tous, de manière rapide, simple et au même endroit.

Préservez votre contexte : présentation d'INLINE STATS (aperçu technique)

L'agrégation des données est cruciale, mais parfois vous avez besoin de voir les agrégations à côté de vos données originales. Nous sommes ravis de présenter les STATS EN LIGNE en tant que fonctionnalité de la Tech Preview.

Contrairement à la commande STATS, qui remplace vos champs d'entrée par une sortie agrégée, INLINE STATS préserve tous vos champs d'entrée d'origine et ajoute simplement les nouveaux champs agrégés. Cela vous permet d’effectuer des opérations supplémentaires sur vos champs d’entrée originaux après l’agrégation, offrant ainsi un workflow d’analyse plus continu et plus flexible.

Par exemple, pour calculer la distance moyenne des vols tout en conservant les lignes de vol individuelles :

FROM kibana_sample_data_flights
 | KEEP Carrier, Dest, DistanceMiles
 | INLINE STATS avgDist = ROUND(AVG(DistanceMiles))
       BY Dest
 | WHERE DistanceMiles > avgDist

Dans cette requête, avgDist est ajouté à chaque ligne avec le Destcorrespondant (ination) par lequel nous avons regroupé, puis, comme nous avons toujours les colonnes d’information de vol, nous pouvons filtrer les résultats vers les vols ayant une distance supérieure à la moyenne.

Prise en charge des séries temporelles dans ES|QL (aperçu technique)

Elasticsearch utilise des flux de données temporelles pour stocker des métriques. Nous ajoutons la prise en charge des agrégations de séries temporelles dans ES|QL, via la commande source TS . Cette fonctionnalité est disponible dans Elastic Cloud serverless et en version 9.2 (niveau Basic) en préversion technique.

L’analyse de séries temporelles est principalement basée sur des requêtes d’agrégation qui résument les valeurs de métriques sur des plages de temps, segmentées par une ou plusieurs dimensions de filtrage. La majorité des requêtes d’agrégation nécessitent un traitement en deux étapes, avec (a) une fonction d’agrégation interne qui résume les valeurs de chaque série temporelle, et (b) une fonction d’agrégation externe qui consolide les résultats de (a) au travers des séries temporelles.

La commande source TS, combinée à STATS, offre un moyen concis et efficace d'exprimer de telles requêtes sur des séries temporelles. Plus concrètement, considérons l’exemple suivant pour calculer le taux total de requêtes par hôte et par heure :

TS my_metrics
| WHERE @timestamp > NOW() - 1 day
| STATS SUM(RATE(requests))
      BY host, TBUCKET(1h)

Dans ce cas, la fonction d'agrégation de séries chronologiques RATE est d'abord évaluée par série chronologique et par heure. Les agrégats partiels produits sont ensuite combinés à l'aide de SUM pour calculer les valeurs agrégées finales par hôte et par heure.

Vous pouvez consulter la liste des fonctions d'agrégation de séries temporelles disponibles ici. La fonction counter_rate est désormais prise en charge, sans doute la fonction d’agrégation la plus importante pour le traitement des compteurs.

La commande source TS est conçue pour être combinée avec STATS, avec une exécution adaptée pour prendre en charge efficacement les agrégations de séries temporelles. Par exemple, les données sont triées avant d’entrer dans le STATS. Les commandes de traitement susceptibles d’enrichir ou de modifier les données temporelles ou leur ordre, telles que FORK ou INLINE STATS, ne sont actuellement pas autorisées entre TS et STATS. Cette restriction pourrait être levée à l’avenir.

La sortie tabulaire de STATS peut être traitée avec n'importe quelle commande applicable. Par exemple, la requête suivante calcule le rapport entre la valeur moyenne de cpu_usage hébergé par hôte et par heure et la valeur maximale par hôte :

TS my_metrics
| STATS avg_usage = AVG(AVG_OVER_TIME(cpu_usage))
      BY host, time_bucket = TBUCKET(1h)
| INLINE STATS max_avg_usage = MAX(avg_usage)
      BY host
| EVAL ratio = avg_usage / max_avg_usage
| KEEP host, time_bucket, ratio
| SORT host, time_bucket DESC

Les données de séries temporelles sont enregistrées sur notre moteur de stockage sous-jacent à colonnes, optimisé par les doc values de Lucene. La commande TS ajoute une exécution vectorisée de requêtes via le moteur de calcul ES|QL. Les performances des requêtes sont souvent améliorées de plus d'un ordre de grandeur, par rapport aux requêtes DSL équivalentes, et sont comparables aux systèmes établis spécifiques aux métriques. Une analyse détaillée de l’architecture et des performances sera bientôt disponible. Ne manquez pas cette publication.

Élargir votre boîte à outils : nouvelles fonctions ES|QL

Manipulation de chaînes : CONTAINS, MV_CONTAINS, URL_ENCODE, URL_ENCODE_COMPONENT, URL_DECODE pour un traitement plus robuste du texte et des URL.

Séries temporelles et géospatial : TBUCKET pour des buckets temporels flexibles, TO_DENSE_VECTOR pour les opérations vectorielles, et un ensemble complet de fonctions géospatiales comme ST_GEOHASH, ST_GEOTILE, ST_GEOHEX, TO_GEOHASH, TO_GEOTILE, TO_GEOHEX pour une analyse avancée basée sur la localisation.

Formatage de la date : DAY_NAME, MONTH_NAME pour une représentation plus lisible des dates.

Ces fonctions vous offrent un ensemble d'outils plus riche pour manipuler et analyser vos données directement dans ES|QL.

Sous le capot : plus de performance et d'efficacité

Au-delà des fonctionnalités mises en avant, Elasticsearch 9.2 inclut de nombreuses optimisations de performances pour ES|QL. Nous avons accéléré RLIKE (LIST) avec pushdown dans les cas où la fonction remplace plusieurs requêtes RLIKE similaires. Avec RLIKE (LIST), nous pouvons fusionner ces requêtes en un seul automate et appliquer un automate au lieu de plusieurs. Nous avons également accéléré le chargement des champs de mots clés grâce à des tris d'index et des optimisations générales des requêtes. Ces améliorations garantissent que vos requêtes ES|QL s'exécutent plus efficacement que jamais.

Lancez-vous dès aujourd'hui !

La version 9.2 d’Elasticsearch représente une avancée majeure pour ES|QL, conférant une puissance et une flexibilité inédites à vos workflows d’analyse de données. Nous vous encourageons à explorer ces nouvelles fonctionnalités et à constater la différence qu’elles apportent.

Pour une liste complète de tous les changements et améliorations dans Elasticsearch 9.2, veuillez consulter les notes de publication officielles. Bonne recherche !

Les connecteurs personnalisés vous donnent la possibilité de combiner vos connecteurs ChatGPT existants avec des sources de données supplémentaires comme Elasticsearch pour obtenir des réponses complètes.

Dans cet article, nous allons créer un serveur MCP qui connecte ChatGPT à un index Elasticsearch contenant des informations sur les issues GitHub internes et les requêtes pull. Cela permet de répondre aux requêtes en langage naturel en utilisant vos données Elasticsearch.

Nous déploierons le serveur MCP en utilisant FastMCP sur Google Colab avec ngrok pour obtenir une URL publique à laquelle ChatGPT peut se connecter, éliminant ainsi le besoin d'une configuration complexe de l'infrastructure.

Pour un aperçu complet de MCP et de son écosystème, reportez-vous à la section État actuel du MCP.

Prérequis

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

• Cluster Elasticsearch (8.X ou supérieur)
• Clé API Elasticsearch avec accès en lecture à votre index
• Compte Google (pour Google Colab)
• Compte ngrok (fonctionne avec le niveau gratuit)
• Compte ChatGPT avec un forfait Pro/Entreprise/Business ou Edu

Comprendre les exigences du connecteur ChatGPT MCP

Les connecteurs ChatGPT MCP nécessitent l'implémentation de deux outils : search et fetch. Pour plus de détails, consultez OpenAI Docs.

Outil de recherche

Renvoie une liste de résultats pertinents depuis votre index Elasticsearch en fonction d'une requête utilisateur.

Ce qu'il reçoit :

• Une chaîne unique contenant la requête en langage naturel de l'utilisateur.
• Exemple : "Recherchez les issues liées à la migration d'Elasticsearch."

Ce qu'il renvoie : 

• Un objet avec une clé result contenant un tableau d'objets de résultats. Chaque résultat inclut :
  • id - Identifiant de document unique
  • title - Titre de l'issue ou de la PR
  • url - Lien vers l'issue/la PR

Dans notre implémentation :

return {
    "results": [
        {
            "id": "PR-612",
            "title": "Fix memory leak in WebSocket notification service",
            "url": "https://internal-git.techcorp.com/pulls/612"
        },
        # ... more results
    ]
}

Outil de récupération

Récupère le contenu complet d'un document spécifique.

Ce qu'il reçoit :

• Chaîne unique contenant l'ID du document Elasticsearch extrait du résultat de la recherche
• Exemple : "Donnez-moi les détails de la PR-578."

Ce qu'il renvoie :

• Objet de document complet contenant :
  • id - Identifiant de document unique
  • title - Titre de l'issue ou de la PR
  • text - Description complète du problème/PR et détails
  • url - Lien vers l'issue/la PR
  • type - Type de document (issue, pull_request)
  • status - Statut actuel (ouvert, en cours, résolu)
  • priority - Niveau de priorité (faible, moyen, élevé, critique)
  • assignee - Personne en charge de l'issue/la PR
  • created_date - Date de création
  • resolved_date - Date de résolution (le cas échéant)
  • labels - Balises associées au document
  • related_pr - ID de la requête pull associée

return {
    "id": "PR-578",
    "title": "Security hotfix: Patch SQL injection vulnerabilities",
    "text": "Description: CRITICAL SECURITY FIX for ISSUE-1889. Patches SQL...",
    "url": "https://internal-git.techcorp.com/pulls/578",
    "type": "pull_request",
    "status": "closed",
    "priority": "critical",
    "assignee": "sarah_dev",
    "created_date": "2025-09-19",
    "resolved_date": "2025-09-19",
    "labels": "security, hotfix, sql",
    "related_pr": null
}

Remarque : Cet exemple utilise une structure plate où tous les champs se trouvent au niveau racine. Les exigences d'OpenAI sont flexibles et prennent également en charge les objets de métadonnées imbriqués.

Issues GitHub et ensemble de données de PR

Pour ce tutoriel, nous allons utiliser un ensemble de données interne de GitHub contenant des issues et des requêtes pull. Ceci représente un scénario dans lequel vous souhaitez interroger des données privées et internes via ChatGPT.

L'ensemble de données est accessible ici. Et nous mettrons à jour l'index des données à l'aide de l'API Bulk.

Cet ensemble de données comprend :

• Issues avec description, état, niveau de priorité et personnes en charge
• Requêtes pull avec modifications de code, révisions et informations de déploiement
• Relations entre les issues et les PR (p. ex., la PR-578 corrige l'ISSUE-1889)
• Étiquettes, dates et autres métadonnées

Mappings de l'index

L'index utilise les mappings suivants pour prendre en charge la recherche hybride avec ELSER. Le champ text_semantic est utilisé pour la recherche sémantique, tandis que les autres champs permettent la recherche par mot-clé.

{
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text"
      },
      "text": {
        "type": "text"
      },
      "text_semantic": {
        "type": "semantic_text",
        "inference_id": ".elser-2-elasticsearch"
      },
      "url": {
        "type": "keyword"
      },
      "type": {
        "type": "keyword"
      },
      "status": {
        "type": "keyword"
      },
      "priority": {
        "type": "keyword"
      },
      "assignee": {
        "type": "keyword"
      },
      "created_date": {
        "type": "date",
        "format": "iso8601"
      },
      "resolved_date": {
        "type": "date",
        "format": "iso8601"
      },
      "labels": {
        "type": "keyword"
      },
      "related_pr": {
        "type": "keyword"
      }
    }
  }
}

Créer le serveur MCP

Notre serveur MCP implémente deux outils conformes aux spécifications d'OpenAI qui utilisent la recherche hybride pour combiner la sémantique et la correspondance de texte pour de meilleurs résultats.

Outil de recherche

Utilise la recherche hybride avec RRF (fusion des rangs réciproques) qui combine la recherche sémantique avec la correspondance de texte :

@mcp.tool()
    async def search(query: str) -> Dict[str, List[Dict[str, Any]]]:
        """
        Search for internal issues and PRs using hybrid search (semantic + text with RRF).
        Returns list with id, title, and url per OpenAI spec.
        """
        if not query or not query.strip():
            return {"results": []}

        logger.info(f"Searching for: '{query}'")

        try:
            # Hybrid search with RRF (Reciprocal Rank Fusion)
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                size=10,
                source=["id", "title", "url", "type", "priority"],
                retriever={
                    "rrf": {
                        "retrievers": [
                            {
                                # Semantic search with ELSER
                                "standard": {
                                    "query": {
                                        "semantic": {
                                            "field": "text_semantic",
                                            "query": query
                                        }
                                    }
                                }
                            },
                            {
                                # Text search (BM25) for keyword matching
                                "standard": {
                                    "query": {
                                        "multi_match": {
                                            "query": query,
                                            "fields": [
                                                "title^3",
                                                "text^2",
                                                "assignee^2",
                                                "type",
                                                "labels",
                                                "priority"
                                            ],
                                            "type": "best_fields",
                                            "fuzziness": "AUTO"
                                        }
                                    }
                                }
                            }
                        ],
                        "rank_window_size": 50,
                        "rank_constant": 60
                    }
                }
            )

            results = []
            if response and 'hits' in response:
                for hit in response['hits']['hits']:
                    source = hit['_source']
                    results.append({
                        "id": source.get('id', hit['_id']),
                        "title": source.get('title', 'Unknown'),
                        "url": source.get('url', '')
                    })

            logger.info(f"Found {len(results)} results")
            return {"results": results}

        except Exception as e:
            logger.error(f"Search error: {e}")
            raise ValueError(f"Search failed: {str(e)}")

Points clés :

• Recherche hybride avec RRF : combine la recherche sémantique (ELSER) et la recherche de texte (BM25) pour de meilleurs résultats.
• Requête à correspondance multiple : Recherches sur plusieurs champs avec boosting (title^3, text^2, assignee^2). Le symbole caret (^) multiplie les scores de pertinence, en privilégiant les correspondances dans les titres plutôt que dans le contenu.
• Fuzzy matching (correspondance approximative) : fuzziness: AUTO gère les fautes de frappe et d'orthographe en autorisant les correspondances approximatives.
• Ajustement des paramètres RRF :
  • rank_window_size: 50 - Spécifie le nombre de résultats principaux de chaque récupérateur (sémantique et texte) pris en compte avant la fusion.
  • rank_constant: 60 - Cette valeur détermine l'influence des documents dans chaque ensemble de résultats sur le classement final.
• Ne renvoie que les champs obligatoires : id, title, url conformément à la spécification d'OpenAI, et évite d'exposer inutilement des champs supplémentaires.

Outil de récupération

Récupère les détails du document par ID de document, s'il existe :

@mcp.tool()
    async def fetch(id: str) -> Dict[str, Any]:
        """
        Retrieve complete issue/PR details by ID.
        Returns id, title, text, url.
        """
        if not id:
            raise ValueError("ID is required")

        logger.info(f"Fetching: {id}")

        try:
            # Search by the 'id' field (not _id) since IDs are stored as a field
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                body={
                    "query": {
                        "term": {
                            "id": id  # Search by your custom 'id' field
                        }
                    },
                    "size": 1
                }
            )

            if not response or not response['hits']['hits']:
                raise ValueError(f"Document with id '{id}' not found")

            hit = response['hits']['hits'][0]
            source = hit['_source']

            result = {
                "id": source.get('id', id),
                "title": source.get('title', 'Unknown'),
                "text": source.get('text', ''),
                "url": source.get('url', ''),
                "type": source.get('type', ''),
                "status": source.get('status', ''),
                "priority": source.get('priority', ''),
                "assignee": source.get('assignee', ''),
                "created_date": source.get('created_date', ''),
                "resolved_date": source.get('resolved_date', ''),
                "labels": source.get('labels', ''),
                "related_pr": source.get('related_pr', '')
            }

            logger.info(f"Fetched: {result['title']}")
            return result

        except Exception as e:
            logger.error(f"Fetch error: {e}")
            raise ValueError(f"Failed to fetch '{id}': {str(e)}")

Points clés :

• Recherche par champ d'ID de document : utilise une requête de terme sur le champ personnalisé id
• Renvoie le document complet : inclut le champ complet text avec tout le contenu
• Structure plate : tous les champs au niveau racine, correspondant à la structure de document d'Elasticsearch.

Déployer sur Google Colab

Nous utiliserons Google Colab pour exécuter notre serveur MCP et ngrok pour l'exposer publiquement afin que ChatGPT puisse s'y connecter.

Étape 1 : Ouvrir le notebook Google Colab

Accédez à notre notebook préconfiguré Elasticsearch MCP pour ChatGPT.

Étape 2 : Configurer vos identifiants

Vous aurez besoin de trois informations :

• URL Elasticsearch : l'URL de votre cluster Elasticsearch.
• Clé API Elasticsearch : clé API avec accès en lecture à votre index.
• Jeton d'authentification ngrok : jeton gratuit fourni par ngrok. Nous utiliserons ngrok pour exposer l'URL du MCP à l'Internet afin que ChatGPT puisse s'y connecter.

Obtenir votre token ngrok

1. Créez un compte gratuit sur ngrok
2. Accédez à votre tableau de bord ngrok
3. Copier votre jeton d'authentification

Ajouter des secrets à Google Colab

Dans le notebook Google Colab :

1. Cliquez sur l'icône clé dans la barre latérale gauche pour ouvrir Secrets.
2. Ajoutez ces trois secrets :

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443
ELASTICSEARCH_API_KEY=your-api-key
NGROK_TOKEN=your-ngrok-token

3. Activer l'accès aux notebooks pour chaque secret

Étape 3 : Exécuter le notebook

1. Cliquez sur Runtime (Exécution) puis sur Run all (Tout exécuter) pour exécuter toutes les cellules
2. Attendez que le serveur démarre (environ 30 secondes)
3. Recherchez l'URL publique de ngrok dans la sortie

4. La sortie affichera quelque chose comme :

Se connecter à ChatGPT

Nous allons maintenant connecter le serveur MCP à votre compte ChatGPT.

1. Ouvrez ChatGPT et accédez aux Paramètres.
2. Accédez à Connectors (Connecteurs).Si vous utilisez un compte Pro, vous devez activer le mode développeur dans les connecteurs.

Si vous utilisez ChatGPT Enterprise ou Business, vous devez publier le connecteur sur votre espace de travail.

3. Cliquez sur Create (Créer).

Remarque : Dans les espaces de travail Business, Entreprise et Edu, seuls les propriétaires, les administrateurs et les utilisateurs ayant activé l'option correspondante (pour Entreprise/Edu) peuvent ajouter des connecteurs personnalisés. Les utilisateurs ayant un rôle de membre standard ne peuvent pas ajouter de connecteurs personnalisés eux-mêmes.

Une fois qu'un connecteur est ajouté et activé par un propriétaire ou un utilisateur administrateur, il devient accessible à tous les membres de l'espace de travail.

4. Saisissez les informations requises et votre URL ngrok se terminant par /sse/. Notez le "/" après "sse". Cela ne fonctionnera pas sans cet élément :

• Nom : Elasticsearch MCP
• Description : MCP personnalisé pour la recherche et la récupération d'informations GitHub internes.

5. Appuyez sur Créer pour enregistrer le MCP personnalisé.

La connexion est instantanée si votre serveur est en cours d'exécution. Aucune authentification supplémentaire n'est requise, car la clé API Elasticsearch est configurée sur votre serveur.

Tester le serveur MCP

Avant de poser des questions, vous devez sélectionner le connecteur que ChatGPT doit utiliser.

Prompt 1 : Recherchez les issues

Demandez : "Recherchez les issues liées à la migration d'Elasticsearch", puis confirmez l'appel à l'outil d'action.

ChatGPT appellera l'outil search avec votre requête. Vous pouvez voir qu'il recherche des outils disponibles et se prépare à appeler l'outil Elasticsearch, et confirme auprès de l'utilisateur avant de prendre toute action sur l'outil.

Demande d'appel d'outil :

{
  "query": "Elasticsearch migration issues"
}

Réponse de l'outil :

{
  "results": [
    {
      "id": "PR-598",
      "title": "Elasticsearch 8.x migration - Application code changes",
      "url": "https://internal-git.techcorp.com/pulls/598"
    },
    {
      "id": "ISSUE-1712",
      "title": "Migrate from Elasticsearch 7.x to 8.x",
      "url": "https://internal-git.techcorp.com/issues/1712"
    },
    {
      "id": "RFC-045",
      "title": "Design Proposal: Microservices Migration Architecture",
      "url": "https://internal-git.techcorp.com/rfcs/045"
    }
    // ... 7 more results
  ]
}

ChatGPT traite les résultats et les présente dans un format conversationnel naturel.

En coulisses

Prompt : "Recherchez les issues liées à la migration d'Elasticsearch"

1. Appels de ChatGPT search(“Elasticsearch migration”)

2. Elasticsearch effectue une recherche hybride.

• La recherche sémantique comprend des concepts tels que "mise à niveau" et "compatibilité des versions".
• La recherche de texte trouve des correspondances exactes pour "Elasticsearch" et "migration".
• RRF combine et classe les résultats des deux approches

3. Renvoie les 10 événements les plus pertinents avec id, title, url

4. ChatGPT identifie "ISSUE-1712: migrate from Elasticsearch 7.x to 8.x" (Migrer d'Elasticsearch 7.x vers 8.x) comme résultat le plus pertinent.

Prompt 2 : Obtenez tous les détails

Demandez : "Donnez-moi les détails de l'ISSUE-1889"

ChatGPT comprend que vous souhaitez obtenir des informations détaillées sur un problème spécifique, appelle l'outil fetch et confirme auprès de l'utilisateur avant d'entreprendre des actions sur l'outil.

Demande d'appel d'outil :

{
  "id": "ISSUE-1889"
}

Réponse de l'outil :

{
  "id": "ISSUE-1889",
  "title": "SQL injection vulnerability in search endpoint",
  "text": "Description: Security audit identified SQL injection vulnerability in /api/v1/search endpoint. User input from query parameter is not properly sanitized before being used in raw SQL query. Severity: HIGH - Immediate action required Affected Code: - File: services/search/query_builder.py - Line: 145-152 - Issue: String concatenation used instead of parameterized queries Investigation: - @security_team_alice: Confirmed exploitable with UNION-based injection - @sarah_dev: Checking all other endpoints for similar patterns - @john_backend: Found 3 more instances in legacy codebase Remediation: - Rewrite using SQLAlchemy ORM or parameterized queries - Add input validation and sanitization - Implement WAF rules as additional layer - Security regression tests Comments: - @tech_lead_mike: Stop all other work, this is P0 - @sarah_dev: PR-578 ready with fixes for all 4 vulnerable endpoints - @alex_devops: Deployed hotfix to production 2025-09-19 at 14:30 UTC - @security_team_alice: Verified fix, conducting full pentest next week Resolution: All vulnerable endpoints patched. Added pre-commit hooks to catch raw SQL queries. Security training scheduled for team.",
  "url": "https://internal-git.techcorp.com/issues/1889",
  "type": "issue",
  "status": "closed",
  "priority": "critical",
  "assignee": "sarah_dev",
  "created_date": "2025-09-18",
  "resolved_date": "2025-09-19",
  "labels": "security, vulnerability, bug, sql",
  "related_pr": "PR-578"
}

ChatGPT synthétise les informations et les présente clairement.

En coulisses

Prompt : "Donnez-moi les détails de l'ISSUE-1889"

1. Appels ChatGPT fetch(“ISSUE-1889”)
2. Elasticsearch extrait le document complet
3. Retourne un document complet avec tous les champs au niveau racine
4. ChatGPT synthétise les informations et répond avec les citations appropriées.

Conclusion

Dans cet article, nous avons créé un serveur MCP personnalisé qui connecte ChatGPT à Elasticsearch à l'aide d'outils MCP de recherche et de récupération dédiés, permettant de lancer des requêtes en langage naturel sur des données privées.

Ce modèle MCP fonctionne pour n'importe quel index Elasticsearch, documentation, produit, log ou toute autre donnée que vous souhaitez interroger en langage naturel.

Introduction au RAG agentique

La Génération Augmentée de Récupération(RAG) est devenue la pierre angulaire des applications basées sur le LLM, permettant aux modèles de fournir des réponses optimales en récupérant le contexte pertinent basé sur les requêtes de l'utilisateur. Les systèmes RAG améliorent la précision et le contexte des réponses LLM en s'appuyant sur des informations externes provenant d'API ou de magasins de données, au lieu d'être limités à des connaissances LLM préformées. D'autre part, les agents d'intelligence artificielle fonctionnent de manière autonome, prenant des décisions et des mesures pour atteindre les objectifs qui leur sont assignés.

Le RAG agentique est un cadre qui unifie les forces de la génération augmentée par la recherche et du raisonnement agentique. Il intègre le RAG dans le processus décisionnel de l'agent, ce qui permet au système de choisir dynamiquement les sources de données, d'affiner les requêtes pour une meilleure récupération du contexte, de générer des réponses plus précises et d'appliquer une boucle de rétroaction pour améliorer continuellement la qualité des résultats.

Principales caractéristiques du RAG agentic

Le cadre agentique des RAG constitue une avancée majeure par rapport aux systèmes traditionnels de RAG. Au lieu de suivre un processus de recherche fixe, il s'appuie sur des agents dynamiques capables de planifier, d'exécuter et d'optimiser les résultats en temps réel.

Examinons quelques-unes des principales caractéristiques qui distinguent les pipelines RAG agentiques :

• Prise de décision dynamique: Le RAG agentique utilise un mécanisme de raisonnement pour comprendre l'intention de l'utilisateur et acheminer chaque requête vers la source de données la plus pertinente, produisant ainsi des réponses précises et adaptées au contexte.
• Analyse complète des requêtes : Agentic RAG analyse en profondeur les requêtes des utilisateurs, y compris les sous-questions et leur intention générale. Il évalue la complexité des requêtes et sélectionne de manière dynamique les sources de données les plus pertinentes pour récupérer les informations, garantissant ainsi des réponses précises et complètes.
• Collaboration en plusieurs étapes: Ce cadre permet une collaboration en plusieurs étapes grâce à un réseau d'agents spécialisés. Chaque agent s'occupe d'une partie spécifique d'un objectif plus large, travaillant de manière séquentielle ou simultanée pour atteindre un résultat cohérent.
• Mécanismes d'auto-évaluation: Le pipeline RAG agentique utilise l'autoréflexion pour évaluer les documents récupérés et les réponses générées. Il peut vérifier si les informations extraites répondent entièrement à la requête, puis vérifier l'exactitude, l'exhaustivité et la cohérence factuelle des résultats.
• Intégration avec des outils externes: Ce flux de travail peut interagir avec des API externes, des bases de données et des sources d'information en temps réel, en incorporant des informations actualisées et en s'adaptant dynamiquement à l'évolution des données.

Modèles de flux de travail des RAG agentiques

Les modèles de flux de travail définissent la manière dont l'IA agentique structure, gère et orchestre les applications basées sur le LLM de manière fiable et efficace. Plusieurs cadres et plateformes, tels que LangChain, LangGraph, CrewAI et LlamaIndex, peuvent être utilisés pour mettre en œuvre ces flux de travail agentiques.

1. Chaîne de récupération séquentielle: Les flux de travail séquentiels divisent les tâches complexes en étapes simples et ordonnées. Chaque étape améliore les données de l'étape suivante, ce qui permet d'obtenir de meilleurs résultats. Par exemple, lors de la création d'un profil de client, un agent peut extraire les détails de base d'un CRM, un autre récupère l'historique des achats dans une base de données de transactions, et un dernier agent combine ces informations pour générer un profil complet en vue de recommandations ou de rapports.
2. Chaîne de recherche de routage: Dans ce modèle de flux de travail, un agent routeur analyse l'entrée et la dirige vers le processus ou la source de données la plus appropriée. Cette approche est particulièrement efficace lorsqu'il existe plusieurs sources de données distinctes se chevauchant très peu. Par exemple, dans un système de service à la clientèle, l'agent de routage classe les demandes entrantes, telles que les problèmes techniques, les remboursements ou les réclamations, et les achemine vers le service approprié pour un traitement efficace.
3. Chaîne de recherche parallèle: Dans ce modèle de flux de travail, plusieurs sous-tâches indépendantes sont exécutées simultanément et leurs résultats sont ensuite agrégés pour générer une réponse finale. Cette approche permet de réduire considérablement le temps de traitement et d'accroître l'efficacité du flux de travail. Par exemple, dans un flux de travail parallèle de service à la clientèle, un agent récupère les demandes antérieures similaires et un autre consulte les articles pertinents de la base de connaissances. Un agrégateur combine ensuite ces résultats pour produire une résolution complète.
4. Chaîne de travail de l'Orchestrator: Ce flux de travail présente des similitudes avec la parallélisation en raison de l'utilisation de sous-tâches indépendantes. Cependant, une distinction essentielle réside dans l'intégration d'un agent orchestrateur. Cet agent est chargé d'analyser les requêtes des utilisateurs, de les segmenter dynamiquement en sous-tâches au cours de l'exécution et d'identifier les processus ou outils appropriés nécessaires pour formuler une réponse précise.

Construire un pipeline RAG agentique à partir de zéro

Pour illustrer les principes du RAG agentique, concevons un flux de travail utilisant LangChain et Elasticsearch. Ce flux de travail adopte une architecture basée sur le routage, où plusieurs agents collaborent pour analyser les requêtes, récupérer les informations pertinentes, évaluer les résultats et générer des réponses cohérentes. Vous pouvez vous référer à ce carnet Jupyter pour suivre cet exemple.

Le flux de travail commence par l'agent routeur, qui analyse la requête de l'utilisateur pour sélectionner la méthode de recherche optimale, c'est-à-dire l'approche vectorstore, websearch ou composite. Le magasin vectoriel gère la recherche traditionnelle de documents basée sur le RAG, la recherche sur le web récupère les informations les plus récentes qui ne sont pas stockées dans le magasin vectoriel, et l'approche composite combine les deux lorsque des informations provenant de sources multiples sont nécessaires.

Si les documents sont jugés appropriés, l'agent de synthèse génère une réponse claire et adaptée au contexte. Toutefois, si les documents sont insuffisants ou non pertinents, l'agent de réécriture des requêtes reformule la requête pour améliorer la recherche. Cette requête révisée réinitialise alors le processus de routage, ce qui permet au système d'affiner sa recherche et d'améliorer le résultat final.

Produits requis

Ce flux de travail s'appuie sur les composants de base suivants pour exécuter l'exemple de manière efficace :

• Python 3.10
• Bloc-notes Jupyter
• Azure OpenAI
• Elasticsearch
• LangChain

Avant de poursuivre, vous serez invité à configurer l'ensemble des variables d'environnement requises pour cet exemple.

AZURE_OPENAI_ENDPOINT="Add your azure openai endpoint"
AZURE_OPENAI_KEY="Add your azure openai key"
AZURE_OPENAI_DEPLOYMENT="gpt-4.1"
AZURE_OPENAI_API_VERSION="Add your azure openai api version"

ES_ENDPOINT = "Add your Elasticsearch ENDPOINT"
ES_API_KEY = "Add your Elasticsearch API KEY"

Sources de données

Ce processus est illustré à l'aide d'un sous-ensemble du jeu de données AG News. L'ensemble des données comprend des articles d'actualité dans diverses catégories, telles que International, Sports, Affaires et Science/Technologie.

dataset = load_dataset("ag_news", split="train[:1000]")
docs = [
    Document(
        page_content=sample["text"],
        metadata={"category": sample["label"]}
    )
    for sample in dataset
]

Le module ElasticsearchStore est utilisé à partir de langchain_elasticsearch comme magasin de vecteurs. Pour la recherche, nous mettons en œuvre la stratégie SparseVectorStrategy, en utilisant ELSER, le modèle d'intégration propriétaire d'Elastic. Il est essentiel de confirmer que le modèle ELSER est correctement installé et déployé dans votre environnement Elasticsearch avant d'initier le magasin de vecteurs.

elastic_vectorstore = ElasticsearchStore.from_documents(
    docs,
    es_url=ES_ENDPOINT,
    es_api_key=ES_API_KEY,
    index_name=index_name,
    strategy=SparseVectorStrategy(model_id=".elser_model_2"),
)

elastic_vectorstore.client.indices.refresh(index=index_name)

La fonctionnalité de recherche sur le web est mise en œuvre à l'aide de DuckDuckGoSearchRun des outils de la communauté LangChain, ce qui permet au système de récupérer efficacement des informations en direct sur le web. Vous pouvez également envisager d'utiliser d'autres API de recherche qui peuvent fournir des résultats plus pertinents. Cet outil a été choisi car il permet d'effectuer des recherches sans avoir besoin d'une clé API.

duckduckgo = DuckDuckGoSearchRun(description= "A custom DuckDuckGo search tool for finding latest news stories.", verbose=True)
def websearch_retriever(query):
    results = duckduckgo.run(f"{query}")
    return results

L'extracteur composite est conçu pour les requêtes qui nécessitent une combinaison de sources. Il est utilisé pour fournir une réponse complète et contextuelle précise en récupérant simultanément des données en temps réel sur le web et en consultant les informations historiques du magasin de vecteurs.

def composite_retriever(query):
    related_docs = vectorstore_retriever(query)
    related_docs += websearch_retriever(query)
    return related_docs

Mise en place des agents

Dans l'étape suivante, les agents LLM sont définis pour fournir des capacités de raisonnement et de prise de décision au sein de ce flux de travail. Les chaînes LLM que nous créerons sont les suivantes router_chain, grade_docs_chain, rewrite_query_chain, et summary_chain.

L'agent routeur utilise un assistant LLM pour déterminer la source de données la plus appropriée pour une requête donnée au moment de l'exécution. L'agent de classement évalue la pertinence des documents récupérés. Si les documents sont jugés pertinents, ils sont transmis à l'agent de synthèse pour générer un résumé. Dans le cas contraire, l'agent de réécriture reformule la requête et la renvoie au processus de routage pour une nouvelle tentative de recherche. Vous trouverez les instructions pour tous les agents dans la section chaînes LLM du carnet de notes.

class RouteQuery(BaseModel):
    datasource: Literal["vectorstore", "websearch", "composite"] = Field(
        ...,
        description="Choose to route the query to web search, vectorstore or composite."
    )

router_prompt = ChatPromptTemplate.from_template("""You are an assistant that decides the best data source for questions based on news articles.
Choose one of the following options:
- 'vectorstore': for general, background, or historical news articles.
- 'websearch': for recent discoveries, 'latest', 'current', or '2025' type queries.
- 'composite': when the question needs both historical and current knowledge on news articles.

Question: {query}

Return one word: 'vectorstore', 'websearch', or 'composite'.
""")
router_structured = llm.with_structured_output(RouteQuery)
router_chain: RunnableSequence = router_prompt | router_structured

Le site llm.with_structured_output contraint les résultats du modèle à suivre un schéma prédéfini par le BaseModel sous la classe RouteQuery, ce qui garantit la cohérence des résultats. La deuxième ligne compose un RunnableSequence en reliant router_prompt à router_structured, formant un pipeline dans lequel l'invite d'entrée est traitée par le modèle de langage pour produire des résultats structurés et conformes au schéma.

Définir les nœuds d'un graphique

Cette partie consiste à définir les états du graphe, qui représentent les données circulant entre les différents composants du système. Une spécification claire de ces états garantit que chaque nœud du flux de travail sait à quelles informations il peut accéder et les mettre à jour.

class RAGState(TypedDict):
    query: str
    docs: List[Document]
    router: str
    summary: str
    self_reflection: bool
    retry_count: int = 0

Une fois les états définis, l'étape suivante consiste à définir les nœuds du graphe. Les nœuds sont en quelque sorte les unités fonctionnelles du graphique qui effectuent des opérations spécifiques sur les données. Il y a 7 nœuds différents dans notre pipeline.

def router(state: RAGState):
   router = router_chain.invoke({'query': state["query"]})
   logger.info(f"Router selected the datasource: {router.datasource}")
   logger.info(f"User query: {state['query']}")
   return {"router": router.datasource}

def vectorstore(state: RAGState):
   return {"docs": vectorstore_retriever(state["query"])}

def websearch(state: RAGState):
   return {"docs": websearch_retriever(state["query"])}

def composite(state: RAGState):
   return {"docs": composite_retriever(state["query"])}

def self_reflection(state: RAGState):
   evaluation = grade_docs_chain.invoke(
       {"query": state["query"], "docs": state["docs"]}
   )
   if evaluation.binary_score:
       logger.info(f"Self-reflection passed -- binary_score={evaluation.binary_score}")
   else:
       logger.info(f"Self-reflection failed -- binary_score={evaluation.binary_score}")

   return {
       "self_reflection": evaluation.binary_score,
   }

def query_rewriter(state: RAGState):
   retry_count = state.get("retry_count", 0) + 1
   new_query = rewrite_query_chain.invoke({"query": state["query"]})
   logger.info(f"Query rewritten: {new_query}, retry_count: {retry_count}")
   return {
       "query": new_query,
       "retry_count": retry_count,
   }

def summarize(state: RAGState):
   summary = summarize_chain.run(
       query=state["query"],
       docs=state["docs"],
   )
   return {"summary": summary}

Le nœud query_rewriter a deux fonctions dans le flux de travail. Tout d'abord, il réécrit la requête de l'utilisateur à l'aide du site rewrite_query_chain pour améliorer la recherche lorsque les documents évalués par l'agent d'autoréflexion sont jugés insuffisants ou non pertinents. Deuxièmement, il sert de compteur pour savoir combien de fois la requête a été réécrite.

Chaque fois que le nœud est invoqué, il incrémente le site retry_count stocké dans l'état du flux de travail. Ce mécanisme empêche le flux de travail d'entrer dans une boucle infinie. Si le site retry_count dépasse un seuil prédéfini, le système peut passer à un état d'erreur, à une réponse par défaut ou à toute autre condition prédéfinie de votre choix.

Compilation du graphique

La dernière étape consiste à définir les arêtes du graphe et à ajouter toutes les conditions nécessaires avant de le compiler. Chaque graphe doit partir d'un nœud de départ désigné, qui sert de point d'entrée au flux de travail. Les arêtes du graphique représentent le flux de données entre les nœuds et peuvent être de deux types :

• Arêtes droites : Ils définissent un flux direct et inconditionnel d'un nœud à l'autre. Chaque fois que le premier nœud termine sa tâche, le flux de travail passe automatiquement au nœud suivant le long de la ligne droite.
• Arêtes conditionnelles : Elles permettent au flux de travail de se ramifier en fonction de l'état actuel ou des résultats du calcul d'un nœud. Le nœud suivant est sélectionné dynamiquement en fonction de conditions telles que les résultats de l'évaluation, les décisions de routage ou le nombre de tentatives.

graph.add_edge(START, "router")

def after_router(state: RAGState):
   route = state.get("router", None)
   if route == "vectorstore":
       return "vectorstore"
   elif route == "websearch":
       return "websearch"
   else:
       return "composite"

def after_self_reflection(state: RAGState):
   if state["self_reflection"]:
           return "summarize"
   return "query_rewriter"

def after_query_rewriter(state: RAGState):
   while state['retry_count'] <= 3:
           return "router"
   raise RuntimeError("Maximum retries (3) reached -- evaluation failed.")

graph.add_conditional_edges(
   "router",
   after_router,
   {
       "vectorstore": "vectorstore",
       "websearch": "websearch",
       "composite": "composite"
   }
)

graph.add_edge("vectorstore", "self_reflection")
graph.add_edge("websearch", "self_reflection")
graph.add_edge("composite", "self_reflection")
graph.add_conditional_edges(
   "self_reflection",
   after_self_reflection,
   {
       "summarize": "summarize",
       "query_rewriter": "query_rewriter"
   }
)
graph.add_conditional_edges("query_rewriter", after_query_rewriter, {"router": "router"})
graph.add_edge("summarize", END)
agent=graph.compile()

Votre premier pipeline RAG agentique est donc prêt et peut être testé à l'aide de l'agent compilé.

result = agent.invoke({"query": query1})
logger.info(f"\nFinal Summary:\n: {result['summary']}")

Test du pipeline RAG agentique

Nous allons maintenant tester ce pipeline en utilisant trois types de requêtes distinctes, comme indiqué ci-dessous. Il convient de noter que les résultats peuvent varier et que les exemples présentés ci-dessous n'illustrent qu'un résultat potentiel.

query1="What are the latest AI models released this month?"
query2="What technological innovations are discussed in Sci/Tech news?"
query3="Compare a Sci/Tech article from the dataset with a current web article about AI trends."

Pour la première requête, le routeur sélectionne websearch comme source de données. La requête échoue à l'évaluation de l'autoréflexion et est ensuite redirigée vers l'étape de réécriture de la requête, comme le montre la sortie.

INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: What are the latest AI models released this month?
Latest Singapore news, including the city state's relationships with Malaysia and Mahathir, China and Xi Jinping, and the rest of Southeast Asia. 3 days ago · The latest military news, insights and analysis from China. All the latest news, opinions and analysis on Hong Kong, China, Asia and around the world Latest news, in-depth features and opinion on Malaysia, covering politics, economy, society and the Asean member-nation's relationships with China, Singapore, and other Southeast Asian ... Oct 12, 2025 · Brics (an acronym for Brazil, Russia, India, China and South Africa) refers to an association of 10 leading emerging markets. The other member states are Egypt, Ethiopia, ...
INFO     | __main__:self_reflection:31 - Self-reflection failed -- binary_score=False
INFO     | __main__:query_rewriter:40 - Query rewritten: query='Which AI models have been officially released in June 2024?', retry_count: 1
INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: query='Which AI models have been officially released in June 2024?'
Dream Machine is a text-to-video model created by Luma Labs and launched in June 2024 . It generates video output based on user prompts or still images. Dream Machine has been noted for its ability to realistically capture motion... Released in June 2023. In June 2024 , Baidu announced Ernie 4.0 Turbo. In April 2025, Ernie 4.5 Turbo and X1 Turbo were released . These models are optimized for faster response times and lower operational costs.[28][29]. The meaning of QUERY is question, inquiry. How to use query in a sentence. Synonym Discussion of Query. QUERY definition: 1. a question, often expressing doubt about something or looking for an answer from an authority.... Learn more. Query definition: a question; an inquiry.. See examples of QUERY used in a sentence.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: In June 2024, two AI models were officially released: Dream Machine, a text-to-video model launched by Luma Labs, and Ernie 4.0 Turbo, announced by Baidu, which is optimized for faster response times and lower operational costs.

Ensuite, nous examinons un exemple où vectorstore est utilisé, avec la deuxième requête.

INFO     | __main__:router:11 - Router selected the datasource: vectorstore
INFO     | __main__:router:12 - User query: What technological innovations are discussed in Sci/Tech news?
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: Recent Sci/Tech news highlights several technological innovations: NASA is collaborating with Silicon Valley firms to build a powerful Linux-based supercomputer to support theoretical research and shuttle engineering; new chromatin transfer techniques have enabled the cloning of cats; cybersecurity advancements are being discussed in relation to protecting personal technology; Princeton University scientists assert that existing technologies can be used immediately to stabilize global warming; and a set of GameBoy micro-games has been recognized for innovation in game design.

La requête finale est dirigée vers la recherche composite, qui utilise à la fois le magasin de vecteurs et la recherche sur le web.

INFO     | __main__:router:11 - Router selected the datasource: composite
INFO     | __main__:router:12 - User query: Compare a Sci/Tech article from the dataset with a current web article about AI trends.
Atlas currently only available on macOS, built on Chromium with planned features like ad-blocking still in development. OpenAI's Atlas browser launched with bold promises of AI -powered web browsing, but early real-world testing reveals a different story. Career-long data are updated to end-of-2024 and single recent year data pertain to citations received during calendar year 2024. The selection is based on the top 100,000 scientists by c-score (with and without self-citations) or a percentile rank of 2% or above in the sub-field. In this article I list 45 AI tools across 21 different categories. After exploring all the available options in each category, I've carefully selected the best tools based on my personal experience. Reading a complex technical article ? Simply highlight confusing terminology and ask "what's this?" to receive instant explanations. compare browsers. Comparison showing traditional browser navigation versus OpenAI Atlas AI -powered workflows. After putting Gemini, ChatGPT, Grok, and DeepSeek through rigorous testing in October 2025, it's clear that there isn't one AI that reigns supreme across all categories.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: A Sci/Tech article from the dataset highlights NASA's development of robust artificial intelligence software for planetary rovers, aiming to make them more self-reliant and capable of decision-making during missions. In contrast, a current web article about AI trends focuses on the proliferation of AI-powered tools across various categories, including browsers like OpenAI Atlas, and compares leading models such as Gemini, ChatGPT, Grok, and DeepSeek, noting that no single AI currently excels in all areas. While the NASA article emphasizes specialized AI applications for autonomous robotics in space exploration, the current trends article showcases the broadening impact of AI across consumer and professional technologies, with ongoing competition and rapid innovation among major AI platforms.

Dans le flux de travail ci-dessus, le RAG agentique détermine intelligemment quelle source de données utiliser lors de la recherche d'informations pour une requête de l'utilisateur, améliorant ainsi la précision et la pertinence de la réponse. Vous pouvez créer des exemples supplémentaires pour tester l'agent et examiner les résultats pour voir s'ils produisent des résultats intéressants.

Meilleures pratiques pour l'élaboration de flux de travail agentiques de RAG

Maintenant que nous comprenons le fonctionnement du RAG agentique, examinons quelques bonnes pratiques pour la mise en place de ces flux de travail. Le respect de ces lignes directrices contribuera à maintenir l'efficacité du système et à en faciliter l'entretien.

• Préparez-vous à des solutions de repli: Planifiez à l'avance des stratégies de repli pour les scénarios dans lesquels une étape du flux de travail échoue. Il peut s'agir de renvoyer des réponses par défaut, de déclencher des états d'erreur ou d'utiliser d'autres outils. Cela permet au système de gérer les défaillances de manière gracieuse sans interrompre le flux de travail global.
• Mettre en œuvre une journalisation complète: Essayez de mettre en œuvre la journalisation à chaque étape du flux de travail, comme les tentatives, les résultats générés, les choix de routage et les réécritures de requêtes. Ces journaux permettent d'améliorer la transparence, de faciliter le débogage et d'affiner les messages-guides, le comportement de l'agent et les stratégies de recherche au fil du temps.
• Sélectionner le modèle de flux de travail approprié: Examinez votre cas d'utilisation et sélectionnez le modèle de flux de travail qui répond le mieux à vos besoins. Utilisez des flux séquentiels pour le raisonnement étape par étape, des flux parallèles pour les sources de données indépendantes et des modèles d'orchestrateur-worker pour les requêtes multi-outils ou complexes.
• Incorporer des stratégies d'évaluation: Intégrer des mécanismes d'évaluation à différents stades du processus. Il peut s'agir d'agents d'autoréflexion, de classement des documents extraits ou de contrôles de qualité automatisés. L'évaluation permet de vérifier que les documents récupérés sont pertinents, que les réponses sont exactes et que toutes les parties d'une requête complexe sont traitées.

Défis

Si les systèmes agentiques RAG offrent des avantages significatifs en termes d'adaptabilité, de précision et de raisonnement dynamique, ils s'accompagnent également de certains défis qui doivent être relevés lors de leur conception et de leur mise en œuvre. Voici quelques-uns des principaux défis à relever :

• Flux de travail complexes: Au fur et à mesure de l'ajout d'agents et de points de décision, le flux de travail global devient de plus en plus complexe. Cela peut augmenter les risques d'erreurs ou de défaillances au moment de l'exécution. Dans la mesure du possible, donnez la priorité à la rationalisation des flux de travail en éliminant les agents redondants et les points de décision inutiles.
• Évolutivité: Il peut être difficile de faire évoluer les systèmes RAG agentiques pour traiter de grands ensembles de données et des volumes d'interrogation élevés. Incorporer des stratégies efficaces d'indexation, de mise en cache et de traitement distribué pour maintenir les performances à l'échelle.
• Orchestration et surcharge de calcul: L'exécution de flux de travail avec plusieurs agents nécessite une orchestration avancée. Cela implique une programmation minutieuse, la gestion des dépendances et la coordination des agents afin d'éviter les goulets d'étranglement et les conflits, autant d'éléments qui ajoutent à la complexité globale du système.
• Complexité de l'évaluation: L'évaluation de ces flux de travail présente des défis inhérents, car chaque étape nécessite une stratégie d'évaluation distincte. Par exemple, l'étape RAG doit être évaluée en fonction de la pertinence et de l'exhaustivité des documents récupérés, tandis que les résumés générés doivent être vérifiés en termes de qualité et d'exactitude. De même, l'efficacité de la reformulation de la requête nécessite une logique d'évaluation distincte pour déterminer si la requête réécrite améliore les résultats de la recherche.

Conclusion

Dans cet article de blog, nous avons présenté le concept de RAG agentique et souligné comment il améliore le cadre traditionnel de RAG en incorporant des capacités autonomes de l'IA agentique. Nous avons exploré les caractéristiques principales du RAG agentique et les avons démontrées à l'aide d'un exemple pratique, en construisant un assistant de nouvelles utilisant Elasticsearch comme magasin de vecteurs et LangChain pour créer le cadre agentique.

En outre, nous avons discuté des meilleures pratiques et des principaux défis à prendre en compte lors de la conception et de la mise en œuvre d'un pipeline RAG agentique. Ces idées sont destinées à guider les développeurs dans la création de systèmes agentiques robustes, évolutifs et efficaces qui combinent de manière effective la recherche, le raisonnement et la prise de décision.

Prochaines étapes

Le flux de travail que nous avons mis en place est simple et laisse une large place aux améliorations et à l'expérimentation. Nous pouvons l'améliorer en expérimentant divers modèles d'intégration et en affinant les stratégies de recherche. En outre, l'intégration d'un agent de reclassement pour hiérarchiser les documents récupérés pourrait être bénéfique. Un autre domaine d'exploration concerne le développement de stratégies d'évaluation pour les cadres agentiques, en particulier l'identification d'approches communes et réutilisables applicables à différents types de cadres. Enfin, l'expérimentation de ces cadres sur des ensembles de données plus vastes et plus complexes.

En attendant, si vous avez des expériences similaires à partager, nous serions ravis de les connaître ! N'hésitez pas à nous faire part de vos commentaires ou à vous connecter avec nous via notre canal Slack communautaire ou nos forums de discussion.

Ressources

• Self-RAG : Apprendre à retrouver, générer et critiquer par l'autoréflexion
• Génération assistée par récupération agentique : Une enquête sur la recherche agentique et la génération augmentée : une enquête sur la recherche agentique et la génération augmentée

Le problème de l'étendue des scores

Pour préparer le terrain, examinons l'une des principales raisons pour lesquelles la recherche hybride peut s'avérer difficile : la variation des fourchettes de scores. Notre vieil ami BM25 produit des scores non bornés. En d'autres termes, BM25 peut générer des scores allant de près de 0 à (théoriquement) l'infini. En revanche, les requêtes portant sur les champs dense_vector produiront des scores limités entre 0 et 1. Pour aggraver ce problème, semantic_text obscurcit le type de champ utilisé pour indexer les embeddings, de sorte qu'à moins d'avoir une connaissance détaillée de la configuration de votre index et de votre point de terminaison d'inférence, il peut être difficile de savoir quelle sera la plage de scores de votre requête. Cela pose un problème lorsqu'on essaie d'intercaler des résultats de recherche lexicaux et sémantiques, car les résultats lexicaux peuvent prendre le pas sur les résultats sémantiques, même si ces derniers sont plus pertinents. La solution généralement acceptée pour ce problème est de normaliser les scores avant d'entrelacer les résultats. Elasticsearch dispose de deux outils pour cela, les extracteurs linéaires et RRF.

Le récupérateur RRF applique l'algorithme RRF, en utilisant le rang du document comme mesure de la pertinence et en écartant le score. Étant donné que le score n'est pas pris en compte, les écarts de score ne posent pas de problème.

L'extracteur linéaire utilise une combinaison linéaire pour déterminer le score final d'un document. Il s'agit de prendre le score de chaque composante de la requête pour le document, de le normaliser et de l'additionner pour obtenir le score total. Mathématiquement, l'opération peut être exprimée comme suit :

Total Score = 𝚺(N(Sx))

Où N est la fonction de normalisation et SX est le score de la requête X. La fonction de normalisation est essentielle ici, car elle transforme le score de chaque requête pour utiliser le même intervalle. Pour en savoir plus sur le retriever linéaire , cliquez ici.

La décomposition

Les utilisateurs peuvent mettre en œuvre une recherche hybride efficace à l'aide de ces outils, mais cela nécessite une certaine connaissance de votre index. Prenons un exemple avec l'extracteur linéaire, où nous allons interroger un index avec deux champs :

PUT linear_retriever_example
{
  "mappings": {
    "properties": {
      "semantic_text_field": { <1>
        "type": "semantic_text",
        "inference_id": ".multilingual-e5-small-elasticsearch"
      },
      "text_field": { <2>
        "type": "text"
      }
    }
  }
}

1. semantic_text_field est un champ semantic_text qui utilise E5, un modèle d'intégration de texte.

2. text_field est un champ standard text

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "match": { <1>
                  "semantic_text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

1. Nous utilisons une requête match sur notre champ semantic_text, dont la prise en charge a été ajoutée dans Elasticsearch 8.18/9.0.

Lors de la construction de la requête, nous devons garder à l'esprit que semantic_text_field utilise un modèle d'intégration de texte, de sorte que toute requête sur ce site générera un score entre 0 et 1. Nous devons également savoir que text_field est un champ standard de text et que les requêtes sur ce champ génèreront donc un score non borné. Pour créer un ensemble de résultats pertinents, nous devons utiliser un extracteur qui normalisera les résultats des requêtes avant de les combiner. Dans cet exemple, nous utilisons l'extracteur linéaire avec la normalisation minmax, qui normalise le score de chaque requête à une valeur comprise entre 0 et 1.

La construction de la requête dans cet exemple est assez simple car seuls deux champs sont concernés. Toutefois, la situation peut se compliquer très rapidement à mesure que l'on ajoute d'autres champs, de types différents. Cela démontre que la rédaction d'une requête de recherche hybride efficace nécessite souvent une connaissance plus approfondie de l'index interrogé, afin que les scores des composantes de la requête soient correctement normalisés avant d'être combinés. Cela constitue un obstacle à l'adoption plus large de la recherche hybride.

Regroupement de requêtes

Étendons l'exemple : Et si nous voulions interroger un champ text et deux champs semantic_text? Nous pourrions construire une requête comme celle-ci :

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_1",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_2",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

Cela semble être une bonne chose à première vue, mais il y a un problème potentiel. Désormais, les matchs sur le terrain semantic_text représentent ⅔ du score total :

Total Score = N(semantic_text_field_1 score) + N(semantic_text_field_2 score) + N(text_field score)

Ce n'est probablement pas ce que vous souhaitez, car cela crée un score déséquilibré. Les effets ne sont peut-être pas très visibles dans un exemple comme celui-ci, qui ne comporte que trois champs, mais ils deviennent problématiques lorsqu'un plus grand nombre de champs sont interrogés. Par exemple, la plupart des index contiennent beaucoup plus de champs lexicaux que de champs sémantiques (c.-à-d. dense_vector, sparse_vector, ou semantic_text). Que se passerait-il si nous interrogions un index comportant 9 champs lexicaux et 1 champ sémantique en utilisant le modèle ci-dessus ? Les correspondances lexicales représenteraient 90% du score, ce qui réduirait l'efficacité de la recherche sémantique.

Une solution courante consiste à regrouper les requêtes en catégories lexicales et sémantiques et à pondérer les deux de manière égale. Cela permet d'éviter que l'une ou l'autre catégorie ne domine le score total.

Mettons cela en pratique. À quoi ressemblerait cette approche de requêtes groupées pour cet exemple en utilisant l'outil de recherche linéaire ?

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "linear": {
              "retrievers": [
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_1",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                },
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_2",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                }
              ]
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

Wow, ça devient verbeux ! Vous avez peut-être même dû faire défiler l'écran de haut en bas plusieurs fois pour examiner l'ensemble de la requête ! Ici, nous utilisons deux niveaux de normalisation pour créer les groupes de requêtes. Mathématiquement, elle peut être exprimée comme suit :

Total Score = N(N(semantic_text_field_1 score) + N(semantic_text_field_2 score)) + N(text_field score)

Ce deuxième niveau de normalisation garantit que les requêtes portant sur les champs semantic_text et text sont pondérées de manière égale. Notez que nous omettons la normalisation de second niveau pour text_field dans cet exemple puisqu'il n'y a qu'un seul champ lexical, ce qui vous évite encore plus de verbosité.

Cette structure d'interrogation est déjà lourde, et nous n'interrogeons que trois champs. Il devient de plus en plus difficile à gérer, même pour les praticiens chevronnés de la recherche, au fur et à mesure que l'on interroge davantage de champs.

Le format d'interrogation à champs multiples

Nous avons ajouté le format de requête multi-champs pour les extracteurs linéaires et RRF dans Elasticsearch 8.19, 9.1 et serverless pour simplifier tout cela. Vous pouvez maintenant effectuer la même requête que ci-dessus avec just :

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Ce qui réduit la requête de 55 lignes à seulement 9 ! Elasticsearch utilise automatiquement les mappages d'index pour :

• Déterminer le type de chaque champ interrogé
• Regrouper chaque champ dans une catégorie lexicale ou sémantique
• Pondérer chaque catégorie de manière égale dans la note finale

Cela permet à n'importe qui d'exécuter une requête de recherche hybride efficace sans avoir besoin de connaître les détails de l'index ou les points de terminaison d'inférence utilisés.

Lorsque vous utilisez la méthode RRF, vous pouvez omettre le site normalizer, car le rang est utilisé comme indicateur de la pertinence :

GET rrf_retriever_example/_search
{
  "retriever": {
    "rrf": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo"
    }
  }
}

Renforcement par champ

Lors de l'utilisation de l'extracteur linéaire, vous pouvez appliquer un boost par champ pour ajuster l'importance des correspondances dans certains champs. Par exemple, disons que vous interrogez quatre champs : deux champs semantic_text et deux champs text:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field_1", "text_field_2" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Par défaut, chaque champ est pondéré de manière égale dans son groupe (lexical ou sémantique). La répartition des points est la suivante :

En d'autres termes, chaque champ représente 25% du score total.

Nous pouvons utiliser la syntaxe field^boost pour ajouter un boost par champ à n'importe quel champ. Appliquons un boost de 2 à semantic_text_field_1 et text_field_1:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1^2", "semantic_text_field_2", "text_field_1^2", "text_field_2" ]
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

La répartition des points est maintenant la suivante :

Chaque groupe de requêtes est toujours pondéré de manière égale, mais la pondération des champs à l'intérieur des groupes a changé :

• semantic_text_field_1 est 66% du score du groupe de requêtes sémantiques, 33% du score total
• text_field_1 est 66% du score du groupe de requêtes lexicales, 33% du score total

Résolution sur les caractères génériques

Vous pouvez utiliser le caractère générique * dans le paramètre fields pour faire correspondre plusieurs champs. Si l'on reprend l'exemple ci-dessus, cette requête est fonctionnellement équivalente à l'interrogation explicite des sitesemantic_text_field_1, semantic_text_field_2 et text_field_1:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_*", "*_field_1" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Il est intéressant de noter que le modèle *_field_1 correspond à la fois à text_field_1 et à semantic_text_field_1. La requête sera exécutée comme si chacun des champs avait été explicitement interrogé. Le fait que le site semantic_text_field_1 corresponde aux deux modèles ne pose pas de problème ; tous les noms de champ correspondant sont dédupliqués avant l'exécution de la requête.

Vous pouvez utiliser les caractères génériques de différentes manières :

• Correspondance des préfixes (ex : *_text_field)
• Correspondance en ligne (ex : semantic_*_field)
• Correspondance des suffixes (ex : semantic_text_field_*)

Vous pouvez également utiliser plusieurs caractères génériques pour appliquer une combinaison des éléments ci-dessus, par exemple *_text_field_*.

Champs de requête par défaut

Le format d'interrogation à champs multiples vous permet également d'interroger un index dont vous ignorez tout. Si vous omettez le paramètre fields, il interrogera tous les champs spécifiés par le paramètre d'indexation index.query.default_field:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Par défaut, index.query.default_field est défini comme *. Ce caractère générique permet de résoudre tous les types de champs de l'index qui prennent en charge les requêtes de termes, ce qui est le cas de la plupart d'entre eux. Les exceptions sont les suivantes :

• dense_vector champs
• rank_vector champs
• Champs de géométrie : geo_point, shape

Cette fonctionnalité est particulièrement utile lorsque vous souhaitez effectuer une recherche hybride sur un index fourni par un tiers. Le format d'interrogation à champs multiples vous permet d'exécuter une requête appropriée de manière simple. Il suffit d'exclure le paramètre fields pour que tous les champs applicables soient interrogés.

Conclusion

Le problème de la plage de scores peut faire de la recherche hybride efficace un casse-tête à mettre en œuvre, en particulier lorsque l'on ne dispose que de peu d'informations sur l'index interrogé ou sur les points de terminaison d'inférence utilisés. Le format d'interrogation à champs multiples pour les extracteurs linéaires et RRF atténue cette difficulté en intégrant une approche de recherche hybride automatisée, basée sur le regroupement de requêtes, dans une API simple et facile d'accès. Des fonctionnalités supplémentaires, telles que le renforcement par champ, la résolution des caractères génériques et les champs de requête par défaut, permettent d'étendre les fonctionnalités à de nombreux cas d'utilisation.

Essayez le format d'interrogation à champs multiples dès aujourd'hui

Vous pouvez tester les extracteurs linéaires et RRF avec le format de requête multi-champs dans des projets Elasticsearch Serverless entièrement gérés avec un essai gratuit. Il est également disponible en version stack à partir de 8.19 & 9.1.

Démarrez en quelques minutes sur votre environnement local à l'aide d'une simple commande :

curl -fsSL https://elastic.co/start-local | sh

Cet article vous montrera comment construire un agent d'IA pour les RH en utilisant GPT-OSS et Elastic Agent Builder. L'agent peut répondre à vos questions sans envoyer de données à OpenAI, Anthropic ou tout autre service externe.

Nous allons utiliser LM Studio pour servir GPT-OSS localement et le connecter à Elastic Agent Builder.

À la fin de cet article, vous disposerez d'un agent d'IA personnalisé capable de répondre à des questions en langage naturel sur les données de vos employés, tout en conservant un contrôle total sur vos informations et votre modèle.

Produits requis

Pour cet article, vous avez besoin de :

• Elastic Cloud hébergé 9.2, déploiement sans serveur ou local.
• Machine avec 32 Go de RAM recommandée (minimum 16 Go pour GPT-OSS 20B)
• LM Studio installé
• Docker Desktop installé

Pourquoi utiliser GPT-OSS ?

Avec un LLM local, vous avez la possibilité de le déployer dans votre propre infrastructure et de l'adapter à vos besoins. Tout cela en gardant le contrôle sur les données que vous partagez avec le modèle et, bien sûr, sans avoir à payer de licence à un fournisseur externe.

OpenAI a publié GPT-OSS le 5 août 2025, dans le cadre de son engagement envers l'écosystème des modèles ouverts.

Le modèle de paramètres 20B offre :

• Capacités d'utilisation des outils
• Inférence efficace
• Compatible avec le SDK OpenAI
• Compatible avec les flux de travail agentiques

Comparaison des points de repère :

Architecture de la solution

L'architecture fonctionne entièrement sur votre machine locale. Elastic (exécuté dans Docker) communique directement avec votre LLM local via LM Studio, et Elastic Agent Builder utilise cette connexion pour créer des agents d'IA personnalisés qui peuvent interroger les données de vos employés.

Pour plus de détails, consultez cette documentation.

Construire un agent d'IA pour les RH : étapes

Nous diviserons la mise en œuvre en 5 étapes :

1. Configurer LM studio avec un modèle local
2. Déployer Elastic local avec Docker
3. Créer le connecteur OpenAI dans Elastic
4. Téléchargement des données des employés vers Elasticsearch
5. Créez et testez votre agent d'intelligence artificielle

Étape 1 : Configurer LM Studio avec GPT-OSS 20B

LM Studio est une application conviviale qui vous permet d'exécuter localement de grands modèles linguistiques sur votre ordinateur. Il fournit un serveur d'API compatible avec OpenAI, ce qui facilite l'intégration avec des outils tels qu'Elastic sans processus de configuration complexe. Pour plus de détails, reportez-vous à la documentation de LM Studio.

Tout d'abord, téléchargez et installez LM Studio depuis le site officiel. Une fois installée, ouvrez l'application.

Dans l'interface de LM Studio :

1. Allez dans l'onglet recherche et cherchez "GPT-OSS"
2. Sélectionnez le site openai/gpt-oss-20b à partir d'OpenAI
3. Cliquez sur télécharger

La taille de ce modèle devrait être d'environ 12,10 Go. Le téléchargement peut prendre quelques minutes, en fonction de votre connexion internet.

Une fois le modèle téléchargé :

1. Aller dans l'onglet du serveur local
2. Sélectionner l'openai/gpt-oss-20b
3. Utiliser le port par défaut 1234
4. Dans le panneau de droite, cliquez sur Charger et réglez la longueur du contexte sur 40K ou plus.

5. Cliquez sur démarrer le serveur

Vous devriez voir ceci si le serveur est en cours d'exécution.

[LM STUDIO SERVER] Success! HTTP server listening on port 1234
[LM STUDIO SERVER] Supported endpoints:
[LM STUDIO SERVER] ->	GET  http://localhost:1234/v1/models
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/responses
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/chat/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/embeddings
Server started.

Étape 2 : Déployer Elastic local avec Docker

Nous allons maintenant configurer Elasticsearch et Kibana localement à l'aide de Docker. Elastic fournit un script pratique qui gère l'ensemble du processus d'installation. Pour plus de détails, voir la documentation officielle.

Exécuter le script start-local

Exécutez la commande suivante dans votre terminal :

curl -fsSL https://elastic.co/start-local | sh

Ce script va :

• Télécharger et configurer Elasticsearch et Kibana
• Démarrer les deux services à l'aide de Docker Compose
• Activation automatique d'une licence d'essai Platinum de 30 jours

Résultats attendus

Attendez le message suivant et enregistrez le mot de passe et la clé API indiqués ; vous en aurez besoin pour accéder à Kibana :

🎉 Congrats, Elasticsearch and Kibana are installed and running in Docker!
🌐 Open your browser at http://localhost:5601
   Username: elastic
   Password: KSUlOMNr
🔌 Elasticsearch API endpoint: http://localhost:9200
🔑 API key: cnJGX0pwb0JhOG00cmNJVklUNXg6cnNJdXZWMnM4bncwMllpQlFlUTlWdw==
Learn more at https://github.com/elastic/start-local

Accéder à Kibana

Ouvrez votre navigateur et naviguez vers :

http://localhost:5601

Connectez-vous en utilisant les informations d'identification obtenues dans la sortie du terminal.

Activer le constructeur d'agents

Une fois connecté à Kibana, naviguez vers Management > AI > Agent Builder et activez l'Agent Builder.

Étape 3 : Créer le connecteur OpenAI dans Elastic

Nous allons maintenant configurer Elastic pour qu'il utilise votre LLM local.

Connecteurs d'accès

1. Dans Kibana
2. Allez dans Paramètres du projet > Gestion
3. Sous Alertes et aperçus, sélectionnez Connecteurs
4. Cliquez sur Créer un connecteur

Configurer le connecteur

Sélectionnez OpenAI dans la liste des connecteurs. LM Studio utilise le SDK OpenAI, ce qui le rend compatible.

Remplissez les champs avec ces valeurs :

• Nom du connecteur : LM Studio - GPT-OSS 20B
• Sélectionnez un fournisseur OpenAI : Autre (Service compatible avec l'OpenAI)
• URL : http://host.docker.internal:1234/v1/chat/completions
• Modèle par défaut : openai/gpt-oss-20b
• Clé API : testkey-123 (n'importe quel texte fonctionne, car le serveur LM Studio ne nécessite pas d'authentification).

Pour terminer la configuration, cliquez sur Save & test.

Important : Activez l'option "Enable native function calling" (activer l'appel de fonctions natives) ; cette option est nécessaire pour que l'Agent Builder fonctionne correctement. Si vous ne l'activez pas, vous obtiendrez une erreur No tool calls found in the response.

Tester la connexion

Elastic devrait automatiquement tester la connexion. Si tout est configuré correctement, vous obtiendrez un message de réussite comme celui-ci :

Réponse :

{
  "status": "ok",
  "data": {
    "id": "chatcmpl-flj9h0hy4wcx4bfson00an",
    "object": "chat.completion",
    "created": 1761189456,
    "model": "openai/gpt-oss-20b",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hello! 👋 How can I assist you today?",
          "reasoning": "Just greet.",
          "tool_calls": []
        },
        "logprobs": null,
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 69,
      "completion_tokens": 23,
      "total_tokens": 92
    },
    "stats": {},
    "system_fingerprint": "openai/gpt-oss-20b"
  },
  "actionId": "ee1c3aaf-bad0-4ada-8149-118f52dad757"
}

Étape 4 : Téléchargement des données des employés vers Elasticsearch

Nous allons maintenant télécharger l'ensemble de données relatives aux employés des RH afin de montrer comment l'agent travaille avec des données sensibles. J'ai généré un ensemble de données fictives avec cette structure.

Structure de l'ensemble de données

{
  "employee_id": "0f4dce68-2a09-4cb1-b2af-6bcb4821539b",
  "full_name": "Daffi Stiebler",
  "email": "lscutchings0@huffingtonpost.com",
  "date_of_birth": "1975-06-20T15:39:36Z",
  "hire_date": "2025-07-28T00:10:45Z",
  "job_title": "Physical Therapy Assistant",
  "department": "HR",
  "salary": "108455",
  "performance_rating": "Needs Improvement",
  "years_of_experience": 2,
  "skills": "Java",
  "education_level": "Master's Degree",
  "manager": "Carl MacGibbon",
  "emergency_contact": "Leigha Scutchings",
  "home_address": "5571 6th Park"
}

Créer l'index avec les correspondances

Tout d'abord, créez l'index avec les correspondances appropriées. Notez que nous utilisons des champs semantic_text pour certains champs clés ; cela permet des capacités de recherche sémantique pour notre index.

​​PUT hr-employees
{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date"
      },
      "employee_id": {
        "type": "keyword"
      },
      "full_name": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "email": {
        "type": "keyword"
      },
      "date_of_birth": {
        "type": "date",
        "format": "iso8601"
      },
      "hire_date": {
        "type": "date",
        "format": "iso8601"
      },
      "job_title": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "department": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "salary": {
        "type": "double"
      },
      "performance_rating": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "years_of_experience": {
        "type": "long"
      },
      "skills": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "education_level": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "manager": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "emergency_contact": {
        "type": "keyword"
      },
      "home_address": {
        "type": "keyword"
      },
      "employee_semantic": {
        "type": "semantic_text"
      }
    }
  }
}

Index avec Bulk API

Copiez et collez le jeu de données dans votre Dev Tools dans Kibana et exécutez-le :

POST hr-employees/_bulk
{"index": {}}
{"employee_id": "57728b91-e5d7-4fa8-954a-2384040d3886", "full_name": "Filide Gane", "email": "vhallahan1@booking.com", "job_title": "Business Systems Development Analyst", "department": "Marketing", "salary": "$52330.27", "performance_rating": "Meets Expectations", "years_of_experience": 12, "skills": "Java", "education_level": "Bachelor's Degree", "date_of_birth": "2000-02-07T16:49:32Z", "hire_date": "2023-11-07T13:03:16Z", "manager": "Freedman Kings", "emergency_contact": "Vilhelmina Hallahan", "home_address": "75 Dennis Junction"}
{"index": {}}
{"employee_id": "...", ...}

Vérifier les données

Exécutez une requête pour vérifier :

GET hr-employees/_search

Étape 5 : Créer et tester votre agent d'intelligence artificielle

Une fois tout configuré, il est temps de créer un agent d'IA personnalisé à l'aide d'Elastic Agent Builder. Pour plus de détails, voir la documentation Elastic.

Ajouter le connecteur

Avant de pouvoir créer notre nouvel agent, nous devons configurer notre Agent builder pour qu'il utilise notre connecteur personnalisé appelé LM Studio - GPT-OSS 20B, car le connecteur par défaut est Elastic Managed LLM. Pour cela, nous devons aller dans Project Setting > Management > GenAI Settings; nous sélectionnons alors celui que nous avons créé et cliquons sur Save.

Agent d'accès Constructeur

1. Aller aux agents
2. Cliquez sur Créer un nouvel agent

Configurer l'agent

Pour créer un nouvel agent, les champs obligatoires sont l'identifiant de l'agent, le nom d'affichage et les instructions d'affichage.

Mais il existe d'autres options de personnalisation, comme les instructions personnalisées qui indiquent comment votre agent va se comporter et interagir avec vos outils, à la manière d'une invite système, mais pour notre agent personnalisé. Les étiquettes permettent d'organiser les agents, la couleur de l'avatar et le symbole de l'avatar.

Ceux que j'ai choisis pour notre agent sur la base de l'ensemble des données sont les suivants :

Agent ID : hr_assistant

Instructions personnalisées :

You are an HR Analytics Assistant that helps answer questions about employee data.
When responding to queries:
- Provide clear, concise answers
- Include relevant employee details (name, department, salary, skills)
- Format monetary values with currency symbols
- Be professional and maintain data confidentiality

Étiquettes : Human Resources et GPT-OSS

Nom d'affichage : HR Analytics Assistant

Description de l'affichage :

A specialized AI assistant for Human Resources that helps analyze employee data, compensation, performance metrics, and talent management. Ask questions about employees, departments, salaries, or performance analytics.

Une fois toutes les données saisies, nous pouvons cliquer sur Enregistrer notre nouvel agent.

Tester l'agent

Vous pouvez désormais poser des questions en langage naturel sur les données de vos employés, et GPT-OSS 20B comprendra l'intention et générera une réponse appropriée.

Prompt :

Which employee is the one with the highest salary in the hr-employees index?

Réponse :

Le processus de l'agent a été le suivant :

1. Comprendre votre question à l'aide du connecteur GPT-OSS

2. Générer la requête Elasticsearch appropriée (à l'aide des outils intégrés ou d'ES|QL personnalisés)

3. Récupérer les enregistrements des salariés correspondants

4. Présenter les résultats en langage naturel avec un formatage approprié

Contrairement à la recherche lexicale traditionnelle, l'agent alimenté par GPT-OSS comprend l'intention et le contexte, ce qui facilite la recherche d'informations sans connaître les noms exacts des champs ou la syntaxe de la requête. Pour plus de détails sur le processus de réflexion de l'agent, voir cet article.

Conclusion

Dans cet article, nous avons construit un agent d'IA personnalisé à l'aide de l'Agent Builder d'Elastic pour se connecter au modèle OpenAI GPT-OSS fonctionnant localement. En déployant à la fois Elastic et le LLM sur votre machine locale, cette architecture vous permet de tirer parti des capacités d'IA générative tout en conservant un contrôle total sur vos données, le tout sans envoyer d'informations à des services externes.

Nous avons utilisé GPT-OSS 20B à titre expérimental, mais les modèles officiellement recommandés pour Elastic Agent Builder sont référencés ici. Si vous avez besoin de capacités de raisonnement plus avancées, il existe également la variante de paramètre 120B qui est plus performante pour les scénarios complexes, bien qu'elle nécessite une machine plus sophistiquée pour fonctionner localement. Pour plus de détails, consultez la documentation officielle d'OpenAI.

Il y a quelques semaines, nous avons eu l'incroyable opportunité de sponsoriser Cal Hacks 12.0, l'un des plus grands hackathons en personne avec plus de 2000 participants venus du monde entier. Nous avons proposé une piste de prix dédiée à la meilleure utilisation d'Elastic Agent Builder sur Serverless, et la réponse a été phénoménale. En seulement 36 heures, nous avons reçu 29 soumissions qui utilisaient Agent Builder de manière créative, de la construction d'outils de renseignement sur les incendies de forêt aux validateurs StackOverflow.

Au-delà des projets impressionnants, l'expérience de Cal Hacks 12.0 nous a également apporté quelque chose de tout aussi précieux : un retour d'information rapide et non filtré de la part de développeurs qui découvrent notre pile pour la première fois. Les hackathons sont des tests de pression uniques, avec des délais serrés, une absence totale de connaissances préalables et des obstacles imprévisibles (comme les fameuses pannes de WiFi). Ils révèlent exactement les points forts de l'expérience du développeur et ceux sur lesquels il faut encore travailler. Cela est d'autant plus important aujourd'hui que les développeurs interagissent avec la pile Elastic de nouvelles façons, de plus en plus par le biais de flux de travail pilotés par LLM. Dans cet article de blog, nous allons approfondir ce que les participants ont construit avec Agent Builder et ce que nous avons appris au cours du processus.

Les projets gagnants

Première place : AgentOverflow

Stack Overflow reconstruit pour l'ère du LLM et de l'agent.

Pour en savoir plus sur AgentOverflow , cliquez ici.

AgentOverflow s'attaque à un problème que rencontrent la plupart des développeurs d'IA : Les LLM hallucinent, les historiques de conversation disparaissent et les développeurs perdent du temps à résoudre les mêmes problèmes.

AgentOverflow capture, valide et fait réapparaître de véritables paires problème-solution, afin que les développeurs puissent sortir de la spirale de l'hallucination et livrer plus rapidement.

Comment cela fonctionne-t-il ?

1. Partager JSON - le "schéma de solution".

Un clic à partir d'un partage de Claude permet de récupérer, d'extraire et d'assembler une solution de partage JSON, qui est un format structuré contenant :

• Problème
• Contexte
• Code
• Balises
• Vérification des étapes de la solution.

Un validateur (LAVA) vérifie et renforce la structure, l'utilisateur ajoute une ligne de contexte supplémentaire, puis le tout est stocké et indexé dans Elasticsearch.

2. Trouver la solution

Lorsque vous êtes bloqué, cliquez sur Find Solution et AgentOverflow scrapera votre conversation actuelle, l'utilisera pour construire une requête, et lancera une recherche hybride Elasticsearch pour remonter à la surface :

• Corrections classées et validées par la communauté
• Les invites exactes qui ont résolu le problème à l'origine

Cela permet aux développeurs de copier, coller et débloquer rapidement leur session en cours.

3. MCP - injection de contexte pour les LLM

En se connectant aux solutions structurées stockées dans Elasticsearch via MCP (Model Context Protocol), les LLM sont alimentés en contexte à haut signal (code, journaux, configurations, corrections antérieures) au moment de l'exécution sans bruit supplémentaire.

AgentOverflow utilise Agent Builder avec Elasticsearch comme couche de mémoire structurée qui injecte un contexte pertinent dans les LLM. Ils passent ainsi du statut de chatbots passifs à celui de résolveurs de problèmes conscients du contexte.

Deuxième prix : MarketMind

Une vue interprétable en temps réel de l'énergie du marché, alimentée par six agents élastiques.

Pour en savoir plus sur MarketMind , cliquez ici.

MarketMind a gagné sa place en offrant aux traders débutants une plateforme qui convertit les données fragmentées du marché en signaux clairs et en temps réel. Au lieu de jongler avec l'évolution des prix, les fondamentaux, le sentiment et la volatilité sur différents outils, MarketMind consolide toutes ces informations sur une seule plateforme, aidant ainsi les traders à obtenir des informations exploitables. Ce projet a également utilisé des requêtes ES|QL complexes lors de la création de ses agents.

Comment cela fonctionne-t-il ?

1. Collecter des données de marché en temps réel

MarketMind extrait de Yahoo Finance des données sur l'évolution des cours, les fondamentaux, le sentiment, la volatilité et le risque. Ces données sont ingérées et organisées en plusieurs index Elasticsearch.

2. Six agents spécialisés analysent le marché

Chaque agent, créé avec Agent Builder, se concentre sur une couche différente du marché. Ils lisent un index Elasticsearch, calculent leurs propres mesures spécifiques au domaine et génèrent une sortie JSON standardisée avec des scores et un raisonnement.

3. Agréger les signaux dans un modèle unifié d'"énergie de marché".

Les résultats combinés apparaissent sous forme d'impulsions lumineuses autour de chaque action, indiquant si la dynamique se renforce, si le risque augmente ou si le sentiment change.

4. Visualiser les informations

Le frontend a été construit avec React et Next.js, en utilisant TypeScript, des visuels SVG basés sur la physique, et Chart.js pour les graphiques de chandeliers en direct. L'analyse brute est ainsi transformée en un retour d'information exploitable en temps réel.

Autres projets intéressants :

Voici d'autres concurrents de taille qui ont utilisé Elastic dans différentes parties de leur pile :

Vous trouverez ici la liste complète des projets qui ont été soumis à notre circuit.

Ce que nous ont appris les développeurs

• Agent Builder est convivial :

La plupart des équipes n'avaient jamais utilisé Elastic auparavant et étaient encore en mesure de créer des agents rapidement avec peu de soutien. Nous avons organisé un atelier pour ceux qui avaient besoin de plus de conseils, mais la plupart ont été en mesure d'ingérer leurs données et de créer un agent pour effectuer des actions sur ces données.

• Les LLM excellent dans les requêteskNN, mais ont encore besoin d'être guidés dans la création d'ES|QL :

Demander à ChatGPT-5 de générer des requêtes ES|QL renvoyait des informations incorrectes, mélangeant souvent ES|QL et SQL. Alimenter le LLM avec les documents dans un fichier markdown semblait être une solution viable.

• Les fonctions ES|QL en mode instantané ont fait l'objet d'une fuite dans la documentation :

Les fonctions d'agrégation FIRST et LAST ont été glissées involontairement dans nos documents ES|QL. Parce que nous avons fourni ces documents à ChatGPT, le modèle a consciencieusement utilisé ces fonctions, même si elles ne sont pas encore disponibles dans Serverless. Grâce au feedback du groupe, l'ingénierie a rapidement ouvert et fusionné un correctif pour supprimer les fonctions de la documentation publiée(PR #137341).

• Absence d'orientations spécifiques à Serverless :

Une équipe a essayé d'activer LOOKUP JOIN sur un index qui n'a pas été créé en mode consultation. Le message d'erreur les a envoyés à la recherche de commandes qui n'existent pas sur Serverless. Nous avons relayé cette information à l'équipe produit, qui a immédiatement ouvert un correctif pour un message actionnable spécifique à Serverless. À plus long terme, l'objectif est de masquer entièrement la complexité de la réindexation(problème n° 4838).

• Valeur des événements en personne :

Les hackathons en ligne sont formidables, mais rien n'égale la boucle de rétroaction rapide que vous obtenez lorsque vous déboguez épaule contre épaule avec des constructeurs. Nous avons vu des équipes intégrer Agent Builder dans différents cas d'utilisation, repérer où l'expérience des développeurs avec ES|QL pouvait être améliorée, et résoudre les problèmes beaucoup plus rapidement qu'en essayant de le faire sur des canaux asynchrones.

Conclusion

Cal Hacks 12.0 nous a offert plus qu'un week-end de démonstrations intéressantes ; il nous a également permis de comprendre comment les nouveaux développeurs interagissent avec la pile Elastic. En seulement 36 heures, nous avons vu des équipes prendre en main Agent Builder, ingérer des données dans Elasticsearch, concevoir des systèmes multi-agents et tester nos fonctionnalités de différentes manières. L'événement nous a également rappelé pourquoi les événements en personne sont importants. Les boucles de rétroaction rapides, les conversations réelles et le débogage pratique nous ont aidés à comprendre les besoins actuels des développeurs. Nous sommes ravis d'apporter ce que nous avons appris à l'équipe d'ingénieurs. Nous vous donnons rendez-vous au prochain hackathon.

Cet article est le complément de l'article "Creating an LLM Agent newsroom with A2A protocol and MCP in Elasticsearch !", qui expliquait les avantages de la mise en œuvre des architectures A2A et MCP au sein du même agent afin de profiter pleinement des avantages uniques des deux frameworks. Un référentiel est disponible si vous souhaitez exécuter la démo par vous-même.

Voyons comment les agents de notre salle de presse collaborent en utilisant à la fois A2A et MCP pour produire un article. Le référentiel d'accompagnement pour voir les agents en action est disponible ici.

Étape 1 : Attribution de l'histoire

Le chef de l'information (agissant en tant que client) attribue un sujet :

{
  "message_type": "task_request",
  "sender": "news_chief",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "assignment": {
      "topic": "Renewable Energy Adoption in Europe",
      "angle": "Policy changes driving solar and wind expansion",
      "target_length": 1200,
      "deadline": "2025-09-30T18:00:00Z"
    }
  }
}

Étape 2 : Le journaliste demande des recherches

L'agent rapporteur reconnaît qu'il a besoin d'informations générales et délègue à l'agent chercheur par l'intermédiaire de l'A2A :

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "fact_gathering",
    "parameters": {
      "queries": [
        "EU renewable energy capacity 2024",
        "Solar installations growth Europe",
        "Wind energy policy changes 2024"
      ],
      "depth": "comprehensive"
    }
  }
}

Étape 3 : Le rapporteur demande le contexte historique à l'agent d'archivage

L'agent rapporteur reconnaît que le contexte historique renforcerait l'histoire. Il délègue à l'agent d'archivage (alimenté par l'agent A2A d'Elastic), via A2A, le soin d'effectuer des recherches dans les archives d'articles de la salle de presse alimentées par Elasticsearch :

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "archive_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "search_archive",
    "parameters": {
      "query": "European renewable energy policy changes and adoption trends over past 5 years",
      "focus_areas": ["solar", "wind", "policy", "Germany", "France"],
      "time_range": "2019-2024",
      "result_count": 10
    }
  }
}

Étape 4 : L'agent d'archivage utilise l'agent Elastic A2A avec MCP

L'agent d'archivage utilise l'agent A2A d'Elastic, qui à son tour utilise MCP pour accéder aux outils Elasticsearch. Ceci démontre l'architecture hybride où A2A permet la collaboration des agents tandis que MCP fournit l'accès aux outils :

# Archive Agent using Elastic A2A Agent
async def search_historical_articles(self, query_params):
    # The Archive Agent sends a request to Elastic's A2A Agent
    elastic_response = await self.a2a_client.send_request(
        agent="elastic_agent",
        capability="search_and_analyze",
        parameters={
            "natural_language_query": query_params["query"],
            "index_pattern": "newsroom-articles-*",
            "filters": {
                "topics": query_params["focus_areas"],
                "date_range": query_params["time_range"]
            },
            "analysis_type": "trend_analysis"
        }
    )
    
    # Elastic's A2A Agent internally uses MCP tools:
    # - platform.core.search (to find relevant articles)
    # - platform.core.generate_esql (to analyze trends)
    # - platform.core.index_explorer (to identify relevant indices)
    
    return elastic_response

L'agent d'archivage reçoit des données historiques complètes de l'agent A2A d'Elastic et les renvoie au rapporteur :

{
  "message_type": "task_response",
  "sender": "archive_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "status": "completed",
    "archive_data": {
      "historical_articles": [
        {
          "title": "Germany's Energiewende: Five Years of Solar Growth",
          "published": "2022-06-15",
          "key_points": [
            "Germany added 7 GW annually 2020-2022",
            "Policy subsidies drove 60% of growth"
          ],
          "relevance_score": 0.94
        },
        {
          "title": "France Balances Nuclear and Renewables",
          "published": "2023-03-20",
          "key_points": [
            "France increased renewable target to 40% by 2030",
            "Solar capacity doubled 2021-2023"
          ],
          "relevance_score": 0.89
        }
      ],
      "trend_analysis": {
        "coverage_frequency": "EU renewable stories increased 150% since 2019",
        "emerging_themes": ["policy incentives", "grid modernization", "battery storage"],
        "coverage_gaps": ["Small member states", "offshore wind permitting"]
      },
      "total_articles_found": 47,
      "search_confidence": 0.91
    }
  }
}

Cette étape montre comment l'agent A2A d'Elastic s'intègre dans le flux de travail de la salle de presse. L'Archive Agent (un agent spécifique à la salle de presse) se coordonne avec l'A2A Agent d'Elastic (un spécialiste tiers) pour exploiter les puissantes capacités de recherche et d'analyse d'Elasticsearch. L'agent Elastic utilise MCP en interne pour accéder aux outils Elasticsearch, ce qui montre la séparation nette entre la coordination de l'agent (A2A) et l'accès aux outils (MCP).

Étape 5 : Le chercheur utilise les serveurs MCP

L'agent chercheur accède à plusieurs serveurs MCP pour recueillir des informations :

# Researcher Agent using MCP to access tools
async def gather_facts(self, queries):
    results = []
    
    # Use News API MCP Server
    news_data = await self.mcp_client.invoke_tool(
        server="news_api_mcp",
        tool="search_articles",
        parameters={
            "query": queries[0],
            "date_range": "2024-01-01 to 2024-09-30",
            "sources": ["reuters", "bloomberg", "euractiv"]
        }
    )
    
    # Use Statistics MCP Server
    stats_data = await self.mcp_client.invoke_tool(
        server="eurostat_mcp",
        tool="get_energy_statistics",
        parameters={
            "metrics": ["solar_capacity_mw", "wind_capacity_mw"],
            "countries": ["EU27"],
            "year": 2024
        }
    )
    
    # Use Fact-Checking MCP Server
    verified_facts = await self.mcp_client.invoke_tool(
        server="factcheck_mcp",
        tool="verify_claims",
        parameters={
            "claims": [
                "EU solar capacity increased 40% in 2024",
                "Germany leads in wind installations"
            ]
        }
    )
    
    return self._synthesize_research(news_data, stats_data, verified_facts)

Étape 6 : Le chercheur renvoie les données au rapporteur

L'agent chargé de la recherche renvoie la recherche complète par l'intermédiaire de l'A2A :

{
  "message_type": "task_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "status": "completed",
    "research_data": {
      "key_facts": [
        {
          "claim": "EU solar capacity reached 260 GW in 2024",
          "source": "Eurostat Q3 2024 Report",
          "confidence": 0.95,
          "verified": true
        },
        {
          "claim": "Germany installed 12 GW of wind capacity in 2024",
          "source": "German Federal Network Agency",
          "confidence": 0.92,
          "verified": true
        }
      ],
      "statistics": {
        "solar_growth_rate": "35%",
        "wind_growth_rate": "28%"
      },
      "sources_count": 15
    }
  }
}

Étape 7 : Le journaliste rédige un article

L'agent rapporteur utilise les données de recherche et ses propres capacités LLM pour rédiger l'article. Pendant la rédaction, le Reporter utilise les serveurs MCP pour le style et les modèles :

# Reporter Agent writing with MCP assistance
async def write_article(self, research_data, assignment):
    # Get style guidelines via MCP
    style_guide = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="style://editorial/ap_style_guide"
    )
    
    # Get article template via MCP
    template = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="template://articles/news_story"
    )
    
    # Generate article using LLM + research + style
    draft = await self.llm.generate(
        prompt=f"""
        Write a news article following these guidelines:
        {style_guide}
        
        Using this template:
        {template}
        
        Based on this research:
        {research_data}
        
        Assignment: {assignment}
        """
    )
    
    # Self-evaluate confidence in claims
    confidence_check = await self._evaluate_confidence(draft)
    
    return draft, confidence_check

Étape 8 : le manque de confiance déclenche une nouvelle recherche

L'agent déclarant évalue son projet et constate qu'une créance a un faible degré de confiance. Il envoie une autre demande à l'agent du chercheur :

{
  "message_type": "collaboration_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "request_type": "fact_verification",
    "claims": [
      {
        "text": "France's nuclear phase-down contributed to 15% increase in renewable capacity",
        "context": "Discussing policy drivers for renewable growth",
        "current_confidence": 0.45,
        "required_confidence": 0.80
      }
    ],
    "urgency": "high"
  }
}

Le chercheur vérifie l'allégation à l'aide des serveurs MCP de vérification des faits et renvoie les informations mises à jour :

{
  "message_type": "collaboration_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "verified_claims": [
      {
        "original_claim": "France's nuclear phase-down contributed to 15% increase...",
        "verified_claim": "France's renewable capacity increased 18% in 2024, partially offsetting reduced nuclear output",
        "confidence": 0.88,
        "corrections": "Percentage was 18%, not 15%; nuclear phase-down is gradual, not primary driver",
        "sources": ["RTE France", "French Energy Ministry Report 2024"]
      }
    ]
  }
}

Étape 9 : Le journaliste révise le texte et le soumet au rédacteur en chef

Le rapporteur incorpore les faits vérifiés et envoie le projet complet à l'agent rédacteur par l'intermédiaire de l'A2A :

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "editor_agent",
  "payload": {
    "task_id": "edit_renewable_story",
    "parent_task_id": "story_renewable_energy_2024",
    "content": {
      "headline": "Europe's Renewable Revolution: Solar and Wind Surge 30% in 2024",
      "body": "[Full article text...]",
      "word_count": 1185,
      "sources": [/* array of sources */]
    },
    "editing_requirements": {
      "check_style": true,
      "check_facts": true,
      "check_seo": true
    }
  }
}

Étape 10 : Examens des éditeurs à l'aide des outils MCP

L'agent rédacteur utilise plusieurs serveurs MCP pour réviser l'article :

# Editor Agent using MCP for quality checks
async def review_article(self, content):
    # Grammar and style check
    grammar_issues = await self.mcp_client.invoke_tool(
        server="grammarly_mcp",
        tool="check_document",
        parameters={"text": content["body"]}
    )
    
    # SEO optimization check
    seo_analysis = await self.mcp_client.invoke_tool(
        server="seo_mcp",
        tool="analyze_content",
        parameters={
            "headline": content["headline"],
            "body": content["body"],
            "target_keywords": ["renewable energy", "Europe", "solar", "wind"]
        }
    )
    
    # Plagiarism check
    originality = await self.mcp_client.invoke_tool(
        server="plagiarism_mcp",
        tool="check_originality",
        parameters={"text": content["body"]}
    )
    
    # Generate editorial feedback
    feedback = await self._generate_feedback(
        grammar_issues, 
        seo_analysis, 
        originality
    )
    
    return feedback

Le rédacteur en chef approuve l'article et le transmet :

{
  "message_type": "task_response",
  "sender": "editor_agent",
  "receiver": "reporter_agent",
  "payload": {
    "status": "approved",
    "quality_score": 9.2,
    "minor_edits": [
      "Changed 'surge' to 'increased' in paragraph 3 for AP style consistency",
      "Added Oxford comma in list of countries"
    ],
    "approved_content": "[Final edited article]"
  }
}

Étape 11 : L'éditeur publie via CI/CD

Enfin, l'agent imprimeur publie l'article approuvé en utilisant les serveurs MCP pour le CMS et le pipeline CI/CD :

# Publisher Agent publishing via MCP
async def publish_article(self, content, metadata):
    # Upload to CMS via MCP
    cms_result = await self.mcp_client.invoke_tool(
        server="wordpress_mcp",
        tool="create_post",
        parameters={
            "title": content["headline"],
            "body": content["body"],
            "status": "draft",
            "categories": metadata["categories"],
            "tags": metadata["tags"],
            "featured_image_url": metadata["image_url"]
        }
    )
    
    post_id = cms_result["post_id"]
    
    # Trigger CI/CD deployment via MCP
    deploy_result = await self.mcp_client.invoke_tool(
        server="cicd_mcp",
        tool="trigger_deployment",
        parameters={
            "pipeline": "publish_article",
            "environment": "production",
            "post_id": post_id,
            "schedule": "immediate"
        }
    )
    
    # Track analytics
    await self.mcp_client.invoke_tool(
        server="analytics_mcp",
        tool="register_publication",
        parameters={
            "post_id": post_id,
            "publish_time": datetime.now().isoformat(),
            "story_id": metadata["story_id"]
        }
    )
    
    return {
        "status": "published",
        "post_id": post_id,
        "url": f"https://newsroom.example.com/articles/{post_id}",
        "deployment_id": deploy_result["deployment_id"]
    }

L'éditeur confirme la publication via A2A :

{
  "message_type": "task_complete",
  "sender": "printer_agent",
  "receiver": "news_chief",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "status": "published",
    "publication": {
      "url": "https://newsroom.example.com/articles/renewable-europe-2024",
      "published_at": "2025-09-30T17:45:00Z",
      "post_id": "12345"
    },
    "workflow_metrics": {
      "total_time_minutes": 45,
      "agents_involved": ["reporter", "researcher", "archive", "editor", "printer"],
      "iterations": 2,
      "mcp_calls": 12
    }
  }
}

Voici la séquence complète du flux de travail A2A dans le référentiel d'accompagnement en utilisant les mêmes agents que ceux décrits ci-dessus.

Conclusion

L'A2A et le MCP ont tous deux un rôle important à jouer dans le paradigme moderne de l'infrastructure augmentée-LLM. L'A2A offre une certaine souplesse pour les systèmes multi-agents complexes, mais potentiellement moins de portabilité et une plus grande complexité opérationnelle. MCP offre une approche standardisée pour l'intégration des outils, plus simple à mettre en œuvre et à maintenir, bien qu'il ne soit pas conçu pour gérer l'orchestration multi-agents.

Le choix n'est pas binaire. Comme le montre notre exemple de salle de presse, les systèmes les plus sophistiqués et les plus efficaces soutenus par le LLM combinent souvent les deux approches : les agents se coordonnent et se spécialisent par le biais de protocoles A2A tout en accédant à leurs outils et à leurs ressources par le biais de serveurs MCP. Cette architecture hybride offre les avantages organisationnels des systèmes multi-agents ainsi que les avantages de la normalisation et de l'écosystème du MCP. Cela suggère qu'il n'est peut-être pas nécessaire de faire un choix : il suffit d'utiliser les deux en tant qu'approche standard.

C'est à vous, en tant que développeur ou architecte, de tester et de déterminer le meilleur mélange de ces deux solutions pour obtenir le bon résultat pour votre cas d'utilisation spécifique. Comprendre les points forts, les limites et les applications appropriées de chaque approche vous permettra de construire des systèmes d'IA plus efficaces, plus faciles à maintenir et plus évolutifs.

Que vous construisiez une salle de presse numérique, une plateforme de service à la clientèle, un assistant de recherche ou toute autre application alimentée par le LLM, l'examen attentif de vos besoins de coordination (A2A) et des exigences d'accès aux outils (MCP) vous mettra sur la voie de la réussite.

Ressources supplémentaires

• Elasticsearch Agent Builder : https://www.elastic.co/docs/solutions/search/elastic-agent-builder
• Spécification A2A : https://a2a-protocol.org/latest/specification/
• Intégration A2A et MCP : https://a2a-protocol.org/latest/topics/a2a-and-mcp/
• Modèle de protocole de contexte : https://modelcontextprotocol.io

La recherche n'est pas morte, elle s'est simplement déplacée

Nous sommes donc passés d'une recherche de contexte à l'aide d'une zone de texte et de l'utilisation des informations (le contexte) renvoyées pour construire les réponses nous-mêmes, à l'utilisation du langage naturel pour dire à un agent ce que nous voulons et lui permettre de rechercher et de compiler automatiquement la réponse pour nous. Nombreux sont ceux qui, dans le monde de la technologie, soulignent ce changement et proclament que "la recherche est morte" (certes, le monde du référencement et des mots publicitaires est en train de changer: les GEO, par exemple), mais la recherche reste absolument essentielle pour les opérations agentiques - elle est simplement réalisée en grande partie à l'abri des regards par le biais d'outils.

Auparavant, les humains étaient les principaux arbitres de la pertinence subjective : chaque utilisateur a ses propres raisons d'effectuer une recherche, et son expérience personnelle influence la précision relative des résultats. Si nous voulons que les agents parviennent à la même conclusion (ou à une meilleure conclusion) que nous, nous devons nous assurer que les informations contextuelles auxquelles ils ont accès sont aussi proches que possible de notre intention subjective. Nous devons concevoir le contexte dans lequel nous fournissons les LLM en fonction de cet objectif !

Générer du contexte avec la recherche hybride

Je vous rappelle que la recherche hybride d'Elastic combine les points forts de la recherche traditionnelle par mot-clé (flexibilité syntaxique, précision des mots-clés et évaluation de la pertinence) avec la compréhension sémantique de la recherche par similarité vectorielle, et offre plusieurs techniques de reclassement. Cette synergie (il n'y a jamais eu d'usage plus vrai de ce mot !) permet d'obtenir des résultats très pertinents, avec des requêtes qui peuvent être beaucoup plus nuancées dans la manière dont elles ciblent le contenu. Il ne s'agit pas seulement d'appliquer la pertinence subjective à l'une des étapes de la recherche ; il s'agit en fait d'inclure la notation de la pertinence dans la première étape de la recherche, ainsi que tous les autres modes à la fois.

Précision supérieure & efficacité

L'utilisation d'une plateforme de données capable de fournir des services de recherche, d'extraction et de reclassement distribués en tant que principal moteur de recherche contextuelle est très judicieuse. Vous pouvez utiliser une syntaxe d'interrogation avancée pour ajouter la composante manquante de l'intention subjective et filtrer le contenu qui pourrait distraire ou brouiller la valeur des informations contextuelles renvoyées. Vous pouvez sélectionner l'une des options syntaxiques individuelles disponibles ou combiner les modalités dans une recherche unique qui cible chaque type de données de la manière qu'elle comprend le mieux, puis les combiner ou les réordonner avec le reranking. Vous pouvez filtrer la réponse pour qu'elle ne contienne que les champs/valeurs que vous souhaitez, en évitant les données superflues. Au service des agents, cette souplesse de ciblage vous permet de créer des outils extrêmement précis dans la manière dont ils récupèrent le contexte.

Raffinement du contexte (agrégations et signaux non liés au contenu)

Les agrégations peuvent être particulièrement utiles pour façonner le contenu d'un outil dans la fenêtre contextuelle. Les agrégations fournissent naturellement des faits numériques sur la forme des données contextuelles renvoyées, ce qui permet aux LLM de raisonner plus facilement et avec plus de précision. Les agrégations pouvant être imbriquées hiérarchiquement, il est facile d'ajouter des détails à plusieurs niveaux pour que le mécanisme d'apprentissage tout au long de la vie génère une compréhension plus nuancée. Les agrégations peuvent également faciliter la gestion de la taille de la fenêtre contextuelle - vous pouvez facilement réduire le résultat d'une requête de 100 000 documents à quelques centaines de tokens d'informations agrégées.

Les signaux non liés au contenu sont les indicateurs inhérents à vos données qui vous donnent une vue d'ensemble de ce que vous regardez ; il s'agit des caractéristiques supplémentaires des résultats, comme la popularité, la fraîcheur, la géolocalisation, les catégories, la diversité des hôtes ou les fourchettes de prix. Ces éléments d'information peuvent être utiles à l'agent pour évaluer l'importance du contexte qu'il a reçu. Quelques exemples simples permettent d'illustrer au mieux ce propos :

• Renforcer le contenu récemment publié et populaire - Imaginez que vous disposiez d'une base de connaissances contenant des articles. Vous souhaitez trouver des articles pertinents par rapport à la requête d'un utilisateur, mais vous voulez également favoriser les articles qui sont récents et qui ont été jugés utiles par d'autres utilisateurs (par exemple, qui ont un nombre élevé de "likes" ). Dans ce scénario, nous pouvons utiliser une recherche hybride pour trouver les articles pertinents, puis les classer en fonction de leur date de publication et de leur popularité.
• Recherche dans le domaine du commerce électronique avec ajustement des ventes et des stocks - Dans le cadre du commerce électronique, vous souhaitez montrer aux clients les produits qui correspondent à leur recherche, mais vous voulez également promouvoir les produits qui se vendent bien et qui sont en stock. Vous pouvez également déclasser les produits dont le stock est faible afin d'éviter la frustration des clients.
• Priorité aux problèmes de haute gravité dans un système de suivi des bogues - Pour une équipe de développement de logiciels, lorsqu'elle recherche des problèmes, il est essentiel de faire apparaître en premier les problèmes de haute gravité, de haute priorité et ceux qui ont été récemment mis à jour. Vous pouvez utiliser des signaux secondaires tels que "criticité" et "le plus discuté" pour pondérer les différents facteurs de manière indépendante, en veillant à ce que les questions les plus critiques et les plus activement discutées soient placées en tête.

Ces exemples de requêtes et d'autres sont disponibles dans la page de contenu Elasticsearch Labs qui les accompagne.

Renforcement de la sécurité

Un avantage essentiel de l'exploitation d'une couche de vitesse alimentée par la recherche telle qu'Elastic pour l'ingénierie contextuelle est son cadre de sécurité intégré. La plateforme d'Elastic garantit que le contexte fourni aux opérations d'IA agentique et générative respecte et protège les informations privées sensibles grâce à un contrôle d'accès granulaire basé sur les rôles (RBAC) et un contrôle d'accès basé sur les attributs (ABAC). Cela signifie que non seulement les requêtes sont traitées avec efficacité, mais aussi que les résultats sont filtrés en fonction des autorisations spécifiques de l'agent ou de l'utilisateur à l'origine de la demande.

Les agents s'exécutent en tant qu'utilisateur authentifié, de sorte que la sécurité est implicitement appliquée par le biais des fonctions de sécurité intégrées à la plateforme :

• Permissions précises : Définissez l'accès au niveau du document, du champ ou même du terme, en veillant à ce que les agents d'intelligence artificielle ne reçoivent que les données qu'ils sont autorisés à consulter.
• Contrôle d'accès basé sur les rôles (RBAC) : Attribuer des rôles aux agents ou aux utilisateurs, en leur donnant accès à des ensembles de données ou à des fonctionnalités spécifiques en fonction des responsabilités qu'ils ont définies.
• Contrôle d'accès basé sur les attributs (ABAC) : Mettre en œuvre des politiques d'accès dynamiques basées sur les attributs des données, de l'utilisateur ou de l'environnement, permettant une sécurité hautement adaptable et consciente du contexte.
• Sécurité au niveau du document (DLS) et sécurité au niveau du champ (FLS) : Ces capacités garantissent que, même au sein d'un document récupéré, seules les parties autorisées sont visibles, empêchant ainsi l'exposition d'informations sensibles.
• Intégration avec la sécurité de l'entreprise : Intégration transparente avec les systèmes de gestion des identités existants (tels que LDAP, SAML, OIDC) afin d'appliquer des politiques de sécurité cohérentes dans l'ensemble de l'entreprise.

En intégrant ces mesures de sécurité directement dans le mécanisme de récupération du contexte, Elastic agit comme un gardien sécurisé, garantissant que les agents d'intelligence artificielle opèrent dans des limites de données définies, empêchant l'exposition de données non autorisées et maintenant la conformité avec les réglementations en matière de confidentialité des données. Cela est primordial pour instaurer la confiance dans les systèmes d'IA agentique qui traitent des informations confidentielles ou exclusives.

En outre, l'utilisation d'une couche de vitesse unifiée sur les sources de données de l'entreprise permet d'alléger les charges de requêtes ad hoc inattendues sur ces référentiels que les outils agentiques créeraient. Vous disposez d'un lieu unique pour tout rechercher en temps quasi réel, et d'un lieu unique pour appliquer les contrôles de sécurité et de gouvernance.

Outils hybrides basés sur la recherche

La plateforme Elastic comporte certaines fonctionnalités de base (et d'autres sont en cours d'élaboration) qui donnent un coup de fouet à l'ingénierie contextuelle. L'essentiel est que la plateforme offre une multitude de moyens de réaliser des choses, avec la flexibilité de s'adapter, de changer et d'étendre les méthodes au fur et à mesure que l'écosystème de l'IA progresse.

Présentation de l'Agent Builder

Elastic Agent Builder est notre première incursion dans le domaine des outils d'intelligence artificielle conçus pour dialoguer avec les données que vous stockez déjà dans Elastic. Agent Builder offre une interface de chat qui permet aux utilisateurs de créer et de gérer leurs propres agents et outils dans Kibana. Il est livré avec des serveurs MCP et A2A intégrés, des API programmatiques et un ensemble d'outils système prédéfinis pour l'interrogation et l'exploration des index Elasticsearch, ainsi que pour la génération de requêtes ES|QL à partir du langage naturel. Agent Builder vous permet de créer des outils personnalisés qui ciblent et sculptent les données contextuelles renvoyées à l'agent par le biais d'une syntaxe de requête ES|QL expressive.

Comment ES|QL effectue-t-il la recherche hybride ? La capacité de base est obtenue par la combinaison du type de champ semantic_text et descommandesFORK/FUSE (FUSE utilise par défaut RRF pour fusionner les résultats de chaque fourchette). Voici un exemple simple de recherche de produit fictif :

FROM products
| FORK
  (MATCH description "high performance gaming laptop" | EVAL search_type = "bm25"),
  (MATCH description_semantic "high performance gaming laptop" | EVAL search_type = "semantic")
| FUSE 
| LIMIT 20
| KEEP product_name, description, _score, search_type

La clause EVAL incluse dans chacune des branches FORK de l'exemple ci-dessus n'est pas strictement nécessaire ; elle n'est incluse que pour démontrer comment vous pouvez suivre la modalité de recherche à partir de laquelle un résultat donné a été retourné.

Recherche de modèles

Supposons que vous souhaitiez faire pointer vos propres outils agentiques externes vers votre déploiement Elastic. Au lieu d'ES|QL, vous souhaitez utiliser des extracteurs à plusieurs niveaux ou réutiliser la syntaxe DSL existante que vous avez développée, et vous voulez également pouvoir contrôler les entrées acceptées par la requête, la syntaxe utilisée pour exécuter la recherche et les champs renvoyés dans le résultat. Les modèles de recherche permettent aux utilisateurs de définir des structures prédéfinies pour les modèles de recherche courants, ce qui améliore l'efficacité et la cohérence de la recherche de données. Ceci est particulièrement bénéfique pour les outils agentiques qui interagissent avec les API de recherche, car ils aident à normaliser le code standard et permettent une itération plus rapide de la logique de recherche. Et si vous devez modifier l'un de ces facteurs, il vous suffit de mettre à jour le modèle de recherche et voilà, les changements sont appliqués. Si vous cherchez un exemple de modèles de recherche en action avec des outils agentiques, jetez un coup d'œil au blog d'Elasticsearch Labs "MCP for intelligent search", qui utilise un modèle de recherche derrière un appel d'outil à partir d'un serveur MCP externe.

Flux de travail intégrés (FTW !)

L'une des choses les plus difficiles à gérer dans notre nouveau monde d'IA agentique est la nature non déterministe des agents "raisonnants" semi-autonomes et autodirigés. L'ingénierie contextuelle est une discipline essentielle de l'IA agentique : il s'agit des techniques qui permettent de limiter les conclusions possibles de notre agent à ce que nous connaissons de la vérité de terrain. Même avec une fenêtre contextuelle très précise et pertinente (lorsque nous sortons du domaine des faits numériques), il nous manque toujours cette petite assurance que la réponse de l'agent est entièrement reproductible et fiable.

Lorsque vous soumettez plusieurs fois la même demande à un agent, les réponses peuvent être essentiellement les mêmes, avec juste une petite différence dans la réponse. C'est généralement bien pour les requêtes simples, peut-être à peine perceptible, et nous pouvons essayer de façonner le résultat à l'aide de techniques d'ingénierie contextuelle. Mais plus les tâches que nous demandons à nos agents sont complexes, plus il y a de chances qu'une ou plusieurs sous-tâches introduisent une variance qui modifie légèrement le résultat final. La situation s'aggravera probablement à mesure que nous commencerons à nous appuyer davantage sur les communications entre agents, et ces écarts deviendront cumulatifs. Cela confirme l'idée que les outils avec lesquels nos agents interagissent doivent être très souples et adaptables pour cibler précisément les données contextuelles, et qu'ils doivent répondre dans un format de sortie attendu. Il indique également que pour de nombreux cas d'utilisation, nous avons besoin de diriger les interactions entre l'agent et l'outil - c'est là que les flux de travail entrent en jeu !

Elastic disposera bientôt de flux de travail entièrement personnalisables, intégrés au cœur de la plateforme. Ces flux de travail pourront fonctionner avec des agents et des outils de manière bidirectionnelle, de sorte que les flux de travail pourront appeler des agents et des outils, et que les agents et les outils pourront appeler des flux de travail. L'intégration complète de ces capacités dans la même plateforme d'IA de recherche, où toutes vos données sont stockées, sera un facteur de transformation. Bientôt, très bientôt !

Elastique comme la banque de mémoire unifiée

En tant que plateforme de données distribuées conçue pour la recherche en temps quasi réel, Elastic remplit naturellement les fonctions de mémoire à long terme pour les systèmes d'IA agentique. Avec l'expérience de chat intégrée d'Agent Builder, nous disposons également d'un suivi et d'une gestion de la mémoire à court terme et de l'historique des chats. Et comme toute la plateforme est fondée sur l'API, il est extrêmement facile d'utiliser Elastic comme plateforme pour conserver les résultats contextuels d'un outil (et pouvoir s'y référer ultérieurement) qui pourraient dépasser la fenêtre contextuelle de l'agent ; cette technique est parfois appelée "prise de notes" dans les cercles de l'ingénierie contextuelle.

Le fait de disposer d'une mémoire à court terme et d'une mémoire à long terme sur la même plateforme de recherche présente de nombreux avantages intrinsèques : imaginez que vous puissiez utiliser les historiques de chat et les réponses contextuelles persistantes pour influencer sémantiquement les futures interactions de chat, ou pour effectuer une analyse des menaces, ou pour créer des produits de données persistants générés automatiquement à partir d'appels d'outils fréquemment répétés... Les possibilités sont infinies !

Conclusion

L'émergence de grands modèles de langage a modifié la façon dont nous pouvons faire correspondre le contenu et les méthodes que nous utilisons pour interroger nos données. Nous nous éloignons rapidement de notre monde actuel, où les humains effectuent les recherches, les considérations contextuelles et le raisonnement logique pour répondre à leurs propres questions, pour passer à un monde où ces étapes sont largement automatisées grâce à l'IA agentique. Pour que nous puissions faire confiance aux réponses générées que nous recevons, nous devons avoir l'assurance que l'agent a pris en compte toutes les informations les plus pertinentes (y compris le facteur de la pertinence subjective) pour générer sa réponse. Notre principale méthode pour rendre l'IA agentique digne de confiance consiste à ancrer les outils qui récupèrent un contexte supplémentaire grâce aux techniques de RAG et d'ingénierie contextuelle, mais la manière dont ces outils effectuent la récupération initiale peut être déterminante pour la précision de la réponse.

La plateforme d'IA Elastic Search offre la flexibilité et les avantages de la recherche hybride, ainsi que plusieurs fonctionnalités intégrées qui aident l'IA agentique en termes de précision, de performance et d'évolutivité ; en d'autres termes, Elastic est une plateforme fantastique pour plusieurs aspects de l'ingénierie contextuelle ! En normalisant la recherche de contexte via une plateforme de recherche, nous simplifions les opérations de l'outil agentique sur plusieurs fronts - et comme l'oxymore "ralentir pour aller plus vite", la simplicité au niveau de la couche de génération de contexte signifie une IA agentique plus rapide et plus digne de confiance.

Une nouvelle façon d'interagir avec les données

L'IA générative (genAI) et l'IA agentique agissent différemment de la recherche traditionnelle. Alors que nous commencions à rechercher des informations par une recherche ("laissez-moi chercher cela sur Google..."), l'action initiale de l'IA générique et des agents se fait généralement par le biais d'un langage naturel saisi dans une interface de dialogue en ligne. L'interface de chat est une discussion avec un LLM qui utilise sa compréhension sémantique pour transformer notre question en une réponse distillée, une réponse résumée semblant provenir d'un oracle qui a une connaissance étendue de toutes sortes d'informations. Ce qui fait vraiment la différence, c'est la capacité du LLM à produire des phrases cohérentes et réfléchies qui rassemblent les éléments de connaissance qu'il fait apparaître - même s'ils sont inexacts ou totalement hallucinés, ils ont une certaine véracité.

Cette vieille barre de recherche avec laquelle nous avons été tellement habitués à interagir peut être considérée comme le moteur RAG que nous utilisions lorsque nous étions nous-mêmes l'agent de raisonnement. Aujourd'hui, même les moteurs de recherche Internet transforment notre expérience de recherche lexicale bien connue en aperçus pilotés par l'IA qui répondent à la requête par un résumé des résultats, ce qui permet aux utilisateurs d'éviter de cliquer et d'évaluer eux-mêmes les résultats individuels.

IA générative & RAG

L'IA générative tente d'utiliser sa compréhension sémantique du monde pour analyser l'intention subjective exprimée dans une demande de chat, puis utilise ses capacités d'inférence pour créer une réponse d'expert à la volée. L'interaction générative de l'IA comporte plusieurs parties : elle commence par l'entrée/la requête de l'utilisateur, les conversations précédentes dans la session de chat peuvent être utilisées comme contexte supplémentaire, et l'instruction qui indique au LLM comment raisonner et quelles sont les procédures à suivre pour construire la réponse. Les messages-guides ont évolué, passant d'une simple orientation du type ", "Expliquez-moi cela comme si j'étais un enfant de cinq ans", à des descriptions complètes de la manière de traiter les demandes. Ces décompositions comprennent souvent des sections distinctes décrivant les détails du personnage/rôle de l'IA, le raisonnement avant la génération/le processus de réflexion interne, les critères objectifs, les contraintes, le format de sortie, le public, ainsi que des exemples pour aider à démontrer les résultats attendus.

En plus de la requête de l'utilisateur et de l'invite du système, la génération augmentée de recherche (RAG) fournit des informations contextuelles supplémentaires dans ce que l'on appelle une "fenêtre contextuelle". RAG a été un ajout essentiel à l'architecture ; c'est ce que nous utilisons pour informer le LLM des pièces manquantes dans sa compréhension sémantique du monde.

Les fenêtres contextuelles peuvent être un peu tatillonnes en ce qui concerne le contenu, l'emplacement et la quantité que vous leur donnez. Le contexte sélectionné est bien sûr très important, mais le rapport signal/bruit du contexte fourni est également important, de même que la longueur de la fenêtre.

Trop peu d'informations

Le fait de fournir trop peu d'informations dans une fenêtre de requête, d'invite ou de contexte peut entraîner des hallucinations, car le LLM ne peut pas déterminer avec précision le contexte sémantique correct à partir duquel générer une réponse. La similarité vectorielle de la taille des morceaux de documents pose également des problèmes - une question courte et simple peut ne pas correspondre sémantiquement aux documents riches et détaillés trouvés dans nos bases de connaissances vectorisées. Des techniques d'expansion des requêtes telles que Hypothetical Document Embeddings (HyDE) ont été développées. Elles utilisent les LLM pour générer une réponse hypothétique qui est plus riche et plus expressive que la requête courte. Le danger ici, bien sûr, est que le document hypothétique est lui-même une hallucination qui éloigne encore plus le LLM du contexte correct.

Trop d'informations

Tout comme pour nous, un excès d'informations dans une fenêtre contextuelle peut submerger un MLD et le rendre confus quant aux éléments importants. Le débordement de contexte (ou "pourriture de contexte") affecte la qualité et les performances des opérations d'IA générative ; il a un impact considérable sur le "budget d'attention" du LLM (sa mémoire de travail) et dilue la pertinence parmi de nombreux éléments concurrents. Le concept de "rotation du contexte" comprend également l'observation selon laquelle les LLM ont tendance à avoir un biais de position - ils préfèrent le contenu au début ou à la fin d'une fenêtre contextuelle au contenu de la section centrale.

Informations distrayantes ou contradictoires

Plus la fenêtre contextuelle est grande, plus il y a de chances qu'elle contienne des informations superflues ou contradictoires qui peuvent distraire le LLM de la sélection et du traitement du contexte correct. D'une certaine manière, il s'agit d'un problème d'entrée et de sortie de déchets : le simple fait de déverser un ensemble de résultats de documents dans une fenêtre contextuelle donne au LLM beaucoup d'informations à mâcher (potentiellement trop), mais en fonction de la manière dont le contexte a été sélectionné, il y a une plus grande possibilité que des informations contradictoires ou non pertinentes s'infiltrent dans le système.

IA agentique

Je vous avais dit qu'il y avait beaucoup de terrain à couvrir, mais nous l'avons fait - nous parlons enfin de sujets liés à l'IA agentique ! L'IA agentique est une nouvelle utilisation très intéressante des interfaces de chat LLM qui développe la capacité de l'IA générative (peut-on déjà l'appeler "ancienne" ?) à synthétiser des réponses basées sur ses propres connaissances et sur les informations contextuelles que vous lui fournissez. Au fur et à mesure que l'IA générative gagnait en maturité, nous avons réalisé qu'il existait un certain niveau de tâches et d'automatisation que nous pouvions confier aux LLM, initialement reléguées à des activités fastidieuses à faible risque qui peuvent facilement être vérifiées/validées par un être humain. En peu de temps, ce champ d'application initial s'est élargi : une fenêtre de discussion LLM peut désormais être l'étincelle qui envoie un agent d'intelligence artificielle planifier, exécuter, évaluer et adapter son plan de manière itérative afin d'atteindre l'objectif spécifié. Les agents ont accès au raisonnement de leur LLM, à l'historique des discussions et à la mémoire de pensée (telle qu'elle est), et ils disposent également d'outils spécifiques qu'ils peuvent utiliser à cette fin. Nous voyons aussi maintenant des architectures qui permettent à un agent de haut niveau de fonctionner comme l'orchestrateur de plusieurs sous-agents, chacun avec ses propres chaînes logiques, ses jeux d'instructions, son contexte et ses outils.

Les agents sont le point d'entrée d'un flux de travail essentiellement automatisé : ils sont autodirigés en ce sens qu'ils sont capables de discuter avec un utilisateur et d'utiliser ensuite la "logique" pour déterminer les outils dont ils disposent pour répondre à la question de l'utilisateur. Les outils sont généralement considérés comme passifs par rapport aux agents et construits pour effectuer un seul type de tâche. Les types de tâches qu'un outil pourrait accomplir sont en quelque sorte illimités (ce qui est vraiment passionnant !), mais l'une des principales tâches des outils est de rassembler des informations contextuelles qu'un agent doit prendre en compte lors de l'exécution de son flux de travail.

En tant que technologie, l'IA agentique en est encore à ses balbutiements et est sujette à l'équivalent LLM du trouble déficitaire de l'attention - elle oublie facilement ce qu'on lui a demandé de faire, et part souvent faire d'autres choses qui ne faisaient pas du tout partie du cahier des charges. Sous cette apparente magie, les capacités de "raisonnement" des LLM sont toujours basées sur la prédiction du prochain jeton le plus probable dans une séquence. Pour que le raisonnement (ou, un jour, l'intelligence artificielle générale (AGI)) devienne fiable et digne de confiance, nous devons être en mesure de vérifier que, lorsqu'on leur donne les informations correctes et les plus récentes, ils raisonnent de la manière que nous attendons d'eux (et nous donnent peut-être ce petit plus auquel nous n'aurions pas pensé nous-mêmes). Pour ce faire, les architectures agentiques devront être capables de communiquer clairement (protocoles), de respecter les flux de travail et les contraintes que nous leur imposons (garde-fous), de se rappeler où elles en sont dans une tâche (état), de gérer leur espace mémoire disponible et de valider que leurs réponses sont exactes et répondent aux critères de la tâche.

Parlez-moi dans une langue que je peux comprendre

Comme c'est souvent le cas dans les nouveaux domaines de développement (en particulier dans le monde des LLM), il existait initialement plusieurs approches pour les communications entre agents et outils, mais elles ont rapidement convergé vers le protocole de contexte de modèle (MCP) en tant que norme de facto. La définition du protocole de contexte de modèle est vraiment dans le nom - c'est le protocole qu'un modèle utilise pour demander et recevoir des informations contextuelles. MCP agit comme un adaptateur universel permettant aux agents LLM de se connecter à des outils et à des sources de données externes ; il simplifie et normalise les API de manière à ce que les différents cadres et outils LLM puissent facilement interopérer. Cela fait de MCP une sorte de point de pivot entre la logique d'orchestration et les invites du système données à un agent pour qu'il les exécute de manière autonome au service de ses objectifs, et les opérations envoyées à des outils pour qu'ils les exécutent de manière plus isolée (isolée au moins par rapport à l'agent qui en est à l'origine).

Cet écosystème est tellement nouveau que chaque direction d'expansion semble être une nouvelle frontière. Nous disposons de protocoles similaires pour les interactions entre agents(Agent2Agent (A2A) natch !) ainsi que d'autres projets visant à améliorer la mémoire de raisonnement des agents(ReasoningBank), à sélectionner le meilleur serveur MCP pour le travail à effectuer(RAG-MCP), et à utiliser l'analyse sémantique telle que la classification "zero-shot" et la détection de motifs sur les entrées et les sorties comme garde-fous pour contrôler ce sur quoi un agent est autorisé à opérer.

Vous avez peut-être remarqué que l'intention sous-jacente de chacun de ces projets est d'améliorer la qualité et le contrôle des informations renvoyées à une fenêtre contextuelle agent/genAI ? Alors que l'écosystème de l'IA agentique continue de développer la capacité à mieux traiter ces informations contextuelles (pour les contrôler, les gérer et les exploiter), il sera toujours nécessaire d'extraire les informations contextuelles les plus pertinentes pour que l'agent puisse les mouliner.

Bienvenue dans l'ingénierie contextuelle !

Si vous êtes familier avec les termes de l'IA générative, vous avez probablement entendu parler de "l'ingénierie des messages" - à ce stade, il s'agit presque d'une pseudo-science à part entière. L'ingénierie des invites est utilisée pour trouver les moyens les meilleurs et les plus efficaces de décrire de manière proactive les comportements que vous souhaitez que le MLD utilise pour générer sa réponse. L'"ingénierie du contexte" étend les techniques d'"ingénierie de l'invite" au-delà du côté de l'agent pour couvrir également les sources de contexte et les systèmes disponibles du côté des outils du protocole MCP, et comprend les thèmes généraux de la gestion, du traitement et de la génération du contexte :

• Gestion du contexte - liée au maintien de l'efficacité de l'état et du contexte dans des flux de travail agentiques de longue durée et/ou plus complexes. Planification itérative, suivi et orchestration des tâches et de l'utilisation des outils pour atteindre les objectifs de l'agent. En raison du "budget d'attention" limité dont disposent les agents, la gestion du contexte concerne principalement les techniques qui permettent d'affiner la fenêtre contextuelle afin de capturer à la fois la portée la plus complète et les éléments les plus importants du contexte (sa précision par rapport à son rappel !). Les techniques comprennent la compression, le résumé et la persistance du contexte des étapes précédentes ou des appels d'outils pour faire de la place dans la mémoire de travail pour le contexte supplémentaire des étapes suivantes.
• Traitement du contexte - Les étapes logiques et, espérons-le, essentiellement programmatiques visant à intégrer, normaliser ou affiner le contexte acquis à partir de sources disparates afin que l'agent puisse raisonner sur l'ensemble du contexte d'une manière quelque peu uniforme. Le travail sous-jacent consiste à faire en sorte que le contexte provenant de toutes les sources (invites, RAG, mémoire, etc.) soit consommé par l'agent le plus efficacement possible.
• Génération de contexte - Si le traitement du contexte consiste à rendre le contexte récupéré utilisable par l'agent, alors la génération de contexte donne à l'agent la possibilité de demander et de recevoir ces informations contextuelles supplémentaires à volonté, mais aussi avec des contraintes.

Les différents éphémères des applications de chat du LLM correspondent directement (et parfois de manière redondante) à ces fonctions de haut niveau de l'ingénierie contextuelle :

• Instructions / invite du système - Les invites constituent l'échafaudage de la manière dont l'activité générative (ou agentique) de l'IA orientera sa réflexion vers la réalisation de l'objectif de l'utilisateur. Les messages-guides constituent un contexte à part entière ; il ne s'agit pas seulement d'instructions tonales - ils comprennent aussi souvent une logique d'exécution des tâches et des règles telles que "réfléchir étape par étape" ou "respirer profondément" avant de répondre afin de s'assurer que la réponse répond pleinement à la demande de l'utilisateur. Des tests récents ont montré que les langages de balisage sont très efficaces pour encadrer les différentes parties d'une invite, mais il faut également veiller à calibrer les instructions de manière à ce qu'elles soient à la fois trop vagues et trop spécifiques ; nous voulons donner suffisamment d'instructions pour que le LLM trouve le bon contexte, mais sans être trop prescriptif au point de passer à côté d'idées inattendues.
• Mémoire à court terme (état/historique) - La mémoire à court terme correspond essentiellement aux interactions de la session de chat entre l'utilisateur et le LLM. Ils sont utiles pour affiner le contexte lors des sessions en direct et peuvent être sauvegardés pour être retrouvés et poursuivis ultérieurement.
• Mémoire à long terme - La mémoire à long terme doit être constituée d'informations utiles pour plusieurs sessions. Et il ne s'agit pas seulement de bases de connaissances spécifiques à un domaine auxquelles on accède par le biais de RAG ; des recherches récentes utilisent les résultats de demandes d'IA agentique/générative antérieures pour apprendre et se référer aux interactions agentiques actuelles. Certaines des innovations les plus intéressantes dans le domaine de la mémoire à long terme sont liées à l'ajustement de la manière dont l'état est stocké et relié afin que les agents puissent reprendre là où ils se sont arrêtés.
• Sortie structurée - La cognition nécessite un effort, il n'est donc pas surprenant que même avec des capacités de raisonnement, les LLM (tout comme les humains) veulent dépenser moins d'effort lorsqu'ils pensent, et en l'absence d'une API ou d'un protocole défini, avoir une carte (un schéma) sur la façon de lire les données renvoyées par un appel d'outil est extrêmement utile. L'inclusion de sorties structurées dans le cadre agentique contribue à rendre ces interactions machine-machine plus rapides et plus fiables, en réduisant les besoins d'analyse.
• Outils disponibles - Les outils peuvent faire toutes sortes de choses, de la collecte d'informations supplémentaires (par exemple, en émettant des requêtes RAG vers les référentiels de données de l'entreprise, ou par le biais d'API en ligne) à l'exécution d'actions automatisées au nom de l'agent (comme la réservation d'une chambre d'hôtel sur la base des critères de la demande de l'agent). Les outils peuvent également être des sous-agents disposant de leur propre chaîne de traitement agentique.
• Retrieval Augmented Generation (RAG) - J'aime beaucoup la description de RAG en tant qu'"intégration dynamique des connaissances". Comme décrit précédemment, le RAG est la technique permettant de fournir les informations supplémentaires auxquelles le LLM n'a pas eu accès lors de sa formation, ou bien il s'agit d'une réitération des idées que nous pensons être les plus importantes pour obtenir la bonne réponse - celle qui est la plus pertinente par rapport à notre requête subjective.

Une puissance cosmique phénoménale, un espace de vie minuscule !

L'IA agentique a tant de nouveaux domaines fascinants et passionnants à explorer ! Il y a encore beaucoup de problèmes traditionnels de recherche et de traitement de données à résoudre, mais aussi de toutes nouvelles catégories de défis qui commencent seulement à être exposés à la lumière du jour dans la nouvelle ère des LLM. Bon nombre des problèmes immédiats auxquels nous sommes confrontés aujourd'hui sont liés à l'ingénierie contextuelle, c'est-à-dire au fait de fournir aux MFR les informations contextuelles supplémentaires dont ils ont besoin sans surcharger leur espace de mémoire de travail, qui est limité.

La flexibilité des agents semi-autonomes ayant accès à un ensemble d'outils (et à d'autres agents) donne lieu à tant de nouvelles idées pour la mise en œuvre de l'IA qu'il est difficile d'imaginer les différentes façons dont nous pourrions assembler les pièces du puzzle. La plupart des recherches actuelles s'inscrivent dans le domaine de l'ingénierie contextuelle et se concentrent sur la construction de structures de gestion de la mémoire capables de gérer et de suivre de plus grandes quantités de contexte. En effet, les problèmes de réflexion approfondie que nous voulons vraiment que les LLM résolvent présentent une complexité accrue et des étapes de réflexion plus longues et multiphases, où la mémorisation est extrêmement importante.

Une grande partie de l'expérimentation en cours dans le domaine consiste à essayer de trouver la gestion optimale des tâches et les configurations d'outils pour alimenter la gueule de l'agent. Chaque appel d'outil dans la chaîne de raisonnement d'un agent entraîne un coût cumulatif, à la fois en termes de calcul pour exécuter la fonction de l'outil et d'impact sur la fenêtre contextuelle limitée. Certaines des dernières techniques de gestion du contexte pour les agents LLM ont provoqué des effets en chaîne involontaires tels que l'"effondrement du contexte", où la compression/le résumé du contexte accumulé pour les tâches de longue durée entraîne trop de pertes. Le résultat souhaité est de disposer d'outils qui renvoient un contexte succinct et précis, sans que des informations superflues ne viennent empiéter sur l'espace mémoire précieux de la fenêtre de contexte.

Tant/trop de possibilités

Nous voulons une séparation des tâches avec la possibilité de réutiliser les outils/composants, il est donc tout à fait logique de créer des outils agentiques dédiés pour se connecter à des sources de données spécifiques - chaque outil peut se spécialiser dans l'interrogation d'un type de référentiel, d'un type de flux de données, ou même d'un cas d'utilisation. Mais attention : dans le but de gagner du temps/de l'argent/de prouver que quelque chose est possible, la tentation sera grande d'utiliser les MLD comme outil de fédération... Essayez de ne pas le faire, nous sommes déjà passés par là! La recherche fédérée agit comme un "traducteur universel" qui convertit une requête entrante dans la syntaxe que le référentiel distant comprend, et qui doit ensuite rationaliser les résultats provenant de sources multiples en une réponse cohérente. La fédération en tant que technique fonctionne bien à petite échelle, mais à grande échelle et surtout lorsque les données sont multimodales, la fédération tente de combler des lacunes qui sont tout simplement trop importantes.

Dans le monde agentique, l'agent serait le fédérateur et les outils (par l'intermédiaire de MCP) seraient les connexions définies manuellement vers des ressources disparates. L'utilisation d'outils dédiés pour accéder à des sources de données non connectées peut sembler être une nouvelle façon puissante d'unir dynamiquement différents flux de données sur la base d'une requête, mais l'utilisation d'outils pour poser la même question à plusieurs sources finira probablement par causer plus de problèmes qu'elle n'en résoudra. Chacune de ces sources de données est probablement constituée de différents types de référentiels, chacun ayant ses propres capacités de récupération, de classement et de sécurisation des données qu'il contient. Ces écarts ou "décalages d'impédance" entre les référentiels augmentent bien entendu la charge de traitement. Ils peuvent également introduire des informations ou des signaux contradictoires, où quelque chose d'apparemment inoffensif comme un décalage de notation peut perturber considérablement l'importance accordée à un élément de contexte renvoyé, et affecter la pertinence de la réponse générée en fin de compte.

Le changement de contexte est également difficile pour les ordinateurs

Lorsque vous envoyez un agent en mission, sa première tâche consiste souvent à trouver toutes les données pertinentes auxquelles il a accès. Tout comme pour les humains, si chaque source de données à laquelle l'agent se connecte fournit des réponses dissemblables et désagrégées, il y aura une charge cognitive (mais pas exactement du même type) associée à l'extraction des éléments contextuels saillants du contenu récupéré. Cela prend du temps/du calcul, et chaque petit morceau s'additionne dans la chaîne logique agentique. Cela conduit à la conclusion que, à l'instar de ce qui est discuté pour MCP, la plupart des outils agentiques devraient plutôt se comporter comme des API - des fonctions isolées avec des entrées et des sorties connues, réglées pour répondre aux besoins de différents types d'agents. Ils parviennent beaucoup mieux à relier les points sémantiques, en particulier lorsqu'il s'agit d'une tâche telle que la traduction du langage naturel en syntaxe structurée, lorsqu'ils disposent d'un schéma auquel se référer (RTFM en effet !).

7ème manche !

Nous avons maintenant abordé l'impact des LLM sur la recherche et l'interrogation de données, ainsi que la manière dont la fenêtre de discussion évolue vers l'expérience de l'IA agentique. Mettons les deux sujets ensemble et voyons comment nous pouvons utiliser nos nouvelles capacités de recherche et d'extraction pour améliorer nos résultats en matière d'ingénierie contextuelle. En route pour la troisième partie : la puissance de la recherche hybride dans l'ingénierie contextuelle!

ECK demande nettement plus d'efforts que les solutions Elastic Cloud basées sur la Marketplace, mais il est plus automatisé que le déploiement de VM par vous-même, car l'opérateur Kubernetes s'occupera de l'orchestration du système et de la mise à l'échelle des nœuds.

Cette fois, nous allons travailler avec le service Azure Kubernetes (AKS), en utilisant Automatic. Dans les autres articles, vous apprendrez à utiliser Azure VM et Azure Marketplace.

Qu'est-ce qu'AKS Automatic ?

Azure Kubernetes Service (AKS) gère automatiquement la configuration des clusters, alloue dynamiquement les ressources et intègre les meilleures pratiques de sécurité tout en préservant la flexibilité de Kubernetes, ce qui permet aux développeurs de passer d'une image de conteneur à une application déployée en quelques minutes.

AKS Automatic supprime la plupart des frais généraux liés à la gestion des clusters et offre un bon équilibre entre simplicité et flexibilité. Le bon choix dépend de votre cas d'utilisation, mais la décision est plus facile à prendre si vous prévoyez de le faire :

• Déployer un environnement de test : Le déploiement est rapide et simple, ce qui le rend idéal pour les expériences rapides ou les clusters de courte durée.
• Travaillez sans exigences strictes en matière de VM, de stockage ou de réseau : AKS Automatic fournit des valeurs par défaut prédéfinies, de sorte que si celles-ci correspondent à vos besoins, vous n'avez pas besoin d'une configuration supplémentaire.
• Commencez avec Kubernetes pour la première fois : En prenant en charge une grande partie de la configuration du cluster, AKS Automatic réduit la courbe d'apprentissage et permet aux équipes de se concentrer sur leurs applications.

Pour Elasticsearch, nous allons utiliser Elastic Cloud on Kubernetes (ECK), qui est l'opérateur officiel d'Elastic Kubernetes qui simplifie l'orchestration des déploiements Kubernetes de la pile Elastic.

Comment configurer AKS Automatic

1. Connectez-vous au portail Microsoft Azure.

2. En haut à droite, cliquez sur sur le bouton Cloud Shell pour accéder à la console et déployer le cluster AKS à partir de là. Vous pouvez également utiliser Azure Cloud Shell.

N'oubliez pas de mettre à jour l'identifiant du projet avec le vôtre pendant le tutoriel.

L'ouverture de l'AKS devrait ressembler à la capture d'écran ci-dessus.

3. Installez l'extension aks-preview Azure CLI. Cette version preview nous permettra de sélectionner --sku automatic lors de la création du cluster, ce qui activera la fonction AKS Automatic.

az extension add --name aks-preview

Si vous voyez ce message, cela signifie que l'extension AKS a été installée correctement.

4. Enregistrer les indicateurs de caractéristiques à l'aide de la commande az feature register

az feature register --namespace Microsoft.ContainerService --name AutomaticSKUPreview

Vous verrez les détails de l'abonnement de fonctionnalité que nous venons de créer :

Vérifiez l'état de l'enregistrement jusqu'à ce qu'il passe de "En cours d'enregistrement" à "Enregistré". L'enregistrement peut prendre quelques minutes.

az feature show --namespace Microsoft.ContainerService --name AutomaticSKUPreview

Exécutez az provider register pour propager les modifications.

az provider register --namespace Microsoft.ContainerService

5. Créer un groupe de ressources

Un groupe de ressources est un groupe logique de ressources Azure à gérer et à déployer.

az group create --name elastic-resource --location eastus

6. Créez un cluster Autopilot. Nous le nommerons myAKSAutomaticCluster et utiliserons le groupe de ressources que nous venons de créer. Assurez-vous d'avoir 16 vCPUs disponibles sur l'une des tailles de VM suivantes : Standard_D4pds_v5, Standard_D4lds_v5, Standard_D4ads_v5, Standard_D4ds_v5, Standard_D4d_v5, Standard_D4d_v4, Standard_DS3_v2, Standard_DS12_v2 pour qu'AKS alloue des ressources.

az aks create \
    --resource-group elastic-resource \
    --name myAKSAutomaticCluster \
    --sku automatic \
    --generate-ssh-keys

* Si vous obtenez des erreurs MissingSubscriptionRegistration, revenez à l'étape 4 avec les abonnements manquants. Par exemple , The subscription is not registered to use namespace 'microsoft.insights' nécessite l'exécution de az provider register --namespace Microsoft.Insights.

Suivez la connexion interactive :

Un message demandant d'exécuter "az login" s'affiche. Vous devez exécuter cette commande et attendre.

7. Attendez qu'il soit prêt. Il faut environ 10 minutes pour le créer.

8. Configurer l'accès à la ligne de commande kubectl.

az aks get-credentials --resource-group elastic-resource --name myAKSAutomaticCluster

Notez que l'extension que nous avons installée active AKS Automatic.

9. Confirmez que les nœuds ont été déployés.

kubectl get nodes

Vous verrez un message d'erreur interdit ; copiez l'identifiant de l'utilisateur dans le message d'erreur.

10. Ajoutez votre utilisateur au contrôle d'accès AKS.

Obtenir l'ID AKS. Copie la sortie de la commande.

az aks show --resource-group elastic-resource  --name myAKSAutomaticCluster --query id --output tsv

Créez une attribution de rôle en utilisant l'identifiant AKS et l'identifiant principal de votre utilisateur.

az role assignment create --role "Azure Kubernetes Service RBAC Cluster Admin" --assignee  --scope 

11. Essayez de confirmer que les nœuds ont été déployés à nouveau.

kubectl get nodes

12. Installez l'opérateur Elastic Cloud on the Kubernetes (ECK).

# Install ECK Custom Resource Definitions
kubectl create -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml

# Install the ECK operator
kubectl apply -f https://download.elastic.co/downloads/eck/2.16.1/operator.yaml

13. Créons une instance Elasticsearch à nœud unique avec les valeurs par défaut.

cat <

Nous avons désactivé nmap parce que la machine AKS par défaut a une valeur vm.max_map_count trop faible. Sa désactivation n'est pas recommandée pour la production, mais l'augmentation de la valeur de vm.max_map_count. Pour en savoir plus , cliquez ici.

14. Déployons également un cluster Kibana à nœud unique. Pour Kibana, nous allons ajouter un équilibreur de charge, qui nous donnera une IP externe que nous pouvons utiliser pour atteindre Kibana depuis notre appareil.

cat <

Par défaut, AKS Automatic configure l'équilibreur de charge comme étant public ; vous pouvez modifier ce comportement en définissant l'annotation des métadonnées :

service.beta.kubernetes.io/azure-load-balancer-internal: "true"

15. Vérifiez que vos pods fonctionnent.

kubectl get pods

16. Vous pouvez également lancer kubectl get elasticsearch et kubectl get kibana pour obtenir des statistiques plus spécifiques comme la version d'Elasticsearch, les nœuds et l'état de santé.

17. Accédez à vos services.

kubectl get svc

Cela vous montrera l'URL externe de Kibana sous EXTERNAL-IP. Le provisionnement de l'équilibreur de charge peut prendre quelques minutes. Copier la valeur de EXTERNAL-IP.

18. Obtenez le mot de passe Elasticsearch pour l'utilisateur 'elastic' :

kubectl get secret quickstart-es-elastic-user -o=jsonpath='{.data.elastic}' | base64 --decode

19. Accédez à Kibana via votre navigateur :

a. URL : https://<EXTERNAL_IP>:5601

b. Nom d'utilisateur:elastic

c. Mot de passe:c44A295CaEt44D6xIzN6Zs5m (de l'étape précédente)

20. Lorsque vous accédez à Elastic Cloud à partir de votre navigateur, vous verrez l'écran de bienvenue.

Si vous souhaitez modifier les spécifications du cluster Elasticsearch, comme changer ou redimensionner les nœuds, vous pouvez appliquer à nouveau le manifeste YML avec les nouveaux paramètres :

cat <

Dans cet exemple, nous allons ajouter un nœud supplémentaire et modifier la RAM et la CPU. Comme vous pouvez le voir, kubectl get elasticsearch affiche maintenant 2 nœuds :

Il en va de même pour Kibana :

cat <

Nous pouvons ajuster le CPU/RAM du conteneur ainsi que l'utilisation de la mémoire de Node.js (max-old-space-size).

N'oubliez pas que les créances en volume existantes ne peuvent pas être réduites. Après avoir appliqué la mise à jour, l'opérateur effectuera les changements avec un minimum de temps d'interruption.

N'oubliez pas de supprimer la grappe lorsque vous avez terminé les tests afin d'éviter des coûts inutiles.

az aks delete --name myAKSAutomaticCluster --resource-group elastic-resource

Conclusion

L'utilisation d'Azure AKS Automatic avec ECK fournit une solution équilibrée pour le déploiement d'Elasticsearch et de Kibana : elle réduit la complexité opérationnelle, assure une mise à l'échelle et des mises à jour automatisées, et tire parti de la flexibilité de Kubernetes. Cette approche est idéale pour les équipes qui souhaitent un processus de déploiement fiable, reproductible et maintenable sans avoir à gérer manuellement chaque détail de l'infrastructure, ce qui en fait un choix pratique pour les environnements de test et de production.

Étapes suivantes

Si vous souhaitez en savoir plus sur Kubernetes, vous pouvez consulter la documentation officielle ici :

• Elastic Cloud sur Kubernetes | Elastic Docs
• Introduction à Azure Kubernetes Service (AKS) Automatique (preview)
• AKS Automatic - Blog d'AKS Engineering

]]>