199 lines
12 KiB
Markdown
199 lines
12 KiB
Markdown
# Pendientes priorizados del RAG
|
|
|
|
**Ultima actualizacion:** 2026-09-17
|
|
**Responsable de la priorizacion:** Usuario
|
|
**Estado:** Activo
|
|
|
|
Este documento es la fuente canonica del orden de trabajo pendiente del modulo RAG. La numeracion ya refleja la prioridad final indicada por el usuario.
|
|
|
|
## Hoja de ruta OCR prioritaria
|
|
|
|
Esta secuencia tiene prioridad sobre la aceptacion productiva pendiente de FacturaTech. No cerrar v4, crear una candidata nueva, reingestar FacturaTech, aprobar, indexar ni activar contenido fuera del orden indicado.
|
|
|
|
### Fase 1. Corregir y verificar el codigo
|
|
|
|
**Estado:** Completada funcionalmente y verificada en produccion el 2026-09-17.
|
|
|
|
1. Completado: errores OCR estructurados, seguros y accionables.
|
|
2. Completado: recuperacion administrativa autenticada y auditada para candidatas con evidencia invalida.
|
|
3. Completado: RAG y OCR exponen versiones; los digests identifican las imagenes desplegadas.
|
|
4. Completado: errores, recuperacion, reinicios y versiones cubiertos localmente y verificados en produccion sin modificar v4.
|
|
|
|
**Salida:** el comportamiento nuevo esta validado y v4 permanece intacta. La etiqueta OCI de revision legible sigue como mejora operativa no bloqueante: actualmente el digest es la identidad verificable de la imagen.
|
|
|
|
### Fase 2. Resolver la candidata v4
|
|
|
|
1. Consultar v4 mediante el contrato de errores ya corregido.
|
|
2. Confirmar que su evidencia no cumple los requisitos.
|
|
3. Aplicar una operacion administrativa solo con aprobacion explicita del usuario.
|
|
4. Verificar que la version activa no cambia ni se indexa contenido.
|
|
5. Confirmar que la fuente ya no queda bloqueada para una nueva candidata.
|
|
|
|
**Salida:** v4 queda resuelta de forma auditable, sin crear todavia otra candidata.
|
|
|
|
### Fase 3. Finalizar la aceptacion de FacturaTech
|
|
|
|
1. Crear una nueva candidata no activada para el documento.
|
|
2. Verificar la evidencia durable y revisar sus 34 entradas.
|
|
3. Comprobar `CBG04a`, `FAT07`, `DSAU08` y `NSAV06`.
|
|
4. Requerir aprobacion humana antes de indexar o activar.
|
|
5. Completar la tarea SDD 7.4 con su evidencia de validacion.
|
|
|
|
**Salida:** la ingesta OCR de FacturaTech queda aceptada y activada de forma segura.
|
|
|
|
## 1. Documentacion y descubrimiento de la API
|
|
|
|
**Estado:** Completado y validado definitivamente en produccion el 2026-09-08.
|
|
|
|
- Implementar `/help` o una especificacion OpenAPI consultable.
|
|
- Actualizar documentos desfasados que todavia muestran como pendientes funciones ya desplegadas, como playground, logs y cleanup.
|
|
- Documentar los contratos, parametros, respuestas y errores reales de todos los endpoints.
|
|
- Mantener la documentacion alineada con produccion para que agentes e integradores no tengan que reconstruir el comportamiento desde el codigo.
|
|
|
|
## 2. Ciclo de vida del conocimiento
|
|
|
|
**Estado:** Completado y validado en produccion el 2026-09-13.
|
|
|
|
El contrato de implementacion esta cerrado en [`CONTRATO_CICLO_VIDA_Y_OCR.md`](./CONTRATO_CICLO_VIDA_Y_OCR.md). Antes de ejecutar las pruebas de migracion o activar el ciclo de vida hay que completar este prerrequisito:
|
|
|
|
### Prerrequisito bloqueante: preparar PostgreSQL
|
|
|
|
- Confirmar que existe la instancia y la base de datos que usara RAG en EasyPanel.
|
|
- Obtener el hostname interno, puerto, nombre de base de datos, usuario y requisitos SSL.
|
|
- Configurar `POSTGRES_URL`, `POSTGRES_SSL` y `LIFECYCLE_ADMIN_TOKEN` en el servicio RAG.
|
|
- Ejecutar las migraciones del esquema y verificar las tablas, permisos y `SELECT 1` desde RAG. Completado el 2026-09-13.
|
|
- Revisar que no falten variables, red interna, credenciales, almacenamiento persistente o permisos de migracion. Completado el 2026-09-13; la configuracion completa de backups queda diferida al paquete del punto 7.
|
|
- Inventariar las fuentes actuales de Qdrant y preparar su carga en el catalogo PostgreSQL.
|
|
|
|
### Resultado del dry-run legacy
|
|
|
|
- Ejecutado el 2026-09-13 sin `--apply`.
|
|
- Detectados 22.605 puntos en 7 fuentes de `rag_chunks`.
|
|
- `ok: true`; no se encontraron `blockedReasons`.
|
|
- Ventana de mantenimiento ejecutada con `INGEST_WRITES_ENABLED=false` y `rag_system_state.maintenance=true`.
|
|
- Migracion aplicada con el lote `17f05cae-c5a7-49a5-b3ad-729958e1a342` usando snapshot Qdrant remoto con checksum `a55b13d3b6b791e9b148f87491b9b2788ce5797ee997a9f6be2a6d424eb92302`.
|
|
- Catalogadas 7 fuentes y 22.605 puntos; todas las versiones quedaron `active` y sus recuentos PostgreSQL/Qdrant coinciden.
|
|
- `KNOWLEDGE_LIFECYCLE_ENFORCED=true`, `INGEST_WRITES_ENABLED=true`, `maintenance=false` y retrieval validado en produccion.
|
|
|
|
El punto 2 queda cerrado. El punto 3, OCR integrado en la ingesta, puede comenzar respetando el contrato secuencial.
|
|
|
|
- Crear un catalogo de fuentes y versiones ingeridas.
|
|
- Saber que documento esta vigente, obsoleto, reemplazado o pendiente de reingesta.
|
|
- Evitar duplicados y permitir actualizaciones incrementales controladas.
|
|
- Registrar fecha de indexacion, modelo de embeddings, proveedor y version del contenido.
|
|
- Facilitar el reemplazo o rollback de una fuente sin depender de operaciones manuales dificiles de auditar.
|
|
|
|
### Paquete de mejora posterior: seguimiento del corpus en API y frontend
|
|
|
|
**Prioridad:** Diferida, sin urgencia; no bloquea la preparacion de PostgreSQL ni el cierre funcional del punto 2. Retomar al trabajar en el frontend de gestion.
|
|
|
|
- Exponer por API los documentos que componen cada version de una fuente.
|
|
- Exponer el historial de intentos de ingesta, resultados y errores.
|
|
- Incluir fechas y detalles de error de las versiones en las respuestas de la API.
|
|
- Ampliar la vista basica del playground a una gestion de fuentes, documentos, versiones e ingestas con su estado e historial.
|
|
- Incorporar al frontend las operaciones ya disponibles por API: activacion, rollback, reintento y purga.
|
|
|
|
## 3. OCR integrado en la ingesta
|
|
|
|
**Diseño:** Contrato de implementacion cerrado en [`CONTRATO_CICLO_VIDA_Y_OCR.md`](./CONTRATO_CICLO_VIDA_Y_OCR.md). El punto 2 ya fue validado en produccion; su ejecucion queda habilitada.
|
|
|
|
- Detectar PDFs con capturas, imagenes o una capa textual insuficiente.
|
|
- Ejecutar OCR automaticamente o bloquear la ingesta para revision cuando no pueda garantizarse la cobertura.
|
|
- Generar un documento intermedio auditable cuando sea necesario.
|
|
- Verificar el resultado antes de sustituir una fuente vigente.
|
|
- Evitar que se repita el problema detectado con el PDF de FacturaTech.
|
|
|
|
### Paquete de mejora posterior: OCR reutilizable para entradas visuales
|
|
|
|
**Prioridad:** Diferida; no bloquea la correccion actual ni la aceptacion de FacturaTech.
|
|
|
|
- Mantener el contrato actual de trabajos PDF.
|
|
- Aceptar directamente `image/jpeg` y `image/png`, ademas de PDF.
|
|
- Normalizar cada entrada visual a un resultado por pagina con texto, lineas, posiciones y metricas.
|
|
- Emitir resultados OCR o errores estructurados sin depender del RAG.
|
|
- Mantener RAG como consumidor opcional del OCR y responsable de versionado, revision e indexacion de conocimiento.
|
|
- Definir limites de tamano, dimensiones y paginas, autenticacion, retencion y pruebas para cada formato.
|
|
|
|
## 4. Mejora del retrieval
|
|
|
|
- Anadir busqueda hibrida semantica y textual para codigos exactos como `FAT07`, `504` o `SQLSTATE[23505]`.
|
|
- Mejorar el ranking usando coincidencias de codigo, regla, modulo y mensaje, no solo proximidad semantica.
|
|
- Crear un conjunto estable de consultas de evaluacion basado en casos reales.
|
|
- Medir precision, resultados irrelevantes y consultas ambiguas.
|
|
- Refinar retrieval y chunking con evidencia de uso, no mediante cambios generales sin medicion.
|
|
|
|
## 5. Seguridad de la API
|
|
|
|
- Anadir autenticacion para consumidores autorizados.
|
|
- Proteger especialmente uploads, cleanup y operaciones sobre logs.
|
|
- Aplicar rate limiting y limites de tamano o tipo de archivo.
|
|
- Revisar CORS, exposicion publica, registros sensibles y permisos por operacion.
|
|
- Sustituir la configuracion sin credenciales de n8n cuando exista el mecanismo de autenticacion definitivo.
|
|
- Actualizar Express/`qs` para cerrar los avisos moderados pendientes de `npm audit`.
|
|
|
|
## 6. Pruebas automatizadas
|
|
|
|
- Incorporar un framework y scripts de pruebas; actualmente el proyecto no tiene suite automatizada.
|
|
- Cubrir ingesta, parsing, chunking, scopes, cleanup y retrieval.
|
|
- Probar contratos y respuestas de error de la API.
|
|
- Anadir pruebas de regresion con consultas reales como las validadas para FacturaTech.
|
|
- Separar pruebas unitarias, de integracion y verificaciones opcionales contra servicios remotos.
|
|
|
|
## 7. Operacion y mantenimiento
|
|
|
|
- Resolver la colision de `sourceRef` al ingerir carpetas homonimas.
|
|
- Separar claramente configuracion versionable y secretos locales.
|
|
- Verificar y cerrar documentalmente la migracion del repositorio raiz de RAG y su despliegue en EasyPanel.
|
|
- Revisar copias temporales o backups asociados a la migracion antes de eliminarlos.
|
|
- Mantener un procedimiento fiable de despliegue, verificacion y rollback.
|
|
|
|
### Paquete de mejora posterior: backups manuales del RAG
|
|
|
|
**Prioridad:** Diferida, sin urgencia; no bloquea la preparacion actual de PostgreSQL. Sin programacion automatica.
|
|
|
|
**Estado de la propuesta:** Diseno guardado para completar e implementar mas adelante.
|
|
|
|
- Configurar el destino de backups y diagnosticar el error observado al crearlo en EasyPanel.
|
|
- Preparar copias manuales de la nueva base del RAG y snapshots de Qdrant; `db_gestion_flujos_n8n` es ajena a este alcance.
|
|
- Definir una ventana sin escrituras para obtener copias coherentes de ambos almacenes.
|
|
- Documentar y comprobar la restauracion, incluyendo la recuperacion de los permisos necesarios.
|
|
- Este paquete difiere la solucion habitual de backups; el snapshot previo exigido por la migracion legacy sigue formando parte de esa operacion.
|
|
|
|
#### Diseno propuesto
|
|
|
|
- Mantener los datos primarios separados: PostgreSQL conserva el catalogo, Qdrant conserva chunks y embeddings, y un volumen privado del RAG conserva originales y artefactos.
|
|
- Montar un volumen `rag-ingestions` en `/data/ingestions` para conservar originales, manifiestos y futuros artefactos OCR por version.
|
|
- Cambiar la ingesta para guardar el original antes de procesarlo; el flujo actual usa `/tmp` y elimina los uploads al terminar.
|
|
- Respaldar PostgreSQL con un dump portable de `db_rag` y, cuando quede configurado, con Database Backups de EasyPanel hacia un destino S3-compatible.
|
|
- Respaldar Qdrant con snapshot de la coleccion o del almacenamiento completo, preferentemente hacia el mismo destino externo.
|
|
- Incluir los artefactos del volumen en el plan de backup y probar una restauracion completa antes de considerar portable el servicio.
|
|
- No tratar un volumen Docker del mismo VPS como backup externo: protege frente a reinicios, no frente a perdida del servidor.
|
|
- Mantener fuera de este alcance `db_gestion_flujos_n8n`.
|
|
|
|
## 8. Sistema de evaluacion
|
|
|
|
- Revisar periodicamente los logs de evaluacion almacenados en Qdrant.
|
|
- Convertir incidencias reales en casos de prueba permanentes.
|
|
- Anadir metricas de recuperacion, calidad y contexto insuficiente.
|
|
- Mantener trazabilidad entre una incidencia, el cambio aplicado y la validacion posterior.
|
|
- Diferenciar claramente observacion manual, alerta automatica y regresion confirmada.
|
|
|
|
## 9. Capa MCP
|
|
|
|
- Exponer capacidades del RAG como tools MCP reutilizables.
|
|
- Definir inicialmente retrieval y consulta de fuentes; limitar operaciones destructivas.
|
|
- Mantener HTTP como API base y MCP como adaptador, evitando duplicar la logica del servicio.
|
|
- Definir autenticacion, contratos y permisos antes de exponer operaciones adicionales.
|
|
|
|
## 10. Modelo de `answer`
|
|
|
|
- Evaluar y sustituir `openai/gpt-4.1-mini` por el modelo definitivo de respuesta.
|
|
- Comparar calidad, coste, latencia y dependencia del proveedor.
|
|
- Mantener `answer` construido sobre `retrieve` y evitar un segundo camino de recuperacion.
|
|
- Considerar esta tarea despues de las anteriores; integraciones como WhatsApp ya pueden usar `/retrieve` y dejar la respuesta final a su propio agente.
|
|
|
|
## Regla de mantenimiento
|
|
|
|
- No cambiar este orden sin confirmacion del usuario.
|
|
- Al completar un punto, registrar evidencia y marcar su estado sin renumerar silenciosamente los demas.
|
|
- Las tareas detalladas pueden vivir en documentos independientes, pero este archivo conserva la prioridad global del modulo.
|