Cursus — RAG against the machine pendiente

«Will you answer my questions?»: un sistema de Retrieval-Augmented Generation que indexa el código de vLLM, encuentra los fragmentos que responden a una pregunta y hace que un modelo pequeño y local conteste a partir de ellos. Proyecto del rank 04.

De dónde sale — Un modelo de lenguaje está congelado en el día en que terminó su entrenamiento: no sabe nada de la librería del mes pasado ni de tu código privado, y si le preguntas, o se calla o se lo inventa con total seguridad (las famosas alucinaciones). Reentrenarlo cada vez es carísimo, así que se hace trampa: en lugar de meterle más conocimiento, se le da acceso a una fuente externa en el momento de responder, igual que tú no te sabes el manual entero pero sabes qué página abrir. El término RAG viene de un artículo de Facebook AI de 2020 (Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks), pero la parte de buscar es mucho más antigua: es la recuperación de información clásica de los buscadores. El nombre es un juego con el grupo Rage Against the Machine.

En 42next este proyecto continúa a Call Me Maybe (rank 03), donde se vio la llamada a funciones con un modelo de lenguaje. El enunciado divide RAG en cuatro etapas, cada una alimenta a la siguiente: indexar (organizar los datos para buscar en ellos), recuperar (cruzar la pregunta con el índice y sacar los fragmentos más relevantes), aumentar (filtrarlos y meterlos en la ventana de contexto del modelo) y generar (leer ese contexto y producir la respuesta).

00Qué pide

Rank: 04Lenguaje: Python ≥ 3.10Equipo: no lo indica el enunciado (los repos públicos son individuales)Versión del enunciado: 2.0

Un sistema RAG que responde preguntas sobre un código fuente: ingerir el repositorio de vLLM (versión 0.10.1, adjunto al enunciado) en un índice, recuperar los fragmentos más relevantes para una pregunta, generar una respuesta con Qwen/Qwen3-0.6B y medir la calidad de la recuperación con recall@k. Se juzga si encuentra las ubicaciones correctas y si las respuestas se apoyan en ellas.

Reglas comunes de los proyectos Python de 42next (flake8, mypy, docstrings, excepciones controladas, Makefile con install, run, debug, clean, lint) y, además, propias de este proyecto:

01Indexar el código

Leer los ficheros de vLLM que consideres útiles, partirlos en trozos (chunks) y guardar en data/processed/ un índice que se pueda consultar en milisegundos. Indexar todo el corpus: como mucho 5 minutos.

Una idea de lo que mide TF-IDF, en su forma más básica (BM25 la refina con saturación de la frecuencia y normalización por longitud del documento):

tf(t, d)  = cuántas veces aparece el término t en el fragmento d
idf(t)    = log(N / nº de fragmentos que contienen t)
peso      = tf · idf     → alto si t abunda en d y escasea en el resto
Qué te obliga a aprender — Recuperación de información clásica. La idea del IDF es de Karen Spärck Jones (1972): una palabra que sale en todos los documentos no distingue ninguno. BM25 salió del sistema Okapi de la City University de Londres (Robertson, Spärck Jones y otros, años noventa) y sigue siendo la base de muchos buscadores. El troceado es la otra mitad: un fichero Python y una página Markdown no se rompen por los mismos sitios, y un fragmento cortado a mitad de una función o de una sección pierde el sentido. El enunciado avisa de algo más: las preguntas y el código rara vez usan las mismas palabras (una pregunta parafrasea o cita un identificador literal), y lo que guardes al indexar decide qué podrás encontrar luego.

02Recuperar

Dada una pregunta, devolver los top-k fragmentos más relevantes. Cada resultado es una ubicación: un file_path y el rango de caracteres que cubre (first_character_index, last_character_index), de como mucho 2000 caracteres. La ruta debe coincidir exactamente con la del corpus (por ejemplo data/raw/vllm-0.10.1/docs/features/lora.md): se compara literalmente.

Tiene que funcionar para una sola pregunta y en lote sobre un dataset de preguntas en JSON. Mínimos: 80 % de recall@5 en las preguntas de documentación y 50 % en las de código; y como mucho 90 segundos para 200 preguntas.

Qué te obliga a aprender — Que la búsqueda es un problema de ranking, no de coincidencia exacta, y que hay que medirlo: los umbrales están fijados y los comprueba un programa, no una impresión. Guardar los desplazamientos de cada chunk en el fichero original (no solo su texto) es lo que permite citar la fuente.

03Generar la respuesta

Con los fragmentos recuperados, generar una respuesta en lenguaje natural con Qwen3-0.6B, pasándole el contexto dentro de su presupuesto de tokens y produciendo JSON estructurado según los modelos pydantic. Una respuesta satisfactoria es coherente, se apoya en las fuentes recuperadas sin alucinaciones graves y responde a lo que se ha preguntado.

El enunciado reconoce que un modelo de 0,6 mil millones de parámetros tiene límites de razonamiento: esos criterios son el objetivo, no un aprobado/suspenso estricto. La nota prioriza la calidad de la recuperación, que la respuesta se base en el contexto y la estrategia de prompt, por delante de una redacción perfecta.

Qué te obliga a aprender — Cómo se usa un modelo de lenguaje desde código: tokens, ventana de contexto, plantilla de prompt, y por qué el contexto que le das importa más que el modelo. Si recuperas poco, falta la respuesta; si recuperas demasiado, la ahogas en ruido y te sales del presupuesto. Y todo en CPU, en local, sin API externa.

04Modelos de datos y salida

El enunciado da los modelos pydantic que validan lo que pasa entre etapas (se pueden ampliar con campos o modelos nuevos): MinimalSource (una ubicación), UnansweredQuestion y AnsweredQuestion, RagDataset, MinimalSearchResults y MinimalAnswer, y los contenedores StudentSearchResults y StudentSearchResultsAndAnswer (lista de resultados más el k usado). Cada comando escribe un JSON que cumple uno de ellos.

Qué te obliga a aprender — Contratos de datos entre componentes. pydantic convierte las anotaciones de tipo de Python, que normalmente solo mira mypy, en validación real en tiempo de ejecución: si un JSON no cuadra con el modelo, lo sabes al cargarlo y no tres etapas después. Es la misma idea que el formato estricto de la moulinette: si la salida no valida, no se puntúa.

05La CLI y el flujo completo

Todo se invoca como uv run python -m src <comando>. Comandos obligatorios:

comandoqué hace
indexingiere data/raw/ y crea el índice en data/processed/
searchtop-k fuentes para una pregunta
search_datasetbúsqueda sobre un dataset completo → JSON StudentSearchResults
answerresponde una pregunta con el contexto recuperado
answer_datasetrespuestas para un dataset → JSON StudentSearchResultsAndAnswer
evaluatetu propio recall@k contra un dataset con respuestas, para iterar

Ninguna ruta puede ir escrita en el código: todas son argumentos. La CLI se prueba con entradas degeneradas (pregunta vacía o sin sentido, k=0, ficheros que no existen, JSON mal formado) y nunca debe acabar en traceback. En la defensa se ejecuta automáticamente la cadena index → search_dataset → moulinette con unos scripts de referencia, así que hay que respetar la estructura del repo que fija el enunciado (src/, pyproject.toml y uv.lock en la raíz, data/raw/, data/processed/, data/datasets/…, data/output/…). La nota oficial la calcula el ejecutable de la moulinette que se da con el proyecto; tu código no puede importarlo ni llamarlo.

En el repo no van datos grandes, pesos del modelo ni salidas generadas: los genera el evaluador. El enunciado avisa de que la pila de deep learning y los pesos pueden ocupar varios gigas.

Qué te obliga a aprender — A construir algo que otro programa va a ejecutar sin ti delante: interfaz fija, rutas configurables, entorno reproducible con uv.lock. Fire genera la CLI a partir de las funciones y sus argumentos, así que la forma de tu código es la interfaz.

06Evaluación: recall@k

Para cada pregunta, recall@k es la fracción de sus fuentes correctas que aparecen entre tus k primeros resultados. Una fuente cuenta como encontrada si uno de tus resultados está en el mismo fichero y solapa su rango de caracteres con una IoU (intersección sobre unión) de al menos 0,05 — el listón es bajo: basta con un chunk que cubra la zona correcta. Un resultado en otro fichero nunca cuenta, de ahí que la ruta deba ser exacta. Rendimiento mínimo: indexar en 5 minutos o menos, 200 preguntas en 90 segundos o menos, recall@5 de 80 % (docs) y 50 % (código).

El README en inglés debe incluir, además de lo común: arquitectura del sistema, estrategia de troceado, método de recuperación, análisis de rendimiento (recall@k), decisiones de diseño, dificultades y ejemplos de uso.

Qué te obliga a aprender — Métricas de recuperación de información (recall, precisión, IoU) y a iterar con ellas: cambiar el tamaño de chunk o el troceado y medir el efecto, que es justo lo que el enunciado pide documentar. Mejorar «a ojo» no vale cuando hay un número.

+Bonus

Cinco, un punto cada uno, todos en CPU, y solo se miran si la parte obligatoria valida entera:

  1. Embeddings semánticos: un índice vectorial con un modelo ligero (como all-MiniLM-L6-v2) junto al léxico.
  2. Recuperación híbrida: combinar los rankings léxico y semántico en una sola lista.
  3. Indexado incremental: reindexar solo el fichero que cambia.
  4. Caché del índice y de las consultas.
  5. API HTTP local para consultar y responder sin la CLI.
Qué te obliga a aprender — Los embeddings resuelven lo que el léxico no puede: encontrar fragmentos que dicen lo mismo con otras palabras, porque comparan significados como vectores y no palabras. La búsqueda híbrida es lo que usan hoy la mayoría de sistemas RAG reales.

!Puntos delicados

srcFuente

El enunciado no está descargado en el pack. Se ha leído el PDF del enunciado (v2.0) subido al repositorio público de un estudiante, junto con el README de la moulinette del proyecto, y se ha contrastado con otros repos públicos del mismo proyecto (milestone 4 del nuevo common core), que describen lo mismo: vLLM, Qwen3-0.6B, BM25/TF-IDF, recall@k.

El enunciado oficial está en la página del proyecto en la intra (slug rag-against-the-machine).