Inspección: ¿qué chunks recuperó?

La pregunta clave

Tu RAG corre. Te devuelve respuestas. Pero ¿son buenas las respuestas? Y si no lo son — ¿el problema es del retriever o del LLM?

Sin saber distinguir esas dos cosas, vas a estar tuneando a ciegas. Vamos a aprender a leerlo.

Lo que ya estás viendo

Cada vez que corrés pnpm vercel:query "...", la salida termina con:

=== Sources ===
  - clean-architecture.md (score: 0.7234)
  - hexagonal-architecture.md (score: 0.6118)
  - solid-principles.md (score: 0.5891)
  - screaming-architecture.md (score: 0.5102)

Ese bloque es oro puro. Lee tres cosas:

1. ¿Los archivos son los esperados? Si preguntaste sobre Clean Architecture y aparece primero solid-principles.md, ya tenés un problema de retrieval.
2. ¿El score top-1 está arriba de 0.65? Si no, la pregunta está mal planteada o el corpus no cubre el tema.
3. ¿La diferencia entre top-1 y top-K es grande? Si todos los scores están parejos (~0.55), el retriever no está discriminando — probablemente la query es ambigua.

El árbol de decisión del debugging

Cuando una respuesta es mala, no la culpes al LLM ciegamente. Aplicá este flow:

¿La respuesta es mala?
├── ¿Los chunks recuperados eran los correctos?
│   ├── SÍ → el problema es del LLM o del prompt
│   │       (probá un modelo más grande, o ajustá el prompt template)
│   └── NO → el problema es del retrieval
│           (sigue abajo)
│
└── ¿Por qué falló el retrieval?
    ├── Scores muy bajos (top-1 < 0.5) → la query no matchea con NADA en el corpus
    │   - ¿Mismo idioma corpus + query?
    │   - ¿El tema está en el corpus?
    │
    ├── Scores OK pero archivos incorrectos → chunk size puede estar mal
    │   (chunks muy chicos pierden contexto, muy grandes diluyen señal)
    │
    └── Top-1 correcto pero top-2/3 traen ruido → bajá TOP_K
        (de 4 a 2-3 a veces ayuda)

Cómo ver los chunks completos

Por defecto el script imprime solo filename + score. Para debuggear necesitás ver el contenido del chunk. Editá query.ts temporalmente y agregá esto antes del console.log('=== Answer ==='):

query.ts: debug retrieval

console.log('\n=== Retrieved chunks ===');
hits.forEach((hit, i) => {
  const payload = hit.payload;
  if (!isChunkPayload(payload)) return;
  console.log(`\n--- Chunk ${i + 1} (${payload.filename}, score: ${hit.score?.toFixed(4)}) ---`);
  console.log(payload.content);
});

Ahora vas a ver exactamente qué texto está leyendo el LLM antes de responder. Si lo que leés vos no responde la pregunta, el LLM tampoco va a poder.

Tres pruebas concretas para hacer ahora

Prueba 1 — Pregunta puntual y bien planteada

pnpm vercel:query "¿Qué propone la regla de dependencia en Clean Architecture?"

Esperado: top-1 es clean-architecture.md con score > 0.7. Respuesta clara y citada.

Prueba 2 — Pregunta multi-documento

pnpm vercel:query "¿Cuál es la diferencia entre Hexagonal y Clean Architecture?"

Esperado: top-2 son hexagonal-architecture.md y clean-architecture.md. Si solo aparece uno, el retrieval no está balanceando bien.

Prueba 3 — Pregunta fuera del corpus

pnpm vercel:query "¿Cuál es la capital de Francia?"

Esperado: scores todos bajos (< 0.5) y el LLM admite que no tiene info en el contexto. Si el LLM responde “París”, está alucinando — algo en tu prompt no está restringiendo bien al contexto.

El test fuera-de-corpus es el más útil

Una RAG que aprueba la prueba 3 (admite “no sé”) es más confiable que una que aprueba las 1 y 2 pero falla la 3 (alucina). En producción, alucinaciones erosionan trust mucho más rápido que respuestas honestas de “no tengo info”.

Las 3 pruebas, capturadas

Mismas 3 pruebas que recién corriste mentalmente, pero con los chunks recuperados y scores reales que produjo pnpm vercel:query sobre el corpus del curso. Pickeá una pregunta del dropdown para ver qué trajo el retriever, qué scores tienen los chunks, y cómo respondió el LLM.

Probá con una pregunta capturada Regla de dependencia (Clean)Diferencia entre Hexagonal y CleanPregunta fuera del corpus

Pregunta puntual sobre un solo doc — caso ideal

Respuesta del LLM

La regla de dependencia en Clean Architecture establece que el código fuente solo puede depender de cosas que estén más adentro. En otras palabras, nada en una capa interior puede saber absolutamente nada sobre algo en una capa exterior.

Sources (top-K) — 4 chunks

1. [1] clean-architecture.md score 0.8170

   # Clean Architecture Clean Architecture es un enfoque arquitectónico propuesto por Robert C. Martin (Uncle Bob) que organiza el código en capas concéntricas con una regla de dependencia estricta: **las dependencias del c…

2. [2] clean-architecture.md score 0.7574

   cíficas de la aplicación. Por ejemplo: "registrar un usuario", "transferir dinero entre cuentas". 3. **Interface Adapters (Adaptadores)**: convierten datos del formato más conveniente para los casos de uso al formato más…

3. [3] hexagonal-architecture.md score 0.7526

   éntricas** (Entities, Use Cases, Interface Adapters, Frameworks) y la regla de dependencia entre ellas. En la práctica, muchos equipos combinan: usan el modelo de puertos/adaptadores de Hexagonal con la organización en c…

4. [4] solid-principles.md score 0.7467

   ementan. La dirección de la dependencia se invierte: la infraestructura depende del dominio, no al revés. **Ejemplo**: en vez de que `OrderService` importe `PostgresOrderRepository` directamente, define una interfaz `Ord…

Captura: 2026-05-03 · 6990 ms · llama3.2:3b + nomic-embed-text

Mirá especialmente q5 (out-of-corpus): aún con scores bajos uniformes, el LLM intenta responder algo. Es exactamente el patrón que el cap 06 va a desarmar como uno de los errores más comunes.

Lo que viene

En la última página de Nivel 1 vamos a ver los errores más comunes que cometen quienes recién arrancan con RAG — y cómo evitarlos.