Главная / Статьи

Ассистент для документации в двух файлах 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, состояния и промежуточные компоненты для внедрения инструкций только тогда, когда это необходимо.