Servicio OpenAPI (FastAPI) que orquesta OCR, chunking semántico y generación de embeddings para documentos almacenados como Large Objects en PostgreSQL. Diseñado para ejecutarse con aceleración GPU (NVIDIA).

• feature/<alcance> para nuevas capacidades
• fix/<alcance> para correcciones normales
• hotfix/<alcance> para correcciones urgentes con destino directo a main

1. Crear rama desde develop.
2. Abrir PR hacia develop para cambios normales.
3. Cuando develop esté estable, promover hacia main con PR.
4. Ramas temporales se borran automáticamente tras merge.

1. Arquitectura general
2. Requisitos de hardware
3. Requisitos de software
4. Instalación paso a paso
5. Variables de entorno
6. Arranque del servicio
7. Validación post-despliegue
8. Catálogo de endpoints
9. Autenticación JWT
10. Pipeline de procesamiento
11. Sistema de logs
12. Compatibilidad GPU
13. Modelos utilizados
14. Formatos de archivo soportados
15. Ejemplo de request/response
16. Troubleshooting

┌──────────────┐     HTTP/JSON      ┌─────────────────────────────────────────┐
│  Caller      │ ─────────────────► │  ocr_chunking.py (FastAPI + Uvicorn)    │
│  (Airflows)  │ ◄───────────────── │                                         │
└──────────────┘                    │  ┌──────────┐ ┌────────┐ ┌───────────┐  │
                                    │  │ Docling   │ │PyMuPDF │ │ RapidOCR  │  │
                                    │  │ OCR/Parse │ │FastPath│ │ ONNX+GPU  │  │
                                    │  └────┬─────┘ └───┬────┘ └─────┬─────┘  │
                                    │       └───────────┴────────────┘        │
                                    │                  │                       │
                                    │       ┌──────────▼──────────┐           │
                                    │       │ HybridChunker       │           │
                                    │       │ (docling-core)      │           │
                                    │       └──────────┬──────────┘           │
                                    │                  │                       │
                                    │       ┌──────────▼──────────┐           │
                                    │       │ Embeddings GPU      │           │
                                    │       │ multilingual-e5     │           │
                                    │       │ (torch fp16+AMP)    │           │
                                    │       └──────────┬──────────┘           │
                                    │                  │                       │
                                    └──────────────────┼───────────────────────┘
                                                       │
                                              ┌────────▼────────┐
                                              │   PostgreSQL     │
                                              │   (pgvector)     │
                                              └─────────────────┘

Archivo principal único: ocr_chunking.py (~4400 líneas). No hay módulos adicionales.

Importante: La versión de PyTorch (cu126 vs cu130) cambia según la GPU. Ver sección Compatibilidad GPU.

python -m venv venv
source venv/bin/activate        # Linux
# venv\Scripts\activate          # Windows

Para RTX A6000 (Ampere, sm_86) — PRODUCCIÓN:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

Para RTX 5090 (Blackwell, sm_120) — DESARROLLO:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130

Este paso DEBE hacerse ANTES de instalar requirements.txt. PyTorch no está en requirements.txt porque su versión depende de la GPU del host.

pip install -r requirements.txt

python -c "
import torch
print('torch:', torch.__version__)
print('CUDA:', torch.cuda.is_available())
print('GPU:', torch.cuda.get_device_name(0))
print('Arch list:', torch.cuda.get_arch_list())
t = torch.randn(3,3, device='cuda')
print('Tensor test OK:', t.device)
"

Salida esperada para RTX A6000:

torch: 2.10.0+cu126
CUDA: True
GPU: NVIDIA RTX A6000
Arch list: ['sm_50', 'sm_60', 'sm_61', 'sm_70', 'sm_75', 'sm_80', 'sm_86', 'sm_90']
Tensor test OK: cuda:0

sm_86 DEBE aparecer en Arch list. Si no aparece, la GPU fallará en runtime.

python -c "
import onnxruntime as ort
print('onnxruntime:', ort.__version__)
print('Providers:', ort.get_available_providers())
"

Salida esperada:

onnxruntime: 1.24.4
Providers: ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']

CUDAExecutionProvider DEBE aparecer. Lo usa RapidOCR para OCR con GPU.

# PostgreSQL
OCR_DB_HOST=10.0.1.50
OCR_DB_PORT=5432
OCR_DB_NAME=niledb
OCR_DB_USER=ocr_service
OCR_DB_PASSWORD=<password_seguro>

# JWT / Keycloak
OCR_AUTH_ENABLED=true
OCR_JWT_ISSUER=https://anh-pro.flows.ninja/auth/realms/airflows
OCR_JWT_EXPECTED_AZP=ocr-chunking-embeddings

# Logs
OCR_LOG_DIR=/var/log/ocr-chunking
OCR_LOG_RETENTION_DAYS=60
OCR_LOG_LEVEL=INFO

python ocr_chunking.py --host 0.0.0.0 --port 8000

uvicorn ocr_chunking:app --host 0.0.0.0 --port 8000 --workers 1

Workers = 1 es obligatorio. El servicio mantiene modelos GPU en memoria (cache singleton) que no se comparten entre procesos. Usar más de 1 worker duplicaría el consumo de VRAM y causaría errores OOM.

# /etc/systemd/system/ocr-chunking.service
[Unit]
Description=Brain VT OCR Chunking Embeddings Service
After=network.target postgresql.service

[Service]
Type=simple
User=ocr-service
WorkingDirectory=/opt/brain-vt-ocr-chunking
EnvironmentFile=/opt/brain-vt-ocr-chunking/.env
ExecStart=/opt/brain-vt-ocr-chunking/venv/bin/uvicorn ocr_chunking:app --host 0.0.0.0 --port 8000 --workers 1
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

# GPU access
SupplementaryGroups=video render

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable ocr-chunking
sudo systemctl start ocr-chunking
sudo journalctl -u ocr-chunking -f    # ver logs

En el primer request que use embeddings o reranker, el servicio descarga los modelos correspondientes de HuggingFace:

Cada uno tarda 2-5 minutos según el ancho de banda. Los requests posteriores usan la cache local en ~/.cache/huggingface/.

Para pre-descargar ambos modelos antes de recibir tráfico:

python -c "
from transformers import AutoModel, AutoTokenizer, AutoModelForSequenceClassification

# Bi-encoder embeddings
embed = 'intfloat/multilingual-e5-large-instruct'
AutoTokenizer.from_pretrained(embed)
AutoModel.from_pretrained(embed)
print(f'{embed} OK')

# Cross-encoder reranker (solo necesario si se usa resolver F1)
rerank = 'BAAI/bge-reranker-v2-m3'
AutoTokenizer.from_pretrained(rerank)
AutoModelForSequenceClassification.from_pretrained(rerank)
print(f'{rerank} OK')
"

Después de desplegar, ejecutar estos endpoints en orden para verificar que todo funciona:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/health

Respuesta esperada: {"status": "ok", ...}

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/validate-gpu

Verificar en la respuesta:

• status = "ok"
• devices[0].name = "NVIDIA RTX A6000"
• devices[0].architecture.sm_code = "sm_86"
• devices[0].compatible_with_torch = true
• onnxruntime.gpu_enabled = true

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/validate-cuda-stress

Verificar: status = "ok" y cada device con status = "ok".

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/validate-libraries

Verificar: missing = [] (array vacío).

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/validate-db

Verificar: status = "ok".

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/validate-environment

Verificar: ready_for_production = true. Si es false, el campo checks indica qué falló.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@documento_prueba.pdf" \
  http://localhost:8000/validate-pipeline/upload

Este endpoint ejecuta el pipeline completo (OCR → limpieza → chunking → embeddings GPU) sin escribir en BD. La respuesta incluye tiempos por fase, preview del texto, chunks y vectores generados. Si retorna status: "ok", el servicio está 100% operativo.

Todos los endpoints de procesamiento reciben el mismo modelo de request (OCRChunkingRequest) y difieren en las fases que ejecutan.

Endpoints stateless usados desde plpython3u (función IaCore.anhResolverDocumento) para convertir la pregunta del usuario en un documento_id antes de ejecutar las tools N3/N4. No dependen de Large Objects ni del pipeline OCR.

Arquitectura F1 (pipeline de resolución orquestado en plpython3u):

Pregunta del usuario
    │
    ▼
[LLM extract entidades]  ← ministral-3:14b (Ollama anh-inf2)
    │
    ▼
[/embed-query/process]   ← OCR service (E5-Large fp16)
    │
    ▼
[HNSW top-100 sobre custom.DocumentosFicha] + boost estructural
    │
    ▼
[/rerank-pairs/process]  ← OCR service (BGE-reranker-v2-m3 fp16)
    │
    ▼
[LLM judge top-5]        ← ministral-3:14b (prompt productivo)
    │
    ▼
documento_id (clear | ambiguo | silencio)

Request /embed-query/process:

{
  "text": "¿Cuál es el objeto del Reporte prueba de inyectividad CPO17-WI1 de 2012?",
  "max_length": 384,
  "model_name": "intfloat/multilingual-e5-large-instruct"
}

Response:

{
  "vector": [0.0123, -0.0456, ...],
  "dim": 1024,
  "tokens": 42,
  "model_name": "intfloat/multilingual-e5-large-instruct",
  "device": "cuda:0",
  "latency_ms": 338
}

Request /rerank-pairs/process:

{
  "query": "contrato Durillo 2009 E&P",
  "docs": [
    "Ctto 245 Durillo Enero 13 2009 E&P Emerald Energy",
    "Ctto 244 CPO 5 Dic 26 2008 E&P ONGC Videsh",
    "Ctto 190 Agerato Marzo 13 2008 E&P Emerald"
  ],
  "max_length": 512
}

Response (scores en el mismo orden de docs, sigmoid 0-1):

{
  "scores": [0.9544, 0.0023, 0.0081],
  "model_name": "BAAI/bge-reranker-v2-m3",
  "device": "cuda:0",
  "latency_ms": 163
}

Notas operativas:

• Ambos endpoints requieren JWT (require_service_auth) igual que los demás.
• Cache singleton de modelos en memoria: primera llamada ~10-15 s (descarga/carga), siguientes ~300 ms.
• VRAM combinada E5-Large + BGE-reranker en fp16: ~2.3 GB.
• /rerank-pairs/process acepta hasta 50 docs por llamada y max_length hasta 1024 tokens. Uso típico: top-20 tras dense retrieval, max_length=512.

Todos los endpoints requieren header Authorization: Bearer <token> validado contra Keycloak JWKS.

Claims validados:

• iss — issuer obligatorio
• exp — expiración obligatoria
• iat — issued at obligatorio
• aud — solo si se configura OCR_JWT_AUDIENCE
• azp — si se configura OCR_JWT_EXPECTED_AZP
• clientId — si se configura OCR_JWT_EXPECTED_CLIENT_ID

Para deshabilitar auth en testing: OCR_AUTH_ENABLED=false.

Request (oid) → Resolver documentoId → Leer Large Object → Selección de páginas
    → Probe extractabilidad → Extracción texto (Docling OCR / PyMuPDF fast path)
    → Limpieza determinista → Chunking (semántico / simple)
    → Embeddings GPU (fp16 + AMP) → Persistencia pgvector → Actualizar documento

El servicio elige automáticamente (engine: "auto"):

• PyMuPDF fast path: si el PDF tiene texto embebido con confianza ≥ 0.85. Más rápido, no usa GPU.
• Docling OCR: si el PDF es escaneado/imagen o confianza < 0.85. Usa RapidOCR con GPU via ONNX Runtime.

• Modelo en float16: reduce VRAM a la mitad (~1.1 GB vs ~2.2 GB para e5-large)
• torch.inference_mode(): menor overhead que no_grad()
• torch.amp.autocast("cuda"): mixed precision automática en inferencia
• ONNX Runtime GPU: RapidOCR usa CUDAExecutionProvider directamente, sin pasar por PyTorch

Cada ejecución del pipeline escribe un archivo .jsonl estructurado:

{LOG_DIR}/ocr-chunking/
  2026-03-21/
    pipeline_2026-03-21T10-30-00_oid-2299268.jsonl    ← ejecución exitosa
    pipeline_2026-03-21T10-35-12_oid-4455667.jsonl    ← ejecución exitosa
    validation_2026-03-21T11-00-00.jsonl               ← test de validación
    errors_2026-03-21.jsonl                             ← consolidado de errores del día

Directorio por defecto:

• Linux: /tmp/ocr-chunking-logs/ocr-chunking/
• Windows: C:\Users\<user>\AppData\Local\Temp\ocr-chunking-logs\ocr-chunking\

Recomendación producción: configurar OCR_LOG_DIR=/var/log/ocr-chunking con permisos del usuario del servicio.

Los logs no reemplazan stdout/stderr. El servicio escribe a ambos: logging estándar para Docker/journald y archivos JSONL para consulta vía API.

Regla: si la GPU es Blackwell (RTX 50xx), usar cu130. Para todo lo demás, usar cu126.

El endpoint GET /validate-gpu verifica esta compatibilidad automáticamente.

El servicio carga dos modelos transformer en GPU (ambos con cache singleton en memoria):

Total VRAM con ambos modelos cargados en fp16: ~2.3 GB. El reranker se carga lazy la primera vez que se invoca /rerank-pairs/process; si el despliegue no usa el resolver F1, no consume VRAM.

curl -X POST http://localhost:8000/PipelineOCR/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "oid": 2299268,
      "nombre_documento": "CTO_EyP_LLA_50_2013.pdf",
      "mime_type": "application/pdf",
      "documento_id": 1234,
      "created_by": 1101,
      "extraction": {
        "engine": "auto",
        "page_mode": "head_tail",
        "head_pages": 8,
        "tail_pages": 8
      },
      "chunking": {
        "strategy": "semantic"
      },
      "embedding": {
        "enabled": true,
        "save_to_db": true
      }
    }
  }'

{
  "status": "COMPLETED",
  "exitoso": true,
  "message": "Proceso 'pipeline' completado exitosamente.",
  "error": null,
  "phases": [
    {"phase": "REQUEST_VALIDATION", "status": "OK", "message": "Request recibida.", ...},
    {"phase": "LOAD_BINARY", "status": "OK", ...},
    {"phase": "PAGE_SELECTION", "status": "OK", ...},
    {"phase": "TEXT_EXTRACTION", "status": "OK", ...},
    {"phase": "TEXT_CLEANING", "status": "OK", ...},
    {"phase": "CHUNKING", "status": "OK", ...},
    {"phase": "EMBEDDINGS", "status": "OK", ...},
    {"phase": "PERSIST", "status": "OK", ...},
    {"phase": "DOCUMENT_FINALIZE", "status": "OK", ...}
  ],
  "data": {
    "oid": 2299268,
    "documento_id_resuelto": 1234,
    "engine_used": "docling",
    "chunks_count": 47,
    "inserted_rows": 47,
    "elapsed_ms": 12450,
    "gpu": {"cuda_available": true, "device_name": "NVIDIA RTX A6000", ...}
  }
}

{
  "status": "FAILED",
  "exitoso": false,
  "message": "Proceso fallido.",
  "error": {
    "phase": "TEXT_EXTRACTION",
    "code": "EMPTY_EXTRACTED_TEXT",
    "message": "No se pudo extraer texto del archivo.",
    "details": {"engine": "docling"}
  },
  "phases": [...]
}

Causa: PyTorch fue compilado para una arquitectura GPU diferente a la instalada.

Solución: Reinstalar PyTorch con el CUDA index correcto para la GPU:

# Para RTX A6000 (Ampere)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126 --force-reinstall

# Para RTX 5090 (Blackwell)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130 --force-reinstall

Verificar con GET /validate-gpu que compatible_with_torch = true.

Causa: onnxruntime-gpu no instalado. RapidOCR hace fallback a PyTorch para OCR, que puede fallar en GPUs nuevas.

Solución:

pip install onnxruntime-gpu==1.24.4

Causa: Modelo cargado en fp32 o batch_size muy alto.

Solución: El servicio ya carga modelos en fp16 por defecto. Si persiste:

• Reducir embedding.batch_size en el request (default: 8)
• Verificar que no hay otros procesos usando la GPU: nvidia-smi

Causa normal: El modelo de embeddings se descarga de HuggingFace la primera vez.

Solución: Pre-descargar antes de recibir tráfico:

python -c "
from transformers import AutoModel, AutoTokenizer
AutoTokenizer.from_pretrained('intfloat/multilingual-e5-large-instruct')
AutoModel.from_pretrained('intfloat/multilingual-e5-large-instruct')
"

Causa: Variables de entorno de BD no configuradas o PostgreSQL no accesible.

Solución: Verificar OCR_DB_HOST, OCR_DB_PORT, OCR_DB_NAME, OCR_DB_USER, OCR_DB_PASSWORD. Probar con GET /validate-db.

Causa: torch y torchvision instalados desde índices CUDA diferentes.

Solución: Instalar ambos del mismo índice:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126 --force-reinstall

Estas son las versiones pinadas en requirements.txt y probadas en conjunto:

Nota: transformers se mantiene en 4.57.6 porque docling-ibm-models requiere transformers<5.0.0 y huggingface_hub<1. Esta restricción viene del ecosistema docling.