Ein lokaler RAG-Pipeline mit Qdrant, fastembed und Gemini in Python
Ein kleiner RAG-Pipeline in Python: Teilen Sie lokale Dokumente in Blöcke auf, embedden Sie sie offline mit fastembed, speichern Sie die Vektoren in Qdrant und beantworten Sie Fragen mit Gemini über die CLI.
Eine maßgeschneiderte RAG-(Retrieval-augmented Generation)-Einrichtung klingt schwieriger, als sie tatsächlich ist. Die Vermarktung suggeriert, man bräuchte eine Unternehmensplattform, nur damit ein LLM lokale Dateien lesen kann. Das ist nicht der Fall. Ein voll funktionsfähiger, schrittweiser Arbeitsablauf kann auf einem einzigen Rechner mit Qdrant und Gemini laufen, ohne komplexe Frameworks oder zu verwaltende Server. Im Folgenden wird erklärt, wie es funktioniert, was der Code bewirkt und wie man ihn ausführt.
Das Problem, das RAG löst
Sprachmodelle kennen nur ihre Trainingsdaten. Sie haben Ihre Notizen, Berichte oder das PDF, das Sie heute Morgen gespeichert haben, noch nie gesehen. RAG schließt diese Lücke. Anstatt zu hoffen, dass das Modell aus allgemeinem Wissen errät, durchsucht das System Ihre Dokumente nach relevanten Passagen, übergibt diese dem Modell und weist es an, ausschließlich auf dieser Grundlage zu antworten. So erfindet es keine Inhalte mehr, da es Ihr Material liest.
Eine einfache Schlüsselwortsuche könnte diese Abschnitte finden, funktioniert aber schnell nicht mehr zuverlässig, weshalb die Vektorsuche die übliche Wahl ist.
Vektoren und Vektorsuche
Ein Vektor ist eine Liste von Zahlen, die die Bedeutung eines Textabschnitts darstellt. Wenn man „Wie geht es Ihnen?“ und „Wie alt sind Sie?“ in Vektoren umwandelt, kann man berechnen, wie ähnlich sie sind. Die Vektorsuche nutzt dieses Prinzip, um Antworten zu finden, selbst wenn die Formulierung unterschiedlich ist. Die Frage sowie jeder Dokumentabschnitt werden in denselben numerischen Raum eingebettet, und dasjenige, das inhaltlich am nächsten liegt, gewinnt. Das ist wichtig, weil Menschen selten eine Frage genauso formulieren wie im Dokument. Jemand, der fragt „Wie bekomme ich mein Geld zurück?“, benötigt dennoch den Abschnitt mit dem Titel „Rückerstattungspolitik“.
Ein RAG-Pipeline ist das System, das all das miteinander verbindet. Sie umfasst in der Regel sechs Schritte:
- Einlesen: Eine Datei landet in einem Ordner, in diesem Fall
documents/. - In Teilblöcke aufteilen: Das Skript teilt die Datei in kleinere, überschneidende Abschnitte auf. Das Suchen in einem 50-seitigen Dokument als Ganzes funktioniert nicht, daher ist eine Aufteilung notwendig.
- Einbetten: Ein kleines lokales Modell wandelt jeden Teilblock in einen Vektor um, sodass Abschnitte zu ähnlichen Themen in der Nähe voneinander landen.
- Speicherung: Die Vektoren werden in Qdrant gespeichert, einer Vektor-Datenbank, die dafür konzipiert ist, einen neuen Vektor entgegenzunehmen und schnell die am nächsten liegenden Ergebnisse aus Millionen von Datensätzen zurückzugeben. Sie ist schnell, open source und läuft lokal – ohne Servereinstellungen oder Account.
- Auswertung: Auch eine Frage wird in einen Vektor umgewandelt, und Qdrant gibt die Teilblöcke zurück, die am nächsten dazu liegen und daher am ehesten die Antwort enthalten.
Die Schritte 1 bis 4 laufen automatisch über das Flag -i oder den -w Watcher, sodass die Dokumente stets auffindbar sind. Die Schritte 5 und 6 erfolgen auf Anfrage, wenn -q verwendet wird.
Die Python-Implementierung
Der Code bleibt leichtgewichtig und verzichtet auf große Frameworks, wodurch man leicht nachvollziehen kann, wohin die Daten fließen.
Dateien lesen
Zuerst werden die Dateien gefunden und der Rohtext extrahiert, egal ob es sich um Markdown-Notizen oder unstrukturierte Word-Dokumente handelt:
def read_document(path) -> str:
# dispatches on extension: .txt/.md read directly,
# .pdf via pypdf, .docx via docx2txt -> returns plain textdef file_status(path, state) -> str:
# "not_indexed" if never seen, "modified" if file_hash(path)
# differs from the hash stored in state, else "indexed"
Chunking
Anschließend wird der Text mit einem einfachen Schiebefenster aufgeteilt, sodass ein Satz, der eine Trennlinie überschreitet, seinen Kontext beibehält:
def chunk_text(text, chunk_size=500, overlap=50) -> list:
words = text.split()
step = chunk_size - overlap
return [" ".join(words[i:i+chunk_size])
for i in range(0, len(words), step)]
Embeddings und stabile IDs
Die Embedding-Verarbeitung findet lokal statt, ohne dass pro Satz eine externe API-Aufruf notwendig ist. Jeder Textabschnitt erhält außerdem eine vorhersehbare ID, die aus dem Hash seines Textes abgeleitet wird, sodass unveränderter Text von Lauf zu Lauf dieselbe ID behält:
def chunk_ids_for(chunks) -> dict:
# id = uuid5(namespace, chunk_text) for each chunk
# -> same text always gets the same id, across re-indexes
...
Die Einbettung selbst findet innerhalb des Qdrant-Aufrufs statt:
# inside index_file():
client.add(collection_name=index_name, documents=new_chunks, ids=new_ids)
# Qdrant's fastembed integration embeds `documents` automatically
Dateisynchronisierung mit der Datenbank
Hier werden lokale Dateien mit der Datenbank abgeglichen. Die Korrektur eines Tippfehlers löscht weder den Index noch erzwingt sie einen Neustart. Der Code vergleicht IDs, löscht die verschwundenen Teile und fügt neue hinzu:
def index_file(path, state) -> bool:
chunks = chunk_text(read_document(path))
new_ids = chunk_ids_for(chunks)
old_ids = state[path.name].chunk_ids # from last time
client.delete(collection_name, ids=old_ids - new_ids) # removed chunks
client.add(collection_name, ids=new_ids - old_ids, ...) # new/changed chunks
state[path.name] = {...updated record...}
Auch die aus dem Ordner entfernten Dateien werden bereinigt:
def prune_deleted(state) -> int:
# for each file in state no longer present in DOCUMENT_DIR:
# delete its Qdrant collection, drop its state entry
Antwort auf eine Anfrage
Wenn eine Frage eintrifft, wird von Qdrant nach den besten Übereinstimmungen in den ausgewählten Dokumenten gesucht. Zunächst prüft ein Hilfsprogramm, in welchen Indizes gesucht werden soll:
def resolve_index_names(spec, state) -> list:
# "all" -> every indexed collection; "a,b" -> ["a","b"], validated
Dann wird die Abfrage gegen jede davon ausgeführt und die Ergebnisse zusammengeführt:
def cmd_query(index_spec, question, top_k, show_sources):
for name in resolve_index_names(index_spec, state):
hits += client.query(collection_name=name, query_text=question, limit=top_k)
hits = sorted(hits, key=score, reverse=True)[:top_k]
Generierung
Schließlich werden die abgerufenen Fragmente direkt an Gemini übermittelt, das mit dem bereitgestellten Text verglichen wird:
def generate_answer(question, context) -> str:
prompt = f"Answer using only this context:\n{context}\n\nQuestion: {question}"
return genai.Client(api_key=...).models.generate_content(
model=GEMINI_MODEL, contents=prompt
).text
Der Rest ist Hilfskode. get_client() öffnet die Qdrant-Verbindung, load_state() und save_state() lesen und schreiben in .rag_state.json, und sanitize_index_name() wandelt Dateinamen in gültige Sammelnamen um. Die Befehlsfunktionen (cmd_list_files, cmd_index, cmd_watch) verknüpfen alles mit den Befehlszeilen-Flaggen.
Lokal ausführen
Klonen Sie das Repository und wechseln Sie in das Projektverzeichnis:
git clone https://github.com/Shivvam/rag-pipeline-qdrant.git
cd rag-cli
Dann erstellen Sie eine Umgebung, installieren die erforderlichen Komponenten und richten die Konfigurationsdatei ein:
python3 -m venv venv
source venv/bin/activate # on Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # then edit in your GEMINI_API_KEY
Aktivieren Sie die virtuelle Umgebung erneut in jedem neuen Terminal, bevor Sie app.py ausführen. GEMINI_API_KEY muss gesetzt sein, damit -q Antworten liefert, während die anderen Befehle auch ohne diese Einstellung funktionieren.
Verwendung über die Kommandozeile
Alles bezüglich der Einholung und Abfrage von Daten wird über das Terminal gesteuert. Um zu sehen, welche Dateien sich im Dokumentenordner befinden und welche Aufmerksamkeit benötigen, oder welche Indizes vorhanden sind:
python app.py -lf # list files in ./documents + status
python app.py -li # list existing indexes
Zum Verarbeiten neuer Dokumente oder Zum Aktualisieren geänderter Dokumente:
python app.py -i myfile.md # index one file (or re-index if changed)
python app.py -i all # index every not_indexed/modified file
Um während der Bearbeitung eine automatische Indizierung zu ermöglichen, lassen Sie dies in einem zweiten Terminal laufen:
python app.py -w # watch ./documents, auto-index on add/edit
Fragen zu einem einzelnen Datei, mehreren Dateien oder allem zusammen stellen:
python app.py -q report "What is X?" # query a single index
python app.py -q report,notes "What is X?" # query multiple indexes together
python app.py -q all "What is X?" --sources # query everything, show retrieved chunks
python app.py -q report "..." -k 8 # retrieve top 8 chunks instead of default 5
Der von -lf angezeigte Status kann drei Werte annehmen. not_indexed bedeutet, dass die Datei noch nie verarbeitet wurde, indexed bedeutet, dass sie aktuell ist, und modified bedeutet, dass sie seit dem letzten Ausführungsvorgang geändert wurde und -i erneut ausgeführt werden muss.
Entwurfsentscheidungen
Mehrere Entscheidungen sorgen dafür, dass alles schnell und einfach bleibt.
- Qdrant: Jede Datei erhält ihre eigene Sammlung, die nach dem bereinigten Dateinamen benannt wird; bei Kollisionen wird ein numerischer Suffix hinzugefügt. Standardmäßig wird der lokale Modus auf der Festplatte (
./qdrant_storage) verwendet, sodass kein Server erforderlich ist. Für gleichzeitigen Zugriff mussQDRANT_URLin.envauf einen echten Qdrant-Server eingestellt werden. Im lokalen Modus wird der Verzeichniszugriff auf einen Prozess beschränkt, weshalb-wund-qnicht gleichzeitig ausgeführt werden können. - Embeddings: Das Modell
BAAI/bge-small-en-v1.5wird über fastembed ausgeführt. Es wird einmal heruntergeladen und im Cache gespeichert, sodass es keine API-Kosten gibt und zur Abfragezeit keine Netzwerkverbindung erforderlich ist. - Gemini: Es werden nur die endgültigen Antworten aus den abgerufenen Datenblöcken geschrieben, wobei standardmäßig
gemini-3.5-flashverwendet wird. - State:
.rag_state.jsonspeichert Datei-Hashes, Status, Indexnamen sowie die Anzahl der Datenblöcke, wodurch die Befehle-lfund-lisofort ausgeführt werden können, da Qdrant keine erneute Suche durchführen muss. Die IDs der Datenblöcke stammen aus dem Text selbst, weshalb das Neuindexieren schrittweise erfolgt und nur die geänderten Datenblöcke neu eingebettet und aktualisiert werden. - Dateitypen:
.txtund.mdfunktionieren sofort..pdfund.docxerfordernpypdfoderdocx2txt, die beide bereits in den Anforderungen aufgeführt sind.