Wie man eine Rag-Pipeline mit Langfuse aufbaut (Schritt für Schritt)

Wie Langfuse einen funktionierenden RAG-Pipeline mit echten Daten aufbaut

Wenn Sie wie ich sind, haben Sie genug von diesen Tutorials zu RAG-Pipelines (Retrieval-Augmented Generation), die nach einem simplen Beispiel mit sauberem Text oder perfekt formatierten PDFs enden. Stattdessen werde ich Ihnen zeigen, wie langfuse einen RAG-Pipeline aufbaut, die mit echten und unordentlichen Datenquellen arbeitet und dabei die wichtigsten Aspekte für die Produktion im Blick behält: Beobachtbarkeit, Debugging und Zuverlässigkeit.

Ich habe verschiedene Bibliotheken und Frameworks getestet, und das Ergebnis ist: Langfuse übertrifft derzeit bei Weitem seine eigene Ausgangslage, wenn es darum geht, RAG-Pipelines zu erstellen und zu überwachen. Es geht nicht nur darum, Abruf und Generierung zu verbinden; es geht darum, jede Interaktion nachzuvollziehen, damit Sie nicht in die Verzweiflung geraten, wenn Ihre Pipeline plötzlich wertlose Ergebnisse zurückliefert.

Langfuse/langfuse hat derzeit 23.484 Sterne und 2.377 Forks auf GitHub, was ein echtes Interesse der Community und aktive Entwicklungsarbeit zeigt. Trotz 588 offenen Problemen am 20. März 2026 ist es ein Projekt, in das es sich lohnt, Zeit zu investieren – vor allem, weil es häufig aktualisiert wird (letztes Update am 20.03.2026), und seine NOASSERTION-Lizenz erleichtert die Einführung.

Voraussetzungen

• Python 3.11 oder höher (das ist nicht verhandelbar – die neuesten Features und die Leistung sind entscheidend)
• pip install langchain >= 0.2.0 (einige Langfuse-Integrationen erfordern die neuesten Updates von Langchain)
• Zugang zu einer Vektor-Datenbank (Pinecone, Weaviate, FAISS oder Chroma; ich werde FAISS der Einfachheit halber vorführen)
• Ein OpenAI-API-Schlüssel oder gleichwertig (für LLM-Aufrufe)
• Docker installiert (optional, aber dringend empfohlen für die Einrichtung eines lokalen Langfuse-Servers)
• Grundkenntnisse in asynchroner Programmierung und REST-APIs (der Langfuse-Client nutzt asynchrone Aufrufe)

Schritt für Schritt: Aufbau der RAG-Pipeline mit Langfuse

Schritt 1: Langfuse-Server einrichten (lokal oder SaaS)

# Der schnellste Weg, um einen Langfuse-Server lokal zu bekommen, ist über Docker:

docker run -d -p 4200:4200 langfuse/langfuse:latest

# Navigieren Sie dann zu http://localhost:4200 und erstellen Sie Ihr Projekt sowie Ihre API-Schlüssel.

Warum sich die Mühe machen, den Langfuse-Server lokal zu betreiben? Weil Sie Ihre Pipeline mit vollständiger Beobachtbarkeit für jeden LLM-Aufruf und jedes Retrieving testen möchten. Auch wenn Sie das Cloud-Angebot von Langfuse nutzen können, gibt Ihnen das lokale Deployment die volle Kontrolle für Entwicklung und Debugging.

Typische Probleme: Docker könnte sich über Portkonflikte beschweren. Wenn Sie Fehler sehen, prüfen Sie, was sonst noch auf Port 4200 läuft mit lsof -i :4200 und beenden Sie den Übeltäter. Wenn Ihr System Windows ist, seien Sie vorbereitet – die Integration der Docker-Linux-VM kann launisch sein. Verwenden Sie bei Bedarf WSL 2.

Schritt 2: Python-Abhängigkeiten installieren

pip install langchain==0.2.5 langfuse openai faiss-cpu

Warum Langchain explizit festlegen? Weil Langfuse in das Erinnerungs-System von Langchain integriert ist, und Versionskonflikte zu stillen Fehlern oder seltsamen Bugs führen. Ich habe das am eigenen Leib erfahren – ich habe einen Nachmittag damit verbracht, herauszufinden, warum Langfuse meine LLM-Aufrufe nicht verfolgt hat, bis ich die Version von Langchain synchronisiert habe.

Schritt 3: Langfuse-Client initialisieren und Ihren API-Schlüssel einrichten

from langfuse.client import LangfuseClient

# Ersetzen Sie YOUR_LANGFUSE_API_KEY durch Ihren tatsächlichen Schlüssel vom Langfuse-Server
lf = LangfuseClient(api_key="YOUR_LANGFUSE_API_KEY", api_url="http://localhost:4200/api")

# Erstellen Sie ein Projekt und eine Umgebung im Langfuse-Dashboard und definieren Sie dann hier:
project_name = "mein-rag-projekt"
environment = "dev"

Langfuse verwendet ein klares Projekt-/Umgebungsmodell, damit Sie die Protokolle für Entwicklung, Staging und Produktion isolieren können. Stellen Sie sicher, dass Ihre API-Schlüssel sicher sind – überprüfen Sie sie nicht in Git!

Schritt 4: Dokumente mit FAISS laden und indizieren

from langchain.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.vectorstores import FAISS
from langchain.embeddings import OpenAIEmbeddings

# Laden Sie Ihre Dokumente – hier ist der Deal: Unordentlicher PDF-Text oder große Artikel können sich möglicherweise nicht richtig aufteilen.
loader = TextLoader("./data/messy_docs.txt")
documents = loader.load()

# Teilen Sie den Text in Stücke für die Embedding
text_splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
docs_split = text_splitter.split_documents(documents)

# Initialisieren Sie die Embeddings
embeddings = OpenAIEmbeddings(openai_api_key="YOUR_OPENAI_KEY")

# Erstellen Sie den Vektorspeicher
vector_store = FAISS.from_documents(docs_split, embeddings)

Warum auf diese Weise teilen? Wenn Ihre Stücke zu lang sind, leidet die Abrufleistung. Die Überlappung hilft, den Kontext zu bewahren, aber zu viel ist kostspielig. Verlassen Sie sich nicht blind auf Tutorials, die sagen „Chunk-Größe 1000“ – ich habe festgestellt, dass eine Überlappung von 500+50 den richtigen Kompromiss für mich darstellt.

Fehler, die Sie sehen könnten:

• ImportError: Fehlende FAISS-Links? Führen Sie pip install faiss-cpu aus.
• Authentifizierung fehlgeschlagen von OpenAI? Überprüfen Sie Ihre API-Schlüssel und Umgebungsvariablen.

Schritt 5: RetrievalQA-Kette mit Langfuse-Callbacks einrichten

from langchain.chains import RetrievalQA
from langchain.chat_models import ChatOpenAI
from langfuse.callback import LangfuseTracer

# Initialisieren Sie Ihr Sprachmodell mit dem Langfuse-Tracer für die Beobachtbarkeit
llm = ChatOpenAI(
 openai_api_key="YOUR_OPENAI_KEY",
 temperature=0,
)

# Wickeln Sie LLM mit dem Langfuse-Callback ein
lf_tracer = LangfuseTracer(lf_client=lf, project_name=project_name, environment=environment)

# Wenn Sie den Tracer hier nicht hinzufügen, wird Langfuse Ihre LLM-Aufrufe nicht verfolgen
llm.callbacks = [lf_tracer]

# Erstellen Sie die RAG-Pipeline
qa = RetrievalQA.from_chain_type(
 llm=llm,
 chain_type="stuff", # einfache Kette, füllt den Prompt mit den Docs
 retriever=vector_store.as_retriever(),
)

Hier ist der Trick: Das Vergessen, LangfuseTracer als Callback hinzuzufügen, ist der häufigste Fehler bei Anfängern. Sie werden sich am Kopf kratzen und sich fragen, warum kein Ereignis in Langfuse angezeigt wird. Überprüfen Sie immer, ob die Callbacks vor dem Testen der Anfragen angehängt sind.

Schritt 6: Abfragen und Überwachen

query = "Was sind die größten Herausforderungen beim Aufbau von zuverlässigen RAG-Pipelines?"

result = qa.run(query)
print("Antwort:", result)

# In der Benutzeroberfläche von Langfuse können Sie die detaillierten Traces der Embeddings, Abrufe, LLM-Prompts und Antworten inspizieren.

Dieser letzte Schritt scheint täuschend einfach zu sein, produziert aber die wahre Magie. Wenn Sie den Server und den Tracer richtig konfiguriert haben, erhalten Sie detaillierte Protokolle über Anfragen/Antworten, Timing-Informationen und Fehlermeldungen – was traditionelle RAG-Pipelines standardmäßig nicht bieten.

Die Fänge

1. Fehlende Callbacks bedeuten keine Beobachtbarkeit

Im Ernst, wenn Sie vergessen, LangfuseTracer zu Ihren LLM-Callbacks hinzuzufügen, navigieren Sie im Dunkeln. Keine Fehler, keine Warnungen, nur Stille in Ihrem Beobachtungs-Dashboard. Es hat mich eine frustrierende Stunde gekostet, bis ich realisiert habe, dass die Integration der Callbacks manuell und entscheidend ist.

2. Persistenz des Vektorspeichers

FAISS kann den Index serialisieren und speichern, aber nachlässige Implementierungen laden von null, was Zeit und Ressourcen kostet. Persistieren Sie immer Ihren Vektorspeicher auf der Festplatte nach der Indizierung mit save_local oder Ähnlichem und laden Sie ihn bei der Initialisierung der Pipeline.

3. API-Rate-Limits und Wiederholungen

Fehler in der OpenAI-API führen zu Fehlschlägen bei LLM-Aufrufen, aber Langfuse verwaltet Wiederholungen nicht magisch für Sie. Implementieren Sie ein exponentielles Backoff in der Produktion. Ihr Überwachungs-Dashboard zeigt hier Fehlerspitzen an, aber Ihre Pipeline muss Ausfälle oder Rückschläge elegant bewältigen.

4. Planung der Chunk-Größen und Überlappungen

Zu kleine Chunks verursachen Abrufgeräusch; zu große Chunks führen zu einem Tokenüberlauf und Fehlschlägen. Passen Sie die Chunk-Einstellungen entsprechend Ihrer Datenmodalität an. Langfuse korrigiert kein schlechtes Fragmentieren – Sie müssen immer für diese Logik verantwortlich sein.

5. Lizenzwarnungen

Die NOASSERTION-Lizenz von Langfuse bedeutet, dass Sie die Konformität bewerten müssen, wenn Sie es in proprietäre Software integrieren. Es ist nicht GPL oder MIT, also überprüfen Sie dies mit Ihrem rechtlichen Team, bevor Sie in die Produktion gehen.

Vollständiges funktionales Beispiel

import os
from langchain.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.vectorstores import FAISS
from langchain.embeddings import OpenAIEmbeddings
from langchain.chat_models import ChatOpenAI
from langchain.chains import RetrievalQA
from langfuse.client import LangfuseClient
from langfuse.callback import LangfuseTracer

# ----------- Konfiguration -----------
OS_ENV_VARS = {"OPENAI_API_KEY": "YOUR_OPENAI_KEY"}
os.environ.update(OS_ENV_VARS)

LANGFUSE_API_KEY = "YOUR_LANGFUSE_API_KEY"
LANGFUSE_API_URL = "http://localhost:4200/api"
PROJECT = "my-rag-project"
ENVIRONMENT = "dev"

# ----------- Langfuse Client Setup -----------
lf = LangfuseClient(api_key=LANGFUSE_API_KEY, api_url=LANGFUSE_API_URL)

# ----------- Dokumente laden und aufteilen -----------
loader = TextLoader("./data/messy_docs.txt")
docs = loader.load()

splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
docs_split = splitter.split_documents(docs)

# ----------- Einbettungen und Vektorstore -----------
embeddings = OpenAIEmbeddings()
vectorstore = FAISS.from_documents(docs_split, embeddings)

# ----------- Langfuse Tracer und LLM -----------
tracer = LangfuseTracer(
 lf_client=lf,
 project_name=PROJECT,
 environment=ENVIRONMENT,
)

llm = ChatOpenAI(temperature=0)
llm.callbacks = [tracer]

# ----------- RAG Kette -----------
retriever = vectorstore.as_retriever()
qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever, chain_type="stuff")

# ----------- Abfrage -----------
query = "Was sind die Hauptprobleme beim Aufbau zuverlässiger RAG-Pipelines?"
answer = qa.run(query)

print(f"Q: {query}\nA: {answer}")

Und nachher?

Seien Sie nicht damit zufrieden, eine RAG-Pipeline zu erstellen und sie zu vergessen. Der nächste sofortige Schritt sollte sein, ein Fehler-Management und eine Wiederholungslogik in Ihre Langfuse-Trace-Konfiguration einzufügen – bedanken Sie sich später bei mir.

Langfuse verfolgt Ihre Aufrufe, aber das verhindert nicht, dass Ihre Pipeline stillschweigend ausfällt oder besondere Fälle übersieht. Richten Sie daher eine automatische Benachrichtigung bei Spitzen in der Langfuse-Fehlerquote ein und verwenden Sie sie als Ihre erste Verteidigungslinie in der Produktion.

Häufig gestellte Fragen

F: Kann ich Langfuse mit anderen Vektordatenbanken wie Pinecone oder Weaviate verwenden?

Absolut. Langfuse schränkt Sie nicht auf FAISS ein. Es integriert sich in das Callback-System von Langchain, daher funktioniert jede Vektordatenbank, die mit Langchain integriert ist. Ersetzen Sie einfach den Vektordatenbankcode und stellen Sie sicher, dass Ihre Abrufaufrufe immer über die Langfuse-Callbacks laufen.

F: Was passiert, wenn ich die API-Rate-Limits von OpenAI überschreite? Behandelt Langfuse Wiederholungen?

Nein. Langfuse ist eine Lösung zur Beobachtbarkeit, kein Anfrage-Proxy. Sie müssen die Wiederholungslogik selbst implementieren. Die gute Nachricht: Langfuse zeigt Ihnen die fehlgeschlagenen Aufrufe und Zeitinformationen, sodass Sie Ihre Wiederholungsstrategie anpassen oder den Anbieter wechseln können, bevor sich Ihre Benutzer beschweren.

F: Ich habe keine unordentlichen PDFs, sondern semi-strukturierte Dokumente. Kann Langfuse bei der Fehlersuche der Ingestion helfen?

Ja. Langfuse verfolgt alles, von den Embeddings über das Abrufen bis zur Generierung. Wenn Ihre Quelldokumente sich nicht gut aufspalten oder die Embeddings mittelmäßig sind, werden die Metriken und Protokolle von Langfuse diese Probleme aufdecken. Nutzen Sie diese Informationen, um Ihre Splitter, Vorverarbeiter oder Embedding-Modelle zu verfeinern.

Langfuse Modell-Repository Statistiken

Repository	Sterne	Forks	Offene Probleme	Lizenz	Letzte Aktualisierung
langfuse/langfuse	23.484	2.377	588	NOASSERTION	2026-03-20

Abschluss Empfehlungen basierend auf dem Entwickler-Persona

Der Unabhängige Entwickler: Wenn Sie allein oder in einem kleinen Team an einer neuen Anwendung arbeiten, halten Sie Langfuse lokal. Führen Sie den Docker-Server aus und verbinden Sie Ihre Pipeline schnell. Übertreiben Sie es vorerst nicht mit Persistenz oder Cloud-Skalierung – sorgen Sie einfach für eine Beobachtbarkeit, die zeigt, wann Ihre LLM-Aufrufe fehlschlagen.

Der Produktions-Operations Ingenieur: Sie möchten ein redundantes Langfuse-Deployment mit integrierten Alarme und persistierenden Vektordatenbanken mit täglichen Rekonstruktionen. Langfuse hilft, Latenzen in Echtzeit oder Fehler-Spitzen in der Produktion zu debuggen. Automatisieren Sie die Gesundheitsüberprüfungen Ihrer Pipeline und speisen Sie diese Metriken in Ihre bestehende Dashboard-Stack ein.

Der Forschungsingenieur: Nutzen Sie Langfuse, um verschiedene Embeddings und LLM-Parameter in der gleichen Pipeline zu bewerten. Seine detaillierten Trace-Logs ermöglichen es Ihnen, die Anfrage-Token, die Vollständigkeiten und die Effizienz des Abrufs zu vergleichen. Iterieren Sie dann schnell in Ihrem Experimentierzyklus.

Daten ab dem 21. März 2026. Quellen: https://github.com/langfuse/langfuse, https://langfuse.com

Verwandte Artikel

• Beste AI-Suchleistungsüberwachungstools
• Beste Screenshot- und Aufnahmewerkzeuge für präzise Arbeiten
• Beste DNS- und Domain-Management-Tools im Jahr 2023

🕒 Published: March 30, 2026