Inicio / Artículos

Un asistente para documentos en dos archivos de Python: ChromaDB, LangChain y Claude

Convertir un PDF de 187 páginas con las normas de dbt en un asistente con capacidad de búsqueda, mediante un script de ingestión, embeddings locales de Hugging Face, ChromaDB y respuestas de Claude basadas en los documentos.

Editor: REACTAPP.TOP7 min de lectura1539 palabras

Fuentes: How I Built an AI Agent That Reads Company Docs in 5 Minutes

La documentación estática conlleva un costo conocido: los colegas se ven interrumpidos con las mismas preguntas, los nuevos empleados no pueden encontrar las normas de dbt, y todos pierden tiempo al cambiar de contexto. La generación mejorada mediante recuperación de información soluciona gran parte de esto al permitir que la base de conocimientos se busque por su significado y no solo por palabras clave. Sin embargo, un plano no responde a preguntas; el código sí. Así que aquí hay un pequeño pipeline en Python que lee un documento de la empresa, crea un “cerebro” buscable a partir de él y proporciona a su equipo un asistente conversacional, todo en aproximadamente cinco minutos.

Todo consta de dos archivos:

  • ingest.py es el herramienta de creación. Úselo una vez para procesar la documentación y almacenarla en una base de datos.
  • ask.py es el asistente de voz. Úselo cada vez que alguien tenga una pregunta, y él devolverá una respuesta basada en la documentación.

Configuración

Hay dos cosas prioritarias: las bibliotecas y un lugar donde guardar la clave de API.

El archivo de requisitos

Las bibliotecas se encargan de cargar documentos, dividirlos en partes, generar embeddings, realizar búsquedas vectoriales y comunicarse con Claude. Crea requirements.txt en la carpeta del proyecto con esta lista:

# 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

Instale todo con pip install -r requirements.txt.

El archivo .env

Claude es la voz del agente, por lo que se necesita una clave de API de Anthropic. Nunca incluya claves de forma directa en los scripts de Python, ya que subirlas accidentalmente a GitHub representa un grave riesgo de seguridad. En su lugar, cree un archivo .env oculto en la raíz del proyecto y agregue la clave allí:

ANTHROPIC_API_KEY=your_actual_api_key_here

La biblioteca python-dotenv permite que los scripts lean ese archivo automáticamente en segundo plano.

Construyendo el “cerebro” con ingest.py

Un asistente debe leer el manual antes de poder responder preguntas. ingest.py se ejecuta una vez, o nuevamente cada vez que la documentación cambia. Su tarea es leer un PDF, dividirlo en partes comprensibles, convertir esas partes en vectores que capturen el significado y guardarlos en una base de datos. El script completo:

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.")

Qué hace el script, paso a paso:

  • Carga. PyPDFLoader lee el documento, en este caso un PDF de 187 páginas con estándares dbt.
  • División. No se puede pasar todo el contenido de un libro a un modelo de una sola vez, por lo que el texto se divide en bloques de 1000 caracteres, aproximadamente un párrafo cada uno. Un chunk_overlap de 200 caracteres evita que una regla que abarque dos párrafos quede dividida en dos partes.
  • Incrustación. El modelo utilizado es all-MiniLM-L6-v2, un modelo pequeño de código abierto de Hugging Face. Funciona en la CPU local, sin necesidad de usar una API en la nube de pago, y convierte cada bloque en un vector de 384 dimensiones.
  • Almacenamiento. Los vectores se guardan en ChromaDB, en una carpeta del disco en ./chroma_db.

Ejecútelo con python ingest.py. Después de unos segundos, aparecerá una nueva carpeta chroma_db en el proyecto. El documento estático se ha convertido en un almacenamiento codificado y buscable.

Dándole voz con ask.py

La documentación ahora se encuentra codificada en ./chroma_db. Lo que falta es algo que tome una pregunta, la busque y responda. Eso es ask.py; úsalo cada vez que alguien tenga una pregunta:

"""
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")

Probándolo

Comiéncelo con python ask.py e introduzca una pregunta como “¿Cómo debería nombrar los modelos de etapa intermedia?”. El script también acepta --db para indicar una carpeta Chroma diferente y --k para modificar la cantidad de fragmentos que se recuperan por pregunta, lo cual es útil cuando las respuestas parecen omitir el contexto. Una respuesta genérica o inventada sería inútil aquí. En su lugar, la respuesta es algo como “los modelos de etapa intermedia deben usar el prefijo stg_”. No hizo conjeturas, y nadie tuvo que buscar en la página 14 del PDF. Encontró la regla correcta y la explicó como lo haría un ingeniero senior.

Ahora pruebe algo no relacionado, como qué tiempo hará en París esta semana. El asistente no inventa una respuesta basada en conocimientos generales. Revisa el contexto de la documentación recuperada, ve que la información no está allí y dice honestamente que no puede responder con la documentación proporcionada. Esa honestidad es una parte importante de lo que hace que un sistema sea confiable en entornos de producción.

Qué cambia para el equipo

Este patrón se puede aplicar fácilmente más allá de dbt. Cualquier manual, guía de operaciones o conjunto de políticas basado en PDF puede pasar por los mismos dos scripts, y como los embeddings se ejecutan localmente, solo la pregunta final y los fragmentos recuperados se envían a una API externa.

En dos archivos de Python y en pocos minutos, 187 páginas de documentación en su mayoría ignorada se convirtieron en un experto con el que se puede conversar. Ya nadie tiene que responder manualmente a “¿cómo nombramos los modelos de preparación?” ni buscar en Confluence el enlace adecuado. El asistente responde al instante, basándose en sus estándares reales.

No obstante, todavía funciona en una laptop. Los siguientes pasos lógicos son conectar el mismo flujo de trabajo a Slack, para que los compañeros de equipo puedan mencionar al bot @dbt-assistant donde ya trabajan, y automatizar la ingesta para que el índice se actualice cada vez que cambie la documentación.

Leer más

  • Creando un equipo de agentes de investigación con LangGraph, DeepEval y GitLab CI — Cómo un agente planificador, investigador y escritor comparte estado en LangGraph, cómo DeepEval evalúa la fidelidad, y cómo Langfuse y GitLab CI mantienen honesto el proceso.
  • Notas prácticas: Serie 1 de LangChain: Entendiendo modelos, prompts y cadenas — Guía paso a paso de las Notas prácticas: Serie 1 de LangChain: Entendiendo modelos, prompts y cadenas: contratos, verificaciones y espacios de código listos para usar por parte de los equipos que implementan este patrón.
  • Habilidades de LangChain: Cargar la experiencia del agente bajo demanda, no en un solo prompt — Deje de incluir todas las reglas en un único prompt del sistema. Vea cómo las habilidades de LangChain utilizan una herramienta load_skill, estados y middleware para insertar instrucciones solo cuando es necesario.