Paddle ocr, easyicr and doctr gpu support. (#4)

docs/07_anexo_a.md

@@ -8,61 +8,210 @@ 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
+
+**Tabla A1.** *Especificaciones del 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 |
+
+*Fuente: Elaboración propia.*
+
+### Dependencias
+
+**Tabla A2.** *Dependencias del proyecto.*
 
 | Componente | Versión |
 |------------|---------|
-| Python | 3.11.9 |
-| PaddlePaddle | 3.2.2 |
-| PaddleOCR | 3.3.2 |
+| Python | 3.12.3 |
+| Docker | 29.1.5 |
+| NVIDIA Container Toolkit | Requerido para GPU |
 | Ray | 2.52.1 |
-| Optuna | 4.6.0 |
-| jiwer | (última versión) |
-| PyMuPDF | (última versión) |
+| Optuna | 4.7.0 |
 
-## A.4 Instrucciones de Ejecución
+*Fuente: Elaboración propia.*
 
-1. Clonar el repositorio
-2. Instalar dependencias: `pip install -r requirements.txt`
-3. Ejecutar el notebook `src/paddle_ocr_fine_tune_unir_raytune.ipynb`
+## A.4 Instrucciones de Ejecución de Servicios OCR
 
-## A.5 Licencia
+### PaddleOCR (Puerto 8002)
+
+**Imágenes Docker:**
+- GPU: `seryus.ddns.net/unir/paddle-ocr-gpu`
+- CPU: `seryus.ddns.net/unir/paddle-ocr-cpu`
+
+```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)
+
+**Imagen Docker:** `seryus.ddns.net/unir/doctr-gpu`
+
+```bash
+cd src/doctr_service
+
+# GPU
+docker compose up -d
+```
+
+### EasyOCR (Puerto 8002)
+
+**Imagen Docker:** `seryus.ddns.net/unir/easyocr-gpu`
+
+```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
+
+**Tabla A3.** *Servicios Docker y puertos.*
+
+| Servicio | Puerto | Script de Ajuste |
+|----------|--------|------------------|
+| PaddleOCR | 8002 | `paddle_ocr_payload` |
+| DocTR | 8003 | `doctr_payload` |
+| EasyOCR | 8002 | `easyocr_payload` |
+
+*Fuente: Elaboración propia.*
+
+## 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.76% CER baseline, **1.49% optimizado**)
+- [DocTR](metrics/metrics_doctr.md) - Más rápido (0.50s/página)
+- [EasyOCR](metrics/metrics_easyocr.md) - Balance intermedio
+
+### Resumen de Resultados
+
+**Tabla A4.** *Resumen de resultados del benchmark por servicio.*
+
+| 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% |
+
+*Fuente: Elaboración propia.*
+
+## A.8 Licencia
 
 El código se distribuye bajo licencia MIT.