rag-service/docs/OPERATIVA.md

Operativa del servicio RAG

Modulo: RAG Ultima actualizacion: 2026-09-16 Version: 1.1

---

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-16)

• KNOWLEDGE_LIFECYCLE_ENFORCED=true: el ciclo de vida del conocimiento esta activo; no queda pendiente ninguna activacion.
• OCR_INGEST_ENABLED=false: la ingesta sigue el flujo nativo, sin OCR.
• 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.
• Verificadas exactamente 29 variables de entorno del RAG en EasyPanel, todas unicas y sin nombres duplicados.

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=false hasta completar el orden seguro de salida del OCR.
4. Pulsar Deploy en EasyPanel despues de cada cambio principal.
5. Verificar GET /health tras cada deploy.

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.

Configuracion actual (valores no secretos)

Valores vigentes confirmados en EasyPanel (2026-09-16):

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	false
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.
• 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 false en EasyPanel.

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.
• La readiness es falsa hasta que los modelos estan cargados; 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, la limpieza automatica expira los trabajos a las 24 horas.
• La limpieza transitoria nunca toca los artefactos duraderos del RAG ni el corpus activo.

Orden seguro de salida (cuando cambian ambos servicios)

1. Publicar el codigo en Git main (autorizacion ya concedida de forma separada).
2. Desplegar primero el servicio OCR.
3. Verificar el OCR: GET /health/live y GET /health/ready responden; un trabajo real autenticado llega a succeeded, devuelve un resultado ligado por integridad y admite limpieza transitoria.
4. Desplegar el RAG en segundo lugar manteniendo OCR_INGEST_ENABLED=false.
5. Verificar la ruta nativa del RAG: /health, ingesta textual, retrieval y corpus activo protegido, sin regresiones.
6. Solo entonces activar el OCR: OCR_INGEST_ENABLED=true y volver a pulsar Deploy en el RAG.
7. Presentar el PDF de FacturaTech como candidato de revision no activado, con el sourceRef logico Errores Junio 2026 - OCR verificado.md. La aprobacion humana sigue siendo obligatoria antes de cualquier activacion.

Rollback de emergencia

• Ante cualquier fallo: poner OCR_INGEST_ENABLED=false, pulsar Deploy en el RAG y conservar la version activa actual del corpus.
• 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; requieren revision humana obligatoria (estado review_required).
• Desactivar el OCR no borra el corpus activo ni exige reingesta.

Limites opcionales del RAG (valores por defecto del codigo)

Variable	Valor por defecto
OCR_MAX_UPLOAD_BYTES	52428800 (50 MiB)
OCR_MAX_PAGES	100
OCR_PAGE_TIMEOUT_MS	60000
OCR_TOTAL_TIMEOUT_MS	900000 (15 min)
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.