Головна / Статті

Асистент для документації у двох файлах Python: ChromaDB, LangChain та Claude

Перетворити 187-сторінковий PDF зі стандартами dbt на пошукового асистента з скриптом імпорту, локальними ембеддингами Hugging Face, ChromaDB та відповідями Claude, заснованими на документації.

Видавець: REACTAPP.TOP7 хв читання1539 слів

Джерела: 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 у тому місці, де вони вже працюють, а також автоматизація процесу отримання даних, щоб індекс оновлювався щоразу, коли змінюється документація.

Пов’язана література

  • Створення команди агентів для досліджень за допомогою LangGraph, DeepEval та GitLab CI — Як агенти-планувальники, дослідники та автори обмінюються інформацією в LangGraph, як DeepEval оцінює точність даних, та як Langfuse та GitLab CI забезпечують прозорість процесу.
  • Практичні нотатки: LangChain Серія 1: Розуміння моделей, запитів та ланцюгів — Детальний огляд Практичних нотаток: LangChain Серія 1: Розуміння моделей, запитів та ланцюгів: контракти, перевірки та готові фрагменти коду для команд, які використовують цю схему.
  • LangChain Skills: Завантажувати експертизу агента за потребою, а не за допомогою одного запиту — Припиніть вставляти всі правила в один системний запит. Дізнайтеся, як функції LangChain Skills використовують інструмент load_skill, стан та проміжне програмне забезпечення для введення інструкцій лише тоді, коли це необхідно.