Langfuse: Ihre lokalen LLMs überwachen (Traces, Prompts, Evaluationen)

#Warum ein lokales LLM beobachten?

Langfuse ist eine Observability-Plattform für LLM-Anwendungen, deren Hauptrepository unter der MIT-Lizenz steht. Sie lässt sich selbst hosten, damit die Traces Ihrer Gespräche bei Ihnen bleiben. Für jede Anfrage zeichnet sie den tatsächlich an das Modell gesendeten Prompt, die Antwort, die Dauer jedes Schritts und, sofern ein Preis festgelegt ist, die Kosten auf. Damit lässt sich feststellen, warum eine Antwort schlecht ist: eine abgerufene Passage, die am Thema vorbeigeht, ein anderer Prompt als der, den Sie vermutet hatten, oder ein Versagen des Modells. Sie wird nützlich, sobald eine zweite Person auf das Ergebnis angewiesen ist oder die Verarbeitungskette mehrere Schritte umfasst; für die alleinige explorative Nutzung genügt eine Protokolldatei. Rechnen Sie mit einem Stack aus mehreren Containern (Webserver, Worker, PostgreSQL, ClickHouse, Redis, Objektspeicher) und für den Produktionsbetrieb mit Kubernetes statt Docker Compose.

Wenn eine Antwort enttäuscht, kommen drei Ursachen infrage, von denen nur eine ohne Instrumentierung sichtbar ist: Der endgültige Prompt, der an das Modell gesendet wurde, war nicht der, für den Sie ihn hielten, die bei der Dokumentensuche abgerufenen Passagen waren nicht relevant oder das Modell selbst ist gescheitert. Ohne Aufzeichnung ändert man den Prompt aufs Geratewohl, bis es besser wird, ohne jemals zu wissen, warum.

Das Argument gilt lokal genauso wie online, mit einem Unterschied: Die Rechnung dient nicht mehr als Warnsignal. Niemand erhält eine Abrechnung, wenn eine Kette von Agenten auf Ihrer eigenen Grafikkarte in eine Endlosschleife gerät; stattdessen machen sich Latenz und Wärmeentwicklung bemerkbar. Observability ersetzt dieses Preissignal durch Messwerte: Tokenanzahl, Dauer, Fehlerrate, Qualität.

#Was Langfuse protokolliert

Das Projekt beschreibt sich selbst als Open-Source-Plattform für Agentenevaluierung und Observability: LLM-Anwendungen auf einer einzigen offenen Plattform nachverfolgen, evaluieren und verbessern. Seine SDKs für Python (Version 4) und JS/TS (Version 5) basieren auf OpenTelemetry, und auch andere Sprachen können ihre Traces über dieses Protokoll senden. Das Hauptrepository hat mehr als 35.000 Sterne auf GitHub. Laut seinem README gehört Langfuse seit Januar 2026 zu ClickHouse, und ClickHouse ist zugleich die Datenbank, in der die Traces gespeichert werden.

Traces

Der vollständige Ablauf einer Benutzeranfrage: jeder Schritt in der richtigen Reihenfolge mit seiner Dauer. Das ist die Grundeinheit.

Beobachtungen

Innerhalb eines Traces: die Modellaufrufe mit ihrem exakten Prompt und ihrer Antwort, die Schritte zum Abrufen von Dokumenten, die Tool-Aufrufe.

Sitzungen und Benutzer

Die Gruppierung der Protokolldaten je nach Konversation und Benutzer, um einen Nutzungsverlauf anstatt einen isolierten Aufruf zu verfolgen.

Punktzahlen

Eine Bewertung, die einer Trace zugeordnet ist: ein Daumen hoch von einem Benutzer, das Ergebnis einer automatischen Evaluation oder eine manuelle Annotation.

Prompts

Versionierte Prompt-Vorlagen, die die Anwendung zur Laufzeit abruft, statt sie fest im Code zu hinterlegen.

Kosten

Langfuse berechnet Kosten anhand einer Modelldefinition, die jeder Nutzungsart einen Preis zuordnet. Solche Definitionen stellt Langfuse für Modelle von OpenAI, Anthropic und Google bereit. Für ein lokales Modell gibt es keinen Preis, solange Sie keinen hinzufügen: Ohne Definition sollten Sie in der Benutzeroberfläche keine Kosten erwarten, oder Sie legen einen fiktiven Preis fest, um Stromkosten und Abschreibung abzubilden.

#Auf der eigenen Infrastruktur installieren

Langfuse lässt sich mit Docker Compose selbst hosten. Das README nennt einen Start in fünf Minuten; die Bereitstellungsdokumentation rechnet mit zwei bis drei Minuten, bis der Webcontainer „Ready“ anzeigt. Der Stack besteht nicht nur aus einem Container: Er umfasst zwei Anwendungscontainer (den Webserver, der die Benutzeroberfläche und die API bereitstellt, und einen Worker, der Ereignisse asynchron verarbeitet) sowie vier Speicherkomponenten: PostgreSQL für Transaktionsdaten, ClickHouse für Traces, Beobachtungen und Scores, Redis oder Valkey für die Warteschlange und den Cache sowie einen S3-kompatiblen Objektspeicher, der alle eingehenden Ereignisse aufbewahrt. Das ist aufwendiger als ein einfaches Dashboard und ergibt sich aus den Anforderungen: viele Ereignisse aufnehmen, ohne einen Trace zu verlieren, selbst wenn die Datenbank vorübergehend nicht verfügbar ist.

Zwei Einschränkungen sollten Sie kennen, bevor Sie die Software neben einem Modell installieren. Erstens ist Docker Compose laut Dokumentation zum Ausprobieren gedacht: Diese Konfiguration bietet weder Hochverfügbarkeit noch Skalierung noch Backups; für den Produktionsbetrieb empfiehlt die Dokumentation Kubernetes mit Helm. Zweitens empfiehlt sie für eine virtuelle Maschine mindestens 4 Kerne, 16 GiB Arbeitsspeicher und 100 GiB Speicherplatz. Auf einem Rechner, der bereits ein Modell bereitstellt, sind diese Größenordnungen wichtig: Ein Observability-Stack, der einen Teil des für das Modell benötigten Arbeitsspeichers beansprucht, tut dies zum ungünstigsten Zeitpunkt. Ändern Sie schließlich die mit CHANGEME gekennzeichneten Secrets in der Datei docker-compose.yml: Es gibt kein Standardkonto; das erste Benutzerkonto wird über die Schaltfläche Sign up unter http://localhost:3000 erstellt.

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# Éditer docker-compose.yml : remplacer chaque secret marqué CHANGEME
docker compose up
# Après 2 à 3 minutes, le conteneur web affiche « Ready » : ouvrir http://localhost:3000

#An Ollama oder vLLM anbinden

Langfuse ist kein Inferenzserver und schaltet sich nicht in den Datenverkehr ein: Ihre Anwendung sendet die Traces an Langfuse. Das Projekt dokumentiert drei konkrete Wege, je nachdem, wie Sie Ihr Modell aufrufen, sowie eine eigene Seite zu Ollama, deren Beispiel das OpenAI-SDK verwendet: Ollama stellt unter http://localhost:11434/v1 eine OpenAI-kompatible API bereit, und Langfuse bietet einen direkten Ersatz für dieses SDK, bei dem lediglich der Import geändert werden muss. Auch für vLLM gibt es eine Seite.

1. 01
   Über das SDK in Ihrem Code

   Sie dekorieren die Funktionen, die den Modellaufruf auslösen. Dies ist der klarste und genaueste Ansatz, da Sie bestimmen, was aufgezeichnet wird.
2. 02
   Durch eine Framework-Integration

   Eine automatische Instrumentierung ist für einen direkten Ersatz des OpenAI-SDK, für einen an eine LangChain-Anwendung angebundenen Callback-Handler und für das Callback-System von LlamaIndex verfügbar: Die Traces werden übertragen, ohne die Geschäftslogik zu ändern.
3. 03
   Über ein API-Gateway

   Wenn Ihre Anfragen bereits über einen OpenAI-kompatiblen Router geleitet werden, erfolgt die Instrumentierung auf dieser Ebene und deckt alle Anwendungen gleichzeitig ab.

In allen drei Fällen müssen Sie prüfen, ob der tatsächlich übermittelte Prompt aufgezeichnet wird und nicht nur die Frage des Benutzers: Genau der Unterschied zwischen beiden erklärt die meisten schlechten Antworten eines Systems zur Dokumentensuche. Mit Ollama setzt die unten gezeigte Konfiguration LANGFUSE_BASE_URL auf Ihre selbst gehostete Instanz (http://localhost:3000) und definiert Ihren öffentlichen und Ihren geheimen Schlüssel als Umgebungsvariablen.

# pip install langfuse openai
# Variables d'environnement : LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY,
# LANGFUSE_BASE_URL=http://localhost:3000
from langfuse.openai import OpenAI  # remplace : from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # requis mais inutilisé
)
reponse = client.chat.completions.create(
    model='llama3.1',
    messages=[{'role': 'user', 'content': 'Bonjour !'}],
)

• API-Aufrufe über ein OpenAI-kompatibles Gateway zentralisieren
• vLLM bereitstellen, um mehrere Benutzer zu bedienen
• Ollama aus Python aufrufen
• Ragas: ein lokales RAG anhand von Zahlen bewerten
• Quelle: Details zu SDK-, Framework- und Gateway-Integrationen

#Prompts verwalten und versionieren

Prompts aus dem Code auszulagern ist der Vorteil, den Teams zuerst bemerken. Laut README ermöglicht ein robuster Cache auf Server- und Clientseite, Prompts schrittweise zu überarbeiten, ohne die Latenz der Anwendung zu erhöhen. Die Vorlage liegt in Langfuse, die Anwendung ruft sie zur Laufzeit ab, und jede Änderung erzeugt eine Version. Eine Formulierung zu korrigieren erfordert keine erneute Bereitstellung mehr. Vor allem zeigt der Trace, welche Version welche Antwort erzeugt hat: Wenn die Qualität nach einer Änderung sinkt, weiß man, welche Änderung dafür verantwortlich ist, ohne separate Bereitstellungsprotokolle miteinander abgleichen zu müssen.

#Testdatensätze und Bewertung

Traces aus dem tatsächlichen Betrieb fließen in Testdatensätze ein: Sie markieren interessante Fälle – vor allem Fehlschläge –, und diese bilden eine Sammlung, anhand derer Sie eine neue Prompt-Version oder ein anderes Modell erneut testen können. So lässt sich die Frage „Reicht das Modell mit 14 Milliarden Parametern aus?“ fundiert beantworten, statt nur darüber zu diskutieren.

Die Bewertungen stammen aus verschiedenen Quellen: von Nutzern, aus menschlichen Annotationen in der Benutzeroberfläche, von codebasierten Evaluatoren oder von einem Modell, das die Antwort eines anderen anhand eines Bewertungsrasters beurteilt — die sogenannte LLM-as-a-judge-Methode, die Langfuse nativ unterstützt. Für den letzten Fall muss eine LLM-Verbindung eingerichtet werden. Laut Dokumentation eignet sich jedes Modell, das dem Schema der OpenAI-API folgt, wenn die Basis-URL entsprechend ersetzt wird: Ein lokales Modell, das über Ollama bereitgestellt wird, kann daher als Bewerter dienen, sofern seine Adresse vom Langfuse-Container aus erreichbar ist. Die Methode ist nützlich und weist Verzerrungen auf: Die Autoren des Referenzartikels zu diesem Thema (arXiv 2306.05685) beschreiben Verzerrungen durch die Position, die Ausführlichkeit und die Bevorzugung eigener Antworten. Zugleich messen sie eine Übereinstimmung von über 80 % zwischen einem Bewerter vom Typ GPT-4 und menschlichen Präferenzen. Die Methode dient dazu, zwei Versionen zu vergleichen, nicht dazu, eine absolute Note zu vergeben.

Ein auf die Bewertung von RAG spezialisiertes Werkzeug wie Ragas ergänzt Langfuse, statt es zu ersetzen: Langfuse erfasst den Trace und speichert den Score, Ragas berechnet spezifische Metriken – Kontexttreue und Relevanz der Antwort –, die Langfuse anschließend wie jeden anderen einem Trace zugeordneten Score anzeigen kann.

#Konkrete Anwendungsfälle

Support-Assistent mit RAG

Eine Antwort, die am Thema vorbeigeht, lässt sich anhand des Traces nachvollziehen: War die abgerufene Passage relevant, oder hat das Modell eine korrekte Passage ignoriert? Der Trace zeigt, welche der beiden Hypothesen zutrifft.

Agent, der Tools aufruft

Bei einer Kette mit mehreren Schritten — Recherche, Berechnung, Texterstellung — zeigt der Trace, welcher Schritt fehlgeschlagen ist, statt Sie bei einem Fehlschlag der gesamten Kette ohne Details im Unklaren zu lassen.

Vergleich zweier Modelle vor der Entscheidung

Denselben Testsatz zuerst mit einem Modell mit 8 Milliarden und dann mit einem Modell mit 27 Milliarden Parametern erneut durchlaufen zu lassen, liefert einen Qualitätswert und eine Laufzeit statt eines bloßen Eindrucks.

Überwachung einer Regression nach einem Update

Ein Versionswechsel von Prompt oder Modell, der die Qualität verschlechtert, wird in den aggregierten Bewertungen sichtbar, bevor ein Benutzer sich darüber beschwert.

Diese Fälle haben eines gemeinsam: Keiner lässt sich durch erneutes Lesen des Codes lösen. Die Ursache einer schlechten Antwort liegt in den Daten, die verarbeitet wurden – dem exakten Prompt, den abgerufenen Passagen und der erzeugten Antwort. Diese Daten sind nirgendwo sonst vorhanden, wenn sie nicht zum Zeitpunkt des Aufrufs aufgezeichnet wurden. Genau das spricht dafür, Observability schon vor der Inbetriebnahme einzurichten, statt erst nach dem ersten Vorfall.

#Was es kostet und was es nicht tut

Das macht ein Modell nicht besser

Die Beobachtbarkeit misst, sie korrigiert jedoch nichts. Sie zeigt Ihnen, wo Sie suchen sollten.

Das speichert Ihre Chats

Auch beim Self-Hosting werden die Inhalte der Prompts auf dem Datenträger gespeichert, und ohne eine Aufbewahrungsrichtlinie (eine Funktion der Enterprise-Edition) bleiben die Daten unbegrenzt gespeichert. Die SDKs bieten dagegen Maskierungsfunktionen (Masking), um sensible Daten vor dem Versand der Traces zu entfernen.

Dieser Stack muss gewartet werden

Backups, Updates, Migrationen: Die Dokumentation weist selbst darauf hin, dass Docker Compose keine Backup-Funktion bietet. Für persönliche Experimente ist dieser Aufwand unverhältnismäßig.

Oft kommt das erst spät

Der richtige Zeitpunkt für die Installation ist vor der Inbetriebnahme, nicht erst nach dem ersten unbemerkten Ausfall.

• Quelle: offizielles Langfuse-Repository auf GitHub
• Quelle: offizielles Ragas-Repository zur Bewertung von RAG

#FAQ