Die lexikalische Suche (Textabgleich), die semantische Suche (Abgleich von Konzepten) und die hybride Suche (Kombination lexikalischer und semantischer Signale) lösen diese Probleme für sich genommen nicht. Bei der lexikalischen Suche werden möglicherweise alle Ergebnisse angezeigt, die das Wort „Orangen“ enthalten, während sich die rein semantische Suche bei einer Suchanfrage mit hoher Intentionsstärke wie „Orangen“ auf verwandte Begriffe wie Zitronen oder Grapefruits ausweiten kann. Die hybride Abfrage kombiniert diese lexikalischen und semantischen Signale, kann jedoch nach wie vor nicht entscheiden, ob diese Abfrage als navigatorisch zu behandeln ist, welche Einschränkungen durchgesetzt werden sollten oder welche geschäftlichen Richtlinien gelten sollten. Das Problem liegt nicht in der Abruftechnologie selbst, sondern im Fehlen einer Steuerungsebene, die erkennt, um welche Art von Abfrage es sich handelt und welche Einschränkungen vor Beginn des Abrufs durchgesetzt werden müssen.

In diesem Blogbeitrag befassen wir uns mit der Steuerung der E-Commerce-Suche, ihrer Bedeutung und der Frage, wie eine Kontrollschicht für vorhersehbare und präzise Suchergebnisse sorgt.

Was Governance in der E-Commerce-Suche bedeutet

Governance bedeutet in diesem Zusammenhang, eine Entscheidungsebene zwischen der Abfrage des Nutzers und der Abruf-Engine einzuführen. Diese Ebene erfüllt die folgenden Funktionen:

• Klassifiziert die Suchabsicht: Handelt es sich um eine Navigation („Orangen“) oder um eine Suche („Geschenk für Opa“)?
• Wendet geschäftliche Vorgaben an: Welche Kategoriegrenzen, Zulassungsregeln, Verfügbarkeitsbeschränkungen oder Merchandising-Richtlinien gelten?
• Wege zur geeigneten Strategie: Sollte hierbei lexikalisches Abrufen, semantisches Abrufen oder ein hybrider Ansatz zum Einsatz kommen?

Eine Governance-Ebene legt fest, welcher Abrufansatz für jede Abfrage verwendet werden soll, welche Einschränkungen durchgesetzt werden müssen und welche Geschäftsrichtlinien vor Beginn des Abrufs gelten sollen. Es ist wichtig, Governance nicht mit dem hybriden Abruf zu verwechseln: Der hybride Abruf ist eine Abrufstrategie, die lexikalische und semantische Signale kombiniert, während Governance die vorgelagerte Entscheidungsebene ist, die bestimmt, ob lexikalische, semantische oder hybride Signale verwendet werden sollen.

Der Status quo: Die „Spaghetti“-Implementierung auf Anwendungsebene

Derzeit versuchen viele Händler, dieses Problem zu lösen, indem sie die Logik direkt in die Anwendungsschicht integrieren. Dies führt oft zu Spaghetti-Code, also zu Tausenden von Zeilen fest codierter if-then-Anweisungen, Regex und komplexen Suchvorlagen.

Dieser Ansatz kann die oben gezeigten gewünschten Suchergebnisse liefern; jedoch verursacht er erhebliche betriebliche Reibungsverluste:

• Abhängigkeit von der Entwicklungsabteilung: Geschäfts-Nutzer und Merchandiser können das Suchverhalten nicht ohne Entwicklungs-Tickets und lange Deployment-Zyklen ändern, die oft mehrere Wochen dauern.
• Fragmentierung: Die Suchlogik verteilt sich auf den Anwendungscode und die Suchvorlagen, ist schwer zu erklären oder zu überprüfen und birgt daher Risiken bei der Weiterentwicklung.

Selbst wenn Teams die Notwendigkeit des Routings erkennen, konzentriert sich die Debatte oft auf die falsche Frage: welche Abrufmethode gewählt werden soll.

Die falsche Wahl: Lexikalisch vs. semantisch vs. hybrid

Suchteams betrachten diese Herausforderung häufig als eine Frage der Wahl der Abrufstrategie: lexikalisch/BM25 versus semantisch/Vektoren versus hybrid. Diese Sichtweise ist zwar nachvollziehbar (die Abrufmethoden spielen eine Rolle), lässt jedoch die häufigste Fehlerquelle in realen Implementierungen außer Acht: Die Verwendung eines einzigen Abrufansatzes für alle Abfragen führt zu suboptimalen Ergebnissen.

Commerce Search ist eine Mischung aus grundlegend verschiedenen Absichten:

• Deterministische Navigation mit hoher Absicht („Orangen“, „Milch“, „Schokolade ohne Erdnüsse“, „billiges Olivenöl“).
• Explorative Suche („Jacke zum Wandern in den Bergen“, „Geschenk für ein 12‑jähriges Kind, das Robotik mag“).
• Betriebliche Einschränkungen (Verfügbarkeit, Größe, Preis, Farbe).
• Merchandising und Kampagnen (Boost, Begraben, saisonale Kampagnen).

Wenn das System all diese Vorgänge über dieselbe Abrufstrategie abwickelt, sind die Ergebnisse oft auf vorhersehbare Weise systematisch fehlerhaft, da es dem Betriebsmodell an Governance mangelt. Wenn Teams dies nicht als Lücke in der Unternehmensführung erkennen, reagieren sie mit dem einzigen Mittel, das ihnen zur Verfügung steht: noch mehr Feinabstimmung.

Warum „Relevanzoptimierung“ zyklisch werden kann.

Ohne eine Routing-Schicht verwandelt sich „Relevanz“ oft in einen nie endenden Rückstand:

• Warum zeigt diese Abfrage Zubehör über dem Kernprodukt an?
• Warum hat diese Kopfabfrage plötzlich verwandte Ergebnisse angezeigt?
• Warum änderten sich die Ergebnisse, nachdem wir Synonyme hinzugefügt, Analysatoren angepasst oder Hybrid aktiviert hatten?
• Warum benötigt das Business-Team ein Engineering-Release, um eine einzelne Abfrage zu beheben?

Die Teams reagieren mit weiteren Optimierungen: mehr Synonyme, mehr Boosts, mehr Experimente zur Neugewichtung, mehr Ausnahmen im Anwendungscode. Dies kann eine Zeit lang funktionieren, führt jedoch häufig zu instabilem Verhalten, da dem System nach wie vor eine explizite Entscheidungsebene fehlt, um den Abfragetyp zu bestimmen und die richtigen Einschränkungen vor dem Abruf durchzusetzen.

Die Anatomie der E-Commerce-Absicht: „Head“ und „Tail“

In diesem Abschnitt verwenden wir „Head“ und „Tail“ als praktische Kurzform für gängige Navigations- und Suchmuster im E-Commerce. In der realen Welt enthalten viele Anfragen Aspekte von beidem:

„Head“-Abfragen (deterministische Absicht)

Dies sind direkte, navigationsbezogene Abfragen, bei denen der Nutzer genau weiß, was er möchte:

• Absicht in Bezug auf einen einzelnen Artikel ("Orangen", "Milch", "Brot").
• Genaue Marken oder Produktfamilien („iPhone 15 Pro“, „Diet Coke“).
• Artikelnummern, Modellnummern, Größen ("ABC123", "air max 270").

Für diese Abfragen kann die lexikalische Suche die Token-Korrespondenz (Wortübereinstimmung) abdecken, aber das Unternehmen erwartet außerdem, dass Constraints eingehalten werden, vorhersehbare Rankings zurückgegeben werden und die Ergebnisse steuerbar sind. Ein Merchandiser muss sicherstellen, dass eine Abfrage innerhalb der richtigen Kategoriegrenzen aufgelöst wird, die Eligibility-Kriterien einhält und bestimmte geschäftliche Prioritäten sichtbar macht.

Governance ist erforderlich, um die beabsichtigte Lösung durchzusetzen. Zum Beispiel sollten „Orangen“ der Kategorie Frischwaren zugeordnet werden, nicht Orangensaft, Orangenmarmelade oder Orangenlimonade.

„Tail“-Abfragen (explorative Datensuche)

Dies sind beschreibende, absichtsvolle Suchanfragen, mit denen Käufer recherchieren:

• „Geschenk für Opa mit einer Vorliebe für Süßes“
• „Jacke zum Wandern in den Bergen“
• „Schuhe, um den ganzen Tag zu stehen“

Der lexikalische Abruf hat hier oft Schwierigkeiten. Der semantische Abruf ist überlegen, weil er das Abfragekonzept mit dem Produkt verknüpfen kann, selbst wenn die Formulierungen nicht übereinstimmen. Aber auch der semantische Abruf allein reicht selten aus. Abfragen aus der Praxis erfordern oft, dass Constraints durchgesetzt werden – unabhängig davon, welche Abrufmethode verwendet wird.

Die Einschränkungen sind orthogonal zur Abrufmethode.

Das Anwenden von Einschränkungen auf semantische Abrufe bedeutet nicht hybride Suche. Dies sind orthogonale Konzepte. Einschränkungen wie Filter und Boosts in Elasticsearch können auf jede lexikalische, semantische oder hybride Suche angewendet werden. Die Herausforderung besteht darin, zu entscheiden, wie die Abfrage interpretiert werden soll, welche Einschränkungen durchgesetzt werden müssen und welche Abfragemethode verwendet werden soll.

Im Folgenden finden Sie einige Beispiele für Abfragen, die die Datensuche mit festen Einschränkungen kombinieren:

• Orangen: Lexikalische Suche nach „Orangen“ unter Hinzunahme einer Kategoriebeschränkung, wie beispielsweise „Obst“ oder „Frischwaren“, wodurch Orangenmarmelade, Orangensaft und Orangenlimonade ausgeschlossen werden.
• Früchte mit hohem Vitamin-C-Gehalt unter 4 $: Semantische Suche nach dem Nährwert plus Einschränkungen, die die Ergebnisse auf die Kategorie Obst und Produkte unter 4 $ beschränken.
• Bequeme Schuhe für die Arbeit: Semantischer Informationsabruf für kontextuelle Absicht plus eine Kategoriebeschränkung, die die Ergebnisse auf Schuhe begrenzt.

Diese Abfragen können nicht mit einem einzigen Ansatz bearbeitet werden:

• Ein rein lexikalischer Abruf ist hier oft unzureichend, da Phrasen wie „reich an Vitamin C“ oder „komfortabel“ möglicherweise nicht als saubere, strukturierte Attribute existieren. Sie müssen möglicherweise aus Produktbeschreibungen, Bewertungen oder Spezifikationen abgeleitet werden.
• Auch eine rein semantische Suche reicht nicht immer aus, da eine Suchanfrage wie „vitamin-C-reiche Früchte“ ohne explizite Einschränkungen auf Vitaminpräparate, Getränke mit Fruchtgeschmack oder vitaminreiches Gemüse außerhalb der beabsichtigten Kategorie und Preisklasse ausgeweitet werden könnte.

Eine Steuerungsebene legt fest, ob eine Abfrage eine lexikalische Suche, ein semantisches Verständnis, die Durchsetzung von Einschränkungen oder eine Kombination dieser Elemente erfordert. Ohne diese Ebene könnten E-Commerce-Teams in folgende Situation geraten:

• Übermäßige Einschränkung: Verwendung lexikalischer Abfragen für semantische Anfragen (zum Beispiel „Geschenk für Opa“).
• Unterbeschränkung: Verwendung semantischer Abfragen für Head-Abfragen mit hoher Intention (z. B. „Orangen“).

Die Herausforderung im Bereich der Governance besteht darin, ein System zu entwickeln, das für jede Art von Anfrage die richtige Entscheidung treffen kann.

Was passiert ohne Governance?

Die häufigste Fehlerquelle ist ganz einfach: Teams nehmen die rohe Benutzeranfrage und leiten sie direkt an eine einzige Abrufstrategie weiter (lexikalisch, semantisch oder hybrid), ohne eine zwischengeschaltete Governance-Ebene.

Die lexikalische Suche verfehlt die beabsichtigte Auflösung.

Wenn ein Nutzer nach "Orangen" sucht, kann eine lexikalische Suchstrategie alles zurückgeben, was dieses Token enthält: Orangensaft, Orangenmarmelade oder Orangenlimonade. Das System hat den Begriff korrekt zugeordnet, aber ohne Governance kann es den beabsichtigten Einkaufskontext (die Frucht) nicht auflösen.

Der semantische Abruf weitet sich über die beabsichtigten Einschränkungen hinaus aus

Wenn ein Nutzer nach „Orangen“ sucht, kann ein semantisches System konzeptionell verwandte Elemente aus nahegelegenen Produktkonzepten abrufen. Das System versteht zwar den übergeordneten Bereich (Obst oder Gemüse), aber ohne explizite Steuerung kann es dennoch über die vom Nutzer beabsichtigte Beschränkung (speziell Orangen) hinausgehen.

Die Lücke ist Governance

Erforderlich ist eine vorgelagerte Entscheidungsebene, die die Abfrageabsicht bestimmt und die richtigen Einschränkungen durchsetzt, bevor der Abruf beginnt. Dadurch werden Probleme wie die folgenden behoben:

• Ähnliche oder verwandte Artikel, die neben dem angezeigt werden, was der Nutzer eigentlich gesucht hat.
• Verschwimmende Kategoriegrenzen („Getränke“ vs. „Frischwaren“).
• Unfähigkeit, saisonale Boosts oder Kampagnen umzusetzen.
• Unvorhersehbare und unerklärliche Ergebnisse.

Absichtserkennung und Weiterleitung: Die notwendige Steuerungsebene

Ein gesteuertes Suchsystem führt eine schlanke Steuerungsebene vor dem Abruf ein (vor der Ausführung einer Abfrage in Elasticsearch). Auf dieses Steuerelement wird in den Teilen 3 und 4 dieser Blogreihe ausführlich eingegangen; vorerst beschränken wir uns darauf, zu erläutern, was es leisten kann, ohne jedoch auf seine Funktionsweise einzugehen:

Eine Steuerungsebene kann Absichten erkennen, Geschäftsrichtlinien anwenden und die entsprechende Abrufstrategie wie folgt sicherstellen:

1. Absichtssignale erkennen

• Ist diese Abfrage wahrscheinlich Navigation oder Entdeckung?
• Handelt es sich um eine bekannte Head-Abfrage (Milch, Brot, Bananen)?
• Gibt es eine bekannte Interpretation für ein Produkt, eine Marke oder eine Kategorie (beispielsweise sollte „Orangen“ zu „Frischwaren“ führen)?
• Ist die Abfrage ein SKU-ähnliches Muster?
• Fällt die Abfrage unter eine aktive Kampagne oder eine saisonale Richtlinie (beispielsweise während der Weihnachtszeit, um Suchergebnisse zum Thema Truthahn stärker hervorzuheben)?
• Impliziert die Abfrage Einschränkungen (Kategorie, Attribute, Ausschlüsse, Preis/Größe/Farbe)?

2. Setzen Sie Governance- und Geschäftsrichtlinien um.

• Wenden Sie zunächst deterministische Einschränkungen an (Kategorie/Attribut/Negation/Verfügbarkeit).
• Wenden Sie aktive Merchandising-Maßnahmen an (hervorheben/verbergen/fixieren/überschreiben).
• Lösen Sie Konflikte mithilfe von Prioritätsregeln (z. B. Kampagnen-Überschreibungen gegenüber globalen Richtlinien).

3. Weg zur geeigneten Abrufstrategie

• Lexikalisch (schnell, deterministisch) für navigationsorientierte Suchanfragen mit hoher Kaufabsicht.
• Semantische Suche für echte Entdeckungsanfragen.
• Ein hybrider Ansatz, bei dem kombinierte lexikalische und semantische Signale unter expliziten geschäftlichen Vorgaben einen Mehrwert schaffen.

In der Praxis ist der Ausgang der Steuerungsebene nicht einfach „Hybrid verwenden“ oder „Semantik verwenden“. Es handelt sich um einen geregelten Abrufplan: eine Interpretation der Absicht des Kunden, der geltenden Einschränkungen und Richtlinien sowie der auszuführenden Abrufstrategie. Ein paar einfache Beispiele verdeutlichen dies:

Eine Steuerungsebene wählt für jede Abfrage konsistent, vorhersehbar und in großem Maßstab die richtige Richtlinie und Abrufstrategie aus. Dies macht fortgeschrittene Abrufmethoden in der Produktion vorhersehbarer, da absichtsbasierte Einschränkungen zuerst durchgesetzt werden und Routing-Entscheidungen explizit statt implizit getroffen werden.

Wie dies mit anderen Ansätzen zusammenhängt

Einige Teams nutzen verbesserte Einbettungsmodelle, um die Produktsemantik besser zu erfassen, was die Qualität der semantischen Suche erheblich verbessern kann. Andere nutzen Ansätze zur Neureihenfolge, wie beispielsweise Learning To Rank (LTR), um die Reihenfolge der Ergebnisse nach der Abfrage auf der Grundlage von Interaktions- oder geschäftsbezogenen Signalen zu optimieren. Beide sind wertvoll und ergänzen sich oft. Bessere Einbettungen verbessern den Ähnlichkeitsabgleich. Durch die Neubewertung wird die Reihenfolge der abgerufenen Kandidaten verbessert.

Governance befasst sich mit einer anderen Ebene des Problems: Sie ist dem Abrufprozess vorgelagert. Es entscheidet, welche Abrufstrategie verwendet wird (zum Beispiel lexikalisch, semantisch oder hybrid), welche deterministischen Einschränkungen erforderlich sind und welche Abfragen mehrere Geschäftsrichtlinien kombinieren sollten.

Was eine gesteuerte Steuerungsebene ermöglicht

Sobald eine Governance-Ebene eingerichtet ist, verändert sich das Betriebsmodell grundlegend. Umsatzrelevante Abfragen lassen sich vorhersagen. Geschäftsteams können das Suchverhalten anpassen, ohne auf die Release-Zyklen der Entwickler warten zu müssen. Und fortgeschrittene Abrufmethoden, wie semantische und hybride Verfahren, können schrittweise eingeführt werden – im Rahmen von Routing-Regeln und Sicherheitsvorkehrungen – anstatt als globaler Ein-/Aus-Schalter.

Der nächste Beitrag dieser Reihe befasst sich damit, wie dieses Betriebsmodell in der Praxis aussieht und warum es möglicherweise genauso wichtig ist wie die ihm zugrunde liegende Suchtechnologie.

Wenn ein Merchandiser ein Jira-Ticket erstellen und auf eine Bereitstellung warten muss, um eine umsatzkritische Abfrage zu beheben, liegt der Engpass nicht in der Engine, sondern im Betriebsmodell. Eine moderne E-Commerce-Suche muss in der Lage sein, geschäftliche Absichten schnell und sicher in kontrolliertes, überprüfbares Suchverhalten umzusetzen, dabei aber weiterhin auf erweiterte Suchfunktionen zurückzugreifen, wo diese einen messbaren Mehrwert bieten.

Wie geht es weiter in dieser Serie?

Die in dieser Reihe behandelten Muster greifen bereits vor der Abfrage an: Sie dienen dazu, geschäftliche Absichten in die richtige Abfragestrategie umzusetzen, noch bevor die Abfrage generiert wird. Im nächsten Beitrag wechseln wir vom technischen zum operativen Problem: Was passiert, wenn Geschäftsteams das Suchverhalten ohne ein technisches Deployment ändern können, und warum Governance das sicher macht?

Setzen Sie die reglementierte E-Commerce-Suche in die Praxis um

Technische Engpässe, instabile Logik auf Anwendungsebene und unvorhersehbare Suchergebnisse sind Probleme, bei deren Lösung Ihnen Elastic Services im Rahmen von E-Commerce-Projekten für Unternehmen behilflich sein kann. Die in dieser Reihe beschriebene Architektur der verwalteten Steuerungsebene wurde von Elastic Services Engineering entwickelt.

Wenn Ihr Team Entwicklungsressourcen darauf verwendet, Merchandising-Anforderungen in Codeänderungen umzusetzen, oder wenn Ihr Rückstand bei der Suchrelevanz scheinbar nie abnimmt, können wir Ihnen dabei helfen, Ihre aktuelle Architektur zu bewerten und einen Weg zu einer kontrollierten, vom Geschäftsteam editierbaren Suche zu ebnen. Kontaktieren Sie Elastic Services.

Nehmen Sie an der Diskussion teil

Haben Sie Fragen zur Suchsteuerung, zu Abrufstrategien oder zur Sucharchitektur im E-Commerce? Nehmen Sie an der Diskussion der Elastic-Community teil.

Wir haben kürzlich zum Open-Source-Projekt mastra-ai/mastra beigetragen, indem wir Unterstützung für Elasticsearch als Vektordatenbank hinzugefügt haben. Mit diesem neuen Feature können Sie Elasticsearch nativ in Mastra verwenden, um Einbettungen zu speichern. Zusätzlich zu Vektoren bietet Elasticsearch eine Reihe erweiterter Features, die alle Ihre Anforderungen an das Kontext-Engineering erfüllen. (zum Beispiel hybride Suche und Reranking).

Dieser Artikel beschreibt die Erstellung eines Agenten zur Implementierung einer RAG-Architektur (Retrieval-Augmented Generation) mit Elasticsearch. Wir stellen ein Demoprojekt vor, bei dem ein agentischer Ansatz verwendet wird, um mit einem in Elasticsearch gespeicherten Korpus von Science-Fiction-Filmdaten zu interagieren. Das Projekt ist unter elastic/mastra-elasticsearch-example verfügbar.

Mastra

Mastra ist ein TypeScript-Framework zur Erstellung agentischer KI-Anwendungen.

Eine Projektstruktur in Mastra sieht wie folgt aus:

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

In Mastra können Sie Agenten, Tools, Workflows und Scores erstellen.

Ein Agent ist eine Klasse, die eine Nachricht als Eingabe akzeptiert und eine Antwort als Ausgabe erzeugt. Ein Agent kann Tools, Large Language Models (LLMs) und einem Speicher verwenden (Abbildung 1).

Die Tools eines Agenten ermöglichen ihm die Interaktion mit der „Außenwelt“, beispielsweise die Kommunikation mit einer Web-API oder die Durchführung einer internen Operation, wie etwa das Abfragen von Elasticsearch. Die Speicherkomponente ist entscheidend für die Speicherung des Konversationsverlaufs, einschließlich früherer Ein- und Ausgaben. Dank dieser gespeicherten Kontextinformationen kann der Agent anhand früherer Interaktionen fundiertere und relevantere Antworten auf künftige Fragen geben.

Workflows ermöglichen Ihnen die Definition komplexer Aufgabenabläufe anhand klarer, strukturierter Schritte, anstatt sich auf die Argumentation eines einzelnen Agenten zu verlassen (Abbildung 2). Sie geben Ihnen die volle Kontrolle über die Aufteilung von Aufgaben, den Datenaustausch zwischen ihnen und den Zeitpunkt der Ausführung. Workflows werden standardmäßig über die integrierte Ausführungs-Engine ausgeführt oder können auf Workflow-Runner bereitgestellt werden.

In Mastra können Sie außerdem Scores definieren. Dabei handelt es sich um automatisierte Tests, die die Ausgaben der Agenten mithilfe modellbasierter, regelbasierter und statistischer Methoden bewerten. Scorer geben Scores zurück: numerische Werte (in der Regel zwischen 0 und 1), die messen, wie gut eine Ausgabe Ihre Bewertungskriterien erfüllt. Diese Scores ermöglichen Ihnen eine objektive Leistungsüberwachung, den Vergleich verschiedener Ansätze und die Ermittlung von Verbesserungsmöglichkeiten in Ihren KI-Systemen. Scorer können mit Ihren eigenen Prompts und Scoring-Funktionen angepasst werden.

Elasticsearch

Für die Ausführung des Demoprojekts benötigen wir eine laufende Elasticsearch-Instanz. Sie können eine kostenlose Testversion von Elastic Cloud aktivieren oder Elasticsearch lokal mithilfe des Skripts start-local installieren:

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

Dadurch werden Elasticsearch und Kibana auf Ihrem Computer installiert und ein API-Schlüssel generiert, der zur Konfiguration der Mastra-Integration verwendet wird.

Der API-Schlüssel wird als Ausgabe des vorherigen Befehls angezeigt und in einer .env-Datei im Ordner elastic-start-local gespeichert.

Demo installieren und konfigurieren

Wir haben ein Elastic/mastra-elasticsearch-example-Repository erstellt, das den Quellcode des Demoprojekts enthält. Das im Repository bereitgestellte Beispiel veranschaulicht, wie Sie in Mastra einen Agenten erstellen, der eine RAG-Architektur zum Abrufen von Dokumenten aus Elasticsearch implementiert.

Wir haben für die Demo einen Datensatz zu Science-Fiction-Filmen bereitgestellt. Wir haben 500 Filme aus dem IMDb-Datensatz auf Kaggle extrahiert.

Der erste Schritt besteht in der Installation der Abhängigkeiten des Projekts mit npm. Verwenden Sie dazu den folgenden Befehl:

npm install

Anschließend müssen wir die .env-Datei konfigurieren, die die Einstellungen enthalten wird. Wir können diese Datei generieren, indem wir die Struktur aus der .env.example-Datei mit folgendem Befehl kopieren:

cp .env.example .env

Nun können wir die .env-Datei bearbeiten, indem wir die fehlenden Informationen hinzufügen:

OPENAI_API_KEY=
ELASTICSEARCH_URL=
ELASTICSEARCH_API_KEY=
ELASTICSEARCH_INDEX_NAME=scifi-movies

Der Name des Elasticsearch-Index lautet scifi-movies. Auf Wunsch können Sie ihn mithilfe der .env-Variablen ELASTICSEARCH_INDEX_NAME ändern.

Wir haben OpenAI als Einbettungsdienst verwendet, was bedeutet, dass Sie einen API-Schlüssel für OpenAI in der .env-Variablen OPENAI_API_KEY angeben müssen.

Das im Beispiel verwendete Einbettungsmodell ist openai/text-embedding-3-small, mit einer Einbettungsdimension von 1536.

Zur Generierung der endgültigen Antwort haben wir das Modell openai/gpt-5-nano verwendet, um die Kosten zu senken.

Die RAG-Architektur ermöglicht die Verwendung eines weniger leistungsfähigen (und in der Regel kostengünstigeren) finalen LLM-Modells, da die Hauptarbeit der Beantwortung durch die Retrieval-Komponente (in diesem Fall Elasticsearch) erledigt wird.

Das kleinere LLM ist nur für zwei Hauptaufgaben zuständig:

• Umformulierung/Einbettung der Abfrage: Umwandlung der in natürlicher Sprache formulierten Frage des Nutzers in eine Vektoreinbettung für die semantische Suche.
• Antwortsynthese: Die relevanten, abgerufenen Kontextfragmente (Dokumente/Filme) werden gemäß den vorgegebenen Anweisungen zu einer kohärenten, endgültigen und für Menschen lesbaren Antwort zusammengeführt.

Da der RAG-Prozess den genauen sachlichen Kontext liefert, der für die Antwort benötigt wird, muss das endgültige LLM weder umfangreich noch hochkomplex sein und es muss nicht das gesamte erforderliche Wissen innerhalb seiner eigenen Parameter besitzen (was die Stärke großer, teurer Modelle ist). Es fungiert im Wesentlichen als ausgeklügelter Textzusammenfasser und -formatierer für den von Elasticsearch bereitgestellten Kontext und nicht als vollwertige Wissensdatenbank an sich. Auf diese Weise lassen sich Modelle wie gpt-5-nano zur Kosten- und Latenzoptimierung verwenden.

Nach der Konfiguration der .env-Datei können Sie die Filme mithilfe des folgenden Befehls in Elasticsearch ingestieren:

npx tsx src/utility/store.ts

Der Ausgabe sollte wie folgt aussehen:

🚀 Starting ingestion of 500 movies from 500_scifi_movies.jsonl...
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 1/500 (0%) | ok:1 | fail:0 | chunks:1 | eta:19m 33s | current:Capricorn One
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 2/500 (0%) | ok:2 | fail:0 | chunks:2 | eta:10m 32s | current:Doghouse
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 3/500 (1%) | ok:3 | fail:0 | chunks:3 | eta:7m 33s | current:Dinocroc
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 4/500 (1%) | ok:4 | fail:0 | chunks:7 | eta:6m 10s | current:Back to the Future           
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 5/500 (1%) | ok:5 | fail:0 | chunks:9 | eta:5m 14s | current:The Projected Man            
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 6/500 (1%) | ok:6 | fail:0 | chunks:11 | eta:4m 41s | current:I, Robot
...
✅ Ingestion complete in 1m 46s. Success: 500, Failed: 0, Chunks: 693.

Das Mapping des Science-Fiction-Filmindex enthält die folgenden Felder:

• Einbettung, dense_vector mit 1536 Dimensionen, Kosinus-Ähnlichkeit.
• Beschreibung, Text mit der Beschreibung des Films.
• Regisseur, Text mit dem Namen des Regisseurs.
• Titel Text mit dem Titel des Films.

Wir haben die Einbettungen anhand des Titels und der Beschreibung generiert. Da Titel und Beschreibung zwei separate Felder sind, stellt die Verknüpfung beider sicher, dass der resultierende Einbettungsvektor sowohl die spezifische, einzigartige Identität (Titel) als auch den reichhaltigen, beschreibenden Kontext (Beschreibung) des Films erfasst, was zu genaueren und umfassenderen semantischen Suchergebnissen führt. Durch diese kombinierte Eingabe erhält das Einbettungsmodell eine bessere einheitliche Darstellung des Dokumentinhalts für den Ähnlichkeitsabgleich.

Demo ausführen

Sie können die Demo mit folgendem Befehl ausführen:

npm run dev

Dieser Befehl startet eine Webanwendung unter localhost:4111, um auf Mastra Studio zuzugreifen (Abbildung 3).

Mastra Studio bietet eine interaktive Benutzeroberfläche zum Erstellen und Testen Ihrer Agenten sowie eine REST-API, die Ihre Mastra-Anwendung als lokalen Dienst bereitstellt. So können Sie sofort mit der Entwicklung beginnen, ohne sich Gedanken über die Integration machen zu müssen.

Wir haben einen Elasticsearch-Agenten bereitgestellt, der das createVectorQueryTool von Mastra als Tool zur Ausführung semantischer Suchen mit Elasticsearch verwendet. Dieser Agent verwendet den RAG-Ansatz, um relevante Dokumente (d. h. Filme) zu suchen, die die Frage des Nutzers beantworten.

Dieser Agent verwendet folgenden Prompt:

You are a helpful assistant that answers questions based on the provided context.
Follow these steps for each response:

1. First, carefully analyze the retrieved context chunks and identify key information.
2. Break down your thinking process about how the retrieved information relates to the query.
3. Draw conclusions based only on the evidence in the retrieved context.
4. If the retrieved chunks don't contain enough information, explicitly state what's missing.

Format your response as:
THOUGHT PROCESS:
- Step 1: [Initial analysis of retrieved chunks]
- Step 2: [Reasoning based on chunks]

FINAL ANSWER:
[Your concise answer based on the retrieved context]

Important: When asked to answer a question, please base your answer only on the context provided in the tool. 
If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it.
Do not add more information than what is present in the retrieved chunks.
Remember: Explain how you're using the retrieved information to reach your conclusions.

Wenn Sie auf das Menü Mastra Studio > Agents klicken und Elasticsearch-Agent auswählen, können Sie den Agenten über ein Chatsystem testen. Zum Beispiel können Sie Informationen zu Science-Fiction-Filmen mit folgender Frage stellen:

Finden Sie 5 Filme oder Fernsehserien über UFOs.

Sie werden bemerken, dass der Agent das vectorQueryTool ausführen wird. Sie können auf das aufgerufene Tool klicken, um sich die Eingabe und die Ausgabe anzusehen. Am Ende der Ausführung beantwortet das LLM Ihre Frage unter Berücksichtigung des Kontexts aus dem „scifi-movies“-Index von Elasticsearch (Abbildung 4).

Mastra führt intern folgende Schritte aus:

1. Vektorumwandlung: Die Frage des Nutzers, Finde 5 Filme oder TV-Serien über UFOs, wird mithilfe des Modells openai/text-embedding-3-small von OpenAI in eine Vektoreinbettung umgewandelt.
2. Vektorsuche: Diese Einbettung wird dann verwendet, um Elasticsearch über eine Vektorsuche abzufragen.
3. Ergebnisabruf: Elasticsearch gibt eine Liste von 10 Filmen zurück, die für die Suchanfrage besonders relevant sind (d. h. die Filme, deren Vektoren dem Suchvektor des Nutzers am nächsten liegen).
4. Antwortgenerierung: Die abgerufenen Filme und die ursprüngliche Nutzerfrage werden an das LLM gesendet, speziell openai/gpt-5-nano. Das LLM verarbeitet diese Informationen und generiert eine endgültige Antwort, um sicherzustellen, dass die Anfrage des Nutzers nach fünf Ergebnissen erfüllt wird.

Der Elasticsearch-Agent

Hier haben wir den Quellcode des Elasticsearch-Agenten veröffentlicht.

import { Agent } from "@mastra/core/agent";
import { ElasticSearchVector } from '@mastra/elasticsearch';
import { createVectorQueryTool } from '@mastra/rag';
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { Memory } from "@mastra/memory";

const es_url = process.env.ELASTICSEARCH_URL;
const es_apikey = process.env.ELASTICSEARCH_API_KEY;
const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME;
const prompt = 'insert here the previous prompt';

const esVector = new ElasticSearchVector({
  id: 'elasticsearch-vector',
  url: es_url,
  auth: {
    apiKey : es_apikey
  }
});

const vectorQueryTool = createVectorQueryTool({
  vectorStore: esVector,
  indexName: es_index_name,
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
});

export const elasticsearchAgent = new Agent({
  id: "elasticsearch-agent",
  name: "Elasticsearch Agent",
  instructions: prompt,
  model: 'openai/gpt-5-nano',
  tools: { vectorQueryTool },
  memory: new Memory(),
});

Das vectorQueryTool ist das Tool, das zur Implementierung des Abrufteils des RAG-Beispiels aufgerufen wird. Es verwendet die ElasticSearchVector-Implementierung, die Elastic zu Mastra beigetragen hat.

Der Agent ist ein Objekt der Agentenklasse, das das vectorQueryTool, den Prompt und einen Speicher verbraucht. Wie Sie sehen können, ist der Code, den wir für die Verbindung von Elasticsearch mit einem Agenten implementieren müssen, sehr minimal.

Fazit

Dieser Artikel verdeutlichte die Einfachheit und Leistungsfähigkeit der Integration von Elasticsearch in das Mastra-Framework zur Entwicklung komplexer agentischer KI-Anwendungen. Konkret haben wir gezeigt, wie ein RAG-Agent erstellt wird, der eine semantische Suche in einem Korpus von Science-Fiction-Filmdaten durchführen kann, die in Elasticsearch indiziert sind.

Ein wichtiger Aspekt ist der direkte Beitrag von Elastic zum Open-Source-Projekt Mastra, der native Unterstützung für Elasticsearch als Vektorspeicher bietet. Diese Integration senkt die Einstiegshürde erheblich, wie der Quellcode des Elasticsearch-Agenten zeigt. Mit der Verwendung von ElasticSearchVector und createVectorQueryTool benötigt die vollständige Einrichtung für die Verbindung von Elasticsearch mit Ihrem Agenten nur wenige Zeilen Konfigurationscode.

Elasticsearch bietet verschiedene erweiterte Features zur Verbesserung der Ergebnisrelevanz. Zum Beispiel steigert die hybride Suche die Genauigkeit erheblich, indem die lexikalische Suche mit Vektorsuche kombiniert wird. Ein weiteres interessantes Feature ist das Reranking mit den neuesten Jina-Modellen, die am Ende der hybriden Suche angewendet werden können. Weitere Informationen zu diesen Technologien finden Sie in den folgenden Artikeln von Elasticsearch Labs:

• Elasticsearch Hybrides Suchen von Valentin Crettaz
• Einführung in Jina-Modelle, ihre Funktionen und ihre Verwendung in Elasticsearch von Scott Martens

Wir empfehlen Ihnen außerdem, sich das bereitgestellte Beispiel anzusehen und damit zu beginnen, Ihre eigenen datengestützten Agenten mit Mastra und Elasticsearch zu entwickeln. Weitere Informationen zu Mastra finden Sie hier in der offiziellen Dokumentation.

Elastic Workflows ist eine in Kibana integrierte Automatisierungs-Engine, mit der Sie mehrstufige Prozesse mithilfe einer einfachen YAML-Konfiguration definieren können. Jeder Workflow kann über einen Zeitplan, ein Ereignis oder als Tool in Elastic Agent Builder ausgelöst werden, und jeder Schritt kann Kibana-APIs aufrufen, Elasticsearch abfragen oder Daten umwandeln.

Wir verwenden die Anzahl der Dashboard-Ansichten als konkretes Beispiel, aber das gleiche Muster gilt für jede Metrik, die über die Kibana-API für gespeicherte Objekte bereitgestellt wird.

Voraussetzungen

• Elastic Cloud oder selbstverwalteter Cluster (Version 9.3)
• Workflows aktiviert (Erweiterte Einstellungen)

Bevor wir etwas bauen, sollten wir uns erst einmal darüber klar werden, welche Daten wir haben. Kibana speichert den Großteil seiner Konfiguration und Metadaten als gespeicherte Objekte in einem separaten internen Index. Kibana erfasst auf diese Weise unter anderem die Anzahl der Dashboard-Aufrufe, indem ein spezieller Typ gespeicherter Objekte namens „Nutzungszähler“ verwendet wird. Sie können sie direkt in Dev Tools abfragen:

GET kbn:/api/saved_objects/_find?type=usage-counter&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"&per_page=10000

Die Reaktion sieht in etwa wie folgt aus:

{
  "page": 1,
  "per_page": 10000,
  "total": 1,
  "saved_objects": [
    {
      "type": "usage-counter",
      "id": "dashboard:346f3c64-ebca-484d-9d57-ec600067d596:viewed:server:20260310",
      "attributes": {
        "domainId": "dashboard",
        "counterName": "346f3c64-ebca-484d-9d57-ec600067d596",
        "counterType": "viewed",
        "source": "server",
        "count": 1
      },
      ...
    }
  ]

Das Feld counterName ist die Dashboard-ID und count ist die kumulierte Anzahl der Aufrufe für dieses Dashboard an diesem bestimmten Tag. Kibana erstellt ein Zählerobjekt pro Dashboard pro Tag; Sie können das Datumssuffix in der Objekt-ID sehen (...viewed:server:20260310). Die Anzahl wächst im Laufe des Tages, wenn Nutzer das Dashboard öffnen.

Anstatt dieses tägliche Dokumentmodell in unserem Index zu replizieren, erstellen wir pro Workflow-Ausführung ein Dokument. Jedes Dokument zeichnet auf, wie viele Aufrufe dieses Dashboard für den Tag zum Zeitpunkt der Erfassung angesammelt hatte.

Schritt 2: Den Zielindex erstellen

Wir benötigen einen Index, um unsere Snapshots der Dashboard-Ansicht zu speichern. Der folgende Befehl erstellt sie mit expliziten Mappings, sodass wir später aggregieren und visualisieren können. Führen Sie dazu in Dev Tools den folgenden Befehl aus:

PUT dashboard-views
{
  "mappings": {
    "properties": {
      "captured_at": {
        "type": "date"
      },
      "dashboard_id": {
        "type": "keyword"
      },
      "dashboard_name": {
        "type": "keyword"
      },
      "view_count": {
        "type": "integer"
      }
    }
  }
}

Die Verwendung von keyword Mappings für IDs und Namen ermöglicht Aggregationen. Die Verwendung von integer für view_count ist ein sicherer Standardwert, da Kibana den Zähler täglich zurücksetzt und das Erreichen des 32-Bit-Limits (mehr als 2 Milliarden Aufrufe an einem einzigen Tag) daher keine realistische Sorge darstellt. Es unterstützt weiterhin numerische Operationen wie max, avgund min und andere.

Schritt 3: Den Workflow erstellen

Gehen Sie zu Stack Management > Workflows > Neuer Workflow, und fügen Sie die folgende Workflow-YAML-Konfiguration ein:

name: dashboard-views-ingestion
triggers:
  - type: scheduled
    with:
      every: 30m

steps:
  - name: fetch_dashboard_views
    type: kibana.request
    with:
      method: GET
      path: >-
        /api/saved_objects/_find?type=usage-counter&per_page=10000&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"

  - name: index_each_dashboard
    type: foreach
    foreach: "{{ steps.fetch_dashboard_views.output.saved_objects }}"
    steps:
      - name: fetch_dashboard_name
        type: kibana.request
        with:
          method: GET
          path: /api/saved_objects/dashboard/{{ foreach.item.attributes.counterName }}
        on-failure:
          continue: true

      - name: index_doc
        type: elasticsearch.request
        with:
          method: POST
          path: /dashboard-views/_doc
          body:
            dashboard_id: "{{ foreach.item.attributes.counterName }}"
            dashboard_name: "{{ steps.fetch_dashboard_name.output.attributes.title }}"
            view_count: "${{ foreach.item.attributes.count | plus: 0 }}"
            captured_at: "{{ execution.startedAt | date: '%Y-%m-%dT%H:%M:%SZ' }}"

Im folgenden Abschnitt werfen wir Schritt für Schritt einen Blick auf den Workflow.

So funktioniert der Workflow

Auslöser

Der Workflow wird alle 30 Minuten mit einem geplanten Auslöser ausgeführt. Dadurch erhalten wir Zeitreihendaten, ohne die API zu überlasten.

fetch_dashboard_views

Verwendet kibana.request , um die Kibana-API für gespeicherte Objekte aufzurufen. Es ist keine Authentifizierungskonfiguration erforderlich: Die Workflow-Engine fügt automatisch die korrekten Header basierend auf dem Ausführungskontext hinzu.

index_each_dashboard (foreach)

Iteriert über das Array saved_objects, das vom vorherigen Schritt zurückgegeben wurde. Das aktuelle Element in jeder Iteration ist als foreach.item verfügbar. Innerhalb der Schleife führen wir zwei verschachtelte Schritte für jedes Dashboard aus.

1. fetch_dashboard_name:

Ermittelt den für Menschen lesbaren Dashboard-Titel durch Aufruf von GET /api/saved_objects/dashboard/{id}. Wir fügen on-failure: continue: true hinzu, damit die Schleife fortgesetzt wird, anstatt dass die gesamte Ausführung fehlschlägt, falls ein Dashboard gelöscht wurde, aber noch Aufrufzähler vorhanden sind.

2. index_doc:

Indexiert jedes Dokument mit POST /dashboard-views/_doc (ohne eine explizite ID), wodurch Elasticsearch IDs automatisch generieren kann. Dadurch wird bei jedem Durchlauf ein neues Dokument erstellt, wodurch eine Historie der Aufrufzahlen im Laufe der Zeit aufgebaut wird, anstatt den vorherigen Snapshot zu überschreiben.

Zwei Dinge, die es zu beachten gilt:

• Das Feld captured_at verwendet den Datumsfilter, um den Zeitstempel als ISO 8601 zu formatieren. Ohne ihn erscheint der Wert als JavaScript-Datumszeichenfolge, wie Tue Mar 10 2026 05:03:47 GMT+0000, die Elasticsearch nicht als Datum abbildet.
• Der Ausdruck view_count verwendet die Syntax ${{ }} mit | plus: 0, um den numerischen Typ beizubehalten. Die Verwendung von {{ }} würde es als Zeichenfolge darstellen, was mathematische Operationen im Dashboard verhindern würde.

Die Benutzeroberfläche ermöglicht eine komfortable Fehlerbehebung jedes einzelnen Workflow-Schritts.

Schritt 4: Das Statistik-Dashboard erstellen

Sobald der Workflow einige Male ausgeführt wurde und Daten gesammelt wurden, erstellen Sie in Kibana ein neues Dashboard mithilfe der Data View „Dashboard-Ansichten“.

Einige Panels für den Anfang:

• Top-Dashboards nach Ansichten: Verwenden Sie ein Balkendiagramm mit dashboard_name auf der X-Achse und last_value(view_count) auf der Y-Achse. Hier wird die aktuelle tägliche Anzahl der Aufrufe pro Dashboard angezeigt.
• Ansichten im Zeitverlauf: Verwenden Sie ein Liniendiagramm mit captured_at auf der X-Achse und last_value(view_count) auf der Y-Achse, unterteilt nach dashboard_name. Da jede Ausführung ein neues Dokument anhängt, verwenden Sie den letzten Wert, um die Spitzenanzahl pro Zeit-Buckets zu erhalten, anstatt Duplikate zu summieren.
• Aktueller Snapshot: Verwenden Sie eine Datentabelle mit den neuesten captured_at, um die aktuellsten Aufrufzahlen aller Dashboards anzuzeigen.

Da jeder Workflow ein neues Dokument erstellt, können Sie nach Zeitbereich filtern, um die Aktivität in bestimmten Zeiträumen zu analysieren, Vergleiche von Woche zu Woche anzustellen oder Alerts zu erstellen, wenn ein Dashboard unter einen Ansichtsschwellenwert fällt.

Fazit

Elastic Workflows eignet sich gut für diese Art von periodischer Datenerhebung, da sowohl die Quelle (Kibana API) als auch das Ziel (Elasticsearch) native sind, was bedeutet, dass keine Zugangsdaten verwaltet werden. Die Workflow-Engine verwaltet die Authentifizierung für die Schritte kibana.request und elasticsearch.request automatisch, sodass Sie nur die Logik schreiben müssen.

Ressourcen

• Elastic-Workflows
• Kibana-API

Elasticsearch lehnte verspätet eintreffende Metriken ab. Dies führte zu Verzögerungen in der Pipeline. Dadurch wurden wiederum weitere verspätete Daten generiert, was noch mehr Ablehnungen zur Folge hatte. Schließlich kam die Pipeline vollständig zum Stillstand.

Wir mussten die Daten aus einem Snapshot wiederherstellen, die Daten neu indizieren und die Ingestion-Pipeline neu gestalten, um die Wiederherstellung zu ermöglichen.

Die eigentliche Ursache lag nicht in der Verwaltung des Indexlebenszyklus (ILM) selbst. Es ging um Zeitreihendatenströme (TSDS) und wie diese zeitgebundene Sicherungsindizes erzwingen.

TSDS kann die Speicherplatzanforderungen für Metriken um 40–70 % reduzieren, aber die architektonischen Änderungen, die TSDS effizient machen, verändern auch das Verhalten von Indizes im Laufe der Zeit. Diese Änderungen sind wichtig bei der Gestaltung von ILM-Richtlinien oder wenn Ihre Ingestion-Pipelines möglicherweise verspätet eintreffende Daten erzeugen.

TL;DR

Bei Verwendung von TSDS:

• Sicherungsindizes akzeptieren nur Dokumente innerhalb eines bestimmten Zeitfensters.
• Wenn verspätete Daten eintreffen, nachdem ein Index in den Status „kalt“ oder „eingefroren“ versetzt wurde, weist Elasticsearch diese Dokumente zurück oder leitet sie, falls konfiguriert, an den Fehlerspeicher weiter.

Designregel:

warm_min_age > rollover_max_age + maximum_expected_lateness

Was ist ein Zeitreihendatenstrom?

Ein Zeitreihendatenstrom (TSDS) ist ein spezieller Datenstrom, der für Metrikdaten optimiert ist. Die Daten werden so weitergeleitet, dass zugehörige Dokumente innerhalb derselben Shards liegen, wodurch sie für Abfrage und Abruf optimiert werden. So funktioniert dies in Elasticsearch:

Jedes Dokument enthält:

• Ein Zeitstempel.
• Dimensionsfelder, die die Zeitreihen identifizieren.
• Metrische Felder, die Messwerte darstellen.

Dazu ein paar Beispiele:

• CPU-Auslastung pro Host.
• Anfragenlatenzen pro Dienst.
• Temperaturmessungen pro Sensor.

Dimensionen geben an, was wir messen möchten, während Metriken Werte darstellen, die sich im Laufe der Zeit ändern.

Abmessungen

Die Abmessungen beschreiben das gemessene Objekt.

Beispiele:

host.name
service.name
container.id

Wir definieren sie in den Mappings mit:

time_series_dimension: true

Metriken

Metriken stellen numerische Werte dar und werden wie folgt definiert:

time_series_metric

Gängige Arten von Metriken:

• Messanzeigen: Werte, die steigen und fallen.
• Zähler: Werte, die bis zum Zurücksetzen ansteigen.

Elastic Agent sammelt in erster Linie Metriken und Protokolldaten. Selbst wenn Sie also keine TSDS-Indizes manuell aktiviert haben, können diese dennoch in Ihrem Cluster vorhanden sein.

Das _tsid-Feld

Elasticsearch generiert intern einen _tsid-Wert aus Dimensionsfeldern. Dadurch können Dokumente mit identischen Abmessungen an denselben Shard weitergeleitet werden, was folgende Vorteile mit sich bringt:

• Kompression.
• Abfrageort.
• Aggregationsleistung.

Der wesentliche Unterschied: zeitgebundene Sicherungsindizes

Herkömmliche Datenströme schreiben immer in den aktuellsten Sicherungsindex, der als Schreibindex bezeichnet wird, aber TSDS verhält sich anders.

Jeder TSDS-Sicherungsindex hat ein definiertes Zeitfenster und akzeptiert nur Dokumente mit @timestamp-Werten, die in dieses Zeitfenster fallen:

GET _data_stream/my-metrics-data-stream


     "index_mode": "time_series",
     "time_series": {
       "temporal_ranges": [
         {
           "start": "2026-01-15T14:35:50.000Z",
           "end": "2026-03-16T11:34:40.000Z"
         }
       ]
     }

Wenn ein Dokument indexiert wird, leitet Elasticsearch es an den für diesen Zeitstempel zuständigen Sicherungsindex weiter. Das bedeutet, dass ein TSDS im Gegensatz zu herkömmlichen Indizes gleichzeitig auf mehrere Sicherungsindizes schreiben kann.

Zum Beispiel:

• Echtzeit-Daten → aktuellster Index.
• Verspätete Daten → ein früherer Index, der diesen Zeitbereich abdeckt.

Gestaltung für verspätet eintreffende Daten

Echte Ingestion-Pipelines liefern Metriken nur selten perfekt und pünktlich. Die Metriken können sich aufgrund von Netzwerkausfällen, Rückständen auf dem Übertragungsweg, Batch-Ingestion und dem Ausfall von Edge-Geräten verzögern, die sich dann wieder verbinden und den Rückstand aufholen.

Herkömmliche Indizes gleichen diese Verzögerungen stillschweigend aus. TSDS tut dies nicht.

Wenn der Zeitstempel eines Dokuments außerhalb des Bereichs der beschreibbaren Sicherungsindizes liegt, wird es von Elasticsearch abgelehnt. Das bedeutet, dass Ihre ILM-Richtlinie verspätete Daten berücksichtigen muss.

Die kritische Einschränkung

Unterstützende Indizes müssen lange genug beschreibbar bleiben, um verzögerte Daten zu akzeptieren.

Konkret bedeutet dies:

time_until_readonly > maximum_expected_lateness

Da ILM das Alter ab dem Rollover misst, lautet die operative Regel:

warm_or_cold_min_age > rollover_max_age + maximum_expected_lateness

Wenn beispielsweise Metriken bis zu sechs Stunden verspätet eintreffen können, müssen Indizes mindestens sechs Stunden nach dem Rollover beschreibbar bleiben.

Dass diese Einschränkung nicht berücksichtigt wurde, war genau die Ursache für den zuvor beschriebenen Ingestion-Fehler. Verspätet eintreffende Daten wurden an einen früheren Index weitergeleitet, der sich bereits im Cold Tier befand und daher für Schreibvorgänge gesperrt war.

Umgang mit abgelehnten Dokumenten

Wenn TSDS ein Dokument ablehnt, gibt Elasticsearch eine Fehlermeldung aus, die darauf hinweist, dass der Zeitstempel nicht in den Bereich der beschreibbaren Indizes fällt. Die Art und Weise, wie Ihre Ingestion-Pipeline mit diesem Fehler umgeht, bestimmt, ob Sie Daten verlieren oder die Ingestion unterbrechen.

Der primäre Mechanismus für den Umgang mit abgelehnten Dokumenten ist der Fehlerspeicher.

Fehlerspeicher (empfohlen in Elasticsearch 9.1+)

Mit Elasticsearch 9.1 wurde der Fehlerspeicher eingeführt, der automatisch abgelehnte Dokumente erfasst. Anstatt Fehler an Clients zurückzuleiten, schreibt Elasticsearch fehlgeschlagene Dokumente in einen dedizierten Fehlerindex innerhalb des Datenstroms.

Sie können Fehler inspizieren, indem Sie:

GET metrics-myapp::failures/_search

Die Verwendung des Fehlerspeichers verhindert, dass Ingestion-Pipelines aufgrund von Ablehnungsfehlern überlastet werden, während fehlgeschlagene Daten für Analysen oder erneute Indexierung aufbewahrt werden.

Probleme bei der Ablehnung überwachen

Bei spät auftretenden Problemen zeigen sich zunächst meist Ingestion-Anomalien. Zunächst fallen sie Ihnen möglicherweise auf als:

• Plötzliche Rückgänge der Indexierungsrate.
• Sprunghafte Anstiege bei abgelehnten Dokumenten.
• Eine wachsende Anzahl von Einträgen im Fehlerspeicher.
• Abweichungen zwischen den Eingangs- und Ausgangswerten der Pipeline.

Durch die Warnmeldung bei diesen Signalen können die Betreiber Probleme erkennen, bevor es zu einem Stillstand der Pipelines kommt. Workflows, Machine Learning-Jobs und andere Mechanismen können verwendet werden, um die Erkennung und Benachrichtigung zu automatisieren.

Migrationscheckliste für TSDS + ILM

Wenn Sie einen Metrik-Cluster auf TSDS migrieren, ILM-Tiering einsetzen oder auf eine Elasticsearch-Version upgraden, bei der die Metriken standardmäßig als TSDS erfasst sind, überprüfen Sie diese Punkte zuerst.

1. Ingestion-Latenz messen

Vor der Änderung der ILM-Richtlinien ist Folgendes festzulegen:

• Normale Ingestion-Verzögerung.
• Maximale Verzögerung bei Vorfällen.
• Verzögerungen durch Batch-Pipelines.

Ihr ILM-Design muss die maximale realistische Verzögerung berücksichtigen.

2. Indexzeitfenster überprüfen

Inspizieren Sie Ihre TSDS-Sicherungsindizes:

GET _data_stream/

Suchen Sie nach:

• time_series.start_time
• time_series.end_time

Diese Grenzen legen fest, welche Indizes Dokumente aufnehmen können. Das Verständnis dieser Zeitfenster kann Ihnen dabei helfen, zu ermitteln, wie spät Daten eintreffen dürfen, bevor sie abgelehnt werden.

3. Die Dimension der „heißen“ Ebene für verspätet eintreffende Daten bestimmen

Stellen Sie sicher, dass die unterstützenden Indizes lange genug beschreibbar bleiben, um verzögerte Daten zu verarbeiten.

Betriebsregel:

• warm_min_age > rollover_max_age + maximum_expected_lateness

Denken Sie daran, dass Indizes mindestens sechs Stunden beschreibbar bleiben müssen, wenn Metriken sechs Stunden zu spät eintreffen.

4. Entscheiden Sie, wie mit abgelehnten Dokumenten umgegangen werden soll

Wählen Sie eine Strategie, bevor Sie TSDS aktivieren:

• Fehlerspeicher (empfohlen in Elasticsearch 9.1+).
• Warteschlange für unzustellbare Nachrichten in Logstash.
• Fallback-Index für verspätete Eingänge.
• Akzeptanz von begrenztem Datenverlust.

5. Ingestion-Status überwachen

Warnmeldungen hinzufügen für:

• Die Indexierungsrate sinkt.
• Abgelehnte Dokumente.
• Das Fehlerspeicherwachstum.
• Diskrepanzen zwischen Pipeline-Eingabe und -Ausgabe.

Verspätete Datenprobleme treten oft zuerst als Ingestion-Anomalien auf.

Zusammenfassung

Zeitreihendatenströme bieten erhebliche Speicher- und Leistungsverbesserungen für Metrik-Workloads, bringen aber eine wichtige architektonische Änderung mit sich: Sicherungsindizes sind zeitgebunden, was das Verhalten von ILM beeinflusst.

Bei Verwendung von TSDS:

• Indizes müssen lange genug beschreibbar bleiben, um verzögerte Daten zu akzeptieren.
• Ingestion-Pipelines sollten abgelehnte Dokumente sicher verarbeiten.

Die wichtigste Regel lautet:

warm_min_age > rollover_max_age + maximum_expected_lateness

Wenn Sie Ihre ILM-Richtlinien unter Berücksichtigung dieser Einschränkung gestalten, eignet sich TSDS hervorragend für Metrik-Workloads.

Wenn Sie dies jedoch ignorieren, könnte Ihre Ingestion-Pipeline diese Zeitgrenzen auf die harte Tour erfahren.

Ihre erste Abfrage

Definieren Sie zunächst ein einfaches altes CLR-Objekt (POCO), das auf Ihren Elasticsearch-Index abgebildet wird. Eigenschaftsnamen werden über Standardattribute System.Text.Json , wie z. B. [JsonPropertyName], oder über ein konfiguriertes JsonNamingPolicy in ES|QL-Spaltennamen aufgelöst. Die gleichen Regeln für die Quellenserialisierung, die für den Rest des Clients gelten, gelten auch hier.

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_id")]
    public string Id { get; set; }

    public string Name { get; set; }

    public string Brand { get; set; }

    [JsonPropertyName("price_usd")]
    public double Price { get; set; }

    [JsonPropertyName("in_stock")]
    public bool InStock { get; set; }
}

Nachdem der Typ festgelegt wurde, sieht eine Abfrage folgendermaßen aus:

var minPrice = 100.0;
var brand = "TechCorp";

await foreach (var product in client.Esql.QueryAsync(q => q
    .From("products")
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10)))
{
    Console.WriteLine($"{product.Name}: ${product.Price}");
}

Der Anbieter übersetzt dies in folgende ES|QL:

FROM products
| WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand)
| SORT price_usd DESC
| LIMIT 10

Ein paar Details, die zu beachten sind:

• Namensauflösung der Eigenschaften: p.Price wird aufgrund des Attributs [JsonPropertyName] zu price_usd , und p.Brand wird gemäß der Standard-CamelCase-Namenskonvention zu brand .
• Parametererfassung: Die C#-Variablen minPrice und brand werden als benannte Parameter erfasst (?minPrice, ?brand). Sie werden separat von der Abfragezeichenfolge im JSON-Payload gesendet, was Injektionen verhindert und serverseitiges Abfrageplan-Caching ermöglicht.
• Streaming: QueryAsync<T> gibtIAsyncEnumerable<T> zurück. Zeilen werden einzeln materialisiert, sobald sie von Elasticsearch eintreffen.

Sie können auch die generierte Abfrage und ihre Parameter inspizieren, ohne sie auszuführen:

var query = client.Esql.CreateQuery()
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE (in_stock == true AND price_usd >= 100) | SORT price_usd DESC | LIMIT 10

Console.WriteLine(query.ToEsqlString(inlineParameters: false));
// FROM products | WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand) | SORT price_usd DESC | LIMIT 10

var parameters = query.GetParameters();
// { "minPrice": 100.0, "brand": "TechCorp" }

Wie funktioniert das? Eine kurze LINQ-Auffrischung

Der Mechanismus, der LINQ-Anbieter ermöglicht, ist die Unterscheidung zwischen IEnumerable<T> und IQueryable<T>.

Wenn Sie.Where(p => p.Price > 100) auf einem IEnumerable<T>aufrufen, kompiliert die Lambda zu einem Func<Product, bool>, einem regulären Delegierten, den die Laufzeit während des Prozesses ausführt. Dies ist LINQ-to-Objects.

Wenn Sie dieselbe Methode auf einem IQueryable<T>aufrufen, umwickelt der C#-Compiler stattdessen das Lambda in einem Expression<Func<Product, bool>> . Dies ist eine Datenstruktur, die die Struktur des Codes repräsentiert und nicht seine ausführbare Form. Der Ausdrucksbaum kann zur Laufzeit inspiziert, analysiert und in eine andere Sprache übersetzt werden.

// IEnumerable: the lambda is a compiled delegate
IEnumerable local = products.Where(p => p.Price > 100);

// IQueryable: the lambda is an expression tree, a data structure
IQueryable remote = queryable.Where(p => p.Price > 100);

Die IQueryProvider Schnittstelle ist der Erweiterungspunkt. Jeder Anbieter kann CreateQuery<T> und Execute<T> implementieren, um diese Ausdrucksbäume in eine Zielsprache zu übersetzen. Entity Framework verwendet dies, um SQL auszugeben. Der LINQ to ES|QL-Anbieter verwendet es, um ES|QL zu emittieren.

Der Ausdrucksbaum für die obige Abfrage sieht wie folgt aus:

Ausdrucksbaum für die Beispielabfrage.

Der Baum ist von innen nach außen verschachtelt: Take umschließt OrderByDescending, welches Where umschließt, welches From umschließt, welches die Wurzel EsqlQueryable<Product> Konstante umschließt. Das Where -Prädikat ist selbst ein Teilbaum von BinaryExpression Knoten für die Operatoren &&, >=, und == , mit MemberExpression Blättern für Eigenschaften-Zugriffe und Abschluss-Erfassungen für die Variablen minPrice und brand . Dies ist die Datenstruktur, die der Provider durchläuft, um das endgültige ES|QL zu erzeugen.

Unter der Haube: Die Übersetzungspipeline

Der Weg von einem LINQ-Ausdruck zu den Abfrageergebnissen folgt einer sechsstufigen Pipeline:

Überblick über die Übersetzungspipeline.

1. Erfassung des Ausdrucksbaums

Wenn man .Where(), .OrderBy(), .Take() und andere Operatoren auf einem IQueryable<T> verkettet, erstellt die Standard-LINQ-Infrastruktur einen Ausdrucksbaum. EsqlQueryable<T> implementiert IQueryable<T> und delegiert an EsqlQueryProvider.

2. Übersetzung

Wenn die Abfrage ausgeführt wird (durch Enumerieren, Aufrufen von ToList() oder Verwenden von await foreach)), durchläuft EsqlExpressionVisitor den Ausdrucksbaum von innen nach außen. Es sendet jeden LINQ-Methodenaufruf an einen spezialisierten Besucher:

Bei der Übersetzung werden in Ausdrücken referenzierte C#-Variablen als benannte Parameter erfasst.

3. Abfragemodell

Die Besucher produzieren nicht direkt Zeichenfolgen. Stattdessen produzieren sie QueryCommand Objekte, eine unveränderliche Zwischenrepräsentation. Ein FromCommand, ein WhereCommand, ein SortCommand und ein LimitCommand, jeweils einen ES|QL-Verarbeitungsbefehl repräsentierend. Diese werden in einem EsqlQuery Modell gesammelt.

Abfragemodell und Befehlsmuster.

Dieses Zwischenmodell ist vom Ausdrucksbaum und vom Ausgangsformat entkoppelt. Es kann inspiziert, abgefangen (über IEsqlQueryInterceptor) oder vor der Formatierung modifiziert werden.

4. Formatierung

EsqlFormatter besucht jede QueryCommand in der richtigen Reihenfolge und erstellt die finale ES|QL-Zeichenfolge. Jeder Befehl wird zu einer Zeile, getrennt durch den Pipe-Operator (|), den ES|QL zur Verkettung von Verarbeitungsbefehlen verwendet. Bezeichner, die Sonderzeichen enthalten, werden automatisch mit Backticks versehen.

5. Ausführung

Die formatierte ES|QL-Zeichenfolge und erfasste Parameter werden als JSON-Payload an den /_query -Endpunkt von Elasticsearch gesendet. Die Schnittstelle IEsqlQueryExecutor abstrahiert die Transportschicht, an der die geschichtete Paketarchitektur zum Tragen kommt.

6. Materialisierung

EsqlResponseReader streamt die JSON-Reaktion, ohne das gesamte Ergebnis-Set in den Speicher zu puffern. Ein ColumnLayout -Baum, der einmal pro Abfrage vorab berechnet wird, ordnet flache ES|QL-Spaltennamen (wie address.street, address.city) verschachtelten POCO-Eigenschaften zu. Jede Zeile wird zu einer T -Instanz zusammengestellt und einzeln über IEnumerable<T> oder IAsyncEnumerable<T> zurückgegeben.

Die mehrschichtige Architektur

Die LINQ-to-ES|QL-Funktionalität ist auf drei Pakete aufgeteilt:

Paketarchitektur.
Elastic.Esql ist die reine Übersetzungsmaschine. Es hat keine HTTP-Abhängigkeiten und enthält die Expression Visitors, das Abfragemodell, den Formatter und den Response Reader. Sie können es eigenständig verwenden, um ES|QL-Abfragen ohne Elasticsearch-Verbindung zu erstellen und zu inspizieren, was für Tests, Abfrageprotokollierung oder den Aufbau einer eigenen Ausführungsschicht nützlich ist.

// Translation-only: no Elasticsearch connection needed
var provider = new EsqlQueryProvider();
var query = new EsqlQueryable(provider)
    .From("products")
    .Where(p => p.InStock)
    .OrderByDescending(p => p.Price);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE in_stock == true | SORT price_usd DESC

Elastic.Clients.Esql ist ein leichter, eigenständiger ES|QL-Client. Es fügt die HTTP-Ausführung über Elastic.Esql mittels Elastic.Transport hinzu. Wenn Ihre Anwendung nur ES|QL und keine der anderen Elasticsearch-APIs benötigt, ist dies die Option mit den geringsten Abhängigkeiten.

Elastic.Clients.Elasticsearch ist der vollständige Elasticsearch.NET-Client. Es baut außerdem auf Elastic.Esql auf und stellt den LINQ-Provider über den Namespace client.Esql bereit. Dies ist der empfohlene Einstieg für die meisten Anwendungen.

Beide Ausführungsschicht-Pakete bieten ihre eigene Implementierung von IEsqlQueryExecutor, der Strategieschnittstelle, die Übersetzung und Transport miteinander verbindet.

Alle drei Pakete sind mit Native AOT kompatibel, wenn sie mit einem quellgenerierten JsonSerializerContext verwendet werden. Für den vollständigen Client siehe die Native AOT-Dokumentation.

Über die Grundlagen hinaus

Das obige Beispiel umfasste das Filtern, Sortieren und Paginieren. Der Anbieter unterstützt ein breiteres Spektrum an Operationen.

Aggregationen

GroupBy, kombiniert mit Aggregatfunktionen in Select, übersetzt in ES|QL STATS ... BY:

var stats = client.Esql.Query(q => q
    .GroupBy(p => p.Brand)
    .Select(g => new
    {
        Brand = g.Key,
        Count = g.Count(),
        AvgPrice = g.Average(p => p.Price),
        MaxPrice = g.Max(p => p.Price)
    }));

// -> FROM products | STATS COUNT(*), AVG(price_usd), MAX(price_usd) BY brand

Projektionen

Select, mit anonymen Typen erzeugt die Befehle EVAL, KEEP und RENAME:

var query = client.Esql.CreateQuery()
    .Select(p => new { ProductName = p.Name, p.Price, p.InStock });

// -> FROM products | KEEP name, price_usd, in_stock | RENAME name AS ProductName

Umfassende Funktionsbibliothek

Über 80 ES|QL-Funktionen sind über die EsqlFunctions -Klasse verfügbar und decken Datum/Uhrzeit, Zeichenfolgen, Mathematik, IP, Musterabstimmung und Wertung ab. Die Standardmethoden Math.* und string.* werden ebenfalls übersetzt:

.Where(p => p.Name.Contains("Pro"))       // -> WHERE name LIKE "*Pro*"
.Where(p => EsqlFunctions.CidrMatch(      // -> WHERE CIDR_MATCH(ip, "10.0.0.0/8")
    p.IpAddress, "10.0.0.0/8"))

LOOKUP JOIN

Indexübergreifende Suchvorgänge werden in ES|QL LOOKUP JOIN übersetzt:

var enriched = client.Esql.Query(q => q
    .LookupJoin(
        "category-lookup-index",
        product => product.Id,
        category => category.CategoryId,
        (product, category) => new { product.Name, category!.CategoryLabel }));

Raw ES|QL Umgehungsmöglichkeit

Für ES|QL-Features, die vom LINQ-Anbieter noch nicht unterstützt werden, können Sie Rohfragmente anfügen:

var results = client.Esql.Query(q => q
    .Where(p => p.InStock)
    .RawEsql("| EVAL discounted = price_usd * 0.9"));

Serverseitige asynchrone Abfragen

Bei langlaufenden Abfragen sollten diese zur Hintergrundverarbeitung auf dem Server eingereicht werden:

await using var asyncQuery = await client.Esql.SubmitAsyncQueryAsync(
    q => q.Where(p => p.InStock),
    asyncQueryOptions: new EsqlAsyncQueryOptions
    {
        WaitForCompletionTimeout = TimeSpan.FromSeconds(5),
        KeepAlive = TimeSpan.FromMinutes(10)
    });

await asyncQuery.WaitForCompletionAsync();
await foreach (var product in asyncQuery.AsAsyncEnumerable())
    Console.WriteLine(product.Name);

Serverseitige asynchrone Abfragen sind besonders nützlich für langlaufende analytische Abfragen / die Verarbeitung großer Datensätze, die die typischen Timeout-Schwellenwerte überschreiten könnten, oder in Timeout-sensiblen Umgebungen mit Load-Balancern, API-Gateways oder Proxys, die strikte HTTP-Timeouts durchsetzen. Asynchrone Abfragen vermeiden Verbindungsabbrüche, indem die Übermittlung von dem Abruf der Ergebnisse entkoppelt wird.

Erste Schritte

LINQ to ES|QL ist verfügbar ab:

• Elastic.Clients.Elasticsearch v9.3.4 (9.x branch)
• Elastic.Clients.Elasticsearch v8.19.18 (8.x Branch)

Installation über NuGet:

dotnet add package Elastic.Clients.Elasticsearch

Die Einstiegspunkte befinden sich auf client.Esql:

Eine vollständige Feature-Referenz – einschließlich Abfrageoptionen, Zugriff auf mehrere Felder, verschachtelter Objekte und der Verarbeitung mehrwertiger Felder – finden Sie in der LINQ to ES|QL-Dokumentation.

Fazit

LINQ to ES|QL bringt die volle Ausdruckskraft von C# LINQ in die ES|QL-Abfragesprache von Elasticsearch, sodass Sie stark typisierte, kombinierbare Abfragen schreiben können, ohne Abfragezeichenfolgen von Hand erstellen zu müssen. Mit automatischer Parametererfassung, Streaming-Materialisierung und einer geschichteten Paketarchitektur, die von eigenständiger Übersetzung zum vollständigen Elasticsearch-Client skaliert, fügt es sich natürlich in .NET-Anwendungen jeder Größe ein. Installieren Sie den neuesten Client, verweisen Sie Ihre LINQ-Ausdrücke auf einen Index und überlassen Sie den Rest dem Provider.

In diesem Artikel untersuchen wir die Vorteile der Entwicklung eines benutzerdefinierten Elasticsearch MCP-Servers und zeigen, wie man einen in TypeScript erstellt, der Elasticsearch mit LLM-gestützten Anwendungen verbindet.

Warum einen benutzerdefinierten Elasticsearch MCP-Server entwickeln?

Elastic bietet einige Alternativen für MCP-Server:

• Elastic Agent Builder MCP-Server für Elasticsearch 9.2+
• Elasticsearch MCP-Server für ältere Versionen (Python)

Wenn Sie mehr Kontrolle darüber benötigen, wie Ihr MCP-Server mit Elasticsearch interagiert, bietet Ihnen die Entwicklung eines eigenen benutzerdefinierten Servers die nötige Flexibilität, um ihn genau an Ihre Bedürfnisse anzupassen. Zum Beispiel ist der MCP-Endpoint von Agent Builder auf Elasticsearch Query Language (ES|QL) Abfragen beschränkt, während ein benutzerdefinierter Server die Verwendung des vollständigen Abfrage-DSL ermöglicht. Sie erhalten außerdem die Kontrolle über die Formatierung der Ergebnisse, bevor sie an das LLM weitergeleitet werden, und können zusätzliche Verarbeitungsschritte integrieren, wie die OpenAI-gestützte Zusammenfassung, die wir in dieses Tutorial implementieren.

Am Ende dieses Artikels verfügen Sie über einen MCP-Server in TypeScript, der in einem Elasticsearch-Index gespeicherte Informationen durchsucht, zusammenfasst und Zitate bereitstellt. Wir verwenden Elasticsearch für den Abruf, das gpt-4o-mini-Modell von OpenAI zur Zusammenfassung und Erzeugung von Zitaten sowie Claude Desktop als MCP-Client und Benutzeroberfläche, um Nutzeranfragen zu empfangen und darauf zu reagieren. Das Endergebnis ist ein interner Wissensassistent, der Entwicklern dabei hilft, Best Practices in der technischen Dokumentation ihres Unternehmens zu entdecken und zu synthetisieren.

Voraussetzungen:

• Node.js 20+
• Elasticsearch
• OpenAI-API-Schlüssel
• Claude Desktop

Was ist MCP?

MCP ist ein offener Standard, der von Anthropic entwickelt wurde und sichere, bidirektionale Verbindungen zwischen LLMs und externen Systemen wie Elasticsearch ermöglicht. Mehr über den aktuellen Stand von MCP können Sie in diesem Artikel lesen.

Die MCP-Landschaft entwickelt sich täglich weiter, wobei Server für eine Vielzahl von Anwendungsfällen zur Verfügung stehen. In diesem Artikel zeigen wir Ihnen außerdem, wie einfach es ist, Ihren eigenen benutzerdefinierten MCP-Server zu entwickeln.

MCP-Clients

Es gibt eine lange Liste verfügbarer MCP-Clients, von denen jeder seine eigenen Eigenschaften und Einschränkungen hat. Aufgrund seiner Einfachheit und Beliebtheit verwenden wir Claude Desktop als unseren MCP-Client. Er dient als Chat-Schnittstelle, auf der Nutzer Fragen in natürlicher Sprache stellen können, und ruft automatisch die von unserem MCP-Server bereitgestellten Tools auf, um Dokumente zu durchsuchen und Zusammenfassungen zu erstellen.

Erstellen eines Elasticsearch MCP-Servers

Mit dem TypeScript SDK können wir einfach einen Server erstellen, der versteht, wie er unsere Elasticsearch-Daten basierend auf einer Nutzereingabe abfragt.

In diesem Artikel werden die folgenden Schritte zur Integration des Elasticsearch MCP-Servers mit dem Claude Desktop-Client beschrieben:

1. MCP-Server für Elasticsearch konfigurieren.
2. MCP-Server in Claude Desktop laden.
3. Probieren Sie es aus.

MCP-Server für Elasticsearch konfigurieren

Zunächst initialisieren wir eine Node-Anwendung:

npm init -y

Dadurch wird eine package.json-Datei erstellt, wodurch wir damit beginnen können, die notwendigen Abhängigkeiten für diese Anwendung zu installieren.

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

• @elastic/elasticsearch verschafft Ihnen Zugriff auf die Node.js-Bibliothek von Elasticsearch.
• @modelcontextprotocol/SDK stellt die Kerntools bereit, um einen MCP-Server zu erstellen und zu verwalten, Tools zu registrieren und die Kommunikation mit MCP-Clients zu übernehmen.
• OpenAI ermöglicht die Interaktion mit OpenAI-Modellen, um Zusammenfassungen oder Antworten in natürlicher Sprache zu generieren.
• ZOD sorgt dafür, strukturierte Schemata für Eingangs- und Ausgangsdaten in jedem Tool zu definieren und zu validieren.

ts-nodeWährend der Entwicklung werden @types/node und typescript verwendet, um den Code zu schreiben und die Skripte zu kompilieren.

Datensatz einrichten

Um die Daten bereitzustellen, die Claude Desktop über unseren MCP-Server abfragen kann, verwenden wir einen simulierten internen Wissensdatenbank-Datensatz. So sieht ein Dokument aus diesem Datensatz aus:

{
    "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"]
}

Für die Aufnahme der Daten haben wir ein Skript vorbereitet, das einen Index in Elasticsearch erstellt und den Datensatz darin lädt. Sie finden es hier.

MCP-Server

Erstellen Sie eine Datei mit dem Namen index.ts und fügen Sie den folgenden Code hinzu, um die Abhängigkeiten zu importieren und Umgebungsvariablen zu verarbeiten:

// 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";

Außerdem initialisieren wir die Clients, um Elasticsearch- und OpenAI-Aufrufe zu bewältigen:

const openai = new OpenAI({
  apiKey: OPENAI_API_KEY,
});

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

Um unsere Implementierung robuster zu machen und einen strukturierten Eingang und Ausgang zu gewährleisten, definieren wir Schemata mit zod. Dadurch können wir Daten zur Laufzeit validieren, Fehler frühzeitig abfangen und die Tool-Reaktionen einfacher programmatisch verarbeiten.

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;

Erfahren Sie hier mehr über strukturierte Ausgänge.

Nun initialisieren wir den MCP-Server:

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",
});

Definition der MCP-Tools

Wenn alles konfiguriert ist, können wir mit dem Schreiben der Tools beginnen, die von unserem MCP-Server bereitgestellt werden. Dieser Server stellt zwei Tools bereit:

• search_docs: Sucht nach Dokumenten in Elasticsearch mittels Volltextsuche.
• summarize_and_cite: Fasst Informationen aus zuvor abgerufenen Dokumenten zusammen und synthetisiert sie, um eine Nutzerfrage zu beantworten. Dieses Tool fügt außerdem Zitate hinzu, die auf die Quelldokumente verweisen.

Zusammen bilden diese Tools einen einfachen Workflow zum Abrufen und Zusammenfassen, bei dem ein Tool relevante Dokumente abruft und das andere diese Dokumente verwendet, um eine zusammengefasste, zitierte Reaktion zu generieren.

Reaktionsformat des Tools

Jedes Tool kann beliebige Eingangsparameter akzeptieren, muss aber mit folgender Struktur antworten:

• Inhalt: Dies ist die Reaktion des Tools im unstrukturierten Format. Dieses Feld wird in der Regel verwendet, um Text, Bilder, Audio, Links oder Einbettungen zurückzugeben. In dieser Anwendung dient es dazu, formatierten Text mit den Informationen zurückzugeben, die von den Tools generiert wurden.
• structuredContent: Dies ist eine optionale Rückgabe, die verwendet wird, um die Ergebnisse der einzelnen Tools in einem strukturierten Format bereitzustellen. Dies ist für programmatische Zwecke nützlich. Zwar wird es in diesem MCP-Server nicht verwendet, es kann jedoch von Nutzen sein, wenn Sie andere Tools entwickeln oder die Ergebnisse programmatisch verarbeiten möchten.

Vor diesem Hintergrund betrachten wir nun jedes Tool im Detail.

Tool „Search_docs“

Dieses Tool führt eine Volltextsuche im Elasticsearch-Index durch, um die relevantesten Dokumente basierend auf der Nutzeranfrage abzurufen. Es hebt die wichtigsten Treffer hervor und bietet einen schnellen Überblick mit Relevanzbewertungen.

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,
      };
    }
  }
);

Wir konfigurieren fuzziness: “AUTO” so, dass eine variable Tippfehlertoleranz basierend auf der Länge des analysierten Tokens besteht. Wir legen außerdem title^2 fest, um die Bewertung der Dokumente zu erhöhen, bei denen die Übereinstimmung im Feld „Titel“ erfolgt.

Tool „summarize_and_cite“

Dieses Tool erstellt eine Zusammenfassung auf Basis von Dokumenten, die bei der vorherigen Suche ermittelt wurden. Es verwendet das gpt-4o-mini-Modell von OpenAI, um die relevantesten Informationen zur Beantwortung der Nutzerfragen zu synthetisieren und Antworten zu liefern, die direkt aus den Suchergebnissen abgeleitet werden. Neben der Zusammenfassung werden auch Metadaten für Zitate zu den verwendeten Quelldokumenten zurückgegeben.

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,
      };
    }
  }
);

Zu guter Letzt starten wir den Server mithilfe von stdio. Das bedeutet, dass der MCP-Client mit unserem Server kommuniziert, indem er seine standardmäßigen Eingangs- und Ausgangsstreams liest und schreibt. stdio ist die einfachste Transportoption und funktioniert gut für lokale MCP-Server, die vom Client als Unterprozesse gestartet werden. Fügen Sie den folgenden Code am Ende der Datei hinzu:

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

Kompilieren Sie das Projekt jetzt mit folgendem Befehl:

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

Dadurch wird ein Ordner dist erstellt und darin eine Datei index.js.

Laden Sie den MCP-Server in Claude Desktop

Folgen Sie dieser Anleitung, um den MCP-Server mit Claude Desktop zu konfigurieren. In der Konfigurationsdatei von Claude müssen die folgenden Werte festgelegt werden:

{
  "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"
      }
    }
  }
}

Der Wert args sollte auf die kompilierte Datei im Ordner dist verweisen. Außerdem müssen Sie die Umgebungsvariablen in der Konfigurationsdatei mit genau den gleichen Namen festlegen, die im Code definiert sind.

Probieren Sie es aus

Klicken Sie vor der Ausführung jedes Tools auf Search and Tools, um sicherzustellen, dass die Tools aktiviert sind. Hier können Sie außerdem alle Funktionen aktivieren oder deaktivieren:

Zum Schluss testen wir den MCP-Server über den Claude Desktop-Chat und beginnen, Fragen zu stellen:

Für die Frage „Suche nach Dokumenten zu Authentifizierungsmethoden und RBAC“ wird das search_docs-Tool ausgeführt und liefert folgende Ergebnisse:

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.

Die Reaktion lautet: „Großartig! Ich habe 5 relevante Dokumente über Authentifizierungsmethoden und RBAC gefunden. Folgendes wurde gefunden:“

Der Toolaufruf gibt die Quelldokumente als Teil seiner Reaktionnutzlast zurück, die später zur Erstellung von Zitaten verwendet werden.

Es ist auch möglich, mehrere Tools in einer einzigen Interaktion zu verketten. In diesem Fall analysiert Claude Desktop die Frage des Nutzers und stellt fest, dass zunächst search_docs aufgerufen werden muss, um relevante Dokumente abzurufen, und dass diese Ergebnisse anschließend an summarize_and_cite übergeben werden müssen, um die endgültige Antwort zu generieren, ohne dass dafür separate Prompts vom Nutzer erforderlich sind:

In diesem Fall haben wir für die Abfrage „Was sind die wichtigsten Empfehlungen zur Verbesserung der Authentifizierung und Zugriffssteuerung in unseren Systemen? Referenzen einbeziehen.“ folgende Ergebnisse erzielt:

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.

Wie im vorherigen Schritt können wir die Reaktion jedes Tools auf diese Frage einsehen:

Hinweis: Wenn ein Untermenü erscheint, in dem gefragt wird, ob Sie die Nutzung jedes Tools genehmigen möchten, wählen Sie Immer erlauben oder Einmal erlauben.

Fazit

MCP-Server stellen einen bedeutenden Schritt zur Standardisierung von LLM-Tools für lokale und entfernte Anwendungen dar. Die vollständige Kompatibilität ist zwar noch in Bearbeitung, wir verzeichnen jedoch große Fortschritte in diese Richtung.

In diesem Artikel haben wir gelernt, wie man einen benutzerdefinierten MCP-Server in TypeScript entwickelt, der Elasticsearch mit LLM-gestützten Anwendungen verbindet. Unser Server stellt zwei Tools bereit: search_docs zum Abrufen relevanter Dokumente mittels Abfrage-DSL und summarize_and_cite zur Erstellung von Zusammenfassungen mit Zitaten über OpenAI-Modelle und Claude Desktop als Client-Benutzeroberfläche.

Die Zukunft der Kompatibilität zwischen verschiedenen Client- und Server-Anbietern sieht vielversprechend aus. Zu den nächsten Schritten gehört die Erweiterung des Funktionsumfangs und die Erhöhung der Flexibilität Ihres Agenten. Es gibt einen praktischen Artikel dazu, wie Sie Ihre Abfragen mithilfe von Suchvorlagen für mehr Präzision und Flexibilität parametrisieren können.

Genau aus diesem Grund haben wir schreibgeschützte Dashboards entwickelt. Das ist die Kontrolle, die Sie sich gewünscht haben. Geben Sie Dashboards vertrauensvoll weiter, ohne befürchten zu müssen, dass die nächste Person mit Bearbeitungsrechten sie verändert oder zerstört.

Hinweis: Schreibgeschützte Berechtigungen sind in Elastic Cloud Serverless und ab Version 9.3 für Elastic Cloud Hosted und Elastic Self-Managed verfügbar.

Wenn die Option „Jeder kann bearbeiten“ Probleme bereitet

In Kibana hat das Teilen in der Regel Berechtigungen auf Space-Ebene bedeutet. Wenn jemand Dashboards in einem Bereich erstellen kann, kann er auch die Dashboards anderer Personen bearbeiten oder löschen. Das ist großartig für die Zusammenarbeit – bis es das nicht mehr ist. Eine einzige versehentliche Änderung kann zu Fehlentscheidungen, Vertrauensverlust und viel Aufräumarbeit führen.

Wir haben die Workarounds gehört: „Wir haben ‚read-only‘ in den Dashboard-Namen gesetzt und hoffen, dass die Leute es bemerken.“ Oder: „Wir markieren sie und drücken die Daumen.“ Hoffnung ist kein Genehmigungsmodell. Sie brauchten eine echte Möglichkeit, ein Dashboard zu sperren, ohne alle aus dem Bereich auszusperren.

Was tatsächlich schiefgeht

Deb und Kevin haben beide Bearbeitungszugriff auf das Log-Monitoring-Dashboard im Operationsbereich. Kevin nimmt einige Änderungen an den Charts vor. Als Deb zurückkommt, stimmen die Zahlen nicht mit den von ihr präsentierten überein. Sie muss herausfinden, was sich geändert hat (oft aus dem Gedächtnis), es beheben und sich fragen, wie viele Berichte mit falschen Daten verschickt wurden.

Schreibgeschützte Dashboards: Verantwortung und Kontrolle, die sinnvoll sind

Schreibgeschützte Dashboards lösen dieses Problem, indem sie Ihnen die Kontrolle darüber geben, ob andere Nutzer das Dashboard bearbeiten können. Wenn Sie ein Dashboard teilen, wählen Sie: Bearbeiten (Standard, wie heute) oder Ansehen. Im Ansichtsmodus können nur Sie (und die Kibana-Administratoren) es ändern oder löschen. Alle anderen können es öffnen, verwenden und darauf vertrauen, aber sie können es nicht verändern.

Was Sie erhalten

• Dashboard-Integrität: Im Ansichtsmodus können andere Nutzer mit Bearbeitungszugriff das Dashboard nicht ändern oder löschen. Wenn sie es versuchen, wird ihnen mitgeteilt, dass es gesperrt ist. Ihre Diagramme und Logik bleiben so, wie Sie sie verlassen haben.
• Sie behalten die Kontrolle: Sie sind der Besitzer. Sie können jederzeit bearbeiten, verfeinern und aktualisieren. Das Teilen als Nur-Ansicht sperrt Sie nicht aus; es fixiert die Version, die alle anderen sehen.
• Flexibler Lebenszyklus: Sie können ein Dashboard jederzeit wieder auf „bearbeitbar“ umschalten. Und Kibana-Administratoren können weiterhin alle Dashboards verwalten (zum Beispiel, wenn der Eigentümer ausscheidet). Keine Sackgassen.

Sie können finalisierte, missionskritische Dashboards weitreichend teilen und sicher sein, dass sie konsistent bleiben. Dies ist in allen Elastic-Stufen und -Angeboten verfügbar, einschließlich Serverless.

Wer kann was tun?

Schnelle Referenz nach Rolle:

• Dashboard-Besitzer: Sie haben es erstellt; Sie haben vollen Bearbeitungszugriff.
• Kibana-Administrator: Kann alle Dashboards verwalten.
• Nutzer mit Bearbeitungsrechten: Kann eigene Dashboards erstellen und bearbeiten; kann schreibgeschützte Dashboards weder bearbeiten noch löschen.
• Nutzer mit Ansichtsrechten: Kann nur Dashboards anzeigen (und auflisten).

So aktivieren Sie den Schreibschutz

Sie können den schreibgeschützten Modus beim Speichern eines neuen Dashboards oder später über das Freigabemenü festlegen.

Beim Speichern eines neuen Dashboards

• Erstellen Sie Ihr Dashboard, und klicken Sie auf Speichern.
• Suchen Sie im Modal „Als neues Dashboard speichern“ nach Berechtigungen.
• Ändern Sie diese von Kann bearbeiten in Kann ansehen.
• Klicken Sie auf Speichern. Das war's. Für alle anderen ist es schreibgeschützt.

Für ein Dashboard, das Sie bereits besitzen

• Dashboard öffnen.
• Öffnen Sie das Menü Dashboard teilen.

• Im Freigabemodal suchen Sie Berechtigungen und wechseln Sie zu Kann anzeigen. Die Änderung tritt sofort in Kraft; andere Nutzer im selben Bereich können sie nicht mehr bearbeiten oder löschen.

• Sie können mit der Maus über die Aktion Teilen fahren, um zu sehen, welche Art von Berechtigungen ein bestimmtes Dashboard hat.

Sehen, welche Dashboards gesperrt sind

In der Hauptliste der Dashboards haben Dashboards, die Sie nicht bearbeiten oder löschen können, ein deaktiviertes Auswahlkästchen. Dadurch lässt sich leicht erkennen, welche Inhalte nur zur Ansicht freigegeben sind.

Im Dashboard werden Sie außerdem feststellen, dass die Aktion „Bearbeiten“ deaktiviert ist und ein Tooltip erscheint, der erklärt, dass das Dashboard als schreibgeschützt eingestellt wurde.

Ausprobieren

Schreibgeschützte Dashboards sind jetzt verfügbar. Erstellen Sie ein Dashboard, setzen Sie es auf Ansehen und teilen Sie es. Ihr Team erhält eine einzige verlässliche Informationsquelle, und Sie erhalten Sicherheit. Kein „Bitte nicht bearbeiten“ mehr im Titel.

Wir würden gerne hören, wie Sie schreibgeschützte Dashboards verwenden. Teilen Sie Ihr Feedback in unserem Community-Forum mit.

Dieser Beitrag konzentriert sich erneut auf die Frage:Welche Suchoberflächen braucht ein Agent, um seinen eigenen Kontext zu erstellen? Zunächst werden die Vor- und Nachteile von Shell-Tools und dedizierten Datenbanktools erläutert. Von dort aus ergibt sich ein praktisches Framework, um die richtigen Schnittstellen für die Bedürfnisse Ihres Agenten zu finden.

Was bedeutet „Kontextaufbau“ eigentlich für einen Agenten?

In frühen Retrieval-Augmented Generation (RAG)-Pipelines erzeugte der Entwickler eine feste Retrieval-Pipeline, und das große Sprachmodell (LLM) war passiver Empfänger des Kontexts. Das war eine grundlegende Einschränkung: Der Kontext wurde bei jeder Abfrage abgerufen, egal ob er benötigt wurde oder nicht, ohne zu prüfen, ob er tatsächlich half.

Mit der Umstellung auf agentenbasiertes RAG haben die Agenten nun Zugriff auf eine Reihe von Suchwerkzeugen, um ihren eigenen Kontext zu erstellen. Beispielsweise ermöglichen sowohl Claude Code [1] als auch Cursor [2] dem Agenten, zwischen verschiedenen Suchwerkzeugen zu wählen und diese sogar für verkettete Abfragen zu kombinieren, je nachdem, was die Aufgabe tatsächlich erfordert.

Welche Suchoberflächen gibt es für das Kontext-Engineering?

Kontext kann sich an verschiedenen Orten befinden, etwa im Web, in einem lokalen Dateisystem oder in einer Datenbank. Ein Agent kann mit jeder dieser kontextlosen Datenquellen über verschiedene Werkzeuge interagieren:

• Shell-Tools können Shell-Befehle ausführen und haben Zugriff auf das lokale Dateisystem. Beispiele für integrierte Shell-Tools sind das Bash-Tool von Claude API, das Exec-Tool von OpenClaw und das Shell-Tool von LangChain.
• Spezielle Datenbanktools wie zum Beispiel Tools eines Model Context Protocol (MCP)-Servers (z. B. der Elastic Agent Builder MCP-Server) oder benutzerdefinierte Tools (z. B. run_esql(query) oder db_list_index()) können Datenbanken abfragen.
• Dedizierte Dateisuchwerkzeuge können lokale (oder hochgeladene) Dateien suchen und lesen (ohne vollständigen Zugriff auf die Shell). Beispiele für integrierte Dateisuchwerkzeuge sind das Dateisuchwerkzeug der Gemini API oder das Dateisuchwerkzeug von OpenAI.
• Web-Suchwerkzeuge können Informationen aus dem Web abrufen.
• Gedächtniswerkzeuge speichern und rufen aus dem Langzeitgedächtnis ab (unabhängig davon, wie es gespeichert ist).

Wie Sie sehen, ist das Shell-Tool vielseitig und kann verwendet werden, um Kontext aus verschiedenen Datenquellen abzurufen, darunter:

• Dateisystem: Der Agent erkundet die Verzeichnisstruktur (ls, find), sucht nach relevanten Inhalten (grep, cat) und wiederholt dies, bis er genügend Kontext aufgebaut hat.
• Datenbank: Der Agent kann Befehlszeilen-Schnittstellen (CLI)-Tools für Datenbanken verwenden (z. B. elasticsearch-sql-cli), HTTP-APIs über curl aufrufen oder Skripte ausführen, was insbesondere in Kombination mit Elastic Agent Skills nützlich ist. Dabei handelt es sich um wiederverwendbare, dokumentierte Beispiele, die in den Kontext des Agenten eingefügt werden, um die korrekte Tool-Nutzung anzuleiten (z. B. Elastic Agent Skills für Elasticsearch).
• Web: Der Agent kann Websuchen per curl-Befehl über die API eines Suchanbieters ausführen.

Das Shell-Tool bietet jedoch direkten Systemzugriff und erfordert daher Sicherheitsmaßnahmen, zum Beispiel die Ausführung in einer isolierten Sandbox-Umgebung und das Protokollieren aller ausgeführten Befehle.

Wann sollten welche Suchoberflächen verwendet werden?

Die richtige Suchschnittstelle hängt von Ihren Daten, Ihren Abfragemustern und Ihrem Anwendungsfall ab. Dieser Abschnitt dient als praktischer Ausgangspunkt.

Dateisysteme machen Datenbanken nicht überflüssig

Bei der Diskussion um Dateisysteme versus Datenbanken geht es nicht um die Speicherschicht. LangChain erklärt zum Beispiel, dass sein Speichersystem Daten nicht wirklich in einem echten Dateisystem speichert. Stattdessen speichert es sie in einer Datenbank und stellt sie dem Agenten als eine Reihe von Dateien dar [3].

Dateisysteme eignen sich hervorragend für dateiabhängige Anwendungsfälle, wie z. B. Codierungsagenten. Sie eignen sich auch gut als temporärer Notizblock oder Arbeitsspeicher und für Einzelnutzer- oder Einzelagenten-Szenarien, bei denen die Gleichzeitigkeit keine Rolle spielt. In diesen Fällen bietet Ihnen ein physisches Dateisystem oder die Darstellung der Daten als Dateisystem Flexibilität, bevor Sie sich auf eine speziell entwickelte Schnittstelle festlegen.

Aber Dateisystemspeicher haben echte Nachteile, wie etwa schwache Parallelität, manuelle Schema-Durchsetzung und atomare Transaktionen. Diese treten noch deutlicher zutage, wenn Ihre Anwendung skaliert werden muss oder auf ein Multi-Agenten-Szenario umgestellt werden soll. Wer diese Nachteile ignoriert, sieht sich zu einer mühsamen Neuerstellung schlechterer Datenbanken gezwungen, ohne die jahrzehntelange technische Erfahrung hinter Transaktionssicherheit oder Zugriffskontrolle nutzen zu können, die Produktionsdatenbanken bereits bieten. Außerdem wählt man in den meisten Unternehmenskontexten nicht, ob eine Datenbank verwenden werden soll, da sie bereits vorhanden ist und geschäftskritische Daten speichert.

Shell-Tool + Dateisystem

Ein Shell-Tool ist der natürliche Ausgangspunkt für die Dateisystemsuche. Derzeit treiben Codierungsagenten den Fortschritt auf diesem Feld maßgeblich voran. Da sie mit Code in lokalen Dateien arbeiten, sind es von Natur aus dateiintensive Anwendungsfälle. Deshalb werden LLMs in der Post-Training-Phase für Codierungsaufgaben feinjustiert. Viele LLMs beherrschen daher nicht nur das Schreiben von Code, sondern auch die Verwendung von Shell-Befehlen und die Navigation in Dateisystemen.

Die Verwendung eines Shell-Tools mit integrierten CLIs wie ls und grep zum Suchen von Dateien ist effektiv. Mit grep ist eine Abfrage wie „Finde alle Dateien, die matplotlibimportieren“ schnell, präzise und kostengünstig. Wenn der Agent jedoch konzeptionelle Anfragen bearbeiten muss, wie zum Beispiel „Wie geht unsere App mit fehlgeschlagener Authentifizierung um?“, kann die Mustererkennung mit grep schnell an ihre Grenzen stoßen. Um diese Lücke zu schließen, sind mehrere Alternativen entstanden, die semantische Suchfunktionen in die Befehlszeile einfügen, darunter jina-grep.

Grep und viele seiner semantischen Suchalternativen laufen jedoch in O(n) über dem Korpus. Für Anwendungsfälle in Codebasen mag das in Ordnung sein. Wenn Ihre Datenmenge jedoch zunimmt, wird sich Latenz bemerkbar machen. In diesem Fall ist ein indizierter Datenspeicher erforderlich, um die Leistung aufrechtzuerhalten.

Shell-Tool + Datenbank

Eine weitere Möglichkeit, zusätzliche Suchfunktionen wie semantische oder hybride Suche für Ihre Daten zu erstellen, besteht darin, diese in einer Datenbank zu speichern, wie es beispielsweise Cursor tut. Und wenn Daten komplexe relationale Verknüpfungen oder Aggregationen erfordern, benötigen Sie eine Datenbankschnittstelle.

Falls die Daten nicht im Dateisystem, sondern in einer Datenbank gespeichert sind, kann ein Shell-Tool für bestimmte Anwendungsfälle als leichtgewichtige Datenbankschnittstelle dienen. Sind Ihre Abfragen einfach genug für eine CLI oder einen curl-Aufruf, führt ein spezielles Datenbanktool eventuell zu unnötiger Komplexität.

Dieser Ansatz eignet sich auch für frühe Explorationsphasen, in denen Sie noch nicht wissen, welche Abfragemuster Ihr Agent tatsächlich entwickeln wird. In diesem Fall können Agent Skills dem Agenten genügend Struktur geben, um korrekte Abfragen durchzuführen, ohne dass ein speziell dafür entwickeltes Tool erforderlich ist. Wenn der Agent jedoch viele Iterationen benötigt, um die richtige Methode zum Abfragen der Datenbank für wiederkehrende Aufgaben herauszufinden, rechtfertigt der Token-Overhead der Verwendung eines Shell-Tools als Schnittstelle den Einfachheitsvorteil, ein zusätzliches Tool zu vermeiden, nicht mehr.

Dedizierte Datenbank-Tools

Insbesondere bei strukturierten oder analytischen wiederkehrenden Abfragemustern sind spezielle Datenbankwerkzeuge notwendig. In einem Blogbeitrag von Vercel und Braintrust wurden Agenten mit verschiedenen Suchwerkzeugen für reale Rechercheaufgaben in semistrukturierten Daten verglichen, wie z. B. Kundensupport-Tickets und Transkripte von Verkaufsgesprächen (z. B. „Wie viele offene Tickets erwähnen ‚Sicherheit‘?“ oder „Finden Sie Tickets, bei denen jemand einen Fehler gemeldet hat und später jemand einen PR eingereicht hat, der behauptet, ihn zu beheben?“). [4].

Agenten mit dedizierten Datenbank-Tools verbrauchten weniger Token, waren schneller und machten weniger Fehler als Agenten, die nur ein Shell-Tool und ein Dateisystem verwendeten. Wir ziehen daraus den Schluss, dass direkte Datenbank-Tools die richtige Wahl sind, wenn die Abfrage analytische Schlussfolgerungen über teilweise strukturierte Daten erfordert.

Kombination von Suchschnittstellen

Keine einzelne Suchschnittstelle kann jede Suchanfrage optimal verarbeiten. Cursor kombiniert beispielsweise Shell-Tools (für Suchen mit grep) und semantische Suchwerkzeuge und ermöglicht es dem Agenten, mit dem Prompt des Nutzers das richtige Werkzeug auszuwählen. Sie berichten, dass der Agent für das Auffinden bestimmter Symbole oder Zeichenfolgen grep, für konzeptuelle oder Verhaltensfragen die semantische Suche und beides für explorative Aufgaben auswählt.

Das Vercel-Experiment kommt zum selben Ergebnis: Sein Hybrid-Agent mit Zugriff sowohl auf ein Shell-Tool als auch auf ein dediziertes Datenbank-Tool erzielte die beste Leistung aller getesteten Agenten, indem er zuerst die dedizierten Datenbank-Tools nutzte und anschließend die Ergebnisse durch das Durchsuchen des Dateisystems mit grep überprüfte. Jedoch verwendet dieser Ansatz mehr Token und Zeit für Überlegungen zur Werkzeugwahl und Verifizierung.

Das Muster ist in beiden Beispielen dasselbe: Komposition ist jeder einzelnen Schnittstelle überlegen, aber Komposition hat auch den Nachteil zusätzlicher Kosten und Latenz.

Praktische Empfehlungen zur Auswahl des richtigen Werkzeugsatzes

Die richtigen Suchschnittstellen sind klein, zielgerichtet und speziell auf die tatsächlichen Suchmuster Ihres Agenten zugeschnitten. Derzeit gilt es als Best Practice, statt eines Agenten mit Hunderten von MCP-Tools einen Agenten mit so wenigen Tools wie möglich zu haben. Das liegt daran, dass die sofortige Offenlegung aller möglichen Tools ein Nachteil ist, weil sie das Kontextfenster aufbläht und den Agenten darüber verwirrt, welches Tool er tatsächlich verwenden soll. Claude Code verfügt beispielsweise Berichten zufolge nur über etwa 20 Tools.

Die Idee der progressiven Offenlegung besteht hingegen darin, mit einem minimalen Satz an Tools zu beginnen und es dem Agenten zu ermöglichen, zusätzliche Fähigkeiten nur bei Bedarf abzufragen. Forschungen von Anthropic [5] und Cursor [6] haben gezeigt, dass dieser Ansatz eine Token-Ersparnis von 47%–85% bringt. Claude Code implementiert dies zum Beispiel direkt und ermöglicht es dem Agenten, schrittweise herauszufinden, wie eine API oder eine Datenbank abgefragt werden kann, ohne dass dieses Wissen bei jedem LLM-Aufruf Kontext verbraucht.

Sobald Sie mit den Abfragemustern des Agenten vertraut sind, können Sie die Suchwerkzeuge, auf die der Agent standardmäßig Zugriff hat, erneut aufrufen. Eine hilfreiche Herangehensweise an diesen Zielkonflikt ist das Prinzip „Low Floor, High Ceiling“ zur Auswahl der passenden Werkzeuge. High-Ceiling-Tools schränken das Potenzial des Agenten nicht ein. Ein vielseitiges Shell-Tool ermöglicht es dem Agenten beispielsweise, vollständige, auch mehrdeutige Datenbankabfragen zu schreiben, aber auf Kosten des Argumentationsaufwands, höherer Latenz und geringerer Zuverlässigkeit.

Bei Low-Floor-Tools ist es genau umgekehrt. Dabei handelt es sich um spezialisierte Tools, die bestimmte Abfragen kapseln und dem Agenten mit minimalem zusätzlichem Überlegungsaufwand sofort zur Verfügung stellen – bei geringeren Kosten und höherer Zuverlässigkeit. Sie erfordern jedoch eine Vorentwicklung, können nicht jede mögliche Anfrage abdecken und erschweren es dem Agenten, das richtige Werkzeug auszuwählen.

Betrachten Sie jedes Tool als Teil eines Spektrums: Low-Floor-Tools sind für den Agenten leicht korrekt zu verwenden, haben aber einen begrenzten Anwendungsbereich. High-Ceiling-Tools sind vielseitig, erfordern aber mehr Überlegung, um sie richtig einzusetzen.

Die meisten Agenten benötigen eine Mischung aus verschiedenen Suchwerkzeugen. Jedes Werkzeug muss sich jedoch als nützlich erweisen. Wir empfehlen, mit einem universellen Such-Tool zu beginnen (zum Beispiel einem search_database() -Tool oder einem Shell-Tool). Nutzen Sie dann die Befehlsprotokolle, die Sie aus Sicherheitsgründen bereits führen, erneut, um nachzuverfolgen, was Ihr Agent tatsächlich tut, einschließlich der Toolaufrufe, Wiederholungen und der Anzahl der Aufrufe pro Nutzerabfrage. Und wenn Sie feststellen, dass sich ein Abfragemuster wiederholt oder fehlschlägt, dann sollten Sie für diese Aufgabe ein spezielles Werkzeug erstellen.

Zusammenfassung

Die Debatte „Dateisystem versus Datenbank“ lenkt von der eigentlichen Frage ab, die sich Entwickler stellen müssen: Welche Suchoberflächen braucht ein Agent, um seinen eigenen Kontext zu erstellen? Die Antwort ist sehr wahrscheinlich: keine einzige.

Ein Shell-Tool ist ein vielseitiges Tool für die Interaktion mit unterschiedlichen kontextfremden Quellen und damit ein guter Ausgangspunkt. Für Anwendungsfälle mit strukturierten analytischen Abfragen ist es jedoch weniger effizient und präzise als dedizierte Datenbank-Tools.

Ziel ist es, die minimale Menge an Suchwerkzeugen zu finden, die die tatsächlichen Abfragemuster Ihres Agenten gut verarbeitet. Beginnen Sie mit einem Shell-Tool und protokollieren Sie, was Ihr Agent tatsächlich tut. Wenn Sie feststellen, dass sich ein Abfragemuster wiederholt und fehlschlägt, ist es Zeit, spezialisierte Werkzeuge zu entwickeln.

Referenzen

1. Thariq (Anthropic). Lessons from Building Claude Code: Seeing like an Agent (2026).

2. Cursor: Dokumentation. Semantic & agentic search (2026).

3. Harrison Chase (LangChain). How we built Agent Builder’s memory system (2026).

4. Ankur Goyal (Braintrust) und Andrew Qu (Vercel). Testing if "bash is all you need" (2026).

5. Anthropic. Introducing advanced tool use on the Claude Developer Platform (2025).

6. Cursor. Dynamische Kontexterkennung (2026).

Es ist zu voll auf der Party

Sie veranstalten eine Pizza-Party. Sie haben ein paar Freunde, die Ihnen beim Servieren helfen, jeder an verschiedenen Stellen im Raum stationiert. Sie geben jedem Freund eine Pizza und verteilen die Stücke an die hungrigen Gäste, sobald diese eintreffen.

Zunächst läuft alles reibungslos. Nach und nach treffen ein paar Gäste ein, Ihre Freunde servieren Snacks, alle sind zufrieden. Aber dann spricht sich herum, wie gut Ihre Sauerteigpizzen sind. Es klingelt ständig an der Tür. Die Gäste strömen herein. Bald formiert sich eine Menschenmenge um einen Ihrer Freunde, der eine Salamipizza in der Hand hält, die anscheinend jeder will.

Ihr Freund mit der Salamipizza ist überfordert. Die Gäste warten, werden ungeduldig und es hat sich eine lange Warteschlange gebildet. Währenddessen steht Ihr Freund mit einer Margherita-Pizza herum, und kaum jemand fragt nach einem Stück.

Und was nun?

Sie bestellen ein paar mehr Salamipizzen und geben sie an andere Freunde weiter. Jetzt haben drei Freunde Salamipizzen parat, nicht nur einer. Die Menge verteilt sich und plötzlich können dreimal so viele Gäste gleichzeitig bedient werden.

Ein paar Dinge werden deutlich, wenn Sie mehr Partys veranstalten:

• Nicht alle Pizzen sind gleich beliebt. Einige sind sehr gefragt, andere finden weniger Abnehmer. Sie benötigen keine zusätzlichen „Kopien“ unbeliebter Pizzen. Sie benötigen noch weitere der stark gefragten.
• Bestellen Sie mehr Pizzen, bevor die Warteschlange zu lang wird. Wenn Sie warten, bis Ihr Freund völlig überfordert ist und die Gäste verärgert abreisen, haben Sie zu lange gewartet. Es ist besser, eine zusätzliche Pizza zu holen, wenn Sie sehen, wie sich eine Menschenmenge bildet.
• Werfen Sie die Pizzen nicht zu schnell weg. Nur weil der Andrang am Salamistand für fünf Minuten zurückgegangen ist, heißt das nicht, dass der Ansturm vorbei ist. Vielleicht füllen die Leute nur ihre Getränke nach oder unterhalten sich miteinander (gibt es sowas heutzutage überhaupt noch?). Halten Sie die zusätzlichen Pizzen bereit. Wenn die Flaute eine Weile anhält, können Sie sie wegräumen.
• Sie können nur so viele Pizzen verteilen, wie Sie Freunde haben, die mithelfen. Wenn Ihnen nur vier Freunde helfen, ändern zehn Pizzen nichts am Ergebnis. Es können nur vier Menschen gleichzeitig bedient werden. Passen Sie die Anzahl der Pizzen an Ihre verfügbaren Helfer an.
• Wenn ein Freund geht, räumen Sie seine Pizza weg. Wenn einer Ihrer Freunde gehen muss, räumen Sie sofort seine Pizza weg. Sie können keine Pizzen unbeaufsichtigt stehen lassen. Geben Sie sie jemand anderem oder räumen Sie sie weg.

Von Pizzen bis zu Repliken

Ordnen wir dies wieder Elasticsearch zu.

In unserer Analogie sind Pizzen die Replikate (Kopien Ihrer Index-Shards), Ihre Freunde, die sie servieren, sind die Suchknoten, die hungrigen Gäste sind die Suchabfragen, und die beliebte Pizza, um die sich alle reißen, ist ein heißer Index mit hoher Suchlast.

Wenn der Suchverkehr auf einem bestimmten Index zunimmt, erstellen wir zusätzliche Replikate und verteilen diese auf Ihre Suchknoten. Jedes Replikat kann jede Abfrage für diesen Index beantworten, genau wie jeder Freund, der eine Salamipizza in der Hand hält, Pizzastücke verteilen kann. Mehr Replikate bedeuten einen höheren Durchsatz: Drei Replikate können dreimal so viele Abfragen pro Sekunde wie ein einzelnes Replikat verarbeiten.

Den Hunger messen

Bevor wir entscheiden, wie viele Pizzen wir bestellen, müssen wir wissen, wie hungrig das Publikum ist.

Elasticsearch verfolgt die Suchlast für jeden Shard. Es ist eine Metrik, die erfasst, wie viel Suchaktivität ein Shard verarbeitet. Wir aggregieren dies über alle Shards eines Indexes, um die gesamte Suchnachfrage zu verstehen.

Am wichtigsten ist die relative Suchlast: Welcher Anteil des gesamten Suchverkehrs Ihres Projekts trifft jeden Index? Wenn ein Index 60 % aller Suchanfragen erhält, während ein anderer 5 % bekommt, wissen wir, wo wir Kapazität hinzufügen müssen.

Die Berechnung hinter den Pizzen

Wir berechnen die optimale Anzahl der Replikate nach folgender Formel:

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

Wo:

• L = die relative Suchlast des Index (zwischen 0 und 1).
• N = die Anzahl der gewünschten Suchknoten in Ihrem Projekt.
• S = die Anzahl der Shards im Index.
• X = eine Schwelle, um Hotspots zu vermeiden (Standard: 0,5).

Ein Beispiel: vier Suchknoten, ein Index mit zwei primären Shards, die 80 % des Suchverkehrs erhalten:

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

Dieser Hot-Index erhält vier Replikate, die auf die Suchknoten verteilt werden.

Der Schwellenwert X (standardmäßig 0,5) ist wichtig. Wir warten nicht, bis ein Replikat völlig überlastet ist, sondern skalieren, wenn es die halbe Kapazität erreicht hat. Teilen Sie die zusätzliche Pizza aus, wenn Sie sehen, dass sich eine Menschenmenge bildet, nicht wenn die Gäste bereits gehen.

Schnell hochskalieren, langsam herunterskalieren

Wenn die Suchlast steigt, fügen wir sofort Repliken hinzu. Es gibt keinen Grund, die Nutzer warten zu lassen.

Wenn die Suchlast abfällt, warten wir eine Weile, bevor wir etwas unternehmen. Wir müssen eine konstant niedrige Nachfrage über einen Zeitraum von etwa 30 Minuten beobachten, bevor wir die Anzahl der Replikate reduzieren. (Dies dient dazu, mit Spitzenverkehr umzugehen, wobei ein ruhiger Moment nicht bedeutet, dass die Party vorbei ist.)

Das ist wichtig, weil das Hinzufügen eines Replikats Kosten verursacht. Das neue Replikat kopiert Daten und wärmt seine Caches auf, bevor es Abfragen effizient verarbeitet. Replikate zu voreilig zu entfernen bedeutet, dass Sie diese Anlaufkosten ständig erneut zahlen, weil der Traffic naturgemäß schwankt.

Berücksichtigung der Topologiegrenzen

Replikate können niemals die Anzahl der Suchknoten überschreiten. Mehr Replikate als Knoten zu haben, bringt keinen Vorteil (Sie können nur so viele Pizzen servieren, wie Sie Freunde haben, die beim Servieren der Pizzastücke helfen).

Wenn Knoten aus Ihrem Projekt entfernt werden, reduzieren wir die Anzahl der Replikate sofort entsprechend. Es wird nicht erst aufs Abkühlen gewartet, da es keine nicht zugewiesenen Replikate geben kann. Sobald ein Freund geht, räumen wir seine Pizza weg.

Das größere Serverless-Bild

Replikate für den Suchlastausgleich arbeiten mit anderen Systemen zur automatischen Skalierung zusammen:

• Automatische Suchskalierung passt die Anzahl der Suchknoten an (Anzahl der helfenden Freunde).
• Replikate für die Suchlastverteilung verteilen den Traffic durch Anpassung der Replikatzahlen pro Index (wie viele Pizzen jeder Sorte benötigt werden).
• Datenstrom-Autosharding optimiert die Shard-Anzahl für Schreibvorgänge (wie man jede Pizza aufteilt, beschrieben im vorherigen Beitrag).

Ein wichtiges Gestaltungsprinzip: Replikate für den Lastausgleich lösen nicht direkt die automatische Skalierung der Suche aus. Durch die Verteilung von Suchanfragen auf mehrere Replikate können Sie stattdessen die Ressourcenauslastung Ihrer Suchknoten erhöhen. Diese höhere Auslastung löst dann unsere vorhandene automatische Skalierungslogik aus, um bei Bedarf für zusätzliche Kapazitäten zu sorgen. Replikate für den Lastausgleich ermöglichen die automatische Skalierung und stellen sicher, dass Ihre Suchknoten tatsächlich genutzt werden, anstatt dass der gesamte Datenverkehr auf einem einzigen Replikat blockiert wird, während andere Knoten untätig bleiben.

Was das für Sie bedeutet

Sie müssen nicht vorhersagen, welche Indizes beliebt sein werden. Sie müssen die Replikate nicht manuell anpassen, wenn sich die Verkehrsmuster ändern. Sie müssen nicht um 3 Uhr morgens aufwachen, weil ein Ansturm Ihren am stärksten belasteten Index überfordert hat.

Das System überwacht, wo sich Warteschlangen bilden, und bestellt für diese Stellen mehr Pizzen. Kalte Indizes verschwenden keine Ressourcen für unnötige Replikate. Heiße Indizes erhalten die benötigte Kapazität. Ihr Budget fließt dort hin, wo es wichtig ist.

Fazit

Im Autosharding-Beitrag haben wir dafür gesorgt, dass Ihre Pizzen richtig aufgeteilt werden. Jetzt sorgen wir mit Replikaten für die Suchlastverteilung dafür, dass Sie genug Pizzen bereit haben, wenn die hungrigen Massen eintreffen.

Probieren Sie Elastic Cloud Serverless aus und lassen Sie uns die Pizza-Logistik übernehmen.

Voraussetzungen

• Elasticsearch 9.3 oder Elastic Cloud Serverless: Sie können ein Cloud-Deployment erstellen, indem Sie diese Anweisungen befolgen, oder stattdessen den start-local Quickstart verwenden.
• Python 3.12: Laden Sie Python hier herunter.
• Hugging Face Zugriffstoken.

Chat-Abschlüsse unter Verwendung eines Inferenz-Endpoints von Hugging Face

Zuerst erstellen wir ein praktisches Beispiel, das Elasticsearch mit einem Hugging Face Inferenz-Endpoint verbindet, um KI-gestützte Empfehlungen aus einer Reihe von Blogbeiträgen zu generieren. Für die Wissensdatenbank der App verwenden wir einen Datensatz mit Blogartikeln des Unternehmens, der wertvolle, aber oft schwer zugängliche Informationen enthält.

Bei diesem Endpoint ruft die semantische Suche die relevantesten Artikel für eine gegebene Abfrage ab, und ein Hugging Face LLM generiert kurze, kontextuelle Empfehlungen basierend auf diesen Ergebnissen.

Verschaffen wir uns einen groben Überblick über den Informationsfluss, den wir entwickeln werden:

In diesem Artikel testen wir die Fähigkeit von SmolLM3-3B und kombinieren seine kompakte Größe mit einer starken mehrsprachigen Argumentations- und Tool-Aufruffunktion. Basierend auf einer Suchabfrage senden wir alle passenden Inhalte (auf Englisch und Spanisch) an das LLM, um eine Liste empfohlener Artikel mit einer individuell erstellten Beschreibung basierend auf der Suchanfrage und den Ergebnissen zu erstellen.

So könnte die Benutzeroberfläche einer Artikelseite mit einem System zur Generierung von KI-Empfehlungen aussehen.

Sie können die vollständige Implementierung dieser Anwendung im verlinkten Notizbuch finden.

Konfiguration der Elasticsearch Inferenz-Endpoints

Um den Elasticsearch Hugging Face Inferenz-Endpoint zu verwenden, benötigen wir zwei wichtige Elemente: einen Hugging Face API-Schlüssel und eine ausgeführte Hugging Face Endpoint-URL. Dies sollte so aussehen:

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

Der Hugging Face Inferenz-Endpoint in Elasticsearch unterstützt verschiedene Aufgabentypen: text_embedding, completion, chat_completion und rerank. In diesem Blogbeitrag verwenden wir chat_completion, weil das Modell Gesprächsempfehlungen basierend auf den Suchergebnissen und einem Systemprompt generieren kann. Dieser Endpoint ermöglicht es uns, Chatabschlüsse direkt von Elasticsearch aus auf einfache Weise mit der Elasticsearch-API durchzuführen:

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

Dies dient als Kern der Anwendung, der den Prompt und die Suchergebnisse empfängt, die durch das Modell laufen werden. Nachdem die Theorie geklärt ist, können wir mit der Implementierung der Anwendung beginnen.

Einrichten des ​​Inferenz-Endpoints auf Hugging Face

Um das Hugging Face Modell bereitzustellen, werden wir Hugging Face One-Click-Deployments verwenden, einen einfachen und schnellen Service für die Bereitstellung von Modell-Endpoints. Beachten Sie bitte, dass es sich um einen kostenpflichtigen Service handelt, durch dessen Nutzung zusätzliche Kosten entstehen können. In diesem Schritt wird die Modellinstanz erstellt, die zur Generierung der Empfehlungen für die Artikel verwendet wird.

Sie können ein Modell aus dem Ein-Klick-Katalog aussuchen:

Wählen Sie das SmolLM3-3B Modell:

Hier können Sie die URL des Hugging Face Endpoints abrufen:

Wie in der Dokumentation zu den Hugging Face Inferenz-Endpunkten von Elasticsearch erwähnt, erfordert die Textgenerierung ein Modell, das mit der OpenAI-API kompatibel ist. Aus diesem Grund müssen wir den /v1/chat/completions-Subpfad an die Hugging Face Endpoint-URL anhängen. Das Ergebnis sieht wie folgt aus:

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

Mit dieser Voraussetzung können wir mit dem Codieren in einem Python-Notebook beginnen.

API-Schlüssel für Hugging Face generieren

Erstellen Sie ein Hugging Face Konto und erhalten Sie ein API-Token, indem Sie diesen Anweisungen folgen. Man kann zwischen drei Token-Typen wählen: detailliert (empfohlen für die Produktion, da es nur Zugriff auf bestimmte Ressourcen bietet); Lesezugriff (schreibgeschützt); oder Schreibzugriff (für Lese- und Schreibzugriff). Für dieses Tutorial ist ein Lesezugriffstoken ausreichend, da wir nur den Inferenz-Endpoint aufrufen müssen. Speichern Sie diesen Code für den nächsten Schritt.

Einrichten des Elasticsearch Inferenz-Endpoints

Zunächst legen wir einen Elasticsearch-Python-Client fest:

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"]
)

Danach erstellen wir einen Elasticsearch Inferenz-Endpoint, der das Hugging Face Modell verwendet. Dieser Endpoint ermöglicht es uns, Reaktionen zu generieren, die auf den Blogbeiträgen und dem an das Modell übergebenen Prompt basieren.

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"],
            },
        },
    )

Datensatz

Der Datensatz enthält die Blogbeiträge, die abgefragt werden, und repräsentiert einen mehrsprachigen Inhaltssatz, der im gesamten Workflow verwendet wird:

// 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."
  }

Elasticsearch-Mappings

Mit dem definierten Datensatz müssen wir ein Datenschema erstellen, das der Struktur des Blogbeitrags entspricht. Die folgenden Index-Mappings werden verwendet, um die Daten in Elasticsearch zu speichern:

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)

Hier können wir klar erkennen, wie die Daten strukturiert sind. Wir werden die semantische Suche verwenden, um Ergebnisse basierend auf natürlicher Sprache abzurufen, zusammen mit der copy_to-Eigenschaft, um den Feldinhalt in das semantic_text-Feld zu kopieren. Zusätzlich enthält das title-Feld zwei Unterfelder: Das original-Unterfeld speichert den Titel entweder auf Englisch oder Spanisch, abhängig von der Originalsprache des Artikels, und das translated_title-Unterfeld ist nur für spanische Artikel vorhanden und enthält die englische Übersetzung des Originaltitels.

Ingestieren von Daten

Der folgende Code-Schnipsel überträgt den Datensatz des Blogbeitrags in Elasticsearch mithilfe der Bulk-API:

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)}")

Nun, da wir die Artikel in Elasticsearch aufgenommen haben, müssen wir eine Funktion erstellen, die nach dem Feld semantic_text sucht:

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 []

Wir benötigen außerdem eine Funktion, die den Endpoint aufruft. In diesem Fall rufen wir den Endpoint mit dem chat_completion Aufgabentyp auf, um Streaming-Antworten zu erhalten:

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)}"

Nun können wir eine Funktion schreiben, die die semantische Suchfunktion, den chat_completions Inferenz-Endpoint und den Empfehlungs-Endoint aufruft, um die Daten zu generieren, die in den Karten angezeigt werden:

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

Abschließend müssen wir die Informationen extrahieren und formatieren, um sie zu drucken:

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 + "┘")

Wir führen einen Test durch, indem wir eine Frage zu den Sicherheitsblogbeiträgen stellen:

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)

Hier sehen wir die vom Workflow in der Konsole generierten Karten:

Die vollständigen Ergebnisse, einschließlich aller Treffer und der LLM-Reaktion, können Sie in dieser Datei sehen.

Wir bitten um Artikel zum Thema: „Sicherheit und Schwachstellen“. Diese Frage wird als Suchabfrage gegen die in Elasticsearch gespeicherten Dokumente verwendet. Die abgerufenen Ergebnisse werden dann an das Modell weitergegeben, das basierend auf ihrem Inhalt Empfehlungen generiert. Wie wir sehen können, hat das Modell gute Arbeit geleistet und einen ansprechenden kurzen Text erstellt, der den Leser zum Anklicken motivieren kann.

Fazit

Dieses Beispiel zeigt, wie Elasticsearch und Hugging Face kombiniert werden können, um ein schnelles und effizientes zentrales System für KI-Anwendungen zu schaffen. Dieser Ansatz reduziert den manuellen Aufwand und bietet dank des umfangreichen Modellkatalogs von Hugging Face mehr Flexibilität. Insbesondere die Verwendung von SmolLM3-3B zeigt, wie kompakte, mehrsprachige Modelle in Kombination mit semantischer Suche weiterhin sinnvolles Schlussfolgern und Content-Generierung liefern können. Zusammen bieten diese Tools eine skalierbare und effektive Grundlage für die Entwicklung intelligenter Inhaltsanalysen und mehrsprachiger Anwendungen.

Zur Lösung dieses Problems wenden Suchmaschinen wie Elasticsearch zwei wesentliche Optimierungsstrategien an:

1. Ungefähre Suche (Hierarchical Navigable Small World [HNSW]): Anstatt jedes Dokument zu durchsuchen, erstellen wir einen Navigationsgraphen, um schnell in die wahrscheinliche Nachbarschaft der Antwort zu gelangen.
2. Quantisierung: Wir komprimieren die Vektoren (beispielsweise von 32-Bit-Gleitkommazahlen auf 8-Bit-Ganzzahlen oder sogar auf 1-Bit-Binärwerte), um den Speicherbedarf zu verringern und die Berechnungen zu beschleunigen.

Doch Optimierung hat oft ihren Preis: Genauigkeit.

Die Befürchtung ist berechtigt: „Wenn ich meine Daten komprimiere und bei der Suche Abstriche mache, verpasse ich dann die besten Ergebnisse?“ „Beeinträchtigt diese Optimierung die Relevanz meiner Suchmaschine?“

Für den Nachweis, dass die Quantisierung von Elastic die Ergebnisse nicht beeinträchtigt, haben wir einen wiederholbaren Testrahmen unter Verwendung des DBPedia-14-Datensatzes entwickelt, um präzise zu berechnen, wie viel Genauigkeit (genauer gesagt Recall) wir bei der Verwendung der Standardoptimierungen in Elasticsearch zugunsten der Geschwindigkeit einbüßen.

Kurz gesagt: Viel weniger, als Sie denken. Sehen Sie sich das Notebook hier an und testen Sie es selbst

Die Definitionen (für die Nicht-Experten)

Klären wir zunächst einige Begriffe, bevor wir uns den Code ansehen.

• Relevanz vs. Recall: Relevanz ist subjektiv (habe ich etwas Gutes gefunden?). Recall ist mathematisch. Wenn sich in der Datenbank 10 Dokumente befinden, die perfekt zu Ihrer Abfrage passen, und die Suchmaschine neun davon findet, beträgt Ihr Recall 90 % (oder 0,9).
• Exakte Suche (flach): Wird auch als „Brute-Force“-Methode bezeichnet. Die Suchmaschine scannt jedes einzelne Dokument in einem Index und berechnet die Entfernung.
  • Vorteile: 100 % perfekter Recall.
  • Nachteile: Rechenintensiv und bei großem Umfang langsam.
• Näherungssuche (HNSW): Die „Abkürzungs“-Methode. Die Suchmaschine erstellt einen HNSW-Graphen. Sie durchläuft den Graphen, um die nächsten Nachbarn zu finden.
  • Vorteile: Extrem schnell und skalierbar.
  • Nachteile: Falls das Durchlaufen des Graphen zu früh beendet wird, könnte ein Nachbar übersehen werden.

Das Experiment: Exakt vs. ungefähr

Für den Recall-Test haben wir den DBPedia-14-Datensatz verwendet, einen umfangreichen Datensatz mit Titeln und Auszügen aus 14 Ontologieklassen, der häufig zum Trainieren und Bewerten von Modellen zur Textkategorisierung genutzt wird. Konkret konzentrieren wir uns auf die Kategorie „Film“. Wir wollten die optimierten Produktionseinstellungen mit einem mathematisch perfekten Referenzwert vergleichen.

Für dieses Experiment verwenden wir das Modell jina-embeddings-v5-text-small, ein fortschrittliches mehrsprachiges Modell, das bei den Branchen-Benchmarks für Textdarstellung führend ist. Wir haben uns für dieses Modell entschieden, da es den aktuellen Standard für leistungsstarke Einbettungen setzt. Durch die Kombination der herausragenden Genauigkeit von Jina v5 mit der nativen Quantisierung von Elasticsearch können wir eine Sucharchitektur präsentieren, die sowohl rechnerisch effizient ist als auch keine Kompromisse bei der Abrufqualität eingeht.

Wir haben einen Index mit doppeltem Mapping eingerichtet. Wir haben denselben Text gleichzeitig in zwei verschiedene Felder aufgenommen:

1. content.raw mit Typ: flat. Dadurch wird Elasticsearch gezwungen, einen Brute-Force-Scan der gesamten Float32-Vektoren durchzuführen. Hierdurch werden exakte Übereinstimmungen geliefert, die als Ausgangsbasis dienen.
2. content mit Typ semantic_text. Standardmäßig werden HNSW und „Better Binary Quantization“ (BBQ) verwendet. Hierbei handelt es sich um die standardmäßige, optimierte Produktionseinstellung für die ungefähre Übereinstimmung.

Der Recall @10-Test

Als Metrik verwendeten wir Recall@10.

Wir haben 50 zufällige Filme ausgewählt und dieselbe Abfrage für beide Felder durchgeführt.

• Wenn die exakte (flache) Suche ergibt, dass die ersten 10 Nachbarn IDs [1, 2, 3 ... 10] sind.
• Und die ungefähre (HNSW) Suche liefert die IDs [1, 2, 3 ... 9, 99].
• Wir haben neun der Top 10 korrekt gefunden. Der Score liegt bei 0,9.

Hier ist das von uns verwendete Mapping:

# 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"
        }
    }
}

Das Ergebnis: Die „flache Kurve“ des Erfolgs

Wir haben einen Skalierungstest durchgeführt, bei dem wir den gesamten Datensatz neu geladen und mit Indexgrößen von 1.000 bis 40.000 Dokumenten getestet haben.

So hat sich der Recall-Score entwickelt:

Die Ergebnisse waren erstaunlich stabil. Selbst als wir die Skalierung erhöhten, stimmte die ungefähre Suche in >99 % der Fälle mit der exakten Brute-Force-Suche überein.

Warum hat es so gut funktioniert?

Sie könnten erwarten, dass die Komprimierung von Vektoren zu Binärwerten die Genauigkeit stärker beeinträchtigen würde. Der Grund dafür liegt in der Art und Weise, wie Elasticsearch den Abruf handhabt.

Die meisten Einbettungsmodelle liefern heutzutage Float32-Vektoren als Ausgabe, die sehr groß sind. Für eine effiziente Suche nutzt Elasticsearch die Quantisierung für hochdimensionale Vektoren. Genauer gesagt wird seit Version 9.2 standardmäßig BBQ verwendet.

BBQ verwendet einen Rescoring-Mechanismus:

1. Durchlaufen: Die Suchmaschine verwendet die komprimierten (quantisierten) Vektoren, um den HNSW-Graphen schnell zu durchlaufen. Da die Vektoren klein sind, kann das System effizient überabtasten und so eine größere Liste von Kandidaten (zum Beispiel die 100 am ehesten passenden Dokumente) ohne Leistungseinbußen zusammenstellen.
2. Rescore: Sobald diese Kandidaten vorliegen, ruft das System die Werte in voller Genauigkeit nur für diese wenigen Dokumente ab, um das endgültige, genaue Ranking zu berechnen.

So erhalten Sie das Beste aus beiden Welten: die Geschwindigkeit der Quantisierung für die rechenintensiven Aufgaben und die Präzision von Gleitkommazahlen für die abschließende Sortierung.

Können wir das besser machen?

An dieser Stelle ist anzumerken, dass die hier gezeigten Ergebnisse auf den Standardeinstellungen und einer zufälligen Stichprobe von Daten basieren. Betrachten Sie das als einen leistungsstarken Ausgangspunkt. Auch wenn Jina v5 ein wahres Kraftpaket ist, sind diese Recall-Werte keine allgemeingültige Garantie für jeden Datensatz. Jede Datenerhebung hat ihre Eigenheiten, und obwohl es durchaus möglich ist, die Leistung durch weitere Optimierungen weiter zu steigern, sollten Sie stets einen Vergleichstest mit Ihren eigenen spezifischen Daten durchführen, um Ihre Leistungsgrenze zu ermitteln.

Fazit

Es handelt sich hierbei um einen sehr kleinen Test. Der Zweck dieser Übung besteht jedoch nicht speziell in der Messung des Einbettungsmodells oder von BBQ, sondern vielmehr in der Veranschaulichung, wie Sie mit minimalem Aufwand den Recall Ihres Datensatzes messen können.

Wenn Sie diesen Test mit Ihren eigenen Daten durchführen möchten, können Sie sich das Notebook hier ansehen und es selbst testen.

Die Erweiterung ist hier als Open-Source-Projekt verfügbar.

Was ist Gemini CLI, und wie installieren Sie sie?

Gemini CLI ist ein Open-Source-KI-Agent, der Googles Gemini-Modelle direkt in die Befehlszeile bringt. Er ermöglicht Entwicklern, über das Terminal mit KI zu interagieren, um Aufgaben wie das Generieren von Code, das Bearbeiten von Dateien, das Ausführen von Shell-Befehlen und das Abrufen von Informationen aus dem Web durchzuführen.

Im Gegensatz zu typischen Chat-Schnittstellen integriert sich die Gemini CLI in Ihre lokale Entwicklungsumgebung. Das bedeutet, dass sie den Projektkontext versteht, Dateien ändert, Builds oder Tests ausführt und Workflows direkt im Terminal automatisiert. Dies macht sie besonders nützlich für Entwickler, Site Reliability Engineers (SREs) und Engineers, die KI-gestütztes Codieren und Automatisierung wünschen, ohne ihren Befehlszeilen-Workflow zu verlassen.

Gemini CLI kann mit mehreren Paketmanagern installiert werden. Die gängigste Methode ist die Installation über npm:

npm install -g @google/gemini-cli

Wenn Sie sich über alternative Installationsmöglichkeiten informieren möchten, lesen Sie die offizielle Installationsseite.

Starten Sie die CLI nach der Installation durch Ausführen des folgenden Befehls:

gemini

Sie sehen einen Bildschirm, wie in Abbildung 1 dargestellt:

Elasticsearch konfigurieren

Wir benötigen eine laufende Elasticsearch-Instanz. Wenn Sie den Model Context Protocol (MCP)-Server verwenden möchten, benötigen Sie zudem Kibana 9.3+. Für die Nutzung der unten beschriebenen Elasticsearch Query Language (ES|QL)-Fähigkeit (esql) ist Kibana nicht erforderlich.

Sie können eine kostenlose Testversion auf Elastic Cloud aktivieren oder es lokal mit dem start-local-Skript installieren:

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

Dadurch werden Elasticsearch und Kibana auf Ihrem Computer installiert und ein API-Schlüssel generiert, den Sie für die Konfiguration von Gemini CLI verwenden können.

Der API-Schlüssel wird als Ausgabe des vorherigen Befehls angezeigt und in einer .env-Datei im Ordner elastic-start-local gespeichert.

Wenn Sie Elasticsearch lokal (zum Beispiel start-local), und Elastic Agent Builder mit MCP verwenden möchten, müssen Sie auch ein Large Language Model (LLM) verbinden. Lesen Sie diese Dokumentationsseite, um sich über die verschiedenen Optionen zu informieren.

Wenn Sie Elastic Cloud (oder serverless) verwenden, verfügen Sie bereits über eine vorgefertigte LLM-Verbindung.

Installieren Sie die Elasticsearch-Erweiterung

Sie können die Elasticsearch-Erweiterung für Gemini CLI mit folgendem Befehl installieren:

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

Sie können überprüfen, ob die Erweiterungen erfolgreich installiert wurden, indem Sie Gemini öffnen und den folgenden Befehl ausführen:

/extensions list

Die Elasticsearch-Erweiterung sollte verfügbar sein.

Wenn Sie die MCP-Integration verwenden möchten, müssen Sie die Elasticsearch-Version 9.3 oder höher installiert haben. Sie benötigen die URL Ihres MCP-Servers aus Kibana:

• Sie erhalten Ihre MCP-Server-URL unter Agenten > Alle Tools anzeigen > MCP verwalten > MCP-Server-URL kopieren.
• Die URL wird so aussehen: https://your-kibana-instance/api/agent_builder/mcp

Sie benötigen die URL des Elasticsearch-Endpoints. Dies wird üblicherweise oben auf der Kibana Elasticsearch-Seite angezeigt. Wenn Sie Elasticsearch mit start-local ausführen, ist der Endpoint bereits im Schlüssel ES_LOCAL_URL in der .env-Datei start-local hinterlegt.

Sie benötigen auch einen API-Schlüssel. Wenn Sie Elasticsearch mit start-local ausführen, ist der ES_LOCAL_API_KEY in der .env-Datei start-local hinterlegt. Andernfalls können Sie einen API-Schlüssel über die Kibana-Schnittstelle erstellen, wie hier beschrieben:

• In Kibana: Stack Management > Sicherheit > API-Schlüssel > API-Schlüssel erstellen.
• Wir empfehlen, nur die Leserechte für den API-Schlüssel festzulegen und so die hier beschriebene Berechtigung feature_agentBuilder.read zu aktivieren.
• Kopieren Sie den codierten API-Schlüsselwert.

Stellen Sie die erforderlichen Umgebungsvariablen in Ihrer Shell ein:

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

Installieren Sie den Beispieldatensatz

Sie können den Datensatz für E-Commerce-Bestellungen , der von Kibana verfügbar ist, installieren. Sie enthält einen einzigen Index mit dem Namen kibana_sample_data_ecommerce, der Informationen für 4.675 Bestellungen von einer E-Commerce-Website enthält. Für jede Bestellung haben wir folgende Informationen:

• Kundeninformationen (Name, Ausweis, Geburtsdatum, E-Mail-Adresse und mehr)
• Bestelldatum
• Bestell-ID
• Produkte (Liste aller Produkte mit Preis, Menge, ID, Kategorie, Rabatt und weiteren Details)
• SKU
• Gesamtpreis (ohne Steuern, mit Steuern)
• Gesamtmenge
• Geoinformationen (Stadt, Land, Kontinent, Ort, Region)

Um die Beispieldaten zu installieren, öffnen Sie die Seite Integrationen in Kibana (suchen Sie in der Suchleiste oben nach „Integration") und installieren Sie die Beispieldaten. Weitere Einzelheiten finden Sie in der Dokumentation hier.

Ziel dieses Artikels ist es, zu zeigen, wie einfach es ist, die Gemini CLI so zu konfigurieren, dass sie mit Elasticsearch verbunden ist und mit dem Index kibana_sample_data_ecommerce interagiert.

Verwendung des Elasticsearch MCP

Sie können die Verbindung mit folgendem Befehl in Gemini überprüfen:

/mcp list

Sie sollten sehen, dass elastic-agent-builder aktiviert ist, wie in Abbildung 2 dargestellt:

Elasticsearch bietet eine Reihe von Standardtools. Sehen Sie sich die Beschreibung hier an.

Mithilfe dieser Tools können Sie mit Elasticsearch interagieren und Fragen stellen wie:

• 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?

Je nach Frage wird Gemini eines oder mehrere der verfügbaren Tools verwenden, um sie zu beantworten.

Die /elastic-Befehle

In der Elasticsearch-Erweiterung für Gemini CLI haben wir auch/elastic-Befehle hinzugefügt.

Wenn Sie den Befehl /help ausführen, werden Ihnen alle verfügbaren /elastic-Optionen angezeigt (Abbildung 3):

Diese Befehle können nützlich sein, wenn Sie ein bestimmtes Tool des elastic-agent-builder-MCP-Servers direkt ausführen möchten. Beispielsweise können Sie mit dem folgenden Befehl das Mapping von kibana_sample_data_ecommerce abrufen:

/elastic:get-mapping kibana_sample_data_ecommerce

Diese Befehle sind im Wesentlichen Abkürzungen für das Ausführen spezifischer Tools, anstatt sich auf das Gemini-Modell zu verlassen, um zu bestimmen, welches Tool aufgerufen werden sollte.

Verwendung der Elasticsearch-Fähigkeiten

Diese Erweiterung beinhaltet außerdem eine agentische Fähigkeit für ES|QL, die in Elasticsearch verfügbare Elasticsearch Query Language. Agentische Fähigkeiten stellen ein offenes Format dar, das KI-Coding-Agenten wie Gemini CLI individuelle Anweisungen für bestimmte Aufgaben gibt. Sie verwenden ein Konzept namens Progressive Disclosure (progressive Offenlegung), was bedeutet, dass der anfänglichen Systemaufforderung nur eine kurze Beschreibung der Fähigkeit hinzugefügt wird. Wenn Sie den Agenten bitten, eine Aufgabe auszuführen, wie etwa eine Abfrage an Elasticsearch, passt er die Anfrage an die relevante Fähigkeit an und lädt dynamisch die detaillierten Anweisungen. Dies ist eine effiziente Methode, um Token-Budgets zu verwalten und der KI genau den Kontext bereitzustellen, den sie benötigt.

Die esql-Fähigkeit ist so konzipiert, dass Gemini CLI ES|QL-Abfragen direkt in Ihrem Cluster schreiben und ausführen kann. ES|QL ist eine leistungsstarke Abfragesprache, die die Datenexploration, die Log-Analyse und die Aggregationen sehr intuitiv macht. Wenn diese Fähigkeit aktiviert ist, müssen Sie nicht nach der ES|QL-Syntax suchen; Sie können der Gemini CLI einfach Fragen zu Ihren Daten in natürlicher Sprache stellen, und der Agent kümmert sich um den Rest.

Die Ausführung erfolgt mit einfachen curl-Befehlen, die in einem Terminal ausgeführt werden. Dies ist möglich, da Elasticsearch eine umfangreiche Sammlung von REST APIs bereitstellt, die sich problemlos in jede beliebige Architektur integrieren lassen.

Was die esql Fähigkeit bietet:

• Erkennung von Indizes und Schemata: Der Agent kann die integrierten Tools der Fähigkeit nutzen, um verfügbare Indizes aufzulisten und Feld-Mappings abzurufen. Bevor der Agent beispielsweise eine Abfrage für die E-Commerce-Datensätze schreibt, kann er eine Schema-Prüfung für kibana_sample_data_ecommerce ausführen, um die verfügbaren Felder wie taxful_total_price oder category zu ermitteln.
• Nahtlose Übersetzung natürlicher Sprache: Diese Fähigkeit bietet dem Agenten mehr als nur ein einfaches Nachschlagewerk; sie liefert eine konkrete Anleitung zur Interpretation der Nutzerabsicht. Wenn Sie Anfragen in natürlicher Sprache eingeben, wie „Zeige durchschnittliche Reaktionszeit gruppiert nach Service“, nutzt der Agent die in der Fähigkeit integrierte Mustererkennung, um Ihre Worte sofort in die richtigen ES|QL-Aggregationen, Filter und Befehle umzuwandeln.
• Selbstkorrektur: Wenn eine Abfrage fehlschlägt (zum Beispiel wegen eines Typfehlers oder eines Syntaxfehlers), gibt die Fähigkeit die generierte Abfrage zusammen mit der genauen Elasticsearch-Fehlermeldung zurück, sodass der Agent die Abfrage sofort beheben und erneut ausführen kann, ohne dass Sie eingreifen müssen.

Da die esql-Fähigkeit auch als Tool auf dem elastic-agent-builder-MCP-Server verfügbar ist, müssen wir diesen Server vorübergehend deaktivieren. Sie können sie mit dem folgendem Befehl deaktivieren:

/mcp disable elastic-agent-builder

Dann können Sie einfach einen Befehl wie diesen in Ihre Gemini CLI eingeben:

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

Der Agent wird:

• Die Notwendigkeit der esql-Fähigkeit erkennen
• Überprüfen Sie das Schema von kibana_sample_data_ecommerce.
• Eine ES|QL-Abfrage erstellen wie: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5
• Die Abfrage über die Elasticsearch-API ausführen
• Das Ergebnis Ihnen direkt im Terminal anzeigen

Hier haben wir ein Beispiel für die Antwort von Gemini auf die vorherige Eingabe aufgeführt:

───────────────────────────────────────────────────────────
> 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.
 ───────────────────────────────────────────────────────────

Es ist interessant festzustellen, wie das Gemini-Modell die endgültige Antwort generiert, indem es alle Schritte zeigt, die es dabei durchläuft. Hier können Sie deutlich den Einfluss der Fähigkeit auf den Denkprozess des Modells erkennen. Wenn das Modell zum ersten Mal erkennt, dass es eine Fähigkeit verwenden oder einen Shell-Befehl ausführen muss, erfragt es die Genehmigung mithilfe des Human-in-the-Loop-Ansatzes.

Durch die Übernahme der aufwendigen Aufgaben der Schemaerkennung, Abfragegenerierung und -ausführung ermöglicht Ihnen die esql-Fähigkeit, sich voll und ganz auf die Antworten zu konzentrieren, anstatt auf die Mechanismen ihrer Ermittlung. Sie erhalten die Daten, die Sie benötigen, richtig formatiert und direkt in Ihrem Terminal, ohne jemals eine einzige Zeile Syntax zu schreiben oder zu einer anderen Anwendung zu wechseln.

Fazit

In diesem Artikel haben wir die kürzlich veröffentlichte Elasticsearch-Erweiterung für die Gemini CLI vorgestellt. Mit dieser Erweiterung können Sie über Gemini und den von Elastic Agent Builder bereitgestellten Elasticsearch-MCP-Server, der ab Version 9.3.0 verfügbar ist, sowie über den Befehl /elastic mit Ihrer Elasticsearch-Instanz interagieren.

Darüber hinaus enthält die Erweiterung auch eine esql-Fähigkeit, die die Anfrage eines Nutzers von der natürlichen Sprache in eine ES|QL-Abfrage umwandelt. Diese Fähigkeit kann besonders nützlich sein, wenn der MCP-Server nicht genutzt werden kann, da die zugrundeliegende Kommunikation durch einfache Curl-Befehle in einem Terminal gesteuert wird. Elasticsearch bietet eine umfangreiche Auswahl an REST APIs, die leicht in jedes Projekt integriert werden können. Dies ist besonders nützlich bei der Entwicklung von agentischen KI-Anwendungen.

Weitere Informationen zu unserer Gemini CLI-Erweiterung finden Sie hier im Projekt-Repository.

Deshalb stellen wir Elastic Agent Skills als Open Source zur Verfügung: native Plattform-Expertise für Elasticsearch, Kibana, Elastic Observability und Elastic Security. Fügen Sie sie in die Agenten-Runtime ein, die Sie bereits verwenden, und machen Sie Ihren Agenten aus einem „Generalisten“, der viel Syntax erraten kann, zu einem Experten, der in der Lage ist, viele der Architekturstandards genauso wie die Entwicklungsteams von Elastic selbst zu verwenden. Diese erste technische Vorschauversion konzentriert sich auf Fähigkeiten mit maximaler Kompatibilität für Elastic Cloud Serverless, wird sich aber schnell weiterentwickeln, um auch eine verbesserte Unterstützung für ältere Stack-Versionen zu bieten.

Darüber hinaus löst Elastic dieses Problem von beiden Seiten. Für Agenten auf der Elastic-Plattform ermöglicht der Elastic Agent Builder (jetzt allgemein verfügbar) das Erstellen und Chatten mit KI-Agenten, die die Zugriffskontrollen Ihrer Daten erben, integrierte Such- und Analysetools verwenden und kontextbezogen neben Ihren Dashboards, Alerts und Untersuchungen arbeiten. Wir arbeiten intensiv daran, herausragende agentische Erlebnisse auf der Elastic-Plattform zu gewährleisten. Aber nicht jeder Agent ist in Elastic integriert. Ihr Team verwendet bereits Cursor, Claude Code oder andere Laufzeitumgebungen, und diese Agenten müssen Elastic ebenfalls richtig einsetzen. An dieser Stelle kommen Agent Skills ins Spiel.

Warum Agenten mit spezialisierten Plattformen Schwierigkeiten haben

Große Sprachmodelle (LLMs) sind bemerkenswert leistungsfähige Generalisten. Sie können Python schreiben, Kubernetes-Manifeste erklären und React-Komponenten refaktorisieren, weil ihre Trainingsdaten reich an Beispielen sind. Aber wenn es um plattformspezifische Arbeit geht, die proprietäre Abfragesprachen, tiefe API-Oberflächen und domänenspezifische Best Practices beinhaltet, stoßen sie auf vorhersehbare Weise an ihre Grenzen.

Bei Elasticsearch zeigt sich die Lücke ganz konkret:

• Die Elasticsearch-Abfragesprache (ES|QL) ist Neuland. LLMs werden intensiv in SQL geschult, aber ES|QL ist eine Pipe-Abfragesprache mit anderer Syntax, anderen Funktionen und anderer Semantik. Agenten schreiben oft Abfragen, die plausibel aussehen, aber nicht parsen. Sie verwechseln WHERE mit | WHERE, erfinden Funktionen, die es nicht gibt, und übersehen das Pipe-basierte Kompositionsmodell völlig.
• API-Oberflächen sind breit und tief. Elasticsearch, Kibana und Elastic Security stellen Hunderte von APIs für Suche, Ingestion, Alerting, Erkennungsregeln, Ticketmanagement, Dashboard und mehr zur Verfügung. Ein Agent, der nur mit allgemeinen Trainingsdaten ausgestattet ist, muss erraten, welchen Endpoint er aufrufen soll, wie der Anfragetext aussieht und wie er mit der Reaktion umgehen soll. Er rät oft genug falsch und untergräbt damit das Vertrauen.
• Best Practices liegen nicht in den Trainingsdaten. Wann sollten Sie semantic_text im Vergleich zu einer benutzerdefinierten Einbettungs-Pipeline verwenden? Wie sollte man eine Ingest-Pipeline für eine 10-GB-CSV strukturieren? Was ist die richtige Erkennungsregelsyntax für eine MITRE ATT&CK-Technik? Allgemeine Agenten haben standardmäßig kein kuratiertes, zuverlässig strukturiertes Elastic-spezifisches Wissen geladen. Sie müssten es erst einmal finden, und selbst wenn sie es fänden, spiegeln Rohdokumente nicht immer die Beurteilungen und Best Practices wider, die erfahrene Fachleute anwenden.

Das Ergebnis: Entwickler verbringen mehr Zeit damit, die Ausgabe des Agenten zu korrigieren, als sie für das Schreiben des Codes selbst benötigt hätten. Das ist nicht das, was man haben wollte.

Agent Skills: Plattformwissen, speziell für Agenten aufbereitet

Agent Skills sind selbstständige Verzeichnisse mit Anweisungen, Skripten und Referenzmaterial, die in Agentenlaufzeiten dynamisch geladen werden können. Wenn ein Skill, also eine Fähigkeit, aktiv ist, hat der Agent zum richtigen Zeitpunkt Zugriff auf den richtigen Kontext: Abfragesyntax, API-Muster, Validierungslogik, ausgearbeitete Beispiele, sodass er Aufgaben schon beim ersten Versuch korrekt ausführen kann.

Jede Fähigkeit folgt der offenen agentskills.io-Spezifikation: einem Ordner mit einer SKILL.md-Datei, die Metadaten und strukturierte Anweisungen enthält. Kein proprietäres Format, keine Anbieterabhängigkeit. Fähigkeiten funktionieren über Agentenlaufzeiten hinweg, darunter Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini CLI, Cline, Codex und viele mehr.

Was enthält die erste Version 0.1.0?

Die erste Gruppe von Fähigkeiten umfasst fünf Bereiche des Elastic Stack:

• Interaktion mit den Elasticsearch-APIs (Suche, Indizierung, Clusterverwaltung)
• Erstellung und Verwaltung von Kibana-Inhalten wie Dashboards, Warnmeldungen, Konnektoren und mehr
• Domänenexpertise für Elastic Observability
• Domänenexpertise für Elastic Security
• Erstellung effektiver Agenten in Agent Builder

Skills sind kombinierbar

Skills sind nicht monolithisch. Sie sind von Natur aus modular. Ihr Agent lädt nur die Fähigkeiten, die für die jeweilige Aufgabe relevant sind. Arbeiten Sie an einer ES|QL-Abfrage? Die ES|QL-Fähigkeit wird aktiviert. Müssen Sie aus diesen Ergebnissen ein Dashboard erstellen? Die Dashboard-Fähigkeit wird aktiviert. Müssen Sie den Zustand Ihrer Anwendung beurteilen? Da kommt die Dienstzustandsfähigkeit ins Spiel. Sie untersuchen eine Sicherheitswarnung? Die Triage-Fähigkeiten werden im Verlauf der Untersuchung in Ticketmanagement- und Reaktionsfähigkeiten umgewandelt.

Diese Komponierbarkeit bedeutet, dass Sie keinen einzigen, massiven Prompt benötigen, der versucht, alles abzudecken. Jede Fähigkeit trägt genau den Kontext, den ihr Bereich erfordert, nichts mehr, nichts weniger.

Für Entwickler, die Such- und KI-Anwendungen entwickeln

Wenn Sie Daten in Elasticsearch laden, Abfragen schreiben oder Indizes migrieren, reduzieren Skills den Kreislauf aus Codegenerierung, Fehlersuche und der Suche nach der Ursache in der Dokumentation.

Bitten Sie Ihren Agenten, eine CSV-Datei zu laden und er verwendet ein Streaming-Ingestion-Tool, das Backpressure handhabt und aus den Daten Zuordnungen ableitet. Es handelt sich dabei nicht um eine handgesteuerte _bulk-Schleife, die beim Ausführen der ersten großen Datei den Speicher erschöpft. Bitten Sie ihn um eine Abfrage mit ES|QL und er entdeckt Ihre tatsächlichen Indexnamen und Feldschemata und schreibt dann gültige Pipe-Abfragen mit korrekter Syntax, geeigneten Aggregationen und versionsabhängiger Feature-Auswahl, nicht eine SQL-basierte Vermutung, die drei Runden Debugging erfordert. Fordern Sie ihn auf, die Neuindizierung Cluster-übergreifend durchzuführen und er wird dem gesamten operativen Workflow folgen: Er erstellt das Ziel mit expliziten Zuordnungen, optimiert die Einstellungen für den Durchsatz, führt den Job asynchron aus und stellt nach Abschluss die Produktionseinstellungen wieder her – das ist nicht nur ein einfacher _reindex-Aufruf, der die Hälfte der Schritte überspringt, die ein erfahrener Operator befolgen würde.

Statt eines Agenten, der Ihnen einen plausiblen Ausgangspunkt liefert, den Sie dann korrigieren müssen, erhalten Sie einen, der die operative Disziplin kodiert, die dafür sorgt, dass das Ergebnis tatsächlich funktioniert.

Beispiele für die Wirkung von Elastic Agent Skills

Für Sicherheitsteams

Security-Teams wiederholen täglich die gleichen operativen Workflows: Priorisierung von Warnmeldungen, Anpassung von Erkennungsregeln und Verwaltung von Tickets. Agent Skills kodieren dieses prozedurale Wissen, damit Ihr KI-Agent die Workflows korrekt ausführen kann, indem er die richtigen APIs in der richtigen Reihenfolge mit den richtigen Feldnamen aufruft. Eine praktische Anleitung, die Sie von null zu einer vollständig eingerichteten Elastic Security-Umgebung führt, ohne Ihre IDE zu verlassen, finden Sie unter Erste Schritte mit Elastic Security von Ihrem KI-Agenten aus.

Für Observability- und operative Teams

Die neuen Agent Skills für Elastic Observability reduzieren den betrieblichen Aufwand bei der Instrumentierung komplexer Systeme, der Verwaltung von SLOs, der Sichtung komplexer Daten und der Bewertung des Dienstzustands. Die direkte Einbettung nativer Elastic-Expertise in KI-Agenten ermöglicht es Teams, komplexe Beobachtbarkeits-Workflows mit einfacher natürlicher Sprache auszuführen. Dadurch können SREs und Ops-Teams Vorfälle schneller beheben und zuverlässige Systeme einfacher pflegen. Weitere Informationen finden Sie in diesem Blog.

Open Source, offene Spezifikationen, Community-gesteuert

Wir veröffentlichen Agent Skills unter der Apache-2.0-Lizenz, weil wir glauben, dass Agentenwissen offen sein sollte. Die agentskills.io-Spezifikation, der die Skills folgen, ist ein offener Standard, kein proprietäres Elastic-Format. Wir möchten, dass Fähigkeiten eine Gemeinschaftsleistung sind, kein geschlossener Bereich.

Teil eines größeren Ganzen

Agent Skills ist Teil einer umfassenderen Initiative, Elasticsearch zur agentenfreundlichsten Datenplattform zu machen. Für Agenten, die in die Elasticsearch-Plattform integriert sind, geht Agent Builder noch einen Schritt weiter, indem es die Zugriffskontrollen und Berechtigungen Ihrer Daten übernimmt, integriert und individuelle Tools für Suche und Analyse bereitstellt und Nutzern erlaubt, mit Agenten im Kontext und ihren Dashboards, Warnungen und Untersuchungen zu interagieren. Schließlich wird in Kürze auch die Unterstützung für Skills in Agent Builder verfügbar sein und Entwicklern die Flexibilität geben, Elastic Agent Skills sowie Skills aus beliebigen anderen Quellen zu nutzen, um sichere, kontextbezogene Chats und Automatisierungen auf der Elasticsearch-Plattform zu ermöglichen.

Für Agenten an allen anderen Orten investieren wir in das offene Ökosystem:

• Erweiterung des Model Context Protocol (MCP)-Servers: Die Erweiterung des MCP Endpoints in Agent Builder um weitere Tools über die aktuelle Suche, ES|QL und Indexoperationen hinaus.
• Verbesserungen bei der Authentifizierung: Dies macht es für Agenten einfacher, eine sichere Verbindung herzustellen, mit dem Ziel, manuelles Kopieren und Einfügen von API-Schlüsseln zu eliminieren.
• LLM-lesbare Dokumentation: Veröffentlichung der Dateien llms.txt und AGENTS.md, damit Agenten Elastic-APIs selbstständig finden und verstehen können.
• Eine Befehlszeilenschnittstelle (CLI) für Agenten-Workflows: Ein Befehlszeilentool, das die Verbindungsverwaltung und gängige Operationen agentenfreundlich gestaltet.

Skills sind die Ebene, die Sie heute nutzen können. Der Rest folgt.

Erste Schritte

Bevor Sie beginnen: KI-Programmieragenten arbeiten mit echten Anmeldeinformationen, echtem Shell-Zugriff und oft mit den vollen Berechtigungen des Nutzers, der sie ausführt. Wenn diese Agenten auf Sicherheitsworkflows ausgerichtet werden, steigen die Risiken: Sie geben einem automatisierten System Zugriff auf Erkennungslogik, Reaktionsmaßnahmen und sensible Telemetrie. Das Risikoprofil jeder Organisation ist unterschiedlich. Bevor Sie KI-gesteuerte Sicherheitsworkflows aktivieren, sollten Sie prüfen, auf welche Daten der Agent zugreifen kann, welche Maßnahmen er ausführen kann und was passiert, wenn er sich nicht so verhält, wie erwartet.

Installieren Sie Elastic Agent Skills in Ihrer Agenten-Runtime:

npx skills add elastic/agent-skills

Dadurch werden Ihre installierten Agenten-Runtimes automatisch erkannt und die Skills im richtigen Konfigurationsverzeichnis abgelegt. Von dort aus nimmt Ihr Agent sie automatisch auf.

Sie können den Fähigkeitenkatalog auch direkt durchsuchen und einzelne Fähigkeiten manuell installieren, indem Sie den Fähigkeitenordner in das Konfigurationsverzeichnis Ihres Agenten kopieren.

Sie haben noch keinen Elasticsearch-Cluster? Starten Sie eine kostenlose Elastic Cloud-Testversion. Es dauert etwa eine Minute, bis eine vollständig konfigurierte Umgebung eingerichtet ist.

Projekt erkunden:

• Agent Skills-Repository
• agentskills.io Spezifikation
• Elasticsearch-Dokumentation
• Elastic Cloud kostenlos testen

Wie wir im vorherigen Beitrag gesehen haben, ist die Konstanz, die durch Funktionsaufrufe ermöglicht wird, nicht nur eine praktische Optimierung, sondern essenziell. Nachdem wir strukturelle Fehler aus dem Evaluationskreislauf entfernt hatten, verbesserten sich die Ergebnisse in Standardszenarien (wie denen im Tier-4-Datensatz) dramatisch.

Doch eine offensichtliche Frage bleibt noch zu beantworten:

Funktioniert dieser Ansatz noch, wenn es kompliziert wird?

Die Entitätsauflösung in der realen Welt schlägt selten in einfachen Fällen fehl. Sie scheitert, wenn Namen Sprach-, Kultur-, Schrift-, Zeit- und Unternehmensgrenzen überschreiten. Sie scheitert, wenn auf Menschen mit Titeln anstelle von Namen Bezug genommen wird, wenn Unternehmen Namen ändern, wenn Transliterationen nicht konstant sind und wenn Kontext (nicht die Schreibweise) das Einzige ist, was eine Erwähnung mit einer realen Entität verbindet.

Für den letzten Beitrag dieser Serie haben wir das System einer sogenannten ultimativen Herausforderung unterzogen.

Was macht dies zur ultimativen Herausforderung?

In früheren Auswertungen haben wir das System mit zunehmend komplexeren Datensätzen getestet. Als wir die im vorherigen Beitrag besprochene Stufe 4 erreichten, hatten wir es bereits mit einer Mischung aus Spitznamen, Titeln, mehrsprachigen Namen und semantischen Bezügen zu tun. Diese Tests zeigten, dass die Architektur selbst solide war, aber dass Zuverlässigkeitsprobleme, insbesondere fehlerhaftes JSON, den Rückruf unterdrückten.

Mit dem implementierten Funktionsaufruf hatten wir endlich eine stabile Grundlage. So konnten wir eine interessantere Frage stellen:

Kann eine einheitliche Pipeline viele verschiedene Arten von Entitätsauflösungsproblemen gleichzeitig bewältigen?

Der ultimative herausfordernde Datensatz wurde darauf ausgelegt, genau diese Dimension zu erreichen.

Anstatt sich auf eine einzelne Schwierigkeit (wie Spitznamen oder Transliteration) zu konzentrieren, kombiniert dieser Datensatz mehr als 50 verschiedene Herausforderungstypen, darunter:

• Kulturelle Namenskonventionen.
• Titelbasierte Referenzen.
• Geschäftliche Beziehungen und historische Namensänderungen.
• Mehrsprachige und skriptübergreifende Erwähnungen.
• Zusammengesetzte Herausforderungen, die mehrere der oben genannten Punkte kombinieren.

Entscheidend ist, dass es hier nicht um die Optimierung für einen einzigen, eng begrenzten Anwendungsfall geht. Es geht darum zu testen, ob das Entwurfsmuster Bestand hat, wenn sich die Regeln von Entität zu Entität ändern.

Der Datensatz auf einen Blick

Der ultimativ herausfordernde Datensatz besteht aus:

• 50 Entitäten, darunter Personen, Unternehmen und Institutionen.
• ~60 Artikel, mit unterschiedlicher Struktur und sprachlicher Komplexität.
• 51 verschiedene Herausforderungskategorien, grob unterteilt in:
  • Kulturelle Namenskonventionen.
  • Titel und beruflichem Kontext.
  • Geschäfts- und Unternehmensbeziehungen.
  • Mehrsprachigkeit und Transliterationsherausforderungen.
  • Kombinierten und Grenzfall-Szenarien.

Zu Beginn der Serie haben wir gesehen, dass die Verwendung von generativer KI (GenKI) zur Erstellung von Datensätzen ein zweischneidiges Schwert sein kann. Ohne sie wäre es äußerst schwierig, ausreichend große und vielfältige Testdaten zusammenzustellen. Aber wenn das Modell nicht kontrolliert wird, neigt es dazu, die Dinge zu einfach zu machen.

Bei einer frühen Generationsüberprüfung stellten wir beispielsweise fest, dass das Modell Formulierungen wie „der russische Präsident“ als expliziten Aliasnamen für Wladimir Putin enthielt. Das mag heute vernünftig erscheinen, aber es widerspricht dem Zweck der Prüfung der Kontextauflösung. Was passiert, wenn der Artikel Russland in den 1990er Jahren behandelt? Das System sollte die richtige Entität aus dem Kontext ableiten und sich nicht auf einen fest codierten Alias verlassen.

Aus diesem Grund wurde dieser Datensatz bewusst so konzipiert, dass Abkürzungen nicht funktionieren. Pseudonyme werden nicht explizit aufgeführt, wenn das System die Bedeutung erschließen soll. Beschreibende Phrasen sind nicht vorab mit Entitäten verknüpft. Korrekte Treffer hängen oft vom Kontext auf Artikelebene ab, nicht nur vom lokalen Text.

Wichtiger Hinweis: Obwohl wir die Fähigkeiten des Systems in verschiedenen Szenarien demonstrieren, ist dies dennoch ein Bildungsprototyp. Produktionssysteme, die die Überwachung von sanktionierten Entitäten in der realen Welt handhaben, würden zusätzliche Validierung, Compliance-Prüfungen, Audit-Trails und eine spezialisierte Handhabung für sensible Anwendungsfälle erfordern.

Warum diese Szenarien schwierig sind

Im ersten Beitrag dieser Reihe haben wir ein einfaches, aber mehrdeutiges Beispiel vorgestellt: „Das neue Swift-Update ist da!“ Die Herausforderung besteht darin, dass „Swift“ je nach Kontext auf mehrere reale Entitäten aufgelöst werden kann. Dieses Beispiel verdeutlicht eine grundlegendere Wahrheit: Natürliche Sprache ist von Natur aus mehrdeutig.

Die Entitätsauflösung ist daher nicht nur ein Problem des Zeichenfolgenabgleichs. Menschen verlassen sich routinemäßig auf gemeinsames Wissen, kulturelle Normen und situativen Kontext, um Referenzen zu lösen, und oft merken wir gar nicht, dass wir das tun.

Betrachten wir ein paar gängige Fälle:

• Ein Titel wie „der Präsident“ ist ohne geopolitischen und zeitlichen Kontext bedeutungslos.
• Ein Firmenname kann sich je nach Zeitpunkt der Artikelveröffentlichung auf ein Mutterunternehmen, eine Tochtergesellschaft oder eine ehemalige Marke beziehen.
• Der Name einer Person kann in verschiedenen Reihenfolgen, Schriften oder Transliterationen erscheinen, abhängig von Sprache und Kultur.
• Die gleiche Phrase kann in verschiedenen Kontexten legitimerweise auf unterschiedliche Entitäten verweisen, und das System muss in der Lage sein, Matches genauso zuversichtlich abzulehnen, wie sie zu akzeptieren.

Es gibt kein einzelnes Regelwerk, das all dies sauber abdeckt. Deshalb trennt dieser Prototyp die verschiedenen Bereiche so konsequent:

• Elasticsearch schränkt den Kandidatenraum effizient und transparent ein.
• Das LLM wird nur dort verwendet, wo ein Urteil erforderlich ist, und ist gezwungen, sich selbst zu erklären.
• Abruf und Schlussfolgerung bleiben getrennte Schritte.

Diese Trennung wird umso wichtiger, je größer die Vielfalt der Herausforderungen ist.

So geht das System mit Vielfalt ohne Spezialfälle um

Eines der interessantesten Ergebnisse dieser Bewertung ist, was sich nicht geändert hat:

• Wir haben keine spezielle Logik für japanische Namen hinzugefügt.
• Wir haben keine benutzerdefinierten Regeln für arabische Patronyme hinzugefügt.
• Wir haben keine fest codierten Mappings für historische Firmennamen hinzugefügt.

Stattdessen basierte das System auf denselben Kernzutaten, die früher in der Serie eingeführt wurden:

• Mit Kontext angereicherte Entitäten, die für semantische Suchen indexiert sind.
• Hybrider Abruf (exakt, per Alias und semantisch) in Elasticsearch.
• Eine kleine, gut definierte Gruppe von Kandidatenmatches.
• LLM-Bewertung eingeschränkt durch Funktionsaufruf und Minimalschemata.

Das deutet darauf hin, dass die Flexibilität des Systems von Repräsentation und Architektur herrührt, nicht von einer ständig wachsenden Sammlung von Regeln.

Wenn das System erfolgreich ist, liegt das daran, dass die richtigen Kandidaten ermittelt werden und das LLM ausreichend Kontext hat, um zu erklären, warum eine Referenz einer bestimmten Entität zugeordnet wird oder nicht.

Ergebnisse: Wie hat es abgeschnitten?

Im ultimativ herausfordernden Datensatz erzielte das System folgende Gesamtergebnisse:

• Präzision: ~91 %
• Rückruf: ~86 %
• F1-Score: ~89 %
• LLM-Annahmequote: ~72 %

Leistung nach Herausforderungstyp

Die Aufschlüsselung der Ergebnisse nach Herausforderungstyp zeigt Stärken und Schwächen:

Die stärkste Leistung (100 % F1-Score) wurde in folgenden Bereichen beobachtet:

• Schriftübergreifender Abgleich (kyrillische, koreanische, chinesische Unternehmen).
• Hebräische Szenarien (Patronyme, Berufstitel, religiöse Titel, Transliteration).
• Unternehmenshierarchien (Luft- und Raumfahrt, diversifizierte Fertigungsunternehmen, Konzerne mit mehreren Geschäftsbereichen).
• Berufsbezeichnungen (akademisch, militärisch, politisch, religiös).
• Kombinierte japanische Szenarien mit mehreren Schriftsystemen.

Starke Leistung (80–99 % F1-Score) umfassten:

• Internationale politische Persönlichkeiten (98 %).
• Historische Namensänderungen (90 %).
• Komplexe Unternehmenshierarchien (89 %).
• Japanische Firmennamen (93 %).
• Cross-Script-Transliteration (86 %).
• Arabische Patronyme (86 %).

Problematischere Bereiche waren:

• Erweiterte Transliteration (Chinesisch, Koreanisch): 0 % F1.
• Bestimmte japanische Szenarien (Höflichkeitsformen, Namensreihenfolge, Variationen des Schriftsystems): ~67 % F1.
• Einige arabische Szenarien (Unternehmensnamen, institutionelle Referenzen): ~40 % F1.

Wichtig ist hier, warum das System in diesen Fällen Schwierigkeiten hatte. Die Fehler waren nicht auf das Scheitern des Gesamtansatzes zurückzuführen, sondern auf Einschränkungen in bestimmten Komponenten, insbesondere dem dichten Vektormodell, das für die semantische Suche in bestimmten mehrsprachigen Szenarien verwendet wird.

Da Abruf und Beurteilung klar getrennt sind, erfordert die Leistungssteigerung keine Neuprogrammierung des Systems. Der Austausch eines leistungsfähigeren mehrsprachigen Einbettungsmodells, die Anreicherung des Entitätskontextes oder die Verfeinerung der Suchstrategien würde die Ergebnisse in diesen Kategorien verbessern, ohne die Kernarchitektur zu verändern.

Aus architektonischer Sicht ist das der eigentliche Erfolgsmaßstab.

Was uns das über das Design verrät

Beim Rückblick auf die Serie lassen sich einige Muster erkennen:

• Vorbereitung ist wichtiger als kluges Matching. Die Anreicherung von Entitäten mit Kontextinformationen im Vorfeld reduziert spätere Mehrdeutigkeiten erheblich.
• LLMs sind als Bewertungs- und nicht als Abrufsysteme am wertvollsten. Sie um eine Erklärung zu bitten, warum eine Übereinstimmung sinnvoll ist, ist weitaus wirkungsvoller als sie um eine Suche zu bitten.
• Zuverlässigkeit ermöglicht Genauigkeit. Der Funktionsaufruf hat nicht nur JSON bereinigt, sondern auch den Abruf von Informationen freigegeben, die bereits in der Abrufphase latent waren.
• Verallgemeinerung schlägt Spezialisierung. Eine kleine Anzahl gut gewählter Abstraktionen bewältigte Dutzende von Aufgabentypen ohne benutzerdefinierte Logik.

Aus diesem Grund ist der Prototyp bewusst Elasticsearch-nativ und konservativ in der Verwendung von LLMs. Das Ziel besteht nicht darin, das Suchen zu ersetzen. Es geht darum, das Suchen in Situationen erklärbar zu machen, in denen die Bedeutung wichtig ist.

Fazit

Die ultimative Herausforderung bestand nicht darin, perfekte Metriken zu verfolgen; es ging darum, eine grundlegendere Frage zu beantworten:

Kann eine transparente, suchbasierte, LLM-gestützte Architektur mit der Mehrdeutigkeit realer Entitäten umgehen, ohne in Regeln oder Blackboxes zu zerfallen?

Für diesen Bildungsprototyp lautet die Antwort ja, mit klaren Vorbehalten in Bezug auf Produktionshärtung, Compliance, Überwachung und Datenqualität. Wenn Sie Systeme erstellen, die begründen müssen, warum ein Entitätsabgleich vorgenommen wurde, ist dieses Muster eine ernsthafte Überlegung wert. Ich hoffe, diese Serie hat gezeigt, dass die Entitätsauflösung kein Mysterium sein muss. Mit der richtigen Aufteilung der Anliegen wird sie zu etwas, worüber man nachdenken, was man messen und verbessern kann.

Diese Arbeit deutet auch auf ein breiteres architektonisches Muster hin. Daraus entsteht eine leichte, aber wichtige Weiterentwicklung der klassischen Retrieval-Augmented-Generation (RAG). Anstatt die Abfrage direkt in die Generierung einfließen zu lassen, führen wir einen expliziten Bewertungsschritt ein. Das LLM wird zunächst zur Beurteilung und Plausibilitätsprüfung der abgerufenen Kandidaten verwendet, und nur die als geeignet befundenen Ergebnisse dürfen die Generierung erweitern. Sie können sich das als Generation-Augmented Retrieval-Augmented Generation with Evaluation oder GARAGE vorstellen, denn wer weiß nicht ein gutes Akronym zu schätzen?

Welche anderen Anwendungsfälle könnten von diesem Muster profitieren? Systeme, die Vertrauen, Transparenz und nachvollziehbare Argumentation erfordern, sind natürliche Kandidaten. Die künftige Arbeit in diesem Bereich sollte sich als ebenso überzeugend erweisen wie die Ergebnisse, die wir hier gesehen haben, und ich bin gespannt, wie sich die Gemeinschaft weiter entwickelt.

Nächste Schritte: Versuchen Sie es selbst

Möchten Sie die ultimative Herausforderung in Aktion sehen? Schauen Sie sich das Ultimate Challenge-Notebook für eine vollständige Anleitung mit realen Implementierungen, detaillierten Erklärungen und praktischen Beispielen an.

Die vollständige Pipeline zur Entitätsauflösung demonstriert die Kernkonzepte und die Architektur, die für den produktiven Einsatz erforderlich sind. Sie können es als Grundlage nutzen, um Systeme zu entwickeln, die Nachrichtenartikel überwachen, Erwähnungen von Entitäten verfolgen und Fragen beantworten, welche Entitäten in welchen Artikeln erscheinen – und das alles, während Transparenz und Erklärbarkeit erhalten bleiben.

In HNSW erfolgt die Suche durch das iterative Erweitern von Kandidatenknoten im Graphen, wobei eine begrenzte Menge der bisher entdeckten nächsten Nachbarn gepflegt wird. Jede Erweiterung hat Kosten zur Folge (Vektorabläufe, zufällige Suchaktionen zur Festplatte und mehr), wobei der marginale Vorteil dieser Kosten tendenziell abnimmt, je weiter die Suche voranschreitet.

Eine Möglichkeit, die Durchquerung von HNSW-Graphen zu optimieren, besteht darin, die Suche zu beenden, wenn die marginale Wahrscheinlichkeit, neue echte Nachbarn zu finden, nicht steigt. Aus diesem Grund haben wir in Elasticsearch 9.2 einen neuen Mechanismus zur vorzeitigen Beendigung eingeführt. Das stoppt den Suchvorgang, wenn der Besuch von Graphknoten nicht genug neue nächste Nachbarn für eine feste Anzahl hintereinander liefert.

In diesem Artikel erfahren Sie, wie wir den erwähnten Mechanismus zur vorzeitigen Beendigung in HNSW verbessert haben, damit er sich für verschiedene Datensätze und Datenverteilungen besser eignet.

Vorzeitige Beendigung in HNSW

In HNSW erfolgt die Suche durch das iterative Erweitern von Kandidatenknoten im Proximity-Graphen, wobei eine begrenzte Menge der bisher entdeckten nächsten Nachbarn gepflegt wird, bis entweder der gesamte Graph besucht wurde oder ein frühes Abbruchkriterium erfüllt ist.

Die vorzeitige Beendigung ist daher nicht unbedingt immer eine Optimierung, sondern Teil des Suchalgorithmus selbst. Der Moment, in dem wir beschließen aufzuhören, bestimmt das Gleichgewicht zwischen Effizienz und Abruf. In Elasticsearch gibt es bereits eine Reihe von Möglichkeiten, um Abfragen auf HNSW vorzeitig zu beenden:

• Eine festgelegte maximale Anzahl von Knoten wird besucht.
• Ein festgelegtes Zeitlimit ist erreicht.

Diese Regeln sind zwar einfach und vorhersehbar, verhalten sich aber weitgehend unabhängig von dem, was die Suche tatsächlich bewirkt. Außerdem werden sie hauptsächlich verwendet, um sicherzustellen, dass die Abfrage für den Endnutzer in angemessener Zeit abgeschlossen wird.

In einem früheren Blogbeitrag haben wir das Konzept der Redundanz im HNSW vorgestellt. Kurz gesagt, redundante Berechnungen treten auf, wenn HNSW weiterhin neue Kandidatenknoten auswertet, ohne dabei weitere nächste Nachbarn zu finden.

Geduld: Fortschritt statt Anstrengung messen

Der Begriff der Geduld stellt die frühe Beendigung auf Fortschritt statt Anstrengung um.

Anstatt zu fragen:

„Wie viele Schritte haben wir unternommen?“

Die neue Frage lautet:

„Wie viel Rechenleistung sind wir bereit zu verschwenden, bis wir die Hoffnung verlieren?“

Während der HNSW-Suche führt eine frühe Exploration in der Regel zu Spitzenverbesserungen der Gruppe der Top-k-Kandidaten. Während der ersten Schritte der HNSW-Graph-Exploration wird die Menge der Nachbarn kontinuierlich aktualisiert, da der Algorithmus immer nähere Nachbarn zum Abfragevektor entdeckt. Mit der Zeit werden diese Verbesserungen immer seltener, da die Suche konvergiert. Die auf Geduld basierende Beendigung überwacht dieses Muster und beendet die Suche, sobald die Verbesserungen für längere Zeit weniger werden.

In der Praxis berechnen wir beim Besuchen des HNSW-Graphen auch das Sättigungsverhältnis der Warteschlange, während wir Kandidatenknoten durchgehen. So wird der Prozentsatz der nächstgelegenen Nachbarn gemessen, die beim Besuch des letzten Graphknoten unverändert blieben (oder der Kehrwert der Anzahl der während der letzten Iteration eingeführten neuen Nachbarn). Wenn ein solches Verhältnis für zu viele aufeinanderfolgende Iterationen zu groß wird, hören wir auf, den Graphen zu besuchen.

Konzeptionell betrachtet Geduld die HNSW-Suche als einen Prozess mit abnehmendem Ertrag. Wenn sich die Erträge einpendeln, bringt die weitere Exploration des Graphen wenig Nutzen.

Dieses Framing ist wirkungsvoll, weil es die Beendigung direkt an beobachtbare Ergebnisse bindet, anstatt an willkürlich festgelegte Grenzwerte.

Der Vorteil dieser intelligenten Technik zur vorzeitigen Beendigung liegt darin, dass HNSW-Graph-Explorationen tendenziell eine geringere Anzahl von Graphknoten besuchen und dabei eine nahezu perfekte relative Abrufquote beibehalten.

Um dies zu visualisieren, können wir die Abrufquote pro besuchtem Knoten aufzeichnen, die wir mit der geduldsbasierten frühzeitigen Beendigung (gekennzeichnet als et=static) im Vergleich zum standardmäßigen HNSW-Verhalten (gekennzeichnet als et=no) bei einigen Datensätzen, FinancialQA und Quora, und Modellen, JinaV3 und E5-small, erhalten haben.

Statische Schwellenwerte und HNSW-Dynamik

In der Praxis wird dies in Elasticsearch mithilfe statischer Schwellenwerte umgesetzt. Ein Schwellenwert bezieht sich auf den Sättigungsschwellenwert, also das Sättigungsverhältnis, das wir für suboptimal halten. Der andere Schwellenwert bezieht sich auf die Anzahl aufeinanderfolgender Graphknoten, die wir zum Besuch zulassen, während wir dennoch eine suboptimale Warteschlangenauslastung erreichen, also der Geduldsschwellenwert.

Als wir diese Strategie zur vorzeitigen Beendigung in Elasticsearch 9.2 einführten, entschieden wir uns für konservative Standardeinstellungen, um den Abruf so weit wie möglich zu erhalten und gleichzeitig die Latenz und den Speicherverbrauch zu verbessern. Aus diesem Grund legten wir den Sättigungsschwellenwert auf 100 % und den Geduldsschwellenwert auf einen (begrenzten) Wert von 30 % des num_candidates in der KNN-Abfrage fest.

In vielen Szenarien erwiesen sich diese Einstellungen als gut geeignet, es kann aber sein, dass zwei Anfragen, die die gleiche Anzahl von Nachbarn anfordern, ein völlig unterschiedliches Konvergenzverhalten aufweisen. Einige Abfragen stoßen auf dichte lokale Nachbarschaften und sind schnell gesättigt, andere müssen lange, spärliche Pfade durchqueren, bevor sie wettbewerbsfähige Kandidaten finden. Letztgenanntes erwies sich als besonders schwierig effektiv zu handhaben.

Dabei fiel uns folgendes auf:

• Übermäßige Exploration bei einfachen Abfragen.
• Vorzeitige Beendigung bei schwierigen Abfragen.

Daher kamen wir zu dem Schluss, dass feste Schwellenwerte globale Annahmen über die Konvergenz kodieren, während wir HNSW besser an unterschiedliche Dynamiken anpassen könnten.

Die vorzeitige Beendigung von HNSW adaptiv gestalten

Ein adaptiver Ansatz zur vorzeitigen Beendigung geht dieses Problem aus einem anderen Blickwinkel an. Anstatt vordefinierte Stoppschwellenwerte durchzusetzen, leitet der Algorithmus aus den Suchdynamiken selbst ab, wann gestoppt werden soll.

Anstatt also das Verhältnis der Warteschlangensättigung zwischen zwei aufeinanderfolgenden Kandidaten zu vergleichen, beschlossen wir, sowohl eine direkt ausgeglichene $Entdeckungsrate d_{q,i} $ (wie viele neue Nachbarn für eine Abfrage q beim letzten Besuch i eingeführt wurden) sowie den fortlaufenden Mittelwert $\mu_{q,i}$ und die Standardabweichung $\sigma_{q,i}$ dieser Entdeckungsrate während des Graphbesuchs (unter Verwendung von Welfords Algorithmus) einzuführen. Diese Statistiken zur Entdeckungsrate werden pro Abfrage berechnet, sodass diese Informationen genutzt werden können, um für jede Abfrage unterschiedliche Geduldsgrade festzulegen.

Die zuvor statischen Schwellenwerte werden an die Statistik der Entdeckungsrate angepasst: Die Sättigungsschwelle wird zum gleitenden Mittelwert und mit der Standardabweichung addiert, während wir die Geduld anpassen und umgekehrt mit der Standardabweichung skalieren.

Die Regeln für die vorzeitige Beendigung bleiben gleich: Die Sättigung tritt ein, wenn die sofortige Entdeckungsrate niedriger ist als der adaptive Sättigungsgrenzwert. Der Graph-Besuch stoppt, wenn die Sättigung für eine Anzahl aufeinanderfolgender Kandidatenbesuche anhält, die größer ist als die adaptive Geduld.

So erhalten wir ein Verhalten, das nicht vom num_candidates-Parameter in der KNN-Abfrage abhängt (der immer als Standard gesetzt oder belassen werden kann, unabhängig von der vorzeitigen Beendigung) und sich dynamisch besser an jede Abfrage und Vektorverteilung anpasst.

Die Abrufquote pro besuchtem Knoten auf FinancialQA und Quora mit der adaptiven Strategie (gekennzeichnet als et=adaptive) ist höher als bei der statischen Strategie (et=static) und dem Standardverhalten von HNSW (et=no).

Die adaptive vorzeitige Beendigung ist in Elasticsearch 9.3 standardmäßig für HNSW-dichte Vektorfelder aktiviert (und kann schließlich über die gleiche Index-Level-Einstellung deaktiviert werden).

Integrationen konfigurieren Filebeat-Eingaben, um die Datenerfassung durchzuführen. Um Daten aus HTTP-APIs zu sammeln, haben wir oft HTTP-JSON-Eingaben verwendet. Jedoch können selbst grundlegende Listing-APIs in den Details stark voneinander abweichen, und das Modell der YAML-konfigurierten Transformationen der HTTP-JSON-Eingabe kann es umständlich und manchmal unmöglich machen, die erforderliche Sammlungslogik auszudrücken.

Common Expression Language (CEL)-Eingaben wurde eingeführt, um eine flexiblere Interaktion mit HTTP-APIs zu ermöglichen. CEL ist eine Sprache, die dafür entwickelt wurde, in Anwendungen eingebettet zu werden, die eine schnelle, sichere und erweiterbare Möglichkeit zur Darstellung von Bedingungen und Datentransformationen erfordern. CEL-Eingaben ermöglichen es einem Integration Builder, einen Ausdruck zu schreiben, der Einstellungen lesen, seinen eigenen Status verfolgen, Anfragen stellen, Reaktionen verarbeiten und letztendlich Ereignisse zurückgeben kann, die für den Ingest bereit sind.

In diesem Artikel werden wir uns ansehen, wie sich CEL von anderen Programmiersprachen unterscheidet, wie wir es für CEL-Eingaben erweitert haben und welche Flexibilität und Möglichkeiten es Ihnen bietet, um Ihre Datenerfassungslogik auszudrücken.

CEL und seine Funktionsweise als Eingabe

CEL ist eine Ausdruckssprache. Es enthält keine Anweisungen. Wenn Sie CEL schreiben, geben Sie dem Programm nicht durch Anweisungen vor, was es tun soll, sondern teilen ihm durch einen Ausdruck mit, welchen Wert es erzeugen soll. Jeder CEL-Ausdruck erzeugt einen Wert, und kleinere Ausdrücke können zu einem größeren Ausdruck kombiniert werden, um ein Ergebnis nach komplexeren Regeln zu erzeugen. Später werden wir sehen, wie man Ausdrücke für Dinge verwendet, die in anderen Sprachen möglicherweise mit Anweisungen geschrieben werden.

CEL ist bewusst eine nicht Turing-vollständige Sprache. Es erlaubt keine unbegrenzten Schleifen. Später werden wir sehen, wie man Listen und Maps mithilfe von Makros verarbeiten kann. Durch die Vermeidung unbegrenzter Schleifen garantiert die Sprache jedoch eine vorhersehbare und begrenzte Ausführungszeit für einzelne Ausdrücke.

Die CEL-Eingabe wird mit einem CEL-Programm (einem Ausdruck) und einem Anfangszustand konfiguriert. Der Zustand wird als Eingabe für das Programm bereitgestellt. Das Programm wird ausgewertet, um einen Ausgabezustand zu erzeugen. Wenn der Ausgabezustand eine Liste von Ereignissen enthält, werden diese entfernt und veröffentlicht. Der Rest des Ausgabezustands wird als Eingabe für die nächste Auswertung verwendet. Wenn der Ausgabezustand ein oder mehrere Ereignisse und den Flag want_more: trueenthält, wird die nächste Auswertung sofort durchgeführt; ansonsten schläft er für den Rest der konfigurierten Intervallzeit, bevor er weiterfährt. Hier ist ein vereinfachtes Diagramm des Kontrollflusses der Eingabe:

Die Ausgabe jeder Auswertung wird als Eingabe an die nächste Auswertung weitergeleitet, solange die Eingabe läuft. Ausgabedaten unter dem Schlüssel „cursor“ werden auf der Festplatte beibehalten und nach dem Neustart der Eingabe wieder geladen, aber der Rest des Zustands wird nicht über Neustarts hinweg beibehalten.

Die CEL-Sprache selbst hat begrenzte Funktionalität und vermeidet Nebenwirkungen, ist jedoch erweiterbar. Die cel-go-Implementierung fügt einige Funktionen hinzu, darunter optionale Syntax und Typen. Die Mito-Bibliothek baut auf cel-go auf und fügt weitere Funktionen hinzu, darunter die Möglichkeit, HTTP-Anfragen zu stellen. Die CEL-Eingabe verwendet die Mito-Version von CEL.

Zusammenarbeit mit Mito

Für den Aufbau oder die Fehlersuche einer Integration mit CEL-Eingaben ist es am wichtigsten zu verstehen, welchen Ausgangszustand Ihr CEL-Programm für einen gegebenen Eingabezustand erzeugt. Während der Entwicklung kann es umständlich sein, Ihr CEL-Programm über die Eingabe auszuführen, umgeben vom vollständigen Elastic Stack. Eine Möglichkeit, eine schnellere Feedback-Schleife zu erreichen, besteht darin, das Befehlszeilentool von Mito zu verwenden, mit dem Sie ein CEL-Programm direkt ausführen und den Ausgang sehen können, den es für eine bestimmte Eingabe erzeugt.

Mito ist in Go geschrieben und kann wie folgt installiert werden:

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

Wenn Sie ein CEL-Programm mit Mito ausführen, geben Sie ihm in der Regel zwei Dateien: eine JSON-Datei mit dem anfänglichen Eingabezustand und eine weitere Datei mit dem Quellcode Ihres CEL-Programms.

mito -data state.json src.cel

Um das Kopieren und Einfügen zu erleichtern, sind die Beispiele in diesem Artikel als einzelne Befehle geschrieben, bei denen die Shell temporäre Dateien spontan erstellt, indem der Inhalt jeder Datei in <(echo '...content...')eingeschlossen wird. Bei Ihren eigenen Entwicklungsprojekten wird Ihnen die Arbeit mit realen Dateien leichter fallen.

Problemdaten von GitHub abrufen

Das folgende Beispiel enthält ein vollständiges CEL-Programm, das Daten zu Problemen aus der GitHub-API abruft. Der anfängliche Eingabezustand enthält eine URL für den API-Endpunkt sowie einige Informationen darüber, wie die Paginierung gehandhabt werden soll. Das CEL-Programm verwendet die Daten im Eingabezustand, um eine Anfrage zu generieren. Es entschlüsselt die Antwort, erzeugt daraus Ereignisse und gibt sie als Teil seines Ausgabezustands zurück.

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,
          })
        )
      )
    )
  )
')

Die erste Auswertung liefert folgende Ausgabe:

{
  "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
}

Die Ereignisse werden entfernt, und wenn sie in der CEL-Eingabe ausgeführt werden, werden sie zur Ingestion veröffentlicht. Der Rest der Ausgabe wird dem nächsten CEL-Programmbewertungsvorgang als Eingabestand bereitgestellt.

Um zu verstehen, wie dieses CEL-Programm funktioniert, betrachten wir einige kleinere CEL-Beispiele und besprechen weitere Details zur Funktionsweise der CEL-Eingabe.

CEL-Grundlagen

In der CEL-Sprache gibt es keine Anweisungen, sondern nur Ausdrücke. Jeder erfolgreiche CEL-Ausdruck wird zu einem endgültigen Wert ausgewertet. Hier ist einer der kleinsten CEL-Ausdrücke, die Sie schreiben können, zusammen mit seiner Ausgabe:

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

"hello world"

Viele einfache Ausdrücke sind intuitiv. Mathematische Operationen werden nur bei Werten desselben Typs unterstützt (zum Beispiel int mit int), konvertieren Sie also Typen nach Bedarf (hier von int zu double):

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

10.5

In der CEL-Sprache gibt es keine Variablen, aber ein Ausdruck kann mit Hilfe des as-Makros von Mito benannt und in einem größeren Ausdruck verwendet werden. In diesem Beispiel wird der Ausdruck (1 + 1) zum Wert 2 ausgewertet, und .as(n, ...) gibt diesem Wert den Namen n zur Verwendung im Ausdruck "one plus one is "+string(n):

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

"one plus one is 2"

Es ist auch möglich, Informationen in einer Map zu sammeln und sie später im Ausdruck zu verwenden, wie hier mit with gezeigt wird:

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

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

Sehen Sie sich dieses Beispiel erneut an. Beachten Sie, dass der verschachtelte Teil – ({ "data": data, "size": size(data), }) – uns die Form des Endwertes vorgibt. Es ist eine Map mit den Schlüsseln "data" und "size". Die Werte für diese Schlüssel hängen von data ab, was durch den äußeren Teil des Ausdrucks definiert ist. Das Lesen von CEL-Ausdrücken von innen nach außen kann helfen, schnell zu erkennen, was sie zurückgeben.

CEL hat keine Kontrollflussanweisungen wie if, aber bedingte Verzweigungen können mit dem ternären Operator durchgeführt werden:

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

"few"

Unbeschränkte Schleifen und Rekursion werden nicht unterstützt, da CEL keine Turing-vollständige Sprache ist. Das macht die Ausführungszeit vorhersehbar und proportional zur Größe der Eingabedaten und zur Komplexität des Ausdrucks.

Obwohl unbeschränkte Schleifen in einzelnen CEL-Ausdrücken nicht möglich sind, können Sie Listen und Maps mit Makros wie mapbearbeiten:

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

[2, 4, 6]

In diesem Abschnitt haben wir Folgendes behandelt:

• Zeichenfolgen, Zahlen, Listen und Maps.
• Verkettung von Zeichenfolgen.
• Mathematische Operationen.
• Typumwandlung.
• Bedingungen.
• Benennung von Unterausdrücken.
• Verarbeiten von Sammlungen.

Als Nächstes sehen wir uns an, wie man HTTP-Anfragen stellt.

Anfragen

Mito erweitert CEL um die Möglichkeit, HTTP-Anfragen zu stellen:

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

"..."

Anfragen können explizit erstellt werden, bevor sie ausgeführt werden. Dadurch ist es möglich, verschiedene HTTP-Methoden zu verwenden und Header sowie einen Body hinzuzufügen.

In diesem Beispiel erstellen wir eine URL mit Hilfe von format_query, fügen der Anfrage einen Header hinzu und parsen den Response Body mit decode_json. Wenn die Option -log_requests angeboten wird, protokolliert Mito detaillierte Informationen im JSON-Format zu jeder Anfrage und Antwort.

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
}

Zustandsverwaltung und Evaluierungen

Nachdem wir nun behandelt haben, wie man Anfragen stellt und welche CEL-Grundlagen erforderlich sind, um den gewünschten Ausgabezustand zu erzeugen, schauen wir uns genauer an, was wir in den Ausgabezustand einfügen sollten und wie wir dadurch die spätere Verarbeitung steuern können.

Das CEL-Programm einer Integration muss sicherstellen, dass sein Ausgabezustand als Eingabe für die nächste Auswertung geeignet ist. Die Konfiguration legt den Ausgabezustand fest, und dieser sollte in der Ausgabe mit allen entsprechenden Änderungen wiederholt werden. Eine einfache Möglichkeit ist, state.with({ ... })zu verwenden, um die Zustands-Map mit einigen Überschreibungen zu wiederholen. Ein gängiges Muster für kleine Programme ist es, das gesamte Programm in state.with()einzuschließen, sodass die Zustandspropagation nicht in jedem Branch wiederholt werden muss, der Ausgabedaten erzeugt (zum Beispiel Erfolg, Fehler).

Wenn es Statuswerte gibt, die durch eine Auswertung initialisiert werden und nicht fest im anfänglichen Eingabezustand kodiert sind, muss das Programm nach einem vorhandenen Wert suchen, bevor es den anfänglichen Wert setzt. Dabei kann die Unterstützung für optionale Syntax und Typen helfen. Durch die Verwendung eines Fragezeichens vor dem Feldnamen in einem Map-Schlüssel wird der Zugriff optional: Er kann zu einem Wert aufgelöst werden oder auch nicht, aber weitere optionale Zugriffe sind möglich, und es ist einfach, einen Standardwert bereitzustellen, wenn kein Wert vorhanden ist.

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 }

In diesem Beispiel wird der aus dem Zustand gelesene Zählerwert in int umgewandelt, da alle Zahlen im Zustand als Gleitkommazahlen serialisiert werden, entsprechend den Konventionen von JSON und dem Number-Typ von JavaScript. Es sollte auch beachtet werden, dass "want_more": true hier von Mito beachtet wird, aber wenn es in der CEL-Eingabe ausgeführt wird, wird die Auswertung nur wiederholt, wenn die Ausgabe auch Ereignisse enthält.

Es ist eine Voraussetzung für CEL-Programme, die über die CEL-Eingabe ausgeführt werden, dass sie in ihrer Ausgabezuordnung einen "events"-Schlüssel zurückgeben. Sein Wert kann eine Liste von Ereignis-Maps, eine leere Liste oder ein einzelnes Ereignis-Map sein. Der Fall mit dem einzelnen Ereignis wird üblicherweise für Fehler verwendet. Das Ereignis wird von der Eingabe veröffentlicht, aber auch sein Wert wird geloggt, und wenn ein error.message Wert gesetzt wird, wird dieser verwendet, um den Fleet-Gesundheitsstatus der Integration zu aktualisieren. Wenn Ihr Programm ein einzelnes Ereignis erzeugt, das keinen Fehler verursacht, ist es am besten, es in eine Liste einzuschließen.

Werfen Sie noch einmal einen Blick auf die Ausgabe unseres GitHub-Problem-Programms von vorhin:

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

Das Programm hat seinen Zustand effektiv verwaltet, indem:

• Wiederholte Anfangszustandswerte in url, per_page, und max_pages.
• Hinzufügen eines Zustands, der über Neustarts hinweg erhalten bleiben soll, in cursor.page.
• Wiederkehrende Veranstaltungen, bereit zur Veröffentlichung in der events-Liste.
• Sofortige Neubewertung mit want_more: true angefordert.

Jetzt, da Sie den optionalen Zugriff und die Statusverwaltung sowie die CEL-Grundlagen und HTTP-Anfragen verstehen, sollte das vollständige GitHub-Problem-Programm lesbar sein. Versuchen Sie, es mit Mito auszuführen und mit einigen Änderungen zu experimentieren.

Überprüfung und Ressourcen

In diesem Artikel haben wir untersucht, was die CEL-Sprache ist und wie sie in der Mito-Bibliothek für die Nutzung in der CEL-Eingabe erweitert wurde. Wir haben die Flexibilität von CEL in einem Beispielprogramm gesehen, das Probleminformationen von der GitHub-API abruft, und sind alle Details durchgegangen, die zum Verständnis dieses Programms notwendig sind. Dazu gehören der Zugriff auf Einstellungen im Ausgabezustand, die Interaktion mit HTTP-APIs, die Rückgabe von Ereignissen zum Ingestieren und die Verwaltung des Zustands für spätere Programmausführungen.

Wenn Sie mehr erfahren und Integrationen mit CEL-Eingaben erstellen möchten, gibt es eine Reihe von Ressourcen, die Sie sich ansehen sollten:

• CEL-Eingabe – Filebeat-Dokumentation
• Mito-Dokumentation
• Common Expression Language - cel.dev Website
• Eine Integration erstellen – Elastic-Dokumentation

Die vielleicht wertvollste Ressource für die Entwicklung von Integrationen mit CEL-Eingaben ist der CEL-Code bestehender Elastic-Integrationen, der auf GitHub zu finden ist:

cel.yml.hbs Dateien im Elastic-Integrations-Repository – GitHub

1. Das neue Swift-Update ist da! Entwickler sind gespannt darauf, die neuen Features auszuprobieren.
2. Das neue Swift-Update ist da! Das neue Album erscheint nächsten Monat.

Mit diesem zusätzlichen Kontext sollten wir den Namen „Swift“ der richtigen Entität zuordnen können.

Im vorherigen Beitrag haben wir unsere Watchlist eingerichtet und die Entitäten mit zusätzlichem Kontext angereichert. Anhand unserer obigen Beispiele müssen wir mindestens die folgenden beiden Elemente in der Liste haben: Taylor Swift und Swift Programming Language. Wir haben auch besprochen, wie wir Entitätserwähnungen aus Text extrahieren. Beide Beispiele würden „Swift“ extrahieren. Mit diesen Zutaten, der angereicherten Watchlist und den extrahierten Entitäten, sind wir endlich bereit, den Star der Show vorzustellen: den Entitätsabgleich.

Denken Sie daran: Dies ist ein pädagogischer Prototyp, der entwickelt wurde, um Konzepte zum Abgleich von Entitäten zu vermitteln. Produktionssysteme könnten verschiedene große Sprachmodelle (LLMs), benutzerdefinierte Abgleichsregeln, spezialisierte Bewertungspipelines oder Ensemble-Ansätze verwenden, die mehrere Abgleichsstrategien kombinieren.

Das Problem: Warum der Abgleich schwierig ist

Die menschliche Sprache ist eine bemerkenswerte Sache. Eine ihrer interessantesten Eigenschaften ist ihre unendliche Kreativität. Wir können eine unendliche Anzahl neuer Sätze erzeugen und verstehen. Ist es dann verwunderlich, dass exakte Übereinstimmungen bei der Entitätsauflösung selten sind? Autoren bemühen sich, kreativ zu sein, wenn sie können. Es wäre ziemlich mühsam, wenn wir immer die vollständigen Namen schreiben und lesen müssten, wenn eine Entität erwähnt wird. Exakte Übereinstimmungen sind zwar einfach, aber die Realität sieht so aus, dass wir einen ausgefeilteren Ansatz zur Entitätsauflösung benötigen: einen, der robust genug ist, um zumindest einen Teil der grenzenlosen Kreativität menschlicher Autoren zu bewältigen. Deshalb unterteilen wir das Problem in zwei Schritte: Mit Elasticsearch werden plausible Kandidaten skaliert abgerufen, und anschließend wird mit einem LLM beurteilt, ob sich diese Kandidaten tatsächlich auf dieselbe reale Entität beziehen.

Die Lösung: Dreistufiger Abgleich mit transparenter LLM-Bewertung

Wir befinden uns mitten in einem Paradigmenwechsel in der Art und Weise, wie wir Computer nutzen. Genauso wie der Aufstieg des Internets uns vom lokalen Computing zu einem global vernetzten Netzwerk geführt hat, verändert die generative KI grundlegend die Art und Weise, wie Inhalte, Code und Informationen erstellt werden. Tatsächlich wurde der pädagogische Prototyp, der diese Serie begleitet, fast ausschließlich „Vibe-codiert“ unter Verwendung eines LLMs mit sorgfältiger Eingabe durch den Autor. Das soll nicht heißen, dass LLMs die Produktivität der menschlichen Sprache erreicht haben oder erreichen werden, aber es bedeutet, dass wir jetzt eine leistungsstarke Ressource haben, die uns bei der Entitätsauflösung unterstützt.

Ein häufiges Muster, das wir mit GenAI verwenden, ist Retrieval-Augmented Generation (RAG). Hier bedeutet Abrufen das Abrufen von Entitätskandidaten (nicht das Generieren von Antworten), und das LLM wird ausschließlich für die Bewertung und Erklärung von Übereinstimmungen verwendet. Obwohl wir ein LLM um Unterstützung bei der End-to-End-Lösung von Entitäten bitten könnten, ist das sowohl zeitlich als auch finanziell kostspielig. RAG hilft LLMs bei ihrer Arbeit, indem es effizientere Wege nutzt, um dem LLM Kontext bereitzustellen, und ermöglicht es dem LLM so, effizient bei der Entitätsauflösung zu helfen.

Für den Abrufteil von RAG greifen wir erneut auf Elasticsearch zurück. Zunächst ermitteln wir potenzielle Übereinstimmungen mithilfe einer Kombination aus exaktem Abgleich, Abgleich mit Aliasen und hybrider Suche, die Stichwort- und semantische Suche kombiniert. Sobald wir diese potenziellen Übereinstimmungen gefunden haben, schicken wir sie an ein LLM zur Bewertung. Das LLM fungiert als der letzte Übereinstimmungsbewerter. Wir lassen das LLM außerdem seine Argumentation erläutern, was ein wichtiges Unterscheidungsmerkmal zu anderen Entitätsauflösungssystemen darstellt. Ohne diese Erklärungen ist die Entitätsauflösung eine Blackbox; mit ihnen können wir selbst sehen, warum eine Übereinstimmung Sinn ergibt.

Schlüsselkonzepte: Drei-Schritte-Abgleich, hybride Suche und transparente LLM-Bewertung

Was ist der Drei-Schritte-Abgleich? Zu Beginn dieses Projekts haben wir die Hypothese aufgestellt, dass die semantische Suche ein entscheidender Bestandteil des Systems sein wird, aber nicht jeder Abgleich erfordert eine so ausgefeilte Suche. Um effizient Übereinstimmungen zu finden, gehen wir das Problem progressiv an. Zuerst überprüfen wir exakte Übereinstimmungen mit der Stichwortsuche. Wenn wir eine solche Übereinstimmung finden, ist unsere Arbeit getan und wir können weitermachen. Wenn der exakte Abgleich fehlschlägt, wenden wir uns dem Aliasabgleich zu. Im Prototyp wird der Einfachheit halber auch der Aliasabgleich mit Stichwörtern durchgeführt. In der Produktion können Sie diesen Schritt durch Normalisierung, Transliterationsregeln, Fuzzy Matching oder kuratierte Aliastabellen erweitern. Wenn wir in den ersten beiden Schritten immer noch keinen potenziellen Treffer gefunden haben, dann ist es an der Zeit, die semantische Suche über die hybride Suche von Elasticsearch mit Reciprocal Rank Fusion (RRF) einzuführen.

Was ist die hybride Suche? In Elasticsearch können wir die semantische Suche nutzen, um bedeutungsvolle Übereinstimmungen zu finden, die Kontext berücksichtigen. Elasticsearch wird häufig für Vektorsuche und hybride Abfrageverfahren eingesetzt. Semantische Ähnlichkeit ist sehr aussagekräftig, aber sie ist kein Ersatz für strukturiertes Filtern (z. B. nach Zeitspannen, Orten oder Identifikatoren) und ist oft unnötig, wenn eine exakte Übereinstimmung verfügbar ist. Elasticsearch hat sich mit der lexikalischen Suche einen Namen gemacht, die sich hervorragend für Aufgaben eignet, bei denen die semantische Suche nicht ausreicht. Um beide Ansätze voll auszuschöpfen, verwenden wir die lexikalische Suche neben der semantischen Suche in einer einzigen hybriden Abfrage. Anschließend führen wir die Ergebnisse zusammen, um mithilfe von RRF die wahrscheinlichsten Übereinstimmungen zu finden. Im Prototyp werden die oberen zwei Ergebnisse zu potenziellen Übereinstimmungen, die zur LLM-Bewertung gesendet werden können.

Warum die LLM-Bewertung? LLM-Bewertungen und -Erklärungen ermöglichen es unserem System, Ambiguität und Kontext transparent zu behandeln. Dies ist entscheidend für Fälle wie „der Präsident“, die sich auf mehrere Entitäten beziehen können, abhängig vom Kontext, aber es ermöglicht auch, dass Dinge wie Spitznamen und kulturelle Variationen gut im System funktionieren. Und schließlich müssen wir bei geschäftskritischen Aufgaben, wie der Identifizierung von Personen aus Sanktionslisten, wissen, warum ein Treffer akzeptiert wurde, um dem System vertrauen zu können. Entscheidend ist, dass das LLM nicht den gesamten Korpus durchsucht; es bewertet nur die kleine Anzahl von Kandidaten, die von Elasticsearch zurückgegeben werden.

Reale Ergebnisse: Übereinstimmung mit der LLM-Argumentation

Eine große Herausforderung bei jeder Aufgabe der natürlichen Sprachverarbeitung ist die Erstellung eines Referenzdokuments, eines „Lösungsschlüssels“, der uns mitteilt, was die zu erwartenden Ergebnisse sind. Ohne diese Grundlage ist es nahezu unmöglich zu beurteilen, wie gut ein System eine Aufgabe erfüllt. Doch die Erstellung eines solchen Dokuments kann ein mühsamer Prozess sein. Für den Prototyp zur Entitätsauflösung haben wir uns erneut an generative KI gewandt, um Unterstützung bei der Einrichtung von Testdaten zu erhalten.

Zunächst definierten wir mehrere Herausforderungstypen, wie Spitznamen und Transliteration, und baten dann das LLM, eine gestufte Sammlung von Datensätzen zu erstellen, die für das System zunehmend größer und anspruchsvoller werden sollte. Die Erstellung der Datensätze war weniger einfach, als man es sich erhoffen könnte. Das LLM hatte eine starke Neigung zum „Betrügen“, indem es zu einfach wurde, die richtige Antwort zu erhalten. Eine der Herausforderungen konzentrierte sich zum Beispiel auf den semantischen Kontext. Zu dieser Art gehörte beispielsweise die Auflösung von „russischer Autor“ zu „Leo Tolstoi“. Das LLM hat fälschlicherweise „russischer Autor“ als Alias für „Leo Tolstoi“ verwendet, was die Notwendigkeit einer Hybridsuche zum Finden der Übereinstimmung negierte.

Nach mehreren Refaktorierungen, um Probleme wie dieses zu beheben, hatten wir fünf Datensatzstufen, mit denen wir arbeiten konnten. Die Stufen 1–4 waren zunehmend größer und boten mehr Herausforderungstypen. Stufe 5 war der Datensatz der „ultimativen Herausforderung“, der aus den kniffligsten Beispielen aller Herausforderungstypen bestand. Sämtliche Testdaten sind im umfassenden Auswertungsverzeichnis verfügbar.

Zur Evaluierung unseres auf Eingabeaufforderungen basierenden Ansatzes zur Entitätsauflösung konzentrierten wir uns auf den Stufe-4-Datensatz. Ein wichtiger Hinweis ist, dass die Bewertung als kontrolliertes Experiment durchgeführt wurde, so dass wir uns auf die Qualität der Entitätsübereinstimmung konzentrieren konnten. Die Daten der Watchlist wurden vorab mit Kontext angereichert, und Entitäten wurden im Voraus aus dem Artikel extrahiert. Dadurch wurde sichergestellt, dass sich die Bewertung auf den Abgleich und nicht auf die Genauigkeit der Extraktion konzentrierte. Dies isoliert die Qualität der Übereinstimmungen; die Gesamtleistung hängt zusätzlich von der Trefferquote bei der Extraktion und der Qualität der Anreicherung ab.

Evaluationsdatensatz

Der Evaluierungsdatensatz der Stufe 4 bietet einen umfassenden Test der Leistungsfähigkeit des Systems:[1]

• Watchlist-Entitäten: 66 Entitäten unterschiedlichster Art (Personen, Organisationen, Standorte).
• Testartikel: 69 Artikel über reale Szenarien zur Auflösung von Entitäten.
• Erwartete Übereinstimmungen: 206 erwartete Entitätsübereinstimmungen in allen Artikeln.
• Herausforderungstypen: 15 verschiedene Herausforderungstypen, die verschiedene Aspekte der Entitätsauflösung prüfen.

Die in den Datensätzen enthaltenen Herausforderungstypen sind:

• Spitznamen: „Bob Smith“ → „Robert Smith“ (sieben Artikel).
• Titel und Ehrenbezeichnungen: „Dr. Sarah Williams“ → „Sarah Williams“ (fünf Artikel).
• Semantischer Kontext: „Russischer Autor“ → „Leo Tolstoi“ (acht Artikel).
• Mehrsprachige Namen: Umgang mit Namen in verschiedenen Skripten (sechs Artikel).
• Geschäftseinheiten: Variationen von Firmennamen (sieben Artikel).
• Referenzen von Führungskräften: „Microsoft CEO“ → „Satya Nadella“ (fünf Artikel).
• Politische Führungspersönlichkeiten: Titelbasierte Referenzen (fünf Artikel).
• Initialen: „J. Smith“ → „John Smith“ (drei Artikel).
• Varianten der Namensreihenfolge: Verschiedene Konventionen für die Namensreihenfolge (drei Artikel).
• Abgekürzte Namen: Teilweise Namensübereinstimmungen (drei Artikel).
• Namensaufteilung: Namen, die über Text verteilt sind (drei Artikel).
• Fehlende Leerzeichen/Bindestriche: Formatierungsabweichungen (zwei Artikel).
• Transliteration: Skriptübergreifender Namensabgleich (zwei Artikel).
• Kombinierte Herausforderungen: Mehrere Herausforderungen in einem Artikel (sechs Artikel).
• Komplexe Geschäftsbeziehungen: Hierarchische Geschäftsbeziehungen (fünf Artikel).

Mal sehen, wie die auf Eingabeaufforderungen basierende Entitätsauflösung funktioniert hat.

Gesamtleistung

Die Ergebnisse zeigen, dass die LLM-gestützte Übereinstimmungsbewertung vielversprechend ist, aber sie offenbaren auch ein erhebliches Zuverlässigkeitsproblem. Da jedes Kandidatenpaar vom LLM bewertet werden muss, können Fehler im strukturierten Ausgang die Akzeptanz und das Erinnern unterdrücken, selbst wenn der Abruf gut funktioniert.

Das Problem mit der Fehlerrate

Zur Erinnerung: Der erste Schritt im Prototyp besteht darin, mithilfe von Elasticsearch potenzielle Übereinstimmungspaare zu erstellen. Jede dieser potenziellen Übereinstimmungen muss vom LLM bewertet werden. Um all diese Übereinstimmungen effizient zu verarbeiten, fassen wir die LLM-Aufrufe in Batches zusammen. Dies reduziert die API-Kosten und die Latenzzeit, aber es besteht auch ein erhöhtes Risiko, dass der Ausgang fehlerhaftes JSON enthält. Mit zunehmender Batchgröße wird das JSON länger und komplexer, wodurch die Wahrscheinlichkeit steigt, dass der LLM ungültiges JSON generiert. Hier liegt der Ursprung der Fehlerquote von 30 %. In der Bewertung haben wir eine Batch-Größe von fünf Übereinstimmungen pro Anfrage verwendet. Selbst bei dieser konservativen Batchgröße beobachten wir immer noch JSON-Parsing-Fehler, welche die Auswertungsergebnisse erheblich verfälschen.

Nächstes Ziel: Optimierung der LLM-Integration

Nachdem wir nun Entitäten mithilfe semantischer Suche und LLM-Bewertung abgeglichen haben, verfügen wir über eine vollständige Entitätsauflösungspipeline. Dieser Ansatz führt jedoch einen neuen Ausfallmodus ein, wenn die Einschätzung des Modells richtig ist, sein Ausgang jedoch nicht nutzbar ist. Wir können die LLM-Integration im Hinblick auf höhere Zuverlässigkeit und Kosteneffizienz optimieren. Im nächsten Beitrag werden wir untersuchen, wie Sie Funktionsaufrufe für einen strukturierten Ausgang verwenden können, der garantierte Struktur- und Typsicherheit bietet und gleichzeitig Fehler und Kosten reduziert.

Probieren Sie es selbst aus

Möchten Sie den Entitätsabgleich in Aktion sehen? Schauen Sie sich das Entitätsabgleich-Notizbuch für eine vollständige Anleitung mit realen Implementierungen, detaillierten Erklärungen und praktischen Beispielen an. Das Notizbuch zeigt Ihnen genau, wie Sie Entitäten mithilfe der dreistufigen Suche, der hybriden Suche mit RRF und der LLM-gestützten Bewertung mit Schlussfolgerungen abgleichen.

Denken Sie daran: Dies ist ein pädagogischer Prototyp, der entwickelt wurde, um die Konzepte zu vermitteln. Bei der Entwicklung von Produktionssystemen sollten zusätzliche Faktoren wie Modellauswahl, Kostenoptimierung, Latenzanforderungen, Qualitätsvalidierung, Fehlerbehandlung und Überwachung berücksichtigt werden, die in diesem lernorientierten Prototyp nicht behandelt werden.

Anmerkungen

1. Diese Datensätze sind synthetisch und für Bildungszwecke konzipiert; sie nähern sich realen Herausforderungen an, sind aber nicht repräsentativ für eine einzelne Produktionsdomäne.

Unsere Benchmarks auf einem 20-Millionen-Dokumentenkorpus zeigen, dass Elasticsearch bei der gefilterten Vektorsuche bis zu 8-mal mehr Durchsatz als OpenSearch liefert und gleichzeitig höhere Recall@100 in den getesteten Konfigurationen erzielt. Kontextgestaltung erfordert mehr als nur einen schnellen Vektorabruf. Teams benötigen außerdem starke Relevanzkontrollen, wie hybride Such- und Filterfunktionen, eine einfache Bedienung und eine vorhersehbare Leistung bei der Iteration von Workflows. Da die Agenten jedoch oft mehrmals pro Anfrage Abfrage-, Auswertungs- und erneute Abfrage-Schleifen durchlaufen, wirkt sich die Latenz bei der Datenabfrage multiplikativ aus, sodass Verbesserungen in diesem Bereich direkt zu einer besseren Reaktionsgeschwindigkeit über den gesamten Prozess hinweg und zu geringeren Kosten führen.

Für das Kontext-Engineering ist der Abruf kein einmaliger Schritt. Agenten und Anwendungen führen wiederholt Schleifen aus, wie z. B. Abrufen → Begründung → Abrufen, um Abfragen zu verfeinern, Fakten zu überprüfen, einen fundierten Kontext zusammenzustellen und Aufgaben zu erledigen. Dieses Muster ist typisch für agentenbasierte Workflows und iterative Retrieval Augmented Generation (RAG). Da der Abruf pro Nutzeranfrage mehrfach aufgerufen werden kann, verzögert sich die Reaktion und/oder erhöht die Infrastrukturkosten.

Warum ist die Leistung der Vektorsuche so wichtig?

Stellen Sie sich vor, ein Verkäufer beantwortet die Frage: „Ich brauche einen Handgepäck-Rucksack unter 60 €, in den ein 15-Zoll-Laptop passt, der wasserabweisend ist und bis Freitag geliefert werden kann.“

In der Produktion gibt der Assistent nur selten eine Vektorabfrage aus und hält dann an. Es führt einen Abrufzyklus aus, um den richtigen Kontext aufzubauen, und jeder Schritt wird typischerweise durch Filter eingeschränkt, wie Verfügbarkeit, Region, Versandversprechen, Markenregeln und Richtlinienberechtigung.

Schritt 1: Absicht interpretieren und in Einschränkungen übersetzen.

Der Agent wandelt die Anfrage in strukturierte Filter und eine semantische Abfrage um, wie zum Beispiel:

• Filterkriterien: Auf Lager, lieferbar an die Postleitzahl des Nutzers, Lieferung bis Freitag, Preis unter 60 €, gültiges Angebot
• Vektorabfrage: „Bordrucksack für 15-Zoll-Laptop, wasserabweisend“

Schritt 2: Kandidaten abrufen und anschließend verfeinern.

Es wiederholt oft das Abrufen mit Variationen, um gute Übereinstimmungen nicht zu verpassen:

• „Reiserucksack in Kabinengröße mit Laptophülle“
• „wasserabweisender Pendlerrucksack 15 Zoll“
• „ leichtgewichtiger Kabinenrucksack “

Für jede Abfrage werden die gleichen Berechtigungsfilter verwendet, da das Abrufen irrelevanter oder nicht verfügbarer Elemente eine Verschwendung von Kontext darstellt.

Schritt 3: Erweitern, um Details zu bestätigen und das Risiko zu reduzieren.

Der Agent ruft dann erneut ab, um wichtige Attribute zu überprüfen, die die endgültige Antwort beeinflussen:

• Angaben zu Material und Wasserfestigkeit
• Abmessungen und Passform des Laptopfachs
• Rückgabebestimmungen oder Garantiebeschränkungen
• Alternative Optionen, wenn der Bestand gering ist

Dies ist mehrstufiges Kontext-Engineering: Abrufen, schlussfolgern, abrufen, zusammenstellen.

Warum Latenz und Recall für das Kontext-Engineering wichtig sind

Diese Interaktionen können Dutzende gefilterter Abrufaufrufe pro Nutzersitzung umfassen. Das macht die Latenz pro Anruf zu einem direkten Multiplikator der End-to-End-Reaktionszeit, und eine niedrige Rückrufrate erzwingt zusätzliche Wiederholungsversuche oder führt dazu, dass der Agent geeignete Elemente übersieht, was die Antwortqualität verschlechtert.

Fazit: In kontextbasierten Systemen ist die gefilterte approximative Suche nach nächsten Nachbarn (ANN) keine einfache Nachschlageoperation. Sie ist ein wiederholter Vorgang unter Einschränkungen, sodass die Leistung der Vektorsuche sofort in Latenz, Durchsatz und Kosten angezeigt wird, selbst wenn das Large Language Model (LLM) die sichtbarste Komponente ist.

Benchmarking

Ergebnisse

In Diagramm 2 stellt jeder Punkt eine Testkonfiguration dar. Die besten Ergebnisse werden oben links angezeigt, was eine höhere Erinnerungsrate bei geringerer Latenz bedeutet. Die Ergebnisse von Elasticsearch liegen durchweg näher am oberen linken Rand als die von OpenSearch, was auf eine höhere Geschwindigkeit und Genauigkeit bei gleicher Arbeitslast hinweist.

Einige wichtige Einblicke

• s_n_r_value: Kurzschrift für size_numCandidates_rescoreOversample (k und numCandidates in diesen Tests gleich numCandidates gesetzt), zum Beispiel 100_500_1 bedeutet size=100, numCandidates=500 und k=500, rescore oversample=1
• Erinnerung: Gemessener Recall@100 für diese Konfiguration
• Durchschnittslatenz (ms): Durchschnittliche End-to-End-Latenz pro Abfrage
• Durchsatz: Abfragen pro Sekunde
• Erinnerung %: Relative Verbesserung der Trefferquote von Elasticsearch gegenüber OpenSearch (Elasticsearch minus OpenSearch) / OpenSearch
• Latenz Xs: Die durchschnittliche Latenz von OpenSearch dividiert durch die durchschnittliche Latenz von Elasticsearch
• Durchsatz Xs: Elasticsearch-Durchsatz geteilt durch den OpenSearch-Durchsatz

Zum Beispiel beträgt OpenSearch bei 100_9000_1 im Durchschnitt 687 Millisekunden pro Abruf gegenüber 90 Millisekunden bei Elasticsearch, und in einer 10-Schritte-Abrufschleife entspricht das etwa 10 × (687 - 90) = sechs Sekunden zusätzlicher Wartezeit.

Die vollständigen Ergebnisse ansehen.

Methodik

Wir verwendeten Python, um die Anfragen zu senden und die Antwortzeiten sowie weitere Statistiken zu verfolgen. Wir haben die folgenden Anfragen an die Engines gesendet. Bedenken Sie, dass die Leistungsfähigkeit jeder Vektorsuchmaschine davon abhängt, wie Sie ihre Kernparameter einstellen: wie viele Kandidaten berücksichtigt werden sollen, wie aggressiv die Neubewertung erfolgen soll und wie viel Kontext zurückgegeben werden soll. Diese Einstellungen wirken sich direkt sowohl auf die Trefferquote (die Wahrscheinlichkeit, die richtige Antwort zu finden) als auch auf die Latenz (wie schnell Sie Ergebnisse erzielen) aus.

In unseren Benchmarks verwendeten wir die gleichen Kandidaten-, Rescore- und Ergebnisgrößeneinstellungen, die man typischerweise in einer agentenbasierten Abrufschleife anpasst, und wir maßen, wie Elasticsearch unter dieser Arbeitslast abschneidet. Anschließend führten wir OpenSearch mit denselben Einstellungen als Referenz durch.

OpenSearch

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

• "size": <RESULT_SIZE>: Anzahl der an den Client zurückgegebenen Treffer. In diesem Benchmark ist die Ergebnisgröße 100, um Recall@100 zu berechnen.
• "k": <NUMBER_OF_CANDIDATES>: Die Anzahl der nächstgelegenen Nachbarkandidaten.
• "ef_search": <NUMBER_OF_CANDIDATES>: Die Anzahl der zu untersuchenden Vektoren.
• "oversample_factor": <OVERSAMPLE>: Wie viele Kandidatenvektoren werden abgerufen, bevor das Rescoring erfolgt.

Elasticsearch

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

• "size": <RESULT_SIZE>: Anzahl der an den Client zurückgegebenen Treffer. In diesem Benchmark ist die Ergebnisgröße 100, um Recall@100 zu berechnen.
• "k": <NUMBER_OF_CANDIDATES>: Anzahl der nächsten Nachbarn, die von jedem Shard zurückgegeben werden sollen.
• "num_candidates": <NUMBER_OF_CANDIDATES>: Anzahl der zu berücksichtigenden nächsten Nachbarn pro Shard bei der knn -Suche.
• "oversample": <OVERSAMPLE>: Wie viele Kandidatenvektoren werden abgerufen, bevor das Rescoring erfolgt.

Beispiel

Knn Die Abfrage (100_500_1) würde wie folgt lauten:

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"
    ]
  }
}

Die vollständige Konfiguration, zusammen mit Terraform-Skripten, Kubernetes-Manifesten und dem Benchmarking-Code, ist in diesem Repository im Ordner es-9.3-vs-os-3.5-vector-search verfügbar.

Cluster-Einrichtung

Wir führten unsere Tests auf sechs e2-Standard-16-Cloud-Servern durch, jeder mit 16 vCPUs und 64 GB RAM. Auf jedem Server haben wir 15 vCPUs und 56 GB RAM jedem Kubernetes-Pod zugewiesen, der den Suchmaschinen-Node ausführt, wobei 28 GB für den JVM-Heap reserviert waren.

Die Cluster liefen mit Elasticsearch 9.3.0 und OpenSearch 3.5.0 (Lucene 10.3.2). Da beide Systeme in diesem Benchmark die gleiche Lucene-Version verwenden, können die beobachteten Unterschiede im Durchsatz und in der Latenz nicht allein Lucene zugeschrieben werden, sondern spiegeln vielmehr Unterschiede in der Art und Weise wider, wie die einzelnen Engines die gefilterte k-nächste-Nachbarn-Suche (kNN) und das Rescoring integrieren und ausführen. Wir haben einen einzelnen Index mit drei Primäre Shards und einem Replikat verwendet (also insgesamt 6 Shards, einer pro Node).

Wir verwendeten außerdem einen separaten Server in derselben Region, um den Benchmark-Client auszuführen und Zeitstatistiken zu erfassen.

Der Datensatz

Für diesen Benchmark verwendeten wir einen umfangreichen Katalog-Embedding-Datensatz im E-Commerce-Stil mit 20 Millionen Dokumenten, der die reale gefilterte Vektorsuche in großem Umfang widerspiegeln soll.

Jedes Dokument stellt einen Katalogartikel dar und beinhaltet:

• Eine 128-dimensionale Dichtevektoreinbettung, die für das ungefähre kNN-Abrufverfahren verwendet wird.
• Strukturierte Metadatenfelder, die zur Filterung verwendet werden (zum Beispiel die Gültigkeit und Verfügbarkeit von Artikeln sowie andere Katalogbeschränkungen), die das gemeinsame Produktionsmuster ermöglichen, die nächstgelegenen Nachbarn abzurufen, jedoch nur innerhalb einer zulässigen Teilmenge.

Wir haben diesen Datensatz gewählt, weil er die Kernleistungsherausforderung widerspiegelt, die wir bei agentenbasierten und RAG-Systemen im Produktiveinsatz beobachten: Vektorähnlichkeit allein reicht nicht aus, die Suche wird häufig durch Filter eingeschränkt, und das System muss unter diesen Einschränkungen eine hohe Trefferquote bei gleichzeitig niedriger Latenz pflegen. Im Vergleich zu kleineren QA-Datensätzen spiegelt ein Korpus von 20 Millionen Dokumenten auch besser den Umfang und den Kandidatendruck wider, denen gefilterte ANN-Systeme in der Praxis ausgesetzt sind.

Fazit

In modernen KI-Architekturen, insbesondere solchen, die auf Kontext-Engineering aufbauen, ist die Geschwindigkeit der Vektorsuche kein unbedeutendes Implementierungsdetail. Sie ist ein Multiplikator. Wenn Agenten und Workflows durch Abrufen → Verarbeiten → Abrufen iterieren, beeinflusst die Abrufleistung direkt die End-to-End-Latenz, den Durchsatz und die Qualität des in das Modell eingespeisten Kontexts.

In unseren Benchmarks lieferte Elasticsearch konstant einen höheren Abruf bei geringerer Latenz als OpenSearch in Szenarien, in denen die Korrektheit vom Abruf des richtigen Dokuments und nicht nur eines ähnlichen Vektors abhängt. An einem kontrollierten Datensatz ist der Unterschied deutlich, und in der Produktion akkumulieren sich diese Gewinne über große Volumina von Abrufaufrufen, wodurch die Reaktionsfähigkeit verbessert, der Kapazitätsspielraum erhöht und die Infrastrukturkosten reduziert werden.

Weitere Lektüre

1. Was ist Context Engineering?
2. Die Entwicklung der hybriden Suche und des Kontext-Engineerings
3. Der Einfluss der Relevanz auf das Kontext-Engineering für KI-Agenten

Die Familie umfasst zwei Modelle:

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

Diese Modelle sind das erfolgreiche Ergebnis eines innovativen neuen Trainingsverfahrens zum Einbetten von Modellen. Beide übertreffen um ein Vielfaches größere Modelle. Sie sparen Speicherplatz und Rechenressourcen und reagieren schneller auf Anfragen.

Das jina-embeddings-v5-text-small-Modell verfügt über 677 Millionen Parameter, unterstützt ein 32.768-Token-Eingangskontextfenster und erzeugt standardmäßig 1.024-Dimensionseinbettungen.

jina-embeddings-v5-text-nano ist nur etwa ein Drittel so groß wie sein Pendant, mit 239 Mio. Parametern und einem Eingangskontextfenster mit 8192 Token, was schlanke Einbettungen mit 768 Dimensionen ergibt.

Diese beiden Modelle sind hinsichtlich der Gesamtleistung des MMTEB (Multilingual MTEB)-Benchmarks die besten verfügbaren. Unter den Modellen mit weniger als 500 Millionen Parametern ist jina-embeddings-v5-text-nano trotz weniger als 250 Millionen Parametern der beste Performer, und das jina-embeddings-v5-text-small-Modell ist führend unter mehrsprachigen Einbettungsmodellen mit weniger als 750 Millionen Parametern.

Diese Modelle sind über den Elastic Inference Service (EIS), über eine Online-API und für lokales Hosting verfügbar. Anweisungen zum Zugriff auf jina-embeddings-v5-text-Modelle finden Sie im Abschnitt „Erste Schritte“ weiter unten.

Einbettungsmodelle und semantisches Indexieren erhöhen die Genauigkeit von Suchalgorithmen drastisch, haben aber auch eine Vielzahl anderer Einsatzmöglichkeiten für Aufgaben, die semantische Ähnlichkeit und Bedeutungsextraktion betreffen, zum Beispiel:

• Doppelte Texte finden.
• Paraphrasen und Übersetzungen erkennen.
• Themenfindung.
• Empfehlungssysteme.
• Stimmungs- und Absichtsanalyse.
• Spamfilterung.
• Und vieles mehr.

Features

Diese neue Modellfamilie verfügt über eine Reihe von Features zur Verbesserung der Relevanz und Kostensenkung.

Aufgabenoptimierung

Wir haben die jina-embeddings-v5-text-Modelle für vier breitgefächerte Aufgabentypen optimiert:

Die Optimierung für eine Aufgabe bedeutet in der Regel, dass man bei einer anderen Aufgabe Kompromisse eingehen muss. Daher bieten die meisten Einbettungsmodelle nur für eine Art von Aufgabe eine wettbewerbsfähige Leistung. jina-embeddings-v5-text-Modelle können sich hingegen auf alle vier Bereiche spezialisieren, ohne Kompromisse einzugehen, indem sie aufgabenspezifische Low-Rank Adaptation (LoRA)-Adapter trainieren.

LoRA-Adapter sind gewissermaßen Plugins für KI-Modelle, die ihr Verhalten drastisch ändern, während sie die Gesamtgröße nur geringfügig erhöhen. Anstatt für jede Aufgabe ein komplettes Modell mit Hunderten Millionen Parametern zu verwenden, ermöglicht die jina-embeddings-v5-text-Modellfamilie die Nutzung eines einzigen Modells mit einem kompakten LoRA-Adapter für jede Aufgabe. Dadurch werden Speicher, Speicherplatz und Inferenzkosten gespart.

Kürzen von Einbettungen

Wir haben die jina-embeddings-v5-text-Modelle mit Matryoshka Representation Learning trainiert, das es Ihnen ermöglicht, Ihre Einbettungen auf kleinere Größen zu reduzieren, ohne die Qualität wesentlich zu beeinträchtigen.

Standardmäßig erzeugt jina-embeddings-v5-text-small Einbettungsvektoren in 1.024 Dimensionen, die jeweils durch eine 16-Bit-Zahl dargestellt werden, sodass jede Einbettung 2 KB groß ist. Für eine große Sammlung von Dokumenten kann dies eine Menge Daten zum Speichern bedeuten, und die Suche in einer Vektordatenbank voller Einbettungen fällt proportional zur Größe der Datenbank sowie zur Anzahl der Dimensionen aus, die jeder gespeicherte Vektor enthält.

Man kann aber einfach die Größe der Einbettungen halbieren (512 der 1.024 Dimensionen weglassen) und so den Speicherplatz halbieren und gleichzeitig die Suchgeschwindigkeit verdoppeln. Dies hat Auswirkungen auf die Leistung. Das Entfernen von Informationen verringert die Präzision. Aber wie der Graph unten zeigt, verringert sich die Leistung selbst dann nur geringfügig, wenn Sie die Hälfte der Einbettung weglassen:

Solange Ihre Einbettungen mindestens 256 Dimensionen haben, sollte der Präzisionsverlust relativ gering bleiben. Unterhalb dieses Niveaus nehmen Relevanz und Genauigkeit jedoch schnell ab.

Das Kürzen von Einbettungen auf diese Weise ermöglicht es Nutzern, ihre eigenen Kompromisse zwischen Genauigkeit und Rechenkosten zu bestimmen. Es bietet Ihnen die nötigen Tools, um große Effizienzgewinne und erhebliche Kosteneinsparungen aus Ihrer Such-KI zu erzielen.

Robuste Quantisierung

Quantisierung ist eine weitere Möglichkeit, um die Größe von Einbettungen zu reduzieren. Anstatt einen Teil jeder Einbettung zu entfernen, reduziert die Quantisierung die Präzision der Zahlen in der Einbettung. Die jina-embeddings-v5-text-Modelle generieren Einbettungen mit 16-Bit-Zahlen, doch diese Zahlen können abgerundet werden, wodurch ihre Präzision und die Anzahl der Bits, die zu ihrer Speicherung nötig sind, reduziert werden. Im Extremfall können wir jede Zahl auf ein Bit (0 oder 1) reduzieren und die standardmäßigen 1.024-dimensionalen Einbettungen von jina-embeddings-v5-textvon 2 Kilobyte auf 128 Byte komprimieren, was einer Reduzierung um 94 % durch alleinige binäre Quantisierung entspricht. Genau wie bei der Kürzung führt dies zu großen Einsparungen bei Speicherplatz und Rechenkosten. Jedoch sorgt die Quantisierung, ähnlich wie eine Kürzung, dafür, dass Einbettungen weniger genau ausfallen.

Wir haben die jina-embeddings-v5-text -Modelle darauf trainiert, mit Elasticsearchs Better Binary Quantization zu arbeiten, indem wir diesen Genauigkeitsverlust minimieren. Benchmark-Tests binarisierter Einbettungen aus diesen Modellen zeigen eine Leistung, die fast der ihrer nicht-binarisierten Äquivalente entspricht. Im technischen Bericht finden Sie detaillierte Ablationsstudien zur Binarisierungsleistung.

Mehrsprachige Leistung

Viele Einbettungsmodelle sind mehrsprachig, weil sie auf Materialien trainiert wurden, die eine große Anzahl von Sprachen enthalten. Das bedeutet jedoch nicht, dass sie in allen unterstützten Sprachen gleich gut funktionieren.

Wir haben 211 Sprachen im MMTEB-Mehrsprachen-Benchmark identifiziert und sie getrennt, um unsere Modelle mit ähnlichen Modellen auf Sprachbasis vergleichen zu können. Die folgende Abbildung fasst unsere Ergebnisse als Heatmap zusammen. Jedes Feld stellt eine Sprache dar (identifiziert durch ihren ISO-639-Code). Je grüner es ist, desto besser hat das Modell im Vergleich zum Durchschnitt ähnlicher Modelle abgeschnitten:

Obwohl die Genauigkeit zwischen Sprachen variiert, sind die jina-embeddings-v5-text-Modelle in den meisten Sprachen weltweit auf dem neuesten Stand der Technik oder nahezu so weit.

Details zur mehrsprachigen Leistung finden Sie im technischen Bericht jina-embeddings-v5-text.

Jina in Elastic: Hochmoderne native KI für die Suche

Mit jina-embeddings-v5-text-Modellen auf EIS können Sie leistungsstarke, mehrsprachige Einbettungsmodelle nativ in Elasticsearch ausführen, mit vollständig verwalteter, GPU-beschleunigter Inferenz und ohne Infrastruktur zur Bereitstellung oder Skalierung. jina-embeddings-v5-text-Modelle erweitern den wachsenden EIS-Modellkatalog mit kompakten, mehrsprachigen Modellen, die von den neuesten Entwicklungen im Bereich der KI angetrieben werden. Diese Modelle weisen eine herausragende Leistung bei der Informationswiedergewinnung und Standard-Datenanalyse-Benchmarks auf und bieten eine unübertroffene, weltweite Unterstützung in mehreren Sprachen.

Mit zwei Modellen in deutlich unterschiedlichen Größen können die Nutzer entscheiden, welches am besten zu ihren Anwendungsbereichen und ihrem Budget passt. Darüber hinaus bieten jina-embeddings-v5-text -Modelle mit robusten Einbettungen, die auch bei Verkleinerung der Größe oder Quantisierung auf eine geringere Genauigkeit leistungsfähig bleiben, Möglichkeiten für weitere konkrete Einsparungen bei Speicher- und Rechenkosten sowie bei der Verarbeitungslatenz.

Mit der jina-embeddings-v5-text-Familie, Jina Reranker und Elastics schneller Vektor- und BM25-Suche haben Nutzer nun Zugang zu einer End-to-End-Hybridsuche von Elastic. Wenn Sie die relevantesten Ergebnisse benötigen – sei es für Retrieval Augmented Generation (RAG) Pipelines, Suchanwendungen oder Datenanalysen – bietet Elastic mit den Such-KI-Modellen von Jina solide und kosteneffiziente Qualität.

Erste Schritte

Die jina-embeddings-v5-text-Modelle sind vollständig in EIS integriert und können durch Einstellen des type Felds für semantic_text verwendet werden, um Ihren Index zu erstellen und das Modell (jina-embeddings-v5-text-small oder jina-embeddings-v5-text-nano) im inference_id Feld zu spezifizieren, wie an diesem Beispiel zu sehen ist:

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 wählt während des Indexierens und des Abrufs automatisch den entsprechenden LoRA-Adapter aus. Die Einbettungsdimensionen (siehe Abschnitt „Kürzen von Einbettungen“ oben) können festgelegt werden, wenn ein benutzerdefinierter Inferenz-Endpoint erstellt wird.

In der Elasticsearch-Dokumentation finden Sie weitere Informationen zur Nutzung vonjina-embeddings-v5-text Modellen.

Weitere Informationen

Um mehr über jina-embeddings-v5-text-Modelle zu erfahren, lesen Sie die Versionshinweise im Jina AI-Blog und den technischen Bericht mit detaillierteren technischen Informationen zur Leistung und zum innovativen neuen Trainingsverfahren von Jina AI. Informationen zum lokalen Herunterladen und Betrieb dieser Modelle finden Sie auf der Seite der jina-embeddings-v5-text-Sammlung auf Hugging Face.

Die Jina AI-Modelle stehen unter einer CC-BY-NC-4.0-Lizenz zur Verfügung. Sie können sie also kostenlos herunterladen und ausprobieren. Für die kommerzielle Nutzung wenden Sie sich bitte an den Elastic-Vertrieb.

In diesem Artikel erfahren Sie, wie Sie den Parameter „Mindestscore“ verwenden können, um die Genauigkeit Ihrer semantischen Suchergebnisse zu erhöhen. Wenn Sie die in diesem Blogbeitrag bereitgestellten Beispiele testen möchten, besuchen Sie das zugehörige Jupyter-Notizbuch.

Hintergrund: Präzision und Abruf

In der Suchrelevanz sind Präzision und Recall Schlüsselkonzepte. Lesern, die noch nicht mit diesen Themen vertraut sind, wird dringend empfohlen, sich darüber zu informieren. Nachfolgend eine Zusammenfassung.

• Genauigkeit: Der Anteil der zurückgegebenen Suchergebnisse, die für den Nutzer relevant sind.
• Recall: Der Anteil aller relevanten Dokumente im Korpus, die in den Suchergebnissen enthalten sind.

Oder, mit anderen Worten, Präzision gibt nur relevante Ergebnisse zurück; und Recall gibt alle relevanten Ergebnisse zurück. Wie Sie sich vorstellen können, handelt es sich dabei oft um konkurrierende Anforderungen. Die semantische Suche weist tendenziell eine sehr hohe Trefferquote auf, hat aber mitunter Schwierigkeiten mit der Präzision. Lesen Sie weiter, um zu erfahren, wie Sie diese Eigenschaft umgehen können.

Einführung des Mindestscore-Parameters

Der ‘min_score’-Parameter ermöglicht es uns, die Präzision zu verbessern, indem ein Mindestscore festgelegt wird, der das Ergebnisset durch Entfernen aller Treffer mit einem Score unter dem definierten Schwellenwert kürzt. Nachfolgend ein einfaches Beispiel:

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

Normalisierung des Scores

Die Festlegung eines Mindestscores ist schön und gut, aber nicht alle semantischen Modelle liefern einen Score, die sich für einen statischen Schwellenwert eignet. ELSER gibt beispielsweise einen unbegrenzten Score zurück. Einige Scores des dichten Modells sind eng gruppiert und nur im Zusammenhang mit der spezifischen Anfrage sinnvoll.

Für die meisten Fälle der semantischen Suche empfehlen wir, vor der Anwendung von „min_score“ einen Normalisierungsansatz zu verwenden. Durch die Normalisierung wird sichergestellt, dass der Dokumentenscore innerhalb eines definierten Intervalls liegt. Elasticsearch-Retriever bieten zwei solcher Normalisierer, ‘l2_norm’ und ‘minmax’. Am häufigsten wird die „minmax“-Methode verwendet, da sie leicht verständlich ist und in vielen Szenarien gut funktioniert. Wichtige Eigenschaften von ‘minmax’ umfassen:

• Die Dokumentenscores liegen im Bereich von 0 bis 1.
• Das Dokument mit der höchsten Punktzahl erhält immer den Score 1.
• Das Dokument mit der niedrigsten Punktzahl erhält immer den Score 0.
  • Dies kann die Eignung für die Stichwortsuche beeinträchtigen. Weitere Informationen finden Sie im Abschnitt „Hybride Suche“.

Im Folgenden ein Beispiel für eine normalisierte semantische Abfrage mit min_score. Die Größe des Ranking-Fensters wurde auf 500 erhöht, damit wir eine längere Liste von Suchergebnissen zurückgeben können, angefangen bei 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"
                }
              }
            }
          }
        }
      ]
    }
  }
}

Die Größe wurde auf einen höheren Wert als in der Produktion üblich eingestellt. So können wir die Qualität der Suchergebnisse inspizieren und die Ergebnisse optimieren.

Hybridsuche mit dem linearen Retriever

Für die Hybridsuche ist der einfachste Ansatz, alle Scores zu normalisieren, Gewichte zuzuweisen und einen Mindestscore anzuwenden. Beachten Sie, dass Sie durch die Wahl von Gewichtungen mit einer Summe von 1 den Gesamtscore innerhalb eines Bereichs von 0 bis 1 halten. Dadurch lassen sich die Endergebnisse leicht nachvollziehen und die Melodie min_score stimmen. Nachfolgend ein Beispiel:

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"
                }
              }
            }
          }
        }
      ]
    }
  }
}

Hybridsuche mit RRF

Mit BM25 steuern wir die Präzision oft durch andere Mittel, wie die Verwendung des AND-Operators oder minimum_should_match. Darüber hinaus werden Abfragen, die aus einzelnen, präzisen und seltenen Begriffen bestehen, natürlicherweise zu Suchergebnissen mit wenigen Suchergebnissen führen, die oft alle hochrelevant sind. Dies kann zu Folgendem führen:

• Ergebnisse, die weiter hinten im Ergebnis stehen, erhalten im BM25-Retriever einen niedrigen normalisierten Score, selbst wenn der absolute BM25-Score nahe an den Treffern mit den höchsten Scores liegt.
• Wenn ein sehr niedriger BM25-Score zum semantischen Score hinzugefügt wird, kann die Summe als semantischer Score approximiert werden.
• Das Fehlen eines BM25-Score-Beitrags kann dazu führen, dass das Dokument von min_score threshold verworfen wird.

Als Lösung können wir stattdessen die reziproke Rangfusion (RRF) verwenden, um BM25- und semantische Ergebnisse zu kombinieren. RRF umgeht die Herausforderung, Scores verschiedener Suchalgorithmen zu vergleichen, indem es sich stattdessen auf die Position in jedem Ergebnis auf konzentriert. In diesem Szenario wird die min_score nur auf den semantischen Retriever angewendet.

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"
              }
            }
          }
        }
      ]
    }
  }
}

Fazit

Mit min_score haben wir gezeigt, wie wir die Anzahl der Fehlalarme in unseren Ergebnissätzen reduzieren können, die durch den hohen Recall semantischer Suchalgorithmen verursacht werden. Um mehr über Retriever zu erfahren, siehe bitte diesen Blogbeitrag und die Elasticsearch-Dokumentation.

Abhängigkeitsmanagement bei Elastic

Bei Elastic müssen wir Hunderte oder sogar Tausende von Repositorys, sowohl privat als auch öffentlich, verwalten. Wird eine kritische CVE entdeckt, benötigen wir umgehend Antworten und Maßnahmen: Welche Repositorys sind anfällig? Wie schnell können wir sie patchen? Neben der Sicherheit stellen sich auch Produktivitätsfragen: Wie können wir die Veröffentlichung einer neuen Paketversion schnell über alle darauf angewiesenen Repositorys verbreiten, ohne zu viel Zeit mit manuellen Aufgaben zu verbringen?

Der ursprüngliche Auslöser für die Suche nach Möglichkeiten für das Abhängigkeitsmanagement war die Notwendigkeit, eine sichere Grundlage mit automatisierten Updates zur Reduzierung von CVEs zu schaffen. Nachdem wir verschiedene Lösungen zum Abhängigkeitsmanagement sorgfältig geprüft hatten, begannen wir zunächst mit der Arbeit an einer selbstgehosteten Infrastruktur. Wir nutzten unseren eigenen Kubernetes-Cluster genutzt, um Mend Renovate Community Self-Hosted auszuführen. Die Idee war, eine Abhängigkeitsmanagement-Plattform bereitzustellen, auf die unsere Nutzer im Self-Service-Modus zugreifen könnten.

Das erste Experiment war erfolgreich, sodass immer mehr Teams begannen, unsere Plattform zu integrieren und sie im täglichen Lebenszyklus ihrer Repositorys für Updates und CVE-Patches zu nutzen. Das geschah so schnell, dass wir bald die Grenze unserer selbstgehosteten Installation erreichten.

Die Herausforderung: Wie können wir eine Plattform zur Verwaltung von Abhängigkeiten in einem großen Unternehmen mit einer großen Anzahl von Repositorys skalieren?

Unsere Plattform für das Abhängigkeitsmanagement verarbeitete ein Repository nach dem anderen, und das sequentielle Verarbeitungsmodell konnte aufgrund der großen Anzahl von Repositorys, die wir besitzen, nicht Schritt halten. Wir hatten bereits festgestellt, dass das Problem daran lag, dass eine einzige Instanz unseres Abhängigkeitsverwaltungstools unsere lange und ständig wachsende Liste von Repositorys verarbeiten sollte. Die Repositorys warteten in einer Warteschlange, manchmal stundenlang. Mehr als 50 % unserer Repositorys wurden noch nicht einmal täglich verarbeitet. Das bedeutet, dass bei über 50 % unserer Repositorys zwischen den Scans mehr als 24 Stunden vergingen.

Große Repositorys erzeugten aufgrund ihrer umfangreichen Codebasen und ihrer zahlreichen offenen PRs größere Engpässe. GitHub-Webhook-Ereignisse unterbrachen den Ablauf. Die automatische Zusammenführung wurde unzuverlässig, da die Scan-Zeitpunkte unvorhersehbar waren. Wir hatten unseren Nutzern ein Versprechen für die Häufigkeit der Scans gegeben, konnten es aber nicht einhalten.

Die Entscheidung für die Eigenentwicklung: Erfüllung des individuellen Bedarfs für Skalierung und Sicherheit bei Elastic

Während wir auch kommerzielle Optionen in Betracht zogen, darunter die Renovate Self-Hosted Enterprise Edition von Mend, hatten wir intern bei Elastic einige wichtige Initiativen in der Entwicklung.

Unsere Entscheidung, eine interne Plattform zu entwickeln, beruhte auf der Erkenntnis, dass nur eine gut angepasste Lösung die spezifischen, nicht verhandelbaren Anforderungen von Elastic erfüllen kann:

1. Investitionen in unsere interne Entwicklerplattform: Zu dieser Zeit hatten wir bereits damit begonnen, stark in unsere hausinterne Entwicklerplattform zu investieren. Wir diskutierten und entwarfen Möglichkeiten dazu, wie jeder einzelne unserer Dienste darin Platz finden könnte. Wir wollten eigene Regeln und Praktiken für unsere Abhängigkeitsverwaltungsplattform testen. Außerdem waren neue Richtlinien zu erwarten, und wir wollten die Plattform im Vorfeld der Ereignisse entwickeln.
2. Native Integration und Workflow-Anpassung: Wir benötigten eine unkomplizierte Integration mit unseren internen Tools und internen Prozessen. Zum Beispiel wollten wir die Konfiguration als Code mit unserem Servicekatalog (Backstage) zentralisieren. Wir haben spezifische Anforderungen an die Nutzung von Backstage, mit denen wir unsere Plattform kompatibel machen wollten. Obwohl es möglich wäre, die Renovate Self-Hosted-APIs zusammen mit unserer Backstage-Automatisierung zu nutzen, würde dies unsere internen Prozesse nicht vollständig abdecken.
3. Elastic-spezifische Defense-in-Depth-Sicherheit: Unsere strengen Anforderungen an die Sicherheitskonformität erforderten besondere Sicherheitsmechanismen, die auf unser Ökosystem abgestimmt sind. Wir versuchten, unsere Nutzung von „nicht-menschlichen Identitäten“ besser zu sichern. Die Art und Weise, wie diese Zugriffssicherung funktionierte, bedeutete, dass die nicht standardmäßigen Authentifizierungsmethoden für GitHub mit einem Standardtool, das diese interne Implementierung nicht unterstützte, nicht funktionierten. Unser Workflow umfasste die Implementierung eines geheimen Verschlüsselungsmusters für über- und untergeordnete Workflows sowie die Verwendung temporärer, einmalig verwendbarer GitHub-Token. Die Eigenentwicklung war die einzig praktikable Möglichkeit, diese individuellen Sicherheitsebenen zu integrieren und die Angriffsfläche in unserer komplexen Multi-Cloud-Umgebung zu minimieren.

Die Lösung: Eine Workflow-Orchestrierung für das Abhängigkeitsmanagement

Unsere Lösung basiert auf der Tatsache, dass wir auf dem bereits von uns verwendeten Abhängigkeitsverwaltungstool aufbauen wollten, statt es zu ersetzen und nach anderen Lösungen zu suchen. Es hatte sein Potenzial bereits gezeigt, und seine Flexibilität ist für die unterschiedlichen Anforderungen innerhalb unseres Unternehmens sehr wichtig. Wir zogen verschiedene Lösungen in Betracht, und was uns bei unserer Entscheidung half, waren die großen und manchmal speziellen Bedarfe, die wir abdecken müssen. Wir entschieden uns dafür, eine zuverlässige und skalierbare Plattform für das Abhängigkeitsmanagement aufzubauen, bei der jedes Repository einzeln verarbeitet wird, um Engpässe zu beseitigen und uns für Wachstum zu rüsten.

Wir gestalteten die Plattform nach drei Kernprinzipien:

1. Parallelverarbeitung

Jedes Repository erhält seine eigene Umgebung für das Abhängigkeitsmanagement. Es gibt keine Warteschlangen mehr. Unsere Parallelität ist nur durch die Anzahl der Ressourcen begrenzt, die wir einsetzen. Wir haben außerdem eine intelligente verteilte Planung implementiert, um eine Quotenbegrenzung durch GitHub zu vermeiden.

2. Selbstbedienbarkeit

Wir nutzen unseren Servicekatalog (Backstage), um jedes neue Repository automatisch zu integrieren und zu verwalten. Wir verwenden unsere eigene Ressourcendefinition, um dem Nutzer die Möglichkeit zu geben, auszuwählen, wie oft ein Repository verarbeitet werden soll, wie viele Ressourcen er seinen Zeitplänen zuweisen möchte und ob er die Verarbeitung aus irgendeinem Grund deaktivieren oder wieder aktivieren möchte. Wir planen, auf diese Weise weitere Optionen hinzuzufügen, sobald sich die Bedürfnisse unserer Nutzer weiterentwickeln und sie mit der neuen Installation vertrauter werden.

3. Reduzierter Geheimnisbereich und Namespace-Isolation

Um die Sicherheit zu erhöhen, versorgen wir unsere Pods zur Verwaltung von Abhängigkeiten mit ephemeren GitHub-Token, die zu Beginn jedes Workflows generiert werden. Darüber hinaus isolieren wir unsere Workloads in spezifischen Namespaces, sodass ihnen nur die notwendigen Geheimnisse bereitgestellt werden. Wir steuern mithilfe von Kubernetes RBAC, auf welche Geheimnisse die einzelnen Workflows des Abhängigkeitsmanagements zugreifen dürfen. Wir verwenden auch eine Verschlüsselung, um das GitHub-Token vom übergeordneten Workflow an die untergeordneten Workflows zu übertragen.

Wir bauten unsere Plattform mit Kubernetes neu auf und nutzten dabei die Leistungsfähigkeit von Kubernetes; Argo Workflows treibt die Logik unserer Prozesse an, und Renovate CLI ist für das Scannen und Verarbeiten eines Repositorys nach dem anderen eingerichtet.

Das Schöne: Wir verwenden praxiserprobte Open-Source-Projekte auf originelle Weise, bieten neue Arbeitsbeispiele für all diese Projekte, erhöhen gleichzeitig die Entwicklungsgeschwindigkeit und konsolidieren die CVE-Reduzierung für unsere Teams.

Architektur des Abhängigkeitsmanagements: Vier Microservices

Die Plattform besteht aus vier maßgeschneiderten Komponenten:

Workflows Operator (Go/Kubebuilder)

Ein Kubernetes-Operator, der den Workflow-Lebenszyklus über drei benutzerdefinierte Ressourcendefinitionen (CRDs) verwaltet:

• RepoConfig-CRD: Eine einzige Wahrheitsquelle für die Konfiguration des Repositorys.

So wird RepoConfig im Operator definiert:

// 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"`
}

Und so würde eine Instanz von RepoConfig aussehen:

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

• Parent-CRD: Verwaltet CronWorkflows für geplante Scans.

Innerhalb der Abstimmungsschleife des übergeordneten Controllers sorgen wir dafür, dass die Workflow-Einstellungen erstellt und auf dem neuesten Stand gehalten oder bei Bedarf sogar gelöscht werden.

Zunächst werden einige global konfigurierte Einstellungen für Workflows abgerufen:

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",
	}

Das stellt sicher, dass eine Mutex-Configmap auf dem neuesten Stand ist, um zu verhindern, dass ähnliche Workflows gleichzeitig ausgeführt werden:

	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)

Anschließend wird ein Workflow-Manager erstellt, der als Struktur die CronWorkflows und die Workflow-Vorlagen erstellt oder aktualisiert:

	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

• Child-CRD: Verwaltet WorkflowTemplates mit Ressourcen pro Repository.

Der untergeordnete Controller hat eine ähnliche Abgleichsaufgabe wie der übergeordnete Controller, ist aber diesmal für Workflow-Vorlagen im untergeordneten Namespace verantwortlich, die von den Workflows des übergeordneten Controllers ausgelöst werden.

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
}

Das Multi-Controller-Muster bietet eine klare Trennung: Der RepoConfig-Controller übernimmt das Onboarding/Offboarding, der Parent-Controller verwaltet die Planung und der Child-Controller kümmert sich um die Ausführungsvorlagen.

GitHub Events Gateway (Go)

Ein sicherer Webhook-Proxy, der GitHub-Webhooks empfängt, Signaturen verifiziert, nach Organisation/Repository filtert und an Argo Events weiterleitet. Wir haben 10 verschiedene Sensoren entwickelt, die auf Interaktionen im Abhängigkeits-Dashboard, PR-Ereignisse und Paketaktualisierungen reagieren.

Dieses Gateway ermöglicht die Integration mit GitHub-Apps durch:

• Überprüfung eingehender GitHub-Webhook-Signaturen auf Sicherheit.
• Weiterleitung gültiger Ereignisse an die Argo Events EventSource mit allen relevanten Headern und der Authentifizierung.
• Wir konfigurieren außerdem ein authSecret auf der EventSource und stellen dieses als Bearer-Header in weitergeleiteten Anfragen bereit.
• Bereitstellung von Protokollierung, Metriken und Wiederholungslogik.

Es führt verschiedene Überprüfungen für jede GitHub-Ereignisanfrage durch.

Es stellt sicher, dass bestimmte HTTP-Attribute vorhanden sind:

// 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
}

Gleichzeitig validiert es auch die Signatur jeder Anfrage und deren 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
}

Schließlich wird je nach Ereignistyp an Argo Events weitergeleitet:

	// 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

Auf der Seite von Argo Events überwachen 10 Sensoren den Argo Events EventBus auf neue Ereignisse:

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

Anschließend wendet das Skript die Logik jedes Sensors an:

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-Synchronisierer (Go)

Dies fragt unseren Service-Katalog (Backstage) nach Repository Real Resource Entities ab, wandelt sie in RepoConfig-CRDs um und hält die Plattform mit den Konfigurationsänderungen synchron. Änderungen werden innerhalb von drei Minuten wirksam.

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)

Schließlich werden diese Daten in RepoConfig-Instanzen eingeschrieben.

Workflows-Basis (Gemischt: JavaScript, Go, Helm)

Die Basisschicht enthält Helm-Charts, JavaScript-Konfigurationen, einen Go-Wrapper für die Renovate CLI mit Verschlüsselungsunterstützung und einen benutzerdefinierten APK-Indexer für Alpine-Pakete.

Self-Service-Konfiguration

Teams konfigurieren ihre Repositories deklarativ über Backstage:

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

Ressourcengruppen verteilen CPU und Speicher basierend auf der Größe des Repositorys:

• KLEIN: 500 m CPU, 1 Gi Arbeitsspeicher.
• MITTEL: 1000 m CPU, 2 Gi Arbeitsspeicher.
• GROSS: 2000 m CPU, 4 Gi Arbeitsspeicher.

Die Konfiguration ist versionskontrolliert, überprüfbar und wird automatisch angewendet.

Das Parent-Child-Muster

Das Ausführungsmodell verwendet ein Parent-Child-Workflow-Muster:

• Übergeordneter Workflow: Der Lightweight CronWorkflow läuft planmäßig. Verschlüsselt Geheimnisse, bestimmt, ob ein Scan ausgeführt werden soll, und gibt die Konfiguration an die untergeordneten Workflows weiter.
• Untergeordneter Workflow: Ein flüchtiger Pod, auf dem Renovate CLI läuft. Weist Ressourcen dynamisch zu, entschlüsselt Geheimnisse isoliert und beendet sich nach Abschluss.

Diese Trennung bietet Sicherheit (Geheimnisse werden auf der Ebene der übergeordneten Prozesse verschlüsselt), Ressourcenoptimierung (übergeordnete Prozesse verbrauchen nur minimale Ressourcen) und Skalierbarkeit (untergeordnete Prozesse laufen parallel).

Die Ergebnisse

Leistungsveränderung

• Vorher: Es wurde jeweils nur ein Repository bearbeitet, manche Repositorys wurden unter Umständen sogar einen Tag oder länger nicht verarbeitet, insgesamt wurden weniger als 1.000 Scans pro Tag durchgeführt.
• Nachher: Mehr als 100 gleichzeitige Scans, in der Regel 8.000 Scans und bis zu 10.000 aufgezeichnete Scans pro Tag, begrenzt nur durch die Menge an Ressourcen, die wir verbrauchen möchten, und unseren Umgang mit den Quotenbegrenzungen von GitHub.

Kosteneffizienz

So seltsam es auch klingen mag, mit 8.000 Pods pro Tag erzielt man das gleiche Ergebnis viel günstiger als mit einem einzigen, lange laufenden Pod, der versucht, das gleiche Ergebnis zu erzielen.

In der vorherigen Konfiguration betrieben wir eine einzelne Instanz, die an einem guten Tag 500 bis 600 Scans durchführte. Da gleichzeitig verschiedene Arten von Repositorys auf demselben Pod ausgeführt werden sollten, mussten wir den Pod auf die größten Repositorys abstimmen. Diese Größe wäre mit 8 CPUs für den Pod und 16 GB Speicher deutlich größer als unser aktuelles, besonders großes Angebot.

Um die aktuelle Tagesproduktion zu erreichen, müsste der einzelne Pod 12 Tage laufen. Vergleicht man also die Kosten für einen einzelnen Pod, der 12 Tage lang läuft, mit den Kosten für 8.000 Pods unserer Größe „MEDIUM“, die täglich im Einsatz sind, so ist unser neues Design bei gleicher Scan-Ausgabe weitaus effizienter:

Allerdings sollten wir berücksichtigen, dass unsere Standardeinstellung für unsere Workloads auf „KLEIN“ gesetzt ist, wobei die große Mehrheit erfolgreich mit 0,5 CPU und 1 GB RAM läuft und nur wenige auf „MITTEL“ oder „GROSS“ umgestellt werden müssen. Mal sehen, was passiert, wenn 60 % unserer Arbeitslasten auf „KLEIN“, 30 % auf „MITTEL“ und 10 % auf „GROSS“ laufen, was den tatsächlichen Anforderungen näherkommt.

Wir können sehen, dass wir bei gleicher Ausgabe in unserem aktuellen Setup weitaus kosteneffizienter sind.

Verbesserte Sicherheit

• Kurzlebige GitHub-Token (Minuten der Exposition im Vergleich zu Tagen).
• Namespace-Isolation mit rollenbasierten Zugriffskontrollgrenzen (RBAC).
• Geheime Verschlüsselung inaktiver Daten in übergeordneten Workflows.
• Kein direkter Tresorzugriff mehr.

Vorhersagbare Leistung

Mit einer garantierten Scanfrequenz können wir endlich Service Level Objectives (SLOs) festlegen. Die automatische Zusammenführung funktioniert zuverlässig. Die Teams vertrauen darauf, dass die Plattform das Versprochene auch tatsächlich liefert.

Wichtige architektonische Entscheidungen

Zu den wichtigsten Designentscheidungen, die die Gestaltung der Plattform geprägt haben, gehören die Folgenden.

• Warum über- und untergeordnete Workflows?

Wir haben dieses Muster übernommen, um eine tiefgreifende Verteidigungsstrategie durchzusetzen. Indem wir wertvolle Zugangsdaten (wie GitHub-App-Geheimnisse) auf einen dedizierten, gesperrten Namespace beschränken, nutzen wir RBAC, um sicherzustellen, dass flüchtige Ausführungspods keinen beliebigen Zugriff auf sensible Daten haben. Jüngste Sicherheitslücken in Lieferketten (zum Beispiel die „Shai Hulud“ Continuous Integration/Continuous Delivery [CI/CD]-Angriffe) haben gezeigt, wie wichtig es ist, Laufzeitumgebungen, die dynamisches Scripting ausführen, vom Anmeldeinformationsspeicher zu isolieren.

Gleichzeitig ermöglicht diese Entkopplung eine granulare Ressourcenoptimierung. Die „übergeordneten“ Workflows fungieren als leichtgewichtige Orchestrierer mit minimalem Ressourcenbedarf, während die „untergeordneten“ Workflows die rechenintensive Abhängigkeitsanalyse übernehmen. Diese Trennung vereinfacht das Lifecycle-Management, da wir auf jede Ebene eine eigene Abstimmungslogik anwenden können, sodass die Nutzer die Kontrolle über die Ausführungsparameter haben (untergeordnet), während wir die administrative Kontrolle über die Planungs- und Sicherheitsinfrastruktur (übergeordnet) behalten.

• Warum Selbstbedienbarkeit?

Die Beseitigung unseres Teams als Engpass bei der Repository-Konfiguration war eine entscheidende Voraussetzung. Unser Ziel war es, eine skalierbare Self-Service-Plattform zu entwickeln, die vielfältige Anwendungsfälle unterstützen kann. Wir haben erkannt, dass es angesichts der schieren Menge an Repositorys nicht nachhaltig ist, als Gatekeeper für jede Konfigurationsänderung zu agieren. Stattdessen verfolgten wir eine Philosophie der Befähigung: Wir stellten die „Schienen“ (Infrastruktur und Leitplanken) bereit, während wir die Nutzer in die Lage versetzten, die „Züge“ (Ausführung und Anpassung) zu fahren. Wir sind überzeugt, dass dieser Wandel hin zur Teamautonomie die Produktivität erheblich steigert, da Nutzer das System nun an ihre spezifischen operativen Bedürfnisse anpassen können.

• Warum das Kubernetes-Operator-Muster?

Wie oben bereits erwähnt, wollten wir grundsätzlich sicherstellen, dass die Plattform vollkommen selbstbedienbar sein würde. Wir benötigten einen automatisierten Mechanismus, um die Absicht des Nutzers zu erfassen (z. B. das Umschalten von Scans, das Anpassen der Planungsfrequenz oder das Optimieren der Laufzeitressourcengrenzen) und diese Änderungen sofort an die zugrunde liegenden Workflows weiterzugeben. In Erwartung zukünftiger Anforderungen sollte das System zudem leicht erweiterbar sein.

Um dies zu erreichen, entwickelten wir einen individuellen Dependency Management Kubernetes Operator. Mithilfe von CRDs als Schnittstelle für die Konfiguration etablierten wir eine Kubernetes-native Abgleichschleife. Dieser Operator überwacht kontinuierlich den vom Nutzer definierten gewünschten Zustand und orchestriert automatisch die notwendigen Aktualisierungen der Workflow-Infrastruktur. Das gewährleistet einen ereignisgesteuerten, nahtlosen Betrieb, bei dem die Plattformlogik die gesamte Komplexität hinter den Kulissen bewältigt.

• Warum ein GitHub Events Gateway entwickeln?

Die Einführung einer ereignisgesteuerten Architektur (EDA) war für die Reaktionsfähigkeit der Plattform unerlässlich. Zwar bot CronWorkflows einen zuverlässigen Basisplan, aber wir brauchten auch die Flexibilität zur Bewältigung von Ad-hoc-Ausführungen, wie etwa das manuelle Auslösen von Scans durch Nutzer über das Dashboard. Dafür benötigten wir ein dediziertes Ingestionsgateway, um die Integrität der Nutzlasten zu validieren und Anfragen intelligent weiterzuleiten.

Wir evaluierten bestehende Lösungen, darunter die native GitHub EventSource für Argo, aber stellten erhebliche Risiken hinsichtlich des operativen Aufwands und der strengen GitHub API-Kontingente (z. B. Webhook-Limits pro Repository) fest. Deshalb entwickelten wir ein benutzerdefiniertes Gateway, um unsere Infrastruktur von diesen Einschränkungen zu entkoppeln.

Entscheidend war, dass dieses Gateway während unserer Migration als strategischer Verkehrskontrollpunkt diente. Es fungierte als Switch und ermöglichte uns die Durchführung eines schrittweisen, granularen Rollouts (Verkehrsverlagerung) vom Altsystem zur neuen Infrastruktur. Dies stellte sicher, dass die Einbindung von Tausenden von Repositorys ein kontrollierter, risikofreier Prozess und kein abrupter „Big Bang“-Wechsel war.

Erkenntnisse

Einiges, was wir dabei gelernt haben, entspricht dem Elastic Source Code:

1. Der Kunde steht im Mittelpunkt: Plattformen sind für Nutzer gebaut. Deshalb sind die Bedürfnisse der Nutzer an erste Stelle zu setzen. Die Plattform wird damit zu einer effizient gestalteten Infrastruktur mit Anwendungen, die Reibungsverluste für die Nutzer reduzieren, das Skalieren der Plattform vereinfachen und die Akzeptanz erhöhen.
2. Raum und Zeit: Manchmal gerät man beim Weg des geringsten Widerstands in Treibsand. Wir haben zunächst versucht, das bestehende sequenzielle Verarbeitungsmodell zu optimieren, aber das löste unsere Probleme nicht, sondern ergab nur noch mehr Komplexität und lose Enden. Die mutige Entscheidung, die Plattform mit paralleler Verarbeitung neu zu gestalten, erforderte erhebliche Vorarbeiten. Letztendlich ebnete es jedoch den Weg für ein nachhaltiges Plattformwachstum und beseitigte praktisch die mühsame tägliche Verwaltungsarbeit.
3. IT-Abhängigkeiten: Eine Plattform kann nicht isoliert betrieben werden; ihr Erfolg hängt davon ab, wie gut sie sich in das breitere Ökosystem integriert. In unserem Fall war die Integration mit Backstage entscheidend, da es als Wahrheitsquelle für ein nahtloses Service-Onboarding dient. In ähnlicher Weise ermöglichte uns die Verbindung zu Artifactory, private Paket-Updates effizient zu verwalten, und das sind nur einige der wichtigsten Integrationen.
4. Fortschritt und EINFACHE Perfektion: Während der gesamten Implementierung stellten wir unsere ursprünglichen Annahmen immer wieder auf den Prüfstand und passten uns an neue Hindernisse an, sobald sie auftauchten. Anstatt uns durch Perfektionismus lähmen zu lassen, wählten wir einen iterativen Ansatz, gingen Herausforderungen nacheinander an und richteten unsere Migrationsstrategie an den realen Gegebenheiten aus.

Was kommt als Nächstes?

Die Bereitstellung der Plattform ermöglicht uns sinnvollere Arbeit, die uns wiederum helfen wird, das Nutzererlebnis und die Effizienz unserer Plattform zu verbessern. Einige Beispiele sind:

• Ausweitung und Absicherung der Einführung einer automatischen Zusammenführung

Die Auto-Merge-Funktion beschleunigt die Teamgeschwindigkeit erheblich, da sie mühsame manuelle Aufgaben eliminiert. Allerdings müssen wir sicherstellen, dass strenge Schutzmaßnahmen vorhanden sind, um zu gewährleisten, dass diese erhöhte Geschwindigkeit nicht auf Kosten der Sicherheit geht.

• Verbesserung der Beobachtbarkeit rund um die Endnutzererfahrung

Ein zentrales Anliegen unserer Roadmap ist die Verbesserung der Beobachtbarkeit, nicht nur auf Plattformebene, sondern auch speziell aus der Perspektive des Endnutzers. Die Erfassung von Infrastrukturkennzahlen ist zwar einfach, aber für ein Verständnis der tatsächlichen Nutzererfahrung sind tiefere Einblicke erforderlich. Wir arbeiten daran, zentrale, benutzerzentrierte Leistungskennzahlen (KPIs) zu definieren, damit unsere Telemetrie Reibungspunkte und Leistungsprobleme erkennen kann, bevor sie zu Nutzerbeschwerden eskalieren.

• Beseitigung von Hindernissen für eine breitere Akzeptanz

Mit Blick in die Zukunft liegt unser Schwerpunkt darauf, alle Barrieren zu identifizieren und zu beseitigen, die die Einführung der Plattform behindern. Ob dies die Entwicklung neuer Integrationen oder die Bereitstellung spezifischer Funktionssets erfordert – wir setzen uns für datengetriebene Planung ein. Wir haben erfolgreich eine skalierbare Plattform aufgebaut; unser Fokus verlagert sich nun darauf, ihr Potenzial zu maximieren.

Im Ganzen betrachtet

Das Projekt zu den Workflows für das Abhängigkeitsmanagement demonstriert ein allgemeineres Prinzip: Wenn Sie Open-Source-Tools über deren Standard-Bereitstellungsmodell hinaus skalieren müssen, sind Kubernetes-native Muster eine Möglichkeit dafür.

Indem Sie Folgendes annehmen:

• CRDs für die Konfiguration.
• Operatoren für das Lifecycle-Management.
• Ereignisgesteuerte Architektur für Reaktionsfähigkeit
• GitOps für das Deployment.

Wir haben eine Orchestrierung entwickelt, die unabhängig von der Zahl der verwalteten Repositorys skaliert. Die Leistung beim Scannen eines Repositorys ist gleich, egal ob wir 100 oder 1.000 verwalten.

Wenn ein kritisches CVE angekündigt wird, haben wir jetzt Antworten innerhalb von Minuten, nicht Stunden. Das ist der Unterschied zwischen einem Engpass und einem Wettbewerbsvorteil.

Danksagungen

Diese Plattform basiert auf exzellenten Open-Source-Tools:

• Kubebuilder: Das Open Source-Framework, das wir genutzt haben, um unsere Kubernetes-Operatoren zu starten, die unsere Arbeitsabläufe initialisieren und orchestrieren. [1][2]
• Backstage: Das Open-Source-Framework, auf dem wir unseren Servicekatalog aufgebaut haben und das wir als unsere Informationsquelle verwenden. [1][2]
• Argo Workflows und Argo Events: Die Open-Source-Suite, die wir verwendeten, um komplexe Prozesse zu orchestrieren und eine dynamische Verarbeitung basierend auf Ereignissen hinzuzufügen. [1][2][3][4]
• Renovate CLI: Das Open-Source-Tool zur Verwaltung von Abhängigkeiten, das unsere Repositorys verarbeitet. [1][2]

* Als Referenz für die Kosten eines einzelnen Pods wurde das AWS Fargate-Preismodell verwendet, obwohl unsere Workloads nicht unbedingt auf AWS laufen, sondern auf vollwertigen Kubernetes-Clustern.

Bei der Optimierung von Elasticsearch für Workloads mit hoher Parallelität besteht der Standardansatz darin, den Arbeitsspeicher zu maximieren, um den Arbeitsdatensatz im Speicher zu halten und so eine geringe Suchlatenz zu erreichen. Daher wird best_compression selten für Such-Workloads berücksichtigt, da es in erster Linie als Speichereinsparungsmaßnahme für Elastic Observability und Elastic Security betrachtet wird, in denen Speichereffizienz Vorrang hat.

In diesem Blog zeigen wir, dass, wenn die Datensatzgröße den OS-Seitencache deutlich übersteigt, best_compression die Suchleistung und Ressourceneffizienz verbessert, indem der I/O-Engpass reduziert wird.

Das Setup

Unser Anwendungsfall ist eine Suchanwendung mit hoher Parallelität, die auf Elastic Cloud CPU-optimierten Instanzen ausgeführt wird.

• Datenvolumen: ~500 Millionen Dokumente
• Infrastruktur: 6 Elastic Cloud (Elasticsearch Service)-Instanzen (jede Instanz: 1,76 TB Speicher | 60 GB RAM | 31,9 vCPUs)
• Verhältnis von Arbeitsspeicher zu Speicher: Ungefähr 5 % des gesamten Datensatzes passen in den Arbeitsspeicher

Die Symptome: hohe Latenz

Wir haben beobachtet, dass sich die Suchlatenz deutlich verschlechterte, wenn die Anzahl der aktuellen Anfragen um 19:00 Uhr stark anstieg. Wie in Abbildung 1 und Abbildung 2 zu sehen ist, erreichte der Datenverkehr einen Spitzenwert von 400 Anfragen pro Minute und Elasticsearch-Instanz, während die durchschnittliche Abfragezeit auf über 60 ms sank.

Die CPU-Auslastung blieb nach der anfänglichen Verarbeitung der Verbindungen relativ niedrig, was darauf hindeutet, dass die Rechenleistung nicht der Engpass war.

Es zeigte sich eine starke Korrelation zwischen dem Abfragevolumen und den Seitenfehlern. Mit zunehmenden Anfragen beobachteten wir einen proportionalen Anstieg der Seitenfehler, mit einem Höchststand von etwa 400.000 pro Minute. Dies deutete darauf hin, dass der aktive Datensatz nicht in den Seitencache passte.

Gleichzeitig schien die Heap-Nutzung der JVM normal und unauffällig zu sein. Dies schloss Probleme mit der Garbage Collection aus und bestätigte, dass der Engpass I/O war.

Die Diagnose: I/O gebunden

Das System war I/O-gebunden. Elasticsearch nutzt den OS-Seitencache, um Indexdaten aus dem Speicher bereitzustellen. Wenn der Index zu groß für den Cache ist, lösen Abfragen kostspielige Festplatten-Lesevorgänge aus. Während die typische Lösung darin besteht, horizontal zu skalieren (Nodes/RAM hinzufügen), wollten wir zunächst alle Möglichkeiten zur Effizienzsteigerung unserer bestehenden Ressourcen ausschöpfen.

Die Lösung

Standardmäßig verwendet Elasticsearch LZ4-Kompression für seine Indexsegmente und findet so ein Gleichgewicht zwischen Geschwindigkeit und Größe. Wir stellten die Hypothese auf, dass ein Wechsel zu best_compression (das zstd verwendet) die Größe der Indizes verringern würde. Durch den geringeren Speicherbedarf kann ein größerer Prozentsatz des Index im Seitencache gespeichert werden, wodurch ein vernachlässigbarer Anstieg der CPU-Auslastung (für die Dekomprimierung) gegen eine Reduzierung der Festplatten-I/O eingetauscht wird.

Um best_compressionzu aktivieren, haben wir die Daten mit der Indexeinstellung index.codec: best_compressionneu indexiert. Alternativ könnte dasselbe Ergebnis erreicht werden, indem der Index geschlossen, der Indexcodec auf best_compressionzurückgesetzt und dann eine Segmentzusammenführung durchgeführt wird.

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

Die Ergebnisse

Die Ergebnisse bestätigten unsere Hypothese: Die verbesserte Speichereffizienz führte direkt zu einer erheblichen Steigerung der Suchleistung, ohne dass die CPU-Auslastung anstieg.

Durch die Anwendung von best_compression wurde die Indexgröße um etwa 25 % reduziert. Obwohl die Reduzierung geringer ausfiel als bei sich wiederholenden Log-Daten, erhöhte diese 25%ige Reduzierung effektiv unsere Seitencache-Kapazität um denselben Faktor.

Beim nächsten Auslastungstest (ab 17:00 Uhr) war der Traffic sogar noch höher und erreichte seinen Höhepunkt bei 500 Anfragen pro Minute pro Elasticsearch-Node.

Trotz der höheren Last war die CPU-Auslastung geringer als in der vorherigen Ausführung. Die erhöhte Nutzung im früheren Test war wahrscheinlich auf den Overhead durch übermäßige Seitenfehlerbehandlung und Festplatten-I/O-Verwaltung zurückzuführen.

Entscheidend ist, dass die Seitenfehler deutlich zurückgingen. Selbst bei höherem Durchsatz lagen die Fehler bei etwa <200.000 pro Minute, verglichen mit >300.000 im Basistest.

Obwohl die Seitenfehlerergebnisse immer noch nicht optimal waren, wurde die Abfragedienstzeit um etwa 50 % reduziert und lag selbst bei höherer Last unter 30 ms.

Fazit: best_compression zum Suchen

Für Such-Anwendungsfälle, in denen das Datenvolumen den verfügbaren physischen Speicher übersteigt, ist best_compression ein kraftvoller Hebel zur Leistungsoptimierung.

Die herkömmliche Lösung für Cache-Fehler besteht darin, den Arbeitsspeicher (RAM) zu skalieren. Allerdings haben wir durch die Reduzierung der Indexgröße das gleiche Ziel erreicht: Maximierung der Dokumentanzahl im Seiten-Cache. Unser nächster Schritt ist es, die Indexsortierung zu untersuchen, um den Speicher weiter zu optimieren und noch mehr Leistung aus unseren bestehenden Ressourcen herauszuholen.

Agenten gewinnen an Bedeutung, getrieben durch ihr Potenzial, Effizienzsteigerungen und bessere Kundenerlebnisse zu liefern. Aber in der Praxis ist es schwierig, Agenten den richtigen Kontext zu bieten, insbesondere wenn sie mit unübersichtlichen, unstrukturierten Unternehmensdaten arbeiten. Entwickler müssen Tools, Prompts, Zustand, Schlussfolgerungslogik, Modelle und vor allem den relevanten Kontext aus Geschäftsquellen abrufen, um genaue Ergebnisse und Aktionen zu liefern. Elastic Agent Builder bietet diese Kernkomponenten für die Entwicklung sicherer, zuverlässiger, kontextgesteuerter Agenten.

Kernfunktionen von Agent Builder

Agent Builder nutzt die langfristigen Investitionen von Elastic in die Suchrelevanz und die Retrieval-Augmented Generation und arbeitet daran, Elasticsearch zur besten Vektordatenbank zu machen, um die Entwicklung kontextbezogener, datenorientierter KI-Agenten zu vereinfachen.

Mit Agent Builder können Sie:

• Starten Sie sofort mit einem integrierten Dialogagenten, der Fragen beantworten, Analysen durchführen und Untersuchungen über alle Daten in Elasticsearch anstoßen kann.
• Wechseln Sie schnell von komplexen unstrukturierten Daten zu einem benutzerdefinierten Agenten mit konfigurationsbasierter Entwicklungserfahrung.
• Nutzen Sie die erstklassige, hybride Suchrelevanz durch integriertes ES|QL oder benutzerdefinierte Tools, um die Kontextqualität und Agentenzuverlässigkeit zu verbessern.
• Komplexe Workflows (Vorschau) als wiederverwendbare Werkzeuge ausführen, um Daten anzureichern, Einträge zu aktualisieren, Nachrichten zu senden und vieles mehr für eine regelbasierte Automatisierung.
• Verbinden Sie sich mit Datenquellen außerhalb von Elasticsearch über Workflows und MCP, um den Kontext für Agenten zu korrelieren und zu kombinieren.
• Integrieren Sie beliebige Agenten- oder Anwendungsframeworks mithilfe von integrierten und benutzerdefinierten Tools, die über MCP bereitgestellt werden, sowie mit der Möglichkeit zur Verbindung mit externen MCPs (Vorschau), Unterstützung für A2A und vollständige API-Unterstützung.
• Erweitern Sie die Fähigkeiten von Agent Builder durch Integration mit Drittanbieterlösungen wie LlamaIndex für komplexe Dokumentenverarbeitung oder Arcade.dev für sicheren, strukturierten Toolzugriff.

Um die Funktionen von Agent Builder weiter zu erweitern, führen wir Elastic Workflows ein, unsere neuen regelbasierten Automatisierungsfunktionen, jetzt in der technischen Vorschau. Für organisatorische Aufgaben benötigen Agenten manchmal Sicherheit und Zuverlässigkeit von regelbasierten Aktionen, die oft notwendig sind, um eine bestimmte Geschäftslogik umzusetzen. Elastic Workflows bietet Agenten eine einfache, deklarative Möglichkeit, interne und externe Systeme zu orchestrieren, um Aktionen durchzuführen, Daten und Kontext zu erfassen und zu transformieren. Workflows sind vollständig zusammensetzbar, ereignisgesteuert und flexibel und können einem Agenten über MCP als Werkzeuge zur Verfügung gestellt werden.

In wenigen Minuten vom Daten zum Agenten

Die Entwicklung von Agenten kann wochenlange Vorarbeit erfordern, um separate Datenspeicher zu konsolidieren, manuelle Pipelines zu erstellen, Abfragen zu optimieren und komplexe Orchestrierungen zu verwalten. Agent Builder verkürzt die Entwicklungszeit für Agenten, indem es die Notwendigkeit für separate Datenspeicher, Vektordatenbanken, RAG-Pipelines, Suchschichten, Abfrageübersetzer und Tool-Orchestratoren beseitigt, sodass Sie sich auf die Agentenlogik und die Anwendungsbereitstellung konzentrieren können.

Agent Builder integriert nativ die Primitiven der Elasticsearch-Plattform, um die Agentenentwicklung zu beschleunigen.

• Beginnen Sie mit einem integrierten Dialogsystem, das sofort mit Ihren indexierten Daten chatten und argumentieren kann.
• Integrieren Sie Agenten in Anwendungen, Dashboards oder CI/CD-Systeme mit interaktivem Zugriff über Kibana, APIs oder MCP und A2A.
• Nutzen Sie die Standardwerkzeuge, um Ihre Datenstruktur zu verstehen, den passenden Index auszuwählen, optimierte hybride, semantische und strukturierte Abfragen zu generieren und konfigurierbare Visualisierungen mit ES|QL auf Basis von natürlichsprachlichen Eingabeaufforderungen zu erstellen.

Um tiefer einzutauchen, probieren Sie eine vollständige praktische Anleitung.

Bauen Sie auf Elasticsearch auf, einer vollständigen Datenplattform für Kontext-Engineering

Für KI-Agenten ist die Qualität des Kontexts entscheidend, um effektives Denken zu ermöglichen und die Gefahr von Halluzinationen zu verringern. Für viele Enterprise-KI-Agenten sind die Geschäftsdaten, die für die Ausführung einer Aufgabe erforderlich sind, der wichtigste Kontext. Als massiv skalierbarer Datenspeicher, Vektordatenbank und führender Anbieter relevanter Daten bietet Elasticsearch bereits viele leistungsstarke Kontext-Engineering-Primitive. Context Engineering geht über die einfache retrieval-augmented generation hinaus, indem es Ihnen ermöglicht, die Art und Weise, wie Daten abgerufen, sortiert, gefiltert und Agenten präsentiert werden, individuell anzupassen und zu skalieren, wodurch Rauschen und Mehrdeutigkeiten reduziert werden.

Elasticsearch liefert eine Kontext-Engine, die lexikalische Suche, Vektorsuche und strukturierte Filterung für den Abruf kombiniert und die Leistung von LLMs erheblich verbessert, indem sichergestellt wird, dass das Modell auf relevantem und präzisem Kontext arbeitet. Diese Funktion wird durch agentische Abrufe unterstützt, zusammen mit integrierten Werkzeugen und einer Suchlogik, die automatisch die richtigen Indizes auswählt und natürliche Sprache in optimierte Kontextanfragen umwandelt.

Mit Agent Builder können Sie sicherstellen, dass Agenten zuerst den relevantesten Kontext erhalten, indem Sie die Relevanz und das Ranking steuern. So können Sie die Logik für Bewertung, Ranking und Filterung feinabstimmen. Mit Elasticsearch können Sie kontrollieren, was wichtig ist, warum es wichtig ist und wie es priorisiert wird, anstatt sich auf ein undurchsichtiges Abrufverhalten zu verlassen. Grundlage hierfür ist Elasticsearch als Skalierbarkeits-Datenplattform, mit der sich alle Ihre Daten – von Texten über Vektoren und Metadaten bis hin zu Logs und mehr – auf einer Plattform speichern und skalieren lassen, was die Kontextverwaltung für Agenten vereinfacht.

Führen Sie komplexe Workflows als wiederverwendbare Tools aus

Während KI-Agenten das Denken für komplexe Aufgaben ermöglichen, hängt ein Großteil der Automatisierung davon ab, regelbasierte Aktionen zuverlässig auszuführen, die eine spezifische Geschäftslogik durchsetzen. Elastic Workflows bietet eine einfache, deklarative Möglichkeit, interne und externe Systeme zu orchestrieren, um Aktionen auszuführen, Kontext oder Daten zu sammeln und diese als Teil der Agenten zu integrieren. Die in YAML definierten Workflows sind vollständig zusammensetzbar, so dass sie so einfach oder so komplex sein können, wie es die Aufgabe erfordert. Dies gibt Agenten eine effiziente Möglichkeit, über die Elasticsearch-Platform und solutions hinweg sowie mit Anwendungen von Drittanbietern zu agieren.

Die Integration eines Workflows mit Agent Builder kann in drei Schritten erfolgen (Voraussetzung: Workflows mit den hier angegebenen Details aktivieren)

1. Erstellen und speichern Sie einen neuen Workflow mit dem einfachen YAML-basierten Editor mit integrierter Autovervollständigung und Testfunktion.

2. Erstellen Sie ein neues Tool in Agent Builder mit dem Typ „Workflow“ und geben Sie eine Beschreibung an, die dem Agenten hilft zu bestimmen, wann das Workflow-Tool verwendet werden soll.

3. Fügen Sie das Workflow-Tool zu Ihrem benutzerdefinierten Agenten hinzu.

4. Das ist es! Jetzt kann der Agent den Workflow innerhalb eines Gesprächs aufrufen.

Ihr Agent, Ihre Regeln

Agent Builder bindet Sie nicht an ein einzelnes Entwicklungsparadigma. Stattdessen ist es darauf ausgelegt, offene, flexible Entwicklungsansätze für Agenten mit vollständiger Kontrolle über Daten, Relevanz, Modelle, Interoperabilität, Sicherheit und Agentendesign zu ermöglichen.

Mithilfe benutzerdefinierter Agentendefinitionen können Sie genau auswählen, auf welche Tools ein Agent zugreifen darf, benutzerdefinierte Systemaufforderungen einbetten, die Anweisungen des Agenten anpassen und Sicherheitsgrenzen definieren. Die Agenten bleiben modellunabhängig, sodass Sie flexibel ein bevorzugtes LLM konfigurieren können, sowohl nativ als auch im gesamten Ökosystem, ohne an einen einzigen Anbieter gebunden zu sein.

Entwickeln Sie erweiterbare Tools, die domänenspezifische Logik kapseln (z. B. spezifische Indexfilter, ES|QL-Joins, analytische Pipelines) und schränken Sie diese für einen sicheren Einsatz in der Produktion ein. Vollständige API-Unterstützung ermöglicht die Interoperabilität mit anderen agentischen Frameworks, mit nativer Unterstützung für das Model Context Protocol (MCP). Die A2A-Integration bedeutet, dass Sie Ihre Elastic-Agenten anderen Frameworks, Diensten und Client-Apps zugänglich machen können, indem Sie dieselben Daten und dieselbe Context-Engineering-Logik für alle Integrationen wiederverwenden.

Agent Builder unterstützt eine flexible, offene Entwicklung und ist so konzipiert, dass er sich problemlos in gängige Agenten-Frameworks und -Plattformen integrieren lässt. Diese Integrationen können für die Bereitstellung effektiver Agenten von entscheidender Bedeutung sein. Wie Sam Partee, Mitbegründer von Arcade.dev , beschreibt:

„Agentische Systeme scheitern heute, weil die Verbindung von KI mit Werkzeugen und Daten komplex ist.“ Elastic Agent Builder mit Arcade.dev bietet Entwicklern eine strukturierte und sichere Möglichkeit, die Art und Weise zu steuern, wie Agenten Kontext abrufen, Argumente liefern und handeln, und ermöglicht so die Weiterentwicklung von Demo- zu Produktionsversionen.

Agent Builder nutzt außerdem die Erweiterbarkeit von Elasticsearch zur Verarbeitung komplexer Daten. Wie Jerry Liu, CEO von LlamaIndex beschreibt:

„Das Erschließen des Unternehmenskontextes aus unstrukturierten Datenquellen ist der Schlüssel zum Aufbau effektiver Agenten. Elastic Agent Builder in Kombination mit der komplexen Dokumentenverarbeitung von LlamaIndex stärkt die kritische Kontextschicht und hilft Teams dabei, Daten abzurufen, zu verarbeiten und aufzubereiten, damit Agenten genauer argumentieren und bessere Ergebnisse erzielen können.“

Was können Sie erstellen?

Agent Builder wird bereits für eine Vielzahl von Anwendungsfällen eingesetzt. Nachfolgend finden Sie einige Beispiele und Referenzarchitekturen für den Einstieg in die Agentenarbeit:

• Infrastruktur automatisieren: In Support-Szenarien wurden Agenten zum Lesen, Nachdenken und Chatten eingesetzt, aber bisher können sie nicht die Infrastruktur berühren, die sie möglicherweise verwalten müssen. Das Ingenieurteam von Elastic hat im Rahmen eines Hackathons einen Agenten für die automatische Verwaltung der Infrastruktur entwickelt. Der Agent untersucht aktiv Probleme mit der Anwendungsinfrastruktur und ergreift automatisierte Maßnahmen. Es verwendet Workflows, um Konfigurationen zu optimieren, auf Probleme zu reagieren und Ressourcen zu skalieren, alles auf der Grundlage eines intelligenten Verständnisses der Infrastrukturprotokolle.
• Sicherheitsbedrohungsanalyse: Ein Sicherheitsschwachstellen-Agent wurde mit Elastic Agent Builder, MCP und Elasticsearch entwickelt. Es automatisiert die Bedrohungsanalyse durch die Korrelation interner Sicherheitsdaten mit externen Bedrohungsinformationen. Der Agent führt semantische Suche über historische Vorfälle und Konfigurationen durch, erweitert die Ergebnisse mit Live-Internetdaten und wendet LLM-Argumentation an, um Umweltrelevanz zu bewerten, Risiken zu priorisieren und umsetzbare Sanierungen zu erstellen. Sehen Sie sich die Referenzarchitekturan.
• Technischer Kundensupport: Agenten können mehrere Unterstützungsaufgaben ausführen, darunter Ticketzusammenfassungen, Issue-Deduplizierung und -Erstellung sowie tiefgehende technische Untersuchungen. Agent Builder ermöglicht dies mit mehrstufigen, hybriden Suchen, um nur die relevantesten verwandten Probleme, Lösungen und Verfahren zu finden und Hypothesen zu Grundursachen sowie Behebungspläne zu formulieren. Agent Builder kann die Architektur komplexer Unterstützungssysteme vereinfachen und die Zeit bis zur Bereitstellung beschleunigen.
• Produkt- und Inhaltserkennung: Agent Builder vereinfacht den Prozess der Bereitstellung komplexer Produktkataloge für Konversationserlebnisse und bietet Unternehmen gleichzeitig die Flexibilität, ihre eigene Geschäftslogik und ihre eigenen Anforderungen zu pflegen.
• Selbst erstellen: Nehmen Sie am Agent Builder Hackathon teil, der vom 22. Januar bis 27. Februar 2026 stattfindet. Arbeiten Sie mit der Community zusammen, um kontextgesteuerte, mehrstufige KI-Agenten zu entwickeln, die Suche, Workflows, Tools und Argumentation kombinieren, um reale Aufgaben zu automatisieren*

Beginnen Sie jetzt mit der Erstellung benutzerdefinierter Agenten

Starten Sie mit einer Elastic Cloud-Testversion und sehen Sie sich hier die Dokumentation an. Für bestehende Kunden ist Agent Builder in Cloud Serverless und auf dem Enterprise Tier in Elastic Cloud Hosted und selbstverwaltet verfügbar.

* Klicken Sie hier für die vollständigen Bedingungen und Teilnahmevoraussetzungen für den Hackathon

Eine der Möglichkeiten, das Glas zu zerbrechen, ist die Einführung von Voice Agents, d. h. von KI-Agenten, die menschliche Sprache erkennen und computergenerierte Audiosignale synthetisieren. Mit dem Aufkommen von Transkriptionen mit geringer Latenz, schnellen Large Language Models (LLMs) und Text-zu-Sprach-Modellen, die menschlich klingen, ist dies möglich geworden.

Sprachagenten benötigen außerdem Zugriff auf Geschäftsdaten, um wirklich wertvoll zu werden. In diesem Blog-Artikel erfahren wir, wie Sprachagenten funktionieren, und erstellen einen für ElasticSport, ein fiktives Outdoor-Sportartikelgeschäft, mit LiveKit und Elastic Agent Builder. Unser Sprachagent wird kontextbewusst sein und mit unseren Daten arbeiten.

So funktionierts

In der Welt der Sprachagenten gibt es zwei Paradigmen: Das erste verwendet Sprache-zu-Sprache-Modelle, das zweite eine Sprachpipeline, die aus Sprache-zu-Text, LLM und Text-zu-Sprache besteht. Sprach-zu-Sprache-Modelle haben ihre eigenen Vorteile, aber Sprachpipelines bieten viel mehr Anpassungsmöglichkeiten bei den verwendeten Technologien und der Kontextverwaltung sowie Kontrolle über das Verhalten des Agenten. Wir werden uns auf das Sprachpipeline-Modell konzentrieren.

Hauptkomponenten

Transkription (Sprache-zu-Text)

Die Transkription ist der Einstiegspunkt für die Sprachpipeline. Die Transkriptionskomponente nimmt rohe Audio-Frames als Eingabe, transkribiert Sprache in Text und gibt diesen Text aus. Der transkribierte Text wird gepuffert, bis das System erkennt, dass das Sprechen des Nutzers beendet ist, woraufhin die LLM-Generierung gestartet wird. Verschiedene Drittanbieter bieten Transkriptionen mit geringer Latenz an. Berücksichtigen Sie bei der Auswahl eines Anbieters die Latenz und die Transkriptionsgenauigkeit und stellen Sie sicher, dass dieser Anbieter gestreamte Transkripte unterstützt.

Beispiele für Drittanbieter-APIs: AssemblyAI, Deepgram, OpenAI, ElevenLabs

Wendeerkennung

Die Wendeerkennung ist die Komponente der Pipeline, die erkennt, wann der Sprecher zu Ende gesprochen hat und die Generierung beginnen soll. Eine gängige Methode dazu ist ein Voice Activity Erkennung (VAD)-Modell wie Silero VAD. VAD nutzt Audio-Energiepegel, um zu erkennen, wenn ein Audiosignal Sprache enthält und wann das Sprechen beendet ist. Allerdings kann VAD allein den Unterschied zwischen einer Pause und dem Ende der Rede nicht erkennen. Aus diesem Grund wird es oft mit einem Modell für das Ende der Äußerung kombiniert, das auf der Grundlage des Zwischentranskripts oder des Rohaudiosignals vorhersagt, ob der Sprecher zu Ende gesprochen hat.

Beispiele (Hugging Face): Livekit/Wendeerkennung, pipecat-ai/smart-turn-v3

Agent

Der Agent ist der Kern einer Sprachpipeline. Er ist verantwortlich für das Verstehen der Absicht, das Erfassen des richtigen Kontexts und das Formulieren einer Antwort im Text-Format. Elastic Agent Builder, mit integrierten Reasoning-Funktionen, Werkzeug-Bibliothek und Workflow-Integration, ermöglicht die Erstellung eines Agenten, der Ihre Daten verarbeiten und mit externen Diensten interagieren kann.

LLM (Text-zu-Text)

Bei der Auswahl eines LLM für Elastic Agent Builder sind zwei Hauptmerkmale zu berücksichtigen: die LLM-Benchmarks und die Zeit bis zum ersten Token (TTFT).

Die Reasoning-Benchmarks geben Aufschluss darüber, wie gut das LLM in der Lage ist, korrekte Reaktionen zu generieren. Zu berücksichtigende Benchmarks sind solche, die die Einhaltung von Mehrrundengesprächen und Intelligenz-Benchmarks bewerten, wie z. B. MT-Bench und der Datensatz „Humanity's Last Exam“.

TTFT-Benchmarks bewerten, wie schnell das Modell sein erstes Ausgabetoken erzeugt. Es gibt andere Arten von Latenz-Benchmarks, aber TTFT ist besonders wichtig für Sprachagenten, da die Audiosynthese sofort nach Empfang des ersten Tokens beginnen kann, was zu einer geringeren Latenz zwischen den Runden und zu einer natürlich wirkenden Konversation führt.

In der Regel muss man einen Kompromiss zwischen diesen beiden Merkmalen eingehen, da schnellere Modelle oft schlechtere Ergebnisse bei Reasoning-Benchmarks erzielen.

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

Synthese (Text-zu-Sprache)

Der letzte Teil der Pipeline ist das Text-to-Speech-Modell. Diese Komponente ist für die Umwandlung der Textausgabe des LLM in hörbare Sprache zuständig. Ähnlich wie beim LLM ist die Latenz ein Merkmal, auf das bei der Auswahl eines Text-zu-Sprache-Anbieters zu achten ist. Die Latenz bei der Umwandlung von Text in Sprache wird durch die Zeit bis zum ersten Byte (TTFB) gemessen. Das ist die Zeit, die vergeht, bis das erste Audiobyte empfangen wird. Ein niedrigeres TTFB reduziert auch die Rundenlatenz.

Beispiele: ElevenLabs, Cartesia, Rime

Erstellen der Sprachpipeline

Elastic Agent Builder kann auf mehreren verschiedenen Ebenen in eine Sprachpipeline integriert werden:

1. Nur Agent Builder-Tools: Sprache-zu-Text → LLM (mit Agent Builder-Tools) → Text-zu-Sprache
2. Agent Builder als MCP: Sprache-zu-Text → LLM (mit Agent Builder-Zugang über MCP) → Text-zu-Sprache
3. Agent Builder als Kern: Sprache-zu-Text → Agent Builder → Text-zu-Sprache

Für dieses Projekt habe ich den Ansatz Agent Builder als Kern gewählt. Mit diesem Ansatz kann der volle Funktionsumfang des Agent Builder und Workflows genutzt werden. Das Projekt verwendet LiveKit, um Sprache-zu-Text, Wendeerkennung und Text-zu-Sprache zu orchestrieren, und implementiert einen benutzerdefinierten LLM-Knoten, der direkt mit Agent Builder integriert ist.

Elastic Support-Sprachagent

Wir werden einen benutzerdefinierten Support-Sprachagenten für ein fiktives Sportgeschäft namens ElasticSport erstellen. Kunden können die Hotline anrufen, um Produktempfehlungen bitten, Produktdetails finden, den Bestellstatus prüfen und Bestellinformationen per SMS erhalten. Um dies zu erreichen, müssen wir zunächst einen benutzerdefinierten Agenten konfigurieren und Tools für die Ausführung von Elasticsearch Query Language (ES|QL)-Abfragen und -Workflows erstellen.

Konfigurieren des Agenten

Prompt

Der Prompt teilt dem Agenten mit, welche Persönlichkeit er annehmen und wie er reagieren soll. Wichtig ist, dass es einige sprachspezifische Hinweise gibt, die sicherstellen, dass die Reaktionen korrekt in Audio umgewandelt werden und Missverständnisse elegant behoben werden.

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

Wir fügen einen kleinen Workflow hinzu, um eine SMS über die Messaging-API von Twilio zu versenden. Der Workflow wird dem benutzerdefinierten Agenten als Tool zur Verfügung gestellt, so dass der Agent dem Anrufer während des Gesprächs eine SMS senden kann. Dadurch kann der Anrufer zum Beispiel fragen: „Können Sie mehr Informationen über X per SMS senden?“

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

ES|QL-Tools

Mit den folgenden Tools kann der Agent relevante Antworten geben, die auf realen Daten beruhen. Das Beispiel-Repository enthält ein Setup-Skript zur Initialisierung von Kibana mit Produkt-, Auftrags- und Wissensdatenbank-Datensätzen.

• Product.search

Der Produktdatensatz enthält 65 fiktive Produkte. Dies ist ein Beispieldokument:

{
      "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"]
    }

Die Felder „Name“ und „Beschreibung“ sind als semantic_text abgebildet, wodurch das LLM die semantische Suche über ES|QL nutzen kann, um relevante Produkte abzurufen. Die hybride Suchabfrage führt einen semantischen Abgleich in beiden Feldern durch, wobei Treffer im Namensfeld mithilfe eines Boosts etwas höher gewichtet werden.

Die Abfrage ruft zunächst die 20 besten Ergebnisse ab, geordnet nach ihrer anfänglichen Relevanzbewertung. Diese Ergebnisse werden dann basierend auf ihrem Beschreibungsfeld mit dem .rerank-v1-elasticsearch Inferenzmodell neu bewertet und schließlich auf die fünf relevantesten Produkte reduziert.

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

Die Wissensdatenbank-Datensätze enthalten Dokumente mit folgender Struktur, wobei die Felder „Titel“ und „Inhalt“ als semantischer Text gespeichert werden:

{
        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
        `
}

Und das Tool verwendet eine ähnliche Abfrage wie das product.search -Tool:

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

Das letzte Tool, das wir hinzufügen werden, ist dasjenige, das zum Abrufen von Bestellungen nach order_id verwendet wird:

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"

Nach der Konfiguration des Agenten und dem Anhängen dieser Workflows und ES|QL-Tools an den Agenten kann der Agent in Kibana getestet werden.

Abgesehen vom Aufbau eines ElasticSport-Supportagenten können der Agent, die Workflows und die Tools auch für andere Anwendungsfälle angepasst werden, beispielsweise für einen Vertriebsagenten, der Leads qualifiziert, einen Serviceagenten für Hausreparaturen, Reservierungen für ein Restaurant oder einen Terminplanungsagenten.

Der letzte Teil ist die Verknüpfung des Agenten, den wir gerade erstellt haben, mit LiveKit-, Text-to-Speech- und Speech-to-Text-Modellen. Das am Ende dieses Blogbeitrags verlinkte Repository enthält einen benutzerdefinierten Elastic Agent Builder LLM-Knoten, der mit LiveKit verwendet werden kann. Ersetzen Sie einfach AGENT_ID durch Ihren eigenen Wert und verknüpfen Sie es mit Ihrer Kibana-Instanz.

Erste Schritte

Sehen Sie sich den Code an und probieren Sie es hier selbst aus.

Wir haben alle den Aufstieg von KI-Agenten gesehen. Sie sind hervorragend darin, Texte zusammenzufassen, Code-Snippets zu schreiben und Fragen anhand der Dokumentation zu beantworten. Doch für uns im Bereich DevOps und Site Reliability Engineering (SRE) gab es eine frustrierende Einschränkung. Die meisten Agenten sind im Call Center-Paradigma gefangen, d. h. sie können lesen, denken und chatten, aber sie können die Infrastruktur, die sie verwalten sollen, nicht erreichen und berühren.

Für unser neuestes Hackathon-Projekt haben wir beschlossen, diese Einschränkung aufzuheben.

Wir haben Augmented Infrastructure entwickelt: einen Infrastruktur-Copiloten, der Ihnen nicht nur Ratschläge gibt, sondern auch Ihre Live-Umgebung erstellt, bereitstellt, überwacht und repariert.

Das Problem: Kopieren, Neuformatieren, Einfügen

Standardagenten agieren isoliert. Wenn Ihre App ausfällt und das Unternehmen 5 Millionen $ kostet, kann Ihnen ein Standard-Agent die Bedienungsanleitung vorlesen, wie Sie das Problem beheben können. Aber Sie müssen trotzdem die Arbeit machen. Kopieren Sie den Code, formatieren Sie ihn für Ihre Umgebung um und fügen Sie ihn in Ihr Terminal ein.

Wir wollten einen Agenten, der den Unterschied zwischen dem Sprechen über Kubernetes und dem Konfigurieren von Kubernetes versteht.

Die Engine: Was ist der Elastic Agent Builder?

Um das zu realisieren, haben wir nicht bei null angefangen. Wir haben es auf Elastic Agent Builder aufgebaut. Für diejenigen, die es noch nicht kennen: Elastic Agent Builder ist ein Framework, das für die schnelle Entwicklung von Agenten konzipiert wurde und als Brücke zwischen einem großen Sprachmodell (LLM) (in unserer Demo haben wir Google Gemini verwendet) und privaten Daten, die in Elasticsearch gespeichert sind, fungiert.

Agent Builder kann für dialogbasierte KI verwendet werden, indem er auf internen Daten wie Dokumenten oder Protokollen basiert. Aber sein leistungsstärkstes Feature ist die Möglichkeit, Tools zuzuweisen. Mithilfe dieser Tools kann das LLM die Chat-Schnittstelle verlassen, um spezifische Aufgaben auszuführen. Wir haben erkannt, dass wir, wenn wir dieses Feature bis an seine Grenzen ausreizen, Agent Builder in eine Automatisierungs-Hochburg verwandeln könnten.

So funktioniert es: Die erste Version wird erstellt

Als wir mit dem Projekt angefangen haben, wussten wir, dass wir die Agenten in die Lage versetzen wollten, die Außenwelt zu verändern. Wir hatten eine Idee: Was wäre, wenn wir eine Art „Runner“-Software entwickeln würden (die jeden Befehl, den sich der Agent ausdenken könnte, auf dem Host ausführt)? Und dann: Was wäre, wenn die Runner, Elastic Agent Builder und der Nutzer in einem Dreiergespräch wären?

Wir begannen damit, ein Python-Projekt namens Augmented Infrastructure Runners zu entwickeln, das im Grunde eine while(true)-Schleife war, die jede Sekunde die Elastic Agent Builder Conversations API abfragte und nach einer speziellen Syntax prüfte, die wir erstellt hatten:

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

Anschließend aktualisierten wir den Prompt, um ihn mit unserer neuen Tool-Aufruf-Syntax vertraut zu machen. Bill ist Maintainer von FastMCP, dem beliebtesten Framework zum Aufbau von Modellkontextprotokoll-(MCP)-Servern in Python. Er machte sich daran, mit dem FastMCP-Client und dieser neuen Runner-Software MCP-Server einzubinden und deren Tools dem Runner zur Verfügung zu stellen. Als der Agent dies sah, führte er den Tool-Aufruf aus und POST die Ergebnisse zurück an die Konversation, als ob der Nutzer die Ergebnisse gesendet hätte. Dies veranlasste das LLM, auf das Ergebnis zu reagieren, und schon ging es los!

Das war toll, hatte aber zwei Hauptprobleme:

1. Der Agent würde all diese JSON-Daten direkt in die Unterhaltung mit dem Nutzer einspeisen.
2. Der früheste Zeitpunkt, an dem Nachrichten über die Konversations-API sichtbar waren, war, als eine Konversationsrunde abgeschlossen wurde (also als das LLM antwortete).

Also machten wir uns daran, herauszufinden, wie wir dies in den Hintergrund verschieben können.

Wir sind dann dazu übergegangen, dem Agenten ein Tool namens call_external_tool mit zwei Argumenten zu geben: dem tool_name und den stringifizierten JSON-Tool-Argumenten. Dieser externe Toolaufruf gab kein Ergebnis, war aber wichtigerweise in der GET-Anfrage an die Konversations-API sichtbar. Wir gaben den Runnern dann die Erlaubnis, Dokumente direkt in Elasticsearch zu schreiben, die der Elastic Agent Builder-Agent bei Bedarf abrufen konnte. Der Agent arbeitet immer als Reaktion auf eine Nutzernachricht, daher müssen wir den Agenten mit einer Nutzernachricht starten, damit er nach Ergebnissen sucht und die Verarbeitung fortsetzt. Deshalb haben wir die Agenten gebeten, eine kurze Nachricht in den Chat einzufügen, um die Konversation fortzusetzen:

Nun hatten wir also externe Tool-Aufrufe. Wegen des zweiten oben genannten Problems mussten wir jedoch auf diesen letzten Anstoßmechanismus verzichten. Andernfalls erforderte jeder externe Tool-Aufruf eine komplette Gesprächsrunde, um die Ergebnisse abzurufen!

Das Beste daraus machen: Einführung von Workflows

Zusätzlich zur Elasticsearch-Abfragesprache (ES|QL) und Aufrufen von Index-Such-Tools können Agent Builder-Agenten Elastic-Workflow-basierte Tools aufrufen. Elastic-Workflows bieten eine flexible und einfach zu verwaltende Möglichkeit, eine beliebige Abfolge und Logik von Aktionen auszuführen. Für unsere Zwecke muss der Workflow lediglich eine externe Tool-Anfrage in Elasticsearch speichern und eine ID zurückgeben, anhand derer die Ergebnisse abgefragt werden können. Daraus ergibt sich die folgende einfache Workflow-Definition:

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."

Damit können die Runner, anstatt sich darauf zu verlassen, dass die Tool-Aufrufanfrage in die Konversation geschrieben wird, einfach den Elasticsearch- distributed-tool-requests -Index auf neue externe Tool-Anfragen abfragen und die Ergebnisse als Bericht mit dem bereitgestellten execution.id in einen anderen Elasticsearch-Index zurückmelden.

Damit sind die beiden oben genannten Hauptprobleme beseitigt:

1. Der Gesprächsverlauf ist nicht mehr mit den Nutzdaten der externen Tool-Aufrufe überladen.
2. Da die Runner den Elasticsearch-Index anstelle des Konversationsverlaufs abfragen, werden sie nicht dadurch blockiert, dass die Konversationsrunde abgeschlossen sein muss, damit die Anfragen an das externe Tool sichtbar werden.

Der zweite Punkt hat den großen Vorteil, dass die Verarbeitung der externen Tool-Aufrufe bereits in der Denkphase des Agenten beginnt (und nicht erst nach Abschluss der Gesprächsrunde). Dadurch können wir den LLM im System-Prompt anweisen, die Ergebnisse des externen Tools abzufragen, bis diese verfügbar sind, und die Notwendigkeit einer Startnachricht entfällt. Insgesamt hat dies den angenehmen Effekt, dass sich die Konversation natürlicher anfühlt: Das LLM kann mehrere externe Tool-Anfragen innerhalb einer einzigen Konversationsrunde verarbeiten (anstatt für jede Tool-Anfrage eine Konversationsrunde zu benötigen) und kann somit komplexere Nutzeranfragen in einem Durchgang erledigen.

Aus den Einzelteilen entsteht ein Ganzes

Um die Lücke zwischen dem LLM und dem Server-Rack zu schließen, haben wir eine spezielle Architektur entwickelt, die die Funktionen des Agent Builders nutzt:

1. Runner für erweiterte Infrastruktur: Wir haben Lightweight-Runner innerhalb der Zielumgebungen (Server, Kubernetes-Cluster, Cloud-Konten) bereitgestellt. Diese Runner sind direkt mit Elastic verbunden und verwenden gesicherte Endpoints und Secrets, die nur dem jeweiligen Runner zur Verfügung stehen.
2. ES|QL-Abfrage: Der Copilot verwendet Elastics ES|QL, um hybride Suchen durchzuführen. Er sucht nicht nur nach Wissen; er sucht nach Fähigkeiten. Er fragt die verbundenen Runner ab, um zu sehen, welche Werkzeuge verfügbar sind (zum Beispiel list_ec2_instances, install_helm_chart).
3. Workflow-Ausführung: Sobald der Agent sich für eine Vorgehensweise entschieden hat, erstellt er einen strukturierten Workflow.
4. Rückkopplungsschleife: Die Ausführenden führen den Befehl lokal aus und senden den Bericht an Elasticsearch zurück. Der Copilot liest das Ergebnis aus dem Index und entscheidet den nächsten Schritt.

Die Demo: Von Ausfall zu Beobachtbarkeit

Im Video haben wir zwei unterschiedliche Szenarien gezeigt, die die Kraft dieser Architektur demonstrieren.

Szenario 1: DevOps-Rettung

Wir begannen mit einem Nutzer, der wegen eines Ausfalls von 5 Millionen $ durch einen blinden Winkel in seinem Kubernetes-Cluster in Panik geriet.

• Die Anfrage: „Wie kann ich sicherstellen, dass dies nicht wieder vorkommt?“
• Die Aktion: Der Agent hat nicht nur ein Tutorial bereitgestellt. Er identifizierte den Cluster, erstellte die notwendigen Namespaces, generierte Kubernetes-Secrets, installierte den OpenTelemetry Operator und stellte sofort einen Link zu einem Live-APM-Dashboard bereit.
• Das Ergebnis: Vollständige Kubernetes-Beobachtbarkeit und Anwendungseinblicke, ohne dass der Nutzer auch nur eine einzige YAML-Zeile schreiben muss.

Szenario 2: Security-Übergabe

Eine Grundregel der Infrastruktursicherheit lautet: Was man nicht sieht, kann man nicht schützen. Während der Durchführung unserer DevOps-Rettung sieht der Agent eine Möglichkeit, die Sicherheit der Umgebung zu verbessern.

Ausgehend von einer Warnung, die im Rahmen einer früheren Untersuchung im Zusammenhang mit Elastic Observability ausgelöst wurde, zeigen wir, wie ein Sicherheitsexperte direkt mit seiner Infrastruktur kommunizieren kann: erstens, um die Assets und Ressourcen in seiner Cloud-Umgebung aufzulisten; und zweitens, um die notwendigen Tools bereitzustellen, um die Sicherheit der Umgebung zu gewährleisten.

• Entdeckung: Der Copilot zählte die AWS-Ressourcen für den Sicherheitsexperten auf und identifizierte eine kritische Lücke: eine Amazon Elastic Compute Cloud (EC2)-Instanz und ein Amazon Elastic Kubernetes Service (EKS)-Cluster, bei denen öffentliche Endpoints keinen Endpoint-Schutz besitzen.
• Behebung: Mit einer einfachen Freigabe stellte der Copilot Elastic Security Erweiterte Erkennung und Reaktion (XDR) und Cloud-Erkennung und -Reaktion (CDR) für die anfälligen Assets bereit und sicherte die Umgebung in Echtzeit.
• Das Ergebnis: Schutz der bereitgestellten AWS-Assets und -Ressourcen mit vollständiger Laufzeitsicherheit.

Die Zukunft: Alles augmentiert

Dieses Projekt beweist, dass Elastic Agent Builder die zentrale Steuerungseinheit für verteilte Operationen sein kann. Wir beschränken uns nicht nur auf die Infrastruktur. Unsere Runner-Technologie kann Folgendes mit Energie versorgen:

• Augmented Synthetics: Diagnose von TLS-Fehlern bei globalen Runnern.
• Erweiterte Entwicklung: Erstellung von Pull-Anfragen und Implementierung von CAPTCHAs auf Frontend-Diensten.
• Erweiterter Betrieb: Automatische Neukonfiguration der DNS-Resolver bei einem Ausfall.

Probieren Sie es selbst aus

Wir glauben, dass es bei der Zukunft der KI nicht nur um Chat-Support geht, sondern um erweiterte Infrastruktur. Es geht darum, einen Partner zu haben, der gemeinsam mit Ihnen bereitstellen, reparieren, beobachten und schützen kann.

Sehen Sie sich den Code an und probieren Sie ihn noch heute mit Distributed Runners (GitHub) plus Elastic Agent Builder auf Elastic Cloud Serverless aus!

• Erstellen Sie ein serverloses Projekt auf Elastic Cloud.
• Stellen Sie den Code auf einem Runner bereit.
• Richten Sie den Runner ein.
• Konfigurieren Sie Ihre mcp.json.
• Starten Sie den Runner, der automatisch Ihren Agenten und seine Tools erstellt.
• Chatten Sie mit einem Agenten, der Aktionen für Ihre verteilten Runner planen und ausführen kann!

Das Team: Alex, Bill, Gil, Graham und Norrie

Warum das wichtig ist

Die meisten typischen analytischen Workflows laufen letztendlich auf die Gruppierung von Daten hinaus. Ob es nun um die Berechnung der durchschnittlichen Bytes pro Host, das Zählen von Ereignissen pro Nutzer oder das Aggregieren von Metriken über Dimensionen hinweg geht, die Kernoperation ist immer dieselbe – Schlüssel werden Gruppen zugeordnet und laufende Aggregate aktualisiert.

In kleinem Maßstab funktioniert fast jede vernünftige Hashtabelle einwandfrei. Bei großer Skalierung (Hunderte Millionen Dokumente und Millionen verschiedener Gruppen) beginnen Details eine Rolle zu spielen. Auslastungsfaktoren, Sondierungsstrategie, Speicherlayout und Cache-Verhalten können den Unterschied zwischen linearer Leistung und einer Flut von Cache-Fehlern ausmachen.

Elasticsearch unterstützt diese Workloads seit Jahren und wir suchen stets nach Möglichkeiten, die Kernalgorithmen zu modernisieren. Daher haben wir einen neueren, von Schweizer Tabellen inspirierten Ansatz evaluiert und ihn auf die Art und Weise angewendet, wie ES|QL Statistiken berechnet.

Was genau sind Schweizer Tabellen?

Schweizer Tabellen sind eine Familie moderner Hash-Tabellen, die von Googles SwissTable popularisiert und später in Abseil und anderen Bibliotheken übernommen wurden.

Traditionelle Hash-Tabellen verbringen viel Zeit damit, Zeiger zu verfolgen oder Schlüssel zu laden, nur um festzustellen, dass sie nicht übereinstimmen. Das definierende Feature von Schweizer Tabellen ist die Fähigkeit, die meisten Anfragen mit einer winzigen, im Cache befindlichen Array-Struktur abzulehnen, die getrennt von Schlüsseln und Werten gespeichert wird und als Kontrollbytes bezeichnet wird, um den Speicherverkehr drastisch zu reduzieren.

Jedes Kontrollbyte repräsentiert einen einzelnen Slot und kodiert in unserem Fall zwei Dinge: ob der Slot leer ist und einen kurzen Fingerabdruck, der aus dem Hash abgeleitet wird. Diese Steuerbytes sind zusammenhängend im Speicher angeordnet, typischerweise in Gruppen von 16, was sie ideal für die SIMD-Verarbeitung (Single Instruction, Multiple Data).

Anstatt einen Slot nach dem anderen zu testen, scannen Schweizer Tabellen einen gesamten Kontrollbyte-Block mithilfe von Vektorinstruktionen. In einer einzigen Operation vergleicht die CPU den Fingerabdruck des eingehenden Schlüssels mit 16 Slots und filtert leere Einträge heraus. Nur bei den wenigen Kandidaten, die diesen Schnelltest überstehen, ist das Laden und Vergleichen der tatsächlichen Schlüssel erforderlich.

Dieses Design tauscht eine kleine Menge zusätzlicher Metadaten gegen eine viel bessere Cache-Lokalität und weitaus weniger zufällige Ladevorgänge ein. Wenn die Tabelle wächst und die Sondenketten länger werden, werden diese Eigenschaften immer wertvoller.

SIMD im Mittelpunkt

Der eigentliche Star der Show ist SIMD.

Die Steuerbytes sind nicht nur kompakt, sondern auch explizit für die Verarbeitung mit Vektorbefehlen konzipiert. Ein einzelner SIMD-Vergleich kann 16 Fingerabdrücke gleichzeitig überprüfen und verwandelt, was normalerweise eine Schleife wäre, in eine Handvoll breiter Operationen. Zum Beispiel:

In der Praxis bedeutet das:

• Weniger Zweige.
• Kürzere Testketten.
• Weniger Ladevorgänge aus Schlüssel- und Wertspeicher.
• Viel bessere Nutzung der Ausführungseinheiten der CPU.

Die meisten Suchvorgänge kommen nie über den Control-Byte-Scan hinaus. Wenn sie das tun, ist die verbleibende Arbeit zielgerichtet und vorhersehbar. Das ist genau die Art von Arbeitslast, für die moderne CPUs gut geeignet sind.

SIMD unter der Haube

Für Leser, die gerne einen Blick hinter die Kulissen werfen, hier eine Erklärung, was beim Einfügen eines neuen Schlüssels in die Tabelle passiert. Wir verwenden die Panama Vector API mit 128-Bit-Vektoren und bearbeiten somit 16 Kontrollbytes parallel.

Der folgende Ausschnitt zeigt den Code, der auf einem Intel Rocket Lake mit AVX-512 generiert wurde. Obwohl die Anweisungen diese Umgebung widerspiegeln, hängt das Design nicht von AVX-512 ab. Die gleichen hochstufigen Vektoroperationen werden auf anderen Plattformen mit gleichwertigen Befehlen (zum Beispiel AVX2, SSE oder NEON) ausgesendet.

; 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 

Jede Anweisung hat eine klare Rolle im Einfügeprozess:

• vmovdqu: Lädt 16 aufeinanderfolgende Steuerbytes in das 128-Bit-xmm0-Register.
• vpbroadcastb: Repliziert den 7-Bit-Fingerabdruck des neuen Schlüssels über alle Spuren des xmm1-Registers.
• vpcmpeqb: Vergleicht jedes Steuerbyte mit dem gesendeten Fingerabdruck und erstellt eine Maske mit möglichen Übereinstimmungen.
• kmovq + test: Verschiebt die Maske in ein allgemeines Register und überprüft schnell, ob ein Match existiert.

Schließlich entschieden wir uns dafür, Gruppen von jeweils 16 Kontrollbytes zu untersuchen, da Benchmarks zeigten, dass eine Erweiterung auf 32 oder 64 Bytes mit breiteren Registern keinen messbaren Leistungsvorteil brachte.

Integration in ES|QL

Die Einführung des Hashing im Schweizer Stil in Elasticsearch war nicht einfach ein direkter Ersatz. ES|QL stellt hohe Anforderungen an die Speicherverwaltung, die Sicherheit und die Integration mit dem Rest der Compute Engine.

Wir haben die neue Hash-Tabelle eng in die Speicherverwaltung von Elasticsearch integriert, einschließlich des Seitenrecyclers und der Abrechnung von Schutzschaltern, um sicherzustellen, dass die Zuweisungen sichtbar und begrenzt bleiben. Die Aggregationen von Elasticsearch werden dicht gespeichert und durch eine Gruppen-ID indexiert, wodurch das Speicherlayout kompakt und schnell für Iterationen bleibt und zudem bestimmte Leistungsoptimierungen durch zufälligen Zugriff ermöglicht werden.

Bei Byte-Schlüsseln mit variabler Länge wird der vollständige Hash zusammen mit der Gruppen-ID zwischengespeichert. Dadurch wird die Neuberechnung teurer Hash-Codes während der Sondierung vermieden und die Cache-Lokalität verbessert, indem zusammengehörige Metadaten nahe beieinander gehalten werden. Während des Rehashings können wir uns auf den zwischengespeicherten Hash und die Kontroll-Bytes verlassen, ohne die Werte selbst zu inspizieren, wodurch die Kosten für die Größenänderung niedrig gehalten werden.

Eine wichtige Vereinfachung in unserer Implementierung besteht darin, dass Einträge niemals gelöscht werden. Dadurch werden Tombstones (Markierungen zur Identifizierung zuvor belegter Steckplätze) überflüssig, und leere Steckplätze bleiben wirklich leer, was das Verhalten der Sonde weiter verbessert und Kontroll-Byte-Scans effizient macht.

Das Ergebnis ist ein Design, das sich nahtlos in das Ausführungsmodell von Elasticsearch einfügt und gleichzeitig die Leistungsmerkmale beibehält, die Schweizer Tabellen so attraktiv machen.

Wie ist die Performance?

Bei kleinen Kardinalitäten schneiden die Schweizer Tabellen in etwa gleich gut ab wie die bestehende Implementierung. Das ist zu erwarten: Bei kleinen Tabellen spielen Cache-Effekte eine geringere Rolle und es gibt wenig Optimierungsbedarf.

Mit zunehmender Kardinalität ändert sich das Bild schnell.

Die obige Heatmap zeigt die Zeitverbesserungsfaktoren für verschiedene Schlüsselgrößen (8, 32, 64 und 128 Byte) über Kardinalitäten von 1.000 bis 10.000.000 Gruppen hinweg. Mit zunehmender Kardinalität steigt der Verbesserungsfaktor stetig an und erreicht bei Gleichverteilungen Werte von bis zu 2–3x.

Dieser Trend entspricht genau dem, was die Konstruktion vorhersagt. Höhere Kardinalität führt zu längeren Prüfketten in traditionellen Hash-Tabellen, während die meisten Suchvorgänge nach wie vor in SIMD-freundlichen Kontroll-Byte-Blöcken gelöst werden.

Das Cache-Verhalten erzählt die Geschichte

Um die Beschleunigungen besser zu verstehen, haben wir denselben JMH-benchmarks unter Linux perf ausgeführt und Cache- sowie TLB-Statistiken erfasst.

Im Vergleich zur ursprünglichen Implementierung benötigt die Schweizer Version insgesamt etwa 60 % weniger Cache-Zugriffe. Die Last-Level-Cache-Ladevorgänge sinken um mehr als das Vierfache, und LLC-Ladefehler gehen um mehr als das Sechsfache zurück. Da LLC-Fehlzugriffe oft direkt in Hauptspeicherzugriffe übersetzt werden, erklärt diese Reduzierung allein einen großen Teil der End-to-End-Verbesserung.

Näher an der CPU beobachten wir weniger L1-Datencache-Fehler und fast 6x weniger TLB-Datenfehler, was auf eine engere räumliche Lokalität und besser vorhersagbare Speicherzugriffsmuster hindeutet.

Dies ist der praktische Nutzen von SIMD-freundlichen Kontrollbytes. Anstatt Schlüssel und Werte immer wieder von verstreuten Speicherplätzen zu laden, werden die meisten Suchvorgänge durch das Durchsuchen einer kompakten, im Cache befindlichen Struktur gelöst. Weniger berührter Speicher bedeutet weniger Fehltritte, und weniger Fehltritte bedeuten schnellere Abfragen.

Fazit

Indem wir einen Hashtabellenentwurf im Schweizer Stil verwendeten und uns stark auf SIMD-freundliche Sondierungen konzentrierten, erreichten wir 2–3-fache Beschleunigungen für ES|QL-Statistik-Workloads mit hoher Kardinalität sowie eine stabilere und vorhersehbarere Leistung.

Diese Arbeit zeigt, wie moderne CPU-fähige Datenstrukturen erhebliche Verbesserungen ermöglichen können, selbst bei bekannten Problemen wie Hash-Tabellen. Hier gibt es mehr Raum für Erkundungen, wie etwa zusätzliche Spezialisierungen von primitiven Typen und die Verwendung in anderen Pfaden mit hoher Kardinalität, wie Joins, die alle Teil der umfassenderen und fortlaufenden Bemühungen sind, die internen Abläufe von Elasticsearch kontinuierlich zu modernisieren.

Wenn Sie an den Details interessiert sind oder die Arbeit verfolgen möchten, schauen Sie sich diesen Pull Request und den Meta-Issue-Fortschritt auf Github an.

Viel Spaß beim Hashing!

Schließlich beeinflusst der gesamte Kontext die Reaktionen der KI. Was man hinein gibt, kommt auch wieder heraus trifft in diesem Fall zu.

In diesem Artikel stellen wir vor, was Kurzzeit- und Langzeitgedächtnis für KI-Agenten bedeuten, insbesondere:

• Der Unterschied zwischen Kurz- und Langzeitgedächtnis.
• Wie sie sich auf Retrieval-Augmented Generation (RAG) Techniken mit Vektordatenbanken wie Elasticsearch beziehen und warum ein sorgfältiges Gedächtnismanagement notwendig ist.
• Die Risiken der Vernachlässigung des Gedächtnisses, einschließlich Kontextüberlauf und Kontextvergiftung.
• Best Practices wie Kontextbereinigung, Zusammenfassung und Abruf nur relevanter Daten, damit das Gedächtnis eines Agenten sowohl nützlich als auch sicher bleibt.
• Abschließend werden wir darauf eingehen, wie das Gedächtnis in Systemen mit mehreren Agenten gemeinsam genutzt und weitergegeben werden kann, damit Agenten mithilfe von Elasticsearch problemlos zusammenarbeiten können.

Kurzzeit- versus Langzeitgedächtnis bei KI-Agenten

Das Kurzzeitgedächtnis eines KI-Agenten bezieht sich in der Regel auf den unmittelbaren Gesprächskontext oder -zustand – im Wesentlichen auf den aktuellen Chatverlauf oder die letzten Nachrichten in der aktiven Sitzung. Dies umfasst die letzte Anfrage des Nutzers und den jüngsten Nachrichtenaustausch. Es ähnelt den Informationen, die eine Person während eines Gesprächs im Kopf hat.

KI-Frameworks pflegen häufig dieses vorübergehende Gedächtnis als Teil des Agentenzustands (zum Beispiel durch die Verwendung eines Checkpointers, um den Konversationszustand zu speichern, wie in diesem Beispiel von LangGraph beschrieben). Das Kurzzeitgedächtnis ist sitzungsbezogen, das heißt, es existiert innerhalb einer einzelnen Diskussion oder Aufgabe und wird zurückgesetzt oder gelöscht, wenn diese Sitzung endet, es sei denn, sie wird explizit an anderer Stelle gespeichert. Ein Beispiel für ein sitzungsgebundenes Kurzzeitgedächtnis wäre der temporäre Chat, der in ChatGPT verfügbar ist.

Das Langzeitgedächtnis hingegen bezeichnet Informationen, die über Gespräche oder Sitzungen hinweg erhalten bleiben. Dies ist das Wissen, das ein Agent im Laufe der Zeit behält: Fakten, die er zuvor gelernt hat, Nutzerpräferenzen oder alle Daten, die wir ihm zum dauerhaften Speichern gegeben haben.

Das Langzeitgedächtnis wird in der Regel durch Speichern und Abrufen aus einer externen Quelle implementiert, z.B. einer Datei oder einer Vektordatenbank, die sich außerhalb des unmittelbaren Kontextfensters befindet. Im Gegensatz zum kurzfristigen Chatverlauf wird das Langzeitgedächtnis nicht automatisch in jeden Prompt einbezogen. Stattdessen muss der Agent es auf der Grundlage eines bestimmten Szenarios zurückrufen oder abrufen, wenn die entsprechenden Tools aufgerufen werden. In der Praxis könnte das Langzeitgedächtnis beispielsweise Nutzerprofilinformationen, frühere Antworten oder Analysen des Agenten oder eine Wissensdatenbank umfassen, die der Agent abfragen kann.

Nehmen Sie als Beispiel einen Reiseplaner-Agenten, bei dem das Kurzzeitgedächtnis Details der aktuellen Reiseanfrage (Daten, Ziel, Budget) und alle Folgefragen in diesem Chat enthält, während das Langzeitgedächtnis die allgemeinen Reisepräferenzen des Nutzers, vergangene Reisepläne und andere Fakten, die in vorherigen Sitzungen geteilt wurden, speichern könnte. Wenn der Nutzer später zurückkehrt, kann der Agent auf dieses Langzeitgedächtnis zurückgreifen (zum Beispiel, dass der Nutzer Strände und Berge liebt, über ein durchschnittliches Budget von 100.000 INR verfügt, eine Liste mit Zielen hat, die er besuchen möchte, und lieber Geschichte und Kultur als kinderfreundliche Attraktionen erleben möchte), sodass der Nutzer nicht jedes Mal als unbeschriebenes Blatt behandelt wird.

Das Kurzzeitgedächtnis (Chatverlauf) bietet unmittelbaren Kontext und Kontinuität, während das Langzeitgedächtnis einen umfassenderen Kontext bereitstellt, auf den der Agent bei Bedarf zurückgreifen kann. Die fortschrittlichsten KI-Agenten-Frameworks ermöglichen beides: Sie verfolgen aktuelle Dialoge, um den Kontext zu pflegen, und bieten Mechanismen, um Informationen in einem längerfristigen Repository nachzuschlagen oder zu speichern. Die Verwaltung des Kurzzeitgedächtnisses stellt sicher, dass es innerhalb des Kontextfensters bleibt, während die Verwaltung des Langzeitgedächtnisses dem Agenten hilft, die Antworten auf der Grundlage früherer Interaktionen und Personas zu fundieren.

Speicher und RAG im Kontext-Engineering

Wie geben wir einem KI-Agenten in der Praxis ein nützliches Langzeitgedächtnis?

Ein bedeutender Ansatz für das Langzeitgedächtnis ist das semantische Gedächtnis, das oft über Retrieval-Augmented Generation (RAG) implementiert wird. Dabei wird der LLM an einen externen Wissensspeicher oder einem vektorfähigen Datenspeicher wie Elasticsearch gekoppelt. Wenn das LLM Informationen benötigt, die über das hinausgehen, was im Prompt oder im integrierten Training enthalten ist, führt es eine semantische Suche in Elasticsearch durch und fügt die relevantesten Ergebnisse als Kontext in den Prompt ein. Auf diese Weise umfasst der effektive Kontext des Modells nicht nur das aktuelle Gespräch (Kurzzeitgedächtnis), sondern auch relevante, kurzfristig abgerufene Langzeitfakten. Das LLM stützt seine Reaktion dann sowohl auf eigene Schlussfolgerungen als auch auf die abgerufenen Informationen und kombiniert so effektiv Kurzzeitgedächtnis und Langzeitgedächtnis, um eine genauere, kontextbezogene Reaktion zu erzeugen.

Elasticsearch kann verwendet werden, um das Langzeitgedächtnis für KI-Agenten zu implementieren. Hier ist ein Beispiel dafür, wie der Kontext aus Elasticsearch für das Langzeitgedächtnis abgerufen werden kann.

Auf diese Weise „erinnert“ sich der Agent, indem er nach relevanten Daten sucht, anstatt alles in seinem begrenzten Prompt zu speichern, wo es zu verschiedenen Risiken kommen kann.

Die Verwendung von RAG mit Elasticsearch oder einem beliebigen Vektorspeicher bietet mehrere Vorteile:

Erstens erweitert es das Wissen des Modells über seinen Trainingsschnitt hinaus. Der Agent kann aktuelle Informationen oder domänenspezifische Daten abrufen, die das LLM möglicherweise nicht kennt. Dies ist besonders bei Fragen zu aktuellen Ereignissen oder speziellen Themen der Fall.

Zweitens hilft das Abrufen von Kontext nach Bedarf, Halluzinationen zu reduzieren, besonders da LLMs nicht auf proprietären oder hochspezialisierten Daten im Zusammenhang mit Nischenanwendungsfällen trainiert sind, was sehr wahrscheinlich Halluzinationen zur Folge hat. Damit das LLM nicht rät oder neue Informationen erfindet, da es durch die Bewertung einen Anreiz erhalten hat, wie in dem kürzlich erschienenen OpenAI-Paper (Why Language Models Hallucinate) hervorgehoben wird, kann das Modell durch faktische Referenzen aus Elasticsearch geerdet werden. Natürlich hängt das LLM von der Zuverlässigkeit der Daten im Vektorspeicher ab, damit Fehlinformationen wirklich verhindert und die relevanten Daten gemäß den Kernrelevanzmaßen abgerufen werden.

Drittens ermöglicht RAG es Agenten, mit Wissensdatenbanken zu arbeiten, die weit größer sind als alles, was man jemals in einen Prompt einfügen könnte. Anstatt ganze Dokumente, wie lange Forschungsarbeiten oder politische Dokumente, in das Kontextfenster zu schieben und das Risiko einer Überlastung oder Kontextvergiftung durch irrelevante Informationen bei Schlussfolgerungen des Modells einzugehen, verlässt sich RAG auf Chunking. Große Dokumente werden in kleinere, semantisch bedeutungsvolle Teile zerlegt, und das System ruft nur die wenigen für die Anfrage relevantesten Abschnitte ab. Auf diese Weise benötigt das Modell keinen Kontext von einer Million Token, um kompetent zu wirken, sondern lediglich Zugriff auf die richtigen Teile eines viel größeren Korpus.

Es ist erwähnenswert, dass mit dem Wachstum der LLM-Fenster (einige Modelle unterstützen inzwischen Hunderttausende oder sogar Millionen von Token) eine Debatte darüber entstanden ist, ob RAG „tot“ ist. Warum nicht alle Daten in den Prompt einfügen? Wenn Sie das ähnlich sehen, lesen Sie diesen wunderbaren Artikel meiner Kollegen Jeffrey Rengifo und Eduard Martin: Longer context ≠ better: Why RAG still matters. Dies vermeidet das „Was man hinein gibt, kommt auch wieder heraus“-Problem: Das LLM bleibt auf die wenigen wichtigen Teile fokussiert, anstatt sich durch Rauschen zu arbeiten.

Nichtsdestotrotz bietet die Integration von Elasticsearch oder einem beliebigen Vektorspeicher in eine KI-Agentenarchitektur ein Langzeitgedächtnis. Der Agent speichert Wissen extern und ruft es bei Bedarf als Gedächtniskontext ab. Dies könnte als Architektur implementiert werden, bei der der Agent nach jeder Nutzeranfrage in Elasticsearch nach relevanten Informationen sucht und dann die Top-Ergebnisse an den Prompt anhängt, bevor er das LLM aufruft. Die Reaktion kann auch wieder in das Langzeitgedächtnis gespeichert werden, wenn sie nützliche neue Informationen enthält (wodurch ein Feedback-Loop des Learnings entsteht). Durch die Nutzung eines solchen abrufbasierten Gedächtnisses bleibt der Agent informiert und auf dem neuesten Stand, ohne alles, was er weiß, in jeden Prompt quetschen zu müssen, obwohl das Kontextfenster eine Million Token unterstützt. Diese Technik ist ein Eckpfeiler des Kontext-Engineerings und kombiniert die Stärken von Information Retrieval und generativer KI.

Hier ist ein Beispiel für einen verwalteten In-Memory-Gesprächszustand, der das Checkpoint-System von LangGraph für das Kurzzeitgedächtnis während der Sitzung verwendet. (Mehr dazu in unserer unterstützenden Context Engineering-App.)

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

So werden Checkpoints gespeichert:

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

Für das Langzeitgedächtnis führen wir mit Elasticsearch eine semantische Suche durch, um relevante vorherige Gespräche mithilfe von Vektoreinbettungen abzurufen, nachdem wir die Checkpoints in Elasticsearch zusammengefasst und indexiert haben.

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)}"

Nachdem wir untersucht haben, wie Kurzzeit- und Langzeitgedächtnis mithilfe der Checkpoints von LangGraph in Elasticsearch indexiert und abgerufen werden, wollen wir uns etwas Zeit nehmen, um zu verstehen, warum das Indexieren und Speichern der kompletten Konversationen riskant sein kann.

Risiken der fehlenden Verwaltung des Kontextgedächtnisses

Da wir viel über Kontextgestaltung sowie Kurzzeit- und Langzeitgedächtnis sprechen, ist es wichtig, zu verstehen, was passiert, wenn wir Gedächtnis und Kontext eines Agenten nicht effektiv verwalten.

Leider kann vieles schiefgehen, wenn der Kontext einer KI extrem lang wird oder falsche Informationen enthält. Wenn die Kontextfenster größer werden, tauchen neue Fehlerarten auf, zum Beispiel:

• Kontextvergiftung
• Kontextablenkung
• Kontextverwirrung
• Kontextkonflikt
• Kontextlecks und Wissenskonflikte
• Halluzinationen und Fehlinformationen

Werfen wir einen Blick auf diese Probleme und andere Risiken, die durch schlechtes Kontextmanagement entstehen:

Kontextvergiftung

Kontextvergiftung bezieht sich darauf, wenn falsche oder schädliche Informationen in den Kontext gelangen und die nachfolgenden Ausgänge des Modells „vergiften“. Ein häufiges Beispiel ist eine Halluzination des Modells, die als Tatsache behandelt und in den Gesprächsverlauf eingefügt wird. Das Modell könnte dann in späteren Reaktionen auf diesem Fehler aufbauen und den Fehler verstärken. In iterativen Agenten-Loops kann eine falsche Information, sobald sie in den gemeinsamen Kontext gelangt (zum Beispiel in einer Zusammenfassung der Arbeitsnotizen des Agenten), immer wieder verstärkt werden.

Forscher von DeepMind haben dies bei der Veröffentlichung des Gemini 2.5-Berichts (TL;DR, mehr dazu hier) bei einem langjährig Pokémon-spielenden Agenten beobachtet: Wenn der Agent einen falschen Spielzustand halluzinierte und dieser in seinem Kontext (seinem Gedächtnis für Ziele) aufgezeichnet wurde, bildete der Agent unsinnige Strategien um ein unmögliches Ziel herum und blieb stecken. Mit anderen Worten: Ein vergiftetes Gedächtnis kann den Agenten auf unbestimmte Zeit auf den falschen Weg bringen.

Kontextvergiftung kann aus Versehen oder auch böswillig geschehen, zum Beispiel durch Prompt-Injection-Angriffe, bei denen ein Nutzer oder Dritter eine versteckte Anweisung oder falsche Tatsache einschleust, die der Agent dann erinnert und befolgt.

Empfohlene Gegenmaßnahmen:

Basierend auf Einblicken von Wiz, Zerlo und Anthropic konzentrieren sich Gegenmaßnahmen gegen Kontextvergiftung darauf, zu verhindern, dass falsche oder irreführende Informationen in den Prompt, das Kontextfenster oder die Abrufpipeline eines LLM gelangen. Wichtige Schritte umfassen:

• Überprüfen Sie den Kontext regelmäßig: Überwachen Sie die Konversation oder den abgerufenen Text auf alles Verdächtige oder Schädliche, nicht nur den anfänglichen Prompt.
• Verwenden Sie vertrauenswürdige Quellen: Bewerten oder kennzeichnen Sie Dokumente basierend auf ihrer Glaubwürdigkeit, damit das System zuverlässige Informationen bevorzugt und Daten mit niedriger Bewertung ignoriert.
• Achten Sie auf ungewöhnliche Daten: Verwenden Sie Tools, die ungewöhnliche, unpassende oder manipulierte Inhalte erkennen, und entfernen Sie diese, bevor das Modell sie verwendet.
• Filtern Sie Eingänge und Ausgänge: Integrieren Sie Schutzvorkehrungen, damit schädliche oder irreführende Texte nicht so leicht in das System gelangen oder vom Modell wiederholt werden können.
• Halten Sie das Modell mit sauberen Daten auf dem neuesten Stand: Aktualisieren Sie das System regelmäßig mit verifizierten Informationen, um etwaigen fehlerhaften Daten entgegenzuwirken, die durchgerutscht sind.
• Human-in-the-loop: Lassen Sie wichtige Ausgänge von Menschen überprüfen oder mit bekannten, vertrauenswürdigen Quellen vergleichen.

Auch einfache Nutzergewohnheiten helfen, wie das Zurücksetzen langer Chats, das Teilen nur relevanter Informationen, das Aufteilen komplexer Aufgaben in kleinere Schritte und die Pflege sauberer Notizen außerhalb des Modells.

In Kombination bilden diese Maßnahmen einen mehrschichtigen Schutz, der LLMs vor Kontextvergiftung schützt und die Genauigkeit und Vertrauenswürdigkeit der Ausgänge gewährleistet.

Ohne Gegenmaßnahmen, wie hier erwähnt, könnte sich ein Agent an Anweisungen erinnern, z. B. vorherige Richtlinien zu ignorieren oder unwichtige Fakten, die ein Angreifer eingefügt hat, was zu schädlichen Ausgängen führen könnte.

Kontextablenkung

Kontextablenkung liegt vor, wenn ein Kontext so lang wird, dass sich das Modell zu sehr auf den Kontext konzentriert und vernachlässigt, was es während des Trainings gelernt hat. In extremen Fällen ähnelt dies katastrophalem Vergessen. Das heißt, das Modell „vergisst“ effektiv sein zugrunde liegendes Wissen und konzentriert sich übermäßig auf die Informationen, die ihm präsentiert werden. Frühere Studien haben gezeigt, dass LLM oft den Fokus verlieren, wenn der Prompt extrem lang ist.

Der Gemini 2.5-Agent zum Beispiel unterstützte ein Million-Token-Fenster, aber sobald sein Kontext über einen bestimmten Punkt hinauswuchs (etwa 100.000 Token in einem Experiment), begann er, sich darauf zu fixieren, seine früheren Aktionen zu wiederholen , anstatt neue Lösungen zu finden. In gewisser Weise wurde der Agent zum Gefangenen seiner umfangreichen Geschichte. Er betrachtete kontinuierlich seinen langen Log früherer Aktionen (den Kontext) und ahmte diese nach, anstatt sein zugrunde liegendes Trainingswissen zu nutzen, um frische und neuartige Strategien zu entwickeln.

Das ist kontraproduktiv. Wir wollen, dass das Modell den relevanten Kontext zur Unterstützung des Denkens nutzt, nicht aber seine Denkfähigkeit außer Kraft setzt. Bemerkenswerterweise zeigen selbst Modelle mit riesigen Fenstern diesen Kontextverfall: Ihre Leistung verschlechtert sich ungleichmäßig, wenn mehr Token hinzugefügt werden. Es scheint ein Aufmerksamkeitsbudget zu geben. Wie Menschen mit begrenztem Gedächtnis hat ein LLM begrenzte Kapazitäten, sich um Token zu kümmern, und wenn dieses Budget überlastet ist, sinken Präzision und Fokus.

Kontextablenkung verhindern Sie durch Chunking, die Entwicklung der richtigen Informationen, regelmäßige Kontextzusammenfassungen sowie Bewertungs- und Überwachungstechniken zur Messung der Genauigkeit der Reaktion mittels Scoring.

Diese Methoden halten das Modell sowohl im relevanten Kontext als auch in seinem zugrundeliegenden Training verankert, wodurch das Risiko von Ablenkungen reduziert und die Gesamtqualität des Schlussfolgerns verbessert wird.

Kontextverwirrung

Kontextverwirrung liegt vor, wenn überflüssiger Inhalt im Kontext vom Modell verwendet wird, um eine Reaktion von geringer Qualität zu generieren. Ein gutes Beispiel ist, einem Agenten eine große Auswahl an Tools oder API-Definitionen zu geben, die er verwenden könnte. Wenn viele dieser Tools nichts mit der aktuellen Aufgabe zu tun haben, kann das Modell dennoch versuchen, sie in unangemessener Weise zu verwenden, einfach weil sie im Kontext vorhanden sind. Experimente haben gezeigt, dass die Bereitstellung weiterer Tools oder Dokumente die Leistung beeinträchtigen kann, wenn sie nicht alle benötigt werden. Der Agent beginnt Fehler zu machen, z. B. die falsche Funktion aufzurufen oder auf irrelevanten Text zu verweisen.

In einem Fall scheiterte ein kleines Llama 3.1 8B Modell an einer Aufgabe, wenn es 46 Tools zu berücksichtigen hatte, war aber erfolgreich, wenn es nur 19 Tools gab. Die zusätzlichen Tools sorgten für Verwirrung, obwohl der Kontext innerhalb der Längenbeschränkungen lag. Das zugrunde liegende Problem ist, dass alle Informationen in der Aufforderung vom Modell bearbeitet werden. Wenn es nicht weiß, dass es etwas ignorieren soll, könnte genau dieser Punkt seinen Ausgang auf unerwünschte Weise beeinflussen. Irrelevante Teile können „einen Teil der Aufmerksamkeit des Modells stehlen“ und es in die Irre führen (zum Beispiel könnte ein irrelevantes Dokument den Agenten dazu veranlassen, eine andere Frage zu beantworten als die gestellte). Kontextverwirrung äußert sich oft darin, dass das Modell eine minderwertige Reaktion produziert, die einen nicht zusammenhängenden Kontext integriert. Mehr dazu in der Forschungsarbeit: Less is More: Optimizing Function Calling for LLM Execution on Edge Devices.

Es erinnert uns daran, dass mehr Kontext nicht immer besser ist, vor allem, wenn er nicht nach Relevanz kuratiert ist.

Kontextkonflikt

Kontextkonflikte treten auf, wenn Teile des Kontexts sich widersprechen, was interne Abweichungen verursacht, die die Argumentation des Modells entgleisen lassen. Ein Konflikt kann auftreten, wenn der Agent mehrere Informationen ansammelt, die miteinander im Konflikt stehen.

Stellen Sie sich zum Beispiel einen Agenten vor, der Daten aus zwei Quellen abruft: Laut der einen startet Flug A um 17 Uhr, laut der anderen startet Flug A um 18 Uhr. Wenn beide Fakten im Kontext vorkommen, hat das mangelhafte Modell keine Möglichkeit zu wissen, welche richtig ist. Es kann verwirrt werden oder eine falsche oder unähnliche Antwort liefern.

Kontextkonflikte treten auch häufig in Mehrrundengesprächen auf, bei denen die früheren Antworten des Modells noch im Kontext verweilen, zusammen mit später verfeinerten Informationen.

Eine Studie von Microsoft und Salesforce zeigt, dass die Endgenauigkeit deutlich sinkt, wenn man eine komplexe Abfrage in mehrere Chatbot-Durchläufe aufteilt (wobei Details schrittweise hinzugefügt werden). Warum ist das so? Weil die frühen Durchläufe partielle oder inkorrekte Zwischenantworten des Modells enthalten und diese im Kontext verbleiben. Wenn das Modell später versucht, mit allen Informationen zu antworten, enthält sein Gedächtnis immer noch diese falschen Versuche, die mit den korrigierten Informationen kollidieren und es vom Kurs abbringen. Im Grunde genommen widerspricht sich der Kontext des Gesprächs selbst. Das Modell kann versehentlich einen veralteten Kontext (aus einem früheren Durchlauf) verwenden, der nach dem Hinzufügen neuer Informationen nicht mehr zutrifft.

In Agentensystemen sind Kontextkonflikte besonders gefährlich, weil ein Agent Ausgänge verschiedener Tools oder Unteragenten kombinieren kann. Wenn diese Ausgänge nicht übereinstimmen, ist der aggregierte Kontext unbeständig. Der Agent könnte dann stecken bleiben oder sinnlose Ergebnisse produzieren, wenn er versucht, die Widersprüche in Einklang zu bringen. Um Kontextkonflikte zu verhindern, muss sichergestellt werden, dass der Kontext aktuell und konstant ist, zum Beispiel dass alle veralteten Informationen gelöscht oder aktualisiert wurden und Quellen, die nicht auf Konstanz überprüft wurden, nicht miteinander kombiniert werden.

Kontextlecks und Wissenskonflikte

In Systemen, in denen mehrere Agenten oder Nutzer einen Speicher teilen, besteht das Risiko, dass Informationen auf andere Kontexte übergehen.

Wenn sich beispielsweise die Daten-Einbettungen zweier separater Nutzer in derselben Vektordatenbank ohne ordnungsgemäße Zugriffskontrolle befinden, könnte ein Agent, der die Anfrage von Nutzer A beantwortet, versehentlich einen Teil des Speichers von Nutzer B abrufen. Diese kontextübergreifenden Lecks können private Informationen offenlegen oder einfach für Verwirrung bei Reaktionen sorgen.

Laut den OWASP Top 10 für LLM-Anwendungen müssen Multi-Tenant-Vektordatenbanken gegen solche Lecks schützen:

Laut LLM08:2025 Vector and Embedding Weaknesses, ist eines der häufigsten Risiken die Leckage von Kontextinformationen:

In Multi-Tenant-Umgebungen, in denen mehrere Klassen von Nutzern oder Anwendungen dieselbe Vektordatenbank nutzen, besteht die Gefahr von Kontextlecks zwischen Nutzern oder Abfragen. Fehler bei der Datenföderation können auftreten, wenn Daten aus mehreren Quellen einander widersprechen. Das kann auch passieren, wenn ein LLM altes Wissen, das es während des Trainings gelernt hat, nicht mit den neuen Daten aus Retrieval Augmentation ersetzen kann.

Ein weiterer Aspekt ist, dass ein LLM Schwierigkeiten haben könnte, sein integriertes Wissen mit neuen Informationen aus dem Gedächtnis zu überschreiben. Wenn das Modell auf eine bestimmte Tatsache trainiert wurde und der abgerufene Kontext das Gegenteil aussagt, kann das Modell verwirrt sein, welcher Aussage es vertrauen soll. Ohne eine geeignete Konzeption könnte der Agent Kontexte verwechseln oder altes Wissen nicht mit neuen Erkenntnissen aktualisieren, was zu veralteten oder falschen Antworten führen könnte.

Halluzinationen und Fehlinformationen

Die Halluzination (das LLM erfindet plausibel klingende, aber falsche Informationen) ist zwar auch ohne lange Kontexte ein bekanntes Problem, aber schlechtes Gedächtnismanagement kann es verstärken.

Wenn im Gedächtnis des Agenten eine entscheidende Tatsache fehlt, kann das Modell die Lücke einfach mit einer Vermutung füllen, und wenn diese Vermutung dann in den Kontext einfließt (ihn vergiftet), bleibt der Fehler bestehen.

Der OWASP LLM-Sicherheitsbericht (LLM09:2025 Misinformation) hebt Fehlinformationen als Kernschwachstelle hervor: LLMs können zuverlässige, aber erfundene Antworten liefern, und Nutzer könnten ihnen zu sehr vertrauen. Ein Agent mit einem schlechten oder veralteten Langzeitgedächtnis könnte getrost etwas zitieren, das im letzten Jahr gestimmt hat, jetzt aber falsch ist, es sei denn, sein Gedächtnis wird auf dem neuesten Stand gehalten.

Eine übermäßige Abhängigkeit vom Ausgang der KI (entweder durch den Nutzer oder den Agenten selbst in einer Schleife) kann dies verschlimmern. Wenn niemand die Informationen im Gedächtnis überprüft, kann der Agent Unwahrheiten ansammeln. Dies ist der Grund, warum RAG oft verwendet wird, um Halluzinationen zu reduzieren: Durch den Abruf einer maßgeblichen Quelle muss das Modell keine Fakten erfinden. Wenn Sie jedoch ein falsches Dokument abrufen (z. B. eines, das Fehlinformationen enthält) oder wenn eine frühe Halluzination nicht entfernt wird, kann das System diese Fehlinformation in seinen Aktionen weitergeben.

Fazit: Wird das Gedächtnis nicht verwaltet, kann dies zu falschen und irreführenden Ausgängen führen, was womöglich Schäden zur Folge hat, besonders wenn viel auf dem Spiel steht (z. B. schlechte Ratschläge in einem Finanz- oder medizinischen Bereich). Ein Agent benötigt Mechanismen, um seinen Speicherinhalt zu überprüfen oder zu korrigieren, anstatt bedingungslos allem zu vertrauen, was im Kontext steht.

Zusammengefasst ist es kein Erfolgsrezept, einem KI-Agenten ein unendlich langes Gedächtnis zu geben oder alles Mögliche in seinen Kontext zu werfen.

Best Practices für das Gedächtnismanagement in LLM-Anwendungen

Um die oben genannten Fallstricke zu vermeiden, haben Entwickler und Forscher eine Reihe von Best Practices für die Verwaltung von Kontext und Gedächtnis in KI-Systemen entwickelt. Diese Praktiken zielen darauf ab, den Arbeitskontext der KI übersichtlich, relevant und auf dem neuesten Stand zu halten - hier sind einige der wichtigsten Strategien und Beispiele dafür, wie sie helfen können.

RAG: Gezielten Kontext verwenden

Ein Großteil der RAG wurde bereits im vorangegangenen Abschnitt behandelt, so dass dieser Abschnitt eine kurze Zusammenfassung praktischer Hinweise bietet:

• Verwenden Sie gezieltes Abrufen, nicht Bulk-Loading: Rufen Sie nur die relevantesten Teile ab, anstatt ganze Dokumente oder vollständige Konversationsverläufe in den Prompt zu laden.
• Behandeln Sie RAG wie einen bedarfsgerechten Gedächtnisabruf: Rufen Sie den Kontext nur dann ab, wenn er benötigt wird, anstatt bei jedem Abruf alles zu verwenden.
• Bevorzugen Sie relevanzbasierte Abrufstrategien: Ansätze wie Top-k semantische Suche, Reciprocal Rank Fusion oder Tool-Loadout-Filterung helfen, Rauschen zu reduzieren und die Verankerung zu verbessern.
• Größere Kontextfenster beseitigen nicht die Notwendigkeit von RAG: Zwei hochrelevante Absätze sind fast immer effektiver als 20 lose zusammenhängende Seiten.

Allerdings geht es bei RAG nicht darum, mehr Kontext, sondern den richtigen Kontext hinzuzufügen.

Tool-Loadout

Tool-Loadout bedeutet, einem Modell nur die Tools zu geben, die es tatsächlich für eine Aufgabe benötigt. Der Begriff stammt aus dem Gaming-Bereich: Sie wählen ein Loadout, das zur Situation passt. Zu viele Tools verlangsamen den Fortschritt, die falschen führen zum Scheitern. LLM verhalten sich genauso, wie das Forschungspaper Less is more besagt. Sobald Sie ~30 Tools durchgegeben haben, überschneiden sich die Beschreibungen und das Modell ist verwirrt. Nach etwa 100 Tools ist ein Ausfall nahezu garantiert. Das ist kein Problem mit dem Kontextfenster, sondern eine Kontextverwirrung.

Eine einfache und effektive Lösung ist RAG-MCP. Anstatt jedes Tool in den Prompt zu laden, werden die Tool-Beschreibungen in einer Vektordatenbank gespeichert und nur die relevantesten werden pro Anfrage abgerufen. In der Praxis hält das den Loadout klein und konzentriert, die Prompts werden drastisch verkürzt und die Genauigkeit der Tool-Auswahl kann um das bis zu Dreifache verbessert werden.

Kleinere Modelle stoßen noch früher an diese Grenze. Die Forschung zeigt, dass ein 8B-Modell mit Dutzenden von Tools versagt, jedoch Erfolg zeigt, sobald das Loadout reduziert wird. Durch die dynamische Auswahl von Tools, in Fällen zunächst mit einem LLM, und die Überlegung, was benötigt wird, kann die Leistung um 44 % gesteigert werden, während gleichzeitig Stromverbrauch und Latenz reduziert werden. Daraus ist zu erkennen, dass die meisten Agenten nur wenige Tools benötigen, mit dem Wachstum Ihres Systems jedoch Tool-Loadout und RAG-MCP zu erstrangigen Designentscheidungen werden.

Kontextbereinigung: Begrenzung der Länge des Chatverlaufs

Wenn sich ein Gespräch über mehrere Ausführungen erstreckt, kann der angesammelte Chatverlauf zu viel Platz einnehmen, was zu einem Kontextüberlauf führt oder das Modell zu sehr abgelenkt wird.

Trimming bedeutet, programmatisch weniger wichtige Teile des Dialogs zu entfernen oder zu kürzen, während er wächst. Eine einfache Form besteht darin, die ältesten Runden der Konversation abzubrechen, wenn ein bestimmtes Limit erreicht ist, sodass nur die letzten N Nachrichten gespeichert werden. Eine ausgefeiltere Bereinigung könnte irrelevante Abschweifungen oder frühere Anweisungen entfernen, die nicht mehr benötigt werden. Das Ziel ist es, dass das Kontextfenster übersichtlich bleibt, ohne alte Nachrichten.

Wenn der Agent beispielsweise vor 10 Ausführungen ein Teilproblem gelöst hat und seitdem fortgefahren wurde, könnten wir diesen Teil des Verlaufs aus dem Kontext löschen (vorausgesetzt, er wird nicht mehr benötigt). Viele Chat-basierte Implementierungen bieten ein fortlaufendes Fenster mit den neuesten Nachrichten.

Beim Trimming handelt es sich im Grunde um das „Vergessen“ der ersten Teile eines Gesprächs, sobald diese zusammengefasst wurden oder als irrelevant erachtet werden. Dadurch verringern wir das Risiko von Kontextüberlauffehlern und reduzieren auch die Kontextablenkung, sodass das Modell nicht von alten oder themenfremden Inhalten gestört und abgelenkt wird. Dieser Ansatz ähnelt sehr der Art und Weise, wie Menschen sich vielleicht nicht an jedes Wort aus einem einstündigen Vortrag erinnern, aber die Höhepunkte im Gedächtnis behalten.

Falls Sie die Kontextbereinigung noch nicht ganz verstanden haben, kann, wie der Autor Drew Breunig hier hervorhebt, die Verwendung des Provence-Modells (naver/provence-reranker-debertav3-v1), ein leichter (1,75 GB), effizienter und genauer Kontext-Pruners für die Beantwortung von Fragen gut geeignet sein. Er kann große Dokumente auf nur den relevantesten Text für eine bestimmte Abfrage reduzieren. Sie können ihn in bestimmten Abständen aufrufen.

So rufen wir das Provence-Reranker-Modell in unserem Code auf, um den Kontext zu bereinigen:

# 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

Wir verwenden das Provence-Reranker-Modell (naver/provence-reranker-debertav3-v1), um die Satzrelevanz zu bewerten. Durch eine schwellenwertbasierte Filterung werden Sätze oberhalb der Relevanzschwelle beibehalten. Außerdem führen wir einen Fallback-Mechanismus ein, bei dem wir zum ursprünglichen Kontext zurückkehren, wenn die Bereinigung fehlschlägt. Zu guter Letzt verfolgt das Statistik-Logging den Reduktionsanteil im ausführlichen Modus.

Kontextzusammenfassung: Fassen Sie ältere Informationen zusammen, anstatt sie ganz wegzulassen

Die Zusammenfassung ist eine Ergänzung zum Trimming. Wenn der Verlauf oder die Wissensdatenbank zu umfangreich wird, können Sie das LLM einsetzen, um eine kurze Zusammenfassung der wichtigen Punkte zu erstellen und diese anstelle des vollständigen Inhalts verwenden, so wie in unserem obigen Code geschehen.

Wenn zum Beispiel ein KI-Assistent ein Gespräch mit 50 Runden geführt hat, könnte das System, anstatt alle 50 Runden an das Modell in Runde 51 zu senden (was wahrscheinlich nicht passt), die Runden 1–40 übernehmen, das Modell diese in einem Absatz zusammenfassen lassen und dann nur diese Zusammenfassung plus die letzten 10 Runden im nächsten Prompt bereitstellen. Auf diese Weise weiß das Modell immer noch, was besprochen wurde, ohne jedes Detail zu benötigen. Frühe Chatbot-Nutzer taten dies manuell, indem sie fragten: „Können Sie zusammenfassen, worüber wir bisher gesprochen haben?“ und dann in einer neuen Sitzung mit der Zusammenfassung fortfuhren. Nun kann dies automatisiert werden. Zusammenfassungen sparen nicht nur Platz im Kontextfenster, sondern können auch Kontextverwirrung und -ablenkung verringern, indem zusätzliche Details entfernt und nur die wichtigsten Fakten erhalten bleiben.

Hier ist unsere Vorgehensweise: Wir nutzen OpenAI-Modelle (Sie können beliebige LLMs verwenden), um den Kontext zu verdichten und gleichzeitig alle relevanten Informationen zu bewahren, wodurch Redundanz und Duplikate vermieden werden.

# 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

Wenn der Kontext zusammengefasst wird, ist es weniger wahrscheinlich, dass das Modell von unwichtigen Details oder vergangenen Fehlern überwältigt wird (vorausgesetzt, die Zusammenfassung ist korrekt).

Die Zusammenfassung muss jedoch sorgfältig erfolgen. Eine schlechte Zusammenfassung könnte ein entscheidendes Detail auslassen oder sogar zu einem Fehler führen. Es ist im Grunde eine weitere Aufforderung an das Modell („fassen Sie das zusammen“), sodass es zu Halluzinationen oder Nuancierungen kommen kann. Es empfiehlt sich, bei der Zusammenfassung schrittweise vorzugehen und möglicherweise autorisierte Fakten nicht in die Zusammenfassung einzubinden.

Dennoch hat sich dies als sehr nützlich erwiesen. Im Gemini-Agenten-Szenario war die Zusammenfassung des Kontexts alle ~100.000 Token eine Möglichkeit, der Wiederholungstendenz des Modells entgegenzuwirken. Die Zusammenfassung wirkt wie ein komprimierter Speicher des Gesprächs oder der Daten. Als Entwickler können wir dies umsetzen, indem ein Agent periodisch eine Zusammenfassungsfunktion (vielleicht ein kleineres LLM oder eine eigene Routine) aus dem Gesprächsverlauf oder einem langen Dokument aufruft. Die resultierende Zusammenfassung ersetzt den Originalinhalt im Prompt. Diese Taktik wird häufig verwendet, um Kontexte in Grenzen zu halten und die Informationen zusammenzufassen.

Kontextquarantäne: Kontexte nach Möglichkeit isolieren

Dies ist insbesondere bei komplexen Agentensystemen oder mehrstufigen Workflows relevant. Die Idee der Kontextsegmentierung besteht darin, eine große Aufgabe in kleinere, isolierte Aufgaben aufzuteilen, von denen jede ihren eigenen Kontext hat, um nicht zu viel Kontext mit umfassendem Inhalt anzuhäufen. Jeder Unteragent oder jede Teilaufgabe bearbeitet einen Bereich des Problems in einem fokussierten Kontext, anschließend integriert ein übergeordneter Agent, Supervisor oder Koordinator die Ergebnisse.

Die Forschungsstrategie von Anthropic verwendet mehrere Unteragenten, die jeweils einen anderen Aspekt einer Frage mit eigenen Kontextfenstern untersuchen, und einen Leitagenten, der die zusammengefassten Ergebnisse dieser Unteragenten ausliest. Dieser parallele, modulare Ansatz bedeutet, dass kein einzelnes Kontextfenster zu groß wird. Es reduziert auch die Wahrscheinlichkeit, dass irrelevante Informationen sich vermischen, jeder Thread bleibt beim Thema (keine Kontextverwirrung) und trägt keine unnötige Last, wenn er seine spezifische Teilfrage beantwortet. In gewisser Weise ist es, als würde man separate Gedankenstränge ausführen, die nur ihre Ergebnisse teilen, nicht ihren gesamten Denkprozess.

In Systemen mit mehreren Agenten ist dieser Ansatz unerlässlich. Wenn Agent A Aufgabe A und Agent B Aufgabe B bearbeitet, besteht für keinen Agenten der Grund, den vollständigen Kontext des anderen zu verwenden, es sei denn, dies ist unbedingt erforderlich. Stattdessen können Agenten nur die notwendigen Informationen austauschen. Zum Beispiel kann Agent A eine konsolidierte Zusammenfassung seiner Ergebnisse an Agent B über einen Supervisor-Agenten weitergeben, während jeder Unteragent seinen ganz eigenen Kontext-Thread pflegt. Bei diesem System ist kein menschliches Eingreifen erforderlich. Es basiert auf einem Überwachungsagenten mit aktivierten Tools, die einen minimalen und kontrollierten Kontextaustausch ermöglichen.

Dennoch kann die Gestaltung Ihres Systems, sodass Agenten oder Tools mit minimaler notwendiger Kontextüberschneidung arbeiten, die Klarheit und Leistung erheblich verbessern. Das kann man sich wie einen Microservices für KI vorstellen. Jede Komponente befasst sich mit ihrem Kontext, und Sie leiten Nachrichten zwischen ihnen auf kontrollierte Weise weiter, anstatt in einem monolithischen Kontext. Diese Best Practices werden oft in Kombination miteinander verwendet. Außerdem verleiht es Ihnen die Flexibilität, überflüssige Verläufe zu kürzen, wichtige ältere Nachrichten oder Unterhaltungen zusammenzufassen, detaillierte Protokolle für langfristigen Kontext an Elasticsearch zu übergeben und bei Bedarf mit Abruf alles Relevante zurückzuholen.

Wie hier erwähnt, ist das Leitprinzip, dass der Kontext eine begrenzte und wertvolle Ressource ist. Jeder Token im Prompt sollte sein Geld wert sein, d.h. er sollte zur Qualität des Ausgangs beitragen. Wenn etwas im Gedächtnis seine Funktion nicht erfüllt (oder schlimmer noch, aktiv Verwirrung stiftet), dann sollte es bereinigt, zusammengefasst oder beseitigt werden.

Als Entwickler können wir nun den Kontext genauso programmieren wie den Code und entscheiden, welche Informationen einbezogen, wie sie formatiert und wann sie weggelassen oder aktualisiert werden sollen. Mithilfe dieser Methoden können wir die LLM-Agenten mit dem dringend benötigten Kontext versorgen, um Aufgaben auszuführen, ohne den zuvor beschriebenen Fehlermodi zum Opfer zu fallen. Daraus resultieren Agenten, die sich an nötige Aufgaben erinnern, unnötige Aufgaben vergessen und alles Nötige gerade rechtzeitig abrufen.

Fazit

Erinnerungsvermögen wird Agenten nicht einfach hinzufügt, es muss entwickelt werden. Das Kurzzeitgedächtnis ist der Notizblock für die Arbeit des Agenten, das Langzeitgedächtnis sein dauerhafter Wissensspeicher. RAG dient als Verbindung zwischen den beiden und verwandelt einen passiven Datenspeicher wie Elasticsearch in einen aktiven Abrufmechanismus, der Ausgänge erden und den Agenten auf dem neuesten Stand halten kann.

Erinnerungsvermögen ist jedoch ein zweischneidiges Schwert. Sobald man zulässt, dass der Kontext unkontrolliert wächst, ist mit Vergiftung, Ablenkung, Verwirrung und Konflikten zu rechnen, in gemeinsam genutzten Systemen sogar mit Datenlecks. Deshalb ist die wichtigste Aufgabe hierbei nicht „mehr speichern“, sondern „besser kuratieren“: Selektiv abrufen, aktiv bereinigen, sorgfältig zusammenfassen und das Kombinieren unzusammenhängender Kontexte vermeiden, es sei denn, die Aufgabe erfordert dies wirklich.

In der Praxis ähnelt gutes Kontext-Engineering einem guten Systemdesign: kleinere, ausreichende Kontexte, kontrollierte Schnittstellen zwischen Komponenten und eine klare Trennung zwischen dem Rohzustand und dem destillierten Zustand, den das Modell tatsächlich sehen soll. Wenn man es richtig macht, führt dies nicht zu einem Agenten, der sich an alles erinnert, sondern zu einem Agenten, der sich zum richtigen Zeitpunkt und aus dem richtigen Grund an die richtigen Dinge erinnert.

Wir haben ein umfassendes Infrastruktur-Upgrade für alle Elastic Cloud Serverless-Projekte abgeschlossen, die auf AWS laufen und auf neuere, schnellere Hardware migriert wurden. Diese Änderung wurde automatisch auf alle Serverless-Projekte ausgerollt. Es bietet einen höheren Durchsatz und geringere Latenz für Serverless-Projekte mit Elasticsearch, Elastic Observability und Elastic Security auf AWS.

Wichtigste Leistungsvorteile für Entwickler:innen

Die neue AWS-Hardwareinfrastruktur bildet die Grundlage für alles, was Sie mit Elastic Cloud Serverless tun, und führt zu spürbaren Vorteilen hinsichtlich der Geschwindigkeit und Reaktionsfähigkeit Ihrer Anwendungen.

Reduzierte Abfragelatenz … erhöhter Durchsatz

Die verbesserte Hardware steigert die Geschwindigkeit der Rechenressourcen erheblich, sodass Ihre Suchanfragen schneller als je zuvor verarbeitet werden.

• Suchen und Vektorsuche: Egal, ob Sie traditionelle Volltextabfragen durchführen oder modernste Vektorsuche für Ihre generative KI- und Retrieval-Augmented-Generation (RAG)-Anwendungen verwenden – Sie werden eine deutliche Verringerung der Latenzzeit feststellen. Interne Benchmarkings zeigten einen durchschnittlichen Rückgang der Suchlatenz um 35 %.
• Schnellere Indexierung: Die Ingestion-Raten sind optimiert, sodass Sie riesige Datenmengen und komplexe Dokumente mit erhöhtem Durchsatz indexieren können. Das ist besonders wichtig für Anwendungen, die Daten nahezu in Echtzeit anzeigen müssen. Interne Benchmarkings zeigten einen durchschnittlichen Anstieg des Indexierungsdurchsatzes um 26 %.

Konstante Leistung unter Last

Elastic Cloud Serverless ist so konzipiert, dass es sich dynamisch in Echtzeit an die Nachfrage anpasst und die Latenz minimiert, unabhängig von Ihrer Arbeitslast. Mit diesem Hardware-Upgrade ist das Skalieren nun leistungsfähiger und reaktionsschneller.

• Problemloser Umgang mit Spitzen: Egal, ob Sie mit einem plötzlichen Anstieg des Nutzerverkehrs oder einem massiven Batch-Ingest konfrontiert sind – die neue Infrastruktur stellt sicher, dass Ihre Such- und Indexierungsressourcen effizienter skaliert werden, um eine gleichbleibend niedrige Latenz zu gewährleisten.
• Optimierte Entkopplung von Rechenleistung und Speicher: Die Serverless-Architektur trennt Rechenleistung und Speicher, wodurch Workloads unabhängig voneinander skaliert werden können, um optimale Leistung und Kosteneffizienz zu gewährleisten. Die schnellere Hardware verbessert die Computerschicht und maximiert die Effizienz dieses entkoppelten Designs.

Hinter den Kulissen: Ergebnisse interner Benchmarks

Um die Auswirkungen unseres AWS-Infrastruktur-Upgrades zu quantifizieren, führte das Elastic-Engineering-Team ein umfassendes internes Benchmarking mit einer Reihe von Serverless-Workloads durch. Diese Workloads lieferten empirische Beweise für Leistungsverbesserungen, die Sie in Ihren Anwendungen erwarten können, unabhängig von Ihrem Anwendungsfall.

Der Benchmarking-Ansatz

Wir konzentrierten unsere Tests auf die wichtigsten Kennzahlen, die das Entwicklererlebnis und die Anwendungsreaktionsfähigkeit direkt beeinflussen: Reaktionszeit (also Latenz) und Durchsatz bei Such- und Indexierungsoperationen.

• Getestete Arbeitslasten: Die Tests umfassten Suchvorgänge mit hoher Parallelität, wie sie typisch für benutzerorientierte Anwendungen sind, komplexe Vektorsuchanfragen sowie die Erfassung/Indexierung großer Datenmengen für Anwendungsfälle im Bereich Beobachtbarkeit und Sicherheit. Insbesondere nutzte unsere Testmethodik öffentlich verfügbare Datensätze für Rally, das Benchmarking-Tool von Elastic.
  • wikipediaEin Datensatz, der aus einem Snapshot des Wikipedia-Textinhalts abgeleitet wurde, um die allgemeine Textsuchleistung zu messen.
  • MSMARCO-Passage-RankingEin Datensatz, abgeleitet von Microsofts Machine Reading Comprehension (MS MARCO), um die Suchleistung auf spärlichen Vektorfeldern zu messen.
  • OpenAI_Vector: Ein Datensatz, der aus BEIRs NQ abgeleitet und mit Einbettungen angereichert wurde, die vom text-embedding-ada-002-Modell von OpenAI generiert wurden, um die Suchleistung auf dichten Vektorfeldern zu messen.
• Messung: Wir verglichen die Leistung der alten und neuen Infrastruktur und maßen die Latenz im 99. Perzentil (P99), um den Worst-Case, die Tail-Latenz-Performance und die Operationen pro Sekunde zu erfassen. Jeder Track wurde für jedes Hardware-Profil fünfmal ausgeführt, um die Konsistenz der Ergebnisse zu gewährleisten.
• Das Ziel: Unser Ziel war es, die Fähigkeit der Infrastruktur zu validieren, um eine konstant schnellere und vorhersehbarere Leistung zu liefern, selbst in Phasen schneller automatischer Skalierung.

Zusammenfassung der Leistungsdaten

Die Ergebnisse bestätigen deutliche Verbesserungen in Effizienz und Geschwindigkeit. Diese Vorteile schlagen sich direkt in kürzeren Reaktionszeiten für Ihre Benutzer:innen und niedrigeren Betriebskosten nieder, da Sie die gleiche Menge an Arbeit mit weniger Rechenressourcen erledigen können.

Die folgenden Tabellen zeigen die quantitativen Verbesserungen. Höhere Werte sind besser für den Durchsatz; niedrigere Werte sind besser für die Latenz.

Suche nach Benchmark-Ergebnissen:

Indexieren der Benchmark-Ergebnisse:

Der zusätzliche Bonus: Kostenreduzierung

Unser Fokus liegt zwar auf der Bereitstellung einer Performance mit geringer Latenz, aber die Effizienz der neuen Hardware hat auch einen direkten, positiven Einfluss auf die Kosten von Elasticsearch-Projekten.

Die Preisgestaltung von Elasticsearch Serverless basiert auf der Nutzung, das heißt, Sie zahlen nur für die Ingest- und Suchressourcen, die Sie verbrauchen. Da die neuere, schnellere Hardware effizienter ist, werden Ihre Arbeitslasten oft mit weniger Ressourcen erledigt, was bei den meisten Projekten zu einer erheblichen Kostenreduzierung führt. Sie erhalten eine Premium-Leistungssteigerung ohne den Premium-Preis – die Definition von optimierter Effizienz.

Was bedeutet das für Sie als Entwickler:in?

Dieses Infrastruktur-Upgrade wird vollständig von Elastic verwaltet, sodass Sie keinen Finger rühren müssen – keine Migrationen und keine Konfigurationsänderungen. Die Verbesserung erfolgt sofort und automatisch bei all Ihren AWS-basierten Serverless-Projekten.

Dieses Upgrade ermöglicht Ihnen Folgendes:

• Erstellen Sie schnellere Anwendungen: Konzentrieren Sie sich auf die Geschwindigkeit der Features, da Sie wissen, dass Ihre zugrundeliegende Such-Platform die Geschwindigkeit bietet, die Ihre Benutzer:innen erwarten.
• Innovation mit Zuversicht: Stellen Sie neue Such-, Beobachtbarkeits- und Sicherheitsfeatures – einschließlich komplexer KI-Features wie Vektorsuche und Relevanzranking – mit der Gewissheit bereit, dass die Platform die Last mit maximaler Leistung bewältigen kann.
• Vereinfachen Sie Ihren Stack: Nutzen Sie einen vollständig verwalteten Service, der Infrastrukturmanagement, Kapazitätsplanung und Skalierung übernimmt, damit Sie sich auf Ihren Code und Ihre Daten konzentrieren können.
  

Voraussetzungen

• NodeJS Version 18 oder neuer
• OpenAI-API-Schlüssel
• Elasticsearch 8.x+ Deployment

Warum LangGraph für Produktions-HITL-Systeme verwenden

In einem früheren Artikel haben wir LangGraph und seine Vorteile für den Aufbau eines RAG-Systems mit LLMs sowie bedingten Kanten vorgestellt, um automatisch Entscheidungen zu treffen und Ergebnisse anzuzeigen. Manchmal möchten wir nicht, dass das System komplett autonom agiert, sondern dass die Nutzer innerhalb der Ausführungsschleife Optionen auswählen und Entscheidungen treffen. Dieses Konzept heißt Human in the Loop.

Human-in-the-loop oder in der Schleife

Dabei handelt es sich um ein KI-Konzept, das es einer realen Person ermöglicht, mit KI-Systemen zu interagieren, um mehr Kontext zu liefern, Reaktionen zu bewerten, Reaktionen zu bearbeiten, nach weiteren Informationen zu fragen usw. Dies ist in Szenarien mit niedriger Fehlertoleranz wie Compliance, Entscheidungsfindung oder Inhaltsgenerierung sehr nützlich und trägt zur Verbesserung der Zuverlässigkeit der LLM-Outputs bei.

Ein häufiges Beispiel ist, wenn Ihr Programmierassistent Sie um die Erlaubnis bittet, einen bestimmten Befehl am Terminal auszuführen, oder Ihnen den Schritt-für-Schritt-Denkprozess zeigt, den Sie genehmigen müssen, bevor Sie mit dem Programmieren beginnen.

Elasticsearch + LangGraph: Wie sie interagieren

LangChain ermöglicht uns die Verwendung von Elasticsearch als Vektorspeicher und die Durchführung von Abfragen innerhalb von LangGraph-Anwendungen, was nützlich ist, um Volltext- oder semantische Suchen auszuführen, während LangGraph verwendet wird, um den spezifischen Workflow, die Tools und die Interaktionen zu definieren. HITL wird außerdem als zusätzliche Interaktionsebene mit dem Nutzer hinzugefügt.

Praktische Umsetzung: Human-in-the-loop

Stellen wir uns einen Fall vor, in dem ein Anwalt eine Frage zu einem Fall hat, den er kürzlich übernommen hat. Ohne die richtigen Hilfsmittel müsste er juristische Artikel und Präzedenzfälle manuell suchen, sie vollständig lesen und dann interpretieren, wie sie auf seine Situation anwendbar sind. Mit LangGraph und Elasticsearch können wir jedoch ein System aufbauen, das eine Datenbank von Rechtspräzedenzfällen durchsucht und eine Fallanalyse erstellt, die die spezifischen Details und den Kontext des Anwalts einbezieht.

Der Workflow beginnt, wenn der Anwalt eine Rechtsfrage einreicht. Das System führt eine Vektorsuche in Elasticsearch durch, ruft die relevantesten Präzedenzfälle ab und präsentiert sie dem Anwalt zur Auswahl in natürlicher Sprache. Nach der Auswahl erstellt der LLM einen Analyseentwurf und prüft, ob die Informationen vollständig sind. An dieser Stelle kann der Workflow zwei Pfaden folgen: Wenn alles klar ist, wird direkt eine endgültige Analyse generiert; wenn nicht, pausiert er, um eine Klärung vom Anwalt anzufordern. Sobald der fehlende Kontext bereitgestellt wird, schließt das System die Analyse ab und gibt sie unter Berücksichtigung der Klärungen zurück.

Nachfolgend ein von LangGraph erstellter Graph, der zeigt, wie die App am Ende der Entwicklung aussehen wird. Jeder Node repräsentiert ein Tool oder eine Funktionalität:

Datensatz

Hier ist der Datensatz, der für dieses Beispiel verwendet wird. Dieser Datensatz enthält eine Sammlung von Präzedenzfällen, die jeweils einen Fall mit Verzögerungen bei der Leistungserbringung, die Begründung des Gerichts und das Endergebnis beschreiben.

[
  {
    "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"
    }
  },
  ...
]

Einrichtung der Ingestion und des Indexes

Die Indexeinrichtung und die Logik zur Daten-Ingestion sind in der Datei dataIngestion.ts definiert, in der wir Funktionen deklarieren, die die Indexerstellung übernehmen. Dieses Setup ist kompatibel mit der LangChain Vektorspeicher-Schnittstelle für Elasticsearch.

Hinweis: Die Mapping-Konfiguration ist ebenfalls in der dataIngestion.ts Datei enthalten.

Pakete installieren und Umgebungsvariablen einrichten

Lassen Sie uns ein Node.js-Projekt mit den Standardeinstellungen initialisieren:

• @elastic/Elasticsearch: Elasticsearch-Client für Node.js. Wird verwendet, um Verbindungen herzustellen, Indizes zu erstellen und Abfragen auszuführen.
• @langchain/community: Bietet Integrationen für von der Community unterstützte Tools, einschließlich des ElasticVectorSearch-Stores.
• @langchain/core: Kernbausteine von LangChain, wie Ketten, Prompts und Hilfsmittel.
• @langchain/langgraph: Fügt graphbasierte Orchestrierung hinzu, die Workflows mit Knoten, Kanten und Zustandsverwaltung ermöglicht.
• @langchain/openai: Bietet Zugriff auf OpenAI-Modelle (LLMs und Einbettungen) über LangChain.
• dotenv: Lädt Umgebungsvariablen aus einer.env Datei in process.env.
• tsx: Ist ein nützliches Tool zum Ausführen von TypeScript-Code.

Führen Sie folgenden Befehl in der Konsole aus, um alle zu installieren:

npm install @elastic/elasticsearch @langchain/community @langchain/core @langchain/langgraph @langchain/openai dotenv --legacy-peer-deps && npm install --save-dev tsx

Erstellen Sie eine .env Datei, um die Umgebungsvariablen einzurichten:

ELASTICSEARCH_ENDPOINT=
ELASTICSEARCH_API_KEY=
OPENAI_API_KEY=

Wir werden TypeScript zum Schreiben des Codes verwenden, da es eine Ebene der Typsicherheit und eine bessere Entwicklererfahrung bietet. Erstellen Sie eine TypeScript-Datei mit dem Namen main.ts und fügen Sie den Code des nächsten Abschnitts ein.

Pakete importieren

In der Datei main.ts importieren wir zunächst die benötigten Module und initialisieren die Umgebungsvariablenkonfiguration. Dazu gehören die Kernkomponenten von LangGraph, die OpenAI-Modellintegrationen und der Elasticsearch-Client.

Wir importieren außerdem Folgendes aus der dataIngestion.ts-Datei :

• ingestData: eine Funktion, die den Index erstellt und die Daten aufnimmt.
• Dokument und Dokumentmetadaten: Schnittstellen, die die Dokumentstruktur des Datensatzes definieren.

Elasticsearch Vector Store Client, Embeddings Client und OpenAI-Client

Dieser Code initialisiert den Vektorspeicher, den Embeddings-Client und einen OpenAI-Client.

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,
});

Das Workflow-Statusschema der Anwendung hilft bei der Kommunikation zwischen den Nodes:

const LegalResearchState = Annotation.Root({
  query: Annotation(),
  analyzedConcepts: Annotation(),
  precedents: Annotation(),
  selectedPrecedent: Annotation(),
  draftAnalysis: Annotation(),
  ambiguityDetected: Annotation(),
  userClarification: Annotation(),
  finalAnalysis: Annotation(),
});

Im Zustandsobjekt geben wir durch die Nodes die Nutzeranfrage, die daraus extrahierten Konzepte, die abgerufenen Rechtspräzedenzfälle und etwaige Mehrdeutigkeiten durch. Der Zustand verfolgt auch den vom Nutzer ausgewählten Präzedenzfall, die während des Prozesses erstellte Entwurfsanalyse und die endgültige Analyse, sobald alle Klärungen abgeschlossen sind.

Knoten

searchPrecedents: Dieser Node führt eine Ähnlichkeitssuche im Elasticsearch-Vektorspeicher basierend auf dem Eingang des Nutzers durch. Er ruft bis zu 5 übereinstimmende Dokumente ab und druckt sie aus, damit der Nutzer sie einsehen kann.

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 };
}

Präzedenzfallauswahl: Dieser Node ermöglicht es dem Nutzer, mithilfe natürlicher Sprache denjenigen Anwendungsfall auszuwählen, der durch die Proximity-Suche ermittelt wurde und am besten zur Frage passt. An diesem Punkt unterbricht die Anwendung den Workflow und wartet auf die Nutzereingabe.

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 };
}

selectPrecedent: Dieser Node sendet den Nutzerinput zusammen mit den abgerufenen Dokumenten zur Interpretation, sodass eines von ihnen ausgewählt werden kann. Das LLM erfüllt diese Aufgabe, indem es eine Zahl zurückgibt, die das Dokument repräsentiert, das es aus der natürlichen Spracheingabe des Nutzers ableitet.

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: Dieser Node generiert die erste rechtliche Analyse basierend auf dem vom Nutzer gewählten Präzedenzfall. Er verwendet einen LLM, um zu beurteilen, inwieweit der gewählte Präzedenzfall auf die Frage des Anwalts anwendbar ist, und um festzustellen, ob dem System genügend Informationen vorliegen, um fortzufahren.

Wenn der Präzedenzfall direkt angewendet werden kann, erstellt der Node einen Analyseentwurf und nimmt den richtigen Pfad zum End-Node. Wenn das LLM Unklarheiten wie undefinierte Vertragsbedingungen, fehlende Zeitrahmendetails oder unklare Bedingungen erkennt, gibt es eine Markierung zurück, die darauf hinweist, dass eine Klärung erforderlich ist, zusammen mit einer Liste der spezifischen Informationen, die bereitgestellt werden müssen. In diesem Fall löst die Mehrdeutigkeit den linken Pfad des Graphen aus.

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,
  };
}

Die beiden möglichen Pfade des Graphen sehen folgendermaßen aus:

Der linke Pfad enthält einen zusätzlichen Node, der die Klarstellung übernimmt.

RequestClarification: Dieser Node löst den zweiten Human-in-the-Loop-Schritt aus, wenn das System feststellt, dass dem Analyseentwurf grundlegender Kontext fehlt. Der Workflow wird unterbrochen und der Nutzer wird aufgefordert, die fehlenden Vertragsdetails zu klären, die der vorherige Node entdeckt hat.

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: Dieser Node erstellt die endgültige rechtliche Analyse, indem er den ausgewählten Präzedenzfall mit dem vom Nutzer bereitgestellten zusätzlichen Kontext kombiniert, falls nötig. Anhand der im vorherigen HITL-Schritt gesammelten Klarstellung fasst das LLM die Begründung des Präzedenzfalls, die vom Nutzer bereitgestellten Vertragsdetails und die Bedingungen zusammen, die bestimmen, ob ein Verstoß stattgefunden haben könnte.

Der Node liefert eine vollständige Analyse, die rechtliche Auslegung und praktische Empfehlungen integriert.

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 };
}

Graph erstellen:

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__");

Im Graph können wir sehen, dass die bedingte Kante die Bedingung für die Wahl des „finalen“ Pfades definiert. Wie gezeigt, hängt die Entscheidung nun davon ab, ob der Analyseentwurf Unklarheiten aufgedeckt hat, die einer weiteren Klärung bedürfen.

Zusammengefasst zur Ausführung:

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
  );
}

Führen Sie das Skript aus:

Nachdem wir den gesamten Code zugewiesen haben, führen wir die Datei main.ts aus, indem wir den folgenden Befehl im Terminal eingeben:

tsx main.ts

Sobald das Skript ausgeführt wird, wird die Frage „Stellt ein Muster wiederholter Verzögerungen einen Verstoß dar, selbst wenn jede einzelne Verzögerung geringfügig ist?“ an Elasticsearch gesendet, um eine Proximity-Suche durchzuführen, und die aus dem Index abgerufenen Ergebnisse werden angezeigt. Die App erkennt, dass mehrere relevante Präzedenzfälle mit der Abfrage übereinstimmen, pausiert die Ausführung und bittet den Nutzer, bei der Klarstellung zu helfen, welcher rechtliche Präzedenzfall am relevantesten ist:

📚 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? 

Das Interessante an dieser Anwendung ist, dass wir in natürlicher Sprache eine Option auswählen können, wobei das LLM den Input des Nutzers interpretiert, um die richtige Wahl zu ermitteln. Lassen Sie uns sehen, was passiert, wenn wir den Text eingeben: „Fall 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:

Das Modell nimmt die Erläuterungen des Nutzers auf und integriert sie in den Workflow, um mit der endgültigen Analyse fortzufahren, sobald genügend Kontext vorhanden ist. In diesem Schritt nutzt das System auch die zuvor festgestellte Unklarheit: Die Entwurfsanalyse hat fehlende Vertragsdetails hervorgehoben, die die rechtliche Auslegung maßgeblich beeinflussen könnten. Diese „fehlenden Informationen“ dienen dem Modell als Leitfaden, um festzustellen, welche Klarstellungen unerlässlich sind, um Unsicherheiten zu beseitigen, bevor eine verlässliche endgültige Meinung abgegeben werden kann.

Der Nutzer muss bei dem nächsten Input die gewünschten Erläuterungen angeben. Versuchen wir es mit „Vertrag erfordert 'pünktliche Lieferung' ohne Zeitpläne. 8 Verzögerungen von 2-4 Tagen über 6 Monate. 50.000 $ Verluste durch 3 verpasste Kundenfristen. Verkäufer benachrichtigt, aber das Muster hält an.“

💭 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.

Dieser Ausgang zeigt die letzte Phase des Workflows, in der das Modell den ausgewählte Präzedenzfall (Fall H) und die Klärungen des Anwalts integriert, um eine vollständige rechtliche Analyse zu generieren. Das System erklärt, warum das Muster der Verzögerungen wahrscheinlich einen Verstoß darstellt, skizziert die Faktoren, die diese Interpretation stützen, und gibt praktische Empfehlungen. Insgesamt zeigt der Output, wie die HITL-Klärungen Mehrdeutigkeiten auflösen und es dem Modell ermöglichen, eine fundierte, kontextspezifische rechtliche Stellungnahme zu erstellen.

Andere reale Szenarien

Diese Art von Anwendung, die Elasticsearch, LangGraph und Human-in-the-Loop verwendet, kann in anderen Apps nützlich sein wie:

• Bei der Überprüfung von Tool-Aufrufen vor ihrer Ausführung, zum Beispiel im Finanzhandel, genehmigt ein Mensch Kauf-/Verkaufsaufträge, bevor sie erteilt werden.
• Fügen Sie bei Bedarf zusätzliche Parameter an, zum Beispiel bei der Triage des Kundensupports, bei der ein menschlicher Mitarbeiter die richtige Problemkategorie auswählt, wenn die KI mehrere mögliche Interpretationen des Problems des Kunden findet.

Und es gibt viele Anwendungsfälle, die es noch zu entdecken gilt, in denen Human-in-the-Loop ein entscheidender Faktor sein wird.

Fazit

Mit LangGraph und Elasticsearch können wir Agenten erstellen, die eigene Entscheidungen treffen und als lineare Workflows agieren oder Bedingungen erfüllen, die sie dazu veranlassen, den einen oder anderen Pfad zu wählen. Mit Human-in-the-Loop können die Agenten den tatsächlichen Nutzer in den Entscheidungsprozess einbeziehen, um kontextuelle Lücken zu füllen und Bestätigungen für Systeme anzufordern, bei denen Fehlertoleranz entscheidend ist.

Einer der Vorteile dieses Ansatzes ist, dass man einen großen Datensatz mithilfe der Elasticsearch-Funktionen filtern und dann mit einem LLM ein einzelnes Dokument als Nutzerauswahl erhalten kann. Dieser letzte Schritt wäre mit Elasticsearch allein viel komplizierter, da es viele Möglichkeiten gibt, wie ein Mensch ein Ergebnis in natürlicher Sprache interpretieren kann.

Mit diesem Ansatz bleibt das System schnell und Token-effizient, da wir dem LLM nur das senden, was für die endgültige Entscheidung benötigt wird, und nicht die gesamten Datensätze. Gleichzeitig wird die Absicht des Nutzers sehr genau erkannt und so lange iteriert, bis die gewünschte Option ausgewählt ist.

Unser Ziel war es, zu einem automatisierten, adaptiven Ansatz überzugehen, der sowohl Log-Parsing (Feldextraktion) als auch Log-Partitionierung (Quellenidentifikation) bewältigen kann. Wir vermuteten, dass Large Language Models (LLMs) mit ihrem inhärenten Verständnis von Codesyntax und semantischen Mustern diese Aufgaben mit minimalem menschlichem Eingreifen automatisieren könnten.

Wir freuen uns, Ihnen mitteilen zu können, dass dieses Feature bereits in Streams verfügbar ist!

Beschreibung des Datensatzes

Wir haben für PoC-Zwecke eine Loghub-Sammlung von Logs gewählt. Für unsere Untersuchung wählten wir repräsentative Stichproben aus den folgenden Schlüsselbereichen aus:

• Verteilte Systeme: Wir verwendeten die HDFS- (Hadoop Distributed File System) und Spark-Datensätze. Diese enthalten eine Mischung aus Info-, Fehlerbehebungs- und Fehlermeldungen, die für Big Data-Plattformen typisch sind.
• Server- und Webanwendungen: Logs von Apache-Webservern und OpenSSH boten eine wertvolle Quelle für Zugriffs-, Fehler- und sicherheitsrelevante Ereignisse. Diese sind entscheidend für die Überwachung des Webverkehrs und die Erkennung potenzieller Bedrohungen.
• Betriebssysteme: Wir haben Protokolle von Linux und Windows aufgenommen. Diese Datensätze repräsentieren die üblichen, semistrukturierten Ereignisse auf Systemebene, denen Betriebsteams täglich begegnen.
• Mobile Systeme: Um sicherzustellen, dass unser Modell auch Logs aus mobilen Umgebungen verarbeiten kann, haben wir den Android-Datensatz mit einbezogen. Diese Logs sind oft ausführlich und erfassen eine Vielzahl von Aktivitäten auf Anwendungs- und Systemebene auf Mobilgeräten.
• Supercomputer: Um die Leistung in Hochleistungs-Computing-Umgebungen (HPC) zu testen, haben wir den BGL-Datensatz (Blue Gene/L) integriert, der hochstrukturierte Logs mit spezifischer Domänenterminologie enthält.

Ein entscheidender Vorteil der Loghub-Sammlung ist, dass die Logs größtenteils unsaniert und unbeschriftet sind, was eine geräuschvolle Live-Produktionsumgebung mit Microservice-Architektur widerspiegelt.

Log-Beispiele:

[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

Zusätzlich haben wir einen Kubernetes-Cluster mit einer typischen Webanwendung und Datenbank erstellt, die zusätzliche Logs in der gängigsten Domäne sammelt.

Beispiel für gängige Logfelder: Zeitstempel, Log-Ebene (INFO, WARN, FEHLER), Quelle, Nachricht.

Few-Shot-Log-Parsing mit einem LLM

Unsere erste Reihe von Experimenten konzentrierte sich auf eine grundlegende Frage: Kann ein LLM zuverlässig Schlüsselfelder identifizieren und konsistente Parsing-Regeln erzeugen, um sie zu extrahieren?

Wir haben ein Modell gebeten, rohe Log-Stichproben zu analysieren und Log-Parsing-Regeln im regulären Ausdruck (Regex) und im Grok-Format zu generieren. Unsere Ergebnisse zeigten, dass dieser Ansatz großes Potenzial hat, aber auch erhebliche Herausforderungen bei der Implementierung.

Hohe Zuverlässigkeit und Kontextbewusstsein

Die ersten Ergebnisse waren vielversprechend. Das LLM zeigte eine starke Fähigkeit, Parsing-Regeln zu generieren, die mit hoher Wahrscheinlichkeit zu den bereitgestellten Beispielen passten. Neben der einfachen Mustererkennung zeigte das Modell die Fähigkeit zum Log-Verständnis – es konnte die Log-Quelle (z. B. Gesundheits-Tracking-App, Nginx-Web-App, Mongo-Datenbank) korrekt identifizieren und benennen.

Das „Goldlöckchen“-Dilemma der Eingabestichproben

Unsere Experimente zeigten schnell einen erheblichen Mangel an Robustheit aufgrund der extremen Empfindlichkeit gegenüber der Eingabestichprobe. Die Leistung des Modells schwankt stark in Abhängigkeit von den spezifischen Log-Beispielen, die im Prompt enthalten sind. Wir haben ein Log-Ähnlichkeitsproblem beobachtet, bei dem die Log-Stichprobe gerade ausreichend unterschiedliche Logs enthalten muss:

• Zu homogen (Overfitting): Wenn die Eingabe-Logs zu ähnlich sind, neigt das LLM dazu, zu überspezifizieren. Es behandelt variable Daten – wie spezifische Java-Klassennamen in einem Stack-Trace – als statische Teile der Vorlage. Das Ergebnis sind spröde Regeln, die nur einen winzigen Teil der Logs abdecken und unbrauchbare Felder extrahieren.
• Zu heterogen (Verwirrung): Umgekehrt, wenn die Stichprobe erhebliche Formatierungsunterschiede enthält – oder schlimmer noch, „Müll-Logs“ wie Fortschrittsbalken, Speichertabellen oder ASCII-Art – kämpft das Modell damit, einen gemeinsamen Nenner zu finden. Oftmals greift man dabei auf die Generierung komplexer, fehlerhafter regulärer Ausdrücke zurück oder verallgemeinert die gesamte Zeile vorschnell zu einem einzigen Nachrichten-Feld.

Die Einschränkung des Kontextfensters

Wir sind außerdem auf einen Engpass im Kontextfenster gestoßen. Wenn die Eingabe-Logs lang, heterogen oder reich an extrahierbaren Feldern waren, verschlechterte sich oft die Ausgabe des Modells und wurde „unübersichtlich“ oder zu lang, um in das Ausgabekontextfenster zu passen. Natürlich hilft Chunking in diesem Fall. Durch das Aufteilen von Protokollen mithilfe zeichenbasierter und entitätsbasierter Trennzeichen könnten wir dem Modell helfen, sich auf das Extrahieren der Hauptfelder zu konzentrieren, ohne von Rauschen überwältigt zu werden.

Die Konsistenz- und Standardisierungslücke

Selbst wenn das Modell erfolgreich Regeln generierte, stellten wir leichte Inkonsistenzen fest:

• Namensvariationen für Dienste: Das Modell schlägt unterschiedliche Namen für dieselbe Entität vor (z. B. wird die Quelle in verschiedenen Ausführungen als „Spark“, „Apache Spark“ und „Spark log Analytics“ bezeichnet).
• Variationen bei der Feldbenennung: Es fehlte an Standardisierung bei den Feldnamen (z. B. id vs. service.id vs. device.id). Wir haben Namen mithilfe einer standardisierten Elastic-Feldbenennung normalisiert.
• Auflösungsvarianz: Die Auflösung der Feldextraktion variierte je nachdem, wie ähnlich die Eingabe-Logs einander waren.

Log-Format-Fingerprint

Um die Herausforderung der Log-Ähnlichkeit anzugehen, führen wir eine leistungsstarke Heuristik ein: Log-Format-Fingerprint (LFF).

Anstatt rohe, verrauschte Logs direkt in ein LLM einzuspeisen, wenden wir zunächst eine deterministische Transformation an, um die zugrundeliegende Struktur jeder Nachricht zu enthüllen. Dieser Vorverarbeitungsschritt abstrahiert variable Daten und generiert einen vereinfachten „Fingerabdruck“, der es uns ermöglicht, verwandte Logs zu gruppieren.

Die Mapping-Logik ist einfach, um Geschwindigkeit und Konsistenz zu gewährleisten:

1. Ziffernabstraktion: Jede Ziffernfolge (0–9) wird durch eine einzelne „0“ ersetzt.
2. Textabstraktion: Jede Folge von alphabetischen Zeichen mit Leerzeichen wird durch ein einzelnes „a“ ersetzt.
3. Normalisierung von Leerzeichen: Alle Sequenzen von Leerzeichen (Leerzeichen, Tabulatoren, Zeilenumbrüche) werden zu einem einzigen Leerzeichen zusammengefasst.
4. Symbolerhaltung: Zeichensetzung und Sonderzeichen (z. B. :, [, ], /) werden beibehalten, da sie oft die stärksten Indikatoren für die Log-Struktur sind.

Wir stellen den Log-Mapping-Ansatz vor. Die grundlegenden Mapping-Muster umfassen Folgendes:

• Ziffern 0–9 von beliebiger Länge -> auf „0“.
• Text (alphabetische Zeichen mit Leerzeichen) von beliebiger Länge -> auf „a“.
• Leerzeichen, Tabulatoren und neue Zeilen -> auf ein einzelnes Leerzeichen.

Schauen wir uns ein Beispiel an, wie uns dieses Mapping die Transformation der Logs ermöglicht.

Dadurch erhalten wir folgende Log-Masken:

Beachten Sie die Fingerabdrücke der ersten beiden Logs. Trotz unterschiedlicher Zeitstempel, Quellklassen und Nachrichteninhalte sind ihre Präfixe (0/0/0 0:0:0 a a.a:) identisch. Durch diese strukturelle Ausrichtung können wir diese Logs automatisch in denselben Cluster einordnen.

Das dritte Log erzeugt jedoch einen völlig abweichenden Fingerabdruck (0-0-0...). Dies ermöglicht es uns, es algorithmisch von der ersten Gruppe zu trennen, bevor wir überhaupt ein LLM aufrufen.

Bonus: Sofortige Implementierung mit ES|QL

Es ist so einfach wie das Übergeben dieser Abfrage in 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

Abfrage-Aufschlüsselung:

FROM LogHub: Zielt auf unseren Index mit den Rohprotokolldaten ab.

EVAL Muster = …: Die Kern-Mapping-Logik. Wir verketten REPLACE-Funktionen, um die Abstraktion durchzuführen (z. B. Ziffern zu '0', Text zu 'a' usw.) und speichern das Ergebnis in einem „Muster“-Feld.

STATS [column1 =] expression1, … BY SUBSTRING(pattern, 0, 15):

Dies ist ein Clustering-Schritt. Wir gruppieren Protokolle, die die ersten 15 Zeichen ihres Musters gemeinsam haben, und erstellen aggregierte Felder wie die Gesamtzahl der Protokolle pro Gruppe, eine Liste der Protokoll-Datenquellen, das Musterpräfix und 3 Protokollbeispiele.

SORT total_count DESC | LIMIT 100 : Zeigt die 100 häufigsten Log-Muster an

Die Abfrageergebnisse auf LogHub werden unten angezeigt:

Wie in der Visualisierung gezeigt, partitioniert dieser „LLM-freie“ Ansatz Protokolle mit hoher Genauigkeit. Es gelang ihm, 10 von 16 Datenquellen (basierend auf LogHub-Labels) vollständig zu clustern (>90 %), und er erreichte ein Mehrheits-Clustering in 13 von 16 Quellen (>60 %) – alles ohne zusätzliche Reinigung, Vorverarbeitung oder Feinabstimmung.

Log-Format-Fingerprinting bietet eine pragmatische, wirkungsvolle Alternative und Ergänzung zu ausgefeilten ML-Lösungen wie der Log-Pattern-Analyse. Es bietet sofortige Einblicke in die Zusammenhänge der Logs und verwaltet große Log-Cluster effektiv.

• Vielseitigkeit als Grundform

Dank ES|QL-Implementierung dient LFF sowohl als eigenständiges Werkzeug für schnelle Datendiagnostik/-visualisierungen als auch als Baustein in Loganalyse-Pipelines für Anwendungsfälle mit hohem Volumen.

• Flexibilität

LFF lässt sich leicht anpassen und erweitern, um spezifische Muster zu erfassen, z. B. hexadezimale Zahlen und IP-Adressen.

• Deterministische Stabilität

Im Gegensatz zu ML-basierten Clustering-Algorithmen ist die LFF-Logik geradlinig und deterministisch. Neue eingehende Logs wirken sich nicht rückwirkend auf bestehende Log-Cluster aus.

• Leistung und mMemory

Es benötigt nur minimalen Speicher, kein Training und keine GPU und ist daher ideal für Echtzeit-Umgebungen mit hohem Durchsatz geeignet.

Kombination des Log-Format-Fingerprints mit einem LLM

Zur Validierung der vorgeschlagenen hybriden Architektur enthielt jedes Experiment eine zufällige 20%ige Teilmenge der Logs aus jeder Datenquelle. Diese Einschränkung simuliert eine reale Produktionsumgebung, in der Logs in Batches und nicht als monolithischer historischer Dump verarbeitet werden.

Das Ziel war zu demonstrieren, dass LFF als effektive Kompressionsschicht fungiert. Wir wollten beweisen, dass Parsing-Regeln mit hoher Abdeckung aus kleinen, kuratierten Stichproben generiert und erfolgreich auf den gesamten Datensatz verallgemeinert werden können.

Ausführungspipeline

Wir haben eine mehrstufige Pipeline implementiert, die die Daten filtert, gruppiert und stratifizierte Stichproben auf sie anwendet, bevor sie das LLM erreichen.

1. Zweistufiges hierarchisches Clustering

• Unterklassen (exakte Übereinstimmung): Logs werden anhand identischer Fingerabdrücke aggregiert. Alle Logs einer Unterklasse haben exakt die gleiche Formatstruktur.
• Ausreißerbereinigung. Wir verwerfen alle Unterklassen, die weniger als 5 % des gesamten Logvolumens ausmachen. Dadurch wird sichergestellt, dass sich das LLM auf das dominante Signal konzentriert und nicht durch Rauschen oder fehlerhafte Logs abgelenkt wird.
• Metaklassen (Präfixübereinstimmung): Verbleibende Unterklassen werden in Metaklassen nach den ersten N Zeichen der Format-Fingerabdruckübereinstimmung gruppiert. Wir haben N=5 für das Log-Parsing und N=15 für die Log-Partitionierung gewählt, wenn die Datenquellen unbekannt sind.

2. Stratifiziertes Sampling. Sobald der hierarchische Baum erstellt ist, erstellen wir die Log-Stichprobe für das LLM. Das strategische Ziel ist es, die Varianzabdeckung zu maximieren und gleichzeitig die Verwendung von Token zu minimieren.

• Wir wählen repräsentative Logs aus jeder gültigen Unterklasse innerhalb der breiteren Metaklasse aus.
• Um einen Randfall mit zu vielen Unterklassen zu managen, wenden wir zufälliges Downsampling an, um die Zielfenstergröße anzupassen.

3. Regelgenerierung. Abschließend fordern wir das LLM auf, eine Regex-Parsing-Regel zu generieren, die auf alle Logs in der bereitgestellten Stichprobe für jede Metaklasse zutrifft. Für unseren PoC haben wir das Modell GPT-4o Mini verwendet.

Experimentelle Ergebnisse und Beobachtungen

Wir haben auf dem Loghub-Datensätze eine Parsing-Genauigkeit von 94 % und eine Partitionierungs-Genauigkeit von 91 % erreicht.

Die obige Konfusionsmatrix veranschaulicht die Ergebnisse der Log-Partitionierung. Die vertikale Achse stellt die tatsächlichen Datenquellen dar, die horizontale Achse die vorhergesagten Datenquellen. Die Intensität der Heatmap entspricht dem Log-Volumen, wobei leichtere Kacheln auf eine höhere Anzahl hinweisen. Die diagonale Ausrichtung zeigt die hohe Genauigkeit des Modells bei der Quellenzuweisung mit minimaler Streuung.

Einblicke aus unseren Leistungsvergleichsanalysen:

• Optimale Ausgangsbasis: Ein Kontextfenster von 30 bis 40 Log-Stichproben pro Kategorie erwies sich als der „Sweet Spot“, der sowohl mit Regex- als auch mit Grok-Mustern durchweg ein robustes Parsing ermöglichte.
• Eingabeminimierung: Wir haben die Eingabegröße für Regex-Muster auf 10 Logs pro Kategorie erhöht und nur einen 2%igen Rückgang der Parsing-Leistung festgestellt, was bestätigt, dass diversitätsbasierte Stichproben kritischer sind als das rohe Volumen.

Jina-Modelle lassen sich in drei Hauptkategorien einteilen, die zur Unterstützung der Informationsverarbeitung, Organisation und den Informationsabruf entwickelt wurden:

• Semantische Einbettungsmodelle
• Reranking-Modelle
• Kleine generative Sprachmodelle

Semantische Einbettungsmodelle

Die Idee hinter semantischen Einbettungen ist, dass ein KI-Modell lernen kann, Aspekte der Bedeutung seiner Eingaben in Bezug auf die Geometrie hochdimensionaler Räume darzustellen.

Sie können sich eine semantische Einbettung als einen Punkt (technisch gesehen einen Vektor) in einem hochdimensionalen Raum vorstellen. Ein Einbettungsmodell ist ein neuronales Netz, das digitale Daten als Eingabe aufnimmt (potenziell alles, aber meist Text oder Bild) und die Position eines entsprechenden hochdimensionalen Punktes als numerische Koordinaten ausgibt. Wenn das Modell seine Aufgabe gut erfüllt, ist der Abstand zwischen zwei semantischen Einbettungen proportional dazu, wie sehr ihre entsprechenden digitalen Objekte dieselbe Bedeutung haben.

Um zu verstehen, wie wichtig das für Suchanwendungen ist, stellen Sie sich eine Einbettung für das Wort „dog“ und eine für das Wort „cat“ als Punkte im Raum vor:

Ein gutes Einbettungsmodell sollte eine Einbettung für das Wort „feline“ generieren, die viel näher an „cat“ als an „dog“ liegt, und „canine“ sollte eine Einbettung haben, die viel näher an „dog“ als an „cat“ liegt, weil diese Wörter fast dasselbe bedeuten:

Wenn ein Modell mehrsprachig ist, würden wir dasselbe für Übersetzungen von „cat“ und „dog“ erwarten:

Einbettungsmodelle übersetzen Ähnlichkeiten oder Unterschiede in der Bedeutung zwischen Dingen in räumliche Beziehungen zwischen Einbettungen. Die Bilder oben haben nur zwei Dimensionen, sodass Sie sie auf einem Bildschirm sehen können, aber das Einbetten von Modellen erzeugt Vektoren mit Dutzenden bis Tausenden von Dimensionen. Dies ermöglicht es ihnen, die Feinheiten der Bedeutung ganzer Texte zu kodieren, indem sie einen Punkt in einem Raum mit Hunderten oder Tausenden von Dimensionen für Dokumente mit Tausenden von Wörtern oder mehr zuweisen.

Multimodale Einbettungen

Multimodale Modelle erweitern das Konzept der semantischen Einbettung auf andere Dinge als Texte, insbesondere auf Bilder. Wir würden erwarten, dass eine Einbettung für ein Bild nahe an einer Einbettung einer getreuen Beschreibung des Bildes liegt:

Semantische Einbettungen haben viele Einsatzmöglichkeiten. Unter anderem können Sie sie verwenden, um effiziente Klassifikatoren zu erstellen, Clustering durchzuführen und eine Vielzahl von Aufgaben zu erledigen, wie z. B. die Deduplizierung von Daten und die Untersuchung der Datendiversität. Beides ist wichtig für Big-Data-Anwendungen, bei denen mit zu vielen Daten gearbeitet wird, um sie manuell zu verwalten.

Die größte direkte Anwendung von Einbettungen ist der Informationsabruf. Elasticsearch kann Abrufobjekte mit Einbettungen als Schlüssel speichern. Abfragen werden in Einbettungsvektoren umgewandelt, und eine Suche gibt die gespeicherten Objekte zurück, deren Schlüssel den Abfrage-Einbettungen am nächsten sind.

Bei der traditionellen vektorbasierten Suche (manchmal auch als Sparse Vector Retrieval bezeichnet) werden Vektoren verwendet, die auf Wörtern oder Metadaten in Dokumenten und Anfragen basieren. Die einbettungsbasierte Suche (auch bekannt als Dense Vector Retrieval) verwendet hingegen KI-bewertete Bedeutungen anstelle von Wörtern. Dadurch sind sie im Allgemeinen wesentlich flexibler und genauer als herkömmliche Suchmethoden.

Matryoshka-Darstellungslernen

Die Anzahl der Dimensionen, die eine Einbettung hat, und die Präzision der darin enthaltenen Zahlen haben erhebliche Auswirkungen auf die Leistung. Äußerst hochdimensionale Räume und extrem hochpräzise Zahlen können sehr detaillierte und komplexe Informationen darstellen, erfordern aber größere KI-Modelle, deren Training und Nutzung teurer sind. Die erzeugten Vektoren benötigen mehr Speicherplatz, und es braucht mehr Rechenzyklen, um die Abstände zwischen ihnen zu berechnen. Bei der Verwendung semantischer Einbettungsmodelle müssen wichtige Kompromisse zwischen Präzision und Ressourcenverbrauch eingegangen werden.

Um die Flexibilität für die Nutzer zu maximieren, werden Jina-Modelle mit einer Technik namens Matryoshka Representation Learning trainiert. Dies führt dazu, dass die Modelle die wichtigsten semantischen Unterscheidungen in die ersten Dimensionen des Einbettungsvektors vorladen, sodass man die höheren Dimensionen einfach abschneiden und trotzdem eine gute Leistung erzielen kann.

In der Praxis bedeutet das, dass Nutzer von Jina-Modellen wählen können, wie viele Dimensionen ihre Einbettungen haben sollen. Die Wahl von weniger Dimensionen verringert die Präzision, der Leistungsverlust ist jedoch gering. Bei den meisten Aufgaben sinken die Leistungskennzahlen für Jina-Modelle um 1 bis 2 %, wenn man die Einbettungsgröße um 50 % reduziert, bis hin zu einer Reduzierung um etwa 95 %.

Asymmetrischer Informationsabruf

Semantische Ähnlichkeit wird normalerweise symmetrisch gemessen. Der Wert, den man beim Vergleich von „cat“ mit „dog“ erhält, ist derselbe wie der Wert, den man beim Vergleich von „dog“ mit „cat“ erhält. Bei der Verwendung von Einbettungen für den Informationsabruf funktionieren diese jedoch besser, wenn man die Symmetrie aufhebt und Anfragen anders kodiert als die zu kodierenden Objekte.

Das liegt an der Art, wie wir Einbettungsmodelle trainieren. Die Trainingsdaten enthalten Instanzen der gleichen Elemente, wie z. B. Wörter, in vielen verschiedenen Kontexten. Die Modelle lernen die Semantik, indem sie die kontextuellen Ähnlichkeiten und Unterschiede zwischen den Elementen vergleichen.

So könnten wir beispielsweise feststellen, dass das Wort „animal“ nicht in sehr vielen der gleichen Kontexte wie „cat“ oder „dog“ vorkommt, und daher ist die Einbettung für „animal“ möglicherweise nicht besonders nahe an der von „cat“ oder „dog“:

Dies macht es unwahrscheinlicher, dass eine Abfrage nach „animal“ Dokumente über Katzen und Hunde zurückgibt – das Gegenteil unseres Ziels. Deshalb kodieren wir „Tier“ anders, wenn es sich um eine Suchanfrage handelt, als wenn es ein Ziel für den Informationsabruf ist:

Asymmetrischer Informationsabruf bedeutet, ein anderes Modell für Abfragen zu verwenden oder ein Einbettungsmodell speziell zu trainieren, um Dinge auf eine bestimmte Weise zu kodieren, wenn sie für den Abruf gespeichert sind, und Abfragen auf eine andere Weise zu kodieren.

Multivektor-Einbettungen

Einzelne Einbettungen sind gut für die Informationsabfrage, da sie in das grundlegende Framework einer indizierten Datenbank passen: Wir speichern Objekte für die Abfrage mit einem einzelnen Einbettungsvektor als deren Abfrageschlüssel. Wenn Nutzer den Dokumentenspeicher abfragen, werden ihre Abfragen in Einbettungsvektoren übersetzt und die Dokumente, deren Schlüssel der Abfrage-Einbettung am nächsten sind (im hochdimensionalen Einbettungsraum), werden als Kandidatenmatches abgerufen.

Multivektor-Einbettungen funktionieren etwas anders. Anstatt einen Vektor mit fester Länge zu erzeugen, um eine Abfrage und ein ganzes gespeichertes Objekt darzustellen, erzeugen sie eine Folge von Einbettungen, die kleinere Teile davon repräsentieren. Die einzelnen Teile sind typischerweise Tokens oder Wörter für Texte und Bildkacheln für visuelle Daten. Diese Einbettungen spiegeln die Bedeutung des Teils in seinem Kontext wider.

Betrachten wir zum Beispiel die folgenden Sätze:

• Sie hatte ein Herz aus Gold.
• Sie hatte einen Herzenswandel.
• Sie hatte einen Herzinfarkt.

Oberflächlich betrachtet sehen sie sehr ähnlich aus, aber ein Multivektor-Modell würde wahrscheinlich sehr unterschiedliche Einbettungen für jede Instanz von „Herz“ generieren, was darstellt, wie jede im Kontext des gesamten Satzes etwas anderes bedeutet:

Der Vergleich zweier Objekte anhand ihrer Multivektor-Einbettungen beinhaltet oft die Messung ihres Chamfer-Abstands: der Vergleich jedes Teils einer Multivektor-Einbettung mit jedem Teil einer anderen und die Summierung der minimalen Abstände zwischen ihnen. Andere Systeme, einschließlich des unten beschriebenen Jina Rerankers, geben sie in ein KI-Modell ein, das speziell für die Bewertung ihrer Ähnlichkeit trainiert wurde. Beide Ansätze haben in der Regel eine höhere Präzision als der Vergleich von Einzeleinbettungen, da Einbettungen mit mehreren Vektoren viel detailliertere Informationen enthalten als solche mit einem Vektor.

Allerdings eignen sich Multivektor-Einbettungen nicht gut zum Indexieren. Sie werden häufig bei Neubewertungsaufgaben verwendet, wie im nächsten Abschnitt für das Modell jina-colbert-v2 beschrieben.

Jina-Einbettungsmodelle

Jina-Einbettungen – v4

jina-embeddings-v4 ist ein 3,8 Milliarden (3,8x10⁹) Parameter umfassendes mehrsprachiges und multimodales Einbettungsmodell, das Bilder und Texte in einer Vielzahl weit verbreiteter Sprachen unterstützt. Es verwendet eine neuartige Architektur, um visuelle Kenntnisse und Sprachkenntnisse zu nutzen, um die Leistung bei beiden Aufgaben zu verbessern, sodass es beim Abrufen von Bildern und insbesondere beim visuellen Abrufen von Dokumenten hervorragende Leistungen erbringt. Das bedeutet, dass es Bilder wie Diagramme, Dias, Karten, Screenshots, Seitenscans und Diagramme verarbeitet – gängige Bildtypen, oft mit wichtigem eingebettetem Text, die außerhalb des Bereichs von Computer-Vision-Modellen fallen, die auf Bildern realer Szenen trainiert sind.

Wir haben dieses Modell mithilfe kompakter Low-Rank Adaptation (LoRA)-Adapter für verschiedene Aufgaben optimiert. Dadurch können wir ein einzelnes Modell trainieren, um sich auf mehrere Aufgaben zu spezialisieren, ohne bei einer davon die Leistung zu beeinträchtigen – mit minimalen zusätzlichen Kosten für Speicher oder Verarbeitung.

Zu den wichtigsten Funktionen gehören:

• Spitzenleistung beim visuellen Dokumentenabruf sowie eine mehrsprachige Text- und Bildverarbeitungsleistung, die deutlich größere Modelle übertrifft.
• Unterstützung für große Eingabekontextgrößen: 32.768 Tokens entsprechen ungefähr 80 Seiten doppeltzeiligem englischen Text, und 20 Megapixel entsprechen einem Bild von 4.500 x 4.500 Pixeln.
• Vom Nutzer ausgewählte Einbettungsgrößen, von maximal 2048 Dimensionen bis zu 128 Dimensionen. Wir haben empirisch festgestellt, dass die Leistung unterhalb dieser Schwelle dramatisch abnimmt.
• Unterstützung für sowohl einzelne Einbettungen als auch Multivektor-Einbettungen. Für Texte besteht die Multivektor-Ausgabe aus einer 128-dimensionalen Einbettung für jedes Eingabetoken. Für Bilder erzeugt es eine 128-dimensionale Einbettung für jede 28x28 Pixel große Kachel, die zur Abdeckung des Bildes benötigt wird.
• Optimierung für asymmetrischen Datenabruf mittels eines Paares von LoRA-Adaptern, die speziell für diesen Zweck trainiert wurden.
• Ein LoRA-Adapter, optimiert für die Berechnung semantischer Ähnlichkeit.
• Spezielle Unterstützung für Programmiersprachen und IT-Frameworks, ebenfalls über einen LoRA-Adapter.

Wir haben jina-embeddings-v4 als allgemeines Mehrzweckwerkzeug für eine breite Palette gängiger Such-, Sprachverarbeitungs- und KI-Analyseaufgaben entwickelt. Es handelt sich im Verhältnis zu seinen Fähigkeiten um ein relativ kleines Modell, dessen Bereitstellung jedoch erhebliche Ressourcen erfordert und das sich am besten für die Nutzung über eine Cloud-API oder in einer Umgebung mit hohem Datenaufkommen eignet.

Jina-Einbettungen – v3

jina-embeddings-v3 ist ein kompaktes, leistungsstarkes, mehrsprachiges, ausschließlich textbasiertes Einbettungsmodell mit weniger als 600 Millionen Parametern. Es unterstützt bis zu 8192 Texteingabetoken und liefert Einzelvektor-Einbettungen mit vom Nutzer gewählten Größen von einem Standard von 1024 Dimensionen bis zu 64 als Ausgabe.

Wir haben jina-embeddings-v3 für eine Vielzahl von Textaufgaben trainiert – nicht nur für den Informationsabruf und die semantische Ähnlichkeit, sondern auch für Klassifikationsaufgaben wie die Sentiment-Analyse und Inhaltsmoderation sowie für Clustering-Aufgaben wie die Nachrichtenaggregation und -empfehlung. Wie jina-embeddings-v4 bietet auch dieses Modell LoRA-Adapter, die auf die folgenden Nutzungskategorien spezialisiert sind:

• Asymmetrischer Informationsabruf
• Semantische Ähnlichkeit
• Klassifizierung
• Clustering

jina-embeddings-v3 ist ein deutlich kleineres Modell als jina-embeddings-v4 mit einer deutlich reduzierten Eingabekontextgröße, aber es ist günstiger in der Nutzung. Dennoch bietet es eine sehr wettbewerbsfähige Leistung, wenn auch nur für Texte, und ist für viele Anwendungsfälle eine bessere Wahl.

Jina Code-Einbettungen

Die spezialisierten Code-Einbettungsmodelle von Jina – jina-code-embeddings (0.5b und 1.5b) – unterstützen 15 Programmierschemata und Frameworks sowie englischsprachige Texte aus dem Bereich Informatik und Informationstechnologie. Es handelt sich um kompakte Modelle mit einer halben Milliarde (0,5x10⁹) bzw. eineinhalb Milliarden (1,5x10⁹) Parametern. Beide Modelle unterstützen Eingabekontextgrößen von bis zu 32.768 Token und ermöglichen es den Nutzern, ihre Ausgabe-Einbettungsgrößen auszuwählen, von 896 bis 64 Dimensionen für das kleinere Modell und 1536 bis 128 für das größere.

Diese Modelle unterstützen asymmetrische Abrufe für fünf aufgabenspezifische Spezialisierungen, wobei Präfixabstimmung statt LoRA-Adapter verwendet wird:

• Code zu Code. Ähnlichen Code in verschiedenen Programmiersprachen abrufen. Dies wird für die Code-Ausrichtung, Code-Deduplizierung sowie die Unterstützung von Portierung und Refactoring verwendet.
• Natürliche Sprache zu Code. Abrufen von Code, um Abfragen, Kommentare, Beschreibungen und Dokumentation in natürlicher Sprache abzugleichen.
• Code zu natürlicher Sprache. Vergleichen des Codes mit der Dokumentation oder anderen Texten in natürlicher Sprache.
• Code-zu-Code-Vervollständigung. Vorschlag von relevantem Code, um bestehenden Code zu ergänzen oder zu verbessern.
• Technische Fragen und Antworten. Identifizierung von Antworten in natürlicher Sprache auf Fragen zu Informationstechnologien, ideal geeignet für Anwendungsfälle im technischen Support.

Diese Modelle bieten eine überlegene Leistung für Aufgaben, die Computerdokumentation und Programmiermaterialien erfordern, bei relativ geringen Rechenkosten. Sie eignen sich hervorragend für die Integration in Entwicklungsumgebungen und Code-Assistenten.

Jina ColBERT v2

jina-colbert-v2 ist ein Multivektor-Texteinbettungsmodell mit 560 Millionen Parametern. Es ist mehrsprachig, mit Materialien in 89 Sprachen trainiert und unterstützt variable Einbettungsgrößen sowie asymmetrischen Informationsabruf.

Wie bereits erwähnt, sind Multivektor-Einbettungen schlecht für das Indexieren geeignet, aber sehr nützlich, um die Genauigkeit von Ergebnissen anderer Suchstrategien zu erhöhen. Mit jina-colbert-v2können Sie Multivektor-Einbettungen im Voraus berechnen und sie dann verwenden, um Abrufkandidaten zur Abfragezeit neu zu ordnen. Dieser Ansatz ist weniger präzise als die Verwendung eines der Reranking-Modelle im nächsten Abschnitt, aber viel effizienter, da er nur den Vergleich gespeicherter Multivektor-Einbettungen beinhaltet, anstatt das gesamte KI-Modell für jede Abfrage und jedes Kandidatenmatch aufzurufen. Es eignet sich ideal für Anwendungsfälle, in denen die Latenz und der Rechenaufwand durch die Nutzung von Reranking-Modellen zu groß sind oder die Anzahl der Kandidaten zum Vergleich zu groß für das Reranking von Modellen ist.

Dieses Modell gibt eine Folge von Einbettungen aus – eine pro Eingabetoken – und Nutzer können Token-Einbettungen aus 128-, 96- oder 64-dimensionalen Einbettungen auswählen. Kandidaten-Textmatches sind auf 8.192 Token begrenzt. Abfragen werden asymmetrisch kodiert, daher müssen Nutzer angeben, ob ein Text eine Abfrage oder ein Kandidatenmatch ist, und die Abfragen auf 32 Token begrenzen.

Jina CLIP v2

jina-clip-v2 ist ein multimodales Einbettungsmodell mit 900 Millionen Parametern, das so trainiert wurde, dass Texte und Bilder Einbettungen erzeugen, die nahe beieinander liegen, wenn der Text den Inhalt des Bildes beschreibt. Es dient in erster Linie zum Abrufen von Bildern auf der Grundlage von Textabfragen, ist aber auch ein leistungsstarkes reines Textmodell, das die Nutzerkosten senkt, da Sie keine separaten Modelle für Text-zu-Text- und Text-zu-Bild-Abfragen benötigen.

Dieses Modell unterstützt einen Texteingabekontext von 8.192 Tokens, und Bilder werden vor der Einbettung auf 512x512 Pixel skaliert.

CLIP-Architekturen („Contrastive Language-Image Pretraining“) sind einfach zu trainieren und zu bedienen und können sehr kompakte Modelle erzeugen, aber sie haben einige grundlegende Einschränkungen. Sie können ihr Wissen aus einem Medium nicht nutzen, um ihre Leistung in einem anderen zu verbessern. Sie können nicht ein Medium nutzen, um ihre Leistung in einem anderen zu verbessern. Obwohl das System also wissen mag, dass die Wörter „dog“ und „cat“ in ihrer Bedeutung näher beieinander liegen als jedes von ihnen bei „car“, weiß es nicht unbedingt, dass ein Bild von einem Hund und ein Bild von einer Katze enger miteinander verwandt sind als jedes von ihnen bei einem Bild von einem Auto.

Sie leiden auch unter der sogenannten Modalitätslücke: Die Einbettung eines Textes über Hunde ist wahrscheinlich näher an der Einbettung eines Textes über Katzen als an der Einbettung eines Bildes von Hunden. Aufgrund dieser Einschränkung empfehlen wir, CLIP entweder als Text-zu-Bild-Abfragemodell oder als reines Textmodell zu verwenden, jedoch nicht beide in einer einzigen Abfrage zu vermischen.

Reranking-Modelle

Reranking-Modelle nehmen ein oder mehrere Kandidatenmatches zusammen mit einer Abfrage als Eingabe für das Modell und vergleichen sie direkt, wodurch deutlich präzisere Übereinstimmungen entstehen.

Grundsätzlich könnte man einen Reranker direkt für die Informationsabfrage verwenden, indem man jede Abfrage mit jedem gespeicherten Dokument vergleicht, dies wäre jedoch sehr rechenintensiv und für alle außer den kleinsten Sammlungen unpraktisch. Daher werden Reranker tendenziell zur Bewertung relativ kurzer Listen von Kandidatenmatches verwendet, die mit anderen Mitteln gefunden wurden, wie z. B. durch einbettungsbasierte Suche oder andere Algorithmen für den Informationsabruf. Reranking-Modelle eignen sich ideal für hybride und föderierte Suchverfahren, bei denen eine Suche bedeuten kann, dass Anfragen an separate Suchsysteme mit unterschiedlichen Datensätzen gesendet werden, die jeweils unterschiedliche Ergebnisse liefern. Sie sind sehr gut darin, vielfältige Ergebnisse zu einem einzigen, hochwertigen Ergebnis zu vereinen.

Die auf Einbettungen basierende Suche kann eine große Herausforderung darstellen, da sie eine Neuindizierung aller gespeicherten Daten erfordert und die Erwartungen der Nutzer an die Ergebnisse verändert. Wenn Sie einen Reranker zu einem bestehenden Suchschema hinzufügen, können Sie viele der Vorteile von KI nutzen, ohne Ihre gesamte Suchlösung neu zu entwickeln.

Jina-Reranker-Modelle

Jina Reranker m0

jina-reranker-m0 ist ein multimodaler Reranker mit 2,4 Milliarden (2,4x10⁹) Parametern, der Textanfragen und Kandidatenmatches aus Texten und/oder Bildern unterstützt. Es ist das führende Modell für die visuelle Dokumentensuche und somit eine ideale Lösung für Sammlungen von PDFs, Scans von Texten, Screenshots und anderen computergenerierten oder modifizierten Bildern, die Text oder andere semistrukturierte Informationen enthalten, sowie für gemischte Daten, die aus Textdokumenten und Bildern bestehen.

Dieses Modell nimmt eine einzelne Abfrage und einen Kandidatenmatch entgegen und gibt einen Score zurück. Wenn dieselbe Abfrage mit verschiedenen Kandidaten verwendet wird, sind die Scores vergleichbar und können zur Rangfolge herangezogen werden. Es unterstützt eine gesamte Eingabegröße von bis zu 10.240 Tokens, einschließlich des Anfragetextes und des Kandidatentextes oder -bildes. Jede 28x28 Pixel große Kachel, die zum Abdecken eines Bildes benötigt wird, zählt als Token zur Berechnung der Eingabegröße.

Jina Reranker v3

jina-reranker-v3 ist ein Text-Reranker mit 600 Millionen Parametern und modernster Leistung für Modelle vergleichbarer Größe. Im Gegensatz zu jina-reranker-m0 nimmt er eine einzelne Abfrage und eine Liste von bis zu 64 Kandidatenübereinstimmungen und gibt die Rangfolge zurück. Es hat einen Eingabekontext von 131.000 Token, einschließlich der Abfrage und aller Textkandidaten.

Jina Reranker v2

jina-reranker-v2-base-multilingual ist ein äußerst kompakter, universeller Reranker mit zusätzlichen Features, die Funktionsaufrufe und SQL-Abfragen unterstützen. Mit weniger als 300 Millionen Parametern bietet er ein schnelles, effizientes und genaues mehrsprachiges Text-Reranking mit zusätzlicher Unterstützung für die Auswahl von SQL-Tabellen und externen Funktionen, die Textabfragen entsprechen, wodurch es sich für agentenbasierte Anwendungsfälle eignet.

Kleine generative Sprachmodelle

Generative Sprachmodelle sind Modelle wie ChatGPT von OpenAI, Google Gemini und Claude von Anthropic, die Text- oder Multimedia-Eingaben aufnehmen und mit Textausgaben antworten. Es gibt keine klar definierte Grenze, die große Sprachmodelle (LLMs) von kleinen Sprachmodellen (SLMs) unterscheidet, aber die praktischen Probleme bei der Entwicklung, dem Betrieb und der Nutzung von Top-LLMs sind wohlbekannt. Die bekanntesten werden nicht öffentlich verbreitet, daher können wir ihre Größe nur schätzen, aber es wird erwartet, dass ChatGPT, Gemini und Claude im Bereich von 1 bis 3 Billionen (1–3x10¹²) Parametern liegen.

Das Ausführen dieser Modelle – selbst wenn sie öffentlich verfügbar sind – geht weit über den Umfang herkömmlicher Hardware hinaus und erfordert die fortschrittlichsten Chips, die in riesigen parallelen Arrays angeordnet sind. Der Zugriff auf LLMs ist über kostenpflichtige APIs möglich, dies verursacht jedoch erhebliche Kosten, führt zu einer hohen Latenz und lässt sich nur schwer mit den Anforderungen an Datenschutz, digitale Souveränität und Cloud-Repatriierung vereinbaren. Außerdem können die Kosten für das Training und die Anpassung von Modellen dieser Größe beträchtlich sein.

Aus diesem Grund wurde viel Forschung in die Entwicklung kleinerer Modelle gesteckt, die vielleicht nicht alle Fähigkeiten der größten LLMs haben, aber bestimmte Aufgaben genauso gut erledigen können, und das zu geringeren Kosten. Unternehmen setzen Software in der Regel ein, um spezifische Probleme zu lösen, und KI-Software bildet da keine Ausnahme. Daher sind SLM-basierte Lösungen oft LLM-basierten Lösungen vorzuziehen. Sie können üblicherweise auf Standardhardware laufen, sind schneller, verbrauchen weniger Energie und lassen sich viel leichter anpassen.

Das SLM-Angebot von Jina wächst, da wir uns darauf konzentrieren, wie wir KI am besten in praktische Suchlösungen integrieren können.

Jina SLMs

ReaderLM v2

ReaderLM-v2 ist ein generatives Sprachmodell, das HTML gemäß benutzerdefinierten JSON-Schemata und natürlichen Sprachanweisungen in Markdown oder JSON umwandelt.

Datenvorverarbeitung und -normalisierung sind ein wesentlicher Bestandteil der Entwicklung guter Suchlösungen für digitale Daten, aber reale Daten, insbesondere webbasierte Informationen, sind oft chaotisch, und einfache Umwandlungsstrategien erweisen sich häufig als sehr zerbrechlich. Stattdessen bietet ReaderLM-v2 eine intelligente KI-Modelllösung, die das Chaos eines DOM-Tree-Dumps einer Webseite verstehen und nützliche Elemente robust identifizieren kann.

Mit 1,5 Milliarden (1,5x10⁹) Parametern ist es drei Größenordnungen kompakter als modernste LLMs, leistet aber bei dieser einen engen Aufgabe auf Augenhöhe.

Jina VLM

jina-vlm ist ein generatives Sprachmodell mit 2,4 Milliarden (2,4x10⁹) Parametern, das darauf trainiert wurde, natürlichsprachliche Fragen zu Bildern zu beantworten. Es bietet eine sehr starke Unterstützung für die visuelle Dokumentenanalyse, d. h. für die Beantwortung von Fragen zu Scans, Screenshots, Folien, Diagrammen und ähnlichen nicht natürlichen Bilddaten.

Zum Beispiel:

Es ist auch sehr gut darin, Text in Bildern zu lesen:

Die wahre Stärke von jina-vlm liegt jedoch im Verständnis des Inhalts von informativen und von Menschen erstellten Bildern:

Oder:

jina-vlm ist gut geeignet für die automatische Generierung von Bildunterschriften, Produktbeschreibungen, Alternativtexten für Bilder und Barrierefreiheitsanwendungen für Sehbehinderte. Es schafft zudem Möglichkeiten für RAG-Systeme („Retrieval-Augmented-Generation“), visuelle Informationen zu verwenden, und für KI-Agenten, Bilder ohne menschliche Unterstützung zu verarbeiten.

Mit dem Elastic Agent Builder können Sie ganz einfach datenverbundene KI-Agenten erstellen. Wie das geht, zeigen wir Ihnen in diesem Blogbeitrag. Lassen Sie uns alle erforderlichen Schritte durchgehen, um einen Agenten mit einem MCP-Tool zu erstellen, der auf in Elastic gespeicherte Daten zugreift. Dann verwenden wir das Strands Agents SDK und seine A2A-Funktionen (Agent2Agent), um den Agenten zu betreiben. Das Strands Agents SDK ist eine Multiagenten-KI-Entwicklungsplattform, mit der Sie agentenbasierte Anwendungen mit genau dem Code erstellen können, der erforderlich ist, um das gewünschte Ergebnis zu erzielen.

Lassen Sie uns einen KI-Agenten entwickeln, der das Spiel RPS+ spielt, eine Variante des klassischen Spiels „Schere, Stein, Papier“ mit einer zusätzlichen Wendung: Es bietet den Spieler:innen einige zusätzliche Auswahlmöglichkeiten.

Voraussetzungen

Folgendes ist erforderlich, um die Schritte in diesem Blogbeitrag zu befolgen:

• Ein Texteditor, der auf Ihrem lokalen Computer ausgeführt wird
  • Für die Beispielanleitungen in diesem Blogbeitrag verwenden wir Visual Studio Code.
• Python 3.10 oder höher, das auf Ihrem lokalen Computer ausgeführt wird

Ein Serverless-Projekt erstellen

Als Erstes benötigen wir ein Elasticsearch Serverless-Projekt, das den Elastic Agent Builder beinhaltet.

Gehen Sie zu Cloud.elastic.co/de/ und erstellen Sie ein neues Elasticsearch Serverless-Projekt.

Einen Index erstellen und Daten hinzufügen

Als Nächstes fügen wir einige Daten zu unserem Elasticsearch-Projekt hinzu. Öffnen Sie die Entwicklertools, wo wir Befehle ausführen können, um einen neuen Index zu erstellen und einige Daten darin einzufügen. Wählen Sie im Hauptmenü „Entwicklungstools“ aus.

Kopieren Sie den folgenden PUT-Befehl und fügen Sie ihn in den Anfrage-Eingangsbereich der Konsole des Entwicklungstools ein. Diese Anweisung erstellt einen Elasticsearch-Index mit dem Namen „game-docs“.

PUT /game-docs
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { 
        "type": "text"
      },
      "filename": { "type": "keyword" },
      "last_modified": { "type": "date" }
    }
  }
}

Klicken Sie auf die Schaltfläche „Anfrage senden“, die in den Entwicklungstools rechts neben der Anweisung angezeigt wird. Sie sollten eine Benachrichtigung sehen, die bestätigt, dass der Game-docs-Index im Reaktion Flächendiagramm der Entwicklungstools erstellt wurde.

Ein Index namens game-docs ist ein großartiger Ort, um die Daten für das Spiel zu speichern, das wir gerade entwickeln. Fügen wir ein Dokument namens rps+-md in diesen Index ein, das alle Daten enthält, die unser Spiel benötigt. Kopieren Sie den folgenden PUT-Befehl und fügen Sie ihn in das Entwicklungstool ein.

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"
}

Klicken Sie auf die Schaltfläche „Anfrage senden“ neben der Anweisung, um sie auszuführen und das rps+-md-Dokument zum game-docs-Index hinzuzufügen.

Wir sollten jetzt einige Daten abfragen können, und mit Agent Builder ist das einfacher als je zuvor.

Wählen Sie Agenten aus dem Hauptnavigationsmenü aus.

Dann müssen Sie nur noch den standardmäßigen Elastic AI Agent fragen: „Welche Daten habe ich?“

Der Elastic AI Agent bewertet die Daten und liefert eine prägnante Erklärung der vorhandenen Daten.

Ein Tool erstellen

Okay, wir haben jetzt einige Daten in Elastic. Lassen Sie uns diese nutzen. Der Agent Builder bietet integrierte Unterstützung zur Erstellung von MCP-Tools, die Agenten helfen, auf die Daten zuzugreifen, die sie benötigen, um den richtigen Kontext für ihre Aufgabe zu haben. Lassen Sie uns ein einfaches Tool erstellen, das unsere Spieldaten abruft.

Klicken Sie auf das Aktionsmenü des Agent Builders.

Wählen Sie in den Menüoptionen Alle Werkzeuge anzeigenaus.

Klicken Sie auf + Neues Tool.

Wählen Sie im Formular Tool erstellen die Option ES|QL aus. Wählen Sie als Werkzeugtyp die gewünschte Option aus und geben Sie die folgenden Werte ein.

Für die Tool-ID:

example.get_game_docs

Für die Beschreibung:

Get RPS+ doc from Elasticsearch game-docs index.

Für Konfiguration geben Sie die folgende Abfrage in das ES|QL-Abfrage-Textfeld ein:

FROM game-docs | WHERE filename == "RPS+.md"

Ihr ausgefülltes Formular Tool erstellen sollte wie folgt aussehen. Klicken Sie auf Speichern, um das Tool zu erstellen.

Wir haben ein neues Werkzeug am Werkzeugständer hängen. Werkzeuge sollten nicht einfach nur an einem Regal hängen; sie sollten sinnvoll eingesetzt werden. Lassen Sie uns einen Agenten erstellen, der unser neues benutzerdefiniertes Tool verwenden kann.

Einen Agenten erstellen und ihm ein Tool zuweisen

Mit dem Agent Builder ist das Erstellen eines Agenten erfreulich einfach. Sie müssen einfach nur die Agentenanweisungen mit ein paar Details eingeben. Lassen Sie uns jetzt einen Agenten erstellen.

Klicken Sie auf Agenten verwalten.

Klicken Sie + Neuer Agent.

Geben Sie die folgenden Informationen in das Formular Neuer Agent ein.

Geben Sie für die Agenten-ID den folgenden Text ein:

rps_plus_agent

Geben Sie im Textfeld Benutzerdefinierte Anweisungen die folgenden Anweisungen ein:

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.

Geben Sie für den Anzeigenamen den folgenden Text ein:

RPS+ Agent

Für die Anzeigebeschreibung geben Sie den untenstehenden Text ein:

An agent that plays the game RPS+

Geben Sie dem Agenten das benutzerdefinierte Tool, das wir zuvor erstellt haben, indem Sie auf den Tab Tools klicken.

Wählen Sie nur das Tool example.get_game_docs aus, das wir zuvor erstellt haben.

Klicken Sie auf Speichern, um den neuen Agenten zu erstellen.

Lassen Sie uns unseren neuen Agenten ausprobieren. Es gibt einen praktischen Link, um einen Chat mit einem beliebigen Agenten aus der Liste der Agenten zu starten.

Geben Sie einfach „start game“ ein und das Spiel beginnt. Es funktioniert!

Sie können sehen, dass der Agent seine Spielobjektauswahl oben in seiner Reaktion anzeigt. Dies ist nützlich, da wir die Wahl des Agenten sehen und bestätigen können, dass das Spiel wie erwartet funktioniert. Wenn man jedoch die Wahl des Gegners kennt, bevor man selbst wählt, wird das Spiel „Schere, Stein, Papier“ nicht besonders unterhaltsam. Um das Spiel zu verfeinern und seine endgültige Form zu erreichen, können wir eine Agenten-Orchestrierungsplattform verwenden, die Agenten mit Code steuern kann.

Hier kommt das Strands Agents SDK ins Spiel.

Strands Agents SDK

Wenn Sie neugierig darauf sind, neue Frameworks für die Agentenentwicklung auszuprobieren, dann ist das Strands Agents SDK einen Versuch wert. Das Strands Agents SDK wurde von AWS (Mai 2025) als Open-Source-Python-Implementierung veröffentlicht, und es gibt jetzt auch eine Typescript-Version.

Erste Schritte mit dem Strands Agents SDK in Python

Starten Sie Ihre Programmiermaschinen. Wir werden jetzt im Eiltempo den Prozess des Klonens und Ausführens einer Beispiel-App durchgehen, die Strands Agents verwendet, um den RPS+ Agent über das A2A-Protokoll zu steuern. Lassen Sie uns eine optimierte Version des RPS+ Spiels entwickeln, bei der die Wahl des Agenten erst nach Ihrer Wahl bekannt gegeben wird, denn schließlich ist es das Rätselraten und der überraschende Ausgang, der Spiele wie „Schere, Stein, Papier“ so unterhaltsam macht.

Öffnen Sie auf Ihrem lokalen Computer Visual Studio Code und öffnen Sie ein neues Terminal.

Im neu geöffneten Terminal führen Sie folgenden Befehl aus, um das Elasticsearch Labs-Repository zu klonen:

git clone https://github.com/elastic/elasticsearch-labs

Führen Sie den folgenden cd-Befehl aus, um das Verzeichnis in das Verzeichnis „elasticsearch-labs“ zu ändern:

cd elasticsearch-labs

Führen Sie anschließend folgenden Befehl aus, um das Repository in Visual Studio Code zu öffnen:

code .

Erweitern Sie im Visual Studio File Explorer die Ordner supporting-blog-content und agent-builder-a2a-strands-agents und öffnen Sie anschließend die Datei elastic_agent_builder_a2a_rps+.py. So sieht die Datei in Visual Studio Code aus:

Hier ist der Inhalt der Datei elastic_agent_builder_a2a_rps+.py, den Sie in Ihrem Texteditor sehen sollten:

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

Lassen Sie uns einen Blick darauf werfen, was in diesem Code passiert. Ausgehend von der Methode main() greift der Code zunächst auf die Umgebungsvariablen für die Agenten-URL und den API-Schlüssel zu. Dann verwenden wir diese Werte, um ein httpx client zu erstellen, mit dem wir die Agentenkarte für den Agenten abrufen können. Der Client verwendet dann die Agentenkartendaten, um eine „Spiel starten“-Anfrage an den Agenten zu senden. Interessant ist hierbei, dass wir einen random_game_object -Wert als Teil der "start game" -Anfrage einfügen. Dieser Wert ist eine Zufallszahl, die mit dem Zufallsmodul der Standardbibliothek von Python generiert wird. Der Grund dafür ist, dass sich herausgestellt hat, dass die leistungsstarken LLMs (die KI-Agenten ermöglichen) nicht besonders gut in Bezug auf Zufälligkeit sind. Kein Problem, hier kann Python helfen.

Im weiteren Verlauf des Codes wird, sobald der Agent auf die Anfrage „Spiel starten“ antwortet, die Spielobjektauswahl des Agenten extrahiert und in der Variable agent_choice gespeichert. Der Rest der Reaktion wird dem:der Nutzer:in als Text angezeigt. Anschließend wird der:die Nutzer:in zur Eingabe der eigenen Spielobjektauswahl aufgefordert. Diese Auswahl wird an den Agenten gesendet. Der Code zeigt dann die Auswahl des Spielobjekts durch den Agenten sowie dessen endgültige Entscheidung über den Spielausgang an.

Einrichten Ihrer Agenten-URL und Ihres API-Schlüssels als Umgebungsvariablen

Da die Beispiel-App auf Ihrem lokalen Computer ausgeführt wird, müssen wir dem Strands Agents SDK eine A2A-URL und einen API-Schlüssel für den Agenten bereitstellen, damit dieser mit unserem Agent Builder-Agenten kommunizieren kann. Die Beispiel-App verwendet eine Datei namens .env, um diese Werte zu speichern.

Erstellen Sie eine Kopie der Datei env.example und benennen Sie die neue Datei .env.

Wechseln Sie zurück zum Elastic Agent Builder, wo wir die beiden benötigten Werte abrufen können.

Wählen Sie im Aktionsmenü des Agent Builders oben rechts auf der Seite die Option Alle Tools anzeigen aus.

Klicken Sie oben auf der Seite „Tools“ auf das Dropdown-Menü MCP-Server und wählen Sie MCP-Server-URL kopieren.

Fügen Sie die MCP-Server-URL als Ersatz für den <YOUR-ELASTIC-AGENT-BUILDER-URL>-Platzhalterwert in die .env-Datei ein. Nun müssen wir eine Aktualisierung an der URL vornehmen, das heißt, den Endtext „mcp“ durch „a2a“ ersetzen, da das A2A-Protokoll dasjenige ist, das das Agent Strands SDK zur Kommunikation mit dem in Elastic Agent Builder ausgeführten Agenten verwenden wird.

Die bearbeitete URL sollte in etwa so aussehen:

https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2a

Der andere Wert, den wir hier in Elastic Cloud brauchen, ist ein API-Schlüssel. Klicken Sie in der oberen Navigationsebene auf Elasticsearch.

Klicken Sie auf die Schaltfläche API-Schlüssel kopieren, um den API-Schlüssel zu kopieren.

Zurück in Visual Studio Code fügen Sie nun den API-Schlüssel in die .env-Datei ein, um den Platzhaltertext <YOUR-ELASTIC-API-KEY> zu ersetzen. Ihre .env-Datei sollte etwa so aussehen:

Die Beispiel-App ausführen

Öffnen Sie ein neues Terminal in Visual Studio Code.

Führen Sie zunächst den folgenden cd-Befehl im Terminal aus:

cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agents

Führen Sie den folgenden Befehl aus, um eine virtuelle Python-Umgebung zu erstellen.

python -m venv .venv

Führen Sie je nach Betriebssystem Ihres lokalen Computers den folgenden Befehl aus, um die virtuelle Umgebung zu aktivieren.

• macOS/Linux

source .venv/bin/activate

• Windows

.venv\Scripts\activate

Die Beispiel-App verwendet das Strands Agents SDK, und wir sind nun an dem Punkt in dieser Anleitung angelangt, an dem wir es installieren müssen. Führen Sie folgenden Befehl aus, um das Strands Agents SDK zusammen mit allen erforderlichen Python-Bibliotheksabhängigkeiten zu installieren.

pip install -r requirements.txt

Es ist Zeit, die Startrampe freizumachen und den Countdown zu starten. Wir sind bereit, diese App zu starten. Zurücktreten. Führen wir sie mit folgendem Befehl aus:

python elastic_agent_builder_a2a_rps+.py

Sie sollten mit einer Partie RPS+ herausgefordert werden. Gut gemacht und viel Erfolg!

Erstellen Sie Ihre KI-Apps mit relevantem Kontext

Die Entwicklung eines KI-Agenten gehört nun zu Ihren Kernkompetenzen. Und Sie haben gesehen, wie einfach die Verwendung von Elastic Agent Builder-Agenten über A2A in Agenten-Entwicklungs-Frameworks wie dem Strands Agents SDK ist. Testen Sie Elastic, um KI-Agenten zu erstellen, die mit dem relevanten Kontext Ihrer benutzerdefinierten Daten verknüpft sind.

Wir haben vor Kurzem zum Open-Source-Projekt Google MCP Toolbox for Databases beigetragen, indem wir Unterstützung für Elasticsearch als Datenbank hinzugefügt haben.

Mit diesem neuen Feature können Sie jetzt die Google MCP Toolbox verwenden, um eine Verbindung zu Elasticsearch herzustellen und direkt mit Ihren Daten zu „kommunizieren“.

Elasticsearch

Wir benötigen eine laufende Elasticsearch-Instanz. Sie können eine kostenlose Testversion auf Elastic Cloud aktivieren oder es lokal mit dem start-local-Skript installieren:

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

Dadurch werden Elasticsearch und Kibana auf Ihrem Computer installiert und ein API-Schlüssel generiert, der zur Konfiguration der Google MCP Toolbox verwendet wird.

Der API-Schlüssel wird als Ausgabe des vorherigen Befehls angezeigt und in einer .env-Datei im Ordner elastic-start-local gespeichert.

Installieren Sie den Beispieldatensatz

Nach der Installation können Sie sich mit dem Benutzernamen elastic und dem vom start-local-Skript generierten Passwort (gespeichert in einer .env-Datei) bei Kibana anmelden.

Sie können den Datensatz für E-Commerce-Bestellungen , der von Kibana verfügbar ist, installieren. Sie enthält einen einzigen Index namens kibana_sample_data_ecommerce, der Informationen über 4.675 Bestellungen von einer E-Commerce-Website enthält. Für jede Bestellung haben wir folgende Informationen:

• Kundeninformationen (Name, Ausweis, Geburtsdatum, E-Mail-Adresse usw.)
• Bestelldatum
• Bestell-ID
• Produkte (Liste aller Produkte mit Preis, Menge, ID, Kategorie, Rabatt usw.)
• SKU
• Gesamtpreis (ohne Steuern, mit Steuern)
• Gesamtmenge
• Geoinformationen (Stadt, Land, Kontinent, Ort, Region)

Um die Beispieldaten zu installieren, öffnen Sie die Seite Integrationen in Kibana (suchen Sie in der Suchleiste oben nach „Integration“) und installieren Sie die „Beispieldaten“. Weitere Details finden Sie in der Dokumentation hier: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

Ziel dieses Artikels ist es, zu zeigen, wie einfach es ist, die Google MCP Toolbox so zu konfigurieren, dass sie sich mit Elasticsearch verbindet und mit dem kibana_sample_data_ecommerce-Index in natürlicher Sprache interagiert.

Google MCP Toolbox

Die Google MCP Toolbox ist ein Open-Source-MCP-Server, der entwickelt wurde, um Anwendungen und KI-Agenten die sichere und effiziente Interaktion mit Datenbanken zu erleichtern. Das Projekt, das zuvor unter dem Namen „GenAI Toolbox for Databases“ bekannt war, wurde nach der vollständigen Kompatibilität mit dem Model Context Protocol (MCP) umbenannt. Ziel ist es, den üblicherweise beim Verbinden von Agenten mit Datenbanken erforderlichen hohen Aufwand zu reduzieren, indem Verbindungspooling, Authentifizierung, Beobachtbarkeit und andere betriebliche Belange im Hintergrund übernommen werden.

Im Kern ermöglicht es die Toolbox Entwicklern, wiederverwendbare, hochwertige Werkzeuge zu definieren, die Datenbankinteraktionen kapseln. Diese Tools können dann von jedem MCP-kompatiblen Client – wie beispielsweise einem KI-Agenten – aufgerufen werden, ohne dass der Client Low-Level-SQL-Abfragen implementieren oder Datenbankverbindungen verwalten muss. Dieser Ansatz reduziert die Menge an Boilerplate-Code, die für den Aufbau datenbankbewusster Agenten benötigt wird, drastisch und ermöglicht die Integration fortgeschrittener Datenoperationen in nur wenigen Anwendungszeilen. Sobald ein Werkzeug definiert ist, kann es von mehreren Agenten, Frameworks oder Sprachen gemeinsam genutzt werden (Abbildung 1).

Ein großer Vorteil der Nutzung der Toolbox ist das integrierte Sicherheitsmodell. Authentifizierungsabläufe wie OAuth2 und OIDC werden nativ unterstützt, sodass Entwickler:innen die Verarbeitung oder Speicherung sensibler Datenbankzugangsdaten in Agenten vermeiden können. Die Plattform bietet außerdem Beobachtbarkeit-Features – einschließlich Metriken und Tracing – über OpenTelemetry, was für Debugging, Monitoring und Deployments in der Produktionsumgebung unerlässlich ist. Insgesamt dient die MCP Toolbox als einheitliche, sichere und erweiterbare Schnittstelle zur Interaktion mit Ihren Daten von jedem MCP-fähigen System.

So installieren Sie die MCP Toolbox

Sie können den MCP-Toolbox-Server unter Linux mit folgendem Befehl installieren:

export VERSION=0.21.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Für eine Installation unter macOS oder Windows können Sie den hier beschriebenen Anweisungen folgen.

Toolbox für Elasticsearch konfigurieren

Um die MCP Toolbox für Elasticsearch zu konfigurieren, müssen wir eine tools.yaml-Datei erstellen, und zwar wie folgt:

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

Sie müssen den Wert <insert-here-api-key> durch einen gültigen Elasticsearch-API-Schlüssel ersetzen. Wenn Sie Elasticsearch lokal mit start-local ausführen, finden Sie den API-Schlüssel in der von start-local generierten .env-Datei unter der Variable ES_LOCAL_API_KEY. Wenn Sie Elastic Cloud verwenden, können Sie einen API-Schlüssel generieren, indem Sie das hier beschriebene Verfahren befolgen.

Die vorherigen Tools enthalten die folgende ES|QL-Abfrage für Elasticsearch:

FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name)

Falls Ihnen ES|QL nicht geläufig ist: Es handelt sich um eine von Elastic entwickelte Abfragesprache, die ähnlich wie SQL funktioniert und mit der man einen oder mehrere Indizes durchsuchen kann. Mehr über ES|QL finden Sie in der offiziellen Dokumentation hier.

Die obige Abfrage sucht nach allen im kibana_sample_data_ecommerce-Index gespeicherten Bestellungen, die den Namen des:der angegebenen Kund:in enthalten, und verwendet den ?name-Parameter (das Fragezeichen bezeichnet einen Parameter).

Der Name des Kunden wird in der vorherigen YAML-Konfiguration mit dem Typ „Zeichenfolge“ und der Beschreibung „Der Name des Kunden“ definiert.

Mit diesem Tool können Fragen zu den Bestellungen eines:einer Kund:in beantwortet werden – zum Beispiel: Wie viele Bestellungen hat Kund:in Foo im Oktober 2025 aufgegeben?

Die Beschreibungen der Werkzeuge und ihrer Parameter sind unerlässlich, um die relevanten Informationen aus der natürlichsprachlichen Anfrage des:der Nutzer:in zu extrahieren. Diese Extraktion erfolgt mithilfe der Funktionsaufruf-Funktion eines Large Language Models (LLM). In der Praxis kann ein LLM bestimmen, welche Funktion (welches Werkzeug) ausgeführt werden muss, um die notwendigen Informationen zu erhalten, sowie die entsprechenden Parameter für diese Funktion.

Für weitere Informationen zu Funktionsaufrufen empfehlen wir, den Artikel OpenAI Function Calling with Elasticsearch von Ashish Tiwari zu lesen.

Führen Sie den Toolbox-Server aus

Sie können die MCP Toolbox unter Verwendung der vorherigen tools.yaml-Datei mit folgendem Befehl ausführen:

./toolbox --tools-file tools.yaml --ui

Der Parameter –ui führt eine Webanwendung unter http://127.0.0.1:5000/ui aus (Abbildung 2).

Sie können die Option Tools > customer-orders auswählen und im Feld Parametername einen Kundennamen eingeben (z. B. Gwen Sanders) und anschließend auf die Schaltfläche Tool ausführen klicken. Sie sollten eine JSON-Reaktion sehen, wie in Abbildung 3 dargestellt.

Die Einrichtung ist abgeschlossen, und die MCP Toolbox kann das Tool customer-orders ausführen, um mit Elasticsearch zu kommunizieren und dabei die ES|QL-Anfrage auszuführen.

Verwendung der MCP Toolbox mit Gemini CLI

Wir können jeden beliebigen MCP-Client verwenden, um mit der MCP Toolbox für Datenbanken zu kommunizieren. Zum Beispiel können wir Gemini CLI verwenden, ein Befehlszeilen-Tool zur Nutzung von Gemini. Sie können die Gemini CLI gemäß den hier beschriebenen Anweisungen installieren.

Gemini CLI bietet eine vorkonfigurierte Erweiterung für die MCP Toolbox an, verfügbar unter gemini-cli-extensions/mcp-toolbox. Sie können diese Erweiterung installieren, indem Sie folgenden Befehl ausführen:

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Nach der Installation müssen Sie in das Verzeichnis gehen, in dem Sie die Konfigurationsdatei tools.yaml für die MCP Toolbox gespeichert haben, und Gemini CLI wie folgt ausführen (dieser Schritt ist erforderlich, damit die Gemini-CLI automatisch mit der MCP-Toolbox konfiguriert wird):

gemini

In Abbildung 4 sollten Sie eine Ausgabeanzeige sehen.

Mit dem folgenden Befehl können Sie überprüfen, ob die MCP Toolbox verbunden ist:

/mcp list

Sie sollten die mcp_toolbox mit den aufgelisteten Tools customer-orders sehen (Abbildung 5).

Wenn die MCP Toolbox mit der Gemini CLI verbunden ist, können wir nun versuchen, einige Fragen zu stellen, wie zum Beispiel: „ Gib mir die Bestellungen für die Kundin Gwen Sanders.“ Anschließend fordert die Gemini CLI die Berechtigung an, das Tool customer-orders vom Server mcp_toolbox auszuführen (siehe Abbildung 6).

Nach der Bestätigung führt Gemini CLI die Anfrage an die MCP Toolbox aus und erhält als Ergebnis eine JSON-Reaktion, die zur Formatierung der Reaktion verwendet wird (Abbildung 7).

Die Reaktion von Gemini CLI wird berichten, dass Gwen Sanders lediglich eine Bestellung über zwei Produkte zum Gesamtpreis von 132 Euro aufgegeben hat.

MCP Toolbox SDKs

Die Google MCP Toolbox bietet außerdem ein SDK an, um alle Funktionen eines in Go, Python und Javascript geschriebenen Programms abzurufen.

Das Python SDK ist beispielsweise auf GitHub unter folgender Seite verfügbar: https://github.com/googleapis/mcp-toolbox-sdk-python.

Wir müssen einen einfachen Agenten erstellen, der mit der MCP Toolbox verbunden werden kann. Wir müssen die folgenden Pakete installieren:

pip install toolbox-core
pip install google-adk

Und erstellen Sie ein neues Agentenprojekt mit folgendem Befehl:

adk create my_agent

Dadurch wird ein neues Verzeichnis namens my_agent mit einer Datei agent.py erstellt.

Aktualisieren Sie my_agent/agent.py mit dem folgenden Inhalt, um eine Verbindung zu Toolbox herzustellen:

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

Erstellen Sie eine .env-Datei mit Ihrem Google API-Schlüssel:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

Schließlich können wir den Agenten ausführen und die Ergebnisse beobachten. Um den Agenten auszuführen, können Sie folgenden Befehl ausführen:

adk run my_agent

Alternativ können Sie ihn über eine Webschnittstelle bereitstellen:

adk web --port 8000

In beiden Tickets können Sie mit der MCP Toolbox über eine Q&A-Schnittstelle interagieren. Sie können zum Beispiel die vorherige Frage stellen: Geben Sie mir die Bestellungen der Kundin Gwen Sanders.

Weitere Informationen zu den verschiedenen SDKs finden Sie auf dieser Dokumentationsseite.

Fazit

In diesem Artikel haben wir die Elasticsearch-Integration für die Google MCP Toolbox for Databases demonstriert. Mithilfe einer einfachen YAML-Konfigurationsdatei können wir eine Reihe von Tools definieren, die Fragen in natürlicher Sprache mithilfe der ES|QL-Sprache in Elasticsearch-Abfragen übersetzen.

Wir haben gezeigt, wie man mit dem Datensatz kibana_sample_data_ecommerce interagiert, der Bestellungen von einer Website enthält. Mit dieser Konfigurationsdatei können wir den MCP Toolbox-Server einfach ausführen und uns von jedem MCP-Client aus mit ihm verbinden.

Abschließend haben wir gezeigt, wie man die Gemini-CLI als Client nutzt, um sich mit der MCP Toolbox for Databases zu verbinden und die in Elasticsearch gespeicherten E-Commerce-Daten abzufragen. Wir haben eine Abfrage in natürlicher Sprache ausgeführt, um Informationen über Bestellungen für eine:n bestimmte:n, namentlich identifizierte:n Kund:in abzurufen.

Während das MCP-Ökosystem weiter wächst, schafft dieses Muster – leichte Werkzeugdefinitionen mit sicherer, produktionsreifer Infrastruktur – neue Möglichkeiten, immer leistungsfähigere, datenbewusste Agenten mit minimalem Aufwand zu entwickeln. Ob Sie nun lokal mit den Elastic-Beispieldatensätzen experimentieren oder Suchfunktionen in eine größere Anwendung integrieren, die MCP Toolbox bietet eine zuverlässige, erweiterbare Grundlage für die Interaktion mit Ihren Elasticsearch-Daten unter Verwendung natürlicher Sprache.

Weitere Informationen zur Entwicklung agentischer KI-Anwendungen finden Sie im Artikel Building AI Agentic Workflows with Elasticsearch von Anish Mathur und Dana Juratoni.

Weitere Informationen über die Google MCP Toolbox finden Sie unter https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

Bei der Behebung dieses einen Problems werden jedoch versehentlich andere Abfragen beeinträchtigt, da nicht alle Fälle manuell getestet werden konnten. Aber wie können Sie oder Ihr QA-Team testen, ob eine Änderung in einer Abfrage Auswirkungen auf andere Abfragen hat? Noch wichtiger: Wie können Sie sicher sein, dass Ihre Änderungen eine Abfrage tatsächlich verbessert haben?

In Richtung einer systematischen Bewertung

Hier kommen Bewertungslisten ins Spiel. Anstatt bei jeder Änderung auf manuelle und subjektive Tests angewiesen zu sein, können Sie einen festen Satz von Abfragen festlegen, die für Ihren Anwendungsfall relevant sind, zusammen mit den entsprechenden Ergebnissen.

Dieser Satz wird zu Ihrer Referenzgrundlage. Bei jeder Änderung, die Sie vornehmen, nutzen Sie diese, um zu bewerten, ob sich Ihre Suche tatsächlich verbessert hat oder nicht.

Der Wert dieses Ansatzes liegt in Folgendem:

• Beseitigt Unsicherheit: Sie müssen sich nicht mehr fragen, ob Ihre Änderungen andere Anfragen beeinflussen; die Daten werden es Ihnen mitteilen.
• Stoppt das manuelle Testen: Sobald die Bewertungssätze aufgezeichnet sind, erfolgt der Test automatisch.
• Unterstützt Veränderungen: Sie können klare Metriken zeigen, die die Vorteile einer Veränderung untermauern.

So beginnen Sie mit dem Erstellen Ihrer Bewertungsliste

Eine der einfachsten Möglichkeiten ist die Auswahl einer repräsentativen Abfrage und die manuelle Auswahl der relevanten Dokumente. Zur Erstellung dieser Liste haben Sie zwei Möglichkeiten:

• Binäre Bewertungen: Jedes Dokument, das mit einer Suchanfrage verknüpft ist, erhält ein einfaches Tag: relevant (in der Regel mit einer Punktzahl von „1“) und nicht relevant („0“).
• Abgestufte Bewertungen: Hier erhält jedes Dokument eine Punktzahl mit unterschiedlichen Stufen. Beispiel: Festlegung einer Skala von 0 bis 4, ähnlich einer Likert-Skala, wobei 0 = „überhaupt nicht relevant” und 4 = „vollkommen relevant” bedeutet, mit Varianten wie „relevant”, „eher relevant” usw.

Binäre Urteile funktionieren gut, wenn die Suchintention klare Grenzen hat: Sollte dieses Dokument in den Ergebnissen enthalten sein oder nicht?

Abgestufte Bewertungen sind vor allem bei Grauzonen sinnvoll: Einige Ergebnisse sind besser als andere, sodass Sie „sehr gute“, „gute“ und „nutzlose“ Ergebnisse erhalten und Metriken verwenden können, die die Reihenfolge der Ergebnisse und das Feedback der Benutzer bewerten. Allerdings haben abgestufte Skalen auch Nachteile: Verschiedene Prüfer können die Bewertungsstufen unterschiedlich anwenden, was die Ergebnisse weniger konsistent macht. Und da bei abgestuften Metriken höhere Werte stärker gewichtet werden, kann selbst eine kleine Änderung (z. B. eine Bewertung von 3 statt 4) zu einer viel größeren Verschiebung der Metrik führen, als vom Prüfer beabsichtigt. Diese zusätzliche Subjektivität macht abgestufte Bewertungen im Laufe der Zeit unübersichtlicher und schwieriger zu verwalten.

Muss ich die Dokumente selbst klassifizieren?

Nicht unbedingt, da es verschiedene Möglichkeiten gibt, Ihre Bewertungsliste zu erstellen, jede mit ihren eigenen Vor- und Nachteilen:

• Explizite Bewertungen: Hier gehen SMEs jede Anfrage/jedes Dokument durch und entscheiden manuell, ob (oder inwieweit) sie relevant ist. Obwohl dies Qualität und Kontrolle bietet, ist die Skalierbarkeit geringer.
• Implizite Bewertungen: Mit dieser Methode leiten Sie die relevanten Dokumente auf der Grundlage des tatsächlichen Nutzerverhaltens wie Klicks, Abwanderungsraten und Käufe ab. Mit diesem Ansatz können Sie Daten automatisch erfassen, allerdings könnten die Ergebnisse verzerrt sein. Zum Beispiel klicken Nutzer häufiger auf Top-Ergebnisse, auch wenn sie nicht relevant sind.
• KI-generierte Bewertungen: Diese letzte Option verwendet Modelle (wie LLMs), um Anfragen und Dokumente automatisch zu bewerten, oft als LLM-Jurys bezeichnet. Sie lässt sich schnell und einfach skalieren, doch die Qualität der Daten hängt von der Qualität des verwendeten Modells und davon ab, wie gut die LLM-Trainingsdaten mit Ihren Geschäftsinteressen übereinstimmen. Wie bei menschlichen Bewertungen können auch LLM-Jurys ihre eigenen Vorurteile oder Inkonsistenzen einbringen. Daher ist es wichtig, ihre Ergebnisse anhand einer kleineren Gruppe vertrauenswürdiger Bewertungen zu validieren. LLM-Modelle sind von Natur aus probabilistisch, daher ist es nicht ungewöhnlich, dass ein LLM-Modell dem gleichen Ergebnis unterschiedliche Bewertungen zuweist, unabhängig davon, ob der Temperaturparameter auf 0 gesetzt wird.

Unten finden Sie einige Empfehlungen zur Auswahl der besten Methode für die Erstellung Ihres Bewertungssatzes:

• Entscheiden Sie, wie kritisch einige Features für Sie sind, die nur Nutzer richtig bewerten können (wie Preis, Marke, Sprache, Stil und Produktdetails). Wenn diese kritisch sind, benötigen Sie explizite Bewertungen für mindestens einen Teil Ihrer Bewertungsliste.
• Verwenden Sie implizite Bewertungen, wenn Ihre Suchmaschine bereits genügend Traffic hat, sodass Sie Metriken zu Klicks, Conversions und Verweildauer nutzen können, um Nutzungstrends zu erkennen. Sie sollten diese dennoch sorgfältig interpretieren und sie mit Ihren expliziten Bewertungssätzen vergleichen, um Verzerrungen zu vermeiden (z. B.: Nutzer neigen dazu, häufiger auf die Ergebnisse mit den höchsten Platzierungen zu klicken, auch wenn Ergebnisse mit niedrigeren Platzierungen relevanter sind)

Um dieses Problem zu beheben, werden mithilfe von Techniken zur Positionsentzerrung Klickdaten angepasst oder neu gewichtet, um das tatsächliche Interesse der Nutzer besser widerzuspiegeln. Mögliche Ansätze hierfür sind:

• Ergebnisse neu mischen: Ändern Sie die Reihenfolge der Suchergebnisse für eine Untergruppe von Nutzern, um zu schätzen, wie sich die Position auf die Klicks auswirkt.
• Zu den Click-Modellen gehören Dynamic Bayesian Network DBN, Nutzer Browsing Model UBM. Diese statistischen Modelle schätzen die Wahrscheinlichkeit, dass ein Klick echtes Interesse widerspiegelt und nicht nur die Position, indem sie Muster wie Scrollverhalten, Verweildauer, Klicksequenz und Rückkehr zur Ergebnisseite verwenden.

Beispiel: App zur Filmbewertung

Voraussetzungen

Um dieses Beispiel auszuführen, benötigen Sie einen laufenden Elasticsearch 8.x-Cluster, lokal oder Elastic Cloud Hosted (gehostet oder serverlos), sowie Zugriff auf die REST API oder Kibana.

Stellen Sie sich eine App vor, in der Nutzer ihre Meinungen zu Filmen hochladen und auch nach Filmen suchen können, die sie sich ansehen möchten. Da die Texte von den Nutzern selbst geschrieben werden, können sie Tippfehler und viele Ausdrucksvariationen aufweisen. Daher ist es unerlässlich, dass die Suchmaschine diese Vielfalt interpretieren und den Nutzern hilfreiche Ergebnisse liefern kann.

Um Abfragen wiederholen zu können, ohne das gesamte Suchverhalten zu beeinträchtigen, hat das Business-Team in Ihrem Unternehmen anhand der häufigsten Suchanfragen die folgenden binären Bewertungssätze erstellt:

Erstellung des Indexes:

PUT movies
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text"
      }
    }
  }
}

BULK-Anfrage:

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." }

Nachfolgend finden Sie die Elasticsearch-Abfrage, die die App verwendet:

GET movies/_search
{
 "query": {
   "match": {
     "text": {
       "query": "DiCaprio performance",
       "minimum_should_match": "100%"
     }
   }
 }
}

Von der Bewertung zu den Metriken

Für sich genommen liefern Bewertungslisten nicht viele Informationen; sie stellen lediglich eine Erwartung der Ergebnisse unserer Abfragen dar. Ihre wahre Stärke zeigen sie, wenn wir sie zur Berechnung objektiver Metriken zur Messung unserer Suchleistung verwenden.

Heutzutage umfassen die meisten gängigen Metriken Folgendes:

• Genauigkeit: Misst den Anteil der Ergebnisse, die innerhalb aller Suchergebnisse tatsächlich relevant sind.
• Recall: Misst den Anteil relevanter Ergebnisse, die die Suchmaschine unter den x Ergebnissen gefunden hat.
• Discounted Cumulative Gain (DCG): Misst die Qualität der Rangfolge der Ergebnisse, wobei die relevantesten Ergebnisse ganz oben stehen sollten.
• Mean Reziprocal Rank (MRR): Misst die Position des ersten relevanten Ergebnisses. Je höher es in der Liste steht, desto höher ist der Score.

Anhand derselben App zur Bewertung von Filmen berechnen wir die Recall-Metrik, um festzustellen, ob Informationen in unseren Abfragen ausgelassen werden.

In Elasticsearch können wir die Bewertungslisten nutzen, um Metriken über die Ranking Evaluation API zu berechnen. Diese API erhält als Eingabe die Bewertungsliste, die Abfrage und die zu bewertende Metrik und gibt einen Wert zurück, der einen Vergleich des Abfrageergebnisses mit der Bewertungsliste darstellt.

Lassen Sie uns die Ergebnisliste für die beiden vorliegenden Anfragen ausführen:

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
     }
 }
}

Wir verwenden zwei Anfragen an _rank_eval: eine für die DiCaprio-Abfrage und eine für traurige Filme. Jede Anfrage enthält eine Fragestellung und die dazugehörige Bewertungsliste (Bewertungen). Wir müssen nicht alle Dokumente bewerten, da diejenigen, die nicht in die Bewertung einbezogen werden, als unbewertet gelten. Für die Berechnungen berücksichtigt Recall nur den „relevanten Satz“, also die Dokumente, die für die Bewertung als relevant gelten.

In diesem Fall hat die DiCaprio-Abfrage einen Recall von 1, während die traurigen Filme einen Recall von 0 haben. Das bedeutet, dass wir bei der ersten Abfrage alle relevanten Ergebnisse erhalten haben, während wir bei der zweiten Abfrage keine Ergebnisse erhalten haben. Der durchschnittliche Recall beträgt daher 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": {}
}

Vielleicht sind wir mit dem Parameter minimum_should_match zu streng, da wir durch die Forderung, dass 100 % der Wörter in der Suchanfrage in den Dokumenten vorkommen müssen, wahrscheinlich relevante Ergebnisse auslassen. Entfernen wir den Parameter minimum_should_match, damit ein Dokument als relevant angesehen wird, wenn nur ein Wort aus der Suchanfrage darin vorkommt.

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
     }
 }
}

Wie Sie sehen können, erhalten wir durch Entfernen des Parameters minimum_should_match in einer der beiden Abfragen nun in beiden Fällen einen durchschnittlichen Recall von 1.

{
  "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": {}
}

Zusammenfassend lässt sich sagen, dass durch das Entfernen der Klausel „minimum_should_match: 100%“ eine perfekte Trefferquote für beide Abfragen erzielt werden kann.

Wir haben es geschafft! Richtig?

Nicht so schnell!

Durch die Verbesserung des Recalls öffnen wir die Tür zu einer größeren Bandbreite an Ergebnissen. Jede Anpassung impliziert jedoch einen Kompromiss. Deshalb ist es wichtig, vollständige Testfälle festzulegen und verschiedene Metriken zur Bewertung von Änderungen zu verwenden.

Die Verwendung von Bewertungslisten und Metriken verhindert, dass Sie Änderungen blind vornehmen, da Sie nun über Daten verfügen, die diese stützen. Die Validierung erfolgt nicht mehr manuell und wiederholt, und Sie können Ihre Änderungen in mehr als nur einem Anwendungsfall testen. Darüber hinaus können Sie mit A/B-Tests live testen, welche Konfiguration für Ihre Nutzer und Ihren Anwendungsfall am besten geeignet ist, wodurch sich der Kreis von technischen Metriken und realen Metriken schließt.

Abschließende Empfehlungen zur Verwendung von Bewertungslisten

Bei der Arbeit mit Bewertungslisten geht es nicht nur um das Messen, sondern auch darum, einen Rahmen zu schaffen, der es Ihnen ermöglicht, mit Zuversicht zu iterieren. Zu diesem Zweck beachten Sie folgende Empfehlungen:

1. Fangen Sie klein an, aber fangen Sie an. Sie benötigen keine 10.000 Anfragen mit jeweils 50 Bewertungslisten. Sie müssen lediglich die 5 bis 10 wichtigsten Suchanfragen für Ihren Anwendungsfall identifizieren und festlegen, welche Dokumente Ihrer Meinung nach ganz oben in den Ergebnissen erscheinen sollten. Damit haben Sie bereits eine Grundlage. Sie möchten in der Regel mit den Top-Suchanfragen sowie den Suchanfragen ohne Ergebnisse beginnen. Sie können auch mit einer einfach zu konfigurierenden Metrik wie Genauigkeit beginnen und sich dann in der Komplexität steigern.
2. Validieren Sie mit Nutzern. Ergänzen Sie die Zahlen durch A/B-Tests in der Produktion. Auf diese Weise können Sie feststellen, ob Änderungen, die in den Metriken gut aussehen, auch tatsächlich Auswirkungen haben.
3. Führen Sie die Liste weiter. Ihr Anwendungsfall wird sich weiterentwickeln. Und damit auch Ihre kritischen Fragen. Aktualisieren Sie Ihre Bewertung regelmäßig, um neue Anforderungen zu berücksichtigen.
4. Integrieren Sie sie in Ihren Workflow. Integrieren Sie Bewertungslisten in Ihre Entwicklungs-Pipelines. Stellen Sie sicher, dass jede Konfigurationsänderung, jedes Synonym und jede Textanalyse automatisch mit Ihrer Basisliste abgeglichen wird.
5. Verbinden Sie technisches Wissen mit Strategie. Beschränken Sie sich nicht auf die Messung technischer Metriken wie Genauigkeit oder Recall. Nutzen Sie Ihre Bewertungsergebnisse, um die Geschäftsergebnisse zu verbessern.

Was ist LangGraph?

LangGraph ist ein Framework zum Erstellen von KI-Agenten und deren Orchestrierung in einem Workflow, um KI-unterstützte Anwendungen zu entwickeln. LangGraph verfügt über eine Knotenarchitektur, in der wir Funktionen deklarieren können, die Aufgaben darstellen, und diese als Knoten des Workflows zuweisen können. Das Ergebnis der Interaktion mehrerer Knoten ist ein Graph. LangGraph ist Teil des umfassenderen LangChain-Ökosystems, das Tools für die Erstellung modularer und zusammensetzbarer KI-Systeme bereitstellt.

Zur Veranschaulichung dessen, warum LangGraph nützlich ist, werden wir eine problematische Situation damit lösen.

Überblick über die Lösung

In einem Risikokapitalunternehmen haben Investoren Zugriff auf eine umfangreiche Datenbank mit zahlreichen Filteroptionen, aber wenn man Kriterien kombinieren möchte, wird es schwierig und langsam. Dies kann dazu führen, dass einige relevante Start-ups für Investitionen nicht entdeckt werden. Das Ergebnis: Man verbringt viele Stunden damit, die besten Kandidaten zu identifizieren, oder verpasst sogar Chancen.

Mit LangGraph und Elasticsearch können wir gefilterte Suchen in natürlicher Sprache durchführen, sodass Nutzer komplexe Anfragen mit Dutzenden von Filtern nicht manuell erstellen müssen. Um die Flexibilität zu erhöhen, entscheidet der Workflow anhand der Nutzereingaben automatisch zwischen zwei Abfragetypen.

• Investitionsorientierte Anfragen: Diese zielen auf finanzielle und finanzierungsbezogene Aspekte von Start-ups ab, wie Finanzierungsrunden, Bewertung oder Umsatz. Beispiel: „Suche Start-ups mit einer Series-A- oder Series-B-Finanzierung zwischen 8 und 25 Mio. Dollar und einem monatlichen Umsatz von über 500.000 Dollar.“
• Marktorientierte Anfragen: Diese konzentrieren sich auf Branchensegmente, geografische Märkte oder Geschäftsmodelle und helfen dabei, Chancen in bestimmten Sektoren oder Regionen zu identifizieren. Beispiel: „Suche Fintech- und Healthcare-Start-ups in San Francisco, New York oder Boston.“

Um die Abfragen robust zu halten, werden wir das LLM dazu bringen, Suchvorlagen anstelle vollständiger DSL-Abfragen zu erstellen. Auf diese Weise erhalten Sie immer die gewünschte Abfrage, und der LLM muss lediglich die Lücken ausfüllen und trägt nicht die Verantwortung, die benötigte Abfrage jedes Mal neu zu erstellen.

Was Sie brauchen, um loszulegen

• Elasticsearch API-Schlüssel
• OpenAPI-API-Schlüssel
• Node 18 oder neuer

Schritt-für-Schritt-Anweisungen

In diesem Abschnitt schauen wir uns an, wie die App aussehen wird. Dafür verwenden wir TypeScript, ein Superset von JavaScript, das statische Typen hinzufügt, um den Code zuverlässiger, leichter zu pflegen und sicherer zu machen, indem Fehler frühzeitig erkannt werden, während er vollständig kompatibel mit bestehendem JavaScript bleibt.

Der Knotenfluss sieht wie folgt aus:

Das obige Bild wird von LangGraph generiert und stellt den Workflow dar, der die Ausführungsreihenfolge und die bedingte Logik zwischen den Knoten definiert:

• decideStrategy: Verwendet ein LLM, um die Anfrage des Nutzers zu analysieren und zwischen zwei spezialisierten Suchstrategien zu entscheiden – investitionsorientiert oder marktorientiert.
• prepareInvestmentSearch: Extrahiert Filterwerte aus der Abfrage und erstellt eine vordefinierte Vorlage, die finanzielle und finanzierungsbezogene Parameter hervorhebt.
• prepareMarketSearch: Extrahiert ebenfalls Filterwerte, baut jedoch dynamisch Parameter auf, die den Markt-, Branchen- und geografischen Kontext betonen.
• executeSearch: Sendet die konstruierte Abfrage mit einer Suchvorlage an Elasticsearch und ruft die entsprechenden Start-up-Dokumente ab.
• VisualizeResults: Formatiert die Endergebnisse in einer klaren, lesbaren Zusammenfassung, die die wichtigsten Startup-Attribute wie Finanzierung, Branche und Umsatz aufzeigt.

Dieser Fluss umfasst eine bedingte Verzweigung, die als „if“-Anweisung fungiert und basierend auf der Eingabe des Nutzers bestimmt, ob der Investitions- oder Marktsuchpfad verwendet wird. Diese vom LLM gesteuerte Entscheidungslogik macht den Workflow adaptiv und kontextsensitiv – ein Mechanismus, den wir in den nächsten Abschnitten genauer untersuchen werden.

LangGraph-Status

Bevor wir jeden Knoten einzeln betrachten, müssen wir verstehen, wie die Knoten kommunizieren und Daten austauschen. Dafür ermöglicht uns LangGraph, den Workflow-Status zu definieren. Dies definiert den gemeinsamen Status, der zwischen Knoten weitergegeben wird.

Der Zustand fungiert als gemeinsamer Container, der während des gesamten Workflows Zwischendaten speichert: Er beginnt mit der natürlichsprachlichen Anfrage des Nutzers, speichert dann die ausgewählte Suchstrategie, die vorbereiteten Parameter für Elasticsearch, die abgerufenen Suchergebnisse und schließlich den formatierten Ausgang.

Diese Struktur ermöglicht es jedem Knoten, den Status zu lesen und zu aktualisieren, wodurch ein konsistenter Informationsfluss vom Nutzer-Eingang bis zur endgültigen Visualisierung gewährleistet wird.

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
});

Einrichten der Anwendung

Der gesamte Code in diesem Abschnitt ist im elasticsearch-labs-Repository zu finden.

Öffnen Sie ein Terminal in dem Ordner, in dem sich die App befindet, und initialisieren Sie eine Node.js-Anwendung mit folgendem Befehl:

npm init -y

Nun können wir die notwendigen Abhängigkeiten für dieses Projekt installieren:

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

• @elastic/elasticsearch: Hilft uns bei der Bearbeitung von Elasticsearch-Anfragen, z. B. bei der Daten-Ingestion und dem Abrufen von Daten.
• @langchain/langgraph: JS-Abhängigkeit zur Bereitstellung aller LangGraph-Tools.
• @langchain/openai: LLM-Client von OpenAI für LangChain.
• @langchain/core: Bietet die grundlegenden Bausteine für LangChain-Apps, einschließlich Prompt-Vorlagen.
• dotenv: Notwendige Abhängigkeit zur Verwendung von Umgebungsvariablen in JavaScript.
• zod: Abhängigkeit von Typdaten.

@types/node tsx typescript ermöglicht es uns, TypeScript-Code zu schreiben und auszuführen.

Erstellen Sie nun die folgenden Dateien:

• elasticsearchSetup.ts: Erstellt die Index-Mappings, lädt die Daten aus einer JSON-Datei und führt den Ingest der Daten in Elasticsearch durch.
• main.ts: Wird die LangGraph-Anwendung enthalten.
• .envDatei zum Speichern der Umgebungsvariablen

In der .env-Datei fügen wir die folgenden Umgebungsvariablen hinzu:

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

Der OpenAPI-APIKey wird nicht direkt im Code verwendet; stattdessen wird er intern von der Bibliothek @langchain/openai verwendet.

Die gesamte Logik bezüglich der Erstellung von Mappings, der Erstellung von Suchvorlagen und der Datensatz-Ingestion kann in der Datei elasticsearchSetup.ts gefunden werden. In den nächsten Schritten konzentrieren wir uns auf die main.ts-Datei. Sie können den Datensatz auch überprüfen, um besser zu verstehen, wie die Daten in dataset.json aussehen.

LangGraph-App

In der main.ts-Datei importieren wir einige notwendige Abhängigkeiten, um die LangGraph-Anwendung zu konsolidieren. In dieser Datei müssen Sie auch die Knotenfunktionen und die Zustandsdeklaration angeben. Die Graphdeklaration erfolgt in den nächsten Schritten anhand einermain-Methode. Die elasticsearchSetup.ts-Datei wird Elasticsearch-Helfer enthalten, die wir in den nächsten Schritten in den Knoten verwenden werden.

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" });

Wie bereits erwähnt, wird der LLM-Client verwendet, um die Elasticsearch-Suchvorlagenparameter basierend auf der Frage des Nutzers zu generieren.

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);
  }
}

Die oben dargelegte Methode erzeugt das Graphbild im PNG-Format und verwendet hinter den Kulissen die Mermaid.INK-API. Dies ist nützlich, wenn Sie sehen möchten, wie die App-Knoten mit einer gestylten Visualisierung zusammenwirken.

LangGraph-Knoten

Sehen wir uns nun die einzelnen Knoten im Detail an:

decideSearchStrategy-Knoten

Der decideSearchStrategy-Knoten analysiert die Eingabe und entscheidet, ob eine investitions- oder marktorientierte Suche durchgeführt werden soll. Er verwendet ein LLM mit einem strukturierten Ausgang (definiert mit Zod), um den Abfragetyp zu klassifizieren. Bevor die Entscheidung getroffen wird, werden mithilfe einer Aggregation die verfügbaren Filter aus dem Index abgerufen, um sicherzustellen, dass das Modell über einen aktuellen Kontext zu Branchen, Standorten und Finanzierungsdaten verfügt.

Um die möglichen Filterwerte zu extrahieren und an das LLM zu senden, verwenden wir eine Aggregation, um sie direkt aus dem Elasticsearch-Index abzurufen. Diese Logik wird in einer Methode namens getAvailableFilterszugeordnet:

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 {};
  }
}

Mit der obigen Aggregationsanfrage erhalten wir die folgenden Ergebnisse:

{
  "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
  }
}

Alle Ergebnisse finden Sie hier.

Für beide Strategien verwenden wir eine hybride Suche, um sowohl den strukturierten Teil der Frage (Filter) als auch die subjektiveren Teile (Semantik) zu erkennen. Hier ist ein Beispiel für beide Abfragen unter Verwendung von Suchvorlagen:

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
            }
          }
        }`,
      },
    });

Sehen Sie sich die Abfragen an, die in derelasticsearchSetup.ts-Datei detailliert beschrieben sind. Im folgenden Knoten wird entschieden, welche der beiden Abfragen verwendet wird:

// 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",
    };
  }
}

prepareInvestmentSearch- und prepareMarketSearch-Knoten

Beide Knoten verwenden eine gemeinsame Hilfsfunktion, extractFilterValues, die das LLM nutzt, um relevante Filter zu identifizieren, die in den Nutzereingaben erwähnt werden, wie z. B. Branche, Standort, Finanzierungsphase, Geschäftsmodell usw. Wir verwenden dieses Schema, um unsere Suchvorlage zu erstellen.

// 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);
}

Je nach erkannter Absicht wählt der Workflow einen von zwei Pfaden:

prepareInvestmentSearch: Erstellt finanzorientierte Suchparameter, einschließlich Finanzierungsphase, Finanzierungsbetrag, Investor und Erneuerungsinformationen. Die gesamte Abfragevorlage finden Sie in der elasticsearchSetup.ts-Datei:

// 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: erstellt marktorientierte Parameter, die sich auf Branchen, Geografien und Geschäftsmodelle konzentrieren. Die vollständige Abfrage finden Sie in der Datei 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 {};
  }
}

executeSearch-Knoten

Dieser Knoten nimmt die gesuchten Parameter aus dem Zustand und sendet sie zuerst an Elasticsearch, wobei er die _render-API verwendet, um die Abfrage für Debugging-Zwecke zu visualisieren, und sendet dann eine Anfrage zur Abrufung der Ergebnisse.

// 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: [] };
  }
}

visualizeResults-Knoten

Dieser Knoten zeigt schließlich die Elasticsearch-Ergebnisse an.

// 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,
  };
}

Programmatisch sieht der gesamte Graph so aus:

  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

Wie Sie sehen können, haben wir eine bedingte Kante, bei der die App entscheidet, welcher „Pfad“ oder Knoten als Nächstes ausführen wird. Dieses Feature ist nützlich, wenn Workflows Verzweigungslogik benötigen, etwa die Wahl zwischen mehreren Tools oder das Einfügen eines Human-in-the-Loop-Schrittes.

Nachdem wir die Kern-Features von LangGraph verstanden haben, können wir die Anwendung einrichten, in der der Code ausgeführt werden soll:

Alles wird in einer main-Methode zusammengefasst. Hier deklarieren wir den Graphen mit allen Elementen unter der Variablen „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);
}

Die Abfragevariable simuliert die in einer hypothetischen Suchleiste eingegebenen Nutzereingaben:

Aus der natürlichsprachlichen Formulierung „Suche Start-ups mit Series-A- oder Series-B-Finanzierung zwischen 8 und 25 Millionen US-Dollar und einem monatlichen Umsatz von über 500.000 US-Dollar“ werden alle Filter extrahiert.

Rufen Sie abschließend die Hauptmethode auf:

main().catch(console.error);

Ergebnisse

🔍 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.

Für die gesendete Eingabe wählt die Anwendung den investitionsorientierten Pfad, wodurch wir die Elasticsearch-Abfrage sehen, die vom Workflow generiert wird und die Werte und Bereiche aus dem Eingang des Nutzers extrahiert. Wir können auch die an Elasticsearch gesendete Anfrage mit den extrahierten Werten sehen, und schließlich die vom visualizeResults-Knoten formatierten Ergebnisse.

Testen wir nun den marktorientierten Knoten mit der Abfrage „Suche Fintech- und Healthcare-Start-ups in San Francisco, New York oder 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.

Erkenntnisse

Während des Schreibprozesses habe ich Folgendes gelernt:

• Wir müssen dem LLM die exakten Werte der Filter zeigen, sonst sind wir darauf angewiesen, dass der Nutzer die präzisen Werte eingibt. Bei niedriger Kardinalität ist dieser Ansatz akzeptabel, aber wenn die Kardinalität hoch ist, benötigen wir einen Mechanismus zum Herausfiltern der Ergebnisse.
• Die Verwendung von Suchvorlagen führt zu deutlich konsistenteren Ergebnissen als die automatische Generierung der Elasticsearch-Abfrage durch das LLM und ist zudem schneller.
• Bedingte Kanten sind ein leistungsstarker Mechanismus, um Anwendungen mit mehreren Varianten und verzweigten Pfaden zu erstellen.
• Strukturierte Ausgaben sind bei der Informationsgenerierung mit LLMs äußerst nützlich, da sie vorhersehbare, typsichere Antworten erzwingen. Dies verbessert die Zuverlässigkeit und reduziert Fehlinterpretationen von Prompts.

Die Kombination von semantischem und strukturiertem Suchen durch hybriden Abruf führt zu besseren und relevanteren Ergebnissen, wobei Präzision und Kontextverständnis in Einklang gebracht werden.

Fazit

In diesem Beispiel kombinieren wir LangGraph.js mit Elasticsearch, um einen dynamischen Workflow zu schaffen, der natürliche Sprachanfragen interpretieren und zwischen finanz- oder marktorientierten Suchstrategien entscheiden kann. Dieser Ansatz reduziert die Komplexität manueller Abfragen und verbessert gleichzeitig die Flexibilität und Genauigkeit für Risikokapitalanalysten.

Was sind Steuerelemente für Variablen?

Wenn Sie bereits mit Kibana-Dashboards gearbeitet haben, kennen Sie wahrscheinlich unsere klassischen Dashboard-Steuerelemente – diese praktischen Dropdown-Menüs, die Werte aus Ihren Daten anzeigen, sodass Sie mit wenigen Klicks Filter setzen können.

Variable Bedienelemente sehen auf der Oberfläche ähnlich aus, haben aber eine clevere Wendung: Anstatt automatisch jedes Panel auf deinem Dashboard zu filtern, können sie direkt an ES|QL-Abfragen innerhalb einzelner Visualisierungen angeschlossen werden.

Das bedeutet, Sie können entscheiden, wo jedes Steuerelement angewendet wird. Noch besser: Sie können sie für alle möglichen kreativen Tricks verwenden – beispielsweise zum Anpassen von Zeitintervallen, zum Wechseln von Aufschlüsselungsfeldern oder zum spontanen Ändern von Visualisierungsparametern. Im Grunde genommen sorgen sie für ein wahrhaft interaktives Erlebnis auf Ihren Dashboards, sodass Sie schneller und einfacher zu Ihren Erkenntnissen gelangen.

Anwendungsfälle für Steuerelemente für Variablen

Steuerelemente für Variablen sind zwar nützlich, aber was kann man damit eigentlich machen? Hier sind einige Beispiele dafür, wie sie Ihre Dashboards verbessern:

Ausgewählte Visualisierungen filtern

Möchten Sie einige Visualisierungen filtern, aber andere unberührt lassen? Steuerelemente für Variablen ermöglichen Ihnen genau das. Wählen Sie die Panels aus, auf die Sie reagieren möchten, und verknüpfen Sie sie in den ES|QL-Abfragen hinter Ihren Visualisierungen.

Wählen Sie unterschiedliche Zeitintervalle aus

Geben Sie Ihren Nutzern die Möglichkeit, zwischen „5 Minuten“, „1 Stunde“, „1 Tag“ oder anderen sinnvollen Buckets zu wechseln. Erstellen Sie ein Steuerelement für Variablen mit vordefinierten Intervallen und verbinden Sie diese mit Ihrer Zeitreihenabfrage.

Funktionen ändern

Anstatt mehrere Diagramme für jeden Vorgang zu erstellen, können die Nutzer des Dashboards wählen, ob sie den Maximalwert, den Durchschnittswert, verschiedene Perzentile oder einen anderen Aggregator sehen möchten.

Nach verschiedenen Feldern gruppieren

Mitunter müssen Sie die Daten während einer Untersuchung nach verschiedenen Dimensionen aufschlüsseln. Mit Steuerelementen für Variablen können Sie mehrere „Gruppieren nach“-Felder festlegen und Dashboard-Nutzer so das Feld auswählen lassen, das sie bei der Gewinnung ihrer Erkenntnisse unterstützt.

Wie kann man sie erstellen?

Die einfachste (und wahrscheinlich angenehmste) Methode zur Erstellung eines Steuerelements für Variablen ist direkt über den ES|QL-Abfrage-Editor in Ihrer Visualisierung. Beginnen Sie einfach mit der Eingabe Ihrer Suchanfrage, nutzen Sie das Autovervollständigungsmenü und Kibana unterstützt Sie bei der Erstellung Ihres Steuerelements.

Wenn Sie jedoch lieber mit der Variablen selbst beginnen möchten, können Sie auch zu Panel hinzufügen → Steuerelemente → Steuerelement für Variablen gehen und die Variable nach dem Erstellen des Steuerelements zu Ihren Visualisierungen hinzufügen.

Beispiel 1: Filter-Steuerelement mit Auswahl mehrerer Werte

1. Wählen Sie eine Visualisierung aus, die auf einer ES|QL-Abfrage basiert, und klicken Sie innerhalb der WHERE-Klausel auf „Steuerelement erstellen“

2. Sie werden automatisch zum Flyout für die Erstellung von Variablen weitergeleitet, wo der Typ „Werte aus einer Abfrage“ für Sie ausgewählt ist und der Name der Variablen bereits vorausgefüllt ist. Beachten Sie, dass der Name eines Steuerelements immer mit „?...” beginnen muss, damit er in der Visualisierungsabfrage funktioniert.

In der Regel benötigen Sie eine Abfrage wie diese, um die Werte eines Feldes abzurufen und sie entsprechend dem im Dashboard ausgewählten Zeitraum zu aktualisieren:

FROM 
| WHERE @timestamp <=?_tend and @timestamp >?_tstart
| STATS BY 

3. Beim Speichern des Steuerelements erscheint sie oben im Dashboard, und Ihre Visualisierungsabfrage wird mit dem Namen des Steuerelements für Variablen aktualisiert.

4. Wenn Sie Mehrfachauswahl zum Steuerelement hinzufügen möchten, verwenden Sie die Funktion MV_CONTAINS in der Abfrage und wählen Sie bei der Erstellung des Steuerelements in Schritt 2 (verfügbar ab 9.3) die Option „Mehrfachauswahl zulassen“ aus.

Beispiel 2: Zeitintervallsteuerung

Bei der Erstellung einer Zeitreihe können Sie ganz einfach ein Steuerelement für Variablen für Ihr Datums-Histogramm-Intervall hinzufügen:

1. Klicken Sie beim Schreiben einer ES|QL-Abfrage für Ihre Zeitreihe auf „Steuerelement erstellen“. Bei der Erstellung einer Variablen für Intervalle ist es besser, TBUCKET anstelle von BUCKET zu verwenden, damit besser lesbare Intervalle wie „1 Stunde“, „1 Tag“ usw. akzeptiert werden. In Kürze steht auch eine automatische Option für TBUCKET zur Verfügung, sodass sich das System automatisch an Zeitbereiche anpassen kann.

2. Legen Sie die Intervalle zum Ausfüllen der Optionen im Dropdown-Menü fest.

3. Wählen Sie im Dropdown-Menü verschiedene Intervalle aus und sehen Sie, wie sich Ihre Visualisierung verändert.

Beispiel 3: Variablen für Funktionen

1. Erstellen Sie eine Variable mithilfe des Kontrolltyps „Statische Werte“ und fügen Sie Funktionsnamen zu Ihren Dropdown-Werten hinzu. Es ist wichtig, für Ihre Variable einen Namen zu verwenden, der mit „??…“ beginnt, um Funktionen zu ersetzen.

2. Fügen Sie den Variablennamen in Ihre ES|QL-Abfrage ein.

Beispiel 4: Variablen für Felder

1. Sie können den Kontrolltyp „Statische Werte“ verwenden und die Namen der gewünschten Felder eingeben. Es ist wichtig, einen Variablennamen zu verwenden, der mit „??...“ beginnt, damit er für Felder funktioniert.

2. Verweisen Sie in der Visualisierungsabfrage auf die gewünschte Variable.

Steuerelemente für Variablen in Discover

Steuerelemente für Variablen sind nicht nur eine Dashboard-Funktion, sondern auch direkt im ES|QL-Editor in Discover verfügbar. Sie können Steuerelemente für eine schnellere Datenexploration in Discover erstellen, diese in das Dashboard übertragen und umgekehrt.

Technische Details

Mittlerweile haben Sie wahrscheinlich bemerkt, dass Steuerelemente für Variablen einigen Regeln unterliegen – beispielsweise, auf welche Teile einer Abfrage sie verweisen können und welche Namenspräfixe Sie verwenden müssen („?...” für Werte und „??...” für Felder oder Funktionen). Das liegt daran, dass Variablen nicht nur einfache Zeichenfolgenersetzungen sind, die auf dem Client stattfinden. Es handelt sich dabei um erstklassige Elemente der Abfragesprache selbst (bekannt als Parameter in ES|QL).

Dieses Design bietet einige große Vorteile. Zum einen kann Kibana den Kontext jeder Variablen verstehen, wodurch wir die Konfiguration automatisch für Sie generieren und vorausfüllen können. Außerdem ist es viel sicherer: Da die Sprache Variableneingaben streng validiert, verhindert sie böswillige Injektionen und gibt bei Unstimmigkeiten eine Fehlermeldung aus. Darüber hinaus werden Leistung und Stabilität verbessert, indem komplexe Validierungen und Fehlerbehandlungen vom Client auf den Server verlagert werden. Ein Hinweis zur Leistung: Eine bewährte Vorgehensweise besteht in der Erstellung von Variablen, die schnelle Abfragen enthalten, da diese vor dem Dashboard geladen werden. Langsame Abfragen können sich daher auf die gesamte Dashboard-Leistung auswirken.

Natürlich bringt diese Architektur vorerst auch einige Einschränkungen mit sich. Variablen unterstützen noch keine „Alle“-Option für das Filtern und können derzeit nicht mit bestimmten Operatoren wie LIKE oder FROM (zum Wechseln der Datenquellen) verwendet werden. Die gute Nachricht? Wir arbeiten aktiv an der Erweiterung um diese Funktionen.

Was die Zukunft für Bedienelemente bereithält

Wir machen hier noch lange nicht Schluss! Zu den geplanten Verbesserungen gehören unter anderem:

✨ Die Möglichkeit zur beliebigen Platzierung von Steuerelementen auf dem Dashboard

✨ Verkettung Ihrer Steuerelemente – das bedeutet, der Ausgang eines Steuerelements wird zum Eingang für das nächste Steuerelement

✨ Verbesserte Auswahlmöglichkeiten wie die Option „Alle“ für Variablen

✨ Neue Kontrolltypen (Suchtyp-Steuerelement und Variablen für Ihre Datenquellen)

✨ Und weitere Verbesserungen der von Ihnen Benutzerfreundlichkeit, wie beispielsweise die Vorfilterung normaler Steuerelemente

Wir freuen uns über Ihre Ideen und Ihr Feedback.

Zusammenfassung

Zunächst einmal ein kurzer Überblick. Elasticsearch hat sich als leistungsstarke Vektordatenbank etabliert und bietet eine Vielzahl von Funktionen sowie eine hohe Leistungsfähigkeit für die Ähnlichkeitssuche im großen Maßstab. Mit Funktionen wie Skalarquantisierung, Better Binary Quantization (BBQ), SIMD- Vektoroperationen und speichereffizienteren Algorithmen wie DiskBBQ bietet es bereits effiziente und flexible Optionen für die Verwaltung von Vektor-Workloads.

Durch die Integration von NVIDIA cuVS als aufrufbares Modul für Vektorsuchaufgaben wollen wir signifikante Verbesserungen bei der Vektorindizierungsleistung und -effizienz erzielen, um große Vektor-Workloads besser zu unterstützen.

Die Herausforderung

Eine der größten Herausforderungen beim Aufbau einer leistungsstarken Vektordatenbank ist die Konstruktion des Vektorindexes – des HNSW-Graphen. Die Indexbildung wird schnell von Millionen oder sogar Milliarden arithmetischer Operationen dominiert, da jeder Vektor mit vielen anderen verglichen wird. Darüber hinaus können Index-Lebenszyklusoperationen wie Komprimierung und Zusammenführungen den gesamten Rechenaufwand für die Indizierung weiter erhöhen. Da Datenmengen und die damit verbundenen Vektoreinbettungen exponentiell wachsen, sind beschleunigte Rechen-GPUs, die für massive Parallelität und mathematische Berechnungen mit hohem Durchsatz ausgelegt sind, ideal für die Bewältigung dieser Arbeitslasten geeignet.

Öffnen Sie das Elasticsearch-GPU-Plugin.

NVIDIA cuVS ist eine Open-Source-CUDA-X-Bibliothek für GPU-beschleunigte Vektorsuche und Datenclustering, die schnelles Indexieren und Einbetten für KI- und Empfehlungs-Workloads ermöglicht.

Elasticsearch nutzt cuVS über cuvs-java, eine Open-Source-Bibliothek, die von der Community entwickelt und von NVIDIA gepflegt wird. Die cuvs-java Bibliothek ist leichtgewichtig und baut auf der cuVS C API auf, indem sie Panama Foreign Function verwendet, um cuVS-Funktionen auf idiomatische Java-Art bereitzustellen und dabei modern und leistungsstark zu bleiben.

Die cuvs-java-Bibliothek ist in ein neues Elasticsearch-Plugin integriert; daher kann die Vektorindizierung auf der GPU auf demselben Elasticsearch-Knoten und -Prozess erfolgen, ohne dass externer Code oder Hardware bereitgestellt werden muss. Während des Indexaufbaus nutzt Elasticsearch die GPU, um den Vektorindexierungsprozess zu beschleunigen, sofern die cuVS-Bibliothek installiert und eine GPU vorhanden und konfiguriert ist. Die Vektoren werden der GPU übergeben, die daraus einen CAGRA-Graphen erstellt. Dieser Graph wird dann in das HNSW-Format umgewandelt, wodurch er sofort für die Vektorsuche auf der CPU verfügbar ist. Das endgültige Format des erstellten Graphen ist identisch mit dem, das auf der CPU erstellt würde; dadurch kann Elasticsearch GPUs für die Vektorindizierung mit hohem Durchsatz nutzen, wenn die zugrunde liegende Hardware dies unterstützt, während gleichzeitig CPU-Leistung für andere Aufgaben (gleichzeitige Suche, Datenverarbeitung usw.) frei bleibt.

Beschleunigung des Indexaufbaus

Im Rahmen der Integration der GPU-Beschleunigung in Elasticsearch wurden mehrere Verbesserungen an cuvs-java vorgenommen, die sich auf einen effizienten Dateneingang/-ausgang und Funktionsaufruf konzentrieren. Eine wichtige Verbesserung ist die Verwendung von cuVSMatrix zur transparenten Modellierung von Vektoren, unabhängig davon, ob sie sich auf dem Java-Heap, außerhalb des Heaps oder im GPU-Speicher befinden. Dadurch können Daten effizient zwischen Arbeitsspeicher und GPU übertragen werden, wodurch unnötige Kopien von potenziell Milliarden von Vektoren vermieden werden.

Dank dieser zugrundeliegenden Zero-Copy-Abstraktion können sowohl die Übertragung in den GPU-Speicher als auch der Abruf des Graphen direkt erfolgen. Beim Indizieren werden die Vektoren zunächst im Speicher auf dem Java-Heap zwischengespeichert und dann an die GPU gesendet, um den CAGRA-Graphen zu erstellen. Der Graph wird anschließend von der GPU abgerufen, in das HNSW-Format konvertiert und auf der Festplatte gespeichert.

Beim Zusammenführen sind die Vektoren bereits auf der Festplatte gespeichert, wodurch der Java-Heap vollständig umgangen wird. Indexdateien sind speicherabgebildet und die Daten werden direkt in den GPU-Speicher übertragen. Das Design unterstützt zudem problemlos unterschiedliche Bitbreiten, z. B. float32 oder int8, und lässt sich natürlich auf andere Quantisierungsschemata erweitern.

Trommelwirbel ... wie gut funktioniert es?

Bevor wir zu den Zahlen kommen, ist ein bisschen Kontext hilfreich. Die Segmentzusammenführung in Elasticsearch läuft in der Regel automatisch im Hintergrund während der Indizierung, was ein isoliertes Benchmarking schwierig macht. Um reproduzierbare Ergebnisse zu erzielen, haben wir in einem kontrollierten Experiment die Segmentzusammenführung explizit mit der Funktion Force-Merge ausgelöst. Da Force-Merge die gleichen zugrunde liegenden Zusammenführungsoperationen wie das Zusammenführen im Hintergrund durchführt, dient seine Leistung als nützlicher Indikator für erwartete Verbesserungen, auch wenn die genauen Gewinne in realen Indexierungs-Workloads abweichen können.

Schauen wir uns nun die Zahlen an.

Unsere ersten Benchmark-Ergebnisse sind sehr vielversprechend. Wir haben den Benchmark auf einer AWS g6.4xlarge Instanz mit lokal angeschlossenem NVMe-Speicher ausgeführt. Ein einzelner Knoten von Elasticsearch wurde so konfiguriert, dass er die standardmäßige, optimale Anzahl von Indizierungs-Threads (8 – einer für jeden physischen Kern) verwendet und Merge Throttling deaktiviert (was bei schnellen NVMe-Festplatten weniger relevant ist).

Für den Datensatz verwendeten wir 2,6 Millionen Vektoren mit 1.536 Dimensionen aus der OpenAI Rally-Vektorstrecke, kodiert als Base64-Zeichenfolgen und indexiert als float32 hnsw. In allen Szenarien erreichen die konstruierten Graphen Recall-Werte von bis zu 95 %. Hier sind unsere Ergebnisse:

• Indizierungsdurchsatz: Durch die Verlagerung der Graphenkonstruktion auf die GPU während des Speicherpuffer-Flushs steigern wir den Durchsatz um das 12-fache.
• Force-Merge: Nach Abschluss der Indizierung beschleunigt die GPU weiterhin die Segmentzusammenführung und beschleunigt die Force-Merge-Phase um das ~7-fache.

• CPU-Auslastung: Durch die Auslagerung der Graph-Konstruktion auf die GPU werden sowohl die durchschnittliche als auch die maximale CPU-Auslastung deutlich reduziert. Die folgenden Graphen veranschaulichen die CPU-Auslastung während der Indizierung und Zusammenführung und zeigen, wie viel geringer sie ist, wenn diese Vorgänge auf der GPU ausgeführt werden. Eine geringere CPU-Auslastung während der GPU-Indexierung setzt CPU-Zyklen frei, die zur Verbesserung der Suchleistung umgeleitet werden können.

• Recall: Die Genauigkeit bleibt zwischen CPU- und GPU-Läufen praktisch gleich, wobei der mit der GPU erstellte Graph einen geringfügig höheren Recall erreicht.

Vergleich anhand einer weiteren Dimension: Preis

Beim vorherigen Vergleich wurde absichtlich identische Hardware verwendet; der einzige Unterschied bestand darin, ob die GPU während der Indizierung verwendet wurde. Diese Konfiguration ist nützlich, um die Auswirkungen der reinen Rechenleistung zu isolieren, aber wir können den Vergleich auch aus einer Kostenperspektive betrachten.

Bei etwa demselben Stundenpreis wie die GPU-beschleunigte Konfiguration kann man ein CPU-reines Setup mit etwa doppelt so vielen vergleichbaren CPU- und Speicherressourcen bereitstellen: 32 vCPUs (AMD EPYC) und 64 GB RAM, wodurch die Anzahl der Indexierungs-Threads auf 16 verdoppelt werden kann.

Um den Vergleich fair und konsistent zu halten, haben wir dieses reine CPU Experiment auf einer AWS g6.8xlarge Instanz ausgeführt, wobei die GPU explizit deaktiviert war. Dadurch konnten wir alle anderen Hardwareeigenschaften konstant halten und gleichzeitig den Kosten-Leistungs-Kompromiss zwischen GPU-Beschleunigung und reiner CPU-Indexierung evaluieren.

Die leistungsstärkere CPU-Instanz zeigt erwartungsgemäß eine verbesserte Performance im Vergleich zu den Benchmarks im obigen Abschnitt. Wenn wir jedoch diese leistungsstärkere CPU-Instanz mit den ursprünglichen GPU-beschleunigten Ergebnissen vergleichen, liefert die GPU immer noch erhebliche Leistungssteigerungen: ~5-fache Verbesserung des Indizierungsdurchsatzes und ~6-fache Verbesserung beim Force Merge, während gleichzeitig Graphen erstellt werden, die Recall-Werte von bis zu 95 % erreichen.

Fazit

In End-to-End-Szenarien bietet die GPU-Beschleunigung mit NVIDIA cuVS eine nahezu 12-fache Verbesserung des Indexierungsdurchsatzes und eine 7-fache Verringerung der Force-Merge-Latenz bei deutlich geringerer CPU-Auslastung. Dies zeigt, dass Vektorindizierungs- und Merge-Workloads erheblich von der GPU-Beschleunigung profitieren. Im Kostenvergleich bietet die GPU-Beschleunigung weiterhin deutliche Leistungssteigerungen, mit einem etwa 5-fach höheren Indexierungsdurchsatz und 6-fach schnelleren Force-Merge-Operationen.

Die GPU-beschleunigte Vektorindizierung ist derzeit für die Tech Preview in Elasticsearch 9.3 geplant, deren Veröffentlichung für Anfang 2026 vorgesehen ist.

Mehr dazu in Kürze.

Hier ist ein Überblick über die Features in Elasticsearch 9.2, die Ihre Datenanalyse-Workflows mit ES|QL verändern werden.

Revolutionierung der Datenkorrelation: Eine intelligentere, schnellere und flexiblere Lookup-Verknüpfung

Der Befehl LOOKUP JOIN in ES|QL hat in Elasticsearch 9.2 eine bedeutende Transformation durchlaufen und ist deutlich effizienter und vielseitiger geworden. LOOKUP JOIN kombiniert Daten aus Ihrer ES|QL-Abfrageergebnistabelle mit übereinstimmenden Einträgen aus einem angegebenen Lookup-Modus-Index. Es fügt Felder aus dem Lookup-Index als neue Spalten zu Ihrer Ergebnistabelle hinzu, basierend auf übereinstimmenden Werten im Join-Feld. Zuvor war die Verknüpfung von Daten auf ein einziges Feld und einfache Gleichheit beschränkt. Das ist Geschichte! Dank dieser Erweiterungen können Sie komplexe Datenkorrelationsszenarien mühelos bewältigen.

Zu den wichtigsten Verbesserungen von Lookup Join gehören:

• Verknüpfungen mit mehreren Feldern: Einfaches Verknüpfen mehrerer Felder. So verbinden Sie beispielsweise application_logs mit service_registry anhand von service_name, environment und version:

FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment, version

• Freischalten komplexer Join-Prädikate mit Ausdrücken (technische Vorschau):

Sie sind nicht mehr auf einfache Gleichheit beschränkt. LOOKUP JOIN ermöglicht es Ihnen nun, mehrere Kriterien für die Korrelation anzugeben und eine Reihe von binären Operatoren einzubeziehen, darunter ==, !=, <, >, <= und >=. Dies bedeutet, dass Sie hochgradig nuancierte Join-Bedingungen erstellen können, die es Ihnen ermöglichen, viel anspruchsvollere Fragen an Ihre Daten zu stellen.

Beispiel 1: Ermittlung von Anwendungsmetriken mit SLA-Schwellenwert pro Dienst

FROM application_metrics
| LOOKUP JOIN sla_thresholds
      ON service_name == sla_service AND response_time > sla_response_time

Beispiel 2: Diese Abfrage berechnet den fälligen Betrag auf Grundlage regionaler Preisrichtlinien, die sich im Laufe der Zeit ändern. Es verknüpft drei Datensätze basierend auf komplexen Datumsbereichs- und Gleichheitsbedingungen, um eine endgültige due_amount zu berechnen. Der zweite Lookup-Join verwendet das Feld measurement_date aus dem Index meter_readings und das Feld region_id aus dem Index customers, um mit dem Index pricing_policies verknüpft zu werden und die richtige Preispolitik für die jeweiligen region und measurement_date zu finden.

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

• Enorme Leistungsgewinne bei gefilterten Joins:

Wir haben die Leistung für „erweiterte Verknüpfungen” verbessert, die anhand von Lookup-Tabellenbedingungen gefiltert werden. Erweiterte Verknüpfungen führen zu mehreren Übereinstimmungen pro Eingabezeile, wodurch große Zwischenergebnismengen entstehen können. Dies wird noch schlimmer, wenn viele dieser Zeilen durch einen nachfolgenden Filter verworfen werden. In 9.2 optimieren wir diese Verknüpfungen, indem wir unnötige Zeilen herausfiltern, wenn ein Filter auf Suchdaten angewendet wird. Dadurch wird die Verarbeitung von Zeilen vermieden, die verworfen würden. In einigen Szenarien können diese Joins bis zu 1000-mal schneller sein!

Diese Optimierung ist entscheidend bei der Verarbeitung von „expandierenden Joins“, bei denen eine Suche anfänglich viele potenzielle Übereinstimmungen erzeugen kann. Durch intelligentes Herunterdrücken von Filtern werden nur die relevanten Daten verarbeitet, was die Ausführungszeit von Abfragen drastisch verkürzt und die Echtzeitanalyse großer Datensätze ermöglicht. Das bedeutet, dass Sie Ihre Einblicke viel schneller erhalten, selbst bei sehr großen oder komplexen Join-Operationen.

Kompatibilität mit der clusterübergreifenden Suche (CCS) Lookup Join:

Als Lookup Join in den Versionen 8.19 und 9.1 allgemein verfügbar wurde, fehlte die Unterstützung für die clusterübergreifende Suche (CCS). Für Organisationen, die in mehreren Clustern arbeiten, lässt sich LOOKUP JOIN in 9.2 jetzt nahtlos in CCS integrieren. Platzieren Sie einfach Ihren Lookup-Index auf allen Remote-Clustern, mit denen Sie einen Join durchführen möchten, und ES|QL nutzt diese Remote-Lookup-Indizes automatisch, um den Join mit Ihren Remote-Daten durchzuführen. Dies vereinfacht die verteilte Datenanalyse und gewährleistet eine konsistente Anreicherung Ihres gesamten Elasticsearch-Deployments.

Diese Verbesserungen ermöglichen es Ihnen, vielfältige Datensätze mit beispielloser Präzision, Geschwindigkeit und Leichtigkeit zu korrelieren und so tiefere, umsetzbare Einblicke ohne komplexe Workarounds oder Vorverarbeitungsschritte zu gewinnen.

Reichern Sie Ihre Daten mühelos an: Kibana Discover UX für Lookup-Indizes

Die Datenanreicherung sollte unkompliziert sein und keine Hürde darstellen. Wir haben in Kibana Discover eine fantastische neue Nutzererfahrung für die Erstellung und Verwaltung von Lookup-Indizes eingeführt.

Intuitiver Workflow: Die umfassende Autovervollständigung von Discover führt Sie durch den Prozess, schlägt Suchindizes und Join-Felder im ES|QL-Editor vor und macht es unglaublich einfach, Ihre hochgeladenen Daten mit vorhandenen Indizes zu verbinden. Geben Sie den Namen eines Lookup-Index ein, der nicht existiert, und erhalten Sie mit einem Klick direkten Zugriff auf den Lookup-Editor, um den Index zu erstellen. Geben Sie den Namen eines bestehenden Nachschlageindex ein, und wir schlagen eine Option zur Bearbeitung vor:

Inline-Management (CRUD): Halten Sie Ihre Datensätze mit Inline-Bearbeitungsfunktionen (Erstellen, Lesen, Aktualisieren, Löschen) und Liniendiagramm direkt in Discover auf dem neuesten Stand.

Müheloses Hochladen von Dateien: Sie können jetzt Dateien wie CSVs direkt in Discover hochladen und sofort in Ihren LOOKUP JOIN verwenden. Keine Kontextwechsel mehr durch das Springen zwischen verschiedenen Bereichen von Kibana!

Egal, ob Sie Nutzer-IDs mit Namen mappen, Geschäfts-Metadaten hinzufügen oder statische Referenzdateien verknüpfen – dieses Feature demokratisiert die Datenanreicherung und versorgt die Joins direkt in den Händen aller Nutzer:innen mit Energie – schnell, einfach und alles an einem Ort.

Bewahren Sie Ihren Kontext: Einführung von INLINE STATS (technische Vorschau)

Die Aggregation von Daten ist entscheidend, aber manchmal müssen Sie die Aggregate neben Ihren ursprünglichen Daten sehen. Wir freuen uns, INLINE STATS als Tech Preview-Feature vorzustellen.

Im Gegensatz zum Befehl STATS, der Ihre Eingabefelder durch aggregierte Ausgaben ersetzt, behält INLINE STATS alle Ihre ursprünglichen Eingabefelder bei und fügt lediglich die neuen aggregierten Felder hinzu. Dies ermöglicht es Ihnen, nach der Aggregation weitere Operationen auf Ihren ursprünglichen Eingabefeldern durchzuführen und bietet so einen kontinuierlicheren und flexibleren Analyse-Workflow.

Um beispielsweise die durchschnittliche Flugdistanz unter Beibehaltung der einzelnen Flugreihen zu berechnen:

FROM kibana_sample_data_flights
 | KEEP Carrier, Dest, DistanceMiles
 | INLINE STATS avgDist = ROUND(AVG(DistanceMiles))
       BY Dest
 | WHERE DistanceMiles > avgDist

Bei dieser Abfrage wird jeder Zeile avgDist mit der entsprechenden Dest(ination) hinzugefügt, nach der wir gruppiert haben. Da wir dann immer noch die Spalten mit den Fluginformationen haben, können wir die Ergebnisse auf die Flüge mit einer Entfernung, die größer als der Durchschnitt ist, filtern.

Zeitreihenunterstützung in ES|QL (technische Vorschau)

Elasticsearch verwendet Zeitreihen-Datenströme zum Speichern von Metriken. Wir fügen Unterstützung für Zeitreihenaggregationen in ES|QL über den TS Source-Befehl hinzu. Dies ist in Elastic Cloud Serverless und 9.2 Basic als Tech-Vorschau verfügbar.

Die Zeitreihenanalyse basiert größtenteils auf Aggregationsabfragen, die Metrikwerte in Zeit-Buckets zusammenfassen, unterteilt durch eine oder mehrere Filterdimensionen. Die meisten Aggregationsabfragen basieren auf einer zweistufigen Verarbeitung: (a) eine innere Aggregationsfunktion, die Werte pro Zeitreihe zusammenfasst, und (b) eine äußere Aggregationsfunktion, die die Ergebnisse von (a) über Zeitreihen hinweg kombiniert.

Der Quellbefehl TS bietet in Kombination mit STATS eine prägnante und dennoch effektive Möglichkeit, solche Abfragen über Zeitreihen auszudrücken. Betrachten wir konkreter das folgende Beispiel zur Berechnung der Gesamtanforderungsrate pro Host und Stunde:

TS my_metrics
| WHERE @timestamp > NOW() - 1 day
| STATS SUM(RATE(requests))
      BY host, TBUCKET(1h)

In diesem Fall wird die Aggregationsfunktion RATE zuerst pro Zeitreihe und Stunde ausgewertet. Die erzeugten Teilaggregate werden dann mit SUM kombiniert, um die endgültigen Aggregatwerte pro Host und Stunde zu berechnen.

Eine Liste der verfügbaren Funktionen zur Aggregation von Zeitreihen finden Sie hier. Zählerrate wird jetzt unterstützt, die wohl wichtigste Aggregationsfunktion für die Verarbeitung von Zählern.

Der Quellbefehl TS ist so konzipiert, dass er mit STATS kombiniert werden kann, wobei die Ausführung so abgestimmt ist, dass sie Zeitreihenaggregationen effizient unterstützt. Zum Beispiel werden die Daten sortiert, bevor sie in die STATS gelangen. Verarbeitungsbefehle, die die Zeitreihendaten oder ihre Reihenfolge anreichern oder verändern können, wie FORK oder INLINE STATS, sind derzeit zwischen TS und STATS nicht zulässig. Diese Beschränkung könnte in Zukunft aufgehoben werden.

Die tabellarische Ausgabe von STATS kann mit einem beliebigen Befehl weiterverarbeitet werden. Zum Beispiel berechnet die folgende Abfrage das Verhältnis des durchschnittlichen cpu_usage pro Host und Stunde bis zum maximalen Wert pro Host:

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

Zeitreihendaten werden auf unserer zugrunde liegenden spaltenförmigen Speicher-Engine gespeichert, die von Lucene-Doc-Werten betrieben wird. Der TS-Befehl fügt die vektorisierte Abfrageausführung über die ES|QL-Compute-Engine hinzu. Die Abfrageleistung wird im Vergleich zu äquivalenten DSL-Abfragen oft um mehr als eine Größenordnung verbessert und ist mit etablierten, metrikspezifischen Systemen vergleichbar. Wir werden in Zukunft eine detaillierte Architektur- und Leistungsanalyse bereitstellen, also bleiben Sie gespannt.

Erweiterung Ihres Toolkits: Neue ES|QL-Funktionen

Zeichenfolgenmanipulation: CONTAINS, MV_CONTAINS, URL_ENCODE, URL_ENCODE_COMPONENT, URL_DECODE für eine robustere Text- und URL-Verarbeitung.

Zeitreihen und Geodaten: TBUCKET für flexible Buckets, TO_DENSE_VECTOR für Vektoroperationen und ein umfassender Satz von Geodatenfunktionen wie ST_GEOHASH, ST_GEOTILE, ST_GEOHEX, TO_GEOHASH, TO_GEOTILE, TO_GEOHEX für fortgeschrittene ortsbezogene Analysen.

Datumsformatierung: DAY_NAME, MONTH_NAME für besser lesbare Datumsdarstellungen.

Diese Funktionen bieten Ihnen eine umfangreichere Auswahl an Werkzeugen, um Ihre Daten direkt innerhalb von ES|QL zu bearbeiten und zu analysieren.

Unter der Haube: Mehr Leistung und Effizienz

Neben den hervorgehobenen Features bietet Elasticsearch 9.2 zahlreiche Leistungsoptimierungen für ES|QL. Wir haben RLIKE (LIST) mit Pushdown beschleunigt, wenn die Funktion mehrere ähnliche RLIKE-Abfragen in einem Ticket ersetzt. Mit RLIKE (LIST) können wir diese Abfragen zu einem einzigen Automaten zusammenführen und einen Automaten anstelle mehrerer anwenden. Wir bieten außerdem ein schnelleres Laden von Schlüsselwortfeldern durch Indexsortierungen und allgemeine Abfrageoptimierungen – diese Verbesserungen gewährleisten, dass Ihre ES|QL-Abfragen effizienter als je zuvor ausgeführt werden.

Legen Sie noch heute los!

Elasticsearch 9.2 ist ein bedeutender Fortschritt für ES|QL und bringt beispiellose Leistung und Flexibilität in Ihre Datenanalyse-Workflows. Wir ermutigen Sie, diese neuen Features zu erkunden und den Unterschied selbst zu erleben.

Eine vollständige Liste aller Änderungen und Verbesserungen in Elasticsearch 9.2 finden Sie in den offiziellen Versionshinweisen. Viel Spaß beim Abfragen!

Benutzerdefinierte Konnektoren ermöglichen es Ihnen, Ihre vorhandenen ChatGPT-Konnektoren mit zusätzlichen Datenquellen wie Elasticsearch zu kombinieren, um umfassende Antworten zu erhalten.

In diesem Artikel werden wir einen MCP-Server erstellen, der ChatGPT mit einem Elasticsearch-Index verbindet, der Informationen zu internen GitHub Issues und Pull Requests enthält. So können Abfragen in natürlicher Sprache mit Ihren Elasticsearch-Daten beantwortet werden.

Wir werden den MCP-Server mithilfe von FastMCP auf Google Colab mit ngrok bereitstellen, um eine öffentliche URL zu erhalten, mit der ChatGPT eine Verbindung herstellen kann. Dadurch entfällt die Notwendigkeit einer komplexen Infrastruktureinrichtung.

Einen umfassenden Überblick über MCP und sein Ökosystem finden Sie unter „Der aktuelle Stand von MCP“.

Voraussetzungen

Vor Beginn benötigen Sie Folgendes:

• Elasticsearch-Cluster (8.X oder höher)
• Elasticsearch-API-Schlüssel mit Lesezugriff auf Ihren Index
• Google-Konto (für Google Colab)
• Ngrok-Konto (das kostenlose Abo genügt)
• ChatGPT-Konto mit Pro-, Enterprise-, Business- oder Edu-Plan

Die Anforderungen für ChatGPT MCP-Konnektoren verstehen

Für die ChatGPT MCP-Konnektoren müssen zwei Tools implementiert werden: search und fetch. Weitere Einzelheiten finden Sie in den OpenAI Dokumenten.

Suchtool

Gibt eine Liste relevanter Ergebnisse aus Ihrem Elasticsearch-Index auf der Grundlage einer Benutzerabfrage zurück.

Das erhält es:

• Eine einzelne Zeichenfolge mit der Anfrage des Benutzers in natürlicher Sprache.
• Beispiel: „Finde Probleme im Zusammenhang mit der Elasticsearch-Migration.“

Was es zurückgibt: 

• Ein Objekt mit einem result-Schlüssel, der ein Array von result-Objekten enthält. Jedes Ergebnis umfasst:
  • id - Eindeutige Dokumentkennung
  • title - Titel eines Issues oder Pull Requests (PR)
  • url - Link zum Issue/PR

In unserer Implementierung:

return {
    "results": [
        {
            "id": "PR-612",
            "title": "Fix memory leak in WebSocket notification service",
            "url": "https://internal-git.techcorp.com/pulls/612"
        },
        # ... more results
    ]
}

Abrufwerkzeug

Ruft den vollständigen Inhalt eines bestimmten Dokuments ab.

Das erhält es:

• Eine einzelne Zeichenfolge mit der Elasticsearch-Dokument-ID aus dem Suchergebnis
• Beispiel: „Nenne mir die Details zum PR-578.“

Was es zurückgibt:

• Ein vollständiges Dokumentobjekt mit:
  • id - Eindeutige Dokumentkennung
  • title - Titel eines Issues oder Pull Requests (PR)
  • text - Vollständige Beschreibung und Details des Problems/PR
  • url - Link zum Issue/PR
  • type - Dokumenttyp (Issue, Pull-Request)
  • status - Aktueller Status (offen, in Bearbeitung, abgeschlossen)
  • priority - Prioritätsstufe (niedrig, mittel, hoch, kritisch)
  • assignee - Person, der das Issue/der PR zugewiesen wurde
  • created_date - Erstellungsdatum
  • resolved_date - Wann das Issue gelöst wurde (falls zutreffend)
  • labels - Mit dem Dokument verbundene Tags
  • related_pr - Verwandte Pull-Request-ID

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
}

Hinweis: In diesem Beispiel wird eine flache Struktur verwendet, bei der sich alle Felder auf der Stammebene befinden. Die Anforderungen von OpenAI sind flexibel und unterstützen auch verschachtelte Metadatenobjekte.

Datensatz zu GitHub Issues und Pull Requests

Für dieses Tutorial verwenden wir einen internen GitHub Datensatz mit Issues und Pull Requests. Dies stellt ein Szenario dar, in dem Sie private, interne Daten über ChatGPT abfragen möchten.

Den Datensätze finden Sie hier. Wir werden außerdem den Index der Daten mit der Bulk-API aktualisieren.

Dieser Datensatz umfasst:

• Issues mit Beschreibungen, Status, Priorität und Zuweisungen
• Pull-Requests mit Codeänderungen, Bewertungen und Deployment-Informationen
• Beziehungen zwischen Issues und PRs (z. B. PR-578 behebt ISSUE-1889)
• Labels, Daten und andere Metadaten

Index-Mappings

Der Index verwendet die folgenden Mappings, um die hybride Suche mit ELSER zu unterstützen. Das text_semantic wird für die semantische Suche verwendet, während andere Felder die Schlüsselwortsuchen ermöglichen.

{
  "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"
      }
    }
  }
}

Den MCP-Server erstellen

Unser MCP-Server implementiert zwei Tools gemäß den OpenAI Spezifikationen und verwendet die hybride Suche, um den semantischen und den textbasierten Abgleich für bessere Ergebnisse zu kombinieren.

Suchtool

Nutzt hybride Suche mit RRF (Reciprocal Rank Fusion), die semantische Suche mit Textabgleich kombiniert:

@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)}")

Wichtige Punkte:

• Hybride Suche mit RRF: Kombiniert semantische Suche (ELSER) und Text-Suche (BM25) für bessere Ergebnisse.
• Multi-Match-Abfrage: Sucht über mehrere Felder hinweg mit Boosting (title^3, text^2, assignee^2). Das Caret-Symbol (^) multipliziert die Relevanzwerte und priorisiert dabei Treffer in Titeln gegenüber solchen im Inhalt.
• Fuzzy-Matching: fuzziness: AUTO behebt Tippfehler und Rechtschreibfehler, indem es ungefähre Übereinstimmungen erlaubt.
• RRF-Parameterabstimmung:
  • rank_window_size: 50 - Legt fest, wie viele Top-Ergebnisse von jedem Retriever (semantische und textbasierte) vor dem Zusammenführen berücksichtigt werden.
  • rank_constant: 60 - Dieser Wert bestimmt, wie viel Einfluss Dokumente in einzelnen Ergebnismengen auf das endgültige Ranking haben.
• Gibt nur die erforderlichen Felder zurück: id, title, url gemäß OpenAI-Spezifikation, und vermeidet das unnötige Freilegen zusätzlicher Felder.

Abrufwerkzeug

Ruft Dokumentdetails anhand der Dokumenten-ID ab, sofern vorhanden:

@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)}")

Wichtige Punkte:

• Suchen nach Dokumenten-ID-Feld: Verwendet eine Begriffsabfrage im benutzerdefinierten id-Feld.
• Vollständige Rückgabe des Dokuments: Mit vollständigem text-Feld mit allen Inhalten
• Flache Struktur: Alle Felder auf der Wurzelebene, entsprechend der Dokumentstruktur von Elasticsearch.

Bereitstellung auf Google Colab

Wir nutzen Google Colab, um unseren MCP-Server zu betreiben, und ngrok, um ihn öffentlich zugänglich zu machen, damit ChatGPT eine Verbindung herstellen kann.

Schritt 1: Öffnen Sie das Google Colab Notebook

Greifen Sie auf unser vorkonfiguriertes Notebook Elasticsearch MCP für ChatGPT zu.

Schritt 2: Konfigurieren Sie Ihre Anmeldeinformationen

Sie benötigen drei Informationen:

• Elasticsearch URL: Ihre Elasticsearch-Cluster-URL.
• Elasticsearch API-Schlüssel: API-Schlüssel mit Lesezugriff auf Ihren Index.
• Ngrok-Auth-Token: Kostenloses Token von ngrok. Wir nutzen ngrok, um die MCP-URL im Internet sichtbar zu machen, damit ChatGPT sich damit verbinden kann.

So erhalten Sie Ihr ngrok-Token

1. Registrieren Sie sich für ein kostenloses Konto bei ngrok
2. Gehe zu Ihrem Dashboard
3. Kopieren Sie Ihr Authentifizierungs-Token

Secrets zu Google Colab hinzufügen

Im Google Colab-Notizbuch:

1. Klicken Sie auf das Schlüsselsymbol in der linken Seitenleiste, um Secrets zu öffnen.
2. Fügen Sie diese drei Secrets hinzu:

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443
ELASTICSEARCH_API_KEY=your-api-key
NGROK_TOKEN=your-ngrok-token

3. Aktivieren Sie den Notebook-Zugriff für jedes Secret.

Schritt 3: Führen Sie das Notebook aus

1. Klicken Sie auf Runtime und dann auf alle ausführen, um alle Zellen auszuführen.
2. Warten Sie, bis der Server startet (etwa 30 Sekunden)
3. Suchen Sie nach der Ausgabe, die Ihre öffentliche ngrok-URL anzeigt.

4. Die Ausgabe sieht in etwa so aus:

Mit ChatGPT verbinden

Nun verbinden wir den MCP-Server mit Ihrem ChatGPT-Konto.

1. Öffnen Sie ChatGPT und gehen Sie zu Einstellungen.
2. Navigieren Sie zu Konnektoren. Wenn Sie ein Pro-Konto nutzen, müssen Sie den Entwicklermodus in den Konnektoren aktivieren.

Wenn Sie ChatGPT Enterprise oder Business verwenden, müssen Sie den Konnektor an Ihrem Workspace veröffentlichen.

3. Klicken Sie auf Erstellen.

Hinweis: In Business-, Enterprise- und Edu-Workspaces können nur Workspace-Inhaber, Administratoren sowie Benutzer, bei denen die entsprechende Einstellung aktiviert ist (für Enterprise/Edu), benutzerdefinierte Konnektoren hinzufügen. Benutzer mit der regulären Mitgliederrolle sind nicht berechtigt, selbst benutzerdefinierte Konnektoren hinzuzufügen.

Sobald ein Konnektor von einem Benutzer mit der Inhaber- oder Admin-Rolle hinzugefügt und aktiviert wurde, kann er von allen Mitgliedern des Workspaces verwendet werden.

4. Geben Sie die erforderlichen Informationen ein sowie Ihre ngrok-URL, die mit /sse/ endet. Beachten Sie den „/“ nach „sse“. Ohne diesen funktioniert es nicht:

• Name: Elasticsearch MCP
• Beschreibung: Benutzerdefiniertes MCP zum Suchen und Abrufen von internen GitHub-Informationen.

5. Klicken Sie auf Erstellen, um das benutzerdefinierte MCP zu speichern.

Die Verbindung ist sofort hergestellt, wenn Ihr Server läuft. Keine zusätzliche Authentifizierung ist erforderlich, da der Elasticsearch-API-Schlüssel auf Ihrem Server konfiguriert ist.

Teste den MCP-Server

Bevor Sie Fragen stellen, müssen Sie auswählen, welchen Konnektor ChatGPT verwenden soll.

Aufforderung 1: Nach Problemen suchen

Anfrage: „Finde Probleme im Zusammenhang mit der Elasticsearch-Migration“ und bestätigen Sie die Aktionen des aufgerufenen Tools.

ChatGPT wird das Tool search mit Ihrer Abfrage aufrufen. Sie können sehen, dass es nach verfügbaren Tools sucht, sich darauf vorbereitet, das Elasticsearch-Tool aufzurufen. Vor jeglichen Aktionen gegenüber dem Tool wird die Bestätigung des Benutzers eingeholt.

Anfrage zum Aufruf des Tools:

{
  "query": "Elasticsearch migration issues"
}

Reaktion des Tools:

{
  "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 verarbeitet die Ergebnisse und präsentiert sie in einem natürlichen, gesprächsorientierten Format.

Hinter den Kulissen

Prompt: „Finde Probleme im Zusammenhang mit der Elasticsearch-Migration.“

1. ChatGPT-Anrufe search(“Elasticsearch migration”)

2. Elasticsearch führt eine hybride Suche durch.

• Die semantische Suche versteht Konzepte wie „Upgrade“ und „Versionskompatibilität“.
• Die Textsuche findet exakte Treffer für „Elasticsearch“ und „Migration“.
• RRF kombiniert und bewertet Ergebnisse beider Ansätze

3. Sie gibt die 10 am besten mit id, title, übereinstimmenden Ergebnisse zurück url

4. ChatGPT identifiziert „ISSUE-1712: Migration von Elasticsearch 7.x auf 8.x“ als relevantestes Ergebnis.

Prompt 2: Nenne mir die vollständigen Details

Anfrage: „Nenne mir die Details zu ISSUE-1889“

ChatGPT erkennt, dass Sie detaillierte Informationen zu einem bestimmten Problem wünschen, ruft das Tool fetch auf holt beim Benutzer die Bestätigung ein, bevor Maßnahmen gegen das Tool ergriffen werden.

Anfrage zum Aufruf des Tools:

{
  "id": "ISSUE-1889"
}

Reaktion des Tools:

{
  "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 fasst die Informationen zusammen und präsentiert sie übersichtlich.

Hinter den Kulissen

Prompt: „Nenne mir die Details von ISSUE-1889“

1. ChatGPT-Anrufe fetch(“ISSUE-1889”)
2. Elasticsearch ruft das vollständige Dokument ab
3. Gibt ein vollständiges Dokument mit allen Feldern auf der Stammebene zurück
4. ChatGPT synthetisiert die Informationen und antwortet mit korrekten Zitaten.

Fazit

In diesem Artikel haben wir einen maßgeschneiderten MCP-Server erstellt, der ChatGPT mit Elasticsearch über spezielle Such- und Abruf--MCP-Tools verbindet und so natürliche Sprachanfragen zu privaten Daten ermöglicht.

Dieses MCP-Muster funktioniert für jeden Elasticsearch-Index, jede Dokumentation, jedes Produkt, jedes Log oder andere Daten, die Sie über natürliche Sprache abfragen möchten.

Einführung in agentische RAG

Retrieval Augmented Generation (RAG) hat sich zu einem Eckpfeiler in LLM-basierten Anwendungen entwickelt und ermöglicht es Modellen, optimale Antworten zu liefern, indem sie relevanten Kontext auf der Grundlage von Benutzeranfragen abrufen. RAG-Systeme verbessern die Genauigkeit und den Kontext von LLM-Antworten, indem sie auf externe Informationen aus APIs oder Datenspeichern zurückgreifen, anstatt sich auf vorab trainiertes LLM-Wissen zu beschränken. Die KI-Agenten hingegen agieren autonom, treffen Entscheidungen und ergreifen Maßnahmen, um ihre vorgegebenen Ziele zu erreichen.

Agentic RAG ist ein Framework, das die Stärken sowohl der abrufgestützten Generierung als auch des agentenbasierten Schließens vereint. Es integriert RAG in den Entscheidungsprozess des Agenten und ermöglicht dem System so, Datenquellen dynamisch auszuwählen, Abfragen für einen besseren Kontextabruf zu verfeinern, genauere Antworten zu generieren und eine Rückkopplungsschleife anzuwenden, um die Ausgabequalität kontinuierlich zu verbessern.

Hauptmerkmale von agentic RAG

Das agentenbasierte RAG-Framework stellt einen bedeutenden Fortschritt gegenüber traditionellen RAG-Systemen dar. Anstatt einem festgelegten Abrufprozess zu folgen, nutzt es dynamische Agenten, die in der Lage sind, Ergebnisse in Echtzeit zu planen, auszuführen und zu optimieren.

Betrachten wir einige der wichtigsten Merkmale, die agentenbasierte RAG-Pipelines auszeichnen:

• Dynamische Entscheidungsfindung: Agentic RAG verwendet einen Schlussfolgerungsmechanismus, um die Absicht des Benutzers zu verstehen und jede Anfrage an die relevanteste Datenquelle weiterzuleiten, wodurch genaue und kontextbezogene Antworten erzeugt werden.
• Umfassende Abfrageanalyse: Agentic RAG analysiert Benutzerabfragen eingehend, einschließlich Unterfragen und deren Gesamtabsicht. Es bewertet die Komplexität der Anfrage und wählt dynamisch die relevantesten Datenquellen aus, um Informationen abzurufen und so genaue und vollständige Antworten zu gewährleisten.
• Mehrstufige Zusammenarbeit: Dieses Framework ermöglicht eine mehrstufige Zusammenarbeit durch ein Netzwerk spezialisierter Agenten. Jeder Agent bearbeitet einen bestimmten Teil eines größeren Ziels und arbeitet dabei sequenziell oder gleichzeitig, um ein zusammenhängendes Ergebnis zu erzielen.
• Selbstbewertungsmechanismen: Die agentenbasierte RAG-Pipeline nutzt Selbstreflexion, um abgerufene Dokumente und generierte Antworten zu bewerten. Es kann prüfen, ob die abgerufenen Informationen die Anfrage vollständig beantworten, und anschließend die Ausgabe auf Richtigkeit, Vollständigkeit und sachliche Konsistenz überprüfen.
• Integration mit externen Tools: Dieser Workflow kann mit externen APIs, Datenbanken und Echtzeit-Informationsquellen interagieren, aktuelle Informationen einbeziehen und sich dynamisch an sich verändernde Daten anpassen.

Workflow-Muster von agentischen RAG

Die Workflow-Muster definieren, wie agentenbasierte KI LLM-basierte Anwendungen zuverlässig und effizient strukturiert, verwaltet und orchestriert. Zur Implementierung dieser agentenbasierten Arbeitsabläufe können verschiedene Frameworks und Plattformen wie LangChain, LangGraph, CrewAI und LlamaIndex verwendet werden.

1. Sequenzielle Abrufkette: Sequenzielle Arbeitsabläufe unterteilen komplexe Aufgaben in einfache, geordnete Schritte. Jeder Schritt verbessert die Ausgangslage für den nächsten, was zu besseren Ergebnissen führt. Wenn beispielsweise ein Kundenprofil erstellt wird, ruft ein Mitarbeiter grundlegende Daten aus einem CRM-System ab, ein anderer die Kaufhistorie aus einer Transaktionsdatenbank, und ein letzter Mitarbeiter kombiniert diese Informationen, um ein vollständiges Profil für Empfehlungen oder Berichte zu erstellen.
2. Routing-Abrufkette: In diesem Workflow-Muster analysiert ein Router-Agent die Eingabe und leitet sie an den am besten geeigneten Prozess oder die am besten geeignete Datenquelle weiter. Dieser Ansatz ist besonders effektiv, wenn mehrere unterschiedliche Datenquellen mit minimaler Überschneidung vorliegen. In einem Kundenservicesystem kategorisiert beispielsweise der Router-Agent eingehende Anfragen wie technische Probleme, Rückerstattungen oder Beschwerden und leitet sie zur effizienten Bearbeitung an die zuständige Abteilung weiter.
3. Parallele Abrufkette: Bei diesem Workflow-Muster werden mehrere unabhängige Teilaufgaben gleichzeitig ausgeführt, und ihre Ergebnisse werden später zusammengeführt, um eine endgültige Antwort zu generieren. Dieser Ansatz reduziert die Bearbeitungszeit erheblich und erhöht die Effizienz des Arbeitsablaufs. In einem parallelen Arbeitsablauf im Kundenservice ruft beispielsweise ein Mitarbeiter ähnliche, frühere Anfragen ab, während ein anderer Mitarbeiter relevante Artikel in der Wissensdatenbank konsultiert. Ein Aggregator kombiniert diese Ausgaben dann zu einer umfassenden Auflösung.
4. Orchestrator-Worker-Kette: Dieser Workflow weist aufgrund der Verwendung unabhängiger Teilaufgaben Ähnlichkeiten mit der Parallelisierung auf. Ein wesentlicher Unterschied besteht jedoch in der Integration eines Orchestrator-Agenten. Dieser Agent ist dafür zuständig, Benutzeranfragen zu analysieren, sie während der Laufzeit dynamisch in Teilaufgaben zu unterteilen und die geeigneten Prozesse oder Werkzeuge zu identifizieren, die zur Formulierung einer genauen Antwort erforderlich sind.

Aufbau einer agentenbasierten RAG-Pipeline von Grund auf

Um die Prinzipien von agentic RAG zu veranschaulichen, entwerfen wir einen Workflow mit LangChain und Elasticsearch. Dieser Workflow verwendet eine routingbasierte Architektur, bei der mehrere Agenten zusammenarbeiten, um Anfragen zu analysieren, relevante Informationen abzurufen, Ergebnisse auszuwerten und kohärente Antworten zu generieren. Sie können dieses Jupyter-Notebook als Referenz verwenden, um diesem Beispiel zu folgen.

Der Workflow beginnt mit dem Router-Agenten, der die Anfrage des Benutzers analysiert, um die optimale Abrufmethode auszuwählen, d. h. entweder einen vectorstore, websearch, oder einen composite Ansatz. Der Vektorspeicher übernimmt die traditionelle RAG-basierte Dokumentenabfrage, die Websuche ruft die aktuellsten Informationen ab, die nicht im Vektorspeicher gespeichert sind, und der kombinierte Ansatz vereint beide, wenn Informationen aus mehreren Quellen benötigt werden.

Wenn die Dokumente als geeignet erachtet werden, generiert der Zusammenfassungsagent eine klare und kontextbezogene Antwort. Sind die Dokumente jedoch unzureichend oder irrelevant, formuliert der Abfrageumschreibungsagent die Abfrage neu, um die Suche zu verbessern. Diese überarbeitete Abfrage initiiert dann den Routing-Prozess erneut, wodurch das System seine Suche verfeinern und das Endergebnis verbessern kann.

Voraussetzungen

Dieser Workflow benötigt zur effektiven Ausführung des Beispiels die folgenden Kernkomponenten:

• Python 3.10
• Jupyter Notebook
• Azure OpenAI
• Elasticsearch
• LangChain

Bevor Sie fortfahren, werden Sie aufgefordert, die folgenden erforderlichen Umgebungsvariablen für dieses Beispiel zu konfigurieren.

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"

Datenquellen

Dieser Arbeitsablauf wird anhand eines Teildatensatzes von AG News veranschaulicht. Der Datensatz umfasst Nachrichtenartikel aus verschiedenen Kategorien, wie etwa Internationales, Sport, Wirtschaft und Wissenschaft/Technologie.

dataset = load_dataset("ag_news", split="train[:1000]")
docs = [
    Document(
        page_content=sample["text"],
        metadata={"category": sample["label"]}
    )
    for sample in dataset
]

Das ElasticsearchStore-Modul wird ab langchain_elasticsearch als unser Vektorspeicher verwendet. Für den Datenabruf implementieren wir die SparseVectorStrategy unter Verwendung von ELSER, dem proprietären Einbettungsmodell von Elastic. Es ist unerlässlich, sicherzustellen, dass das ELSER-Modell in Ihrer Elasticsearch-Umgebung korrekt installiert und bereitgestellt ist, bevor Sie den Vektorspeicher initialisieren.

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)

Die Web-Suchfunktion wird mithilfe von DuckDuckGoSearchRun aus den LangChain-Community-Tools implementiert, wodurch das System effizient Live-Informationen aus dem Web abrufen kann. Sie können auch die Verwendung anderer Such-APIs in Betracht ziehen, die möglicherweise relevantere Ergebnisse liefern. Dieses Tool wurde gewählt, da es Suchvorgänge ohne API-Schlüssel ermöglicht.

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

Der Composite Retriever ist für Abfragen konzipiert, die eine Kombination von Datenquellen erfordern. Es dient dazu, eine umfassende und kontextbezogene Antwort zu liefern, indem gleichzeitig Echtzeitdaten aus dem Web abgerufen und historische Nachrichten aus dem Vektorspeicher konsultiert werden.

def composite_retriever(query):
    related_docs = vectorstore_retriever(query)
    related_docs += websearch_retriever(query)
    return related_docs

Einrichtung der Agenten

Im nächsten Schritt werden die LLM-Agenten so definiert, dass sie innerhalb dieses Arbeitsablaufs Denk- und Entscheidungsfähigkeiten bereitstellen. Die von uns erstellten LLM-Ketten umfassen: router_chain, grade_docs_chain, rewrite_query_chain, und summary_chain.

Der Router-Agent verwendet einen LLM-Assistenten, um zur Laufzeit die am besten geeignete Datenquelle für eine gegebene Abfrage zu ermitteln. Der Bewertungsagent prüft die abgerufenen Dokumente auf Relevanz. Werden die Dokumente als relevant erachtet, werden sie an den Zusammenfassungsagenten weitergeleitet, um eine Zusammenfassung zu erstellen. Andernfalls formuliert der Rewrite-Abfrageagent die Abfrage neu und sendet sie zur erneuten Abfrage an den Routing-Prozess zurück. Die Anweisungen für alle Agenten finden Sie im Abschnitt „LLM-Ketten“ des Notizbuchs.

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

Die llm.with_structured_output -Klausel sorgt dafür, dass die Ausgabe des Modells einem vordefinierten Schema folgt, das vom BaseModel unter der Klasse RouteQuery definiert wird, und gewährleistet so die Konsistenz der Ergebnisse. Die zweite Zeile bildet ein RunnableSequence , indem sie router_prompt mit router_structured verbindet und so eine Pipeline erzeugt, in der die Eingabeaufforderung vom Sprachmodell verarbeitet wird, um strukturierte, schemakonforme Ergebnisse zu erzeugen.

Graphknoten definieren

Dieser Teil beinhaltet die Definition der Zustände des Graphen, welche die Daten darstellen, die zwischen verschiedenen Komponenten des Systems fließen. Eine klare Spezifikation dieser Zustände stellt sicher, dass jeder Knoten im Workflow weiß, auf welche Informationen er zugreifen und welche er aktualisieren kann.

class RAGState(TypedDict):
    query: str
    docs: List[Document]
    router: str
    summary: str
    self_reflection: bool
    retry_count: int = 0

Sobald die Zustände definiert sind, besteht der nächste Schritt darin, die Knoten des Graphen zu definieren. Knoten sind wie die funktionalen Einheiten des Graphen, die spezifische Operationen an den Daten durchführen. Unsere Pipeline besteht aus 7 verschiedenen Knoten.

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}

Der query_rewriter -Knoten erfüllt im Arbeitsablauf zwei Zwecke. Zunächst wird die Benutzeranfrage mithilfe von rewrite_query_chain umgeschrieben, um die Trefferquote zu verbessern, wenn die vom Selbstreflexionsagenten ausgewerteten Dokumente als unzureichend oder irrelevant erachtet werden. Zweitens fungiert es als Zähler, der verfolgt, wie oft die Abfrage neu geschrieben wurde.

Bei jedem Aufruf des Knotens wird der im Workflow-Status gespeicherte Wert retry_count erhöht. Dieser Mechanismus verhindert, dass der Arbeitsablauf in eine Endlosschleife gerät. Wenn der Wert retry_count einen vordefinierten Schwellenwert überschreitet, kann das System auf einen Fehlerzustand, eine Standardantwort oder eine andere von Ihnen gewählte vordefinierte Bedingung zurückgreifen.

Zusammenstellen des Graphen

Im letzten Schritt werden die Kanten des Graphen definiert und gegebenenfalls notwendige Bedingungen hinzugefügt, bevor er kompiliert wird. Jeder Graph muss von einem festgelegten Startknoten ausgehen, der als Einstiegspunkt für den Workflow dient. Die Kanten im Graphen stellen den Datenfluss zwischen den Knoten dar und können zweierlei Art sein:

• Gerade Kanten: Diese definieren einen direkten, bedingungslosen Fluss von einem Knoten zum anderen. Sobald der erste Knoten seine Aufgabe abgeschlossen hat, fährt der Workflow automatisch mit dem nächsten Knoten entlang der geraden Kante fort.
• Bedingte Kanten: Diese ermöglichen es dem Workflow, sich basierend auf dem aktuellen Zustand oder den Ergebnissen der Berechnung eines Knotens zu verzweigen. Der nächste Knoten wird dynamisch anhand von Bedingungen wie Auswertungsergebnissen, Routing-Entscheidungen oder Wiederholungsanzahl ausgewählt.

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

Damit ist Ihre erste agentenbasierte RAG-Pipeline einsatzbereit und kann mithilfe des kompilierten Agenten getestet werden.

result = agent.invoke({"query": query1})
logger.info(f"\nFinal Summary:\n: {result['summary']}")

Testen der agentischen RAG-Pipeline

Wir werden diese Pipeline nun anhand von drei verschiedenen Abfragetypen testen, wie unten dargestellt. Beachten Sie, dass die Ergebnisse unterschiedlich ausfallen können und die unten aufgeführten Beispiele nur ein mögliches Ergebnis veranschaulichen.

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."

Bei der ersten Abfrage wählt der Router websearch als Datenquelle aus. Die Anfrage besteht die Selbstreflexionsprüfung nicht und wird anschließend zur Anfrageumschreibungsphase weitergeleitet, wie in der Ausgabe gezeigt.

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.

Als nächstes betrachten wir ein Beispiel, bei dem die vectorstore -Suche verwendet wird, was anhand der zweiten Abfrage demonstriert wird.

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.

Die letzte Anfrage wird an die zusammengesetzte Abfrage gerichtet, die sowohl den Vektorspeicher als auch die Websuche nutzt.

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.

Im oben beschriebenen Workflow ermittelt agentic RAG intelligent, welche Datenquelle beim Abruf von Informationen für eine Benutzeranfrage verwendet werden soll, wodurch die Genauigkeit und Relevanz der Antwort verbessert wird. Sie können zusätzliche Beispiele erstellen, um den Agenten zu testen und die Ausgaben zu überprüfen, um zu sehen, ob sie interessante Ergebnisse liefern.

Bewährte Verfahren zum Erstellen agentenbasierter RAG-Workflows

Nachdem wir nun verstanden haben, wie agentic RAG funktioniert, schauen wir uns einige Best Practices für die Erstellung dieser Workflows an. Die Einhaltung dieser Richtlinien trägt dazu bei, dass das System effizient und wartungsfreundlich bleibt.

• Bereiten Sie sich auf Ausweichlösungen vor: Planen Sie im Voraus Ausweichstrategien für Szenarien, in denen ein Schritt des Arbeitsablaufs fehlschlägt. Dies kann die Rückgabe von Standardantworten, das Auslösen von Fehlerzuständen oder die Verwendung alternativer Tools umfassen. Dadurch wird sichergestellt, dass das System Fehler reibungslos behebt, ohne den Gesamt-Workflow zu unterbrechen.
• Implementieren Sie eine umfassende Protokollierung: Versuchen Sie, in jeder Phase des Workflows eine Protokollierung zu implementieren, z. B. bei Wiederholungsversuchen, generierten Ausgaben, Routing-Entscheidungen und Abfrageumschreibungen. Diese Protokolle tragen dazu bei, die Transparenz zu verbessern, das Debuggen zu vereinfachen und die Eingabeaufforderungen, das Verhalten der Agenten und die Abrufstrategien im Laufe der Zeit zu verfeinern.
• Wählen Sie das passende Workflow-Muster: Analysieren Sie Ihren Anwendungsfall und wählen Sie das Workflow-Muster, das Ihren Bedürfnissen am besten entspricht. Nutzen Sie sequentielle Arbeitsabläufe für schrittweise Schlussfolgerungen, parallele Arbeitsabläufe für unabhängige Datenquellen und Orchestrator-Worker-Muster für Abfragen mit mehreren Tools oder komplexen Abfragen.
• Evaluierungsstrategien einbeziehen: Evaluierungsmechanismen in verschiedenen Phasen des Arbeitsablaufs integrieren. Dies können Selbstreflexionsagenten, die Bewertung abgerufener Dokumente oder automatisierte Qualitätskontrollen sein. Die Auswertung hilft dabei zu überprüfen, ob die abgerufenen Dokumente relevant sind, die Antworten korrekt sind und alle Teile einer komplexen Anfrage berücksichtigt werden.

Herausforderungen

Während agentenbasierte RAG-Systeme hinsichtlich Anpassungsfähigkeit, Präzision und dynamischem Denken erhebliche Vorteile bieten, bringen sie auch gewisse Herausforderungen mit sich, die während ihrer Entwurfs- und Implementierungsphase bewältigt werden müssen. Zu den wichtigsten Herausforderungen gehören:

• Komplexe Arbeitsabläufe: Mit zunehmender Anzahl von Agenten und Entscheidungspunkten wird der gesamte Arbeitsablauf immer komplexer. Dies kann zu einer höheren Wahrscheinlichkeit von Fehlern oder Ausfällen zur Laufzeit führen. Priorisieren Sie nach Möglichkeit optimierte Arbeitsabläufe, indem Sie redundante Agenten und unnötige Entscheidungspunkte eliminieren.
• Skalierbarkeit: Die Skalierung agentenbasierter RAG-Systeme zur Bewältigung großer Datensätze und hoher Abfragevolumina kann eine Herausforderung darstellen. Um die Leistungsfähigkeit auch bei großem Umfang aufrechtzuerhalten, sollten effiziente Indexierungs-, Caching- und verteilte Verarbeitungsstrategien integriert werden.
• Orchestrierung und Rechenaufwand: Die Ausführung von Arbeitsabläufen mit mehreren Agenten erfordert eine fortgeschrittene Orchestrierung. Dies umfasst eine sorgfältige Terminplanung, das Management von Abhängigkeiten und die Koordination der Agenten, um Engpässe und Konflikte zu vermeiden, die alle zur Gesamtkomplexität des Systems beitragen.
• Evaluierungskomplexität: Die Evaluierung dieser Arbeitsabläufe birgt inhärente Herausforderungen, da jede Phase eine eigene Bewertungsstrategie erfordert. Beispielsweise muss die RAG-Phase hinsichtlich der Relevanz und Vollständigkeit der abgerufenen Dokumente bewertet werden, während die generierten Zusammenfassungen auf Qualität und Genauigkeit geprüft werden müssen. Ebenso erfordert die Effektivität der Abfrageumformulierung eine separate Auswertungslogik, um festzustellen, ob die umgeschriebene Abfrage die Suchergebnisse verbessert.

Fazit

In diesem Blogbeitrag haben wir das Konzept des agentischen RAG vorgestellt und hervorgehoben, wie es das traditionelle RAG-Framework durch die Einbeziehung autonomer Fähigkeiten aus der agentischen KI erweitert. Wir untersuchten die Kernfunktionen von agentic RAG und demonstrierten diese Funktionen anhand eines praktischen Beispiels, indem wir einen Nachrichtenassistenten mit Elasticsearch als Vektorspeicher und LangChain zur Erstellung des agentic Frameworks entwickelten.

Darüber hinaus erörterten wir bewährte Vorgehensweisen und wichtige Herausforderungen, die bei der Konzeption und Implementierung einer agentenbasierten RAG-Pipeline zu berücksichtigen sind. Diese Erkenntnisse sollen Entwicklern als Leitfaden dienen, um robuste, skalierbare und effiziente agentenbasierte Systeme zu erstellen, die Abruf, Schlussfolgerung und Entscheidungsfindung effektiv kombinieren.

Was kommt als Nächstes?

Der von uns entwickelte Workflow ist einfach gehalten und bietet viel Raum für Verbesserungen und Experimente. Dies lässt sich verbessern, indem wir mit verschiedenen Einbettungsmodellen experimentieren und die Abrufstrategien verfeinern. Darüber hinaus könnte die Integration eines Re-Ranking-Agenten zur Priorisierung der abgerufenen Dokumente von Vorteil sein. Ein weiteres Forschungsfeld umfasst die Entwicklung von Evaluierungsstrategien für agentenbasierte Frameworks, insbesondere die Identifizierung gemeinsamer und wiederverwendbarer Ansätze, die für verschiedene Framework-Typen anwendbar sind. Abschließend werden diese Frameworks an großen und komplexeren Datensätzen erprobt.

Sollten Sie in der Zwischenzeit ähnliche Experimente durchgeführt haben, würden wir uns freuen, davon zu hören! Geben Sie uns gerne Feedback oder treten Sie über unseren Community-Slack-Kanal oder unsere Diskussionsforen mit uns in Kontakt.

Ressourcen

• Selbst-RAG: Lernen, durch Selbstreflexion abzurufen, zu generieren und zu kritisieren
• Agentic Retrieval-Augmented Generation: Eine Übersicht über Agentic RAG

Das Problem der Punktespanne

Um die Ausgangslage zu verdeutlichen, betrachten wir zunächst einen der Hauptgründe, warum die hybride Suche schwierig sein kann: die variierenden Bewertungsbereiche. Unser alter Bekannter BM25 liefert unbegrenzte Ergebnisse. Mit anderen Worten: BM25 kann Werte generieren, die von nahe 0 bis (theoretisch) unendlich reichen. Im Gegensatz dazu liefern Abfragen gegen dense_vector -Felder Ergebnisse im Bereich zwischen 0 und 1. Erschwerend kommt hinzu, dass semantic_text den Feldtyp verschleiert, der zur Indizierung von Einbettungen verwendet wird. Daher ist es ohne detaillierte Kenntnisse über die Konfiguration Ihres Index und Inferenzendpunkts schwierig abzuschätzen, in welchem Bereich die Ergebnisse Ihrer Abfrage liegen werden. Dies stellt ein Problem dar, wenn versucht wird, lexikalische und semantische Suchergebnisse zu verschachteln, da die lexikalischen Ergebnisse Vorrang vor den semantischen haben können, selbst wenn die semantischen Ergebnisse relevanter sind. Die allgemein anerkannte Lösung für dieses Problem besteht darin, die Werte vor der Verschachtelung der Ergebnisse zu normalisieren. Elasticsearch bietet hierfür zwei Tools an: den linearen und den RRF- Retriever.

Der RRF- Retriever wendet den RRF-Algorithmus an, wobei der Dokumentenrang als Relevanzmaß verwendet und der Score verworfen wird. Da die Punktzahl nicht berücksichtigt wird, stellen Abweichungen im Punktzahlbereich kein Problem dar.

Der lineare Retriever verwendet eine lineare Kombination, um die endgültige Punktzahl eines Dokuments zu bestimmen. Dabei wird für jede einzelne Abfrage die Punktzahl der Komponenten des Dokuments ermittelt, normalisiert und anschließend summiert, um die Gesamtpunktzahl zu erhalten. Mathematisch lässt sich die Operation wie folgt ausdrücken:

Total Score = 𝚺(N(Sx))

Dabei ist N die Normalisierungsfunktion und SX die Punktzahl für die Anfrage X. Die Normalisierungsfunktion ist hierbei von zentraler Bedeutung, da sie die Punktzahl jeder Abfrage so transformiert, dass sie denselben Wertebereich verwendet. Hier erfahren Sie mehr über den linearen Retriever.

Aufgeschlüsselt

Mit diesen Tools können Benutzer eine effektive Hybridsuche implementieren, dies erfordert jedoch gewisse Kenntnisse über ihren Index. Betrachten wir ein Beispiel mit dem linearen Retriever, bei dem wir einen Index mit zwei Feldern abfragen:

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 ist ein semantic_text -Feld, das E5, ein Text-Embedding-Modell, verwendet.

2. text_field ist ein Standard- text -Feld

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. Wir verwenden eine match -Abfrage für unser semantic_text -Feld, dessen Unterstützung wir in Elasticsearch 8.18/9.0 hinzugefügt haben.

Bei der Erstellung der Abfrage müssen wir berücksichtigen, dass semantic_text_field ein Text-Embedding-Modell verwendet, sodass alle Abfragen darauf eine Punktzahl zwischen 0 und 1 generieren. Wir müssen außerdem wissen, dass text_field ein Standardfeld text ist und dass Abfragen darauf eine unbegrenzte Punktzahl erzeugen. Um ein Ergebnis-Set mit der richtigen Relevanz zu erstellen, müssen wir einen Retriever verwenden, der die Abfrage-Scores normalisiert, bevor er sie kombiniert. In diesem Beispiel verwenden wir den linearen Retriever mit minmax -Normalisierung, der den Score jeder Abfrage auf einen Wert zwischen 0 und 1 normalisiert.

Die Abfragekonstruktion in diesem Beispiel ist recht einfach, da nur zwei Felder beteiligt sind. Allerdings kann es sehr schnell kompliziert werden, wenn weitere Felder unterschiedlicher Art hinzugefügt werden. Dies zeigt, dass das Schreiben einer effektiven hybriden Suchanfrage oft ein tieferes Verständnis des abgefragten Index erfordert, damit die Punktzahlen der einzelnen Suchanfragen vor der Kombination richtig normalisiert werden. Dies stellt ein Hindernis für die breitere Akzeptanz der hybriden Suche dar.

Abfragegruppierung

Erweitern wir das Beispiel: Was wäre, wenn wir ein text -Feld und zwei semantic_text -Felder abfragen wollten? Wir könnten eine Abfrage wie diese erstellen:

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"
        }
      ]
    }
  }
}

Das klingt auf den ersten Blick gut, aber es gibt ein potenzielles Problem. Die Treffer im Feld semantic_text machen nun ⅔ der Gesamtpunktzahl aus:

Total Score = N(semantic_text_field_1 score) + N(semantic_text_field_2 score) + N(text_field score)

Das ist wahrscheinlich nicht das, was Sie wollen, denn dadurch entsteht ein unausgewogenes Ergebnis. Die Auswirkungen sind in einem Beispiel wie diesem mit nur 3 Feldern möglicherweise nicht so deutlich erkennbar, aber es wird problematisch, wenn mehr Felder abgefragt werden. Beispielsweise enthalten die meisten Indizes weitaus mehr lexikalische als semantische Felder (d. h. dense_vector, sparse_vector, oder semantic_text). Was wäre, wenn wir einen Index mit 9 lexikalischen Feldern und 1 semantischen Feld nach dem oben genannten Muster abfragen würden? Die lexikalischen Übereinstimmungen würden 90 % der Punktzahl ausmachen und somit die Effektivität der semantischen Suche beeinträchtigen.

Eine gängige Methode, um diesem Problem zu begegnen, besteht darin, Anfragen in lexikalische und semantische Kategorien zu gruppieren und beide gleich zu gewichten. Dadurch wird verhindert, dass eine der beiden Kategorien die Gesamtpunktzahl dominiert.

Lasst uns das in die Praxis umsetzen. Wie sähe dieser Ansatz mit gruppierten Abfragen in diesem Beispiel bei Verwendung des linearen Retrievers aus?

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, das wird aber ausführlich! Möglicherweise mussten Sie sogar mehrmals auf- und abscrollen, um die gesamte Abfrage zu prüfen! Hier verwenden wir zwei Normalisierungsebenen, um die Abfragegruppen zu erstellen. Mathematisch lässt sich dies wie folgt ausdrücken:

Total Score = N(N(semantic_text_field_1 score) + N(semantic_text_field_2 score)) + N(text_field score)

Diese zweite Normalisierungsebene stellt sicher, dass die Anfragen an die Felder semantic_text und text gleich gewichtet werden. Beachten Sie, dass wir in diesem Beispiel die Normalisierung zweiter Ebene für text_field weglassen, da es nur ein lexikalisches Feld gibt, wodurch Sie sich noch mehr Ausführlichkeit ersparen.

Diese Abfragestruktur ist schon jetzt unhandlich, und wir fragen nur drei Felder ab. Je mehr Felder man abfragt, desto unübersichtlicher wird es, selbst für erfahrene Suchmaschinenexperten.

Das Abfrageformat mit mehreren Feldern

Um das Ganze zu vereinfachen, haben wir das Multi-Field-Abfrageformat für die linearen und RRF-Retriever in Elasticsearch 8.19, 9.1 und Serverless hinzugefügt. Sie können die gleiche Abfrage wie oben nun mit folgendem Befehl durchführen:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Dadurch verkürzt sich die Abfrage von 55 Zeilen auf nur noch 9! Elasticsearch verwendet automatisch die Indexzuordnungen für:

• Ermitteln Sie den Typ jedes abgefragten Feldes.
• Ordnen Sie jedes Feld einer lexikalischen oder semantischen Kategorie zu.
• Jede Kategorie sollte im Endergebnis gleich gewichtet werden.

Dies ermöglicht es jedem, eine effektive hybride Suchanfrage auszuführen, ohne Details über den Index oder die verwendeten Inferenzendpunkte kennen zu müssen.

Bei Verwendung von RRF kann das normalizer weggelassen werden, da der Rang als Indikator für die Relevanz dient:

GET rrf_retriever_example/_search
{
  "retriever": {
    "rrf": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo"
    }
  }
}

Steigerung pro Spielfeld

Bei Verwendung des linearen Retrievers können Sie eine Gewichtung pro Feld anwenden, um die Wichtigkeit von Übereinstimmungen in bestimmten Feldern anzupassen. Nehmen wir beispielsweise an, Sie fragen vier Felder ab: zwei semantic_text -Felder und zwei text -Felder:

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"
    }
  }
}

Standardmäßig wird jedes Feld innerhalb seiner Gruppe (lexikalisch oder semantisch) gleich gewichtet. Die Punkteverteilung sieht wie folgt aus:

Mit anderen Worten: Jedes Feld macht 25 % der Gesamtpunktzahl aus.

Mit der Syntax field^boost können wir jedem Feld einen feldbezogenen Boost hinzufügen. Wenden wir einen Boost von 2 auf semantic_text_field_1 und text_field_1 an:

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"
    }
  }
}

Die Aufschlüsselung der Punkte sieht nun wie folgt aus:

Jede Abfragegruppe ist weiterhin gleich gewichtet, aber die Feldgewichtung innerhalb der Gruppen hat sich geändert:

• semantic_text_field_1 entspricht 66 % der Punktzahl der semantischen Abfragegruppe und 33 % der Gesamtpunktzahl.
• text_field_1 macht 66 % der Punktzahl der lexikalischen Abfragegruppe und 33 % der Gesamtpunktzahl aus.

Wildcard-Auflösung

Sie können das Platzhalterzeichen * im Parameter fields verwenden, um mehrere Felder abzugleichen. Um das obige Beispiel fortzuführen: Diese Abfrage ist funktional äquivalent zur expliziten Abfrage von semantic_text_field_1, semantic_text_field_2, und text_field_1 :

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_*", "*_field_1" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Interessanterweise passt das Muster *_field_1 sowohl zu text_field_1 als auch semantic_text_field_1. Dies wird automatisch gehandhabt; die Abfrage wird so ausgeführt, als ob jedes der Felder explizit abgefragt würde. Es ist auch in Ordnung, dass semantic_text_field_1 beiden Mustern entspricht; alle Feldnamenübereinstimmungen werden vor der Abfrageausführung dedupliziert.

Sie können das Wildcard-Zeichen auf verschiedene Arten verwenden:

• Präfixübereinstimmung (z. B. *_text_field)
• Inline-Matching (z. B. semantic_*_field)
• Suffix-Matching (z. B. semantic_text_field_*)

Sie können auch mehrere Platzhalter verwenden, um eine Kombination der oben genannten anzuwenden, z. B. *_text_field_*.

Standardabfragefelder

Das Abfrageformat mit mehreren Feldern ermöglicht es Ihnen auch, einen Index abzufragen, über den Sie nichts wissen. Wenn Sie den Parameter fields weglassen, werden alle Felder abgefragt, die durch die Indexeinstellung index.query.default_field angegeben sind:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Standardmäßig ist index.query.default_field auf * gesetzt. Dieser Platzhalter wird auf jeden Feldtyp im Index aufgelöst, der Termabfragen unterstützt, was auf die meisten zutrifft. Die Ausnahmen sind:

• dense_vector Felder
• rank_vector Felder
• Geometrische Felder: geo_point, shape

Diese Funktionalität ist besonders nützlich, wenn Sie eine hybride Suchanfrage auf einem von einem Drittanbieter bereitgestellten Index durchführen möchten. Das Abfrageformat mit mehreren Feldern ermöglicht es Ihnen, auf einfache Weise eine passende Abfrage auszuführen. Lassen Sie einfach den Parameter fields weg, und alle relevanten Felder werden abgefragt.

Fazit

Das Problem der Bewertungsbereiche kann die Implementierung einer effektiven hybriden Suche zu einer echten Herausforderung machen, insbesondere wenn nur begrenzter Einblick in den abgefragten Index oder die verwendeten Inferenzendpunkte besteht. Das Mehrfeld-Abfrageformat für die linearen und RRF-Retriever mindert dieses Problem, indem es einen automatisierten, auf Abfragegruppierung basierenden hybriden Suchansatz in einer einfachen und zugänglichen API bündelt. Zusätzliche Funktionen wie die Gewichtung einzelner Felder, die Auflösung von Platzhaltern und die Verwendung von Standardabfragefeldern erweitern den Funktionsumfang und decken viele Anwendungsfälle ab.

Probieren Sie heute noch das Abfrageformat mit mehreren Feldern aus.

Sie können die linearen und RRF-Retriever mit dem Multi-Field-Query-Format in vollständig verwalteten Elasticsearch Serverless- Projekten mit einer kostenlosen Testversion ausprobieren. Es ist auch in Stack-Versionen ab 8.19 und 9.1 verfügbar.

Legen Sie in wenigen Minuten in Ihrer lokalen Umgebung mit einem einzigen Befehl los:

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

Dieser Artikel zeigt Ihnen, wie Sie mit GPT-OSS und Elastic Agent Builder einen KI-Agenten für HR erstellen. Der Agent kann Ihre Fragen beantworten, ohne Daten an OpenAI, Anthropic oder einen externen Dienst zu senden.

Wir werden LM Studio verwenden, um GPT-OSS lokal bereitzustellen und es mit dem Elastic Agent Builder zu verbinden.

Am Ende dieses Artikels verfügen Sie über einen individuell angepassten KI-Agenten, der Fragen in natürlicher Sprache zu Ihren Mitarbeiterdaten beantworten kann und gleichzeitig die volle Kontrolle über Ihre Informationen und Ihr Modell behält.

Voraussetzungen

Für diesen Artikel benötigen Sie:

• Elastic Cloud- gehostete Version 9.2, serverlose oder lokale Bereitstellung
• Empfohlen wird ein Rechner mit 32 GB RAM (mindestens 16 GB für GPT-OSS 20B).
• LM Studio installiert
• Docker Desktop installiert

Warum GPT-OSS verwenden?

Mit einem lokalen LLM haben Sie die Kontrolle, es in Ihrer eigenen Infrastruktur einzusetzen und es genau an Ihre Bedürfnisse anzupassen. All dies, während Sie die Kontrolle über die Daten behalten, die Sie mit dem Modell teilen, und natürlich müssen Sie keine Lizenzgebühr an einen externen Anbieter zahlen.

OpenAI veröffentlichte GPT-OSS am 5. August 2025 als Teil seines Engagements für das offene Ökosystem von Computermodellen.

Das Parametermodell 20B bietet:

• Werkzeugnutzungsfähigkeiten
• Effiziente Schlussfolgerung
• OpenAI SDK-kompatibel
• Kompatibel mit agentenbasierten Workflows

Vergleich der Benchmarks:

Lösungsarchitektur

Die Architektur läuft vollständig auf Ihrem lokalen Rechner. Elastic (läuft in Docker) kommuniziert direkt mit Ihrem lokalen LLM über LM Studio, und der Elastic Agent Builder nutzt diese Verbindung, um benutzerdefinierte KI-Agenten zu erstellen, die Ihre Mitarbeiterdaten abfragen können.

Weitere Einzelheiten entnehmen Sie bitte dieser Dokumentation.

Entwicklung eines KI-Agenten für die Personalabteilung: Schritte

Wir werden die Implementierung in 5 Schritte unterteilen:

1. Konfigurieren Sie LM Studio mit einem lokalen Modell
2. Lokalen Elastic-Speicher mit Docker bereitstellen
3. Erstellen Sie den OpenAI-Konnektor in Elastic
4. Mitarbeiterdaten in Elasticsearch hochladen
5. Erstellen und testen Sie Ihren KI-Agenten

Schritt 1: LM Studio mit GPT-OSS 20B konfigurieren

LM Studio ist eine benutzerfreundliche Anwendung, mit der Sie große Sprachmodelle lokal auf Ihrem Computer ausführen können. Es bietet einen OpenAI-kompatiblen API-Server, wodurch die Integration mit Tools wie Elastic ohne komplexen Einrichtungsprozess vereinfacht wird. Weitere Details finden Sie in der LM Studio-Dokumentation.

Laden Sie zunächst LM Studio von der offiziellen Website herunter und installieren Sie es. Nach der Installation öffnen Sie die Anwendung.

In der LM Studio-Oberfläche:

1. Gehen Sie zum Suchfeld und suchen Sie nach „GPT-OSS“.
2. Wählen Sie openai/gpt-oss-20b aus OpenAI aus.
3. Klicken Sie auf „Herunterladen“.

Die Größe dieses Modells sollte ungefähr 12,10 GB betragen. Der Download kann je nach Ihrer Internetverbindung einige Minuten dauern.

Sobald das Modell heruntergeladen ist:

1. Wechseln Sie zur Registerkarte „Lokaler Server“.
2. Wählen Sie openai/gpt-oss-20b aus.
3. Verwenden Sie den Standardport 1234.
4. Gehen Sie im rechten Bereich auf „Laden“und stellen Sie die Kontextlänge auf 40 KB oder höher ein.

5. Klicken Sie auf „Server starten“.

Dies sollte Ihnen angezeigt werden, wenn der Server läuft.

[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.

Schritt 2: Lokalen Elastic-Speicher mit Docker bereitstellen

Nun richten wir Elasticsearch und Kibana lokal mit Docker ein. Elastic stellt ein praktisches Skript zur Verfügung, das den gesamten Einrichtungsprozess übernimmt. Für weitere Einzelheiten verweisen wir auf die offizielle Dokumentation.

Führen Sie das Start-Lokal-Skript aus

Führen Sie folgenden Befehl in Ihrem Terminal aus:

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

Dieses Skript wird:

• Elasticsearch und Kibana herunterladen und konfigurieren
• Starten Sie beide Dienste mit Docker Compose.
• Automatische Aktivierung einer 30-tägigen Platinum-Testlizenz

Erwartete Ausgabe

Warten Sie einfach auf die folgende Meldung und speichern Sie das angezeigte Passwort und den API-Schlüssel; Sie benötigen diese für den Zugriff auf 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

Zugriff auf Kibana

Öffnen Sie Ihren Browser und navigieren Sie zu:

http://localhost:5601

Melden Sie sich mit den Anmeldeinformationen an, die Sie in der Terminalausgabe erhalten haben.

Agent Builder aktivieren

Nach dem Einloggen in Kibana navigieren Sie zu Management > AI > Agent Builder und aktivieren den Agent Builder.

Schritt 3: Erstellen Sie den OpenAI-Konnektor in Elastic

Nun konfigurieren wir Elastic so, dass es Ihr lokales LLM verwendet.

Zugangsanschlüsse

1. In Kibana
2. Gehen Sie zu Projekteinstellungen > Verwaltung
3. Unter „Warnungen und Einblicke“ wählen Sie „Konnektoren“aus.
4. Klicken Sie auf „Connector erstellen“.

Konfigurieren Sie den Anschluss

Wählen Sie OpenAI aus der Liste der Konnektoren aus. LM Studio nutzt das OpenAI SDK und ist daher kompatibel.

Füllen Sie die Felder mit diesen Werten aus:

• Anschlussname: LM Studio - GPT-OSS 20B
• Wählen Sie einen OpenAI-Anbieter: Andere (OpenAI-kompatibler Dienst)
• URL: http://host.docker.internal:1234/v1/chat/completions
• Standardmodell: openai/gpt-oss-20b
• API-Schlüssel: testkey-123 (Jeder beliebige Text funktioniert, da LM Studio Server keine Authentifizierung erfordert.)

Klicken Sie zum Abschluss der Konfiguration auf Speichern & Testen.

Wichtig: Aktivieren Sie die Option „ Native Funktionsaufrufe aktivieren“; dies ist erforderlich, damit der Agent Builder ordnungsgemäß funktioniert. Wenn Sie dies nicht aktivieren, erhalten Sie einen No tool calls found in the response -Fehler.

Testen Sie die Verbindung

Elastic sollte die Verbindung automatisch testen. Wenn alles korrekt konfiguriert ist, wird eine Erfolgsmeldung wie diese angezeigt:

Abwehr:

{
  "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"
}

Schritt 4: Mitarbeiterdaten in Elasticsearch hochladen

Nun laden wir den HR-Mitarbeiterdatensatz hoch, um zu demonstrieren, wie der Agent mit sensiblen Daten arbeitet. Ich habe einen fiktiven Datensatz mit dieser Struktur generiert.

Struktur des Datensatzes

{
  "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"
}

Erstellen Sie den Index mit Zuordnungen

Zuerst muss der Index mit den entsprechenden Zuordnungen erstellt werden. Beachten Sie, dass wir für einige Schlüsselfelder semantische Textfelder verwenden; dies ermöglicht semantische Suchfunktionen für unseren 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"
      }
    }
  }
}

Indexierung mit Bulk-API

Kopieren Sie den Datensatz in Ihre Entwicklertools in Kibana und führen Sie ihn aus:

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": "...", ...}

Überprüfen Sie die Daten.

Führen Sie eine Abfrage zur Überprüfung durch:

GET hr-employees/_search

Schritt 5: KI-Agent erstellen und testen

Nachdem alles konfiguriert ist, ist es nun an der Zeit, mit dem Elastic Agent Builder einen benutzerdefinierten KI-Agenten zu erstellen. Weitere Details finden Sie in der Elastic-Dokumentation.

Fügen Sie den Verbinder hinzu.

Bevor wir unseren neuen Agenten erstellen können, müssen wir unseren Agent Builder so einstellen, dass er unseren benutzerdefinierten Konnektor mit der Bezeichnung LM Studio - GPT-OSS 20B verwendet, da der Standardkonnektor Elastic Managed LLM ist. Dazu müssen wir zu Projekteinstellungen > Verwaltung > GenAI-Einstellungen gehen; jetzt wählen wir die von uns erstellte Einstellung aus und klicken auf Speichern.

Zugriffsagenten-Generator

1. Gehen Sie zu den Agenten.
2. Klicken Sie auf „Neuen Agenten erstellen“.

Konfigurieren Sie den Agenten

Zum Anlegen eines neuen Agenten sind die Felder Agenten-ID, Anzeigename und Anzeigeanweisungen erforderlich.

Es gibt aber noch weitere Anpassungsmöglichkeiten, wie zum Beispiel die benutzerdefinierten Anweisungen, die vorgeben, wie sich Ihr Agent verhalten und mit Ihren Tools interagieren soll, ähnlich einer Systemaufforderung, aber für unseren benutzerdefinierten Agenten. Mithilfe von Labels lassen sich Agenten, Avatarfarben und Avatarsymbole organisieren.

Diejenigen, die ich anhand des Datensatzes für unseren Agenten ausgewählt habe, sind:

Agenten-ID: hr_assistant

Benutzerdefinierte Anweisungen:

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

Labels: Human Resources und GPT-OSS

Anzeigename: HR Analytics Assistant

Anzeigebeschreibung:

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.

Nachdem alle Daten eingegeben wurden, können wir auf „Unseren neuen Agenten speichern “ klicken.

Testen Sie den Agenten

Sie können nun Fragen in natürlicher Sprache zu Ihren Mitarbeiterdaten stellen, und GPT-OSS 20B versteht die Absicht und generiert eine angemessene Antwort.

Prompt:

Which employee is the one with the highest salary in the hr-employees index?

Antwort:

Der Agentenprozess war wie folgt:

1. Verstehen Sie Ihre Frage mithilfe des GPT-OSS-Connectors.

2. Generieren Sie die entsprechende Elasticsearch-Abfrage (mithilfe der integrierten Tools oder einer benutzerdefinierten ES|QL- Abfrage).

3. Abrufen passender Mitarbeiterdatensätze

4. Die Ergebnisse in natürlicher Sprache und mit geeigneter Formatierung präsentieren

Im Gegensatz zur herkömmlichen lexikalischen Suche versteht der von GPT-OSS unterstützte Agent Absicht und Kontext, wodurch es einfacher wird, Informationen zu finden, ohne die genauen Feldnamen oder die Abfragesyntax kennen zu müssen. Weitere Einzelheiten zum Denkprozess des Agenten finden Sie in diesem Artikel.

Fazit

In diesem Artikel haben wir mithilfe des Agent Builders von Elastic einen benutzerdefinierten KI-Agenten erstellt, um eine Verbindung zum lokal laufenden OpenAI GPT-OSS-Modell herzustellen. Durch die Bereitstellung von Elastic und LLM auf Ihrem lokalen Rechner ermöglicht Ihnen diese Architektur die Nutzung generativer KI-Funktionen bei gleichzeitiger vollständiger Kontrolle über Ihre Daten, ohne dass Informationen an externe Dienste gesendet werden müssen.

Wir haben GPT-OSS 20B als Experiment verwendet, aber die offiziell empfohlenen Modelle für Elastic Agent Builder sind hier aufgeführt. Falls Sie fortgeschrittenere Schlussfolgerungsfähigkeiten benötigen, gibt es auch die 120B-Parametervariante , die bei komplexen Szenarien besser abschneidet, allerdings ist für die lokale Ausführung ein leistungsstärkerer Rechner erforderlich. Weitere Einzelheiten finden Sie in der offiziellen OpenAI-Dokumentation.

Vor einigen Wochen hatten wir die unglaubliche Gelegenheit, Cal Hacks 12.0 zu sponsern, einen der größten Präsenz-Hackathons mit über 2000 Teilnehmern aus aller Welt. Wir haben einen eigenen Preiswettbewerb für die beste Nutzung von Elastic Agent Builder auf Serverless-Plattformen angeboten, und die Resonanz war phänomenal. Innerhalb von nur 36 Stunden erhielten wir 29 Einsendungen, die Agent Builder auf kreative Weise nutzten, von der Entwicklung von Tools zur Waldbrandanalyse bis hin zu StackOverflow-Validatoren.

Neben den beeindruckenden Projekten hat uns die Erfahrung bei Cal Hacks 12.0 auch etwas ebenso Wertvolles gebracht: schnelles, unverfälschtes Feedback von Entwicklern, die zum ersten Mal mit unserem Stack in Berührung kamen. Hackathons sind einzigartige Drucktests mit engen Zeitvorgaben, keinerlei Vorkenntnissen und unvorhersehbaren Hindernissen (wie den berüchtigten WLAN-Ausfällen). Sie zeigen genau, wo die Entwicklererfahrung glänzt und wo noch Verbesserungsbedarf besteht. Dies ist heute umso wichtiger, da Entwickler auf neue Weise mit dem Elastic Stack interagieren, zunehmend über LLM-gesteuerte Workflows. In diesem Blogbeitrag werden wir genauer darauf eingehen, was die Teilnehmer mit Agent Builder erstellt haben und was wir dabei gelernt haben.

Die Gewinnerprojekte

Erster Platz: AgentOverflow

Stack Overflow neu entwickelt für die LLM- und Agentenära.

Lesen Sie hier mehr über AgentOverflow.

AgentOverflow löst ein Problem, mit dem die meisten KI-Entwickler konfrontiert sind: LLMs halluzinieren, Chatverläufe verschwinden, und Entwickler verschwenden Zeit damit, dieselben Probleme immer wieder zu lösen.

AgentOverflow erfasst, validiert und präsentiert reale Problem-Lösungs-Paare, damit Entwickler die Illusionsspirale durchbrechen und schneller Ergebnisse liefern können.

So funktioniert es:

1. JSON teilen – das „Lösungsschema“.

Ein Klick auf eine Claude-Freigabe extrahiert und erstellt eine Share Solution JSON-Datei in einem strukturierten Format, das Folgendes enthält:

• Problem
• Kontext
• Code
• Tags
• Die Lösungsschritte wurden verifiziert.

Ein Validator (LAVA) prüft und erzwingt die Struktur, der Benutzer fügt eine Zeile zusätzlichen Kontexts hinzu, dann wird das Ganze in Elasticsearch gespeichert und indiziert.

2. Lösung finden

Wenn Sie nicht weiterkommen, klicken Sie auf Find Solution AgentOverflow extrahiert dann Ihre aktuelle Konversation, erstellt daraus eine Abfrage und führt eine hybride Elasticsearch-Suche durch, um Folgendes anzuzeigen:

• Rangliste, von der Community validierte Korrekturen
• Die genauen Eingabeaufforderungen, die das Problem ursprünglich gelöst haben

Dies ermöglicht es Entwicklern, ihre aktuelle Sitzung schnell zu kopieren, einzufügen und zu entsperren.

3. MCP – Kontextinjektion für LLMs

Durch die Anbindung an die in Elasticsearch gespeicherten strukturierten Lösungen über MCP (Model Context Protocol) erhalten LLMs zur Laufzeit einen hochsignifikanten Kontext (Code, Protokolle, Konfigurationen, vorherige Korrekturen) ohne zusätzliche Störungen.

AgentOverflow verwendet Agent Builder mit Elasticsearch als strukturierte Speicherschicht, die relevanten Kontext in LLMs einfügt. Dadurch werden sie von passiven Chatbots zu kontextsensitiven Problemlösern.

Zweiter Platz: MarketMind

Eine in Echtzeit interpretierbare Darstellung der Marktenergie, ermöglicht durch sechs elastische Agenten.

Lesen Sie hier mehr über MarketMind.

MarketMind hat sich seinen Platz verdient, indem es unerfahrenen Händlern eine Plattform bietet, die fragmentierte Marktdaten in klare Echtzeitsignale umwandelt. Anstatt Kursentwicklung, Fundamentaldaten, Stimmung und Volatilität über verschiedene Tools hinweg zu jonglieren, konsolidiert MarketMind all diese Informationen auf einer einzigen Plattform und hilft Händlern so, umsetzbare Erkenntnisse zu gewinnen. Dieses Projekt verwendete beim Erstellen seiner Agenten auch einige komplexe ES|QL-Abfragen.

So funktioniert es:

1. Marktdaten in Echtzeit erfassen

MarketMind bezieht Kursdaten, Fundamentaldaten, Stimmungsanalysen, Volatilitäts- und Risikokennzahlen von Yahoo Finance. Diese Daten werden erfasst und in mehreren Elasticsearch-Indizes organisiert.

2. Sechs spezialisierte Agenten analysieren den Markt.

Jeder mit Agent Builder erstellte Agent konzentriert sich auf eine andere Marktebene. Sie lesen Daten aus einem Elasticsearch-Index, berechnen ihre eigenen domänenspezifischen Metriken und generieren eine standardisierte JSON-Ausgabe mit Bewertungen und Begründungen.

3. Signale in einem einheitlichen „Marktenergie“-Modell aggregieren

Die kombinierten Ergebnisse erscheinen als leuchtende Impulse um jede Aktie herum und veranschaulichen, ob sich die Dynamik verstärkt, das Risiko steigt oder sich die Stimmung ändert.

4. Erkenntnisse visualisieren

Das Frontend wurde mit React und Next.js unter Verwendung von TypeScript, SVG-basierten physikbasierten Visualisierungen und Chart.js für Live-Candlestick-Charts erstellt. Dadurch wird die Rohanalyse in direkt umsetzbares Feedback in Echtzeit umgewandelt.

Weitere interessante Projekte:

Hier sind einige weitere starke Konkurrenten, die Elastic in verschiedenen Teilen ihres Technologie-Stacks eingesetzt haben:

Die vollständige Liste der Projekte, die in unserem Wettbewerb eingereicht wurden, finden Sie hier.

Was wir von Entwicklern gelernt haben

• Agent Builder ist benutzerfreundlich:

Die meisten Teams hatten Elastic noch nie zuvor benutzt und waren dennoch in der Lage, mit wenig Unterstützung schnell Agenten zu erstellen. Wir haben einen Workshop für diejenigen veranstaltet, die mehr Unterstützung benötigten, aber die meisten waren in der Lage, ihre Daten zu erfassen und einen Agenten zu erstellen, der Aktionen auf diesen Daten durchführt.

• LLMs sind hervorragend in kNN -Abfragen, benötigen aber dennoch Unterstützung bei der Generierung von ES|QL:

Die Aufforderung an ChatGPT-5, ES|QL-Abfragen zu generieren, lieferte falsche Informationen, wobei häufig ES|QL und SQL vermischt wurden. Die Bereitstellung der Dokumente in einer Markdown-Datei für das LLM schien eine praktikable Lösung zu sein.

• Nur für Snapshots verfügbare ES|QL-Funktionen in die Dokumentation gelangten:

Die kommenden Aggregationsfunktionen FIRST und LAST sind versehentlich in unsere ES|QL-Dokumentation eingeschlichen. Da wir diese Dokumente an ChatGPT übermittelt haben, nutzte das Modell diese Funktionen pflichtgemäß, obwohl sie in Serverless noch nicht verfügbar sind. Dank des Feedbacks der Gruppe hat das Entwicklungsteam schnell einen Fix erstellt und zusammengeführt, um die Funktionen aus der veröffentlichten Dokumentation zu entfernen (PR #137341).

• Fehlende Serverless-spezifische Anleitung:

Ein Team versuchte, LOOKUP JOIN für einen Index zu aktivieren, der nicht im Lookup-Modus erstellt wurde. Die Fehlermeldung veranlasste sie, Befehle zu verfolgen, die auf Serverless nicht existieren. Wir haben dies dem Produktteam mitgeteilt, das umgehend einen Fix für eine Serverless-spezifische, umsetzbare Fehlermeldung erstellt hat. Längerfristig besteht die Vision darin, die Komplexität der Neuindizierung vollständig zu verbergen (Problem #4838).

• Wert von Präsenzveranstaltungen:

Online-Hackathons sind toll, aber nichts kommt an den schnellen Feedback-Loop heran, den man erhält, wenn man Seite an Seite mit Entwicklern Fehler behebt. Wir haben beobachtet, wie Teams Agent Builder in verschiedenen Anwendungsfällen integriert haben, festgestellt, wo die Entwicklererfahrung mit ES|QL verbessert werden konnte, und Probleme viel schneller behoben, als dies über asynchrone Kanäle zu versuchen.

Fazit

Cal Hacks 12.0 bot uns mehr als ein Wochenende voller cooler Demos; es gab uns auch Einblick in die Art und Weise, wie neue Entwickler mit dem Elastic Stack interagieren. Innerhalb von nur 36 Stunden sahen wir, wie Teams Agent Builder einsetzten, Daten in Elasticsearch einspielten, Multiagentensysteme entwarfen und unsere Funktionen auf vielfältige Weise testeten. Die Veranstaltung erinnerte uns auch daran, warum Präsenzveranstaltungen so wichtig sind. Die schnellen Feedbackschleifen, die echten Gespräche und das praktische Debugging halfen uns, die aktuellen Bedürfnisse der Entwickler zu verstehen. Wir freuen uns darauf, das Gelernte an das Ingenieurteam weiterzugeben. Wir sehen uns beim nächsten Hackathon.

Dies ist der Begleitartikel zum Artikel „Erstellung eines LLM-Agent-Newsrooms mit A2A-Protokoll und MCP in Elasticsearch!“, in dem die Vorteile der Implementierung von A2A- und MCP-Architekturen innerhalb desselben Agenten erläutert wurden, um die einzigartigen Vorteile beider Frameworks voll auszuschöpfen. Ein Repository steht zur Verfügung, falls Sie die Demo selbst ausführen möchten.

Lassen Sie uns gemeinsam durchgehen, wie unsere Redakteure mithilfe von A2A und MCP zusammenarbeiten, um einen Nachrichtenartikel zu erstellen. Das zugehörige Repository, um die Agenten in Aktion zu sehen, finden Sie hier.

Schritt 1: Aufgabenstellung für die Geschichte

Der Nachrichtenchef (in der Rolle des Auftraggebers) vergibt eine Story:

{
  "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"
    }
  }
}

Schritt 2: Der Reporter bittet um Recherche

Der Reporteragent erkennt, dass er Hintergrundinformationen benötigt und delegiert diese über A2A an den Rechercheagenten :

{
  "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"
    }
  }
}

Schritt 3: Der Reporter bittet den Archivar um historischen Kontext.

Der Reporteragent erkennt, dass ein historischer Kontext die Geschichte stärken würde. Es delegiert über A2A an den Archivagenten (basierend auf dem A2A-Agenten von Elastic), um das Elasticsearch-basierte Artikelarchiv des Newsrooms zu durchsuchen:

{
  "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
    }
  }
}

Schritt 4: Der Archivierungsagent verwendet den Elastic A2A-Agenten mit MCP.

Der Archive Agent verwendet den A2A Agent von Elastic, der wiederum MCP nutzt, um auf die Elasticsearch-Tools zuzugreifen. Dies veranschaulicht die Hybridarchitektur, bei der A2A die Zusammenarbeit von Agenten ermöglicht, während MCP den Zugriff auf Werkzeuge bereitstellt:

# 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

Der Archivagent empfängt umfassende historische Daten vom A2A-Agenten von Elastic und sendet sie an den Reporter zurück:

{
  "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
    }
  }
}

Dieser Schritt demonstriert, wie sich der A2A-Agent von Elastic in den Workflow der Nachrichtenredaktion integriert. Der Archive Agent (ein speziell für Redaktionen entwickelter Agent) koordiniert sich mit dem A2A Agent von Elastic (einem Drittanbieter-Spezialisten), um die leistungsstarken Such- und Analysefunktionen von Elasticsearch optimal zu nutzen. Der Elastic-Agent nutzt intern MCP für den Zugriff auf Elasticsearch-Tools, was die klare Trennung zwischen Agentenkoordination (A2A) und Toolzugriff (MCP) verdeutlicht.

Schritt 5: Der Forscher nutzt MCP-Server

Der Forschungsagent greift auf mehrere MCP-Server zu, um Informationen zu sammeln:

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

Schritt 6: Der Forscher übermittelt die Daten an den Reporter.

Der Rechercheagent sendet die umfassenden Rechercheergebnisse über A2A zurück:

{
  "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
    }
  }
}

Schritt 7: Der Reporter schreibt einen Artikel

Der Reporteragent nutzt die Forschungsdaten und seine eigenen LLM-Fähigkeiten, um den Artikel zu schreiben. Beim Schreiben nutzt der Reporter die MCP-Server für Stil und Vorlagen:

# 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

Schritt 8: Geringes Vertrauen löst erneute Recherche aus

Der Reporteragent prüft den Entwurf und stellt fest, dass eine Behauptung nur geringes Vertrauen genießt. Es sendet eine weitere Anfrage an den Forschungsagenten:

{
  "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"
  }
}

Der Forscher überprüft die Behauptung mithilfe von Faktencheck-Servern von MCP und liefert aktualisierte Informationen zurück:

{
  "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"]
      }
    ]
  }
}

Schritt 9: Der Reporter überarbeitet den Text und reicht ihn beim Redakteur ein.

Der Reporter integriert die verifizierten Fakten und sendet den fertigen Entwurf per A2A an den Redaktionsagenten :

{
  "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
    }
  }
}

Schritt 10: Redaktionelle Überprüfungen mithilfe von MCP-Tools

Der Redaktionsagent nutzt mehrere MCP-Server zur Überprüfung des Artikels:

# 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

Der Redakteur genehmigt den Artikel und leitet ihn weiter:

{
  "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]"
  }
}

Schritt 11: Der Herausgeber veröffentlicht über CI/CD

Schließlich veröffentlicht der Druckeragent den genehmigten Artikel mithilfe der MCP-Server für die CMS- und CI/CD-Pipeline:

# 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"]
    }

Der Verlag bestätigt die Veröffentlichung 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
    }
  }
}

Hier ist die vollständige Abfolge des A2A-Workflows im zugehörigen Repository unter Verwendung der oben beschriebenen Agenten.

Fazit

Sowohl A2A als auch MCP spielen eine wichtige Rolle im modernen erweiterten LLM-Infrastrukturparadigma. A2A bietet Flexibilität für komplexe Multiagentensysteme, jedoch potenziell geringere Portabilität und höhere operative Komplexität. MCP bietet einen standardisierten Ansatz für die Tool-Integration, der einfacher zu implementieren und zu warten ist, ist jedoch nicht für die Orchestrierung mehrerer Agenten ausgelegt.

Die Wahl ist nicht binär. Wie unser Beispiel aus der Redaktion zeigt, kombinieren die anspruchsvollsten und effektivsten LLM-gestützten Systeme oft beide Ansätze: Agenten koordinieren und spezialisieren sich über A2A-Protokolle, während sie über MCP-Server auf ihre Tools und Ressourcen zugreifen. Diese Hybridarchitektur bietet die organisatorischen Vorteile von Multiagentensystemen sowie die Standardisierungs- und Ökosystemvorteile von MCP. Dies deutet darauf hin, dass möglicherweise gar keine Wahlmöglichkeit besteht: Man könnte einfach beide als Standardansatz verwenden.

Es liegt an Ihnen als Entwickler oder Architekt, die beste Mischung beider Lösungen zu testen und zu ermitteln, um das richtige Ergebnis für Ihren spezifischen Anwendungsfall zu erzielen. Das Verständnis der Stärken, Grenzen und geeigneten Anwendungsbereiche der einzelnen Ansätze ermöglicht es Ihnen, effektivere, wartungsfreundlichere und skalierbare KI-Systeme zu entwickeln.

Egal, ob Sie eine digitale Nachrichtenredaktion, eine Kundenserviceplattform, einen Forschungsassistenten oder eine andere LLM-gestützte Anwendung entwickeln – die sorgfältige Berücksichtigung Ihrer Koordinierungsbedürfnisse (A2A) und Ihrer Anforderungen an den Werkzeugzugriff (MCP) wird Sie auf den Weg zum Erfolg führen.

Weitere Ressourcen

• Elasticsearch Agent Builder: https://www.elastic.co/docs/solutions/search/elastic-agent-builder
• A2A-Spezifikation: https://a2a-protocol.org/latest/specification/
• A2A- und MCP-Integration: https://a2a-protocol.org/latest/topics/a2a-and-mcp/
• Model Context Protocol: https://modelcontextprotocol.io

Die Suche ist nicht tot, sie hat sich nur verlagert.

Wir haben also einen Wandel erlebt: von der primären Suche nach Kontext über ein Textfeld und der Verwendung der zurückgegebenen Informationen (des Kontexts), um die Antworten selbst zu konstruieren, hin zur Verwendung natürlicher Sprache, um einem Agenten mitzuteilen, was wir wollen, und lassen ihn die Antwort automatisch für uns recherchieren und zusammenstellen. Viele in der Tech-Welt verweisen auf diesen Wandel und verkünden, dass „Suche tot ist“ (nun ja, die SEO- und AdWords-Welt verändert sich definitiv: GEO, irgendjemand?), aber die Suche ist für operative Abläufe immer noch absolut entscheidend – sie wird nur heute größtenteils im Verborgenen mithilfe von Tools durchgeführt.

Bisher waren Menschen die Hauptverantwortlichen für die Beurteilung der subjektiven Relevanz: Jeder Nutzer hatte seine eigenen Gründe für die Durchführung der Suche, und seine persönlichen Erfahrungen prägten die relative Genauigkeit der Ergebnisse. Wenn wir darauf vertrauen sollen, dass Agenten zu demselben (oder einem besseren) Schluss kommen können, zu dem wir gekommen wären, müssen wir sicherstellen, dass die Kontextinformationen, auf die sie Zugriff haben, so nah wie möglich an unserer subjektiven Absicht liegen. Wir müssen den Kontext, den wir LLMs bieten, auf dieses Ziel ausrichten!

Kontextgenerierung mit hybrider Suchabfrage

Zur Erinnerung an Teil I: Die Hybridsuche von Elastic kombiniert die Stärken der traditionellen schlüsselwortbasierten Suche (Syntaxflexibilität, Schlüsselwortgenauigkeit und Relevanzbewertung) mit dem semantischen Verständnis der Vektorähnlichkeitssuche und bietet mehrere Reranking-Techniken. Diese Synergie (eine treffendere Verwendung dieses Wortes wurde noch nie gefunden!) ermöglicht hochrelevante Ergebnisse mit Suchanfragen, die wesentlich differenzierter auf die Inhalte abzielen. Es geht nicht nur darum, dass man die subjektive Relevanz als eine der Abrufphasen anwenden kann; es geht vielmehr darum, dass der Abruf in der ersten Phase die Relevanzbewertung zusammen mit all diesen anderen Modi gleichzeitig beinhalten kann.

Überragende Genauigkeit und Effizienz

Die Verwendung einer Datenplattform, die verteilte Suche, Abfrage und Neubewertung als primäre Kontextabfrage-Engine ermöglicht, ist sehr sinnvoll. Sie können eine erweiterte Abfragesyntax verwenden, um die fehlende Komponente der subjektiven Absicht hinzuzufügen und Inhalte herauszufiltern, die vom Wert der zurückgegebenen Kontextinformationen ablenken oder diesen verfälschen könnten. Sie können aus den verfügbaren Syntaxoptionen auswählen oder Modalitäten zu einer einzigen Suche kombinieren, die auf jeden Datentyp auf die für ihn beste Weise abzielt, und diese dann mit Reranking kombinieren/neu anordnen. Sie können die Antwort so filtern, dass sie nur die gewünschten Felder/Werte enthält und überflüssige Daten fernhält. Im Dienste der Agenten ermöglicht diese Targeting-Flexibilität die Entwicklung von Tools, die äußerst präzise beim Abrufen von Kontextinformationen sind.

Kontextverfeinerung (Aggregationen und nicht-inhaltliche Signale)

Aggregationen können besonders nützlich sein, um den Inhalt zu gestalten, den ein Tool im Kontextfenster anzeigt. Aggregationen liefern naturgemäß numerisch basierte Fakten über die Struktur der zurückgegebenen Kontextdaten, was es LLMs erleichtert und genauer macht, darüber zu argumentieren. Da Aggregationen hierarchisch verschachtelt werden können, ist dies eine einfache Möglichkeit, dem LLM mehrstufige Details hinzuzufügen, um ein differenzierteres Verständnis zu erzeugen. Aggregationen können auch bei der Verwaltung der Kontextfenstergröße helfen – Sie können ein Abfrageergebnis von 100.000 Dokumenten leicht auf einige hundert Tokens aggregierter Erkenntnisse reduzieren.

Nicht-inhaltliche Signale sind die in Ihren Daten enthaltenen Indikatoren, die Ihnen ein umfassenderes Bild dessen vermitteln, was Sie betrachten; es handelt sich um zusätzliche Merkmale der Ergebnisse, wie beispielsweise Popularität, Aktualität, geografische Lage, Kategorien, Vielfalt der Anbieter oder Preisklassen. Diese Informationsschnipsel können für den Agenten hilfreich sein, um die Bedeutung des empfangenen Kontextes einzuschätzen. Einige einfache Beispiele veranschaulichen dies am besten:

• Hervorhebung kürzlich veröffentlichter und beliebter Inhalte – Stellen Sie sich vor, Sie verfügen über eine Wissensdatenbank mit Artikeln. Sie möchten Artikel finden, die für die Suchanfrage eines Nutzers relevant sind, aber Sie möchten auch Artikel hervorheben, die sowohl aktuell sind als auch von anderen Nutzern als hilfreich empfunden wurden (z. B. eine hohe Anzahl von „Gefällt mir“-Angaben haben). In diesem Szenario können wir eine Hybridsuche verwenden, um relevante Artikel zu finden und sie dann anhand einer Kombination aus Veröffentlichungsdatum und Popularität neu zu ordnen.
• E-Commerce-Suche mit Umsatz- und Lagerbestandsanpassung – Im E-Commerce-Umfeld möchten Sie Ihren Kunden Produkte anzeigen, die zu ihrem Suchbegriff passen, aber Sie möchten auch Produkte bewerben, die sich gut verkaufen und auf Lager sind. Um Frustration bei den Kunden zu vermeiden, sollten Sie Produkte mit geringem Lagerbestand möglicherweise in der Rangfolge herabstufen.
• Priorisierung von schwerwiegenden Problemen in einem Bugtracker - Für ein Softwareentwicklungsteam ist es bei der Suche nach Problemen entscheidend, dass schwerwiegende, prioritäre und kürzlich aktualisierte Probleme zuerst angezeigt werden. Sie können nicht-signalgebende Kriterien wie „Kritikalität“ und „meistdiskutiert“ verwenden, um verschiedene Faktoren unabhängig voneinander zu gewichten und so sicherzustellen, dass die wichtigsten und am aktivsten diskutierten Themen ganz oben stehen.

Diese und weitere Beispielabfragen finden Sie auf der zugehörigen Inhaltsseite von Elasticsearch Labs.

Sicherheitsdurchsetzung

Ein entscheidender Vorteil der Nutzung einer suchbasierten Geschwindigkeitsschicht wie Elastic für Context Engineering ist ihr integriertes Sicherheitsframework. Die Plattform von Elastic stellt sicher, dass der Kontext, der an agentenbasierte und generative KI-Operationen geliefert wird, sensible, privat gehaltene Informationen durch granulare rollenbasierte Zugriffskontrolle (RBAC) und attributbasierte Zugriffskontrolle (ABAC) respektiert und schützt. Dies bedeutet, dass Anfragen nicht nur effizient bearbeitet werden, sondern dass die Ergebnisse auch nach den spezifischen Berechtigungen des Agenten oder des Benutzers, der die Anfrage initiiert, gefiltert werden.

Die Agenten werden als authentifizierter Benutzer ausgeführt, sodass die Sicherheit implizit durch die in die Plattform integrierten Sicherheitsfunktionen gewährleistet ist:

• Feingranulare Berechtigungen: Definieren Sie den Zugriff auf Dokument-, Feld- oder sogar Begriffsebene und stellen Sie so sicher, dass KI-Agenten nur Daten erhalten, zu deren Einsicht sie berechtigt sind.
• Rollenbasierte Zugriffskontrolle (RBAC): Agenten oder Benutzern werden Rollen zugewiesen, wodurch ihnen basierend auf ihren definierten Verantwortlichkeiten Zugriff auf bestimmte Datensätze oder Funktionalitäten gewährt wird.
• Attributbasierte Zugriffskontrolle (ABAC): Implementieren Sie dynamische Zugriffsrichtlinien basierend auf Attributen der Daten, des Benutzers oder der Umgebung, wodurch eine hochgradig anpassungsfähige und kontextsensitive Sicherheit ermöglicht wird.
• Dokumentenebene-Sicherheit (DLS) und Feldebene-Sicherheit (FLS): Diese Funktionen gewährleisten, dass auch innerhalb eines abgerufenen Dokuments nur autorisierte Abschnitte sichtbar sind, wodurch die Offenlegung sensibler Informationen verhindert wird.
• Integration mit der Unternehmenssicherheit: Nahtlose Integration mit bestehenden Identitätsmanagementsystemen (wie LDAP, SAML, OIDC), um einheitliche Sicherheitsrichtlinien im gesamten Unternehmen durchzusetzen.

Durch die direkte Integration dieser Sicherheitsmaßnahmen in den Kontextabrufmechanismus fungiert Elastic als sicherer Wächter, der sicherstellt, dass KI-Agenten innerhalb definierter Datengrenzen arbeiten, eine unbefugte Datenoffenlegung verhindert und die Einhaltung der Datenschutzbestimmungen gewährleistet. Dies ist von entscheidender Bedeutung für den Aufbau von Vertrauen in agentenbasierte KI-Systeme, die vertrauliche oder geschützte Informationen verarbeiten.

Als zusätzlichen Vorteil verringern Sie durch die Verwendung einer einheitlichen Datengeschwindigkeitsschicht über Ihren Unternehmensdatenquellen die unerwarteten Ad-hoc-Abfragelasten auf diese Repositories, die agentenbasierte Tools erzeugen würden. Sie erhalten einen zentralen Ort, um alles nahezu in Echtzeit zu durchsuchen, und einen Ort, um Sicherheits- und Governance-Kontrollen anzuwenden.

Hybride suchbasierte Tools

Es gibt einige Kernfunktionen (und ständig kommen neue hinzu) der Elastic-Plattform, die das Streben nach Kontextentwicklung enorm beschleunigen. Das Wichtigste hierbei ist, dass die Plattform eine Vielzahl von Möglichkeiten bietet, um Ziele zu erreichen, und die Flexibilität besitzt, Methoden anzupassen, zu verändern und zu erweitern, wenn sich das KI-Ökosystem weiterentwickelt.

Wir stellen Ihnen Agent Builder vor

Elastic Agent Builder ist unser erster Ausflug in die Welt der agentenbasierten KI-Tools, die entwickelt wurden, um mit den Daten zu kommunizieren, die Sie bereits in Elastic speichern. Agent Builder bietet eine Chat-Oberfläche, mit der Benutzer ihre eigenen Agenten und Tools innerhalb von Kibana erstellen und verwalten können. Es verfügt über integrierte MCP- und A2A-Server, programmatische APIs und eine Reihe vorkonfigurierter Systemtools zum Abfragen und Erkunden von Elasticsearch-Indizes sowie zum Generieren von ES|QL-Abfragen aus natürlicher Sprache. Mit Agent Builder können Sie benutzerdefinierte Tools erstellen, die die an den Agenten zurückgegebenen Kontextdaten mithilfe einer ausdrucksstarken ES|QL- Abfragesyntax gezielt ansprechen und formen.

Wie funktioniert die hybride Suche in ES|QL, fragen Sie? Die Kernfunktionalität wird durch die Kombination des Feldtyps semantic_text und der Befehle FORK/FUSE erreicht (FUSE verwendet standardmäßig RRF , um die Ergebnisse der einzelnen Forks zusammenzuführen). Hier ein einfaches Beispiel für eine fiktive Produktsuche:

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

Die EVAL- Klausel, die in jedem der FORK-Zweige im obigen Beispiel enthalten ist, ist nicht unbedingt notwendig; sie dient lediglich dazu, zu veranschaulichen, wie Sie nachverfolgen können, aus welcher Suchmodalität ein bestimmtes Ergebnis zurückgegeben wurde.

Suchvorlagen

Angenommen, Sie möchten Ihre eigenen externen Agenten-Tools auf Ihre Elastic-Bereitstellung verweisen. Anstelle von ES|QL möchten Sie mehrstufige Retriever verwenden oder eine bereits entwickelte DSL-Syntax wiederverwenden und außerdem die Eingaben, die die Abfrage akzeptiert, die Syntax, die zur Ausführung der Suche verwendet wird, und die in der Ausgabe zurückgegebenen Felder steuern können. Suchvorlagen ermöglichen es Benutzern, vordefinierte Strukturen für häufige Suchmuster festzulegen, wodurch die Effizienz und Konsistenz beim Abrufen von Daten verbessert wird. Dies ist besonders vorteilhaft für agentenbasierte Tools, die mit Such-APIs interagieren, da sie dazu beitragen, Boilerplate-Code zu standardisieren und eine schnellere Iteration der Suchlogik zu ermöglichen. Und falls Sie jemals einen dieser Faktoren anpassen müssen, aktualisieren Sie einfach die Suchvorlage und voilà, die Änderungen werden übernommen. Wenn Sie ein Beispiel für die Verwendung von Suchvorlagen mit agentenbasierten Tools suchen, schauen Sie sich den Blog von Elasticsearch Labs an: „MCP für intelligente Suche “. Dort wird eine Suchvorlage hinter einem Tool-Aufruf von einem externen MCP-Server verwendet.

Integrierte Arbeitsabläufe (FTW!)

Eine der größten Herausforderungen in unserer neuen Welt der agentenbasierten KI ist die nicht-deterministische Natur von semi-autonomen, selbstgesteuerten „denkenden“ Agenten. Kontextgestaltung ist eine entscheidende Disziplin für agentenbasierte KI: Es handelt sich um Techniken, die dazu beitragen, die möglichen Schlussfolgerungen, die unser Agent generieren kann, auf das einzugrenzen, was wir als Wahrheit kennen. Selbst bei einem hochpräzisen und relevanten Kontextfenster (wenn wir den Bereich numerischer Fakten verlassen) fehlt uns immer noch die Gewissheit, dass die Reaktion des Agenten vollständig wiederholbar und verlässlich ist.

Wenn Sie dieselbe Anfrage mehrmals an einen Agenten senden, können die Antworten im Wesentlichen gleich sein, wobei sich lediglich die Antwort geringfügig unterscheidet. Das ist in der Regel für einfache Abfragen ausreichend, vielleicht kaum wahrnehmbar, und wir können versuchen, die Ausgabe mithilfe von Kontextmanipulationstechniken zu gestalten. Doch je komplexer die Aufgaben werden, die wir unseren Agenten stellen, desto größer ist die Wahrscheinlichkeit, dass eine oder mehrere Teilaufgaben eine Abweichung hervorrufen, die das Endergebnis geringfügig verändert. Es wird wahrscheinlich noch schlimmer werden, wenn wir uns stärker auf die Kommunikation zwischen den Agenten verlassen, und diese Abweichungen werden sich summieren. Dies unterstreicht erneut die Notwendigkeit, dass die Werkzeuge, mit denen unsere Agenten interagieren, sehr flexibel und genau auf die jeweiligen Kontextdaten abstimmbar sein müssen und dass sie in einem erwarteten Ausgabeformat reagieren sollten. Dies deutet auch darauf hin, dass wir für viele Anwendungsfälle die Interaktion zwischen Agenten und Werkzeugen steuern müssen – hier kommen Workflows ins Spiel!

Elastic wird schon bald vollständig anpassbare Workflows in den Kern der Plattform integrieren. Diese Workflows werden in der Lage sein, bidirektional mit Agenten und Tools zu interagieren, sodass Workflows Agenten und Tools aufrufen können und Agenten und Tools Workflows aufrufen können. Die vollständige Integration dieser Funktionen in dieselbe Such-KI-Plattform, auf der sich all Ihre Daten befinden, wird einen grundlegenden Wandel bewirken; das Potenzial der Arbeitsabläufe ist äußerst spannend! Bald, schon sehr bald!

Elastisch wie die einheitliche Speicherbank

Da Elastic eine verteilte Datenplattform ist, die für die Suche in nahezu Echtzeit konzipiert wurde, übernimmt sie auf natürliche Weise die Langzeitgedächtnisfunktionen für agentenbasierte KI-Systeme. Mit der integrierten Chat-Funktion des Agent Builders bieten wir auch die Möglichkeit, das Kurzzeitgedächtnis und den Chatverlauf zu verfolgen und zu verwalten. Und weil die gesamte Plattform API-first ist, ist es extrem einfach, Elastic als Plattform zu nutzen, um die Kontextausgabe eines Tools zu speichern (und später darauf zurückgreifen zu können), die das Kontextfenster des Agenten überfordern könnte; diese Technik wird in Kontext-Engineering-Kreisen manchmal als „ Notizen-Making“ bezeichnet.

Die Kombination von Kurzzeit- und Langzeitgedächtnis auf derselben Suchplattform bietet viele Vorteile: Stellen Sie sich vor, Sie könnten Chatverläufe und gespeicherte Kontextantworten als semantische Einflussfaktoren für zukünftige Chatinteraktionen nutzen, Bedrohungsanalysen durchführen oder persistente Datenprodukte erstellen, die automatisch aus häufig wiederholten Toolaufrufen generiert werden… Die Möglichkeiten sind endlos!

Fazit

Das Aufkommen großer Sprachmodelle hat die Art und Weise verändert, wie wir Inhalte abgleichen und wie wir unsere Daten analysieren. Wir bewegen uns rasant weg von unserer gegenwärtigen Welt, in der Menschen Recherche, Kontextbetrachtung und logisches Denken betreiben, um ihre eigenen Fragen zu beantworten, hin zu einer Welt, in der diese Schritte weitgehend durch agentenbasierte KI automatisiert werden. Damit wir den generierten Antworten vertrauen können, benötigen wir die Gewissheit, dass der Agent bei der Generierung seiner Antwort alle relevanten Informationen (einschließlich des Faktors der subjektiven Relevanz) berücksichtigt hat. Unsere primäre Methode, um agentenbasierte KI vertrauenswürdig zu machen, besteht darin, die Werkzeuge, die zusätzlichen Kontext abrufen, durch RAG- und Kontext-Engineering-Techniken zu verankern. Die Art und Weise, wie diese Werkzeuge den anfänglichen Abruf durchführen, kann jedoch entscheidend für die Genauigkeit der Antwort sein.

Die Elastic Search AI-Plattform bietet die Flexibilität und Vorteile der hybriden Suche sowie zahlreiche integrierte Funktionen, die agentenbasierte KI in Bezug auf Genauigkeit, Leistung und Skalierbarkeit unterstützen; mit anderen Worten: Elastic ist eine fantastische Plattform für verschiedene Aspekte des Kontext-Engineerings! Durch die Standardisierung des Kontextabrufs über eine Suchplattform vereinfachen wir die Funktionsweise von agentenbasierten Werkzeugen in vielerlei Hinsicht – und ähnlich dem Widerspruch „langsamer werden, um schneller zu werden“ bedeutet Einfachheit auf der Ebene der Kontextgenerierung eine schnellere und vertrauenswürdigere agentenbasierte KI.

Eine neue Art der Interaktion mit Daten

Generative KI (genAI) und agentenbasierte KI gehen anders vor als die traditionelle Suche. Während wir früher mit der Informationssuche durch eine Suche begannen („Lass mich das mal googeln…“), erfolgt die erste Aktion sowohl bei generischer KI als auch bei Agenten in der Regel durch die Eingabe von natürlicher Sprache in eine Chat-Oberfläche. Die Chat-Oberfläche ist eine Diskussion mit einem LLM, der sein semantisches Verständnis nutzt, um unsere Frage in eine destillierte Antwort umzuwandeln, eine zusammenfassende Antwort, die scheinbar von einem Orakel stammt, das über ein breites Wissen über alle Arten von Informationen verfügt. Was den LLM wirklich auszeichnet, ist seine Fähigkeit, kohärente, durchdachte Sätze zu formulieren, die die einzelnen Wissensfragmente miteinander verknüpfen – selbst wenn diese ungenau oder völlig realitätsfern sind, steckt doch ein Körnchen Wahrheit darin.

Die alte Suchleiste, mit der wir so vertraut geworden sind, kann man sich als die Ampelmaschine vorstellen, die wir benutzt haben, als wir selbst der denkende Agent waren. Inzwischen wandeln sogar Internet-Suchmaschinen unsere altbekannte, mühsame Suche nach Wörtern in KI-gesteuerte Übersichten um, die die Anfrage mit einer Zusammenfassung der Ergebnisse beantworten und den Nutzern so die Notwendigkeit ersparen, sich durch die einzelnen Ergebnisse zu klicken und diese selbst zu bewerten.

Generative KI & RAG

Generative KI versucht, mithilfe ihres semantischen Verständnisses der Welt die in einer Chatanfrage geäußerte subjektive Absicht zu analysieren und anschließend mithilfe ihrer Schlussfolgerungsfähigkeiten spontan eine Expertenantwort zu erstellen. Eine generative KI-Interaktion besteht aus mehreren Teilen: Sie beginnt mit der Eingabe/Anfrage des Benutzers, frühere Konversationen in der Chat-Sitzung können als zusätzlicher Kontext verwendet werden, und die Anweisung gibt dem LLM vor, wie er argumentieren und welche Verfahren er bei der Erstellung der Antwort befolgen soll. Die Hilfestellungen haben sich von einfachen Erklärungen im Stil von „Erkläre es mir so, als wäre ich fünf Jahre alt“ zu vollständigen Anleitungen für die Bearbeitung von Anfragen weiterentwickelt. Diese Aufschlüsselungen enthalten oft separate Abschnitte, die Details zur Persona/Rolle der KI, zum vor der Generierung stattfindenden Denkprozess/internen Denkprozess, zu objektiven Kriterien, Einschränkungen, zum Ausgabeformat, zur Zielgruppe sowie Beispiele zur Veranschaulichung der zu erwartenden Ergebnisse beschreiben.

Zusätzlich zur Benutzeranfrage und der Systemaufforderung liefert Retrieval Augmented Generation (RAG) weitere Kontextinformationen in einem sogenannten „Kontextfenster“. RAG war eine entscheidende Ergänzung der Architektur; wir nutzen es, um das LLM über die fehlenden Puzzleteile in seinem semantischen Verständnis der Welt zu informieren.

Kontextfenster können ziemlich pingelig sein, wenn es darum geht, was, wo und wie viel man ihnen gibt. Welcher Kontext ausgewählt wird, ist natürlich sehr wichtig, aber auch das Signal-Rausch-Verhältnis des bereitgestellten Kontexts sowie die Länge des Fensters spielen eine Rolle.

Zu wenige Informationen

Werden in einer Abfrage, einer Eingabeaufforderung oder einem Kontextfenster zu wenige Informationen angegeben, kann dies zu Halluzinationen führen, da das LLM den korrekten semantischen Kontext für die Generierung einer Antwort nicht genau bestimmen kann. Es gibt auch Probleme mit der Vektorähnlichkeit der Dokumentabschnittsgrößen – eine kurze, einfache Frage passt möglicherweise nicht semantisch zu den umfangreichen, detaillierten Dokumenten in unseren vektorisierten Wissensdatenbanken. Es wurden Techniken zur Erweiterung von Anfragen entwickelt, wie zum Beispiel Hypothetical Document Embeddings (HyDE) , die LLMs verwenden, um eine hypothetische Antwort zu generieren, die reichhaltiger und ausdrucksstärker ist als die kurze Anfrage. Die Gefahr hierbei ist natürlich, dass das hypothetische Dokument selbst eine Halluzination ist, die den LLM noch weiter vom richtigen Kontext entfernt.

Zu viele Informationen

Genau wie bei uns Menschen kann eine zu große Informationsmenge in einem Kontextfenster auch einen LLM überfordern und verwirren, sodass er nicht mehr weiß, was die wichtigen Teile sein sollen. Kontextüberlauf (oder „ Kontextverfall“) beeinträchtigt die Qualität und Leistung generativer KI-Operationen; er wirkt sich stark auf das „Aufmerksamkeitsbudget“ (das Arbeitsgedächtnis) des LLM aus und verwässert die Relevanz über viele konkurrierende Token hinweg. Zum Konzept der „Kontextverrottung“ gehört auch die Beobachtung, dass LLMs tendenziell eine Positionsverzerrung aufweisen – sie bevorzugen den Inhalt am Anfang oder Ende eines Kontextfensters gegenüber dem Inhalt im mittleren Abschnitt.

Ablenkende oder widersprüchliche Informationen

Je größer das Kontextfenster wird, desto größer ist die Wahrscheinlichkeit, dass es überflüssige oder widersprüchliche Informationen enthält, die das LLM davon ablenken können, den richtigen Kontext auszuwählen und zu verarbeiten. In gewisser Hinsicht wird es zu einem Problem von Müll rein/Müll raus: Wenn man einfach eine Reihe von Dokumentenergebnissen in ein Kontextfenster einfügt, erhält das LLM eine Menge Informationen zum Verarbeiten (möglicherweise zu viele), aber je nachdem, wie der Kontext ausgewählt wurde, besteht eine größere Wahrscheinlichkeit, dass widersprüchliche oder irrelevante Informationen einfließen.

Agentische KI

Ich hatte es Ihnen ja gesagt, es gäbe noch viel zu besprechen, aber wir haben es geschafft – wir sprechen jetzt endlich über agentenbasierte KI-Themen! Agentic AI ist eine sehr spannende neue Anwendung von LLM-Chat-Schnittstellen, die die Fähigkeit generativer KI (können wir sie schon als „Legacy“ bezeichnen?) erweitert, Antworten auf der Grundlage ihres eigenen Wissens und der von Ihnen bereitgestellten Kontextinformationen zu synthetisieren. Mit zunehmender Reife der generativen KI wurde uns bewusst, dass es ein gewisses Maß an Aufgaben und Automatisierung gibt, die LLMs übernehmen können, zunächst beschränkt auf mühsame, risikoarme Tätigkeiten, die leicht von einem Menschen überprüft/validiert werden können. Innerhalb kurzer Zeit erweiterte sich dieser anfängliche Umfang: Ein LLM-Chatfenster kann nun der Funke sein, der einen KI-Agenten dazu veranlasst, autonom zu planen, auszuführen und iterativ zu evaluieren und anzupassen, um sein festgelegtes Ziel zu erreichen. Die Agenten haben Zugriff auf die Schlussfolgerungen ihrer LLMs, den Chatverlauf und das Denkvermögen (sofern vorhanden) und verfügen außerdem über spezielle Werkzeuge, die sie zu diesem Zweck einsetzen können. Wir sehen jetzt auch Architekturen, die es einem übergeordneten Agenten ermöglichen, als Orchestrator mehrerer Unteragenten zu fungieren, von denen jeder über eigene Logikketten, Befehlssätze, Kontext und Werkzeuge verfügt.

Die Agenten sind der Einstiegspunkt in einen weitgehend automatisierten Arbeitsablauf: Sie arbeiten selbstständig, indem sie mit einem Benutzer chatten und dann mithilfe von „Logik“ ermitteln, welche Tools zur Beantwortung der Frage des Benutzers zur Verfügung stehen. Werkzeuge gelten im Vergleich zu Agenten üblicherweise als passiv und sind darauf ausgelegt, nur eine bestimmte Art von Aufgabe zu erfüllen. Die Aufgaben , die ein Tool ausführen kann, sind quasi unbegrenzt (was wirklich spannend ist!), aber eine Hauptaufgabe von Tools besteht darin, Kontextinformationen zu sammeln, die ein Agent bei der Ausführung seines Arbeitsablaufs berücksichtigen kann.

Als Technologie steckt agentenbasierte KI noch in den Kinderschuhen und ist anfällig für das LLM-Äquivalent einer Aufmerksamkeitsdefizitstörung – sie vergisst leicht, was sie tun sollte, und macht oft andere Dinge, die überhaupt nicht Teil der Aufgabenstellung waren. Hinter der scheinbaren Magie verbergen sich die „logischen“ Fähigkeiten von LLMs, die darauf beruhen, das nächste wahrscheinlichste Token in einer Sequenz vorherzusagen. Damit logisches Denken (oder eines Tages künstliche allgemeine Intelligenz (AGI)) zuverlässig und vertrauenswürdig wird, müssen wir überprüfen können, ob es bei der Bereitstellung korrekter und aktueller Informationen so argumentiert, wie wir es erwarten (und uns vielleicht noch das kleine Quäntchen mehr liefert, an das wir selbst nicht gedacht hätten). Damit dies gelingt, benötigen agentenbasierte Architekturen die Fähigkeit, klar zu kommunizieren (Protokolle), sich an die von uns vorgegebenen Arbeitsabläufe und Einschränkungen zu halten (Leitplanken), sich zu merken, wo sie sich in einer Aufgabe befinden (Zustand), ihren verfügbaren Speicherplatz zu verwalten und zu überprüfen, ob ihre Antworten korrekt sind und die Aufgabenkriterien erfüllen.

Sprich mit mir in einer Sprache, die ich verstehen kann.

Wie es in neuen Entwicklungsbereichen üblich ist (insbesondere in der Welt der LLMs), gab es anfänglich eine ganze Reihe von Ansätzen für die Kommunikation zwischen Agent und Werkzeug, aber sie einigten sich schnell auf das Model Context Protocol (MCP) als De-facto-Standard. Die Definition des Model Context Protocol steckt bereits im Namen – es ist das Protokoll, das ein Modell verwendet, um Kontextinformationen anzufordern und zu empfangen. MCP fungiert als universeller Adapter für LLM-Agenten, um Verbindungen zu externen Tools und Datenquellen herzustellen; es vereinfacht und standardisiert die APIs, sodass verschiedene LLM-Frameworks und -Tools problemlos interoperabel sind. Das macht MCP zu einer Art Dreh- und Angelpunkt zwischen der Orchestrierungslogik und den Systemaufforderungen, die einem Agenten zur autonomen Ausführung im Dienste seiner Ziele gegeben werden, und den Operationen, die an Werkzeuge gesendet werden, um sie isolierter auszuführen (zumindest isoliert in Bezug auf den initiierenden Agenten).

Dieses Ökosystem ist so neu, dass sich jede Expansionsrichtung wie ein neues Terrain anfühlt. Wir verfügen über ähnliche Protokolle für Agent-zu-Agent-Interaktionen (Agent2Agent (A2A) natürlich!) sowie über andere Projekte zur Verbesserung des Agenten-Schlussfolgerungsgedächtnisses (ReasoningBank), zur Auswahl des besten MCP-Servers für die jeweilige Aufgabe (RAG-MCP) und zur Verwendung semantischer Analysen wie Zero-Shot-Klassifizierung und Mustererkennung bei Ein- und Ausgaben als Leitplanken , um zu steuern, worauf ein Agent zugreifen darf.

Möglicherweise ist Ihnen aufgefallen, dass das zugrundeliegende Ziel jedes dieser Projekte darin besteht, die Qualität und Kontrolle der Informationen zu verbessern, die an ein Agenten-/genAI-Kontextfenster zurückgegeben werden? Während das agentenbasierte KI-Ökosystem seine Fähigkeit zur besseren Verarbeitung dieser Kontextinformationen stetig weiterentwickelt (um sie zu kontrollieren, zu verwalten und darauf zu reagieren), wird es immer notwendig sein, die relevantesten Kontextinformationen als Grundlage für die Aktionen des Agenten abzurufen.

Willkommen im Kontext-Engineering!

Wer mit Begriffen aus dem Bereich der generativen KI vertraut ist, hat wahrscheinlich schon von „Prompt Engineering“ gehört – mittlerweile ist es fast schon eine eigene Pseudowissenschaft. Prompt Engineering wird eingesetzt, um die besten und effizientesten Wege zu finden, die Verhaltensweisen, die das LLM bei der Generierung seiner Antwort verwenden soll, proaktiv zu beschreiben. „Context Engineering “ erweitert die Techniken des „Prompt Engineering“ über die Agentenseite hinaus und umfasst auch verfügbare Kontextquellen und -systeme auf der Werkzeugseite des MCP-Protokolls sowie die umfassenden Themen Kontextmanagement, -verarbeitung und -generierung:

• Kontextmanagement – Bezieht sich auf die Aufrechterhaltung der Zustands- und Kontexteffizienz in langlaufenden und/oder komplexeren agentenbasierten Arbeitsabläufen. Iterative Planung, Nachverfolgung und Orchestrierung von Aufgaben und Werkzeugaufrufen zur Erreichung der Ziele des Agenten. Da Agenten nur über ein begrenztes „Aufmerksamkeitsbudget“ verfügen, befasst sich das Kontextmanagement hauptsächlich mit Techniken, die dazu beitragen, das Kontextfenster so zu verfeinern, dass sowohl der größtmögliche Umfang als auch die wichtigsten Kontextinformationen erfasst werden (Präzision versus Trefferquote!). Zu den Techniken gehören Komprimierung, Zusammenfassung und Beibehaltung des Kontextes aus vorherigen Schritten oder Werkzeugaufrufen, um im Arbeitsspeicher Platz für zusätzlichen Kontext in nachfolgenden Schritten zu schaffen.
• Kontextverarbeitung – Die logischen und hoffentlich größtenteils programmatischen Schritte zur Integration, Normalisierung oder Verfeinerung des aus unterschiedlichen Quellen gewonnenen Kontextes, damit der Agent den gesamten Kontext auf eine einigermaßen einheitliche Weise verarbeiten kann. Die grundlegende Aufgabe besteht darin, Kontext aus allen Quellen (Eingabeaufforderungen, RAG-System, Speicher usw.) so aufzubereiten, dass er vom Agenten möglichst effizient genutzt werden kann.
• Kontextgenerierung – Wenn es bei der Kontextverarbeitung darum geht, den abgerufenen Kontext für den Agenten nutzbar zu machen, dann gibt die Kontextgenerierung dem Agenten die Möglichkeit, diese zusätzlichen Kontextinformationen nach Belieben, aber auch unter bestimmten Einschränkungen, anzufordern und zu empfangen.

Die verschiedenen Elemente von LLM-Chatanwendungen lassen sich direkt (und manchmal auch überlappend) auf jene übergeordneten Funktionen des Kontextmanagements abbilden:

• Anweisungen / Systemaufforderung - Die Aufforderungen dienen als Gerüst dafür, wie die generative (oder agentenbasierte) KI-Aktivität ihr Denken auf die Erreichung des Ziels des Benutzers ausrichtet. Eingabeaufforderungen stellen einen eigenen Kontext dar; sie sind nicht nur tonale Anweisungen – sie beinhalten häufig auch Logik zur Aufgabenausführung und Regeln für Dinge wie „Schritt für Schritt nachdenken“ oder „tief durchatmen“, bevor man antwortet, um sicherzustellen, dass die Antwort die Anfrage des Benutzers vollständig erfüllt. Jüngste Tests haben gezeigt, dass Auszeichnungssprachen sehr effektiv sind, um die verschiedenen Teile einer Aufgabenstellung zu strukturieren. Es sollte jedoch darauf geachtet werden, die Anweisungen so zu formulieren, dass sie weder zu vage noch zu spezifisch sind; wir wollen dem LLM genügend Anweisungen geben, um den richtigen Kontext zu finden, aber nicht so präskriptiv sein, dass es unerwartete Erkenntnisse verpasst.
• Kurzzeitgedächtnis (Zustand/Verlauf) - Das Kurzzeitgedächtnis umfasst im Wesentlichen die Interaktionen der Chat-Sitzung zwischen dem Benutzer und dem LLM. Diese sind nützlich, um den Kontext in Live-Sitzungen zu verfeinern, und können zur späteren Verwendung und Fortsetzung gespeichert werden.
• Langzeitgedächtnis – Das Langzeitgedächtnis sollte Informationen enthalten, die über mehrere Sitzungen hinweg nützlich sind. Und es geht nicht nur um domänenspezifische Wissensdatenbanken, auf die über RAG zugegriffen wird; neuere Forschungen nutzen die Ergebnisse vorheriger agentischer/generativer KI-Anfragen, um innerhalb aktueller agentischer Interaktionen zu lernen und darauf zu verweisen. Zu den interessantesten Innovationen im Bereich des Langzeitgedächtnisses gehören solche, die die Art und Weise der Speicherung und Verknüpfung von Zuständen so anpassen, dass Agenten dort weitermachen können, wo sie aufgehört haben.
• Strukturierte Ausgabe - Kognition erfordert Anstrengung, daher ist es wohl keine Überraschung, dass LLMs (genau wie Menschen) selbst mit Denkfähigkeiten beim Denken weniger Anstrengung aufwenden wollen, und in Ermangelung einer definierten API oder eines Protokolls ist eine Karte (ein Schema) für das Lesen der von einem Toolaufruf zurückgegebenen Daten äußerst hilfreich. Die Einbeziehung strukturierter Ausgaben in das agentenbasierte Framework trägt dazu bei, diese Interaktionen zwischen Maschinen schneller und zuverlässiger zu gestalten, wodurch weniger gedankengesteuertes Parsen erforderlich wird.
• Verfügbare Tools – Tools können die unterschiedlichsten Aufgaben übernehmen, von der Erfassung zusätzlicher Informationen (z. B. durch Abfragen von Unternehmensdatenbanken mittels RAG-Code oder über Online-APIs) bis hin zur Durchführung automatisierter Aktionen im Auftrag des Agenten (z. B. durch Buchung eines Hotelzimmers auf Basis der Kriterien der Anfrage des Agenten). Werkzeuge könnten auch Unteragenten mit eigenen agentenbasierten Verarbeitungsketten sein.
• Retrieval Augmented Generation (RAG) – Mir gefällt die Beschreibung von RAG als „dynamische Wissensintegration“ sehr gut. Wie bereits erwähnt, ist RAG die Technik, um die zusätzlichen Informationen bereitzustellen, auf die das LLM beim Training keinen Zugriff hatte, oder es ist eine Wiederholung der Ideen, die wir für am wichtigsten halten, um die richtige Antwort zu erhalten – diejenige, die am relevantesten für unsere subjektive Anfrage ist.

Phänomenale kosmische Energie, winziger Wohnraum!

Agentic AI bietet so viele faszinierende und aufregende neue Welten zum Erkunden! Es gibt zwar noch viele der alten, traditionellen Probleme der Datenbeschaffung und -verarbeitung zu lösen, aber auch ganz neue Herausforderungen, die erst jetzt im neuen Zeitalter der LLMs ans Licht der Öffentlichkeit treten. Viele der aktuellen Probleme, mit denen wir uns heute auseinandersetzen, hängen mit Kontextgestaltung zusammen, also damit, wie man Lernlern die zusätzlichen Kontextinformationen bereitstellt, die sie benötigen, ohne ihren begrenzten Arbeitsgedächtnisraum zu überlasten.

Die Flexibilität von halbautonomen Agenten, die Zugriff auf eine Reihe von Werkzeugen (und andere Agenten) haben, führt zu so vielen neuen Ideen für die Implementierung von KI, dass es schwer ist, sich die verschiedenen Möglichkeiten vorzustellen, wie wir die einzelnen Teile zusammensetzen könnten. Der Großteil der aktuellen Forschung fällt in den Bereich des Kontext-Engineerings und konzentriert sich auf den Aufbau von Speichermanagementstrukturen, die größere Mengen an Kontext verarbeiten und verfolgen können – denn die tiefgründigen Denkprobleme, die wir mit LLMs lösen wollen, weisen eine erhöhte Komplexität und länger andauernde, mehrphasige Denkprozesse auf, bei denen das Erinnern von extrem großer Bedeutung ist.

Viele der laufenden Experimente auf diesem Gebiet versuchen, die optimale Aufgabenverwaltung und Werkzeugkonfigurationen zu finden, um den agentenbasierten Schlund zu füttern. Jeder Werkzeugaufruf in der Argumentationskette eines Agenten verursacht kumulative Kosten, sowohl hinsichtlich des Rechenaufwands zur Ausführung der Funktion dieses Werkzeugs als auch der Auswirkungen auf das begrenzte Kontextfenster. Einige der neuesten Techniken zur Kontextverwaltung für LLM-Agenten haben unbeabsichtigte Ketteneffekte wie den „ Kontextkollaps“ verursacht, bei dem die Komprimierung/Zusammenfassung des akkumulierten Kontexts für langlaufende Aufgaben zu verlustbehaftet wird. Das angestrebte Ergebnis sind Werkzeuge, die einen prägnanten und genauen Kontext liefern, ohne dass überflüssige Informationen in den wertvollen Speicherplatz des Kontextfensters eindringen.

So viele/zu viele Möglichkeiten

Wir wollen eine klare Aufgabentrennung mit der Flexibilität, Werkzeuge/Komponenten wiederzuverwenden. Daher ist es absolut sinnvoll, dedizierte Agentenwerkzeuge für die Verbindung mit bestimmten Datenquellen zu entwickeln – jedes Werkzeug kann sich auf die Abfrage eines bestimmten Repository-Typs, eines bestimmten Datenstroms oder sogar eines bestimmten Anwendungsfalls spezialisieren. Aber Vorsicht: Im Bestreben, Zeit/Geld zu sparen/zu beweisen, dass etwas möglich ist, wird die Versuchung groß sein, LLMs als Instrument der Föderation zu nutzen… Versuchen Sie, das zu vermeiden, wir haben das schon einmal erlebt ! Die föderierte Abfrage fungiert als „universeller Übersetzer“, der eine eingehende Abfrage in die Syntax umwandelt, die das entfernte Repository versteht, und anschließend die Ergebnisse aus mehreren Quellen zu einer kohärenten Antwort zusammenführen muss. Die Federation als Technik funktioniert im kleinen Maßstab ganz gut , aber im großen Maßstab und insbesondere bei multimodalen Daten versucht die Federation, Lücken zu schließen, die einfach zu groß sind.

In der agentenbasierten Welt wäre der Agent der Föderator und die Werkzeuge (über MCP) wären die manuell definierten Verbindungen zu unterschiedlichen Ressourcen. Der Einsatz spezieller Tools zur Erfassung unverbundener Datenquellen mag zwar ein vielversprechender neuer Ansatz sein, um verschiedene Datenströme dynamisch pro Abfrage zu vereinen, doch die Verwendung von Tools, um dieselbe Frage an mehrere Quellen zu stellen, wird wahrscheinlich mehr Probleme verursachen als lösen. Bei jeder dieser Datenquellen handelt es sich wahrscheinlich um einen anderen Typ von Datenspeicher, der jeweils über eigene Funktionen zum Abrufen, Sortieren und Sichern der darin enthaltenen Daten verfügt. Diese Abweichungen oder „Impedanzfehlanpassungen“ zwischen den Repositories erhöhen natürlich die Verarbeitungslast. Außerdem können sie widersprüchliche Informationen oder Signale einbringen, wobei etwas so scheinbar Harmloses wie eine Fehlausrichtung der Bewertung die Bedeutung, die einem Teil des zurückgegebenen Kontextes beigemessen wird, stark beeinträchtigen und letztendlich die Relevanz der generierten Antwort beeinflussen kann.

Auch für Computer ist der Kontextwechsel schwierig.

Wenn man einen Agenten auf eine Mission schickt, besteht seine erste Aufgabe oft darin, alle relevanten Daten zu finden, auf die er Zugriff hat. Genau wie bei Menschen entsteht auch bei uns eine kognitive Belastung, wenn jede Datenquelle, mit der der Agent eine Verbindung herstellt, unterschiedliche und disaggregierte Antworten liefert. Diese Belastung entsteht durch das Herausfiltern der relevanten Kontextinformationen aus den abgerufenen Inhalten. Das braucht Zeit/Rechenleistung, und jedes kleine bisschen summiert sich in der agentenbasierten Logikkette. Daraus lässt sich schließen, dass, ähnlich wie bei MCP, die meisten agentenbasierten Werkzeuge sich eher wie APIs verhalten sollten – isolierte Funktionen mit bekannten Ein- und Ausgaben, die auf die Bedürfnisse verschiedener Agententypen abgestimmt sind. Wir stellen sogar fest, dass LLMs Kontext für Kontext benötigen – sie sind viel besser darin, die semantischen Punkte zu verbinden, insbesondere wenn es um eine Aufgabe wie die Übersetzung von natürlicher Sprache in strukturierte Syntax geht, wenn sie ein Schema haben, auf das sie sich beziehen können (RTFM in der Tat!).

Pause im 7. Inning!

Wir haben nun die Auswirkungen von LLMs auf das Abrufen und Abfragen von Daten sowie die Entwicklung des Chatfensters hin zu einer agentenbasierten KI-Erfahrung behandelt. Lasst uns die beiden Themen miteinander verknüpfen und sehen, wie wir unsere neuartigen Such- und Abruffunktionen nutzen können, um unsere Ergebnisse im Bereich Context Engineering zu verbessern. Weiter zu Teil III: Die Leistungsfähigkeit der hybriden Suche im Kontext-Engineering!

ECK erfordert deutlich mehr Aufwand als die Marketplace-basierten Elastic Cloud-Lösungen, ist aber stärker automatisiert als die manuelle Bereitstellung von VMs, da der Kubernetes-Operator die Systemorchestrierung und die Skalierung der Knoten übernimmt.

Dieses Mal werden wir mit dem Azure Kubernetes Service (AKS) arbeiten und dabei die automatische Methode verwenden. In den anderen Artikeln erfahren Sie, wie Sie Azure VM und Azure Marketplace nutzen.

Was ist AKS Automatic?

Der Azure Kubernetes Service (AKS) verwaltet automatisch die Clusterkonfiguration, weist Ressourcen dynamisch zu und integriert bewährte Sicherheitspraktiken bei gleichzeitiger Beibehaltung der Flexibilität von Kubernetes. Dadurch können Entwickler innerhalb von Minuten vom Container-Image zur bereitgestellten Anwendung gelangen.

AKS Automatic beseitigt den Großteil des Aufwands für die Clusterverwaltung und schafft ein gutes Gleichgewicht zwischen Einfachheit und Flexibilität. Die richtige Wahl hängt von Ihrem Anwendungsfall ab, aber die Entscheidung wird einfacher, wenn Sie Folgendes planen:

• Bereitstellung einer Testumgebung: Die Bereitstellung ist schnell und unkompliziert und eignet sich daher ideal für schnelle Experimente oder kurzlebige Cluster.
• Arbeiten Sie ohne strenge VM-, Speicher- oder Netzwerkanforderungen: AKS Automatic bietet vordefinierte Standardeinstellungen. Wenn diese Ihren Bedürfnissen entsprechen, erspart Ihnen das zusätzliche Konfigurationsaufwand.
• So starten Sie zum ersten Mal mit Kubernetes: AKS Automatic übernimmt einen Großteil der Cluster-Einrichtung, senkt die Lernkurve und ermöglicht es Teams, sich auf ihre Anwendungen zu konzentrieren.

Für Elasticsearch werden wir Elastic Cloud on Kubernetes (ECK) verwenden, den offiziellen Elastic Kubernetes Operator, der die Orchestrierung von Kubernetes-Bereitstellungen des Elastic Stack vereinfacht.

So richten Sie AKS Automatic ein

1. Melden Sie sich beim Microsoft Azure Portal an.

2. Klicken Sie oben rechts. Klicken Sie auf die Schaltfläche „Cloud Shell“ , um auf die Konsole zuzugreifen und den AKS-Cluster von dort aus bereitzustellen. Alternativ können Sie die Azure Cloud Shell verwenden.

Denken Sie daran, die Projekt-ID während des Tutorials durch Ihre eigene zu ersetzen.

Das Öffnen des AKS sollte wie im obigen Screenshot aussehen.

3. Installieren Sie die Azure CLI-Erweiterung aks-preview. Diese Vorabversion ermöglicht es uns, bei der Clustererstellung --sku automatic auszuwählen, wodurch die AKS-Automatikfunktion aktiviert wird.

az extension add --name aks-preview

Wenn Sie diese Meldung sehen, bedeutet dies, dass die AKS-Erweiterung ordnungsgemäß installiert wurde.

4. Registrieren Sie Feature-Flags mit dem Befehl az feature register

az feature register --namespace Microsoft.ContainerService --name AutomaticSKUPreview

Sie sehen nun die Details zu dem soeben erstellten Funktionsabonnement:

Überprüfen Sie den Registrierungsstatus, bis er sich von „ Registrierung läuft“ in „ Registriert“ ändert. Die Registrierung kann einige Minuten dauern.

az feature show --namespace Microsoft.ContainerService --name AutomaticSKUPreview

Führen Sie az provider register aus, um die Änderungen zu verbreiten.

az provider register --namespace Microsoft.ContainerService

5. Erstellen Sie eine Ressourcengruppe

Eine Ressourcengruppe ist eine logische Gruppe von Azure-Ressourcen, die verwaltet und bereitgestellt werden sollen.

az group create --name elastic-resource --location eastus

6. Erstellen Sie einen Autopilot-Cluster. Wir werden es myAKSAutomaticCluster nennen und die soeben erstellte Ressourcengruppe verwenden. Stellen Sie sicher, dass auf einer der folgenden VM-Größen 16 vCPUs verfügbar sind: Standard_D4pds_v5, Standard_D4lds_v5, Standard_D4ads_v5, Standard_D4ds_v5, Standard_D4d_v5, Standard_D4d_v4, Standard_DS3_v2, Standard_DS12_v2, damit AKS Ressourcen zuweisen kann.

az aks create \
    --resource-group elastic-resource \
    --name myAKSAutomaticCluster \
    --sku automatic \
    --generate-ssh-keys

* FallsMissingSubscriptionRegistration-Fehler auftreten , gehen Sie mit den fehlenden Abonnements zurück zu Schritt 4. Beispielsweise erfordert The subscription is not registered to use namespace 'microsoft.insights'die Ausführung vonaz provider register --namespace Microsoft.Insights.

Folgen Sie dem interaktiven Login:

Es erscheint eine Meldung mit der Aufforderung, „az login“ auszuführen. Sie müssen diesen Befehl ausführen und dann warten.

7. Warten Sie, bis es fertig ist. Die Erstellung dauert etwa 10 Minuten.

8. Konfigurieren Sie den Zugriff auf die kubectl-Befehlszeile.

az aks get-credentials --resource-group elastic-resource --name myAKSAutomaticCluster

Beachten Sie, dass die von uns installierte Erweiterung AKS Automatic aktiviert.

9. Bestätigen Sie, dass die Knoten bereitgestellt wurden.

kubectl get nodes

Es wird eine Fehlermeldung angezeigt, die den Zugriff verweigert. Kopieren Sie die Benutzer-ID aus der Fehlermeldung.

10. Fügen Sie Ihren Benutzer zur AKS-Zugriffskontrolle hinzu.

AKS-ID abrufen. Kopiere die Ausgabe des Befehls.

az aks show --resource-group elastic-resource  --name myAKSAutomaticCluster --query id --output tsv

Erstellen Sie eine Rollenzuweisung mithilfe der AKS-ID und der Principal-ID Ihres Benutzers.

az role assignment create --role "Azure Kubernetes Service RBAC Cluster Admin" --assignee  --scope 

11. Versuchen Sie erneut zu überprüfen, ob die Knoten bereitgestellt wurden.

kubectl get nodes

12. Installieren Sie den Elastic Cloud on the Kubernetes (ECK)-Operator.

# 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. Wir erstellen eine Elasticsearch-Instanz mit einem einzelnen Knoten und den Standardwerten.

cat <

Wir haben nmap deaktiviert, da die Standard-AKS-Maschine einen zu niedrigen Wert für vm.max_map_count hat. Für den Produktivbetrieb wird von einer Deaktivierung abgeraten, stattdessen sollte der Wert von vm.max_map_count erhöht werden. Mehr dazu können Sie hier nachlesen.

14. Wir werden auch einen Kibana-Einzelknotencluster bereitstellen. Für Kibana werden wir einen Load Balancer hinzufügen, der uns eine externe IP-Adresse bereitstellt, über die wir Kibana von unserem Gerät aus erreichen können.

cat <

Standardmäßig konfiguriert AKS Automatic den Load Balancer als öffentlich; Sie können dieses Verhalten ändern, indem Sie die Metadaten-Annotation festlegen:

service.beta.kubernetes.io/azure-load-balancer-internal: "true"

15. Überprüfen Sie, ob Ihre Pods ausgeführt werden.

kubectl get pods

16. Sie können auch kubectl get elasticsearch und kubectl get kibana ausführen, um spezifischere Statistiken wie Elasticsearch-Version, Knoten und Zustand zu erhalten.

17. Greifen Sie auf Ihre Dienste zu.

kubectl get svc

Hier wird Ihnen die externe URL für Kibana unter EXTERNAL-IP angezeigt. Es kann einige Minuten dauern, bis der Load Balancer bereitgestellt ist. Kopieren Sie den Wert von EXTERNAL-IP.

18. Ermitteln Sie das Elasticsearch-Passwort für den Benutzer „elastic“:

kubectl get secret quickstart-es-elastic-user -o=jsonpath='{.data.elastic}' | base64 --decode

19. Greifen Sie über Ihren Browser auf Kibana zu :

a. URL: https://:5601<EXTERNAL_IP>

b. Benutzername:elastic

c. Passwort:c44A295CaEt44D6xIzN6Zs5m (aus dem vorherigen Schritt)

20. Wenn Sie Elastic Cloud über Ihren Browser aufrufen, wird Ihnen der Begrüßungsbildschirm angezeigt.

Wenn Sie die Spezifikationen des Elasticsearch-Clusters ändern möchten, z. B. die Anzahl oder Größe der Knoten anpassen, können Sie das YML-Manifest mit den neuen Einstellungen erneut anwenden:

cat <

In diesem Beispiel fügen wir einen weiteren Knoten hinzu und modifizieren RAM und CPU. Wie Sie sehen können, zeigt kubectl get elasticsearch jetzt 2 Knoten an:

Das Gleiche gilt für Kibana:

cat <

Wir können die CPU/RAM-Auslastung des Containers sowie die Speichernutzung von Node.js (max-old-space-size) anpassen.

Beachten Sie, dass bestehende Volumenansprüche nicht reduziert werden können. Nach der Installation des Updates kann der Betreiber die Änderungen mit minimalen Unterbrechungszeiten vornehmen.

Denken Sie daran, den Cluster nach Abschluss der Tests zu löschen, um unnötige Kosten zu vermeiden.

az aks delete --name myAKSAutomaticCluster --resource-group elastic-resource

Fazit

Die Verwendung von Azure AKS Automatic mit ECK bietet eine ausgewogene Lösung für die Bereitstellung von Elasticsearch und Kibana: Sie reduziert die operative Komplexität, gewährleistet automatisierte Skalierung und Aktualisierungen und nutzt die Flexibilität von Kubernetes. Dieser Ansatz ist ideal für Teams, die einen zuverlässigen, wiederholbaren und wartungsfreundlichen Bereitstellungsprozess wünschen, ohne jedes Infrastrukturdetail manuell verwalten zu müssen. Daher ist er eine praktische Wahl sowohl für Test- als auch für Produktionsumgebungen.

Wie geht es weiter?

Wenn Sie mehr über Kubernetes erfahren möchten, können Sie die offizielle Dokumentation hier einsehen:

• Elastic Cloud auf Kubernetes | Elastic Docs
• Einführung in Azure Kubernetes Service (AKS) Automatisch (Vorschau)
• AKS Automatic – AKS Engineering Blog

]]>