Construir un RAG con LlamaIndex sobre tu documentación interna es uno de los proyectos de IA más rentables para un equipo de operaciones: runbooks, procedimientos de guardia, post-mortems y páginas de wiki duermen en carpetas que nadie relee en plena noche. Un asistente basado en LlamaIndex (RAG: generación aumentada por recuperación), capaz de encontrar el pasaje adecuado y de citar su fuente, ahorra minutos valiosos durante un incidente.
La trampa es conocida: un prototipo de RAG impresiona en la demo y luego responde a cualquier cosa en cuanto se le plantea una pregunta real. La diferencia entre ambos no está en el modelo, sino en la medición. Sin un conjunto de preguntas de referencia ni métricas de recuperación, se modifica el tamaño de los fragmentos o el modelo de embeddings a ciegas.
Este artículo muestra cómo montar un RAG con LlamaIndex autoalojado sobre una documentación interna y cómo evaluar después su calidad de forma reproducible. Forma parte de nuestra comparativa de piezas de IA de código abierto autoalojadas.
¿Por qué LlamaIndex para un RAG sobre documentación interna?
LlamaIndex es un framework de Python (existe también una versión en TypeScript) centrado en conectar datos con un LLM. Mientras otros frameworks se concentran en la orquestación de agentes, LlamaIndex pone el acento en la ingesta, el troceado, la indexación y la consulta de documentos. Es justo el núcleo de un RAG (Retrieval-Augmented Generation).
Sus piezas principales:
- Readers: cargan archivos (Markdown, PDF, HTML…) o fuentes externas mediante conectores;
- Node parsers: dividen los documentos en fragmentos (nodes) con sus metadatos;
- Index: el más habitual,
VectorStoreIndex, calcula embeddings y los guarda en un almacén vectorial; - Query engines y retrievers: recuperan los fragmentos pertinentes y construyen la respuesta;
- Módulo de evaluación: evaluadores listos para usar para la fidelidad, la pertinencia y la calidad de la recuperación.
El proyecto es modular: el núcleo se instala con llama-index-core, y cada integración (LLM, embeddings, base vectorial) es un paquete aparte. Para quedarse totalmente en el entorno interno, se puede usar un modelo servido localmente por Ollama.
Arquitectura objetivo: LlamaIndex, RAG y fuentes internas
Para una documentación de unos pocos miles de páginas basta una arquitectura sencilla:
- una exportación de la documentación en Markdown o HTML en una carpeta versionada;
- un script de ingesta que trocea, calcula los embeddings y persiste el índice;
- un servicio de consulta que carga el índice e interroga a un LLM local;
- un conjunto de evaluación que se vuelve a ejecutar con cada cambio de configuración.
El almacenamiento por defecto de LlamaIndex es en memoria, persistible en disco. Pasado cierto volumen, o para compartir el índice entre varias instancias, toma el relevo una base vectorial dedicada (Qdrant, pgvector, Chroma, etc.) mediante el paquete de integración correspondiente.
En la práctica: montar un RAG con LlamaIndex paso a paso
Paso 1: instalar los paquetes
Se instalan el núcleo y las integraciones de Ollama para el LLM y los embeddings. Comprueba los nombres exactos en la documentación, porque las integraciones evolucionan.
python -m venv .venv && source .venv/bin/activate
pip install llama-index-core llama-index-llms-ollama llama-index-embeddings-ollama
ollama pull llama3.1
ollama pull nomic-embed-text
Paso 2: configurar el LLM y el modelo de embeddings
El objeto Settings fija los valores por defecto que usan todos los componentes. El modelo de embeddings debe ser el mismo en la ingesta y en la consulta.
from llama_index.core import Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding
Settings.llm = Ollama(model="llama3.1", request_timeout=120.0)
Settings.embed_model = OllamaEmbedding(model_name="nomic-embed-text")
Settings.chunk_size = 512
Settings.chunk_overlap = 64
Paso 3: ingerir y persistir el índice
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
docs = SimpleDirectoryReader("./docs-internes", recursive=True).load_data()
index = VectorStoreIndex.from_documents(docs, show_progress=True)
index.storage_context.persist(persist_dir="./storage")
El lector conserva la ruta del archivo en los metadatos de cada fragmento: es lo que permitirá citar la fuente en la respuesta.
Paso 4: consultar y mostrar las fuentes
from llama_index.core import StorageContext, load_index_from_storage
ctx = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(ctx)
engine = index.as_query_engine(similarity_top_k=4)
resp = engine.query("Comment redémarrer le collecteur de logs en production ?")
print(resp)
for node in resp.source_nodes:
print(round(node.score or 0, 3), node.metadata.get("file_path"))
Mostrar siempre las fuentes y su puntuación es la primera medida de calidad: quien está de guardia debe poder comprobarlo con un clic.
Paso 5: construir un conjunto de evaluación
Dos enfoques se complementan. El primero: redactar a mano entre 30 y 50 preguntas reales (sacadas de los tickets o de los canales de guardia) con el documento esperado. El segundo: generar pares pregunta/contexto a partir de los fragmentos, con un generador de conjuntos de datos de LlamaIndex (por ejemplo DatasetGenerator del módulo de evaluación; las utilidades disponibles varían según las versiones), y revisarlos después. Las preguntas generadas suelen estar demasiado cerca del texto; las preguntas humanas revelan los huecos reales.
Paso 6: medir la recuperación y la generación
Se evalúan por separado las dos etapas del RAG:
- Recuperación: ¿figura el fragmento correcto en los resultados? El
RetrieverEvaluatorcalcula en particular el hit rate y el MRR (rango recíproco medio). - Generación: ¿es la respuesta fiel al contexto recuperado (
FaithfulnessEvaluator) y pertinente respecto a la pregunta (RelevancyEvaluator)?
from llama_index.core.evaluation import (
FaithfulnessEvaluator, RelevancyEvaluator, RetrieverEvaluator)
retriever = index.as_retriever(similarity_top_k=4)
ret_eval = RetrieverEvaluator.from_metric_names(
["hit_rate", "mrr"], retriever=retriever)
faith = FaithfulnessEvaluator()
relev = RelevancyEvaluator()
resp = engine.query(question)
print(faith.evaluate_response(response=resp).passing,
relev.evaluate_response(query=question, response=resp).passing)
Los evaluadores de generación usan a su vez un LLM como juez. Con un modelo local pequeño, sus veredictos son ruidosos: úsalos para comparar dos configuraciones sobre el mismo conjunto, no como una nota absoluta. Las firmas exactas pueden variar según la versión; la documentación oficial de LlamaIndex es la referencia.
¿Cómo medir la calidad de un RAG a lo largo del tiempo?
La evaluación sin conexión no basta. En producción cuentan tres familias de señales:
- Calidad percibida: opiniones de los usuarios (pulgar arriba o abajo), preguntas reformuladas justo después de una respuesta, tasa de respuestas «no lo sé»;
- Calidad de recuperación: distribución de las puntuaciones de similitud, proporción de consultas cuya mejor puntuación queda por debajo de un umbral (señal de un tema no documentado);
- Rendimiento y coste: latencia de recuperación y de generación por separado, tokens consumidos por consulta, tamaño del contexto inyectado.
LlamaIndex expone puntos de instrumentación que permiten enviar estos pasos como trazas de OpenTelemetry, mediante bibliotecas como OpenLLMetry u OpenInference. Detallamos la puesta en marcha en el artículo Langfuse y OpenLLMetry. Para enlazar estas trazas con el resto de tu aplicación, consulta también OpenTelemetry de extremo a extremo.
Buenas prácticas
- Limpia la fuente antes de indexar: las páginas obsoletas, los duplicados y los borradores degradan la calidad más que un mal modelo.
- Añade metadatos útiles (equipo propietario, fecha de actualización, entorno) y filtra por ellos en la consulta.
- Versiona juntos el índice, el modelo de embeddings, el tamaño de los fragmentos y el conjunto de evaluación.
- Cambia un solo parámetro cada vez y repite la evaluación completa.
- Respeta los derechos de acceso: un RAG no debe exponer una página que el usuario no podría leer.
- Pide al modelo que responda «no lo sé» si falta contexto suficiente, y mide esa tasa.
Preguntas frecuentes
¿LlamaIndex o LangChain para un RAG?
Los dos saben hacer RAG. LlamaIndex está más especializado en la ingesta y la indexación de documentos; LangChain y LangGraph están más orientados a la orquestación y a los agentes. Nuestro artículo LangChain y LangGraph detalla este segundo uso.
¿Hace falta una base vectorial dedicada?
No para empezar: la persistencia en disco basta para un prototipo. Una base dedicada resulta útil en cuanto el índice es voluminoso, se comparte entre varias instancias o se actualiza de forma continua.
¿Cuántas preguntas hacen falta para evaluar un RAG?
Unas pocas decenas de preguntas reales y representativas bastan para comparar configuraciones. Lo importante es mantener el mismo conjunto de una versión a otra y enriquecerlo con los fallos observados en producción.
Conclusión
Un RAG con LlamaIndex sobre documentación interna se monta en unas pocas decenas de líneas. Lo que lo hace fiable es la disciplina alrededor: fuentes limpias, conjunto de evaluación versionado, métricas de recuperación y de generación medidas por separado y, después, trazas en producción. Con estas barreras de seguridad, el asistente se convierte en una herramienta de guardia creíble y no en una simple demo.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y opciones en su documentación oficial.