Asystent do dokumentacji w dwóch plikach Python: ChromaDB, LangChain i Claude
Przekształć 187-stronicowy plik PDF z standardami dbt w asystenta umożliwiającego wyszukiwanie, wykorzystując skrypt do pobierania danych, lokalne embeddingi Hugging Face, ChromaDB oraz odpowiedzi Claude oparte na dokumentacji.
Źródła: How I Built an AI Agent That Reads Company Docs in 5 Minutes
Dokumentacja statyczna wiąże się z oczywistymi kosztami. Koledzy są ciągle przerywani tymi samymi pytaniami, nowi pracownicy nie mogą znaleźć standardów dbt, a wszyscy tracą czas na zmianę kontekstu. Generowanie wzbogacone o wyszukiwanie rozwiązuje wiele z tych problemów, umożliwiając wyszukiwanie w bazie wiedzy według znaczenia, a nie tylko słów kluczowych. Plan nie odpowiada jednak na pytania – kod tak. Oto więc mały pipeline w Pythonie, który czyta dokument firmowy, tworzy z niego wyszukiwalny „mózg” i dostarcza zespołowi asystenta konwersacyjnego, wszystko to w zaledwie około pięciu minutach.
Całość składa się z dwóch plików:
ingest.pysłuży do tworzenia bazy wiedzy. Uruchom go raz, aby przetworzyć dokumentację i przechować ją w bazie danych.ask.pypełni rolę asystenta. Uruchom go za każdym razem, gdy ktoś ma pytanie – on zwróci odpowiedź opartą na dokumentacji.
Ustawienie
Najpierw należy przygotować dwie rzeczy: biblioteki oraz miejsce na przechowywanie klucza API.
Plik wymagań
Biblioteki obejmują ładowanie dokumentów, dzielenie ich na fragmenty, generowanie embeddingów, wyszukiwanie wektorowe oraz komunikację z Claude. Stwórz plik requirements.txt w folderze projektu z następującą listą:
# 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
Zainstaluj wszystko za pomocą pip install -r requirements.txt.
Plik .env
Claude jest głosem agenta, dlatego potrzebny jest klucz API Anthropic. Nigdy nie umieszczaj kluczy bezpośrednio w skryptach Pythona, ponieważ przypadkowe umieszczenie ich na GitHubie stanowi poważne zagrożenie dla bezpieczeństwa. Zamiast tego utwórz ukryty plik .env w korzeniu projektu i dodaj tam klucz:
ANTHROPIC_API_KEY=your_actual_api_key_here
Biblioteka python-dotenv umożliwia skryptom automatyczne odczytywanie tego pliku w tle.
Budowanie „mózgu” za pomocą ingest.py
Asystent musi najpierw przeczytać instrukcję, zanim będzie mógł odpowiadać na pytania. ingest.py jest uruchamiany raz, lub ponownie za każdym razem, gdy dokumentacja ulega zmianie. Jego zadaniem jest odczytanie pliku PDF, podzielenie go na łatwe do przetworzenia fragmenty, przekształcenie tych fragmentów w wektory odzwierciedlające znaczenie oraz zapisanie ich w bazie danych. Pełny skrypt:
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.")
To, co robi skrypt, krok po kroku:
- Ładowanie.
PyPDFLoaderodczytuje dokument, w tym przypadku 187-stronicowy PDF z standardami dbt. - Dzielenie na fragmenty. Całą książkę nie można przekazać modelowi za jednym razem, dlatego tekst jest dzielony na bloki po 1000 znaków, co odpowiada mniej więcej jednemu akapitowi. Wartość
chunk_overlapwynosząca 200 znaków zapobiega rozcięciu reguły, która obejmuje dwa akapity. - Wbudowywanie. Użyty model to
all-MiniLM-L6-v2– mały model otwartego oprogramowania od Hugging Face. Działa na lokalnym procesorze, bez konieczności korzystania z płatnych usług chmurowych, i przekształca każdy fragment w wektor o 384 wymiarach. - Zapisywanie. Wektory trafiają do ChromaDB i są zapisywane w folderze na dysku o adresie
./chroma_db.
Zainstaluj to za pomocą python ingest.py. Po kilku sekundach w projekcie pojawi się nowa folder chroma_db. Dokument statyczny przekształcił się w zakodowany, wyszukiwalny zasób.
Dodanie „głosu” za pomocą ask.py
Dokumentacja znajduje się teraz zakodowana w ./chroma_db. Brakuje jednak czegoś, co przyjmuje pytanie, szuka odpowiedzi i je udziela. Tym czymś jest ask.py – można go uruchomić w każdym momencie, gdy ktoś ma pytanie:
"""
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")
Próba działania
Zacznij od wywołania python ask.py i wpisz pytanie na przykład „Jak powinienem nazywać modele w fazie testowej?”. Skrypt przyjmuje również parametr --db do wskazania innego folderu Chroma oraz --k do zmiany liczby fragmentów pobieranych na jedno pytanie, co jest przydatne, gdy odpowiedzi wydają się pomijać kontekst. Ogólna odpowiedź internetowa lub wymyślona odpowiedź byłyby tutaj bezużyteczne. Zamiast tego otrzymujemy coś w stylu „Modele w fazie testowej powinny używać przedrostka stg_”. Skrypt nie zgadywał, a nikt nie musiał przeglądać strony 14 pliku PDF – znalazł właściwą zasadę i wyjaśnił ją w sposób typowy dla doświadczonego inżyniera.
Teraz spróbuj czegoś niezwiązanego, na przykład tego, jaka będzie pogoda w Paryżu w tym tygodniu. Asystent nie wymyśla odpowiedzi na podstawie ogólnej wiedzy. Sprawdza dostępny kontekst dokumentacji, widzi, że informacji tam nie ma, i szczerze mówi, że nie może odpowiedzieć na podstawie dostarczonej dokumentacji. Ta szczerość stanowi istotną część tego, co sprawia, że system jest godny zaufania w warunkach produkcyjnych.
Co zmienia się dla zespołu
To rozwiązanie dobrze sprawdza się nie tylko w przypadku dbt. Każdy podręcznik, instrukcja lub zbiór zasad w formacie PDF może zostać przetworzony za pomocą tych samych dwóch skryptów, a ponieważ embeddingi są uruchamiane lokalnie, tylko ostateczne pytanie oraz pobrane fragmenty trafiają do zewnętrznego API.
W dwóch plikach w Pythonie i kilku minutach 187 stron w większości ignorowanej dokumentacji stało się źródłem wiedzy dostępną w formie rozmowy. Nikt nie musi ręcznie odpowiadać na pytanie „jak nazwać modele testowe?” ani przeszukiwać Confluence w poszukiwaniu odpowiedniego linku. Asystent odpowiada natychmiast, opierając się na twoich rzeczywistych standardach.
Mimo to nadal funkcjonuje na laptopie. Naturalnymi kolejnymi krokami jest połączenie tego samego procesu z Slackiem, aby współpracownicy mogli wspominać o botie @dbt-assistant w miejscach, gdzie już pracują, oraz zautomatyzowanie procesu pobierania danych, tak by indeks aktualizował się za każdym razem, gdy zmienia się dokumentacja.
Literatura pokrewna
- Agent handlowy LangChain wspierany przez aktualne dane rynkowe EODHD, krok po kroku — Dlaczego agenci handlowe oparte na LLM zawodzą bez rzeczywistych danych, jak działa pętla ReAct oraz jak stworzyć agenta LangChain wykorzystującego trzy narzędzia do analizy cen EODHD, danych fundamentalnych i wskaźnika RSI.
- Agent medyczny, który łączy bazy danych SQLite z wyszukiwaniem w sieci — Stwórz agenta LangChain, który decyduje, czy pytanie medyczne wymaga zapytania SQL w trzech zbiorach danych, czy też aktualnego wyszukiwania w sieci, a także opisz dwa problemy, które zmieniły jego projekt.