Асістэнт па дакументацыі ў двух файлах Python: ChromaDB, LangChain і Claude
Ператвараем 187-старонкавы PDF са стандартамі dbt у асістэнта з пошукам: скрыпт загрузкі, лакальныя эмбедынгі Hugging Face, ChromaDB і адказы Claude, абгрунтаваныя дакументацыяй.
Крыніцы: How I Built an AI Agent That Reads Company Docs in 5 Minutes
Статычная дакументацыя мае знайомыя наследкі. Колегі прынуджаны адпавядаць на тыя ж запытанні, новыя спецыялісты не можуць знайсці стандарты dbt, а всі трацяюць час на змену кантэксту. Тэхнологія Retrieval-augmented generation часткова рашыляе гэтыя проблемы, адколі дазволяе шукаць інформацыю ў базе знанняў па значэнні, а не толькі па ключоўым слову. Аднак план не адпавядае на запытанні; код — так. Таму ўсёрэшце ёсць невялікі Python-пайплайн, які чытае корпоратыўны дакумент, стварае з яго можна шукаць «мозг» і дае вашай командзе асістэнта для дыялогу, і ўсё гэта за апошнія пяць хвілін.
Усё гэта складаецца з двух файлаў:
ingest.py— гэта інструмент для стварэння. Запускайце яго адназначна, каб апрацуе дакументацыю і зберагчы яе ў базе дадзеных.ask.py— гэта асістэнт. Запускайце яго кожны раз, калі у каго-небудзь ёсць запытанне, і ён будзе вяртаць адпаведны адказ на адвароце з дакументацыі.
Настройка
Перш за ўсё неабходныя бібліятэкі і месца для зберагчэння ключа API.
Файл захадаў
Бібліятэкі абавязковыя для завантажэння дакументаў, ўдзелавання іх, стварэння эмбеддынгаў, вектарнага пошуку і взаімадзеяння з Claude. Створыце файл requirements.txt у папцы праекта з гэтым спіскам:
# 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
Установіце все за дапамою pip install -r requirements.txt.
Файл .env
Claude ўособлівае голас агента, таму патрэбны ключы Anthropic API. Ніколі не включайце ключы безпосерэдна ў скрыпты на Python, адтак як ўпуск такога ключа ў GitHub па адной працы ёсць серьёзным рызыкам для безпекі. Узамест таго стварыце схованы файл .env у корні праекту і дадзіце туды ключ:
ANTHROPIC_API_KEY=your_actual_api_key_here
Бібліятэка python-dotenv дазвае скрыптам автаматычна, у фонавым рэжыме, чытаць гэты файл.
Стварэнне „мозга“ за дапамою ingest.py
Памочнік павінен прачытаць інструкцыю, прытымкі як можа адпавядаць на запытанні. ingest.py запускаецца адназначы, альбо знову кожны раз, калі змянюецца дакументацыя. Яго задача — прачытаць PDF, разлучыць яго на зрозумелыя часткі, ператворыць гэтыя часткі на вектары, якія фіксуюць значэнне, і сахаваць іх у базе дадзэння. Полны скрыпт:
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.")
Што робіць скрыпт, па кроках:
- Зачытанне.
PyPDFLoaderчытае дакумент, у гэтым случае PDF стандарта dbt з 187 стороніцамі. - Разбіўка. Весь кнігу нельга перэдаць модэлю заодно, таму тэкст раздзеляецца на блакі з 1000 сімвалів, прыблізна по аднам параграфу кожны. Параметр
chunk_overlapу розмерэ 200 сімвалів запобегае таму, каб правіла, якія распаўляюцца між двума параграфамі, не былі розрываныя на два часткі. - Вбудовванне. Модэль —
all-MiniLM-L6-v2, маленькі адкрытыя код модэль з Hugging Face. Ён працюе на локальным CPU без неабяжлівай платной хмарнай API і ператварае кожны блак у вектар з 384 вымірамі. - Зберагчыце. Вектары зберагаюцца ў ChromaDB, у папку на дыску пад адрэсай
./chroma_db.
Запускайце яго за дапамою python ingest.py. Чыраз секундаў у праекце з’яўляецца новы папака chroma_db. Статычны дакумент стаў закодаваным, можна шукаць у ім інфармацыю.
Надаўанне голасу за дапамою ask.py
Дакументацыя цяпер знаходзіцца закодаваная ў ./chroma_db. Недастаее таго, што б прымала запіт, шукала інфармацыю і адпавядала. Цэе і ёсць ask.py — яго можна запускаць кожны раз, калі хтось мае запыт:
"""
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")
Практычныя прыемы
Запускайце яго за дапамою python ask.py і введзіце запіт, напрыклад, "Як мне называць мадэлі стадыйнага тэставання?" Скрыпт таксама падтрымлівае параметры --db для выбору іншай папкі Chroma і --k для змены колькасці фрагментаў, якія беруцца за адны запіт, што ўжоць корыстна, калі адпаведзі здаюцца неадэкватнымі ў кантэксце. Узвычайныя веб-адпаведзі або выдуманыя тут будуць бесполезныя. Адпаведзь выходзіць працоўна ў такім родзе: "Мадэлі стадыйнага тэставання трэба называць з прымэткай stg_." Скрыпт не здагадваўся, і нікому не патрэбна была шукаць у 14-й сторонцы PDF. Ён знайшоў правілы і поясніў іх так, як бы гэта зрабіў кансультант з высокым досвядам.
Цяпер спробуйце ўзняць кашто-што несувязанае, напрыклад, якая будзе погода ў Парыжы за гэты тыдзень. Асістэнт не выдумвае адпаведзення на адвагу загальных знаёмасцей. Ён пераглядае кантэкст атрыманай дакументацыі, бачыць, што інфармацыі там няма, і чыста сказвае, што не можа адпаведзець на пытанне на адвагу наданай дакументацыі. Гэта чыстасць ў вялікай меры ўскладнівае тое, што робіць сістэму надзеянай у практычнай експлуатацыі.
Што змініцца для каманды
Гэты патэрн добра праіменяецца не толькі для dbt. Будзь-які посібнік, інструкцыя чыста політыка, напісаныя у фармаце PDF, можа праходзіць праз тыя ж два скрыпты, і адтуды, што інтэграцыі выкананы локальна, толькі фінальнае пытанне і атрыманыя фрагменты падаюць у зовнішні API.
У двух файлах на Python і за калькольнах хвілінакоў 187 сторонік дакументацыі, якія здавольна застаўаліся без увагі, сталі справжнім экспертом у спілкуванні. Нікому больш не трэба вручную адпавядаць на запытанне „Як называць мадэлі стэйджынгу?“ чысташукваць у Confluence у пошуках правільнага паўязу. Асістэнт адпавядае мгновенна, адпаведна да вашых рэальных стандартаў.
Пры тым ён яшчэ застаецца на ноутбуку. Наступныя логічныя крокі — падключыць той самы пайплайн да Slack, ўпэўніўшыся, што колегі могу паводзіць мову пра бота @dbt-assistant у таму месцы, дзе яны ведуць працу, а таксама автаматызаваць працэс прыёму даных, каб індэкс апошні раз апдэйтаваўся ў момент змены дакументацыі.
Спадневаная літэратура
- LangChain-аўтамат з трыбутамі рынку EODHD: паследоўныя крокі — чаму аўтаматы для трыбутавання на аднойчынных нейронных сетках не функцыонуюць без рэальных дадзэнняў, як працюе цыкл ReAct, і як стварыць аўтамата LangChain з трыма інструментамі на аднойчынных дадзэннях EODHD, фундаментальных паказніках і індыкатары RSI.
- Медычны аўтамат, які выкарыстоўвае базы дадзэння SQLite і пошук у інтэрнэце — стварэнне аўтамата LangChain, які вяршыць рашэнне, чы рэшэнне медычнага пытання вымагае SQL-запыту ў трох кантэйнерах дадзэнняў чы рэальнага пошуку ў інтэрнэце, а таксама два прыклады сутычак, якія змянілі дызайн.