Crea una Base de Conocimiento con IA para tu Equipo en 48 Horas (Guía Práctica)

El mes pasado, nuestro equipo de producto de 35 personas estaba ahogándose en documentación. Teníamos wikis, Google Docs, páginas de Confluence, bases de datos en Notion, hilos de Slack con decisiones críticas enterradas, y una carpeta compartida con cientos de PDFs donde nadie encontraba nada. ¿Te suena familiar?

Pasé un fin de semana construyendo una base de conocimiento impulsada por IA que permite a cualquier persona del equipo hacer preguntas en lenguaje natural y obtener respuestas precisas, extraídas de toda nuestra documentación. Tiempo total de construcción: unas 48 horas. Costo de operación mensual: $153 USD. El equipo pasó de "no encuentro ese documento" a "solo pregúntale a la base de conocimiento" en menos de una semana.

Aquí te explico exactamente cómo lo construí, paso a paso, con estimaciones de tiempo para que puedas planificar tu propia implementación.

Qué vamos a construir

La arquitectura se llama RAG — Generación Aumentada por Recuperación (Retrieval-Augmented Generation). En lugar de pedirle a un modelo de IA que sepa todo (no lo sabe), le alimentamos nuestros propios documentos y le permitimos buscar en ellos para responder preguntas. Piensa en ello como darle a ChatGPT acceso al cerebro de tu empresa.

El stack:

• Python 3.11+ — la columna vertebral
• LangChain — framework de orquestación para conectar LLMs a datos
• ChromaDB — base de datos vectorial para almacenar embeddings de documentos
• OpenAI Embeddings (text-embedding-3-small) — convierte texto en vectores buscables
• OpenAI GPT-4o-mini — genera respuestas a partir del contexto recuperado
• Streamlit — interfaz web rápida y limpia

Al final de este tutorial, tendrás un sistema funcional donde los usuarios escriben una pregunta, el sistema encuentra los fragmentos de documento más relevantes y un LLM sintetiza una respuesta con citas de origen.

Horas 0-2: Configuración del entorno y dependencias

Primero, vamos a estructurar el proyecto. Crea un nuevo directorio y configura un entorno virtual:

mkdir team-knowledge-base
cd team-knowledge-base
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

pip install langchain langchain-openai langchain-community
pip install chromadb
pip install streamlit
pip install python-dotenv
pip install pypdf docx2txt unstructured
pip install tiktoken

Crea un archivo .env para tu clave API:

OPENAI_API_KEY=sk-your-key-here

Y configura la estructura del proyecto:

team-knowledge-base/
├── .env
├── app.py              # Frontend de Streamlit
├── ingest.py           # Pipeline de procesamiento de documentos
├── query_engine.py     # Lógica de consulta RAG
├── config.py           # Configuración compartida
├── documents/          # Deja tus documentos aquí
│   ├── pdfs/
│   ├── markdown/
│   └── text/
└── chroma_db/          # Almacenamiento de la base de datos vectorial

Verificación de tiempo: esto debería tomar unos 30 minutos si estás familiarizado con entornos Python, hasta 2 horas si necesitas instalar Python y configurar las claves API.

Horas 2-8: Pipeline de ingesta de documentos

Esta es la parte más crítica de todo el sistema. La forma en que fragmentes tus documentos determinará la calidad de tus respuestas. Aprendí esto de la manera difícil: mi primer intento usó fragmentos ingenuos de 1000 caracteres y las respuestas eran basura.

La estrategia de fragmentación que realmente funciona

Después de probar cinco enfoques diferentes de fragmentación, esto es lo que mejor funcionó para nuestra documentación de formato mixto:

# config.py
CHUNK_SIZE = 1500        # caracteres por fragmento
CHUNK_OVERLAP = 200      # superposición entre fragmentos
EMBEDDING_MODEL = "text-embedding-3-small"
LLM_MODEL = "gpt-4o-mini"
COLLECTION_NAME = "team_knowledge"
CHROMA_DIR = "./chroma_db"

¿Por qué 1500 caracteres con 200 de superposición? A través de pruebas, encontré que:

• Demasiado pequeño (500 caracteres): Las respuestas carecen de contexto. El modelo obtiene un fragmento de oración y no puede sintetizar una respuesta útil.
• Demasiado grande (3000+ caracteres): La precisión de recuperación disminuye. Cuando un fragmento cubre múltiples temas, se recupera para consultas donde solo una parte es relevante, agregando ruido al contexto.
• 1500 caracteres: El punto ideal para párrafos de documentación típicos. La mayoría de las ideas completas caben dentro de esta ventana.
• 200 caracteres de superposición: Evita que las ideas que abarcan límites de fragmentos se pierdan. Crítico para listas numeradas e instrucciones paso a paso.

Ahora, aquí está el script de ingesta:

# ingest.py
import os
from dotenv import load_dotenv
from langchain_community.document_loaders import (
    PyPDFLoader,
    TextLoader,
    Docx2txtLoader,
    UnstructuredMarkdownLoader,
)
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from config import *

load_dotenv()

def load_documents(docs_dir="./documents"):
    'Load all supported document types from the directory tree.'
    documents = []
    loaders_map = {
        ".pdf": PyPDFLoader,
        ".txt": TextLoader,
        ".docx": Docx2txtLoader,
        ".md": UnstructuredMarkdownLoader,
    }

    for root, dirs, files in os.walk(docs_dir):
        for file in files:
            ext = os.path.splitext(file)[1].lower()
            if ext in loaders_map:
                file_path = os.path.join(root, file)
                try:
                    loader = loaders_map[ext](file_path)
                    docs = loader.load()
                    # Add source metadata
                    for doc in docs:
                        doc.metadata["source"] = file_path
                        doc.metadata["filename"] = file
                    documents.extend(docs)
                    print(f"  Loaded: {file} ({len(docs)} pages/sections)")
                except Exception as e:
                    print(f"  Error loading {file}: {e}")

    return documents

def chunk_documents(documents):
    'Split documents into overlapping chunks.'
    splitter = RecursiveCharacterTextSplitter(
        chunk_size=CHUNK_SIZE,
        chunk_overlap=CHUNK_OVERLAP,
        length_function=len,
        separators=["\n\n", "\n", ". ", " ", ""]
    )
    chunks = splitter.split_documents(documents)
    print(f"  Split {len(documents)} documents into {len(chunks)} chunks")
    return chunks

def create_vector_store(chunks):
    'Embed chunks and store in ChromaDB.'
    embeddings = OpenAIEmbeddings(model=EMBEDDING_MODEL)
    vector_store = Chroma.from_documents(
        documents=chunks,
        embedding=embeddings,
        collection_name=COLLECTION_NAME,
        persist_directory=CHROMA_DIR,
    )
    print(f"  Vector store created with {len(chunks)} embeddings")
    return vector_store

if __name__ == "__main__":
    print("Step 1: Loading documents...")
    docs = load_documents()
    print(f"  Total documents loaded: {len(docs)}")

    print("Step 2: Chunking documents...")
    chunks = chunk_documents(docs)

    print("Step 3: Creating vector store...")
    store = create_vector_store(chunks)

    print("Done! Knowledge base is ready.")

El RecursiveCharacterTextSplitter es clave aquí. Intenta dividir primero por saltos de párrafo (\n\n), luego por saltos de línea, luego por oraciones, luego por palabras. Esto significa que tus fragmentos casi siempre contendrán ideas completas en lugar de cortarse a mitad de una oración.

Manejo de diferentes tipos de documentos

Una nota rápida sobre los tipos de documentos, porque esto me causó problemas:

• PDFs: PyPDF funciona para la mayoría de los documentos, pero los PDFs escaneados necesitan OCR. Si tienes documentos escaneados, agrega pip install pytesseract y usa UnstructuredPDFLoader en su lugar.
• Google Docs: Exporta primero como .docx. La API de Google Drive puede automatizar esto, pero para el MVP, la exportación manual está bien.
• Confluence: Exporta espacios como HTML, luego usa UnstructuredHTMLLoader. Maneja el formato anidado sorprendentemente bien.
• Hilos de Slack: Este es el más difícil. Escribí un pequeño script que usa la API de Slack para exportar hilos marcados como archivos de texto. Eso es un tutorial aparte, pero la clave es incluir el contexto del hilo (nombre del canal, participantes, fecha) como metadatos.

Horas 8-16: Motor de consulta

Ahora la parte divertida: hacer que la base de conocimiento realmente responda preguntas.

# query_engine.py
import os
from dotenv import load_dotenv
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain.chains import RetrievalQA
from langchain.prompts import PromptTemplate
from config import *

load_dotenv()

# Custom prompt that enforces source citation
PROMPT_TEMPLATE = (
    "You are a helpful assistant for a product team.\n"
    "Use the following context to answer the question.\n"
    "If you do not know the answer based on the context, say so honestly.\n"
    "Always cite which document(s) you are drawing from.\n\n"
    "Context:\n{context}\n\n"
    "Question: {question}\n\n"
    "Answer (cite your sources):"
)

def get_query_engine():
    'Initialize and return the RAG query engine.'
    embeddings = OpenAIEmbeddings(model=EMBEDDING_MODEL)

    vector_store = Chroma(
        collection_name=COLLECTION_NAME,
        persist_directory=CHROMA_DIR,
        embedding_function=embeddings,
    )

    retriever = vector_store.as_retriever(
        search_type="mmr",           # Maximum Marginal Relevance
        search_kwargs={
            "k": 6,                  # Return top 6 chunks
            "fetch_k": 20,           # Consider top 20 before MMR filtering
            "lambda_mult": 0.7,      # Diversity vs relevance balance
        }
    )

    llm = ChatOpenAI(model=LLM_MODEL, temperature=0.1)

    prompt = PromptTemplate(
        template=PROMPT_TEMPLATE,
        input_variables=["context", "question"]
    )

    qa_chain = RetrievalQA.from_chain_type(
        llm=llm,
        chain_type="stuff",
        retriever=retriever,
        return_source_documents=True,
        chain_type_kwargs={"prompt": prompt}
    )

    return qa_chain

def query(question):
    'Query the knowledge base and return answer + sources.'
    engine = get_query_engine()
    result = engine.invoke({"query": question})

    sources = set()
    for doc in result.get("source_documents", []):
        sources.add(doc.metadata.get("filename", "Unknown"))

    return {
        "answer": result["result"],
        "sources": list(sources),
    }

Por qué MMR en lugar de una búsqueda de similitud simple

Quiero destacar la configuración search_type="mmr" porque marca una gran diferencia. La búsqueda de similitud estándar devuelve los 6 fragmentos más similares a tu consulta, pero esos 6 fragmentos podrían ser todos del mismo documento diciendo más o menos lo mismo. Eso es redundante y desperdicia tu ventana de contexto.

MMR (Maximum Marginal Relevance) equilibra la relevancia con la diversidad. Elige el primer fragmento basándose puramente en la similitud, luego para cada fragmento subsiguiente, penaliza los fragmentos que son demasiado similares a lo que ya se ha seleccionado. El resultado son 6 fragmentos que son todos relevantes pero cubren diferentes aspectos del tema.

El lambda_mult=0.7 controla este equilibrio: 1.0 es similitud pura (sin diversidad), 0.0 es diversidad pura (podría no ser relevante). Encontré que 0.7 es el punto ideal para las consultas de documentación.

Horas 16-24: Frontend de Streamlit

Es hora de hacerlo utilizable para personas que no tienen una terminal abierta todo el día.

# app.py
import streamlit as st
from query_engine import query, get_query_engine
import time

st.set_page_config(
    page_title="Team Knowledge Base",
    page_icon="search",
    layout="wide"
)

st.title("Team Knowledge Base")
st.markdown("Ask anything about our documentation, processes, or decisions.")

# Initialize the engine once
if "engine" not in st.session_state:
    with st.spinner("Loading knowledge base..."):
        st.session_state.engine = get_query_engine()

# Chat history
if "messages" not in st.session_state:
    st.session_state.messages = []

# Display chat history
for msg in st.session_state.messages:
    with st.chat_message(msg["role"]):
        st.markdown(msg["content"])
        if msg.get("sources"):
            with st.expander("Sources"):
                for src in msg["sources"]:
                    st.markdown(f"- {src}")

# Input
if prompt := st.chat_input("What would you like to know?"):
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    with st.chat_message("assistant"):
        with st.spinner("Searching knowledge base..."):
            start = time.time()
            result = query(prompt)
            elapsed = time.time() - start

        st.markdown(result["answer"])
        st.caption(f"Response time: {elapsed:.1f}s")

        if result["sources"]:
            with st.expander("Sources"):
                for src in result["sources"]:
                    st.markdown(f"- {src}")

        st.session_state.messages.append({
            "role": "assistant",
            "content": result["answer"],
            "sources": result["sources"],
        })

# Sidebar
with st.sidebar:
    st.header("About")
    st.markdown(
        "This knowledge base searches through all team "
        "documentation to answer your questions."
    )
    st.markdown("---")
    st.markdown("**Tips for better results:**")
    st.markdown("- Be specific with your questions")
    st.markdown("- Ask about one topic at a time")
    st.markdown("- If the answer seems off, try rephrasing")

Ejecútalo con streamlit run app.py y tendrás una base de conocimiento funcional con una interfaz de chat.

Horas 24-36: Haciéndolo realmente bueno

La versión básica funciona, pero esto es lo que agregué para que fuera apta para producción para un equipo de 35 personas:

1. Filtrado de metadatos

No todos los documentos son iguales. Una especificación de producto de la semana pasada es más relevante que una de hace dos años. Agregué metadatos basados en fechas a los fragmentos y modifiqué el recuperador para filtrar opcionalmente por rango de fechas o categoría de documento.

# En ingest.py, al cargar documentos:
doc.metadata["ingested_date"] = datetime.now().isoformat()
doc.metadata["category"] = determine_category(file_path)  # Basado en la estructura de carpetas

2. Bucle de retroalimentación

Agregué botones de pulgar hacia arriba/pulgar hacia abajo a cada respuesta y los registré en una base de datos SQLite. Después de una semana, tuve suficientes datos para identificar qué documentos estaban causando respuestas deficientes (generalmente porque estaban desactualizados o mal estructurados) y qué patrones de consulta necesitaban un mejor manejo.

3. Reingesta automática

Configuré un cron job que ejecuta el script de ingesta todas las noches en una carpeta sincronizada de Google Drive. Cuando alguien actualiza un documento, la base de conocimiento recoge los cambios en 24 horas. Para la unidad compartida, utilicé rclone para sincronizar con el servidor antes de que se ejecute la ingesta.

4. Control de acceso

Para nuestro equipo, esto no fue una gran preocupación (todos tienen acceso a todos los documentos), pero si lo necesitas, Streamlit admite la autenticación a través de streamlit-authenticator o puedes colocarlo detrás de un proxy OAuth como oauth2-proxy.

Horas 36-48: Pruebas, ajuste y despliegue

Metodología de prueba

Preparé un conjunto de prueba de 50 preguntas de las que conocía las respuestas. Luego categoricé las respuestas de la base de conocimiento:

• Correctas y bien fundamentadas: 38 de 50 (76%)
• Parcialmente correctas (idea correcta, faltan detalles): 7 de 50 (14%)
• Incorrectas: 2 de 50 (4%)
• Correctamente dijo "No sé": 3 de 50 (6%)

El 76% de precisión en el primer intento fue suficiente para lanzarlo. Después de ajustar el tamaño del fragmento, la superposición y el prompt, lo subí al 84%. Los errores restantes se debieron principalmente a preguntas ambiguas o documentos que contenían información contradictoria (lo cual es un problema de documentación, no un problema de IA).

Despliegue

Lo implementé en una pequeña máquina virtual en la nube (4GB de RAM, 2 vCPUs, aproximadamente $20 USD/mes). La configuración:

• Aplicación Streamlit ejecutándose detrás de un proxy inverso nginx
• SSL a través de Let's Encrypt
• Servicio systemd para reinicio automático
• ChromaDB almacenado en disco (no se necesita un servidor de base de datos separado)

Desglose de costos

Esto es lo que cuesta ejecutarlo para un equipo de 35 personas:

Eso es aproximadamente $4.37 USD por persona al mes. En comparación, las herramientas comerciales de IA para bases de conocimiento como Guru AI o Glean cuestan entre $15 y $25 USD por usuario al mes. Estamos ahorrando aproximadamente $370-720 USD/mes en comparación con las soluciones listas para usar, y tenemos control total sobre nuestros datos.

Lecciones aprendidas (a la fuerza)

El tamaño del fragmento importa más que la elección del modelo. Pasé horas probando diferentes LLMs cuando el verdadero problema era mi estrategia de fragmentación. Fragmentos malos, respuestas malas. Ningún modelo puede arreglar una recuperación de información deficiente.

Los metadatos no son opcionales. Cuando un usuario pregunta "¿cuál es nuestra política de reembolso?" y la base de conocimiento devuelve la política de reembolso de 2023 en lugar de la versión actualizada de 2026, eso es peor que no devolver nada. Los metadatos de fecha y la atribución de la fuente son esenciales.

La gente hace preguntas de manera diferente a como esperas. Asumí que la gente preguntaría cosas como "¿Cuál es el proceso de despliegue para el servicio X?". En cambio, preguntaban "¿cómo subo código?" y "¿dónde se ejecuta X?". La ingeniería de prompts necesaria para manejar preguntas casuales y vagas fue más trabajo de lo que anticipé.

Empieza con 20 documentos, no 2,000. Inicialmente intenté ingerir todo a la vez. Los costos de embedding se dispararon, la calidad fue inconsistente y la depuración fue dolorosa. Empieza pequeño, valida las respuestas y luego escala.

La respuesta "No sé" es una característica. Entrena al modelo (a través del prompt del sistema) para que diga "No tengo información sobre eso en la base de conocimiento" en lugar de adivinar. Los usuarios confían más en el sistema cuando es honesto acerca de sus limitaciones.

Problemas comunes y soluciones

"Las respuestas son demasiado genéricas." Aumenta el número de fragmentos recuperados de 4 a 6-8, y asegúrate de que tus fragmentos sean lo suficientemente grandes como para contener ideas completas. También verifica si la información relevante está realmente en tu conjunto de documentos.

"Sigue citando el documento equivocado." Tus embeddings podrían estar obsoletos. Vuelve a ejecutar el pipeline de ingesta. También verifica si tienes documentos duplicados o diferentes versiones del mismo documento en el sistema.

"Es lento." El principal cuello de botella suele ser la llamada al LLM, no la recuperación. Cambia a GPT-4o-mini si aún no lo has hecho (es más rápido y económico que GPT-4o con casi la misma calidad para tareas de preguntas y respuestas). También, considera almacenar en caché las preguntas frecuentes.

"Alucina." Baja la temperatura a 0.0-0.1 y agrega instrucciones explícitas en el prompt: "Solo responde basándote en el contexto proporcionado. Si el contexto no contiene la respuesta, dilo." Esto reduce drásticamente las alucinaciones.

¿Qué sigue?

Desde que implementamos esto hace tres semanas, nuestro equipo ha hecho más de 1,200 preguntas. Las consultas más populares son sobre procesos de despliegue, documentación de API y "quién decidió esto y por qué" (razón por la cual ingerir hilos de decisiones de Slack fue tan valioso).

A continuación, planeo agregar: memoria conversacional (para que las preguntas de seguimiento funcionen de forma natural), integración con Slack (hacer preguntas directamente en un canal) y detección automática de obsolescencia de documentos (marcar documentos que no se han actualizado en más de 6 meses pero que aún se están citando).

Construir esto tomó un fin de semana, pero el ahorro de tiempo se acumula cada día. Si tu equipo pasa más de 30 minutos a la semana buscando información, esto se paga solo casi de inmediato.