Cómo usar LlamaIndex: Una guía práctica desde cero hasta producción
Si alguna vez has intentado construir una aplicación de generación aumentada por recuperación (RAG) y has pensado: "¿Por qué conectar embeddings, almacenes de vectores y prompts es tan complicado?", no estás solo. LlamaIndex existe para que esa canalización sea rápida, sensata y esté lista para producción. En esta guía práctica y orientada a soluciones, te guiaremos a través de cómo usar LlamaIndex de principio a fin: ingestión de datos, indexación, consulta, evaluación e implementación, para que puedas entregar algo confiable sin perderte en código de pegamento.
Usaremos una estructura dirigida por preguntas con pasos progresivos, fragmentos ejecutables y consejos del mundo real. Ya sea que estés prototipando un chatbot para documentos internos o implementando un asistente de conocimiento para clientes, aprender a usar LlamaIndex de manera efectiva te ahorrará días.
: LlamaIndex es un framework que te ayuda a conectar tus datos a grandes modelos de lenguaje con herramientas de indexación, recuperación y orquestación, ideal para RAG, agentes y salidas estructuradas.
¿Qué es LlamaIndex y por qué usarlo?
- LlamaIndex es un framework de datos para aplicaciones LLM. Proporciona bloques de construcción para:
- Ingestión: Carga archivos, páginas web, bases de datos y APIs.
- Fragmentación e indexación: Convierte el contenido sin procesar en estructuras consultables (índices vectoriales, de palabras clave, de gráficos).
- Recuperación: Recupera contexto con estrategias flexibles (BM25, híbrida, reranking).
- Motores de consulta y agentes: Combina la recuperación, las herramientas y los prompts en una experiencia de preguntas y respuestas coherente.
- Evaluación y monitoreo: Juzga la calidad de la recuperación y la relevancia de las respuestas.
- Deseas una pila RAG robusta sin reinventar la fragmentación, los embeddings y la recuperación.
- Necesitas combinar múltiples fuentes de datos (PDFs + Notion + SQL).
- Te gustaría experimentar con la recuperación híbrida, el reranking o las salidas estructuradas.
- Modelo mental central al aprender cómo usar LlamaIndex:
- Datos → Nodos → Índice → Recuperador → Motor de consulta → Aplicación
Inicio rápido: El bucle RAG mínimo
Esta es la ruta más rápida hacia un prototipo funcional. Cargaremos documentos, construiremos un índice vectorial y haremos preguntas.
# 1) Instalar
# pip install llama-index llama-index-embeddings-openai llama-index-llms-openai
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
# 2) Configurar tu modelo + embeddings
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # o usar cualquier proveedor de LLM/embedding compatible
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Cargar documentos (p. ej., ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Construir un índice
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Crear un motor de consulta y hacer una pregunta
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("¿Cuáles son las prácticas de seguridad clave mencionadas en los documentos?")
print(response)
Esa es la esencia. A partir de aquí, las aplicaciones reales agregan una mejor fragmentación, reranking, prompts estructurados y observabilidad.
Ingestión: Trae tus propios datos (BYOD) de la manera correcta
Cuando estés decidiendo cómo usar LlamaIndex para datos reales, elige cargadores que coincidan con tus fuentes y preserven la estructura.
- Archivos:
SimpleDirectoryReader, lectores de PDF/HTML/Markdown
- Web:
BeautifulSoupWebReader, lectores de sitemaps
- SaaS: Notion, Confluence, Slack, Google Drive (a través de conectores)
- Bases de datos: SQL y bases de datos vectoriales (Pinecone, Weaviate, Chroma, Elasticsearch)
- Consejo: Normaliza los metadatos (título, autor, URL, created_at). Los buenos metadatos sobrecargan el reranking y el filtrado más adelante.
from llama_index.core import SimpleDirectoryReader
from llama_index.readers.web import SimpleWebPageReader
file_docs = SimpleDirectoryReader("./policies").load_data
web_docs = SimpleWebPageReader(html_to_text=True).load_data
all_docs = file_docs + web_docs
Fragmentación y analizadores de nodos: Basura entra, basura sale
Obtener la fragmentación correcta es uno de los pasos más importantes al aprender cómo usar LlamaIndex de manera efectiva.
- Por qué importa la fragmentación: Demasiado grande → hinchazón de tokens y recuperación irrelevante. Demasiado pequeño → fragmentación del contexto.
- Valores predeterminados: Razonables para muchos casos, pero ajusta para tu tipo de contenido.
- Documentos técnicos: Fragmentos de 512–1024 tokens con un 10–20% de superposición.
- Preguntas frecuentes: Fragmentos más pequeños (256–512) para mantener intactos los pares de preguntas y respuestas.
- Legal/Política: Fragmentos más grandes (1024–1536) para preservar definiciones + cláusulas.
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core import Document
parser = SentenceSplitter(chunk_size=800, chunk_overlap=100)
nodes = []
for d in all_docs:
nodes.extend(parser.get_nodes_from_documents([Document(text=d.text, metadata=d.metadata)]))
Estrategias de índice: ¿Vectorial, de palabras clave o híbrido?
Elegir el índice correcto es crucial. La buena noticia: LlamaIndex te permite combinarlos.
- Índice vectorial: Excelente para la búsqueda semántica. Mejor para “explicar X” o consultas difusas.
- Palabra clave (BM25): Fuerte para términos exactos, IDs, códigos de error, registros.
- Híbrido: Combina ambos; vuelve a clasificar los principales candidatos con un LLM o codificador cruzado.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Índice vectorial de nodos pre-analizados
v_index = VectorStoreIndex(nodes)
# Recuperador de palabras clave BM25
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Híbrido: fusionar candidatos, luego volver a clasificar
from llama_index.core.retrievers import RouterRetriever
from llama_index.retrievers.merge import MergerRetriever
v_retriever = v_index.as_retriever(similarity_top_k=6)
hybrid = MergerRetriever(retrievers=[v_retriever, bm25_retriever], top_k=8)
query_engine = RetrieverQueryEngine.from_args(retriever=hybrid)
Reranking y filtros: Aumenta la precisión sin pagar de más
El reranking mejora la calidad de la respuesta al reordenar los fragmentos recuperados según la relevancia.
- Cuándo volver a clasificar: Si los usuarios informan citas fuera de tema o contextos largos y acolchados.
- Codificadores cruzados (búsqueda de embeddings bi-codificador → reranking de codificador cruzado)
- Reranking basado en LLM (más costoso, a veces más inteligente en texto matizado)
- Filtros de metadatos (p. ej.,
source == 'handbook', created_at > 2024-01-01)
from llama_index.postprocessor.flag_embedding_reranker import FlagEmbeddingReranker
from llama_index.core.query_engine import RetrieverQueryEngine
reranker = FlagEmbeddingReranker(top_n=5, model="BAAI/bge-reranker-base")
query_engine = v_index.as_query_engine(
similarity_top_k=12,
node_postprocessors=[reranker]
)
Prompts y motores de consulta: De la búsqueda a las respuestas
Un motor de consulta es donde la recuperación se encuentra con la generación. Para dominar cómo usar LlamaIndex en producción, diseña prompts y la síntesis de respuestas cuidadosamente.
- Estrategias de síntesis de respuestas:
- Simple “stuff” (concatenar) para contextos pequeños
- Árbol o map-reduce para contextos más largos
- Modo de cita para mostrar las fuentes
from llama_index.core.response_synthesizers import get_response_synthesizer
from llama_index.core import ServiceContext
synth = get_response_synthesizer(response_mode="tree_summarize")
query_engine = v_index.as_query_engine(response_synthesizer=synth)
ans = query_engine.query("Resume los pasos de incorporación y cita las fuentes.")
print(ans)
- Prompts personalizados: Adapta el tono, las salidas estructuradas o las barreras de protección.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Eres un asistente conciso y basado en evidencia. Usa solo el contexto proporcionado.
Si no estás seguro, di que no lo sabes. Devuelve JSON con las claves: answer, sources.
Question: {query_str}
Context: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agentes y herramientas: Cuando la recuperación no es suficiente
A veces, las respuestas requieren acciones: ejecutar SQL, llamar a APIs o navegar. Los agentes de LlamaIndex coordinan las herramientas y el razonamiento con tu canalización de recuperación.
- Casos de uso: Paneles de KPI (herramienta SQL), bots de soporte (API de búsqueda de tickets), agentes de investigación (web + RAG).
from llama_index.core.agent import ReActAgent
from llama_index.tools.sql import SQLQueryEngineTool
from sqlalchemy import create_engine
engine = create_engine("sqlite:///analytics.db")
sql_tool = SQLQueryEngineTool.from_engine(engine)
agent = ReActAgent.from_tools([sql_tool], llm=llm, verbose=True)
agent.chat("¿Cuál fue la rotación mensual en el segundo trimestre de 2025? Si es necesario, consulta la base de datos.")
Evaluación: No envíes a ciegas
Aprender a usar LlamaIndex de manera responsable significa validar tanto la recuperación como las respuestas antes del lanzamiento.
- Evaluación offline: Juzga la recuperación/precisión de la recuperación en un conjunto etiquetado.
- Evaluación online: Registra los prompts de los usuarios, mide la satisfacción, las tasas de desviación y las alucinaciones.
- Funciones integradas: LlamaIndex proporciona ayudantes de evaluación para la fidelidad y la relevancia de las respuestas.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("Enumera las familias de control SOC 2 en nuestra política.")
print("¿fiel?", faith.evaluate_response(pred))
print("¿relevante?", rel.evaluate_response(pred))
- Barra práctica: Para los asistentes internos, apunta a una calificación de >80% “útil” en las principales consultas antes del lanzamiento general.
Persistencia y almacenes de vectores: Hazlo escalable
Los índices construidos en la memoria no serán suficientes para cargas de trabajo reales. Persiste en una base de datos vectorial y habilita actualizaciones incrementales.
- Backends populares: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Consejo: Usa espacios de nombres por inquilino o departamento; mantén los metadatos enriquecidos.
# Ejemplo: Chroma
# pip install chromadb llama-index-vector-stores-chroma
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext
import chromadb
chroma_client = chromadb.PersistentClient(path="./chroma_store")
collection = chroma_client.get_or_create_collection("company_knowledge")
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(all_docs, storage_context=storage_context)
Seguridad y gobernanza: La parte que todos olvidan
- Manejo de PII: Redacta o hashea los campos confidenciales durante la ingestión.
- Controles de acceso: Filtra por roles de usuario con restricciones de metadatos.
- Frescura del contenido: Programa la re-ingestión; marca las versiones.
- Seguridad: Agrega políticas de rechazo y restricciones de solo fuente en los prompts.
# Ejemplo: filtrado basado en metadatos en tiempo de consulta
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Del prototipo a la producción: Patrones de implementación
- Patrón de servidor: Expone un endpoint
/query; mantén el índice activo en la memoria.
- Advertencia sin servidor: Los arranques en frío + los modelos grandes pueden perjudicar la latencia; considera la inferencia administrada.
- Almacenamiento en caché: Almacena en caché los embeddings y los resultados de consultas frecuentes; habilita actualizaciones parciales.
- Observabilidad: Registra los nodos recuperados, el uso de tokens, la longitud de la respuesta y los comentarios de los usuarios.
# Envoltorio mínimo de FastAPI
# pip install fastapi uvicorn
from fastapi import FastAPI
app = FastAPI
qe = index.as_query_engine(llm=llm)
@app.post("/query")
async def query(payload: dict):
q = payload.get("q", "")
resp = qe.query(q)
return {"answer": str(resp), "sources": [s.node.metadata for s in resp.source_nodes]}
Planos técnicos del mundo real: Elige tu camino
- Asistente de políticas internas
- Índice: Híbrido (BM25 + Vectorial) con reranking
- Barreras de protección: Modo de solo fuente; fallback “No lo sé”
- KPI: Tasa de resolución para preguntas sobre políticas
- Copiloto de atención al cliente
- Índice: Documentos del producto + notas de la versión + tickets
- Agentes: Herramienta API para verificar el estado del pedido/ticket
- KPI: Resolución de primer contacto, desviación, CSAT
- Analista de investigación
- Índice: Web + PDFs + notas; fuerte deduplicación
- Reranking: Codificador cruzado; síntesis: map-reduce
- KPI: Tiempo para la información; precisión de la cita
- Herramientas: Motor SQL + RAG en definiciones de métricas
- Gobernanza: Políticas a nivel de fila; auditoría de consultas
- KPI: Corrección vs. verdad fundamental
Costo y latencia: Mantenlo rápido (y barato)
- Embeddings: Procesa por lotes siempre que sea posible; usa modelos más pequeños para la recuperación, vuelve a clasificar selectivamente.
- Tamaño del contexto: Apunta a 1–2k tokens de los fragmentos más relevantes.
- Almacenamiento en caché: Almacena en caché la recuperación top-K para consultas frecuentes; memoriza las llamadas LLM con prompts hasheados.
- Paralelismo: Expande la recuperación → contrae el reranking para reducir la latencia de la cola.
Errores comunes al aprender cómo usar LlamaIndex
- Sobre-fragmentación, lo que lleva a una recuperación superficial y ruidosa
- Sin filtros de metadatos, lo que hace que se filtren fuentes irrelevantes
- Confiar en un solo tipo de índice para todo el contenido
- Omitir la evaluación; enviar sin una barra de calidad
- Dejar que los índices se vuelvan obsoletos; sin actualización programada
Por cierto: Acelera tu flujo de trabajo en el editor
A medida que iteras en los prompts, los fragmentadores y la configuración de recuperación, vale la pena señalar que una barra lateral de codificación e investigación de IA como Sider.ai puede acelerar el bucle. Puedes mantener fragmentos, prompts y notas de evaluación a mano, generar diferencias de cambios de prompt y probar rápidamente variaciones sin salir de tu navegador. Esto es especialmente útil cuando estás ajustando cómo usar LlamaIndex en diferentes estrategias de recuperación. Lista de verificación paso a paso: De cero a producción
- Ingiere fuentes y normaliza los metadatos
- Ajusta los tamaños de los fragmentos por tipo de contenido
- Construye índices vectoriales + BM25; habilita la recuperación híbrida
- Agrega reranking y filtros de metadatos
- Personaliza los prompts; habilita las citas y la política de rechazo
- Evalúa la fidelidad y la relevancia en un conjunto de prueba
- Persiste en un almacén de vectores; habilita actualizaciones incrementales
- Agrega observabilidad, almacenamiento en caché y filtros RBAC
- Envuelve en una API y establece SLAs; documenta los modos de falla
Conclusiones clave
- Si deseas una aplicación RAG robusta, aprender a usar LlamaIndex te ahorrará semanas de ingeniería de pegamento.
- Comienza de forma sencilla, luego agrega recuperación híbrida, reranking y prompts estructurados.
- Evalúa antes de escalar; persiste los índices y monitorea la calidad en producción.
- Diseña para la gobernanza desde el primer día: la seguridad no es un complemento.
Próximos pasos
- Prototipa el inicio rápido en un pequeño conjunto de documentos.
- Experimenta con la recuperación híbrida y un reranker.
- Agrega evaluación y citas; rastrea las métricas de calidad.
- Muévete a un almacén de vectores persistente e implementa una API.
Preguntas frecuentes
P1: ¿Para qué se usa LlamaIndex en aplicaciones RAG?
LlamaIndex te ayuda a conectar tus datos a LLMs con componentes de ingestión, indexación y recuperación. Agiliza la construcción de sistemas RAG al manejar la fragmentación, los índices vectoriales/de palabras clave y la orquestación de consultas.
P2: ¿Cómo elijo el tipo de índice correcto en LlamaIndex?
Usa un índice vectorial para consultas semánticas, BM25 para coincidencias exactas como IDs o códigos, y un enfoque híbrido para la mejor recuperación y precisión general. Muchos equipos combinan ambos y agregan reranking para los resultados top-K.
P3: ¿Cómo puedo mejorar la precisión al usar LlamaIndex?
Ajusta los tamaños de los fragmentos, incluye metadatos enriquecidos, habilita la recuperación híbrida y añade un reranqueador. También implementa la evaluación de la fidelidad y la relevancia, y utiliza el modo de citación para mostrar las fuentes.
P4: ¿Puede LlamaIndex funcionar con mi base de datos vectorial existente?
Sí. LlamaIndex se integra con almacenes de vectores populares como Pinecone, Weaviate, Chroma, Qdrant y Elasticsearch. Persiste los índices para la escalabilidad y las actualizaciones incrementales.
P5: ¿Cómo implemento una aplicación LlamaIndex en producción?
Envuelve tu motor de consulta en una API (por ejemplo, FastAPI), persiste los datos en un almacén de vectores, añade almacenamiento en caché y observabilidad, y evalúa la calidad continuamente. Aplica filtros de metadatos y control de acceso para la seguridad.