Mi primer RAG

Este repositorio implementa un sistema RAG (Retrieval-Augmented Generation o Generación Aumentada por Recuperación) sobre una colección de documentos. Su objetivo es responder preguntas usando contexto recuperado de una base documental, en lugar de depender únicamente del conocimiento paramétrico del modelo.

¿Qué es un RAG?

Un sistema RAG combina dos piezas principales:

1. Retrieval: busca en una colección de documentos los fragmentos más relevantes para una pregunta.
2. Generation: usa un modelo de lenguaje para generar una respuesta apoyándose en esos fragmentos recuperados.

La idea es simple:

• primero se cargan y transforman documentos,
• luego se convierten en embeddings,
• después se comparan con la consulta del usuario,
• y finalmente un LLM redacta la respuesta usando el contexto encontrado.

Esto permite:

• responder sobre documentos privados o específicos,
• reducir alucinaciones frente a un LLM sin contexto,
• mantener el conocimiento actualizable sin reentrenar el modelo.

Cómo funciona este proyecto

En este repositorio el flujo general es el siguiente:

1. Carga de documentos

Los documentos fuente se cargan desde una carpeta de datos, en este caso data_cine, mediante un loader robusto. El objetivo es convertir archivos de entrada en una lista de documentos procesables.

2. Transformación en nodos

Los documentos completos se dividen en fragmentos más pequeños o nodos. Esto mejora la recuperación porque comparar preguntas contra trozos más pequeños suele producir resultados más precisos que hacerlo contra documentos enteros.

3. Indexación y embeddings

Cada nodo se vectoriza con el modelo de embeddings nomic-embed-text ejecutado a través de Ollama. Así se obtiene una representación numérica de cada fragmento para poder medir similitud semántica.

4. Persistencia en disco

Los nodos, embeddings y configuración se guardan en disco para no tener que recalcularlos en cada ejecución. Esto acelera mucho las consultas posteriores.

5. Consulta del usuario

Cuando el usuario hace una pregunta:

• la consulta se compara con los embeddings almacenados,
• se recuperan los nodos más parecidos,
• esos nodos se usan como contexto,
• y el modelo generativo produce una respuesta final.

6. Evaluación

El repositorio también incluye utilidades de evaluación para medir aspectos como:

• exact match,
• similitud semántica,
• faithfulness respecto al contexto recuperado,
• conciseness de la respuesta.

Esto convierte el proyecto no solo en un prototipo de RAG, sino también en una base para experimentar con calidad de recuperación y generación.

Arquitectura del repositorio

A nivel conceptual, el repositorio está organizado en varias etapas del pipeline:

• Loading/: carga de documentos fuente.
• Indexing/: transformación de documentos y generación de embeddings.
• Storer/: almacenamiento y recuperación desde disco.
• Querying/: búsqueda semántica y construcción de respuestas.
• scripts principales en la raíz: orquestan indexación, consulta y evaluación.

Flujo paso a paso

Construcción del índice

El script principal para construir el índice es main_build_index_true.py. Su secuencia es:

1. cargar el modelo de embeddings,
2. leer los documentos desde data_cine,
3. transformar documentos en nodos,
4. generar embeddings de esos nodos,
5. guardar todo en disco.

En otras palabras, esta fase prepara la base de conocimiento para poder consultar después.

Generación de respuestas

El script main_respuesta.py representa la fase de inferencia:

1. carga nodos, embeddings y configuración desde disco,
2. crea un motor de consulta,
3. lanza una pregunta,
4. recupera los nodos más relevantes,
5. envía pregunta + contexto al AnswerEngine,
6. imprime la respuesta final.

Ejemplo mental del pipeline

Si la pregunta del usuario fuera:

"¿Cómo funciona el cine?"

el sistema seguiría esta lógica:

1. convierte la pregunta en una representación semántica,
2. busca los fragmentos del corpus sobre cine más cercanos a esa representación,
3. selecciona, por ejemplo, los 3 mejores nodos,
4. construye un prompt con esos fragmentos,
5. genera una respuesta basada en ese contexto.

Requisitos y dependencias principales

Por lo que se observa en el código, este proyecto usa principalmente:

• Python
• Ollama
• llama_index
• numpy
• un modelo de embeddings como nomic-embed-text
• un modelo generativo como qwen2.5:1.5b

Además, para que funcione correctamente, debes tener disponibles en tu entorno los modelos de Ollama necesarios.

Cómo ejecutar el proyecto

1. Construir el índice

Ejecuta el script de indexación para generar nodos y embeddings persistidos:

python main_build_index_true.py

2. Lanzar una consulta

Una vez creado el índice, puedes generar una respuesta con:

python main_respuesta.py

3. Ejecutar evaluación

El repositorio contiene scripts adicionales para evaluar retrieval y respuestas, por ejemplo:

python main_eval_all.py

Qué aporta este repositorio para entender RAG

Este proyecto sirve para entender un RAG porque separa claramente las fases esenciales:

• ingesta de conocimiento,
• fragmentación en nodos,
• vectorización,
• almacenamiento,
• recuperación semántica,
• generación condicionada por contexto,
• evaluación del resultado.

Es decir, no se limita a “preguntar a un modelo”, sino que implementa la lógica completa de recuperación + generación.

Limitaciones actuales

A partir del código actual, parece haber varios puntos que podrías mejorar en el futuro:

• rutas absolutas que dificultan la portabilidad del proyecto,
• falta de instrucciones de instalación más detalladas,
• ausencia de ejemplos de salida documentados,
• falta de diagrama del pipeline,
• documentación escasa sobre las clases internas (Loader_robusto, Transformer, Indexer_robusto, QueryEngine, AnswerEngine).

Posibles mejoras

Algunas mejoras recomendables para este repositorio serían:

• añadir un requirements.txt o pyproject.toml,
• documentar la estructura exacta de carpetas y clases,
• eliminar rutas absolutas y sustituirlas por rutas relativas o variables de entorno,
• añadir ejemplos reproducibles de preguntas y respuestas,
• incluir métricas de evaluación y cómo interpretarlas,
• explicar mejor el formato de los datos de entrada.

Resumen

Sí: este repositorio implementa y deja entrever bastante bien qué es un RAG y cómo funciona, aunque no lo explica de forma clara en su documentación original.

En concreto, my_first_rag es el mejor candidato dentro de tus repositorios para documentar este tema porque:

• el propio nombre del repositorio lo indica,
• contiene scripts de indexación, consulta y evaluación,
• implementa las partes esenciales de un pipeline RAG real.

Este README.md deja el proyecto mucho más entendible para cualquier persona que llegue nueva al repositorio.