Ein Docs-Assistent in zwei Python-Dateien: ChromaDB, LangChain und Claude
Ein 187-seitiges dbt-Standards-PDF in einen suchbaren Assistenten umwandeln, der über ein Einlesensskript, lokale Hugging Face-Embeddings, ChromaDB sowie auf den Dokumenten basierende Antworten von Claude verfügt.
Quellen: How I Built an AI Agent That Reads Company Docs in 5 Minutes
Statische Dokumentation hat ihren üblichen Preis: Kollegen werden mit denselben Fragen gestört, Neueinsteiger finden die dbt-Standards nicht, und alle verlieren Zeit beim Wechsel des Kontexts. Die durch Suchfunktionen erweiterte Generierung behebt einen Großteil davon, indem sie eine Wissensdatenbank nach Bedeutung und nicht nur nach Schlüsselwörtern suchbar macht. Ein Entwurf beantwortet jedoch keine Fragen – Code schon. Deshalb hier ein kleiner Python-Pipeline, der ein Unternehmensdokument liest, daraus einen suchbaren „Verstand“ erstellt und Ihrem Team einen konversationalen Assistenten bietet – alles in etwa fünf Minuten.
Alles besteht aus zwei Dateien:
ingest.pyist der Ersteller. Führen Sie es einmal aus, um die Dokumentation zu verarbeiten und in einer Datenbank zu speichern.ask.pyist die Sprachsteuerung. Führen Sie es jedes Mal aus, wenn jemand eine Frage hat, und es gibt eine Antwort basierend auf der Dokumentation zurück.
Einrichtung
Zuerst kommen zwei Dinge: die Bibliotheken und ein Ort, an dem der API-Schlüssel aufbewahrt werden kann.
Die Anforderungsdatei
Die Bibliotheken kümmern sich um das Laden von Dokumenten, das Aufteilen in Blöcke, die Erstellung von Embeddings, die Vektorsuche sowie die Kommunikation mit Claude. Erstellen Sie in dem Projektverzeichnis eine requirements.txt-Datei mit dieser Liste:
# Core LangChain — split into standalone packages since 0.2
langchain>=0.2.0
langchain-core>=0.2.0
langchain-community>=0.2.0 # PyPDFLoader still lives here
langchain-text-splitters>=0.2.0 # RecursiveCharacterTextSplitter moved here
langchain-anthropic>=0.1.0
langchain-huggingface>=0.0.3 # HuggingFaceEmbeddings moved here
langchain-chroma>=0.1.0 # Chroma moved here
# Vector store
chromadb>=0.5.0
# PDF loading
pypdf>=4.0.0
# Embeddings
sentence-transformers>=3.0.0
# Claude
anthropic>=0.28.0
# Env vars
python-dotenv>=1.0.0
Installieren Sie alles mit pip install -r requirements.txt.
Die .env-Datei
Claude ist die Stimme des Agents, daher ist eine Anthropic-API-Schlüssel erforderlich. Codieren Sie Schlüssel niemals direkt in Python-Skripten ein, da eine versehentliche Hochladen auf GitHub ein ernstes Sicherheitsrisiko darstellt. Erstellen Sie stattdessen eine versteckte .env-Datei im Projektverzeichnis und fügen Sie den Schlüssel hinzu:
ANTHROPIC_API_KEY=your_actual_api_key_here
Die python-dotenv-Bibliothek ermöglicht es den Skripten, diese Datei automatisch im Hintergrund zu lesen.
Erstellung des „Gehirns“ mit ingest.py
Ein Assistent muss die Anleitung lesen, bevor er Fragen beantworten kann. ingest.py wird einmal ausgeführt oder erneut, sobald sich die Dokumentation ändert. Seine Aufgabe besteht darin, ein PDF zu lesen, es in verdauliche Teile zu zerlegen, diese Teile in Vektoren umzuwandeln, die die Bedeutung erfassen, und sie in einer Datenbank zu speichern. Das vollständige Skript:
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
# Step 1: Load the raw documentation
print("1. Loading the documentation...")
loader = PyPDFLoader("dbt_snowflake_documentation.pdf")
docs = loader.load()
# Step 2: Slice the text into chunks
print("2. Chunking the text...")
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000,
chunk_overlap=200
)
chunks = text_splitter.split_documents(docs)
# Step 3: Set up the Embedding Model (The Translator)
print("3. Setting up the embedding model...")
embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
# Step 4: Build and save the Vector Database
print("4. Building the ChromaDB brain...")
vector_db = Chroma.from_documents(
documents=chunks,
embedding=embeddings,
persist_directory="./chroma_db"
)
print("Done! The AI Brain is successfully built.")
Was die Skriptschritte Schritt für Schritt leisten:
- Laden.
PyPDFLoaderliest das Dokument ein, in diesem Fall ein 187-seitiges PDF nach den dbt-Standards. - Teilen. Ein ganzes Buch kann nicht auf einmal an ein Modell übergeben werden, daher wird der Text in Blöcke à 1000 Zeichen aufgeteilt, jeweils etwa ein Absatz. Eine
chunk_overlapvon 200 Zeichen sorgt dafür, dass eine Regel, die sich über zwei Absätze erstreckt, nicht in der Mitte geteilt wird. - Einbetten. Das Modell ist
all-MiniLM-L6-v2, ein kleines Open-Source-Modell von Hugging Face. Es läuft auf der lokalen CPU ohne kostenpflichtige Cloud-API und wandelt jeden Block in einen 384-dimensionalen Vektor um. - Speichern. Die Vektoren werden in ChromaDB gespeichert, genauer gesagt in einem Verzeichnis auf der Festplatte unter
./chroma_db.
Führen Sie es mit python ingest.py aus. Nach einigen Sekunden erscheint ein neuer Ordner chroma_db im Projekt. Das statische Dokument ist nun zu einem kodierten, suchbaren Speicher geworden.
Eine Stimme verleihen mit ask.py
Die Dokumentation befindet sich nun kodiert in ./chroma_db. Was noch fehlt, ist etwas, das eine Frage entgegennimmt, nach Informationen sucht und antwortet. Das ist ask.py – es kann jederzeit ausgeführt werden, wenn jemand eine Frage hat:
"""
ask.py — Interactive QA loop. Run this after ingest.py has finished.
Usage:
python ask.py
python ask.py --db ./my_chroma_db --k 6
"""
import os
import argparse
from dotenv import load_dotenv
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough, RunnableMap
load_dotenv()
# ── CLI args ──────────────────────────────────────────────────────────────────
parser = argparse.ArgumentParser(description="Ask questions against your embedded docs")
parser.add_argument("--db", default="./chroma_db")
parser.add_argument("--k", type=int, default=4)
parser.add_argument("--model", default="claude-sonnet-4-6")
args = parser.parse_args()
# ── Guards ────────────────────────────────────────────────────────────────────
if not os.path.exists(args.db):
print(f"\nERROR: ChromaDB not found at '{args.db}'")
print(" Run ingest.py first.\n")
exit(1)
if not os.getenv("ANTHROPIC_API_KEY"):
print("\nERROR: ANTHROPIC_API_KEY not found in .env file\n")
exit(1)
# ── 1. Embeddings (same model as ingest.py) ───────────────────────────────────
print("\n[1/3] Loading embedding model...")
embeddings = HuggingFaceEmbeddings(
model_name="sentence-transformers/all-MiniLM-L6-v2",
model_kwargs={"device": "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
# ── 2. ChromaDB ───────────────────────────────────────────────────────────────
print(f"[2/3] Connecting to ChromaDB at: {args.db}")
vectorstore = Chroma(
persist_directory=args.db,
embedding_function=embeddings,
collection_name="dbt_docs",
)
doc_count = vectorstore._collection.count()
print(f" {doc_count} chunks loaded")
retriever = vectorstore.as_retriever(
search_type="similarity",
search_kwargs={"k": args.k},
)
# ── 3. Claude ─────────────────────────────────────────────────────────────────
print(f"[3/3] Loading {args.model}...")
llm = ChatAnthropic(
model=args.model,
temperature=0,
max_tokens=2048,
)
# ── Prompt ────────────────────────────────────────────────────────────────────
PROMPT = PromptTemplate.from_template("""You are a helpful assistant for a data engineering team.
Answer the question using ONLY the context provided below.
If the context does not contain enough information, say so clearly — do not make things up.
Be concise and practical. Use code examples when they are present in the context.
Context:
{context}
Question: {question}
Answer:""")
# ── LCEL chain (replaces RetrievalQA) ────────────────────────────────────────
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
chain = (
RunnableMap({
"context": retriever | format_docs,
"question": RunnablePassthrough(),
})
| PROMPT
| llm
| StrOutputParser()
)
# ── Chat loop ─────────────────────────────────────────────────────────────────
print("\n" + "="*55)
print(" dbt Documentation Agent — ready")
print(f" Model : {args.model}")
print(f" Chunks retrieved per query: {args.k}")
print(" Type 'exit' to quit")
print("="*55 + "\n")
while True:
try:
question = input("Question > ").strip()
except (KeyboardInterrupt, EOFError):
print("\nGoodbye!")
break
if not question:
continue
if question.lower() in ("exit", "quit", "q"):
print("\nGoodbye!")
break
try:
# Retrieve source docs separately so we can display them
source_docs = retriever.invoke(question)
# Run the full chain
answer = chain.invoke(question)
# ── Answer ────────────────────────────────────────────────────────────
print("\n" + "─"*55)
print(answer)
# ── Sources ───────────────────────────────────────────────────────────
print("\n── Sources used " + "─"*39)
seen = set()
for doc in source_docs:
page = doc.metadata.get("page", "?")
source = doc.metadata.get("source", "unknown")
key = (source, page)
if key in seen:
continue
seen.add(key)
preview = doc.page_content.strip()[:280].replace("\n", " ")
print(f"\n [p.{page}] {preview}…")
print("\n" + "─"*55 + "\n")
except Exception as e:
print(f"\nERROR: {e}\n")
Ausprobieren
Starten Sie es mit python ask.py und geben Sie eine Frage ein wie zum Beispiel „Wie sollte ich Staging-Modelle benennen?“ Das Skript akzeptiert außerdem --db, um auf ein anderes Chroma-Verzeichnis zu verweisen, sowie --k, um zu ändern, wie viele Blöcke pro Frage abgerufen werden – was nützlich ist, wenn die Antworten den Kontext zu verfehlen scheinen. Eine allgemeine Webantwort oder eine erfundene Antwort wäre hier nutzlos. Die Antwort lautet stattdessen in etwa: „Staging-Modelle sollten das Präfix stg_ verwenden.“ Es hat nicht geraten, und niemand musste in Seite 14 des PDFs suchen. Es fand die richtige Regel und erklärte sie auf die Weise, wie es ein erfahrener Ingenieur tun würde.
Probieren Sie nun etwas Unverwandtes aus, wie zum Beispiel das Wetter in Paris in dieser Woche. Der Assistent erfindet keine Antwort aus allgemeinem Wissen. Er prüft den heruntergeladenen Dokumentenkontext, stellt fest, dass die Information dort nicht vorhanden ist, und sagt ehrlich, dass er aufgrund der bereitgestellten Dokumente keine Antwort geben kann. Diese Ehrlichkeit ist ein wesentlicher Bestandteil dafür, dass ein System in der Praxis vertrauenswürdig ist.
Was ändert sich für das Team
Das Muster lässt sich gut auf Bereiche jenseits von dbt übertragen. Jedes auf PDF basierende Handbuch, Runbook oder Richtlinienpaket kann mit denselben beiden Skripten verarbeitet werden, und da die Embeddings lokal ausgeführt werden, gelangen nur die endgültige Frage sowie die heruntergeladenen Auszüge zu einer externen API.
In zwei Python-Dateien und innerhalb weniger Minuten wurden 187 Seiten an meist ignorierten Dokumentationen zu einem kompetenten Gesprächspartner. Niemand muss mehr manuell antworten „Wie nennen wir die Staging-Modelle?“ oder in Confluence nach dem richtigen Link suchen. Der Assistent antwortet sofort und berücksichtigt dabei Ihre tatsächlichen Standards.
Er befindet sich jedoch immer noch auf einem Laptop. Die logischen nächsten Schritte sind es, denselben Workflow mit Slack zu verbinden, damit Teammitglieder den @dbt-assistant-Bot dort einsetzen können, wo sie bereits arbeiten, sowie die Dateneingabe zu automatisieren, damit der Index stets aktualisiert wird, sobald sich die Dokumentation ändert.
Verwandte Artikel
- Ein LangChain-Handelsagent, der durch aktuelle EODHD-Marktdaten unterstützt wird – Schritt für Schritt — Warum Handelsagenten auf Basis von LLM ohne echte Daten versagen, wie der ReAct-Loop funktioniert und wie man einen LangChain-Agenten mit drei Werkzeugen auf der Grundlage von EODHD-Preisen, Fundamentaldaten und RSI erstellt.
- Ein Medizin-Agent, der zwischen SQLite-Datenbanken und Web-Suchen wechselt — Erstellen Sie einen LangChain-Agenten, der entscheidet, ob eine medizinische Frage eine SQL-Abfrage in drei Datensätzen oder eine aktuelle Web-Suche erfordert, sowie zwei Fehler, die das Design verändert haben.