LlamaIndex: Framework para aplicaciones RAG y agentes

Qué cubre este artículo

• Casos de uso de LlamaIndex y su arquitectura.
• Conceptos clave: Data Ingestion, Indexing, Query Engine y Agents.
• Cómo cargar documentos propios en un índice y consultarlos.
• Un flujo RAG local con Ollama y LlamaIndex.
• Cómo combinar agentes con tools y Query Engines.
• Errores comunes y obstáculos al comenzar.

Introducción

LlamaIndex es un framework open-source para Python que conecta Large Language Models con tus propios datos. Se enfoca en Data Ingestion, construcción de índices y responder preguntas sobre esos datos. Retrieval-Augmented Generation, o RAG, juega un papel central. En lugar de consultar un modelo solo con su conocimiento de entrenamiento, LlamaIndex busca pasajes de texto relevantes y los proporciona como contexto al LLM.

La arquitectura es modular. Puedes cargar documentos, dividirlos en fragmentos pequeños, calcular embeddings y almacenarlos en un Vector Store. A través de una Query Engine consultas el índice. Si además quieres automatizar decisiones, construyes agentes que seleccionan tools de forma autónoma. Esto convierte a LlamaIndex en una herramienta popular para aplicaciones impulsadas por datos.

¿Por qué necesito LlamaIndex?

Los modelos de lenguaje solo conocen lo que se incluyó en su entrenamiento. Tan pronto como quieras incorporar manuales específicos de la empresa, artículos científicos o documentación interna, un LLM puro no es suficiente. LlamaIndex te ayuda a preparar esta información y proporcionarla al modelo de manera dirigida.

La ventaja sobre una solución manual es la cantidad de componentes ya listos. Loaders para PDFs, archivos de texto y páginas web, diferentes splitters, múltiples integraciones de Vector Store y Query Engines preconstruidas te ahorran mucho tiempo. Además, tu código permanece legible porque el flujo se divide claramente en fases de carga, indexación y consulta.

LlamaIndex también funciona bien con modelos locales. Si usas Ollama, tus datos permanecen en tu máquina. Esto es particularmente interesante para contenido confidencial.

LlamaIndex en pocas palabras

El framework se estructura en varios niveles:

• Data Ingestion: Cargar documentos de diferentes fuentes y llevarlos a un formato uniforme.
• Node Parser: Dividir documentos grandes en chunks pequeños, llamados Nodes.
• Embeddings: Convertir texto en vectores que expresan similitud semántica.
• Index: Un contenedor que administra Nodes y sus vectores, por ejemplo un Vector Store Index.
• Retriever: Componente que devuelve los Nodes más relevantes para una pregunta.
• Query Engine: Combina retrieval y llamadas a LLM en una respuesta.
• Agent: Un ReAct agent o Function Agent que utiliza múltiples tools y Query Engines.
• Tool: Una función o Query Engine que un agent puede invocar.

La idea es simple: ingerir datos, encontrar fragmentos relevantes y alimentar el LLM de forma dirigida. El resultado es un sistema RAG que proporciona respuestas más actuales y precisas.

¿Para quién es este artículo?

Este artículo está dirigido a principiantes que ya tengan conocimientos básicos de Python. Deberías entender cómo funciona un modelo de lenguaje, pero no necesitas ser un experto en RAG. Si quieres aprender a conectar tus propios datos a un LLM, LlamaIndex es un buen punto de partida.

Los conocimientos sobre embeddings o bases de datos vectoriales ayudan, pero no son obligatorios. Lo más importante es la disposición a experimentar con pipelines y APIs. Si quieres profundizar en RAG, encontrarás información complementaria en RAG Grundlagen y Vektordatenbanken.

Términos importantes

Término	Significado
Document	Un documento cargado, por ejemplo de un archivo PDF o texto.
Node	Un pequeño fragmento de texto de un Document, típicamente un chunk.
Chunk	Un bloque de texto contiguo que se puede indexar por separado.
Embedding	Un vector que representa el significado de un texto en números.
Vector Store	Almacenamiento para embeddings que permite búsquedas de similitud.
Index	La estructura de datos que administra Nodes y sus vectores.
Retriever	Componente que encuentra Nodes relevantes según una query.
Query Engine	Conexión entre retriever, synthesizer y LLM para responder.
Agent	Sistema que elige pasos y tools de forma autónoma.
Tool	Una función o Query Engine que un agent puede invocar.

Instalación

Para la mayoría de los ejemplos, estos paquetes son suficientes. Asegúrate de tener Python 3.9 o superior:

pip install llama-index llama-index-llms-ollama llama-index-embeddings-ollama

Si quieres cargar PDFs, agrega:

pip install pypdf

Ollama debe estar ejecutándose y tener disponible al menos un modelo como llama3.2 y un modelo de embedding como nomic-embed-text. Puedes descargar los modelos con ollama pull llama3.2 y ollama pull nomic-embed-text.

Cargar datos e indexar

El primer paso es cargar y preparar los datos. LlamaIndex proporciona diferentes loaders que convierten archivos en objetos Document. Luego divides los contenidos en Nodes manejables y calculas embeddings.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.core.node_parser import SentenceSplitter
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

Settings.llm = Ollama(model="llama3.2", request_timeout=120.0)
Settings.embed_model = OllamaEmbedding(model_name="nomic-embed-text")

documents = SimpleDirectoryReader("data").load_data()

parser = SentenceSplitter(chunk_size=512, chunk_overlap=50)
nodes = parser.get_nodes_from_documents(documents)

index = VectorStoreIndex(nodes)
index.storage_context.persist(persist_dir="./storage")

SimpleDirectoryReader lee todos los archivos de una carpeta. SentenceSplitter garantiza que el texto se divida en chunks que tu modelo pueda procesar. El VectorStoreIndex almacena los embeddings asociados. Con persist guardas el índice localmente para reutilizarlo después.

Query Engine y RAG

Una vez que el índice está listo, lo consultas. La Query Engine se encarga del retrieval y generación de respuestas:

query_engine = index.as_query_engine()

antwort = query_engine.query("Was steht im Dokument zu den Kosten?")
print(antwort)

La Query Engine busca automáticamente los Nodes más similares y los proporciona como contexto al LLM. Puedes ajustar el comportamiento, por ejemplo aumentar el número de Nodes devueltos o usar solo las partes más similares:

query_engine = index.as_query_engine(similarity_top_k=5)
antwort = query_engine.query("Welche Schritte beschreibt die Anleitung?")
print(antwort)

Este patrón es el núcleo de un sistema RAG. Encontrarás más contexto en Lokales RAG y RAG Grundlagen. La forma en que los embeddings funcionan exactamente se explica en Embedding-Modelle.

Agentes con LlamaIndex

La capacidad de crear agentes es una de las fortalezas de LlamaIndex. Un agente puede usar múltiples herramientas: diferentes Query Engines, funciones de búsqueda o funciones Python personalizadas. El siguiente ejemplo muestra un agente ReAct simple que realiza multiplicaciones.

from llama_index.core.tools import FunctionTool
from llama_index.core.agent import ReActAgent

def multiply(a: float, b: float) -> float:
    """Multiply two numbers and return the product."""
    return a * b

tool = FunctionTool.from_defaults(fn=multiply)

agent = ReActAgent.from_tools([tool], llm=Settings.llm, verbose=True)
antwort = agent.chat("Was ist 12 mal 15?")
print(antwort)

El mismo agente puede recibir Query Engines completas como herramientas. Así combinas retrieval preciso con toma de decisiones dinámica. Para profundizar en el concepto de agentes, consulta ¿Qué es un agente de IA?.

LlamaIndex y LangChain comparados

LangChain y LlamaIndex tienen puntos en común pero énfasis distintos. LlamaIndex se especializa en conectar tus propios datos con LLMs. Los conceptos clave son Data Ingestion, Indexing y Query Engine. LangChain ofrece un conjunto más amplio de herramientas para chains, tools y agentes.

Para proyectos RAG puros, LlamaIndex suele estar listo para usar más rápido porque muchos pasos funcionan sin configuración adicional. Si necesitas workflows de agentes generales o chains más complejos, LlamaIndex funciona bien junto con LangChain. Ambos frameworks pueden combinarse también.

Errores comunes

• Clase de modelo incorrecta: Ollama y ChatOllama son diferentes. Para mensajes de chat necesitas clases que soporten el formato de chat.
• Timeout demasiado corto: Los modelos locales tardan más que las APIs en la nube. Aumenta request_timeout a unos 120 segundos.
• Chunks demasiado grandes: Si los Nodes superan el ventana de contexto, la información se trunca. Prueba diferentes valores de chunk_size.
• Retrieval con malos resultados: La calidad depende del modelo de embedding y del splitter. Elegir un modelo adecuado es más importante que tener muchos Nodes.
• Persistencia olvidada: Sin storage_context.persist pierdes el índice cuando termina el programa.
• Falta de manejo de errores: Las llamadas a API, especialmente con Ollama, pueden fallar por límites de tiempo o problemas de memoria. Incluye bloques try-except.
• Imports desactualizados: LlamaIndex cambia rutas de importación. Verifica la versión en los tutoriales e instala los paquetes correctos.

Hardware, costos y seguridad

LlamaIndex en sí es gratuito y Open Source. Los costos surgen de APIs en la nube o tu propio hardware. Para ejecución local pagas por RAM, GPU y electricidad, pero no por llamada. Un modelo 7B se ejecuta a menudo en 8 GB VRAM gracias a la cuantización. Modelos más grandes o muchas solicitudes paralelas requieren mucho más.

En RAG hay carga adicional por embeddings y el Vector Store. Esto es generalmente insignificante mientras el índice no sea extremadamente grande. La seguridad importa cuando procesas documentos sensibles. Para datos confidenciales usa modelos locales y controla los permisos del sistema de archivos. Encontrarás más consejos de seguridad en Ollama.

Enlaces relacionados

• Resumen de herramientas de desarrollo para frameworks relacionados.
• LangChain como alternativa para chains y agentes.
• RAG local para el contexto general.
• Fundamentos de RAG para la teoría.
• Bases de datos vectoriales para elegir un almacenamiento.
• Modelos de embedding para entender embeddings.
• Ollama para ejecución local de modelos.
• ¿Qué es un agente de IA? para conceptos de agentes.

FAQ

¿Es LlamaIndex gratuito?

Sí, el framework es Open Source. Los costos surgen solo de APIs, hosting en la nube o tu propio hardware.

¿Cuál es la diferencia entre LlamaIndex y LangChain?

LlamaIndex se enfoca en RAG, Data Ingestion e Indexing. LangChain es un framework más general para chains, tools y agentes.

¿Puedo ejecutar LlamaIndex localmente?

Sí. Con Ollama y modelos de embedding locales todos tus datos permanecen en tu máquina.

¿Qué formatos de datos soporta LlamaIndex?

PDFs, archivos de texto, Markdown, documentos Word, páginas web y muchos más a través de loaders adicionales.

¿Qué es un Node?

Un Node es un fragmento individual de un documento que puede almacenarse con un embedding.

¿Cómo elijo un modelo de embedding?

Considera el idioma y el dominio de tus datos. nomic-embed-text funciona bien localmente y es versátil.

¿Qué es una Query Engine?

La Query Engine combina retrieval y generación de respuestas: encuentra Nodes relevantes y llama al LLM con el contexto.

¿Cómo construyo un agente?

Creas tools a partir de funciones Python o Query Engines y los pasas a un ReActAgent.

¿Puedo guardar el índice?

Sí. Con storage_context.persist almacenas el índice localmente y lo cargas después.

¿Es suficiente Python 3.9?

Sí, se recomienda Python 3.9 o superior.

¿Qué tan rápido es RAG con LlamaIndex?

Depende del modelo, la cantidad de documentos y el hardware. Sistemas RAG locales pequeños suelen responder en segundos.

¿Hay alternativas?

Sí. LangChain, Haystack y DSPy son otras opciones.

Fuentes

• LlamaIndex Documentation: https://docs.llamaindex.ai/
• LlamaIndex GitHub: https://github.com/run-llama/llama_index
• Ollama LlamaIndex LLM Integration: https://docs.llamaindex.ai/en/stable/examples/llm/ollama/
• Ollama LlamaIndex Embeddings: https://docs.llamaindex.ai/en/stable/examples/embeddings/ollama/
• ReAct Agent Example: https://docs.llamaindex.ai/en/stable/examples/agent/react_agent/