Cómo construí una plataforma de conocimiento documental alrededor de retrieval medido, citas verificables, estados de falla explícitos, tests, CI y decisiones de arquitectura.
Código, tests, CI, ADRs, sets de evaluación y producto ejecutable localmente. Todavía no hay demo publicado.
01 / Overview
Un producto de conocimiento documental construido para que la calidad de las respuestas se pueda inspeccionar. Ingiere PDFs, preserva provenance por página, mide el retrieval léxico y devuelve respuestas fundamentadas cuyas citas se resuelven desde evidencia confiable en el servidor.
02 / El problema
El problema
Los equipos necesitan respuestas verificables desde políticas, contratos, runbooks e investigación; un texto fluido sin evidencia atribuible no es un resultado de producto confiable.
03 / Mi responsabilidad
Mi responsabilidad
Definí los estados del producto y la secuencia de milestones, y después implementé cada vertical slice entre el frontend Next.js y el backend FastAPI.
Diseñé ingesta, extracción, retrieval, generación de respuestas, citas, sets de evaluación, tests, CI y registros de decisiones de arquitectura.
Mantuve separado el estado de implementación de la aceptación con el proveedor en vivo y documenté explícitamente las capacidades faltantes.
Restricciones
Restricciones
El primer slice útil tenía que ejecutarse localmente sin infraestructura cloud, workers en background ni una base publicada.
Cada cita de una respuesta tenía que resolver a una página y un pasaje realmente recuperado por el servidor.
No se podían asumir credenciales del proveedor, por lo que los gates offline y la aceptación de respuestas en vivo necesitaban definiciones separadas.
04 / Arquitectura
Arquitectura
Recorrido actual del request
El navegador muestra estados explícitos de carga, extracción, indexado, búsqueda y respuesta. La API controla validación y provenance; SQLite es un índice léxico reconstruible; el modelo recibe solo evidencia recuperada y acotada.
01UI de productoNext.js · estados accesibles
02API de aplicaciónFastAPI · validación
03Índice de evidenciaSQLite FTS5 · BM25
04Adaptador de respuestasOutput estructurado · evidencia acotada
05 / Decisiones clave
Decisiones clave
01
Modelar estados como contrato
Contexto
Un único flag “ready” ocultaría qué paso falló y qué se podía reintentar.
Decisión
Usar estados separados de stored, processing, extracted, indexing, indexed y fallas explícitas.
Consecuencia
La UI puede preservar trabajo completado y ofrecer el retry correcto en vez de reiniciar todo el flujo.
02
Medir primero el retrieval léxico
Contexto
Agregar embeddings temprano sumaría costo y complejidad sin demostrar que el baseline era insuficiente.
Decisión
Usar chunks acotados por página con SQLite FTS5/BM25 y verificar Recall@3 y MRR@3 en CI.
Consecuencia
El retrieval es reproducible y económico, con un punto explícito donde justificar un enfoque semántico.
03
Resolver citas en el servidor
Contexto
Permitir que un modelo invente metadata de archivo o página haría que las citas plausibles no fueran confiables.
Decisión
Permitir que el modelo refiera solo IDs de evidencia locales al request; construir documento, página, chunk y offsets desde los matches.
Consecuencia
Una cita se puede abrir contra el PDF almacenado y los IDs de evidencia desconocidos fallan la validación.
06 / Trade-offs
Trade-offs
Archivos locales y SQLite embebido
Qué habilitaSetup rápido, datos inspeccionables, tests deterministas y sin dependencia de infraestructura.
Qué cuestaSin coordinación multiproceso, durabilidad cloud, multi-tenancy ni escala horizontal.
Retrieval léxico antes que embeddings
Qué habilitaUn baseline medible, sin credenciales y con costo y comportamiento predecibles.
Qué cuestaSinónimos y redacciones semánticamente relacionadas pueden fallar sin overlap de tokens.
Vertical slices sincrónicos
Qué habilitaUn recorrido corto del request y fallas fáciles de reproducir localmente.
Qué cuestaLos workloads grandes eventualmente van a requerir colas, workers y persistencia de progreso.
07 / Modos de falla
Modos de falla
Las cargas rechazadas o interrumpidas eliminan artefactos temporales, por lo que un archivo parcial nunca aparece almacenado.
Las fallas de extracción e indexado conservan el último estado exitoso y muestran un retry puntual.
Un retrieval débil devuelve evidencia insuficiente en vez de forzar una respuesta generada.
El rechazo por seguridad y la falla técnica del proveedor siguen siendo resultados distintos en la API y la interfaz.
El CV brinda el contexto completo de carrera. Para detalles sensibles de cliente, escribime y puedo conversar sobre el trabajo con el nivel de disclosure apropiado.