249 lines
9.9 KiB
Markdown
249 lines
9.9 KiB
Markdown
# Optimización de Hiperparámetros OCR con Ray Tune para Documentos Académicos en Español
|
||
|
||
**Trabajo Fin de Máster (TFM) – Máster Universitario en Inteligencia Artificial**
|
||
**Líneas:** Percepción computacional · Aprendizaje automático
|
||
**Autor:** Sergio Jiménez Jiménez · **UNIR** · **Año:** 2025
|
||
|
||
> Optimización sistemática de hiperparámetros de **PaddleOCR (PP-OCRv5)** mediante **Ray Tune** con **Optuna** para mejorar el reconocimiento óptico de caracteres en documentos académicos en español.
|
||
|
||
---
|
||
|
||
## Objetivo
|
||
|
||
Optimizar el rendimiento de PaddleOCR para documentos académicos en español mediante ajuste de hiperparámetros, alcanzando un **CER inferior al 2%** sin requerir fine-tuning del modelo ni recursos GPU dedicados.
|
||
|
||
**Resultado alcanzado:** CER = **1.49%** (objetivo cumplido)
|
||
|
||
---
|
||
|
||
## Resultados Principales
|
||
|
||
| Modelo | CER | Precisión Caracteres | WER | Precisión Palabras |
|
||
|--------|-----|---------------------|-----|-------------------|
|
||
| PaddleOCR (Baseline) | 7.78% | 92.22% | 14.94% | 85.06% |
|
||
| **PaddleOCR-HyperAdjust** | **1.49%** | **98.51%** | **7.62%** | **92.38%** |
|
||
|
||
**Mejora obtenida:** Reducción del CER en un **80.9%**
|
||
|
||
### Configuración Óptima Encontrada
|
||
|
||
```python
|
||
config_optimizada = {
|
||
"textline_orientation": True, # CRÍTICO - reduce CER ~70%
|
||
"use_doc_orientation_classify": False,
|
||
"use_doc_unwarping": False,
|
||
"text_det_thresh": 0.4690, # Correlación -0.52 con CER
|
||
"text_det_box_thresh": 0.5412,
|
||
"text_det_unclip_ratio": 0.0,
|
||
"text_rec_score_thresh": 0.6350,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Metodología
|
||
|
||
### Pipeline de Trabajo
|
||
|
||
```
|
||
PDF (académico UNIR)
|
||
└─► Conversión a imagen (PyMuPDF, 300 DPI)
|
||
└─► Extracción de ground truth
|
||
└─► OCR con PaddleOCR (PP-OCRv5)
|
||
└─► Evaluación (CER, WER con jiwer)
|
||
└─► Optimización (Ray Tune + Optuna)
|
||
```
|
||
|
||
### Experimento de Optimización
|
||
|
||
| Parámetro | Valor |
|
||
|-----------|-------|
|
||
| Número de trials | 64 |
|
||
| Algoritmo de búsqueda | OptunaSearch (TPE) |
|
||
| Métrica objetivo | CER (minimizar) |
|
||
| Trials concurrentes | 2 |
|
||
| Tiempo total | ~6 horas (CPU) |
|
||
|
||
---
|
||
|
||
## Estructura del Repositorio
|
||
|
||
```
|
||
MastersThesis/
|
||
├── docs/ # Capítulos del TFM en Markdown (estructura UNIR)
|
||
│ ├── 00_resumen.md # Resumen + Abstract + Keywords
|
||
│ ├── 01_introduccion.md # Cap. 1: Introducción (1.1-1.3)
|
||
│ ├── 02_contexto_estado_arte.md # Cap. 2: Contexto y estado del arte (2.1-2.3)
|
||
│ ├── 03_objetivos_metodologia.md # Cap. 3: Objetivos y metodología (3.1-3.4)
|
||
│ ├── 04_desarrollo_especifico.md # Cap. 4: Desarrollo específico (4.1-4.3)
|
||
│ ├── 05_conclusiones_trabajo_futuro.md # Cap. 5: Conclusiones (5.1-5.2)
|
||
│ ├── 06_referencias_bibliograficas.md # Referencias bibliográficas (APA)
|
||
│ └── 07_anexo_a.md # Anexo A: Código fuente y datos
|
||
├── thesis_output/ # Documento final generado
|
||
│ ├── plantilla_individual.htm # TFM completo (abrir en Word)
|
||
│ └── figures/ # Figuras generadas desde Mermaid
|
||
│ ├── figura_1.png ... figura_7.png
|
||
│ └── figures_manifest.json
|
||
├── src/
|
||
│ ├── paddle_ocr_fine_tune_unir_raytune.ipynb # Experimento principal
|
||
│ ├── paddle_ocr_tuning.py # Script de evaluación CLI
|
||
│ ├── dataset_manager.py # Clase ImageTextDataset
|
||
│ ├── prepare_dataset.ipynb # Preparación del dataset
|
||
│ └── raytune_paddle_subproc_results_*.csv # Resultados de 64 trials
|
||
├── results/ # Resultados de benchmarks
|
||
├── instructions/ # Plantilla e instrucciones UNIR
|
||
│ ├── instrucciones.pdf
|
||
│ ├── plantilla_individual.pdf
|
||
│ └── plantilla_individual.htm
|
||
├── apply_content.py # Genera documento TFM desde docs/ + plantilla
|
||
├── generate_mermaid_figures.py # Convierte diagramas Mermaid a PNG
|
||
├── ocr_benchmark_notebook.ipynb # Benchmark comparativo inicial
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Hallazgos Clave
|
||
|
||
1. **`textline_orientation=True` es crítico**: Reduce el CER en un 69.7%. Para documentos con layouts mixtos (tablas, encabezados), la clasificación de orientación de línea es esencial.
|
||
|
||
2. **Umbral `text_det_thresh` importante**: Correlación -0.52 con CER. Valores óptimos entre 0.4-0.5. Valores < 0.1 causan fallos catastróficos (CER >40%).
|
||
|
||
3. **Componentes innecesarios para PDFs digitales**: `use_doc_orientation_classify` y `use_doc_unwarping` no mejoran el rendimiento en documentos académicos digitales.
|
||
|
||
---
|
||
|
||
## Requisitos
|
||
|
||
| Componente | Versión |
|
||
|------------|---------|
|
||
| Python | 3.11.9 |
|
||
| PaddlePaddle | 3.2.2 |
|
||
| PaddleOCR | 3.3.2 |
|
||
| Ray | 2.52.1 |
|
||
| Optuna | 4.6.0 |
|
||
| jiwer | (para métricas CER/WER) |
|
||
| PyMuPDF | (para conversión PDF) |
|
||
|
||
---
|
||
|
||
## Uso
|
||
|
||
### Preparar dataset
|
||
```bash
|
||
# Ejecutar prepare_dataset.ipynb para convertir PDF a imágenes y extraer ground truth
|
||
jupyter notebook src/prepare_dataset.ipynb
|
||
```
|
||
|
||
### Ejecutar optimización
|
||
```bash
|
||
# Ejecutar el notebook principal de Ray Tune
|
||
jupyter notebook src/paddle_ocr_fine_tune_unir_raytune.ipynb
|
||
```
|
||
|
||
### Evaluación individual
|
||
```bash
|
||
python src/paddle_ocr_tuning.py \
|
||
--pdf-folder ./dataset \
|
||
--textline-orientation True \
|
||
--text-det-thresh 0.469 \
|
||
--text-det-box-thresh 0.541 \
|
||
--text-rec-score-thresh 0.635
|
||
```
|
||
|
||
---
|
||
|
||
## Fuentes de Datos
|
||
|
||
- **Dataset**: Instrucciones para la elaboración del TFE (UNIR), 24 páginas
|
||
- **Resultados benchmark**: `results/ai_ocr_benchmark_finetune_results_20251206_113206.csv`
|
||
- **Resultados Ray Tune**: `src/raytune_paddle_subproc_results_20251207_192320.csv`
|
||
|
||
---
|
||
|
||
## Generación del Documento TFM
|
||
|
||
### Generar documento Word desde Markdown
|
||
|
||
```bash
|
||
# 1. Generar figuras desde diagramas Mermaid
|
||
python3 generate_mermaid_figures.py
|
||
|
||
# 2. Aplicar contenido de docs/ a la plantilla UNIR
|
||
python3 apply_content.py
|
||
|
||
# 3. Abrir en Word y actualizar índices
|
||
# - Abrir thesis_output/plantilla_individual.htm en Microsoft Word
|
||
# - Presionar Ctrl+A luego F9 para actualizar todos los índices
|
||
# - Guardar como .docx
|
||
```
|
||
|
||
**Contenido generado automáticamente:**
|
||
- 30 tablas con formato `Piedefoto-tabla` (Tabla X. *Título* + Fuente)
|
||
- 7 figuras desde Mermaid con formato `Piedefoto-tabla` (Figura X. *Título* + Fuente)
|
||
- 25 referencias en formato APA con sangría francesa
|
||
- Resumen y Abstract con palabras clave reales
|
||
- Eliminación automática de textos de instrucción de la plantilla
|
||
|
||
---
|
||
|
||
## Trabajo Pendiente para Completar el TFM
|
||
|
||
### Contexto: Limitaciones de Hardware
|
||
|
||
Este trabajo adoptó la estrategia de **optimización de hiperparámetros** en lugar de **fine-tuning** debido a:
|
||
- **Sin GPU dedicada**: Ejecución exclusivamente en CPU
|
||
- **Tiempo de inferencia elevado**: ~69 segundos/página en CPU
|
||
- **Fine-tuning inviable**: Entrenar modelos de deep learning sin GPU requeriría tiempos prohibitivos
|
||
|
||
La optimización de hiperparámetros demostró ser una **alternativa efectiva** al fine-tuning, logrando una reducción del 80.9% en el CER sin reentrenar el modelo.
|
||
|
||
### Tareas Completadas
|
||
|
||
- [x] **Estructura docs/ según plantilla UNIR**: Todos los capítulos siguen numeración exacta (1.1, 1.2, etc.)
|
||
- [x] **Añadir diagramas Mermaid**: 7 diagramas añadidos (pipeline OCR, arquitectura Ray Tune, gráficos de comparación)
|
||
- [x] **Generar documento TFM unificado**: Script `apply_content.py` genera documento completo desde docs/
|
||
- [x] **Convertir Mermaid a PNG**: Script `generate_mermaid_figures.py` genera figuras automáticamente
|
||
|
||
### Tareas Pendientes
|
||
|
||
#### 1. Validación del Enfoque (Prioridad Alta)
|
||
- [ ] **Validación cruzada en otros documentos**: Evaluar la configuración óptima en otros tipos de documentos en español (facturas, formularios, contratos) para verificar generalización
|
||
- [ ] **Ampliar el dataset**: El dataset actual tiene solo 24 páginas. Construir un corpus más amplio y diverso (mínimo 100 páginas)
|
||
- [ ] **Validación del ground truth**: Revisar manualmente el texto de referencia extraído automáticamente para asegurar su exactitud
|
||
|
||
#### 2. Experimentación Adicional (Prioridad Media)
|
||
- [ ] **Explorar `text_det_unclip_ratio`**: Este parámetro quedó fijado en 0.0. Incluirlo en el espacio de búsqueda podría mejorar resultados
|
||
- [ ] **Comparativa con fine-tuning** (si se obtiene acceso a GPU): Cuantificar la brecha de rendimiento entre optimización de hiperparámetros y fine-tuning real
|
||
- [ ] **Evaluación con GPU**: Medir tiempos de inferencia con aceleración GPU para escenarios de producción
|
||
|
||
#### 3. Documentación y Presentación (Prioridad Alta)
|
||
- [ ] **Crear presentación**: Preparar slides para la defensa del TFM
|
||
- [ ] **Revisión final del documento**: Verificar formato, índices y contenido en Word
|
||
|
||
#### 4. Extensiones Futuras (Opcional)
|
||
- [ ] **Herramienta de configuración automática**: Desarrollar una herramienta que determine automáticamente la configuración óptima para un nuevo tipo de documento
|
||
- [ ] **Benchmark público para español**: Publicar un benchmark de OCR para documentos en español que facilite comparación de soluciones
|
||
- [ ] **Optimización multi-objetivo**: Considerar CER, WER y tiempo de inferencia simultáneamente
|
||
|
||
### Recomendación de Próximos Pasos
|
||
|
||
1. **Inmediato**: Abrir documento generado en Word, actualizar índices (Ctrl+A, F9), guardar como .docx
|
||
2. **Corto plazo**: Validar en 2-3 tipos de documentos adicionales para demostrar generalización
|
||
3. **Para la defensa**: Crear presentación con visualizaciones de resultados
|
||
|
||
---
|
||
|
||
## Licencia
|
||
|
||
Este proyecto es parte de un Trabajo Fin de Máster académico.
|
||
|
||
---
|
||
|
||
## Referencias
|
||
|
||
- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
|
||
- [Ray Tune](https://docs.ray.io/en/latest/tune/index.html)
|
||
- [Optuna](https://optuna.org/)
|
||
- [jiwer](https://github.com/jitsi/jiwer)
|