Markdown chapters.

2025-12-10 16:06:47 +01:00
parent 6ea2b4b6c2
commit a8198f0906
10 changed files with 1547 additions and 36 deletions
--- a/docs/05_optimizacion_hiperparametros.md
+++ b/docs/05_optimizacion_hiperparametros.md
@@ -0,0 +1,212 @@
+# Capítulo 5: Optimización de Hiperparámetros
+
+## 5.1 Introducción
+
+Este capítulo describe el proceso de optimización de hiperparámetros de PaddleOCR utilizando Ray Tune con el algoritmo de búsqueda Optuna. Los experimentos fueron implementados en el notebook `src/paddle_ocr_fine_tune_unir_raytune.ipynb` y los resultados se almacenaron en `src/raytune_paddle_subproc_results_20251207_192320.csv`.
+
+## 5.2 Configuración del Experimento
+
+### 5.2.1 Entorno de Ejecución
+
+Según los outputs del notebook:
+
+| Componente | Versión/Especificación |
+|------------|------------------------|
+| Python | 3.11.9 |
+| PaddlePaddle | 3.2.2 |
+| PaddleOCR | 3.3.2 |
+| Ray | 2.52.1 |
+| GPU | No disponible (CPU only) |
+
+### 5.2.2 Dataset
+
+Se utilizó un dataset estructurado en `src/dataset/` creado mediante el notebook `src/prepare_dataset.ipynb`:
+
+- **Estructura**: Carpetas con subcarpetas `img/` y `txt/` pareadas
+- **Páginas evaluadas por trial**: 5 (páginas 5-10 del documento)
+- **Gestión de datos**: Clase `ImageTextDataset` en `src/dataset_manager.py`
+
+### 5.2.3 Espacio de Búsqueda
+
+Según el código del notebook, se definió el siguiente espacio de búsqueda:
+
+```python
+search_space = {
+    "use_doc_orientation_classify": tune.choice([True, False]),
+    "use_doc_unwarping": tune.choice([True, False]),
+    "textline_orientation": tune.choice([True, False]),
+    "text_det_thresh": tune.uniform(0.0, 0.7),
+    "text_det_box_thresh": tune.uniform(0.0, 0.7),
+    "text_det_unclip_ratio": tune.choice([0.0]),  # Fijado
+    "text_rec_score_thresh": tune.uniform(0.0, 0.7),
+}
+```
+
+**Descripción de parámetros** (según documentación de PaddleOCR):
+
+| Parámetro | Descripción |
+|-----------|-------------|
+| `use_doc_orientation_classify` | Clasificación de orientación del documento |
+| `use_doc_unwarping` | Corrección de deformación del documento |
+| `textline_orientation` | Clasificación de orientación de línea de texto |
+| `text_det_thresh` | Umbral de detección de píxeles de texto |
+| `text_det_box_thresh` | Umbral de caja de detección |
+| `text_det_unclip_ratio` | Coeficiente de expansión (fijado en 0.0) |
+| `text_rec_score_thresh` | Umbral de confianza de reconocimiento |
+
+### 5.2.4 Configuración de Ray Tune
+
+```python
+tuner = tune.Tuner(
+    trainable_paddle_ocr,
+    tune_config=tune.TuneConfig(
+        metric="CER",
+        mode="min",
+        search_alg=OptunaSearch(),
+        num_samples=64,
+        max_concurrent_trials=2
+    ),
+    run_config=air.RunConfig(verbose=2, log_to_file=False),
+    param_space=search_space
+)
+```
+
+- **Métrica objetivo**: CER (minimizar)
+- **Algoritmo de búsqueda**: Optuna (TPE - Tree-structured Parzen Estimator)
+- **Número de trials**: 64
+- **Trials concurrentes**: 2
+
+## 5.3 Resultados de la Optimización
+
+### 5.3.1 Estadísticas Descriptivas
+
+Del archivo CSV de resultados (`raytune_paddle_subproc_results_20251207_192320.csv`):
+
+| Estadística | CER | WER | Tiempo (s) | Tiempo/Página (s) |
+|-------------|-----|-----|------------|-------------------|
+| **count** | 64 | 64 | 64 | 64 |
+| **mean** | 5.25% | 14.28% | 347.61 | 69.42 |
+| **std** | 11.03% | 10.75% | 7.88 | 1.57 |
+| **min** | 1.15% | 9.89% | 320.97 | 64.10 |
+| **25%** | 1.20% | 10.04% | 344.24 | 68.76 |
+| **50%** | 1.23% | 10.20% | 346.42 | 69.19 |
+| **75%** | 4.03% | 13.20% | 350.14 | 69.93 |
+| **max** | 51.61% | 59.45% | 368.57 | 73.63 |
+
+### 5.3.2 Mejor Configuración Encontrada
+
+Según el análisis del notebook:
+
+```
+Best CER: 0.011535 (1.15%)
+Best WER: 0.098902 (9.89%)
+
+Configuración óptima:
+  textline_orientation: True
+  use_doc_orientation_classify: False
+  use_doc_unwarping: False
+  text_det_thresh: 0.4690
+  text_det_box_thresh: 0.5412
+  text_det_unclip_ratio: 0.0
+  text_rec_score_thresh: 0.6350
+```
+
+### 5.3.3 Análisis de Correlación
+
+Correlación de Pearson entre parámetros y métricas de error (del notebook):
+
+**Correlación con CER:**
+| Parámetro | Correlación |
+|-----------|-------------|
+| CER | 1.000 |
+| config/text_det_box_thresh | 0.226 |
+| config/text_rec_score_thresh | -0.161 |
+| **config/text_det_thresh** | **-0.523** |
+| config/text_det_unclip_ratio | NaN |
+
+**Correlación con WER:**
+| Parámetro | Correlación |
+|-----------|-------------|
+| WER | 1.000 |
+| config/text_det_box_thresh | 0.227 |
+| config/text_rec_score_thresh | -0.173 |
+| **config/text_det_thresh** | **-0.521** |
+| config/text_det_unclip_ratio | NaN |
+
+**Hallazgo clave**: El parámetro `text_det_thresh` muestra la correlación más fuerte (-0.52), indicando que valores más altos de este umbral tienden a reducir el error.
+
+### 5.3.4 Impacto del Parámetro textline_orientation
+
+Según el análisis del notebook, este parámetro booleano tiene el mayor impacto:
+
+| textline_orientation | CER Medio | WER Medio |
+|---------------------|-----------|-----------|
+| True | ~3.76% | ~12.73% |
+| False | ~12.40% | ~21.71% |
+
+**Interpretación del notebook**:
+> "7x better CER with textline_orientation=True. And the variance is much tighter — more reliable results. For Spanish business documents with mixed layouts (tables, headers, addresses), orientation classification helps PaddleOCR correctly order text lines."
+
+### 5.3.5 Análisis de Fallos
+
+Los trials con CER muy alto (>40%) se produjeron cuando:
+- `text_det_thresh` < 0.1 (valores muy bajos)
+- `textline_orientation = False`
+
+Ejemplo de trial con fallo catastrófico:
+- CER: 51.61%
+- WER: 59.45%
+- Configuración: `text_det_thresh=0.017`, `textline_orientation=True`
+
+## 5.4 Comparación Baseline vs Optimizado
+
+### 5.4.1 Resultados sobre Dataset Completo (24 páginas)
+
+Del análisis final del notebook ejecutando sobre las 24 páginas:
+
+| Modelo | CER | WER |
+|--------|-----|-----|
+| PaddleOCR (Baseline) | 7.78% | 14.94% |
+| PaddleOCR-HyperAdjust | 1.49% | 7.62% |
+
+### 5.4.2 Métricas de Mejora
+
+| Métrica | Baseline | Optimizado | Mejora Absoluta | Reducción Error |
+|---------|----------|------------|-----------------|-----------------|
+| CER | 7.78% | 1.49% | -6.29 pp | 80.9% |
+| WER | 14.94% | 7.62% | -7.32 pp | 49.0% |
+
+### 5.4.3 Interpretación (del notebook)
+
+> "La optimización de hiperparámetros mejoró la precisión de caracteres de 92.2% a 98.5%, una ganancia de 6.3 puntos porcentuales. Aunque el baseline ya ofrecía resultados aceptables, la configuración optimizada reduce los errores residuales en un 80.9%."
+
+**Impacto práctico**: En un documento de 10,000 caracteres:
+- Baseline: ~778 caracteres con error
+- Optimizado: ~149 caracteres con error
+- Diferencia: ~629 caracteres menos con errores
+
+## 5.5 Tiempo de Ejecución
+
+| Métrica | Valor |
+|---------|-------|
+| Tiempo total del experimento | ~6 horas (64 trials × ~6 min/trial) |
+| Tiempo medio por trial | 367.72 segundos |
+| Tiempo medio por página | 69.42 segundos |
+| Total páginas procesadas | 64 trials × 5 páginas = 320 evaluaciones |
+
+## 5.6 Resumen del Capítulo
+
+Este capítulo ha presentado:
+
+1. **Configuración del experimento**: 64 trials con Ray Tune + Optuna sobre 7 hiperparámetros
+2. **Resultados estadísticos**: CER medio 5.25%, CER mínimo 1.15%
+3. **Hallazgos clave**:
+   - `textline_orientation=True` es crítico (reduce CER ~70%)
+   - `text_det_thresh` tiene correlación -0.52 con CER
+   - Valores bajos de `text_det_thresh` (<0.1) causan fallos catastróficos
+4. **Mejora final**: CER reducido de 7.78% a 1.49% (reducción del 80.9%)
+
+**Fuentes de datos:**
+- `src/paddle_ocr_fine_tune_unir_raytune.ipynb`: Código del experimento
+- `src/raytune_paddle_subproc_results_20251207_192320.csv`: Resultados de 64 trials
+- `src/paddle_ocr_tuning.py`: Script de evaluación