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

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

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.
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%).
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

# Ejecutar prepare_dataset.ipynb para convertir PDF a imágenes y extraer ground truth
jupyter notebook src/prepare_dataset.ipynb

Ejecutar optimización

# Ejecutar el notebook principal de Ray Tune
jupyter notebook src/paddle_ocr_fine_tune_unir_raytune.ipynb

Evaluación individual

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 Ray Tune (PRINCIPAL): src/raytune_paddle_subproc_results_20251207_192320.csv - 64 trials de optimización con todas las métricas y configuraciones

Generación del Documento TFM

Prerrequisitos

# Instalar dependencias de Python
pip install beautifulsoup4

# Instalar mermaid-cli para generación de figuras
npm install @mermaid-js/mermaid-cli

Flujo de Generación del Documento

El documento TFM se genera en 3 pasos que deben ejecutarse en orden:

┌─────────────────────────────────────────────────────────────────────┐
│  PASO 1: generate_mermaid_figures.py                                │
│  ────────────────────────────────────────────────────────────────── │
│  • Lee diagramas Mermaid de docs/*.md                               │
│  • Genera thesis_output/figures/figura_*.png                        │
│  • Crea figures_manifest.json con títulos                           │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│  PASO 2: apply_content.py                                           │
│  ────────────────────────────────────────────────────────────────── │
│  • Lee plantilla desde instructions/plantilla_individual.htm        │
│  • Inserta contenido de docs/*.md en cada capítulo                  │
│  • Genera tablas con formato APA y figuras con referencias          │
│  • Guarda en thesis_output/plantilla_individual.htm                 │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│  PASO 3: Abrir en Microsoft Word                                    │
│  ────────────────────────────────────────────────────────────────── │
│  • Abrir thesis_output/plantilla_individual.htm                     │
│  • Ctrl+A → F9 para actualizar índices (contenidos/figuras/tablas)  │
│  • Guardar como TFM_Sergio_Jimenez.docx                             │
└─────────────────────────────────────────────────────────────────────┘

Comandos de Generación

# Desde el directorio raíz del proyecto:

# PASO 1: Generar figuras PNG desde diagramas Mermaid
python3 generate_mermaid_figures.py
# Output: thesis_output/figures/figura_1.png ... figura_8.png

# PASO 2: Aplicar contenido de docs/ a la plantilla UNIR
python3 apply_content.py
# Output: thesis_output/plantilla_individual.htm

# PASO 3: Abrir en Word y finalizar documento
# - Abrir thesis_output/plantilla_individual.htm en Microsoft Word
# - Ctrl+A → F9 para actualizar todos los índices
# - IMPORTANTE: Ajustar manualmente el tamaño de las imágenes para legibilidad
#   (seleccionar imagen → clic derecho → Tamaño y posición → ajustar al ancho de página)
# - Guardar como .docx

Notas Importantes para Edición en Word

Ajuste de imágenes: Las figuras Mermaid pueden requerir ajuste manual de tamaño para ser legibles. Seleccionar cada imagen y ajustar al ancho de texto (~16cm).
Actualización de índices: Después de cualquier cambio, usar Ctrl+A → F9 para regenerar índices.
Formato de código: Los bloques de código usan Consolas 9pt. Verificar que no se corten líneas largas.

Archivos de Entrada y Salida

Script	Entrada	Salida
`generate_mermaid_figures.py`	`docs/*.md` (bloques `mermaid`)	`thesis_output/figures/figura_*.png`, `figures_manifest.json`
`apply_content.py`	`instructions/plantilla_individual.htm`, `docs/.md`, `thesis_output/figures/.png`	`thesis_output/plantilla_individual.htm`

Contenido Generado Automáticamente

30 tablas con formato APA (Tabla X. Título + Fuente: ...)
8 figuras desde Mermaid (Figura X. Título + Fuente: Elaboración propia)
25 referencias en formato APA con sangría francesa
Resumen/Abstract con palabras clave
Índices actualizables (contenidos, figuras, tablas)
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

Estructura docs/ según plantilla UNIR: Todos los capítulos siguen numeración exacta (1.1, 1.2, etc.)
Añadir diagramas Mermaid: 7 diagramas añadidos (pipeline OCR, arquitectura Ray Tune, gráficos de comparación)
Generar documento TFM unificado: Script apply_content.py genera documento completo desde docs/
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

Inmediato: Abrir documento generado en Word, actualizar índices (Ctrl+A, F9), guardar como .docx
Corto plazo: Validar en 2-3 tipos de documentos adicionales para demostrar generalización
Para la defensa: Crear presentación con visualizaciones de resultados

Licencia

Este proyecto es parte de un Trabajo Fin de Máster académico.

README.md Unescape Escape

Optimización de Hiperparámetros OCR con Ray Tune para Documentos Académicos en Español