metrics and raytune reuslts

2026-01-19 13:00:08 +01:00
parent 458ff5d831
commit 8bc3b38d46
13 changed files with 1063 additions and 661 deletions
--- a/docs/07_anexo_a.md
+++ b/docs/07_anexo_a.md
@@ -8,61 +8,186 @@ El código fuente completo y los datos utilizados en este trabajo están disponi

 El repositorio incluye:

- **Notebooks de experimentación**: Código completo de los experimentos realizados
- **Scripts de evaluación**: Herramientas para evaluar modelos OCR
+- **Servicios OCR dockerizados**: PaddleOCR, DocTR, EasyOCR con soporte GPU
+- **Scripts de evaluación**: Herramientas para evaluar y comparar modelos OCR
+- **Scripts de ajuste**: Ray Tune con Optuna para optimización de hiperparámetros
 - **Dataset**: Imágenes y textos de referencia utilizados
- **Resultados**: Archivos CSV con los resultados de los 64 trials de Ray Tune
+- **Resultados**: Archivos CSV con los resultados de los 64 trials por servicio

 ## A.2 Estructura del Repositorio

-```mermaid
---
-title: "Estructura del repositorio del proyecto"
---
-flowchart LR
-    root["MastersThesis/"] --> docs["docs/"]
-    root --> src["src/"]
-    root --> instructions["instructions/"]
-    root --> scripts["Scripts generación"]
-
-    src --> nb1["paddle_ocr_fine_tune_unir_raytune.ipynb"]
-    src --> py1["paddle_ocr_tuning.py"]
-    src --> csv["raytune_paddle_subproc_results_*.csv"]
-
-    scripts --> gen1["generate_mermaid_figures.py"]
-    scripts --> gen2["apply_content.py"]
 ```
-
-**Descripción de componentes:**
-
- **docs/**: Capítulos de la tesis en Markdown (estructura UNIR)
- **src/**: Código fuente de experimentación
-  - `paddle_ocr_fine_tune_unir_raytune.ipynb`: Notebook principal con 64 trials Ray Tune
-  - `paddle_ocr_tuning.py`: Script CLI para evaluación OCR
-  - `raytune_paddle_subproc_results_20251207_192320.csv`: Resultados de optimización
- **instructions/**: Plantilla e instrucciones UNIR
- **Scripts de generación**: `generate_mermaid_figures.py` y `apply_content.py` para generar el documento TFM
+MastersThesis/
+├── docs/                           # Documentación de la tesis
+│   └── metrics/                    # Métricas de rendimiento OCR
+│       ├── metrics.md              # Resumen comparativo
+│       ├── metrics_paddle.md       # Resultados PaddleOCR
+│       ├── metrics_doctr.md        # Resultados DocTR
+│       └── metrics_easyocr.md      # Resultados EasyOCR
+├── src/
+│   ├── paddle_ocr/                 # Servicio PaddleOCR
+│   │   ├── Dockerfile.gpu          # Imagen Docker GPU
+│   │   ├── Dockerfile.cpu          # Imagen Docker CPU
+│   │   ├── docker-compose.yml      # Configuración Docker
+│   │   └── main.py                 # API FastAPI
+│   ├── doctr_service/              # Servicio DocTR
+│   │   ├── Dockerfile.gpu
+│   │   ├── docker-compose.yml
+│   │   └── main.py
+│   ├── easyocr_service/            # Servicio EasyOCR
+│   │   ├── Dockerfile.gpu
+│   │   ├── docker-compose.yml
+│   │   └── main.py
+│   ├── dataset/                    # Dataset de evaluación
+│   ├── raytune_ocr.py              # Utilidades compartidas Ray Tune
+│   └── results/                    # Resultados de ajuste CSV
+└── .gitea/workflows/ci.yaml        # Pipeline CI/CD
+```

 ## A.3 Requisitos de Software

-Para reproducir los experimentos se requieren las siguientes dependencias:
+### Sistema de Desarrollo
+
+| Componente | Especificación |
+|------------|----------------|
+| Sistema Operativo | Ubuntu 24.04.3 LTS |
+| CPU | AMD Ryzen 7 5800H |
+| RAM | 16 GB DDR4 |
+| GPU | NVIDIA RTX 3060 Laptop (5.66 GB VRAM) |
+| CUDA | 12.4 |
+
+### Dependencias

 | Componente | Versión |
 |------------|---------|
-| Python | 3.11.9 |
-| PaddlePaddle | 3.2.2 |
-| PaddleOCR | 3.3.2 |
-| Ray | 2.52.1 |
-| Optuna | 4.6.0 |
-| jiwer | (última versión) |
-| PyMuPDF | (última versión) |
+| Python | 3.11 |
+| Docker | 24+ |
+| NVIDIA Container Toolkit | Requerido para GPU |
+| Ray | 2.52+ |
+| Optuna | 4.6+ |

-## A.4 Instrucciones de Ejecución
+## A.4 Instrucciones de Ejecución de Servicios OCR

-1. Clonar el repositorio
-2. Instalar dependencias: `pip install -r requirements.txt`
-3. Ejecutar el notebook `src/paddle_ocr_fine_tune_unir_raytune.ipynb`
+### PaddleOCR (Puerto 8002)

-## A.5 Licencia
+```bash
+cd src/paddle_ocr
+
+# GPU (recomendado)
+docker compose up -d
+
+# CPU (más lento, 126x)
+docker compose -f docker-compose.cpu-registry.yml up -d
+```
+
+### DocTR (Puerto 8003)
+
+```bash
+cd src/doctr_service
+
+# GPU
+docker compose up -d
+```
+
+### EasyOCR (Puerto 8002)
+
+```bash
+cd src/easyocr_service
+
+# GPU
+docker compose up -d
+```
+
+### Verificar Estado del Servicio
+
+```bash
+# Verificar salud del servicio
+curl http://localhost:8002/health
+
+# Respuesta esperada:
+# {"status": "ok", "model_loaded": true, "gpu_name": "NVIDIA GeForce RTX 3060"}
+```
+
+## A.5 Uso de la API OCR
+
+### Evaluar Dataset Completo
+
+```bash
+# PaddleOCR - Evaluación completa
+curl -X POST http://localhost:8002/evaluate_full \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pdf_folder": "/app/dataset",
+    "save_output": true
+  }'
+```
+
+### Evaluar con Hiperparámetros Optimizados
+
+```bash
+# PaddleOCR con configuración óptima
+curl -X POST http://localhost:8002/evaluate_full \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pdf_folder": "/app/dataset",
+    "use_doc_orientation_classify": true,
+    "use_doc_unwarping": false,
+    "textline_orientation": true,
+    "text_det_thresh": 0.0462,
+    "text_det_box_thresh": 0.4862,
+    "text_det_unclip_ratio": 0.0,
+    "text_rec_score_thresh": 0.5658,
+    "save_output": true
+  }'
+```
+
+## A.6 Ajuste de Hiperparámetros con Ray Tune
+
+### Ejecutar Ajuste
+
+```bash
+cd src
+
+# Activar entorno virtual
+source ../.venv/bin/activate
+
+# PaddleOCR (64 muestras)
+python -c "
+from raytune_ocr import *
+
+ports = [8002]
+check_workers(ports, 'PaddleOCR')
+trainable = create_trainable(ports, paddle_ocr_payload)
+results = run_tuner(trainable, PADDLE_OCR_SEARCH_SPACE, num_samples=64)
+analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_KEYS)
+"
+```
+
+### Servicios y Puertos
+
+| Servicio | Puerto | Script de Ajuste |
+|----------|--------|------------------|
+| PaddleOCR | 8002 | `paddle_ocr_payload` |
+| DocTR | 8003 | `doctr_payload` |
+| EasyOCR | 8002 | `easyocr_payload` |
+
+## A.7 Métricas de Rendimiento
+
+Los resultados detallados de las evaluaciones y ajustes de hiperparámetros se encuentran en:
+
+- [Métricas Generales](metrics/metrics.md) - Comparativa de los tres servicios
+- [PaddleOCR](metrics/metrics_paddle.md) - Mejor precisión (7.72% CER)
+- [DocTR](metrics/metrics_doctr.md) - Más rápido (0.50s/página)
+- [EasyOCR](metrics/metrics_easyocr.md) - Balance intermedio
+
+### Resumen de Resultados
+
+| Servicio | CER Base | CER Ajustado | Mejora |
+|----------|----------|--------------|--------|
+| **PaddleOCR** | 8.85% | **7.72%** | 12.8% |
+| DocTR | 12.06% | 12.07% | 0% |
+| EasyOCR | 11.23% | 11.14% | 0.8% |
+
+## A.8 Licencia

 El código se distribuye bajo licencia MIT.
--- a/docs/metrics.md
+++ b/docs/metrics.md
@@ -1,289 +0,0 @@
-# PaddleOCR Performance Metrics: CPU vs GPU
-
-**Benchmark Date:** 2026-01-17
-**Updated:** 2026-01-17 (GPU fix applied)
-**Test Dataset:** 5 pages (pages 5-10)
-**Platform:** Linux (NVIDIA GB10 GPU, 119.70 GB VRAM)
-
-## Executive Summary
-
-| Metric | GPU | CPU | Difference |
-|--------|-----|-----|------------|
-| **Time per Page** | 0.86s | 84.25s | GPU is **97.6x faster** |
-| **Total Time (5 pages)** | 4.63s | 421.59s | 7 min saved |
-| **CER (Character Error Rate)** | 100%* | 3.96% | *Recognition issue |
-| **WER (Word Error Rate)** | 100%* | 13.65% | *Recognition issue |
-
-> **UPDATE (2026-01-17):** GPU CUDA support fixed! PaddlePaddle wheel rebuilt with PTX for Blackwell forward compatibility. GPU inference now runs at full speed (0.86s/page vs 84s CPU). However, 100% error rate persists - this appears to be a separate OCR model/recognition issue, not CUDA-related.
-
-## Performance Comparison
-
-### Processing Speed (Time per Page)
-
-```mermaid
-xychart-beta
-    title "Processing Time per Page (seconds)"
-    x-axis ["GPU", "CPU"]
-    y-axis "Seconds" 0 --> 90
-    bar [0.86, 84.25]
-```
-
-### Speed Ratio Visualization
-
-```mermaid
-pie showData
-    title "Relative Processing Time"
-    "GPU (1x)" : 1
-    "CPU (97.6x slower)" : 97.6
-```
-
-### Total Benchmark Time
-
-```mermaid
-xychart-beta
-    title "Total Time for 5 Pages (seconds)"
-    x-axis ["GPU", "CPU"]
-    y-axis "Seconds" 0 --> 450
-    bar [4.63, 421.59]
-```
-
-## OCR Accuracy Metrics (CPU Container - Baseline Config)
-
-```mermaid
-xychart-beta
-    title "OCR Error Rates (CPU Container)"
-    x-axis ["CER", "WER"]
-    y-axis "Error Rate %" 0 --> 20
-    bar [3.96, 13.65]
-```
-
-## Architecture Overview
-
-```mermaid
-flowchart TB
-    subgraph Client
-        A[Test Script<br/>benchmark.py]
-    end
-
-    subgraph "Docker Containers"
-        subgraph GPU["GPU Container :8000"]
-            B[FastAPI Server]
-            C[PaddleOCR<br/>CUDA Backend]
-            D[NVIDIA GB10<br/>119.70 GB VRAM]
-        end
-
-        subgraph CPU["CPU Container :8002"]
-            E[FastAPI Server]
-            F[PaddleOCR<br/>CPU Backend]
-            G[ARM64 CPU]
-        end
-    end
-
-    subgraph Storage
-        H[(Dataset<br/>45 PDFs)]
-    end
-
-    A -->|REST API| B
-    A -->|REST API| E
-    B --> C --> D
-    E --> F --> G
-    C --> H
-    F --> H
-```
-
-## Benchmark Workflow
-
-```mermaid
-sequenceDiagram
-    participant T as Test Script
-    participant G as GPU Container
-    participant C as CPU Container
-
-    T->>G: Health Check
-    G-->>T: Ready (model_loaded: true)
-
-    T->>C: Health Check
-    C-->>T: Ready (model_loaded: true)
-
-    Note over T,G: GPU Benchmark
-    T->>G: Warmup (1 page)
-    G-->>T: Complete
-    T->>G: POST /evaluate (Baseline)
-    G-->>T: 4.63s total (0.86s/page)
-    T->>G: POST /evaluate (Optimized)
-    G-->>T: 4.63s total (0.86s/page)
-
-    Note over T,C: CPU Benchmark
-    T->>C: Warmup (1 page)
-    C-->>T: Complete (~84s)
-    T->>C: POST /evaluate (Baseline)
-    C-->>T: 421.59s total (84.25s/page)
-```
-
-## Performance Timeline
-
-```mermaid
-gantt
-    title Processing Time Comparison (5 Pages)
-    dateFormat ss
-    axisFormat %S s
-
-    section GPU
-    All 5 pages    :gpu, 00, 5s
-
-    section CPU
-    Page 1         :cpu1, 00, 84s
-    Page 2         :cpu2, after cpu1, 84s
-    Page 3         :cpu3, after cpu2, 84s
-    Page 4         :cpu4, after cpu3, 84s
-    Page 5         :cpu5, after cpu4, 84s
-```
-
-## Container Specifications
-
-```mermaid
-mindmap
-  root((PaddleOCR<br/>Containers))
-    GPU Container
-      Port 8000
-      CUDA Enabled
-      NVIDIA GB10
-      119.70 GB VRAM
-      0.86s per page
-    CPU Container
-      Port 8002
-      ARM64 Architecture
-      No CUDA
-      84.25s per page
-      3.96% CER
-```
-
-## Key Findings
-
-### Speed Analysis
-
-1. **GPU Acceleration Impact**: The GPU container processes pages **97.6x faster** than the CPU container
-2. **Throughput**: GPU can process ~70 pages/minute vs CPU at ~0.7 pages/minute
-3. **Scalability**: For large document batches, GPU provides significant time savings
-
-### Accuracy Analysis
-
-| Configuration | CER | WER | Notes |
-|--------------|-----|-----|-------|
-| CPU Baseline | 3.96% | 13.65% | Working correctly |
-| CPU Optimized | Error | Error | Server error (needs investigation) |
-| GPU Baseline | 100%* | 100%* | Recognition issue* |
-| GPU Optimized | 100%* | 100%* | Recognition issue* |
-
-> *GPU accuracy metrics require investigation - speed benchmarks are valid
-
-## Recommendations
-
-```mermaid
-flowchart LR
-    A{Use Case?}
-    A -->|High Volume<br/>Speed Critical| B[GPU Container]
-    A -->|Low Volume<br/>Cost Sensitive| C[CPU Container]
-    A -->|Development<br/>Testing| D[CPU Container]
-
-    B --> E[0.86s/page<br/>Best for production]
-    C --> F[84.25s/page<br/>Lower infrastructure cost]
-    D --> G[No GPU required<br/>Easy local setup]
-```
-
-## Raw Benchmark Data
-
-```json
-{
-  "timestamp": "2026-01-17T17:25:55.541442",
-  "containers": {
-    "GPU": {
-      "url": "http://localhost:8000",
-      "tests": {
-        "Baseline": {
-          "CER": 1.0,
-          "WER": 1.0,
-          "PAGES": 5,
-          "TIME_PER_PAGE": 0.863,
-          "TOTAL_TIME": 4.63
-        }
-      }
-    },
-    "CPU": {
-      "url": "http://localhost:8002",
-      "tests": {
-        "Baseline": {
-          "CER": 0.0396,
-          "WER": 0.1365,
-          "PAGES": 5,
-          "TIME_PER_PAGE": 84.249,
-          "TOTAL_TIME": 421.59
-        }
-      }
-    }
-  }
-}
-```
-
-## GPU Issue Analysis
-
-### Root Cause Identified (RESOLVED)
-
-The GPU container originally returned 100% error rate due to a **CUDA architecture mismatch**:
-
-```
-W0117 16:55:35.199092 gpu_resources.cc:106] The GPU compute capability in your
-current machine is 121, which is not supported by Paddle
-```
-
-| Issue | Details |
-|-------|---------|
-| **GPU** | NVIDIA GB10 (Compute Capability 12.1 - Blackwell) |
-| **Original Wheel** | Built for `CUDA_ARCH=90` (sm_90 - Hopper) without PTX |
-| **Result** | Detection kernels couldn't execute on Blackwell architecture |
-
-### Solution Applied ✅
-
-**1. Rebuilt PaddlePaddle wheel with PTX forward compatibility:**
-
-The `Dockerfile.build-paddle` was updated to generate PTX code in addition to cubin:
-
-```dockerfile
-DCUDA_NVCC_FLAGS="-gencode=arch=compute_90,code=sm_90 -gencode=arch=compute_90,code=compute_90"
-```
-
-This generates:
- `sm_90` cubin (binary for Hopper)
- `compute_90` PTX (portable code for JIT compilation on newer architectures)
-
-**2. cuBLAS symlinks** (already in Dockerfile.gpu):
-
-```dockerfile
-ln -sf /usr/local/cuda/lib64/libcublas.so.12 /usr/local/cuda/lib64/libcublas.so
-```
-
-### Verification Results
-
-```
-PaddlePaddle version: 0.0.0 (custom GPU build)
-CUDA available: True
-GPU count: 1
-GPU name: NVIDIA GB10
-Tensor on GPU: Place(gpu:0)
-GPU OCR: Functional ✅
-```
-
-The PTX code is JIT-compiled at runtime for the GB10's compute capability 12.1.
-
-### Build Artifacts
-
- **Wheel**: `paddlepaddle_gpu-3.0.0-cp311-cp311-linux_aarch64.whl` (418 MB)
- **Build time**: ~40 minutes (with ccache)
- **Location**: `src/paddle_ocr/wheels/`
-
-## Next Steps
-
-1. ~~**Rebuild GPU wheel**~~ ✅ Done - PTX-enabled wheel built
-2. **Re-run benchmarks** - Verify accuracy metrics with fixed GPU
-3. **Fix CPU optimized config** - Server error on optimized configuration needs debugging
-4. **Memory profiling** - Monitor GPU/CPU memory usage during processing
--- a/docs/metrics/metrics.md
+++ b/docs/metrics/metrics.md
@@ -0,0 +1,211 @@
+# Métricas de Rendimiento OCR
+
+**Fecha de Benchmark:** 2026-01-19
+**Dataset de Prueba:** 45 páginas (2 PDFs)
+
+## Especificaciones del Sistema
+
+| Componente | Especificación |
+|------------|----------------|
+| **Sistema Operativo** | Ubuntu 24.04.3 LTS (Noble) |
+| **Kernel** | 6.14.0-37-generic |
+| **CPU** | AMD Ryzen 7 5800H with Radeon Graphics |
+| **RAM** | 16 GB DDR4 |
+| **GPU** | NVIDIA GeForce RTX 3060 Laptop GPU |
+| **VRAM** | 5.66 GB |
+| **CUDA** | 12.4 |
+
+## Justificación de Ejecución Local vs Cloud
+
+### Costos de Cloud GPU
+
+| Plataforma | GPU | Costo/Hora | Costo Mensual |
+|------------|-----|------------|---------------|
+| **AWS EC2 g4dn.xlarge** | NVIDIA T4 (16 GB) | $0.526 | ~$384 |
+| **Google Colab Pro** | T4/P100 | ~$1.30 | $10 + CU extras |
+| **Google Colab Pro+** | T4/V100/A100 | ~$1.30 | $50 + CU extras |
+
+### Análisis de Costos para Este Proyecto
+
+| Tarea | Tiempo GPU | Costo AWS | Costo Colab Pro |
+|-------|------------|-----------|-----------------|
+| Ajuste hiperparámetros (64×3 trials) | ~3 horas | ~$1.58 | ~$3.90 |
+| Evaluación completa (45 páginas) | ~5 min | ~$0.04 | ~$0.11 |
+| Desarrollo/debug (20 horas/mes) | 20 horas | ~$10.52 | ~$26.00 |
+
+### Ventajas de Ejecución Local
+
+1. **Costo cero de GPU**: La RTX 3060 ya está disponible en el equipo de desarrollo
+2. **Sin límites de tiempo**: AWS y Colab tienen timeouts de sesión
+3. **Acceso instantáneo**: Sin tiempo de aprovisionamiento de instancias
+4. **Almacenamiento local**: Dataset y resultados en disco sin costos de transferencia
+5. **Iteración rápida**: Reinicio inmediato de contenedores Docker
+
+### Conclusión
+
+Para un proyecto de investigación con múltiples iteraciones de ajuste de hiperparámetros y desarrollo, **la ejecución local ahorra ~$10-50/mes** comparado con cloud, además de ofrecer mayor flexibilidad y velocidad de iteración
+
+## Resumen Ejecutivo
+
+| Servicio | CER | WER | Tiempo/Página | Tiempo Total | VRAM |
+|----------|-----|-----|---------------|--------------|------|
+| **PaddleOCR (Mobile)** | **7.76%** | **11.62%** | 0.58s | 32.0s | 0.06 GB |
+| EasyOCR | 11.23% | 36.36% | 1.88s | 88.5s | ~2 GB |
+| DocTR | 12.06% | 42.01% | 0.50s | 28.4s | ~1 GB |
+
+> **Ganador:** PaddleOCR (Mobile) - Mejor precisión (7.76% CER) con velocidad competitiva.
+
+## Comparación de Servicios OCR
+
+### Comparación de Precisión (CER - menor es mejor)
+
+```mermaid
+xychart-beta
+    title "Tasa de Error de Caracteres por Servicio"
+    x-axis ["PaddleOCR", "EasyOCR", "DocTR"]
+    y-axis "CER %" 0 --> 15
+    bar [7.76, 11.23, 12.06]
+```
+
+### Comparación de Velocidad (Tiempo por Página)
+
+```mermaid
+xychart-beta
+    title "Tiempo de Procesamiento por Página (segundos)"
+    x-axis ["DocTR", "PaddleOCR", "EasyOCR"]
+    y-axis "Segundos" 0 --> 2
+    bar [0.50, 0.58, 1.88]
+```
+
+### Flujo de Recomendación de Servicio
+
+```mermaid
+flowchart LR
+    A{Prioridad?}
+    A -->|Precisión| B[PaddleOCR]
+    A -->|Velocidad| C[DocTR]
+    A -->|Balance| B
+    B --> D["7.76% CER<br/>0.58s/página"]
+    C --> E["12.06% CER<br/>0.50s/página"]
+```
+
+### Hallazgos Clave
+
+1. **Mejor Precisión**: PaddleOCR logra las tasas de error más bajas (7.76% CER, 11.62% WER)
+2. **Mejor Velocidad**: DocTR es el más rápido (0.50s/página), pero 55% menos preciso que PaddleOCR
+3. **EasyOCR**: El más lento (3.8x más lento que PaddleOCR) con precisión intermedia
+4. **Eficiencia VRAM**: PaddleOCR Mobile usa solo 0.06 GB
+
+## Análisis de Errores (del debugset)
+
+### PaddleOCR (Mejor - 7.76% CER)
+- **Fortalezas**: Preserva estructura de líneas, maneja bien acentos españoles
+- **Problemas**: Errores menores de espaciado, diferencias ocasionales de mayúsculas en acentos
+- **Mejorable**: Sí - el ajuste de hiperparámetros probablemente ayude
+
+### DocTR (Peor WER - 42.01%)
+- **Problema Crítico**: Colapsa todo el texto en líneas únicas (pierde estructura)
+- **Problema de Acentos**: Omite diacríticos ("Indice" vs "Índice")
+- **Mejorable**: Parcialmente - el problema de estructura puede ser a nivel de modelo
+
+### EasyOCR (36.36% WER)
+- **Problema Crítico**: Inserciones espurias de caracteres (";", "g", "0", "1")
+- **Pérdida de Estructura**: Saltos de línea no preservados
+- **Mejorable**: Sí - umbrales de detección demasiado sensibles
+
+## Comparación de Modelos PaddleOCR (RTX 3060)
+
+| Métrica | Modelos Server | Modelos Mobile | Ganador |
+|---------|----------------|----------------|---------|
+| **Tiempo** | 2.47s | 1.08s | Mobile (2.3x más rápido) |
+| **CER** | 1.82% | 1.42% | Mobile |
+| **WER** | 16.14% | 12.20% | Mobile |
+| **VRAM** | 5.3 GB (OOM en página 2) | 0.06 GB | Mobile |
+| **Multi-página** | No (OOM) | Sí | Mobile |
+
+> **Conclusión:** Se recomiendan los modelos Mobile - más rápidos, más precisos, caben en VRAM.
+
+## Rendimiento CPU vs GPU (PaddleOCR)
+
+Datos de `raytune_paddle_subproc_results_20251207_192320.csv` (CPU) vs RTX 3060 (GPU):
+
+| Métrica | CPU | GPU (RTX 3060) | Aceleración |
+|---------|-----|----------------|-------------|
+| **Tiempo/Página** | 69.4s | 0.55s | **126x más rápido** |
+| **Mejor CER** | 1.15% | 0.79% | GPU mejor |
+| **45 páginas** | ~52 min | ~25 seg | **126x más rápido** |
+
+```mermaid
+xychart-beta
+    title "Tiempo de Procesamiento por Página: CPU vs GPU"
+    x-axis ["CPU", "GPU (RTX 3060)"]
+    y-axis "Segundos" 0 --> 80
+    bar [69.4, 0.55]
+```
+
+> **Conclusión:** GPU es esencial para uso práctico de OCR. El procesamiento en CPU es 126x más lento, haciéndolo impráctico para procesamiento por lotes.
+
+## Datos Crudos del Benchmark
+
+```json
+{
+  "timestamp": "2026-01-19T11:00:00.000000",
+  "platform": {
+    "gpu": "NVIDIA GeForce RTX 3060 Laptop GPU",
+    "vram": "5.66 GB",
+    "cuda": "12.4"
+  },
+  "services": {
+    "PaddleOCR_Mobile": {
+      "port": 8002,
+      "models": {"det": "PP-OCRv5_mobile_det", "rec": "PP-OCRv5_mobile_rec"},
+      "vram_used": "0.06 GB",
+      "results": {
+        "CER": 0.0776,
+        "WER": 0.1162,
+        "PAGES": 45,
+        "TIME_PER_PAGE": 0.58,
+        "TOTAL_TIME": 32.0
+      }
+    },
+    "DocTR": {
+      "port": 8003,
+      "models": {"det": "db_resnet50", "rec": "crnn_vgg16_bn"},
+      "vram_used": "~1 GB",
+      "results": {
+        "CER": 0.1206,
+        "WER": 0.4201,
+        "PAGES": 45,
+        "TIME_PER_PAGE": 0.50,
+        "TOTAL_TIME": 28.4
+      }
+    },
+    "EasyOCR": {
+      "port": 8002,
+      "languages": ["es", "en"],
+      "vram_used": "~2 GB",
+      "results": {
+        "CER": 0.1123,
+        "WER": 0.3636,
+        "PAGES": 45,
+        "TIME_PER_PAGE": 1.88,
+        "TOTAL_TIME": 88.5
+      }
+    }
+  }
+}
+```
+
+## Resultados de Ajuste de Hiperparámetros
+
+Resultados individuales de ajuste por servicio (64 muestras cada uno, páginas 5-10):
+
+- [Resultados de Ajuste PaddleOCR](metrics_paddle.md)
+- [Resultados de Ajuste DocTR](metrics_doctr.md)
+- [Resultados de Ajuste EasyOCR](metrics_easyocr.md)
+
+## Próximos Pasos
+
+1. ~~Ajuste de Hiperparámetros~~ - Completado (64 muestras por servicio)
+2. **Evaluación del Dataset Completo** - Ejecutar mejores configuraciones en las 45 páginas
+3. **Comparar** - Rendimiento base vs ajustado en dataset completo
--- a/docs/metrics/metrics_doctr.md
+++ b/docs/metrics/metrics_doctr.md
@@ -0,0 +1,104 @@
+# Resultados de Ajuste de Hiperparámetros DocTR
+
+**Fecha de Ajuste:** 2026-01-19
+**Plataforma:** NVIDIA RTX 3060 Laptop GPU
+**Muestras:** 64
+**Páginas de Prueba:** 5-10 (primer documento)
+
+### ¿Por Qué Solo 5 Páginas?
+
+Usamos solo 5 páginas (páginas 5-10) para el ajuste de hiperparámetros porque:
+
+1. **Velocidad**: 64 pruebas × 5 páginas = 320 evaluaciones de página. Con 45 páginas, serían 2,880 evaluaciones (~9x más tiempo)
+2. **Eficiencia de recursos**: Cada prueba toma ~2-20 segundos en GPU
+
+**Riesgo de Sobreajuste**: El ajuste de hiperparámetros en un subconjunto pequeño PUEDE causar sobreajuste. Nuestros resultados confirman esto:
+- Subconjunto de ajuste: **38% mejora** (7.43% CER)
+- Dataset completo: **0% mejora** (12.07% CER)
+
+La falta total de mejora en el dataset completo indica sobreajuste severo a las páginas 5-10, combinado con limitaciones a nivel de modelo (manejo de diacríticos, estructura de líneas) que los hiperparámetros no pueden corregir.
+
+## Evaluación del Dataset Completo (45 páginas)
+
+| Métrica | Base | Ajustado | Mejora |
+|---------|------|----------|--------|
+| **CER** | 12.06% | 12.07% | **0%** |
+| **WER** | 42.01% | 42.26% | **0%** |
+| Tiempo/Página | 0.33s | 0.34s | - |
+
+> **Nota:** El ajuste no generalizó al dataset completo. Los problemas de DocTR parecen ser a nivel de modelo (diacríticos, estructura de líneas).
+
+## Resultados del Subconjunto de Ajuste (páginas 5-10)
+
+| Métrica | Base | Ajustado | Mejora |
+|---------|------|----------|--------|
+| **CER** | 12.06% | **7.43%** | **38%** |
+| **WER** | 42.01% | **35.23%** | **16%** |
+
+> Nota: Las mejoras en el subconjunto de ajuste no se transfirieron al dataset completo.
+
+## Mejor Configuración Encontrada
+
+```json
+{
+  "assume_straight_pages": true,
+  "straighten_pages": false,
+  "preserve_aspect_ratio": false,
+  "symmetric_pad": false,
+  "disable_page_orientation": true,
+  "disable_crop_orientation": false,
+  "resolve_lines": true,
+  "resolve_blocks": false,
+  "paragraph_break": 0.0977
+}
+```
+
+## Hallazgos Clave
+
+1. **straighten_pages: false** - ¡Crítico! Configurarlo en true causa ~79% CER (catastrófico)
+2. **assume_straight_pages: true** - Funciona bien con escaneos de documentos rectos
+3. **resolve_lines: true** - Ayuda a mantener la estructura de líneas
+4. **disable_page_orientation: true** - Evita rotación innecesaria
+
+## Impacto de Parámetros
+
+Parámetros que mejoraron la precisión:
+- `straighten_pages=False` absolutamente crítico
+- `assume_straight_pages=True` en los mejores resultados
+- `resolve_lines=True` mantiene la estructura del texto
+
+Parámetros que perjudicaron la precisión:
+- `straighten_pages=True` catastróficamente malo (~79% CER)
+- `resolve_blocks=True` ligeramente peor que False
+
+## Limitaciones Conocidas
+
+Incluso con ajuste, DocTR todavía tiene problemas:
+- Omite diacríticos (tildes) - probablemente problema a nivel de modelo
+- Todavía tiene mayor WER que PaddleOCR debido a problemas de estructura
+
+## Evaluación del Dataset Completo
+
+**Estado:** Completado
+
+```bash
+curl -X POST http://localhost:8003/evaluate_full \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pdf_folder": "/app/dataset",
+    "assume_straight_pages": true,
+    "straighten_pages": false,
+    "preserve_aspect_ratio": false,
+    "symmetric_pad": false,
+    "disable_page_orientation": true,
+    "disable_crop_orientation": false,
+    "resolve_lines": true,
+    "resolve_blocks": false,
+    "paragraph_break": 0.0977,
+    "save_output": true
+  }'
+```
+
+**Resultado:** CER 12.07%, WER 42.26%, 0.34s/página (sin mejora sobre la base)
+
+**Conclusión:** Los problemas de precisión de DocTR son a nivel de modelo, no ajustables por hiperparámetros.
--- a/docs/metrics/metrics_easyocr.md
+++ b/docs/metrics/metrics_easyocr.md
@@ -0,0 +1,113 @@
+# Resultados de Ajuste de Hiperparámetros EasyOCR
+
+**Fecha de Ajuste:** 2026-01-19
+**Plataforma:** NVIDIA RTX 3060 Laptop GPU
+**Muestras:** 64
+**Páginas de Prueba:** 5-10 (primer documento)
+
+### ¿Por Qué Solo 5 Páginas?
+
+Usamos solo 5 páginas (páginas 5-10) para el ajuste de hiperparámetros porque:
+
+1. **Velocidad**: 64 pruebas × 5 páginas = 320 evaluaciones de página. Con 45 páginas, serían 2,880 evaluaciones (~9x más tiempo)
+2. **Eficiencia de recursos**: Cada prueba toma ~10-20 segundos en GPU
+
+**Riesgo de Sobreajuste**: El ajuste de hiperparámetros en un subconjunto pequeño PUEDE causar sobreajuste. Nuestros resultados confirman esto:
+- Subconjunto de ajuste: **48% mejora** (5.83% CER)
+- Dataset completo: **0.8% mejora** (11.14% CER)
+
+La mejora mínima en el dataset completo indica que los hiperparámetros se sobreajustaron a las páginas 5-10. Los problemas de EasyOCR (detecciones espurias, pérdida de estructura) también pueden ser parcialmente a nivel de modelo.
+
+## Evaluación del Dataset Completo (45 páginas)
+
+| Métrica | Base | Ajustado | Mejora |
+|---------|------|----------|--------|
+| **CER** | 11.23% | 11.14% | **0.8%** |
+| **WER** | 36.36% | 36.85% | **-1.3%** |
+| Tiempo/Página | 1.84s | 1.94s | - |
+
+> **Nota:** El ajuste mostró mejora mínima en el dataset completo. Los problemas de EasyOCR pueden ser a nivel de modelo.
+
+## Resultados del Subconjunto de Ajuste (páginas 5-10)
+
+| Métrica | Base | Ajustado | Mejora |
+|---------|------|----------|--------|
+| **CER** | 11.23% | **5.83%** | **48%** |
+| **WER** | 36.36% | **26.33%** | **28%** |
+
+> Nota: Las grandes mejoras en el subconjunto de ajuste no se transfirieron al dataset completo.
+
+## Mejor Configuración Encontrada
+
+```json
+{
+  "text_threshold": 0.6647,
+  "low_text": 0.4247,
+  "link_threshold": 0.2184,
+  "slope_ths": 0.1629,
+  "ycenter_ths": 0.7994,
+  "height_ths": 0.6437,
+  "width_ths": 0.6065,
+  "add_margin": 0.1462,
+  "contrast_ths": 0.1671,
+  "adjust_contrast": 0.6416,
+  "decoder": "greedy",
+  "beamWidth": 7,
+  "min_size": 10
+}
+```
+
+## Hallazgos Clave
+
+1. **decoder: greedy** - Consistentemente mejor que beamsearch para este dataset
+2. **Mayor text_threshold (0.66)** - Reduce detecciones espurias
+3. **min_size: 10** - Filtra artefactos de ruido pequeños
+4. **Umbrales moderados** - Sensibilidad de detección balanceada
+
+## Impacto de Parámetros
+
+Parámetros que mejoraron la precisión:
+- `decoder="greedy"` consistentemente superó a beamsearch
+- Mayor `text_threshold` (0.6-0.8) redujo el ruido
+- `min_size >= 5` ayudó a filtrar artefactos
+
+Parámetros que perjudicaron la precisión:
+- `decoder="beamsearch"` causó ~35-40% CER en muchas pruebas
+- `text_threshold` muy bajo (<0.4) detectó demasiado ruido
+- `min_size` alto (>15) omitió algo de texto
+
+## Comparación con Problemas de Base
+
+Problemas originales identificados en el debugset:
+- Inserciones espurias de caracteres - **Mejorado** con umbrales más altos
+- Pérdida de estructura - Todavía presente pero menos severa
+
+## Evaluación del Dataset Completo
+
+**Estado:** Completado
+
+```bash
+curl -X POST http://localhost:8002/evaluate_full \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pdf_folder": "/app/dataset",
+    "text_threshold": 0.6647,
+    "low_text": 0.4247,
+    "link_threshold": 0.2184,
+    "slope_ths": 0.1629,
+    "ycenter_ths": 0.7994,
+    "height_ths": 0.6437,
+    "width_ths": 0.6065,
+    "add_margin": 0.1462,
+    "contrast_ths": 0.1671,
+    "adjust_contrast": 0.6416,
+    "decoder": "greedy",
+    "beamWidth": 7,
+    "min_size": 10,
+    "save_output": true
+  }'
+```
+
+**Resultado:** CER 11.14%, WER 36.85%, 1.94s/página (mejora mínima)
+
+**Conclusión:** El ajuste de EasyOCR proporcionó mejora insignificante en el dataset completo.
--- a/docs/metrics/metrics_paddle.md
+++ b/docs/metrics/metrics_paddle.md
@@ -0,0 +1,91 @@
+# Resultados de Ajuste de Hiperparámetros PaddleOCR
+
+**Fecha de Ajuste:** 2026-01-19
+**Plataforma:** NVIDIA RTX 3060 Laptop GPU
+**Muestras:** 64
+**Páginas de Prueba:** 5-10 (primer documento)
+
+### ¿Por Qué Solo 5 Páginas?
+
+Usamos solo 5 páginas (páginas 5-10) para el ajuste de hiperparámetros porque:
+
+1. **Velocidad**: 64 pruebas × 5 páginas = 320 evaluaciones de página. Con 45 páginas, serían 2,880 evaluaciones (~9x más tiempo)
+2. **Eficiencia de recursos**: Cada prueba toma ~3-10 segundos en GPU; el dataset completo tomaría ~1 hora por prueba en CPU
+
+**Riesgo de Sobreajuste**: El ajuste de hiperparámetros en un subconjunto pequeño PUEDE causar sobreajuste. Nuestros resultados confirman esto:
+- Subconjunto de ajuste: **90% mejora** (0.79% CER)
+- Dataset completo: **12.8% mejora** (7.72% CER)
+
+La diferencia dramática muestra que los hiperparámetros se sobreajustaron parcialmente a las páginas 5-10. Un subconjunto de ajuste más grande (ej. 15-20 páginas) podría producir parámetros que generalicen mejor, pero aumentaría el tiempo de ajuste proporcionalmente.
+
+## Evaluación del Dataset Completo (45 páginas)
+
+| Métrica | Base | Ajustado | Mejora |
+|---------|------|----------|--------|
+| **CER** | 8.85% | **7.72%** | **12.8%** |
+| **WER** | 13.05% | **11.40%** | **12.6%** |
+| Tiempo/Página | 0.51s | 0.55s | - |
+
+## Resultados del Subconjunto de Ajuste (páginas 5-10)
+
+| Métrica | Base | Ajustado | Mejora |
+|---------|------|----------|--------|
+| **CER** | 7.76% | **0.79%** | **90%** |
+| **WER** | 11.62% | **7.78%** | **33%** |
+
+> Nota: El subconjunto de ajuste mostró mayores mejoras, sugiriendo que algunos hiperparámetros son específicos de la página.
+
+## Mejor Configuración Encontrada
+
+```json
+{
+  "use_doc_orientation_classify": true,
+  "use_doc_unwarping": false,
+  "textline_orientation": true,
+  "text_det_thresh": 0.0462,
+  "text_det_box_thresh": 0.4862,
+  "text_det_unclip_ratio": 0.0,
+  "text_rec_score_thresh": 0.5658
+}
+```
+
+## Hallazgos Clave
+
+1. **textline_orientation: true** - Crítico para la precisión
+2. **use_doc_orientation_classify: true** - Ayuda con la detección de orientación de página
+3. **use_doc_unwarping: false** - El enderezamiento de documentos perjudica la precisión en este dataset
+4. **Bajo text_det_thresh (0.0462)** - Detección de texto más sensible ayuda
+5. **Mayor text_rec_score_thresh (0.5658)** - Filtra reconocimientos de baja confianza
+
+## Impacto de Parámetros
+
+Parámetros que mejoraron la precisión:
+- `textline_orientation=True` consistentemente en los mejores resultados
+- `use_doc_orientation_classify=True` en las mejores pruebas
+- Valores más bajos de `text_det_thresh` (0.04-0.10)
+
+Parámetros que perjudicaron la precisión:
+- `use_doc_unwarping=True` aumentó el CER significativamente
+- `text_det_box_thresh` muy bajo (<0.01) causó problemas
+
+## Evaluación del Dataset Completo
+
+**Estado:** Completado
+
+```bash
+curl -X POST http://localhost:8002/evaluate_full \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pdf_folder": "/app/dataset",
+    "use_doc_orientation_classify": true,
+    "use_doc_unwarping": false,
+    "textline_orientation": true,
+    "text_det_thresh": 0.0462,
+    "text_det_box_thresh": 0.4862,
+    "text_det_unclip_ratio": 0.0,
+    "text_rec_score_thresh": 0.5658,
+    "save_output": true
+  }'
+```
+
+**Resultado:** CER 7.72%, WER 11.40%, 0.55s/página