Ассистент для документации в двух файлах 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 является голосом агента, поэтому требуется ключ API Anthropic. Никогда не вставляйте ключи напрямую в скрипты на 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читает документ — в данном случае 187-страничный PDF стандартов dbt. - Разбиение на части. Весь документ нельзя передать модели сразу, поэтому текст делится на блоки по 1000 символов, примерно по одному абзацу на блок. Параметр
chunk_overlapв 200 символов предотвращает разрезание правила, охватывающего два абзаца, пополам. - Встраивание. Используется модель
all-MiniLM-L6-v2— небольшая модель с открытым исходным кодом от Hugging Face. Она работает на локальном процессоре без необходимости в платных облачных 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: пошаговая инструкция — почему агенты для торговли на основе LLM терпят неудачу без реальных данных, как работает цикл ReAct и как создать агента LangChain с тремя инструментами, использующими цены EODHD, фундаментальные показатели и индикатор RSI.
- Медицинский агент, осуществляющий поиск между базами данных SQLite и веб-поиском — создание агента LangChain, который определяет, требуется ли для медицинского вопроса запрос к трем наборам данных через SQL или поиск в интернете, а также описание двух сбоев, из-за которых изменилась структура агента.