Módulo 8: Proyecto — `search_docs` lista para producción

Lo que a tu RAG todavía le falta

Siguiente →

Descripción

La Lección 06 dejó un número honesto: recall@1 = 0.1667, y BM25 confundiendo un chunk de referencias cruzadas con la respuesta real en cuatro de seis queries. Esta lección no intenta arreglar ese número — arreglarlo de verdad excedería la frontera que esta guía fijó desde su diseño. En cambio, responde la pregunta que un sistema honesto siempre deja pendiente al final: ¿a dónde vas después de esta guía? Cuatro guías del ecosistema resuelven, cada una, un límite específico y real de lo que search_docs construyó en estos ocho módulos — y esta lección te dice, con precisión, cuál resuelve cuál, para que no llegues a ninguna de ellas sin saber por qué la necesitas.

Conexión con el módulo

Esta es la última lección conceptual de la guía — no ejecuta código nuevo. Retoma el diagnóstico ejecutado de la Lección 06 (y el del Módulo 6, Lección 06) y lo convierte en un mapa de próximos pasos, con la misma disciplina de frontera que sostuvo cada módulo anterior: nombrar la guía vecina exacta, no vagamente "hay más para aprender".

Analogía: el plano completo del edificio, con las puertas que llevan a otros edificios

Los ocho módulos de esta guía construyeron un edificio completo y funcional: recepción de documentos, catálogo, mostrador, atención al público, mantenimiento del catálogo, auditoría de calidad, protocolo de manejo de casos difíciles. El edificio funciona, de punta a punta, con evidencia real en cada piso. Pero ningún edificio real de producción es una isla: tiene puertas que llevan a otros edificios especializados —uno que sabe entender el significado de una pregunta más allá de las palabras exactas, uno que decide cuánto espacio de la mesa de trabajo del agente ocupa cada documento traído, uno que recuerda conversaciones anteriores con el mismo cliente—. Esta lección es el plano con esas puertas marcadas, cada una con el letrero exacto de a dónde lleva, para que la próxima persona que use este edificio sepa exactamente dónde seguir cuando el trabajo de aquí no alcance.

El mapa: cuatro guías, cuatro límites distintos

                    search_docs (esta guía, M1-M8)
                    BM25 léxico, k1=1.5/b=0.75
                    recall@1=0.1667 medido y honesto
                         │
    ┌────────────────────┼────────────────────┬─────────────────────┐
    ▼                    ▼                    ▼                     ▼
LÍMITE 1:           LÍMITE 2:            LÍMITE 3:             LÍMITE 4:
BM25 no entiende    lo recuperado no     no hay memoria de     el ranking no
sinónimos ni        se cura ni se        conversación entre    se mejora con
significado         presupuesta en       preguntas             re-ranking ni
                     la ventana                                  hybrid search
    │                    │                    │                     │
    ▼                    ▼                    ▼                     ▼
embeddings-deep-    context-             agent-memory-         advanced-rag-
dive-guide /        engineering-         and-state-guide       techniques-guide
vector-databases-   guide
fundamentals-guide

Cada flecha de este mapa corresponde a un límite que esta guía midió explícitamente en algún módulo, no a una carencia genérica de "RAG básico". Repasemos las cuatro, una por una.

Límite 1: BM25 es léxico, no semántico — el límite que atraviesa toda la guía

Qué mide esta guía sobre esto: cada lección que tocó el índice, desde el Módulo 2 en adelante, rotuló BM25 como recuperación léxica real —coincidencia y frecuencia de términos exactos, el mismo algoritmo que usan Elasticsearch/OpenSearch en producción—, nunca como un embedding semántico. El control de la Lección 06 del Módulo 2 lo demostró con evidencia: search("reimbursement", k=3) devuelve [], no porque el sistema esté roto, sino porque "reimbursement" —sinónimo real de "refund" en el uso cotidiano del inglés— simplemente no existe en el vocabulario indexado. Ningún ajuste de k1/b puede resolver esto: el problema no es de ranking, es de que el término candidato ni siquiera entra en juego.

Dónde se resuelve de verdad:

  • embeddings-deep-dive-guide (AI Engineering) — la teoría completa: arquitectura transformer, tokenización, pooling, cómo un modelo aprende que "reimbursement" y "refund" son vecinos en el espacio vectorial aunque no compartan ni una letra. Esta guía usó un índice; esa guía enseña cómo funciona un embedding por dentro, desde cero.
  • vector-databases-fundamentals-guide (AI Engineering) — cómo se indexa y consulta un vector index real (HNSW, IVF, PQ) y cómo se opera un vector database de producción (ChromaDB, Pinecone, Weaviate, Qdrant). Esta guía nunca instaló ninguno de estos —requieren red y, en producción, presupuesto— pero cada lección que tocó el índice nombró esta opción real en el punto exacto donde aplicaría.

Límite 2: lo recuperado no se cura ni se presupuesta en la ventana de contexto

Qué mide esta guía sobre esto: el Módulo 7 (Lección 06) midió cuántos chunks, caracteres y tokens aproximados viaja cada búsqueda de search_docs — pero decidir en qué orden entran al prompt final, cuándo resumir en vez de incluir texto completo, y cuánto espacio relativo ocupa cada uno frente al resto de la conversación nunca fue parte de esta guía. search_docs produce una lista de chunks candidatos, ya filtrados por apply_threshold; qué pasa con esa lista después de que sale de aquí es, a propósito, terreno de otra guía.

Dónde se resuelve de verdad:

  • context-engineering-guide (guía hermana) — el presupuesto fino de la ventana de contexto: qué entra, en qué orden, cuándo comprimir o resumir, cómo priorizar entre lo que trajo search_docs y el resto de lo que compite por espacio en el prompt (historial de conversación, resultados de otras tools, instrucciones del sistema). Esta guía RECUPERA; context-engineering-guide decide cómo entra eso al prompt — la frontera se nombró explícitamente en el DISEÑO.md de esta guía desde el primer módulo, y se sostuvo en los ocho.

Límite 3: no hay memoria de conversación entre preguntas

Qué mide esta guía sobre esto: cada corrida del agente de esta guía —incluida la de la Lección 04 de este módulo— resuelve una pregunta, en una conversación, sin ningún recuerdo de interacciones anteriores con el mismo usuario. El índice de search_docs es memoria de documentos —el corpus de Reservo, fijo y compartido por cualquier usuario que pregunte—, no memoria de conversación — qué le preguntó este usuario específico la semana pasada, qué preferencias mencionó, qué reservas hizo antes.

Dónde se resuelve de verdad:

  • agent-memory-and-state-guide — persistir, entre sesiones, qué se le mostró a un usuario, sus preferencias, el historial de sus interacciones con el agente. Esta es precisamente la guía en la que estás ahora mismo si estás leyendo este módulo dentro de ella — la distinción que traza consigo misma es la más importante de las cuatro: el índice de search_docs es memoria de documentos compartida por todos; la memoria de conversación es memoria de este usuario, en esta relación con el agente, y vive en una capa completamente distinta del sistema.

Límite 4: el ranking no mejora con re-ranking ni hybrid search

Qué mide esta guía sobre esto: el Módulo 6 (Lección 07) ya trazó, en detalle, las tres técnicas que mejorarían el ranking de BM25 sin cambiar la etapa de recuperación en sí: re-ranking con cross-encoders (relee cada candidato con la query completa, distingue "menciona el tema" de "responde la pregunta" — resolvería el imán léxico), hybrid search (combina el score léxico de BM25 con similitud semántica — la única de las tres que resolvería el límite estructural de "reimbursement"), y query expansion/HyDE (transforma la query antes de buscar). Ninguna de las tres se implementó en esta guía — el DISEÑO.md fijó esa frontera desde el primer módulo.

Dónde se resuelve de verdad:

  • advanced-rag-techniques-guide (AI Engineering) — la implementación completa de las tres técnicas, con modelos reales, sobre un corpus real. Esta guía construyó la base —el pipeline de ingestión, el índice, la tool, la evaluación— sobre la que esas técnicas se aplican; esa guía construye el upgrade, no lo re-explica desde cero.

Tabla resumen: qué límite, qué guía, qué mide esta guía sobre él

LímiteMedido en esta guíaSe resuelve en
BM25 no encuentra sinónimos ("reimbursement" → [])Módulo 2, Lección 06embeddings-deep-dive-guide
No hay vector index ni vector database realRegla dura de toda la guía (nombrada en cada lección de índice)vector-databases-fundamentals-guide
Lo recuperado no se cura/presupuesta en el promptMódulo 7, Lección 06 (mide el tamaño, no decide la ubicación)context-engineering-guide
No hay memoria de conversación entre preguntasAusente por diseño en todos los ejemplos de agente (M4, M8-L04)agent-memory-and-state-guide
El ranking no mejora con re-ranking/hybrid/expansionMódulo 6, Lección 07 (mapa completo de las tres técnicas)advanced-rag-techniques-guide
Evaluación semántica con LLM-juez (RAGAS, faithfulness)Frontera nombrada desde el DISEÑO.md; nunca ejecutada aquíevaluation-frameworks-guide

Por qué ninguno de estos seis límites es un defecto de esta guía

Cada uno de los seis límites de la tabla es una frontera de diseño, fijada antes de escribir la primera línea de código de esta guía, no un descuido descubierto al final. El DISEÑO.md de esta guía lo dice explícito desde su primer párrafo: esta guía enseña la ingeniería de producción para que un agente recupere información de documentos — el pipeline de ingestión, el índice, la tool, la ingestión incremental, la evaluación de recuperación pura, y la capa operativa — no la teoría de embeddings desde cero, ni el presupuesto de ventana de contexto, ni la memoria de conversación, ni las técnicas avanzadas de recuperación. Esa frontera existe porque cada una de esas cinco guías vecinas ya cubre su tema en profundidad real, y repetirlo aquí —de forma superficial, sin el mismo rigor ejecutado— sería peor que nombrarlo y seguir.

Lo que sí puedes afirmar, con la evidencia de los ocho módulos de esta guía, es esto: el search_docs que construiste es una base honesta y real de producción, no un prototipo de juguete. Recupera de verdad (57 chunks, BM25 completo), se conecta de verdad a un agente (protocolo tool_use/tool_result real), sobrevive de verdad a documentos que cambian (idempotencia por hash de contenido), se mide de verdad (recall/precision con ground-truth fijo), y opera de verdad con criterio (citas, umbral, 0-resultados). Cada una de las cinco guías vecinas de este mapa se conecta a esta base — ninguna la reemplaza.

Errores comunes

  1. Pensar que "esta guía no cubre X" significa que search_docs está incompleta o mal construida. Cada límite de este mapa es una frontera fijada por diseño, con la guía exacta que lo resuelve nombrada — no un hueco accidental. search_docs cumple exactamente lo que promete: recuperación léxica real, con sus límites léxicos reales, medidos y rotulados en cada lección.

  2. Ir directo a advanced-rag-techniques-guide sin haber medido el problema primero. El Módulo 6 de esta guía (y la Lección 06 de este módulo) existen precisamente para que sepas qué falla específicamente — el imán léxico, el límite estructural de vocabulario — antes de aplicar una técnica que lo resuelva. Aplicar re-ranking sin saber que el problema real es de vocabulario ausente (no de orden) desperdicia el esfuerzo en la técnica equivocada.

  3. Confundir memoria de documentos (esta guía) con memoria de conversación (agent-memory-and-state-guide). El índice de search_docs es el mismo para cualquier usuario que pregunte — no cambia según quién pregunta ni qué preguntó antes. Construir memoria de conversación encima de search_docs, sin distinguir las dos capas, mezcla dos sistemas con ciclos de vida y objetivos completamente distintos.

  4. Saltarse context-engineering-guide "porque ya filtré con apply_threshold". apply_threshold (Módulo 7) decide qué chunks pasan el filtro de relevancia mínima — no decide en qué orden entran al prompt, ni cuánto espacio ocupan frente al resto del contexto de la conversación. Son dos decisiones distintas, en dos etapas distintas del pipeline.

Ejercicios

Ejercicio 1: Clasifica un síntoma en su límite correcto (Fácil)

Para cada uno de estos tres síntomas, identifica a cuál de los cuatro límites de esta lección pertenece: (a) el agente responde con seguridad sobre una política que Reservo nunca documentó; (b) el agente olvida, en la segunda pregunta de una conversación, la sala que el usuario mencionó en la primera; (c) search_docs("reimbursement policy") devuelve [] aunque refund-policy sí exista.

Ver solución

(a) No es ninguno de los cuatro límites de esta lección — es exactamente el problema que el Módulo 7 (Lección 03, handle_no_results) ya resolvió dentro de esta guía: un agente sin la instrucción de responder solo con lo que las tools devuelven puede recurrir a su conocimiento general en vez de admitir "no lo tenemos". (b) Límite 3 — memoria de conversación, resuelto en agent-memory-and-state-guide; ningún ejemplo de agente de esta guía retiene contexto entre preguntas separadas. (c) Límite 1 — el límite léxico estructural de BM25, resuelto con embeddings semánticos en embeddings-deep-dive-guide; es literalmente el mismo caso, con la misma palabra, que el Módulo 2 (Lección 06) ya demostró.

Ejercicio 2: Ordena las cinco guías vecinas por la urgencia con la que Reservo las necesitaría (Medio)

Imagina que Reservo va a producción real mañana con exactamente el sistema de este proyecto. Basándote en el score de evaluación de la Lección 06 (recall@1=0.1667) y en lo que sabes de cada guía vecina, argumenta cuál de las cinco resolvería el problema más urgente primero, y cuál podría esperar.

Ver solución

No hay una única respuesta correcta —depende del caso de uso real de Reservo—, pero un argumento razonable: advanced-rag-techniques-guide (re-ranking/hybrid) sería la prioridad más alta, porque ataca directamente el número más bajo y más visible (recall@1=0.1667) sin requerir cambiar toda la arquitectura de recuperación —un cross-encoder de re-ranking se agrega sobre el índice BM25 existente, sin descartarlo—. context-engineering-guide vendría después, porque el sistema ya funciona de punta a punta (Lección 04 de este módulo lo demuestra) y el presupuesto de contexto solo se vuelve un problema real cuando el volumen de conversaciones y documentos crece. agent-memory-and-state-guide y embeddings-deep-dive-guide/vector-databases-fundamentals-guide son inversiones más grandes —requieren infraestructura nueva (una base de datos de memoria, un vector database)— y razonablemente esperarían a que el sistema base demuestre valor real con usuarios reales primero. El argumento importante, más que el orden exacto, es que cada elección se basa en evidencia medida (el score real de la Lección 06), no en una intuición vaga de "hay que mejorar todo a la vez".

Ejercicio 3: Diseña la pregunta de evaluación para agent-memory-and-state-guide (Difícil)

El EVAL_SET de esta guía mide recuperación de documentos con doc_id esperado fijo. Si tuvieras que diseñar un EVAL_SET análogo para memoria de conversación —no para search_docs, sino para una futura capa de memoria que recuerde preferencias de usuario entre sesiones—, ¿qué campo reemplazaría a doc_id, y qué haría un recall_at_k análogo en ese contexto? Escribe la firma en prosa, sin implementarla.

Ver solución

En vez de (query, expected_doc_id), un EVAL_SET de memoria de conversación necesitaría algo como (session_context, expected_fact) — donde session_context es el historial simulado de una conversación anterior (por ejemplo, "el usuario mencionó que prefiere reservar Focus por las mañanas") y expected_fact es el dato específico que la memoria debería recuperar en una sesión posterior ("¿qué sala prefiere este usuario?" → "Focus"). Un recall_at_k análogo respondería "¿el hecho esperado aparece entre los k recuerdos que el sistema de memoria trae de vuelta para esta sesión?" — la misma estructura binaria que recall_at_k de esta guía, pero contra un almacén de hechos por-usuario en vez de un corpus de documentos compartido. La diferencia de fondo, que justifica por qué esto vive en una guía completamente distinta: el ground-truth de search_docs es fijo y objetivo (el documento correcto existe, sin ambigüedad, en el corpus); el ground-truth de una memoria de conversación depende de qué pasó en una sesión anterior específica, que varía por usuario y por historial — una superficie de evaluación estructuralmente distinta, que agent-memory-and-state-guide cubre con su propio rigor.

Resumen y siguiente paso

  • search_docs es una base real de producción —57 chunks, BM25 completo, tool con contrato, ingestión incremental, evaluación con ground-truth fijo, capa operativa— con seis límites nombrados por diseño, no descubiertos por accidente.
  • Cuatro guías del ecosistema resuelven, cada una, un límite específico y medido en esta guía: embeddings-deep-dive-guide/vector-databases-fundamentals-guide (léxico → semántico), context-engineering-guide (recuperar → presupuestar en el prompt), agent-memory-and-state-guide (memoria de documentos → memoria de conversación), advanced-rag-techniques-guide (BM25 puro → re-ranking/hybrid/query expansion).
  • Ninguna de las cuatro reemplaza lo construido aquí — todas se conectan sobre esta base, extendiéndola en una dirección específica.

Siguiente lección: 08 — Proyecto: entrega search_docs. El pipeline completo, de punta a punta, en un solo guion — el entregable final de toda la guía.

Recursos adicionales

  1. production-rag-and-document-ingestion-guide — DISEÑO.md, sección "Qué enseña esta guía (y qué NO)": la frontera completa, fijada desde el diseño, que esta lección retoma con evidencia ejecutada de los ocho módulos.
  2. production-rag-and-document-ingestion-guide — Módulo 6, Lección 07 (the-path-to-better-recall): el mapa detallado de re-ranking/hybrid search/query expansion que esta lección resume en la tabla final.
  3. embeddings-deep-dive-guide, vector-databases-fundamentals-guide, advanced-rag-techniques-guide — las tres guías de AI Engineering que resuelven, respectivamente, la teoría semántica, la infraestructura de vector database, y las técnicas avanzadas de recuperación.
  4. context-engineering-guide y agent-memory-and-state-guide — las dos guías hermanas que deciden qué pasa con lo recuperado (presupuesto de ventana) y qué recuerda el agente entre conversaciones (memoria de usuario), respectivamente.
← AnteriorEl score de evaluaciónSiguiente →Proyecto: entrega `search_docs`