paco/rag-service
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rag-service/docs/OPERATIVA.md

16 KiB
Raw Blame History

Operativa del servicio RAG

Modulo: RAG Ultima actualizacion: 2026-09-24 Version: 1.7

Este documento registra los hechos operativos del servicio RAG: la configuracion vigente en EasyPanel y la salida por etapas del OCR. No contiene secretos: las credenciales reales viven unicamente en EasyPanel.

Estado verificado (2026-09-24)

  • Preflight R5 de solo lectura (2026-09-23): el contenedor RAG usa la base db_rag con el rol usr_rag. rag_schema_migrations contiene 001_knowledge_lifecycle.sql, 002_ocr_review.sql y 003_ocr_recovery_audit.sql, todos con checksums coincidentes con el commit publicado; la unica migracion pendiente es 004_ocr_quality_diagnostics.sql.
  • Despliegue R5 verificado (2026-09-23): RAG y OCR exponen version=0.2.1 y revision=0654ce5; sus etiquetas OCI coinciden. Digests: RAG sha256:9a22730406c09c6b773891d8953f451e6263bf9fb0033188f4479f0b93ec8bbf, OCR sha256:6725991d3893a4f16ae6c75f28e9dd59b051bdbc344b28d79f1292224ddceda1. 004_ocr_quality_diagnostics.sql esta aplicada; OCR esta live/ready, con cola vacia, worker/sweeper operativos y almacenamiento disponible; RAG confirma PostgreSQL, Qdrant y reconciliador sanos.
  • Despliegue vigente verificado (2026-09-24): RAG y OCR exponen version=0.2.1 y revision=bfb2d48; sus etiquetas OCI coinciden, las migraciones 001-004 conservan sus checksums y PostgreSQL, Qdrant, reconciliador, OCR, cola y almacenamiento estan sanos.
  • Candidata R5 historica: FacturaTech v8 f4fd1502-1d4d-454f-bbfb-4c3b6820ee97 completo 25/25 paginas OCR y su revision visual, pero el 2026-09-24 fue rechazada por decision del usuario sin aprobarse, indexarse ni activarse. La version activa 3fc78163-9cfb-4979-985c-1520a63327b0 sigue intacta.
  • Limpieza pendiente: la candidata sintetica blank 6011a4eb-3e42-4ea4-a7da-a3e930cc60ed permanece review_required y la sintetica valida c4646668-30e4-409e-800d-23a8ee465a42 permanece purging. Los dos defectos que bloqueaban rechazo y purga estan corregidos y validados localmente; no reintentar la limpieza productiva hasta que el usuario despliegue la correccion.
  • Diagnostico de precision (2026-09-24): los PNG productivos verificados de las paginas 8, 15 y 16 muestran los ceros correctos, mientras ocr-result.json ya contiene las tres confusiones o/0 con confianza alta y la candidata las conserva sin cambios. Se descartan renderizado, reconstruccion y RAG como origen. El OCR queda aceptado para esta fase como servicio best-effort autonomo; la mejora de precision, la consola humana y un posible revisor visual por IA quedan diferidos. Esta aceptacion no aprueba ni activa v8.
  • KNOWLEDGE_LIFECYCLE_ENFORCED=true: el ciclo de vida del conocimiento esta activo; no queda pendiente ninguna activacion.
  • OCR_INGEST_ENABLED=true: la ingesta OCR esta habilitada en el RAG desplegado.
  • OCR_SERVICE_URL: configurada hacia el servicio privado ocr-service de la red interna.
  • OCR_INTERNAL_TOKEN: secreto compartido configurado en EasyPanel (RAG y servicio OCR); su valor nunca se documenta.
  • Volumen duradero del RAG en /data/ingestions: conserva originales y artefactos de revision.
  • Volumen transitorio del OCR en /data/jobs: cola SQLite y trabajos en curso.
  • La respuesta publica sin token de una ruta OCR protegida es 401, lo que confirma que el proceso desplegado tiene OCR habilitado. Con OCR deshabilitado, la misma ruta responderia 404 antes de autenticar.
  • El estado mostrado en EasyPanel debe contrastarse con su entorno persistido y con el entorno del contenedor en ejecucion; anteriormente la UI mostro valores distintos por variables duplicadas y desfasadas.
  • GET /health del RAG confirma PostgreSQL, Qdrant y reconciliador sanos. OCR responde internamente live=ok y ready=true, con cola vacia, worker/sweeper operativos y version/revision 0.2.1/bfb2d48.
  • La migracion 003_ocr_recovery_audit.sql esta aplicada y su tabla de auditoria existe.
  • Las rutas autenticadas de revision y recuperacion devuelven errores estructurados y seguros para una candidata inexistente: 404, OCR_CANDIDATE_NOT_FOUND y accion verify_version_id.
  • La candidata OCR heredada de FacturaTech v4 fue cerrada como failed el 2026-09-20 mediante recuperacion administrativa auditada tras confirmar OCR_ARTIFACT_UNAVAILABLE. No fue indexada ni activada; la fuente conserva su version activa y no tiene candidatas OCR bloqueantes.
  • Las imagenes en ejecucion tienen ambas etiquetas OCI org.opencontainers.image.revision=bfb2d48: EasyPanel recibe BUILD_REVISION durante el build. La identidad se verifica mediante las etiquetas y el health; los digests registrados de entregas anteriores son evidencia historica, no la identidad de la revision vigente.

Version de despliegue

  • La version correcta de cada despliegue es la declarada en el fichero raiz VERSION del commit que se publica (para la entrega actual, 0.2.1). No reutilizar numeros escritos en entradas historicas de este documento.
  • Ambas imagenes publican org.opencontainers.image.version y org.opencontainers.image.revision; las respuestas de salud muestran version y revision.
  • EasyPanel debe construir ambas imagenes con la version de VERSION y con BUILD_REVISION=<commit desplegado>.
  • Por decision del usuario, RAG y OCR se despliegan juntos con OCR_INGEST_ENABLED=true; no se desactiva preventivamente ni se introduce una ventana sin ingestas por protocolo.
  • OCR_INGEST_ENABLED=false y el despliegue por etapas se reservan para responder a un fallo real cuando sus sintomas y la evidencia indiquen que aislar un servicio ayudara al diagnostico o a la recuperacion.

Lista rapida en EasyPanel

  1. Rotar las credenciales expuestas (ver seccion siguiente); la rotacion sigue pendiente.
  2. Comprobar que las variables coinciden con la tabla de configuracion actual.
  3. Mantener OCR_INGEST_ENABLED=true; cambiarlo a false solo ante un fallo real que justifique aislar el flujo OCR.
  4. Pulsar Deploy en EasyPanel despues de cada cambio principal.
  5. Verificar GET /health del RAG y las rutas internas de salud del OCR tras cada deploy.
  6. Registrar el digest de cada imagen y confirmar que version y revision coinciden con la entrega desplegada.

Accion de seguridad urgente: rotar credenciales

Credenciales reales quedaron expuestas en una conversacion de chat. Hay que rotarlas:

  • La credencial de OpenRouter (variable EMBEDDING_API_KEY; y ANSWER_API_KEY si tiene valor propio).
  • La contrasena y la URL de PostgreSQL (variable POSTGRES_URL).
  • El token administrativo del ciclo de vida (variable LIFECYCLE_ADMIN_TOKEN).

Como hacerlo:

  • Generar valores nuevos y actualizarlos unicamente en EasyPanel.
  • Este documento no afirma que la rotacion ya se haya realizado.
  • Nunca pegar valores de credenciales en chat, documentacion, historial ni ficheros versionados.

Como se despliega

  • Tras cada cambio principal (variables de entorno o codigo nuevo subido por Git), el usuario pulsa el boton Deploy de EasyPanel.
  • No existe ninguna accion automatizada documentada sobre EasyPanel: ni scripts, ni comandos de panel, ni webhooks. El deploy siempre lo dispara una persona desde el panel.
  • Verificacion minima tras cada deploy: GET /health del RAG.

Acceso remoto a VPS2

  • Entorno: VPS2 PRODUCCION.
  • Host SSH: 162.19.152.15, puerto 22, usuario debian.
  • Metodo actual: conexion SSH directa con password mediante SSH_ASKPASS temporal; nunca reenviar la contrasena por entrada estandar ni mostrarla en la salida.
  • Fuente canonica del procedimiento y de la credencial vigente: Empresa/Servidores/VPS2/Vps2_despliegue_apps/instrucciones_montado_y_despliegue_apps_vps2_easypanel.md.
  • Verificacion de acceso: 2026-09-23, conexion directa correcta como debian al host vps-4863ac0d.
  • Antes de cualquier accion remota, indicar expresamente VPS2 PRODUCCION; las comprobaciones que no contacten ese host se etiquetan LOCAL.
  • La contrasena no se copia en este repositorio, historial ni chat. Si cambia, actualizarla solo en la fuente canonica.

Configuracion actual (valores no secretos)

Valores vigentes confirmados en produccion (2026-09-17):

Variable Valor actual
NODE_ENV production
PORT 80
QDRANT_URL http://qdrant:6333
QDRANT_API_KEY vacia (sin valor)
QDRANT_COLLECTION rag_chunks
EMBEDDING_PROVIDER openrouter
EMBEDDING_MODEL qwen/qwen3-embedding-8b
EMBEDDING_BASE_URL https://openrouter.ai/api/v1
ANSWER_PROVIDER openrouter
ANSWER_MODEL openai/gpt-4.1-mini
ANSWER_BASE_URL https://openrouter.ai/api/v1
POSTGRES_SSL false
KNOWLEDGE_LIFECYCLE_ENFORCED true
INGEST_WRITES_ENABLED true
OCR_INGEST_ENABLED true
OCR_SERVICE_URL configurada hacia el servicio privado ocr-service

Notas de comportamiento (derivadas del codigo, sin secretos):

  • Si ANSWER_API_KEY no se define, el codigo reutiliza EMBEDDING_API_KEY.
  • Si POSTGRES_URL no se define, el codigo prueba DATABASE_URL.
  • Si OCR_INGEST_ENABLED no existe, el codigo tambien la toma como false; por eso debe existir explicitamente con valor true en el entorno persistido de EasyPanel.
  • Un cambio en KNOWLEDGE_LIFECYCLE_ENFORCED, INGEST_WRITES_ENABLED o OCR_INGEST_ENABLED se hace siempre en EasyPanel y se registra en este documento.

Variables con secretos

Estas variables contienen credenciales reales. Aqui solo se registran sus nombres:

Variable Estado
EMBEDDING_API_KEY Configurada en EasyPanel; nunca copiarla en documentacion.
ANSWER_API_KEY Configurada en EasyPanel; nunca copiarla en documentacion.
POSTGRES_URL Configurada en EasyPanel; nunca copiarla en documentacion.
LIFECYCLE_ADMIN_TOKEN Configurada en EasyPanel; nunca copiarla en documentacion.
OCR_INTERNAL_TOKEN Configurada en EasyPanel, compartida con el servicio OCR y enviada como Authorization: Bearer; nunca copiarla en documentacion.

Salida por etapas del OCR

El OCR es un servicio privado e independiente. El RAG solo lo llama si OCR_INGEST_ENABLED esta activo; con el flag apagado, la ingesta sigue el flujo nativo actual, sin cambios. Hoy el flag esta en true en el RAG desplegado.

Servicio OCR privado (referencia de configuracion)

  • Contenedor ocr-service, imagen Python CPU con PaddleOCR 3.4.0 y PaddlePaddle 3.2.2.
  • Una sola replica y un solo worker; limites del servicio: maximo 3 CPU y 5 GiB de RAM.
  • Modelos descargados durante el build, nunca en el arranque.
  • Solo red interna del proyecto (easypanel-ia_servicios), sin dominio publico.
  • OCR_SERVICE_URL apunta al servicio OCR interno por el puerto 8000; el valor por defecto del codigo es http://ocr-service:8000, valido para un servicio llamado ocr-service en la red interna.
  • Limites fijos (no configurables por variables): cola de 3 trabajos, concurrencia 1, render a 200 DPI, maximo 50 MiB por PDF y 100 paginas por trabajo.
  • Cada trabajo dispone de un lease y un limite total de 15 minutos. Solo se recupera una vez; la segunda interrupcion o el timeout son terminales.
  • La readiness es falsa hasta que modelo, worker, sweeper y almacenamiento estan operativos; expone conteos por estado, recuperaciones y ultima limpieza sin incluir secretos. El healthcheck de arranque concede 90 segundos.

Volumenes

Volumen Ruta Papel
Duradero del RAG /data/ingestions Originales y artefactos de revision conservados.
Transitorio del OCR /data/jobs Cola SQLite, PDFs y resultados en curso.

Limpieza transitoria del OCR

  • Las filas transitorias, el PDF y los resultados del OCR se eliminan tras la transferencia duradera al RAG, cuando el resultado es aceptado.
  • Si esa transferencia no llega, un sweeper ejecutado al arrancar y cada 15 minutos expira los trabajos a las 24 horas, hace checkpoint WAL y vacuum incremental.
  • Antes de admitir el PDF y antes de publicar cada PNG, OCR limita su uso al menor entre 10 % del filesystem y 2 GiB, reservando libre el mayor entre 10 % y 2 GiB. La presion falla cerrada como OCR_STORAGE_PRESSURE.
  • La limpieza transitoria nunca toca los artefactos duraderos del RAG ni el corpus activo.
  • RAG incorpora desde la revision bfb2d48 un scheduler durable basado en next_attempt_at, con backoff de 2 a 15 segundos y un unico temporizador. El reconciliador de 300000 ms permanece activo como fallback global.

Verificacion posterior al despliegue (cuando cambian ambos servicios)

  1. Publicar el codigo en Git main y desplegar juntos OCR y RAG con la version indicada en VERSION y OCR_INGEST_ENABLED=true.
  2. Verificar el OCR internamente: GET /health/live y GET /health/ready deben responder con el servicio preparado.
  3. Verificar GET /health del RAG: PostgreSQL, Qdrant y reconciliador deben estar correctos.
  4. Comprobar una ruta OCR protegida sin token. Un 401 Lifecycle admin token is required confirma que OCR esta habilitado y que la autenticacion administrativa permanece protegida; no es un error que requiera correccion.
  5. Contrastar OCR_INGEST_ENABLED=true en el entorno persistido de EasyPanel y en el proceso del contenedor si la UI no coincide con el comportamiento efectivo.
  6. Consultar con token administrativo una version inexistente en revision y recuperacion: ambas deben devolver un error estructurado 404 OCR_CANDIDATE_NOT_FOUND sin modificar datos.
  7. Confirmar que rag_schema_migrations contiene 003_ocr_recovery_audit.sql y que existe rag_ocr_recovery_audit.
  8. Revisar los digests y confirmar que las etiquetas OCI y las respuestas de salud muestran 0.2.1 y el commit desplegado, no unknown.
  9. Tras completar estas comprobaciones, crear una candidata FacturaTech no activa. No aprobar, indexar ni activar hasta presentar la evidencia al usuario y recibir autorizacion explicita.

Rollback de emergencia

  • Ante un fallo cuyos sintomas indiquen que conviene aislar OCR: poner OCR_INGEST_ENABLED=false, desplegar el RAG y conservar la version activa actual del corpus. No aplicar este paso automaticamente a fallos no relacionados.
  • El sistema es fail-closed: un fallo del OCR deja intacta la version activa anterior; no hay activacion parcial.
  • Las paginas con OCR no se activan solas; pasan por el contrato de revision en estado review_required. En la fase autonoma actual esa revision puede ejecutarla el agente; una futura consola humana reutilizara el mismo contrato.
  • Desactivar el OCR no borra el corpus activo ni exige reingesta.
  • Si se revierte a 0.2.0, la migracion aditiva 004_ocr_quality_diagnostics.sql permanece aplicada. No se eliminan sus columnas ni su fila de historial; antes de reabrir trafico se verifica que RAG y OCR 0.2.0 arrancan y pasan health con ese esquema extendido.

Limites opcionales del RAG (valores por defecto del codigo)

Variable Valor por defecto
OCR_MAX_UPLOAD_BYTES 52428800 (50 MiB)
OCR_MAX_PAGES 100
LIFECYCLE_RECONCILE_INTERVAL_MS 300000
LIFECYCLE_INDEXING_STALE_TIMEOUT_MS 1800000
QDRANT_LOGS_COLLECTION rag_eval_logs

Verificaciones habituales

  • GET /health del RAG: estado general con PostgreSQL, Qdrant y reconciliador.
  • GET /health/live y GET /health/ready del servicio OCR: solo accesibles desde la red interna del proyecto.
  • Tras cambiar cualquier variable: pulsar Deploy y verificar /health.

Reglas de uso de este documento

  • Consultarlo antes de tareas con servicios externos, credenciales, despliegues o ejecuciones recurrentes.
  • Nunca escribir secretos aqui: solo nombres de variables y donde viven (EasyPanel).
  • Si un hecho operativo deja de ser valido, actualizarlo o marcarlo como obsoleto en la misma intervencion en que se descubra.