¿Por qué comparar frameworks?

La pregunta del meta-curso

Llegaste hasta acá. Sabés construir un pipeline RAG end-to-end, sabés medirlo, sabés mejorarlo con técnicas de producción y sabés operarlo. ¿Hay un framework que te ahorre todo eso?

La respuesta corta: depende. Y lo que sigue son los criterios concretos para que ese “depende” se traduzca en una decisión defendible.

El problema con las comparativas online

Buscá “best RAG framework” en Google. Vas a ver:

• “LangChain has 90k stars on GitHub”. OK, pero ¿tu RAG mejora por las stars?
• “LlamaIndex is built specifically for RAG”. OK, pero ¿qué significa eso en código real?
• “Mastra is the new shiny thing”. Claro, ¿pero tiene la integración que necesitás?

La mayoría de las comparativas son superficiales: enumeran features, citan benchmarks de marketing, no usan el mismo dataset, no muestran código real, y no tocan el costo de mantener cada uno.

Una comparativa defendible requiere tres cosas:

1. El mismo problema resuelto en cada framework. No “hicimos chatbot con LangChain y resumen con LlamaIndex” — eso no compara nada.
2. Las mismas métricas. Latencia, retrieval@k, faithfulness, answer-relevance. Misma escala, mismo judge, mismo corpus.
3. Trade-offs explícitos. Nada es gratis. Si X gana en velocidad, ¿qué pierde en flexibilidad?

Este nivel hace eso. Mismo Qdrant, mismo Ollama, mismos 4 markdowns en data/, mismo golden set, mismo harness. Lo único que cambia es el framework.

Los 4 que comparamos

Package	Framework	Filosofía
01-vercel-ai-sdk	Vercel AI SDK	Minimalismo provider-agnostic
02-langchain	LangChain.js	Ecosistema todo-incluido
03-llamaindex	LlamaIndex.TS	RAG-first abstractions
04-mastra	Mastra	Agent-first, RAG como tool

Cada uno está construido para el mismo task: ingestar 4 markdowns en español, indexar en Qdrant con nomic-embed-text, y responder preguntas con llama3.2:3b. 76 a 96 líneas honestas por package, sin abstracciones que escondan el pipeline.

Las dos asimetrías intencionales

Por transparencia: hay dos decisiones de diseño en este repo que no son “puras”, y aparecen documentadas en el header de cada reporte que el harness genera.

LlamaIndex usa retriever + complete, no QueryEngine

El path idiomático de LlamaIndex para RAG es:

el path idiomático (que NO usamos en evals)

const queryEngine = index.asQueryEngine();
const response = await queryEngine.query({ query: 'pregunta' });

queryEngine.query() devuelve la respuesta del LLM pero no expone los chunks recuperados de manera uniforme. Para el harness — que necesita los contextos crudos para computar retrieval@k y faithfulness — usamos un path manual:

el path del harness

const retriever = index.asRetriever();
const nodes = await retriever.retrieve({ query: 'pregunta' });
const answer = await Settings.llm.complete({ prompt: buildPrompt(nodes) });

Esto se ve idéntico al patrón de los otros 3 frameworks — una decisión deliberada para que la comparativa sea honesta. La CLI de query.ts mantiene el path idiomático con asQueryEngine(); solo el query.fn.ts (consumido por el harness) usa el camino manual.

Mastra evalúa el path Naive, no el agéntico

Mastra es el único framework de los 4 cuyo “modo recomendado” no es un pipeline lineal. La forma idiomática de Mastra es un agent con tools: el LLM decide cuándo retrievear, qué retrievear, y consolida la respuesta. Eso no es comparable contra los otros 3 que sí son lineales.

Para el harness, Mastra expone un segundo path llamado directRetrievalQuery (Naive RAG), que es lo que medimos. El path agéntico lo describimos en el cap 06 de este nivel pero queda fuera de los números.

Asimetría justificada vs. asimetría escondida

La diferencia entre una comparativa honesta y una marketing es que la honesta declara las asimetrías y explica por qué. Acá las dos están al pie de cada reporte del harness y en este capítulo.

Si después de leer esto algo todavía te parece injusto contra un framework, abrí un issue en el repo. Las comparativas están vivas y todo argumento bien fundamentado mejora el resultado.

Cómo está organizado este nivel

Los 9 capítulos siguen este arc:

• 02 — Tabla comparativa: vista de pájaro en una sola pantalla.
• 03-06 — Análisis individual: un capítulo por framework, mismo template (filosofía, código, tipos, brilla/sufre).
• 07 — Mismo input, distintos outputs: corremos la misma pregunta en los 4 y leemos las diferencias.
• 08 — Eval harness en acción: los números reales side-by-side.
• 09 — ¿Cuál elegir?: árbol de decisión con criterios concretos.

Si tu caso encaja claro con uno de los 4 después de leer la tabla del cap 02, podés saltearte 3 de los 4 análisis individuales. Los caps 07-09 son donde está el contenido único del nivel.

Lo que viene

La tabla resumen. Vista de pájaro de las 4 opciones en 6 ejes — DX, tipos, velocidad, ecosistema, LOC mínimo y target audience.