Un RAG sense porta d’evals és una demo.

El problema: un recall que ningú mesura

La majoria de projectes RAG entreguen una demo. Preguntes una cosa, el retriever retorna cinc fragments, un model escriu un paràgraf amb seguretat i tothom hi està d’acord. Ningú pot dir si el document correcte era entre aquests cinc fragments — perquè ningú va escriure què vol dir «correcte» i ningú ho mesura. La demo funciona fins que un canvi de chunking, un nou embedding model o un altre vector store mou la qualitat en silenci, i l’únic senyal és una vaga sensació que les respostes han empitjorat.

Aquest és el veritable mode de fallada: no l’al·lucinació com a pànic moral, sinó un retrieval que es degrada sense que ningú hi miri. Una demo optimitza el camí feliç davant d’una audiència; un sistema optimitza un número contra el qual pot regressar. La distància entre tots dos és una eval — i CodebaseRAG existeix per tancar-la.

El set golden: convertir el «correcte» en quaranta parells verificables

Una eval és tan honesta com les seves preguntes. El set golden és una llista pública de parells pregunta/resposta extrets del mateix repositori: una pregunta que un desenvolupador faria de debò, aparellada amb la resposta i amb on viu. Conté ≥40 parells — prou per detectar una regressió real, i prou pocs per revisar-los tots a mà i mantenir-los honests.

No necessites una plataforma d’etiquetatge. Necessites un lloc on escriure les preguntes i la disciplina de mantenir-les. Viuen al costat del codi, així que un canvi al retriever i les seves expectatives actualitzades viatgen a la mateixa revisió.

Tres entrades, parafrasejades del set públic, mostren la forma:

De quina abstracció depèn el query use case i per què no és un tipus del vector store? Depèn d’un port de retriever; els adapters l’implementen, així que el core no importa mai una classe de pgvector o Qdrant.

Què hauria de fer CI quan el recall@5 mitjà cau per sota del sòl compromès? Fer fallar el build. El sòl és un número compromès, i moure’l és una decisió explícita amb gate per ADR — no una edició que posa CI en verd.

Pot l’eval executar-se sense xarxa? Sí. Els embeddings arriben a través d’un port amb dos adapters — Ollama en local, Anthropic quan està allotjat — així que el mateix set golden s’executa offline.

Els exemples no pretenen ser difícils. Pretenen tenir respostes defensables, perquè una d’equivocada sigui un test que falla i no una discussió.

La porta de CI: què falla i què no

Una porta només és útil si falla fort i de manera previsible. Aquesta mesura el recall@5 mitjà, la mean reciprocal rank i el nDCG@5 sobre el set golden, i fa fallar el build quan el recall@5 mitjà cau per sota de la baseline compromesa de 0.409.

Què falla: qualsevol canvi que empenyi el recall@5 mitjà per sota de 0.409. Aquesta és tota la regla. CI executa la mateixa eval determinista que un portàtil, així que un build en vermell apunta a un canvi en el retrieval, no a un entorn inestable.

Què no falla també importa. Un canvi de model que manté el recall@5 al sòl o per sobre passa encara que MRR i nDCG@5 es moguin — la porta protegeix la mètrica compromesa, no tots els números del tauler. Un refactor que mou codi sense moure el retrieval passa. I la porta no jutja la fluïdesa de les respostes: això és una eval de retrieval, i fer veure que mesura la qualitat de generació seria la mateixa deshonestedat que no tenir cap eval.

Per què hexagonal: canviar Qdrant no ha de reescriure el core

Mesures el retrieval, així que allò que mesures no pot estar soldat a allò que desplegues. CodebaseRAG és hexagonal: el query use case depèn de ports, i pgvector, Qdrant, Ollama i Anthropic seuen darrere com a adapters.

El test és concret. Canviar Qdrant per pgvector — o executar-ho tot en local amb Ollama — no ha de reescriure el core. Si canviar un vector store obliga a editar els use cases, l’eval està mesurant un accident de la capa d’emmagatzematge, i cada canvi futur reobre si les mètriques encara volen dir alguna cosa.

Mantenir el core lliure de frameworks i transports aporta més que ordre: manté l’eval determinista, exercitada contra adapters en memòria o recolzats per contenidors sense necessitat de xarxa. Un sòl compromès només és fiable quan el codi que hi ha sota no canvia de forma cada vegada que canvia la infraestructura.

La baseline actual i què no afirma

La baseline compromesa és un recall@5 mitjà de 0.409 (MRR 0.231, nDCG@5 0.277) sobre un set golden d’almenys quaranta parells. Llegeix-ho com un sòl, no com un resultat. 0.409 no és SOTA i això no és cap afirmació que el retrieval estigui resolt. És el número que el projecte es va comprometre a defensar, triat prou baix per mantenir-se estable i prou alt per detectar una caiguda real.

Què no afirma el número: que el set golden sigui exhaustiu, que un build en verd signifiqui bones respostes, o que l’embedding model sigui el millor disponible. Apujar el sòl és una decisió registrada amb una justificació, mai una mètrica de vanitat enganxada en un README.

Què afirma, en canvi, és més petit i més útil: a cada canvi, el repositori et pot dir si el retrieval ha empitjorat, i demostrar-ho amb un set golden públic. Aquesta és la línia entre una demo RAG i un sistema RAG. Una demo et mostra una resposta; un sistema et deixa discrepar-ne.