diff --git a/.claude/commands/documentation-review.md b/.claude/commands/documentation-review.md new file mode 100644 index 0000000..65be2b0 --- /dev/null +++ b/.claude/commands/documentation-review.md @@ -0,0 +1,65 @@ +Review and validate the documentation for this Master's Thesis project. + +## Instructions + +1. **Read metrics source files first** to get the correct values: + - `docs/metrics/metrics_paddle.md` - PaddleOCR results + - `docs/metrics/metrics_doctr.md` - DocTR results + - `docs/metrics/metrics_easyocr.md` - EasyOCR results + - `docs/metrics/metrics.md` - Comparative summary + - `src/results/*.csv` - Raw data from 64 trials per service + +2. **Review UNIR guidelines** for formatting and structure rules: + - `instructions/instrucciones.pdf` - TFE writing instructions + - `instructions/plantilla_individual.pdf` - Official template with required format + +3. **Validate each documentation file** checking: + +### Data Accuracy +- All CER/WER values must match those in `docs/metrics/*.md` +- Verify: baseline, optimized, best trial, percentage improvement +- Verify: GPU vs CPU acceleration factor +- Verify: dataset size (pages) + +### UNIR Formatting +- Tables: `**Tabla N.** *Title in italics.*` followed by table, then `*Fuente: ...*` +- Figures: `**Figura N.** *Title in italics.*` +- Sequential numbering (no duplicates, no gaps) +- APA citation format for references + +### Mermaid Diagrams +- **All diagrams must be in Mermaid format** (no external images for flowcharts/charts) +- All Mermaid diagrams must use the UNIR color theme +- Required YAML frontmatter config (Mermaid v11+): + ```mermaid + --- + title: "Diagram Title" + config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" + --- + flowchart LR + A[Node] --> B[Node] + ``` +- Colors: `#0098CD` (UNIR blue for borders/lines), `#E6F4F9` (light blue background) +- Verify theme is applied to all diagrams in `docs/*.md` + +### Files to Review +- `docs/00_resumen.md` - Resumen/Abstract +- `docs/03_objetivos_metodologia.md` - Objectives +- `docs/04_desarrollo_especifico.md` - Main results (most critical) +- `docs/05_conclusiones_trabajo_futuro.md` - Conclusions +- `docs/07_anexo_a.md` - Technical annex +- `README.md` - Project overview + +4. **Report findings** with: + - List of incorrect values found (with file:line references) + - Formatting issues detected + - Specific corrections needed + - Overall documentation health assessment + +5. **Language**: All docs/* files must be in Spanish. README.md and CLAUDE.md can be in English. diff --git a/.claude/commands/word-generation.md b/.claude/commands/word-generation.md new file mode 100644 index 0000000..10bdfa9 --- /dev/null +++ b/.claude/commands/word-generation.md @@ -0,0 +1,65 @@ +Generate the Word document for this Master's Thesis project. + +## Instructions + +Execute the TFM document generation pipeline in order: + +### Step 0: Clean Up Previous Output + +Remove the entire thesis_output folder to ensure a fresh build: +```bash +rm -rf thesis_output && mkdir -p thesis_output/figures +``` + +### Step 1: Generate Figures from Mermaid Diagrams + +Run the figure generation script using the virtual environment: +```bash +source .venv/bin/activate && python3 generate_mermaid_figures.py +``` + +**Input:** Mermaid code blocks from `docs/*.md` +**Output:** `thesis_output/figures/figura_*.png` and `figures_manifest.json` + +### Step 2: Apply Content to UNIR Template + +Run the content application script using the virtual environment: +```bash +source .venv/bin/activate && python3 apply_content.py +``` + +**Input:** +- `instructions/plantilla_individual.htm` (UNIR template) +- `docs/*.md` (chapter content) +- `thesis_output/figures/*.png` (generated figures) + +**Output:** `thesis_output/plantilla_individual.htm` + +### Step 3: Report Results + +After successful execution, provide: +1. Number of figures generated +2. Number of tables formatted +3. Path to output file +4. Instructions for Word finalization: + - Open `thesis_output/plantilla_individual.htm` in Microsoft Word + - Press Ctrl+A then F9 to update all indices (contents, figures, tables) + - Adjust image sizes if needed (select image → right-click → Size and Position) + - Save as `.docx` + +### Prerequisites + +If scripts fail, check that dependencies are installed: +```bash +# Python dependencies (in .venv) +source .venv/bin/activate && pip install beautifulsoup4 + +# Mermaid CLI for figure generation +npm install @mermaid-js/mermaid-cli +``` + +### Error Handling + +- If `generate_mermaid_figures.py` fails: Check mmdc (mermaid-cli) is installed +- If `apply_content.py` fails: Check beautifulsoup4 is installed +- Report any errors with the specific step that failed diff --git a/.gitignore b/.gitignore index c2762ec..62025a2 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,8 @@ __pycache__/ dataset results .DS_Store -.claude +.claude/* +!.claude/commands/ node_modules src/paddle_ocr/wheels src/*.log diff --git a/README.md b/README.md index 0d4c4f7..7f1e74d 100644 --- a/README.md +++ b/README.md @@ -10,36 +10,39 @@ ## 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. +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. -**Resultado alcanzado:** CER = **1.49%** (objetivo cumplido) +**Resultado alcanzado:** +- **Mejor trial (5 páginas):** CER = **0.79%** ✓ objetivo cumplido +- **Dataset completo (45 páginas):** CER = **7.72%** (mejora del 12.8% respecto a baseline) --- ## Resultados Principales -**Tabla.** *Comparación de métricas OCR entre configuración baseline y optimizada.* +**Tabla.** *Comparación de métricas OCR entre configuración baseline y optimizada (GPU).* | 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%** | +| PaddleOCR (Baseline) | 8.85% | 91.15% | 13.05% | 86.95% | +| **PaddleOCR-HyperAdjust (dataset)** | **7.72%** | **92.28%** | **11.40%** | **88.60%** | +| **PaddleOCR-HyperAdjust (mejor trial)** | **0.79%** | **99.21%** | **7.78%** | **92.22%** | -*Fuente: Elaboración propia.* +*Fuente: [`src/results/raytune_paddle_results_20260119_122609.csv`](src/results/raytune_paddle_results_20260119_122609.csv)* -**Mejora obtenida:** Reducción del CER en un **80.9%** +**Mejora obtenida (dataset completo):** Reducción del CER en un **12.8%** -### Configuración Óptima Encontrada +### Configuración Óptima Encontrada (GPU) ```python config_optimizada = { - "textline_orientation": True, # CRÍTICO - reduce CER ~70% - "use_doc_orientation_classify": False, + "textline_orientation": True, # CRÍTICO para layouts complejos + "use_doc_orientation_classify": True, # Mejora orientación de documento "use_doc_unwarping": False, - "text_det_thresh": 0.4690, # Correlación -0.52 con CER - "text_det_box_thresh": 0.5412, + "text_det_thresh": 0.0462, # Correlación -0.52 con CER + "text_det_box_thresh": 0.4862, "text_det_unclip_ratio": 0.0, - "text_rec_score_thresh": 0.6350, + "text_rec_score_thresh": 0.5658, } ``` @@ -68,7 +71,7 @@ PDF (académico UNIR) | Algoritmo de búsqueda | OptunaSearch (TPE) | | Métrica objetivo | CER (minimizar) | | Trials concurrentes | 2 | -| Tiempo total | ~6 horas (CPU) | +| Tiempo total | ~1.5 horas (GPU RTX 3060) | *Fuente: Elaboración propia.* @@ -76,63 +79,95 @@ PDF (académico UNIR) ## Estructura del Repositorio +```mermaid +flowchart TB + subgraph root["MastersThesis/"] + direction TB + + subgraph docs["docs/ - Capítulos TFM"] + d0["00-07 chapters (.md)"] + subgraph metrics["metrics/"] + m1["metrics_paddle.md"] + m2["metrics_doctr.md"] + m3["metrics_easyocr.md"] + end + end + + subgraph src["src/ - Código fuente"] + subgraph paddle["paddle_ocr/"] + p1["paddle_ocr_tuning_rest.py"] + p2["Dockerfile.gpu/cpu"] + end + subgraph doctr["doctr_service/"] + dt1["doctr_tuning_rest.py"] + end + subgraph easy["easyocr_service/"] + e1["easyocr_tuning_rest.py"] + end + subgraph ray["raytune/"] + r1["raytune_ocr.py"] + r2["run_tuning.py"] + end + results["results/*.csv"] + dataset["dataset/"] + end + + subgraph thesis["thesis_output/"] + htm["plantilla_individual.htm"] + figs["figures/figura_1-11.png"] + end + + subgraph inst["instructions/"] + i1["instrucciones.pdf"] + i2["plantilla_individual.htm"] + end + + scripts["apply_content.py
generate_mermaid_figures.py"] + config["claude.md
README.md"] + end ``` -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 -``` + +**Descripción de directorios principales:** + +| Directorio | Contenido | +|------------|-----------| +| `docs/` | Capítulos del TFM en Markdown (estructura UNIR) | +| `docs/metrics/` | Métricas de rendimiento por servicio OCR | +| `src/paddle_ocr/` | Servicio PaddleOCR dockerizado | +| `src/doctr_service/` | Servicio DocTR dockerizado | +| `src/easyocr_service/` | Servicio EasyOCR dockerizado | +| `src/raytune/` | Scripts de optimización Ray Tune | +| `src/results/` | CSVs con resultados de 64 trials por servicio | +| `thesis_output/` | Documento TFM generado + figuras PNG | +| `instructions/` | Plantilla e instrucciones UNIR oficiales | --- ## 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. +1. **`textline_orientation=True` es crítico**: 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%). +2. **`use_doc_orientation_classify=True` mejora resultados**: En la configuración GPU, la clasificación de orientación del documento demostró impacto positivo. -3. **Componentes innecesarios para PDFs digitales**: `use_doc_orientation_classify` y `use_doc_unwarping` no mejoran el rendimiento en documentos académicos digitales. +3. **Umbral `text_det_thresh` importante**: Correlación -0.52 con CER. En GPU, el valor óptimo fue 0.0462. Valores < 0.01 causan fallos catastróficos (CER >40%). + +4. **`use_doc_unwarping` innecesario para PDFs digitales**: La corrección de deformación no mejora el rendimiento en documentos académicos digitales. --- ## Rendimiento GPU -Se realizó una validación adicional con aceleración GPU para evaluar la viabilidad práctica del enfoque en escenarios de producción. +Los experimentos principales se ejecutaron con aceleración GPU para maximizar la eficiencia de la exploración de hiperparámetros. **Tabla.** *Comparación de rendimiento CPU vs GPU.* | Métrica | CPU | GPU (RTX 3060) | Aceleración | |---------|-----|----------------|-------------| -| Tiempo/Página | 69.4s | 0.55s | **126x** | -| Dataset completo (45 páginas) | ~52 min | ~25 seg | **126x** | +| Tiempo/Página | 69.4s | 0.84s | **82x** | +| Dataset completo (45 páginas) | ~52 min | ~38 seg | **82x** | +| 64 trials completos | ~6.4 horas | ~1.5 horas | **4.3x** | -*Fuente: Elaboración propia.* +*Fuente: [`src/raytune_paddle_subproc_results_20251207_192320.csv`](src/raytune_paddle_subproc_results_20251207_192320.csv) (CPU) y [`src/results/raytune_paddle_results_20260119_122609.csv`](src/results/raytune_paddle_results_20260119_122609.csv) (GPU).* ### Recomendación de Modelos @@ -145,7 +180,7 @@ Se realizó una validación adicional con aceleración GPU para evaluar la viabi *Fuente: Elaboración propia.* -**Conclusión:** Para hardware con VRAM limitada (≤6 GB), los modelos Mobile ofrecen el mejor balance entre precisión y recursos. La aceleración GPU hace viable el procesamiento en tiempo real. +**Conclusión:** Para hardware con VRAM limitada (≤6 GB), los modelos Mobile ofrecen el mejor balance entre precisión y recursos. La aceleración GPU (82×) hace viable la exploración exhaustiva de hiperparámetros y el procesamiento en tiempo real. --- @@ -196,101 +231,8 @@ python src/paddle_ocr_tuning.py \ ## Fuentes de Datos - **Dataset**: 2 documentos UNIR (45 páginas total): Instrucciones TFE (24 pág.) + Plantilla TFE (21 pág.) -- **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 - -```bash -# 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 - -```bash -# 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 - -1. **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). - -2. **Actualización de índices**: Después de cualquier cambio, usar Ctrl+A → F9 para regenerar índices. - -3. **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 - -**Tabla.** *Relación de scripts de generación con sus 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` | - -*Fuente: Elaboración propia.* - -### Contenido Generado Automáticamente - -- **53 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 +- **Resultados GPU (PRINCIPAL)**: [`src/results/raytune_paddle_results_20260119_122609.csv`](src/results/raytune_paddle_results_20260119_122609.csv) - 64 trials de optimización con GPU +- **Resultados CPU (referencia de tiempo)**: [`src/raytune_paddle_subproc_results_20251207_192320.csv`](src/raytune_paddle_subproc_results_20251207_192320.csv) - Para comparación de rendimiento CPU vs GPU --- @@ -301,10 +243,10 @@ python3 apply_content.py Este trabajo adoptó la estrategia de **optimización de hiperparámetros** en lugar de **fine-tuning** debido a que el fine-tuning de modelos OCR requiere datasets etiquetados extensos y tiempos de entrenamiento prohibitivos. **Hardware utilizado:** -- **Optimización (CPU)**: Los 64 trials de Ray Tune se ejecutaron en CPU (~69s/página) -- **Validación (GPU)**: Se validó con RTX 3060 logrando 126x de aceleración (0.55s/página) +- **Optimización (GPU)**: Los 64 trials de Ray Tune se ejecutaron con GPU RTX 3060 (~0.84s/página, ~1.5 horas total) +- **Referencia CPU**: Se midió el tiempo en CPU para comparación (~69s/página) -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. +La optimización de hiperparámetros demostró ser una **alternativa viable** al fine-tuning. El mejor trial alcanzó un CER de 0.79%, mientras que la validación sobre el dataset completo logró una mejora del 12.8%. ### Tareas Pendientes @@ -321,9 +263,10 @@ La optimización de hiperparámetros demostró ser una **alternativa efectiva** #### Completadas - [x] **Estructura docs/ según plantilla UNIR** -- [x] **Diagramas Mermaid**: 8 figuras generadas +- [x] **Diagramas Mermaid**: 8+ figuras generadas - [x] **Documento TFM unificado**: Script `apply_content.py` -- [x] **Evaluación con GPU**: RTX 3060 - 126x más rápido (0.55s/página) +- [x] **Optimización con GPU**: RTX 3060 - 82× más rápido (0.84s/página) +- [x] **Infraestructura Docker**: 5 imágenes (PaddleOCR, EasyOCR, DocTR, RayTune) ### Dataset diff --git a/claude.md b/claude.md index 4ab0fab..316339b 100644 --- a/claude.md +++ b/claude.md @@ -12,39 +12,41 @@ This is a **Master's Thesis (TFM)** for UNIR's Master in Artificial Intelligence ### Why Hyperparameter Optimization Instead of Fine-tuning -Due to **hardware limitations** (no dedicated GPU, CPU-only execution), the project pivoted from fine-tuning to hyperparameter optimization: -- Fine-tuning deep learning models without GPU is prohibitively slow -- Inference time is ~69 seconds/page on CPU -- Hyperparameter optimization proved to be an effective alternative, achieving 80.9% CER reduction +The project chose **hyperparameter optimization** over fine-tuning because: +- Fine-tuning requires extensive labeled datasets specific to the domain +- Hyperparameter tuning can improve pretrained models without retraining +- GPU acceleration (RTX 3060) enables efficient exploration of hyperparameter space -### Main Results +### Main Results (GPU - Jan 2026) | Model | CER | Character Accuracy | |-------|-----|-------------------| -| PaddleOCR Baseline | 7.78% | 92.22% | -| PaddleOCR-HyperAdjust | **1.49%** | **98.51%** | +| PaddleOCR Baseline | 8.85% | 91.15% | +| PaddleOCR-HyperAdjust (full dataset) | **7.72%** | **92.28%** | +| PaddleOCR-HyperAdjust (best trial) | **0.79%** | **99.21%** | -**Goal achieved:** CER < 2% (target was < 2%, result is 1.49%) +**Goal status:** CER < 2% achieved in best trial (0.79%). Full dataset shows 12.8% improvement. -### Optimal Configuration Found +### Optimal Configuration Found (GPU) ```python config_optimizada = { - "textline_orientation": True, # CRITICAL - reduces CER ~70% - "use_doc_orientation_classify": False, + "textline_orientation": True, # CRITICAL for complex layouts + "use_doc_orientation_classify": True, # Improves document orientation "use_doc_unwarping": False, - "text_det_thresh": 0.4690, - "text_det_box_thresh": 0.5412, + "text_det_thresh": 0.0462, # -0.52 correlation with CER + "text_det_box_thresh": 0.4862, "text_det_unclip_ratio": 0.0, - "text_rec_score_thresh": 0.6350, + "text_rec_score_thresh": 0.5658, } ``` ### Key Findings -1. `textline_orientation=True` is the most impactful parameter (reduces CER by 69.7%) -2. `text_det_thresh` has -0.52 correlation with CER; values < 0.1 cause catastrophic failures -3. Document correction modules (`use_doc_orientation_classify`, `use_doc_unwarping`) are unnecessary for digital PDFs +1. `textline_orientation=True` is critical for documents with mixed layouts +2. `use_doc_orientation_classify=True` improves document orientation detection in GPU config +3. `text_det_thresh` has -0.52 correlation with CER; values < 0.01 cause catastrophic failures +4. `use_doc_unwarping=False` is optimal for digital PDFs (unnecessary processing) ## Repository Structure @@ -99,13 +101,18 @@ The template (`plantilla_individual.pdf`) requires **5 chapters**. The docs/ fil ## Important Data Files -### Results CSV Files -- `src/raytune_paddle_subproc_results_20251207_192320.csv` - 64 Ray Tune trials with configs and metrics (PRIMARY DATA SOURCE) +### Results CSV Files (GPU - PRIMARY) +- `src/results/raytune_paddle_results_20260119_122609.csv` - 64 Ray Tune trials PaddleOCR GPU (PRIMARY) +- `src/results/raytune_easyocr_results_20260119_120204.csv` - 64 Ray Tune trials EasyOCR GPU +- `src/results/raytune_doctr_results_20260119_121445.csv` - 64 Ray Tune trials DocTR GPU -### Key Notebooks -- `src/paddle_ocr_fine_tune_unir_raytune.ipynb` - Main Ray Tune experiment -- `src/prepare_dataset.ipynb` - PDF to image/text conversion -- `ocr_benchmark_notebook.ipynb` - EasyOCR vs PaddleOCR vs DocTR comparison +### Results CSV Files (CPU - time reference only) +- `src/raytune_paddle_subproc_results_20251207_192320.csv` - CPU execution for time comparison (69.4s/page vs 0.84s/page GPU) + +### Key Scripts +- `src/run_tuning.py` - Main Ray Tune optimization script +- `src/raytune/raytune_ocr.py` - Ray Tune utilities and search spaces +- `src/paddle_ocr/paddle_ocr_tuning_rest.py` - PaddleOCR REST API ## Technical Stack @@ -128,13 +135,13 @@ The template (`plantilla_individual.pdf`) requires **5 chapters**. The docs/ fil ### Priority Tasks 1. **Validate on other document types** - Test optimal config on invoices, forms, contracts -2. **Expand dataset** - Current dataset has only 24 pages +2. **Use larger tuning subset** - Current 5 pages caused overfitting; recommend 15-20 pages 3. **Create presentation slides** - For thesis defense 4. **Final document review** - Open in Word, update indices (Ctrl+A, F9), verify formatting ### Optional Extensions - Explore `text_det_unclip_ratio` parameter (was fixed at 0.0) -- Compare with actual fine-tuning (if GPU access obtained) +- Compare with actual fine-tuning - Multi-objective optimization (CER + WER + inference time) ## Thesis Document Generation diff --git a/docs/00_resumen.md b/docs/00_resumen.md index 9ba0f09..de1ce36 100644 --- a/docs/00_resumen.md +++ b/docs/00_resumen.md @@ -1,12 +1,12 @@ # Resumen -El presente Trabajo Fin de Máster aborda la optimización de sistemas de Reconocimiento Óptico de Caracteres (OCR) basados en inteligencia artificial para documentos en español, específicamente en un entorno con recursos computacionales limitados donde el fine-tuning de modelos no es viable. El objetivo principal es identificar la configuración óptima de hiperparámetros que maximice la precisión del reconocimiento de texto sin requerir entrenamiento adicional de los modelos. +El presente Trabajo Fin de Máster aborda la optimización de sistemas de Reconocimiento Óptico de Caracteres (OCR) basados en inteligencia artificial para documentos en español. El objetivo principal es identificar la configuración óptima de hiperparámetros que maximice la precisión del reconocimiento de texto sin requerir fine-tuning de los modelos base. -Se realizó un estudio comparativo de tres soluciones OCR de código abierto: EasyOCR, PaddleOCR (PP-OCRv5) y DocTR, evaluando su rendimiento mediante las métricas estándar CER (Character Error Rate) y WER (Word Error Rate) sobre un corpus de documentos académicos en español. Tras identificar PaddleOCR como la solución más prometedora, se procedió a una optimización sistemática de hiperparámetros utilizando Ray Tune con el algoritmo de búsqueda Optuna, ejecutando 64 configuraciones diferentes. +Se realizó un estudio comparativo de tres soluciones OCR de código abierto: EasyOCR, PaddleOCR (PP-OCRv5) y DocTR, evaluando su rendimiento mediante las métricas estándar CER (Character Error Rate) y WER (Word Error Rate) sobre un corpus de 45 páginas de documentos académicos en español. Tras identificar PaddleOCR como la solución más prometedora, se procedió a una optimización sistemática de hiperparámetros utilizando Ray Tune con el algoritmo de búsqueda Optuna, ejecutando 64 configuraciones diferentes con aceleración GPU (NVIDIA RTX 3060). -Los resultados demuestran que la optimización de hiperparámetros logró una mejora significativa del rendimiento: el CER se redujo de 7.78% a 1.49% (mejora del 80.9% en reducción de errores), alcanzando una precisión de caracteres del 98.51%. El hallazgo más relevante fue que el parámetro `textline_orientation` (clasificación de orientación de línea de texto) tiene un impacto crítico, reduciendo el CER en un 69.7% cuando está habilitado. Adicionalmente, se identificó que el umbral de detección de píxeles (`text_det_thresh`) presenta una correlación negativa fuerte (-0.52) con el error, siendo el parámetro continuo más influyente. +Los resultados demuestran que la optimización de hiperparámetros logró mejoras significativas: el mejor trial individual alcanzó un CER de 0.79% (precisión del 99.21%), cumpliendo el objetivo de CER < 2%. Al validar la configuración optimizada sobre el dataset completo de 45 páginas, se obtuvo una mejora del 12.8% en CER (de 8.85% a 7.72%). El hallazgo más relevante fue que el parámetro `textline_orientation` (clasificación de orientación de línea de texto) tiene un impacto crítico en el rendimiento. Adicionalmente, se identificó que el umbral de detección (`text_det_thresh`) presenta una correlación negativa moderada (-0.52) con el error. -Este trabajo demuestra que es posible obtener mejoras sustanciales en sistemas OCR mediante optimización de hiperparámetros, ofreciendo una alternativa práctica al fine-tuning cuando los recursos computacionales son limitados. +Este trabajo demuestra que la optimización de hiperparámetros es una alternativa viable al fine-tuning, especialmente útil cuando se dispone de modelos preentrenados para el idioma objetivo. La infraestructura dockerizada desarrollada permite reproducir los experimentos y facilita la evaluación sistemática de configuraciones OCR. **Palabras clave:** OCR, Reconocimiento Óptico de Caracteres, PaddleOCR, Optimización de Hiperparámetros, Ray Tune, Procesamiento de Documentos, Inteligencia Artificial @@ -14,12 +14,12 @@ Este trabajo demuestra que es posible obtener mejoras sustanciales en sistemas O # Abstract -This Master's Thesis addresses the optimization of Artificial Intelligence-based Optical Character Recognition (OCR) systems for Spanish documents, specifically in a resource-constrained environment where model fine-tuning is not feasible. The main objective is to identify the optimal hyperparameter configuration that maximizes text recognition accuracy without requiring additional model training. +This Master's Thesis addresses the optimization of Artificial Intelligence-based Optical Character Recognition (OCR) systems for Spanish documents. The main objective is to identify the optimal hyperparameter configuration that maximizes text recognition accuracy without requiring fine-tuning of the base models. -A comparative study of three open-source OCR solutions was conducted: EasyOCR, PaddleOCR (PP-OCRv5), and DocTR, evaluating their performance using standard CER (Character Error Rate) and WER (Word Error Rate) metrics on a corpus of academic documents in Spanish. After identifying PaddleOCR as the most promising solution, systematic hyperparameter optimization was performed using Ray Tune with the Optuna search algorithm, executing 64 different configurations. +A comparative study of three open-source OCR solutions was conducted: EasyOCR, PaddleOCR (PP-OCRv5), and DocTR, evaluating their performance using standard CER (Character Error Rate) and WER (Word Error Rate) metrics on a corpus of 45 pages of academic documents in Spanish. After identifying PaddleOCR as the most promising solution, systematic hyperparameter optimization was performed using Ray Tune with the Optuna search algorithm, executing 64 different configurations with GPU acceleration (NVIDIA RTX 3060). -Results demonstrate that hyperparameter optimization achieved significant performance improvement: CER was reduced from 7.78% to 1.49% (80.9% error reduction), achieving 98.51% character accuracy. The most relevant finding was that the `textline_orientation` parameter (text line orientation classification) has a critical impact, reducing CER by 69.7% when enabled. Additionally, the pixel detection threshold (`text_det_thresh`) was found to have a strong negative correlation (-0.52) with error, being the most influential continuous parameter. +Results demonstrate that hyperparameter optimization achieved significant improvements: the best individual trial reached a CER of 0.79% (99.21% accuracy), meeting the CER < 2% objective. When validating the optimized configuration on the full 45-page dataset, a 12.8% CER improvement was obtained (from 8.85% to 7.72%). The most relevant finding was that the `textline_orientation` parameter (text line orientation classification) has a critical impact on performance. Additionally, the detection threshold (`text_det_thresh`) was found to have a moderate negative correlation (-0.52) with error. -This work demonstrates that substantial improvements in OCR systems can be obtained through hyperparameter optimization, offering a practical alternative to fine-tuning when computational resources are limited. +This work demonstrates that hyperparameter optimization is a viable alternative to fine-tuning, especially useful when pre-trained models for the target language are available. The dockerized infrastructure developed enables experiment reproducibility and facilitates systematic evaluation of OCR configurations. **Keywords:** OCR, Optical Character Recognition, PaddleOCR, Hyperparameter Optimization, Ray Tune, Document Processing, Artificial Intelligence diff --git a/docs/02_contexto_estado_arte.md b/docs/02_contexto_estado_arte.md index 048ec7b..457c120 100644 --- a/docs/02_contexto_estado_arte.md +++ b/docs/02_contexto_estado_arte.md @@ -61,7 +61,14 @@ Los sistemas OCR modernos siguen típicamente un pipeline de dos etapas principa ```mermaid --- -title: "Pipeline de un sistema OCR moderno" +title: Pipeline de un sistema OCR moderno +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- flowchart LR subgraph Input @@ -486,7 +493,14 @@ La combinación de Ray Tune con OptunaSearch permite: ```mermaid --- -title: "Ciclo de optimización con Ray Tune y Optuna" +title: Ciclo de optimización con Ray Tune y Optuna +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- flowchart LR A["Espacio de
búsqueda"] --> B["Ray Tune
Scheduler"] diff --git a/docs/03_objetivos_metodologia.md b/docs/03_objetivos_metodologia.md index d14bdd4..05a38c1 100644 --- a/docs/03_objetivos_metodologia.md +++ b/docs/03_objetivos_metodologia.md @@ -4,7 +4,7 @@ Este capítulo establece los objetivos del trabajo siguiendo la metodología SMA ## Objetivo general -> **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.** +> **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.** ### Justificación SMART del Objetivo General @@ -14,7 +14,7 @@ Este capítulo establece los objetivos del trabajo siguiendo la metodología SMA |----------|--------------| | **Específico (S)** | Se define claramente qué se quiere lograr: optimizar PaddleOCR mediante ajuste de hiperparámetros para documentos en español | | **Medible (M)** | Se establece una métrica cuantificable: CER < 2% | -| **Alcanzable (A)** | Es viable dado que: (1) PaddleOCR permite configuración de hiperparámetros, (2) Ray Tune posibilita búsqueda automatizada, (3) No se requiere GPU | +| **Alcanzable (A)** | Es viable dado que: (1) PaddleOCR permite configuración de hiperparámetros, (2) Ray Tune posibilita búsqueda automatizada, (3) Aceleración GPU disponible para experimentación eficiente | | **Relevante (R)** | El impacto es demostrable: mejora la extracción de texto en documentos académicos sin costes adicionales de infraestructura | | **Temporal (T)** | El plazo es un cuatrimestre, correspondiente al TFM | @@ -45,7 +45,14 @@ Este capítulo establece los objetivos del trabajo siguiendo la metodología SMA ```mermaid --- -title: "Fases de la metodología experimental" +title: Fases de la metodología experimental +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- flowchart LR A["Fase 1
Dataset"] --> B["Fase 2
Benchmark"] --> C["Fase 3
Espacio"] --> D["Fase 4
Optimización"] --> E["Fase 5
Validación"] @@ -82,7 +89,14 @@ El script `prepare_dataset.ipynb` implementa: ```mermaid --- -title: "Estructura del dataset de evaluación" +title: Estructura del dataset de evaluación +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- flowchart LR dataset["dataset/"] --> d0["0/"] @@ -185,7 +199,7 @@ El servicio OCR expone una API REST que retorna métricas en formato JSON: 1. **Baseline**: Ejecución con configuración por defecto de PaddleOCR 2. **Optimizado**: Ejecución con mejor configuración encontrada -3. **Comparación**: Evaluación sobre las 24 páginas del dataset completo +3. **Comparación**: Evaluación sobre las 45 páginas del dataset completo 4. **Métricas reportadas**: CER, WER, tiempo de procesamiento ### Entorno de Ejecución @@ -256,11 +270,11 @@ Para un proyecto de investigación con múltiples iteraciones de ajuste de hiper ### Limitaciones Metodológicas -1. **Tamaño del dataset**: El dataset contiene 24 páginas de un único tipo de documento. Resultados pueden no generalizar a otros formatos. +1. **Tamaño del dataset**: El dataset contiene 45 páginas de documentos académicos UNIR. Resultados pueden no generalizar a otros formatos. -2. **Ejecución en CPU**: Los tiempos de procesamiento (~70s/página) serían significativamente menores con GPU. +2. **Subconjunto de optimización**: El ajuste de hiperparámetros se realizó sobre 5 páginas (páginas 5-10), lo que contribuyó al sobreajuste observado en la validación del dataset completo. -3. **Ground truth imperfecto**: El texto de referencia extraído de PDF puede contener errores en documentos con layouts complejos. +3. **Texto de referencia imperfecto**: El texto de referencia extraído de PDF puede contener errores en documentos con diseños complejos. 4. **Parámetro fijo**: `text_det_unclip_ratio` quedó fijado en 0.0 durante todo el experimento por decisión de diseño inicial. @@ -268,7 +282,7 @@ Para un proyecto de investigación con múltiples iteraciones de ajuste de hiper Este capítulo ha establecido: -1. Un objetivo general SMART: alcanzar CER < 2% mediante optimización de hiperparámetros +1. Un objetivo general SMART: alcanzar CER < 2% mediante optimización de hiperparámetros (logrado en el mejor trial: 0.79%) 2. Cinco objetivos específicos medibles y alcanzables 3. Una metodología experimental en cinco fases claramente definidas 4. El espacio de búsqueda de hiperparámetros y la configuración de Ray Tune diff --git a/docs/04_desarrollo_especifico.md b/docs/04_desarrollo_especifico.md index 0f012ff..34d5a17 100644 --- a/docs/04_desarrollo_especifico.md +++ b/docs/04_desarrollo_especifico.md @@ -24,7 +24,7 @@ El reconocimiento óptico de caracteres (OCR) en documentos académicos en espa Se seleccionaron tres soluciones OCR de código abierto representativas del estado del arte: -**Tabla 10.** *Soluciones OCR evaluadas en el benchmark comparativo.* +**Tabla 11.** *Soluciones OCR evaluadas en el benchmark comparativo.* | Solución | Desarrollador | Versión | Justificación de selección | |----------|---------------|---------|----------------------------| @@ -55,7 +55,7 @@ Los criterios establecidos para evaluar las soluciones fueron: Se utilizó el documento "Instrucciones para la redacción y elaboración del TFE" del Máster Universitario en Inteligencia Artificial de UNIR, ubicado en la carpeta `instructions/`. -**Tabla 11.** *Características del dataset de evaluación inicial.* +**Tabla 12.** *Características del dataset de evaluación inicial.* | Característica | Valor | |----------------|-------| @@ -96,7 +96,7 @@ Se utilizó la biblioteca `jiwer` para calcular CER y WER de manera estandarizad Durante el benchmark inicial se evaluó PaddleOCR con configuración por defecto en un subconjunto del dataset. Los resultados preliminares mostraron variabilidad significativa entre páginas, con CER entre 1.54% y 6.40% dependiendo de la complejidad del layout. -**Tabla 12.** *Variabilidad del CER por tipo de contenido.* +**Tabla 13.** *Variabilidad del CER por tipo de contenido.* | Tipo de contenido | CER aproximado | Observaciones | |-------------------|----------------|---------------| @@ -121,7 +121,7 @@ Durante el benchmark inicial se evaluó PaddleOCR con configuración por defecto Los tres modelos evaluados representan diferentes paradigmas de OCR: -**Tabla 13.** *Comparativa de arquitecturas OCR evaluadas.* +**Tabla 14.** *Comparativa de arquitecturas OCR evaluadas.* | Modelo | Tipo | Componentes | Fortalezas Clave | |--------|------|-------------|------------------| @@ -162,7 +162,7 @@ Un análisis cualitativo de los errores producidos reveló patrones específicos La selección de PaddleOCR para la fase de optimización se basó en los siguientes criterios: -**Tabla 14.** *Evaluación de criterios de selección.* +**Tabla 15.** *Evaluación de criterios de selección.* | Criterio | EasyOCR | PaddleOCR | DocTR | |----------|---------|-----------|-------| @@ -244,7 +244,7 @@ La optimización de hiperparámetros representa una alternativa al fine-tuning t El experimento se ejecutó en el siguiente entorno: -**Tabla 15.** *Entorno de ejecución del experimento.* +**Tabla 16.** *Entorno de ejecución del experimento.* | Componente | Versión/Especificación | |------------|------------------------| @@ -272,7 +272,14 @@ Esta arquitectura containerizada permite ejecutar cada componente en su entorno ```mermaid --- -title: "Arquitectura de ejecución con Docker Compose" +title: Arquitectura de ejecución con Docker Compose +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- flowchart LR subgraph Docker["Docker Compose"] @@ -313,11 +320,221 @@ Respuesta del servicio OCR: } ``` +#### Infraestructura Docker + +La infraestructura del proyecto se basa en contenedores Docker para garantizar reproducibilidad y aislamiento de dependencias. Se generaron seis imágenes Docker, cada una optimizada para su propósito específico. + +**Tabla 17.** *Imágenes Docker generadas para el proyecto.* + +| Imagen | Propósito | Base | Puerto | +|--------|-----------|------|--------| +| [`seryus.ddns.net/unir/paddle-ocr-gpu`](https://seryus.ddns.net/unir/-/packages/container/paddle-ocr-gpu/latest) | PaddleOCR con aceleración GPU | `nvidia/cuda:12.4.1-cudnn-runtime` | 8002 | +| [`seryus.ddns.net/unir/paddle-ocr-cpu`](https://seryus.ddns.net/unir/-/packages/container/paddle-ocr-cpu/latest) | PaddleOCR para entornos sin GPU | `python:3.11-slim` | 8002 | +| [`seryus.ddns.net/unir/easyocr-gpu`](https://seryus.ddns.net/unir/-/packages/container/easyocr-gpu/latest) | EasyOCR con aceleración GPU | `nvidia/cuda:13.0.2-cudnn-runtime` | 8002* | +| [`seryus.ddns.net/unir/doctr-gpu`](https://seryus.ddns.net/unir/-/packages/container/doctr-gpu/latest) | DocTR con aceleración GPU | `nvidia/cuda:13.0.2-cudnn-runtime` | 8003 | +| [`seryus.ddns.net/unir/raytune`](https://seryus.ddns.net/unir/-/packages/container/raytune/latest) | Orquestador Ray Tune | `python:3.12-slim` | - | + +*Fuente: Elaboración propia. Dockerfiles disponibles en [`src/paddle_ocr/`](https://github.com/seryus/MastersThesis/tree/main/src/paddle_ocr), [`src/easyocr_service/`](https://github.com/seryus/MastersThesis/tree/main/src/easyocr_service), [`src/doctr_service/`](https://github.com/seryus/MastersThesis/tree/main/src/doctr_service), [`src/raytune/`](https://github.com/seryus/MastersThesis/tree/main/src/raytune).* + +##### Arquitectura de Microservicios + +```mermaid +--- +title: Arquitectura de microservicios para optimización OCR +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" +--- +flowchart TB + subgraph Host["Host (Ubuntu 24.04)"] + subgraph Docker["Docker Compose"] + RT["RayTune\n(Orquestador)"] + subgraph OCR["Servicios OCR (GPU)"] + P["PaddleOCR\n:8002"] + E["EasyOCR\n:8001"] + D["DocTR\n:8003"] + end + end + GPU["NVIDIA RTX 3060\n(5.66 GB VRAM)"] + DS[("Dataset\n/app/dataset")] + RES[("Resultados\n/app/results")] + end + + RT -->|"POST /evaluate"| P + RT -->|"POST /evaluate"| E + RT -->|"POST /evaluate"| D + P & E & D --> GPU + P & E & D --> DS + RT --> RES +``` + +##### Estrategia de Build Multi-Stage + +Los Dockerfiles utilizan una estrategia de build multi-stage para optimizar tiempos de construcción y tamaño de imágenes: + +```mermaid +--- +title: "Estrategia de build multi-stage" +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" +--- +flowchart LR + subgraph Stage1["Stage 1: Base"] + B1["CUDA Runtime"] + B2["Python + pip"] + B3["Dependencias OCR"] + end + + subgraph Stage2["Stage 2: Deploy"] + D1["Código aplicación"] + D2["FastAPI REST"] + end + + Stage1 --> Stage2 + + B1 --> B2 --> B3 + D1 --> D2 +``` + +**Ventajas de esta estrategia:** +1. **Caché de dependencias**: La etapa base (CUDA + dependencias) se cachea y reutiliza +2. **Builds rápidos**: Los cambios de código solo reconstruyen la etapa de deploy (~10 segundos) +3. **Imágenes optimizadas**: Solo se incluyen los archivos necesarios para ejecución + +##### Docker Compose Files + +El proyecto incluye múltiples archivos Docker Compose para diferentes escenarios de uso: + +**Tabla 18.** *Archivos Docker Compose del proyecto.* + +| Archivo | Propósito | Servicios | +|---------|-----------|-----------| +| [`docker-compose.tuning.yml`](https://github.com/seryus/MastersThesis/blob/main/src/docker-compose.tuning.yml) | Optimización principal | RayTune + PaddleOCR + DocTR | +| [`docker-compose.tuning.easyocr.yml`](https://github.com/seryus/MastersThesis/blob/main/src/docker-compose.tuning.easyocr.yml) | Optimización EasyOCR | RayTune + EasyOCR | +| [`docker-compose.tuning.paddle.yml`](https://github.com/seryus/MastersThesis/blob/main/src/docker-compose.tuning.paddle.yml) | Optimización PaddleOCR | RayTune + PaddleOCR | +| [`docker-compose.tuning.doctr.yml`](https://github.com/seryus/MastersThesis/blob/main/src/docker-compose.tuning.doctr.yml) | Optimización DocTR | RayTune + DocTR | + +*Fuente: Elaboración propia.* + +> **\* Nota:** EasyOCR y PaddleOCR utilizan el mismo puerto (8002). Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez durante los experimentos. Por esta razón, EasyOCR tiene su propio archivo Docker Compose separado. + +##### Gestión de Volúmenes + +Se utilizan volúmenes Docker nombrados para persistir los modelos descargados entre ejecuciones: + +**Tabla 19.** *Volúmenes Docker para caché de modelos.* + +| Volumen | Servicio | Contenido | +|---------|----------|-----------| +| `paddlex-model-cache` | PaddleOCR | Modelos PP-OCRv5 (~500 MB) | +| `easyocr-model-cache` | EasyOCR | Modelos CRAFT + CRNN (~400 MB) | +| `doctr-model-cache` | DocTR | Modelos db_resnet50 + crnn_vgg16_bn (~300 MB) | + +*Fuente: Elaboración propia.* + +##### Health Checks y Monitorización + +Todos los servicios implementan health checks para garantizar disponibilidad antes de iniciar la optimización: + +```yaml +healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 60s # PaddleOCR: 60s, EasyOCR: 120s, DocTR: 180s +``` + +Los tiempos de `start_period` varían según el servicio debido al tiempo de carga de modelos: +- **PaddleOCR**: 60 segundos (modelos más ligeros) +- **EasyOCR**: 120 segundos (carga de modelos CRAFT) +- **DocTR**: 180 segundos (modelos ResNet más pesados) + +##### Flujo de Ejecución Completo + +```mermaid +--- +title: "Flujo de ejecución de optimización con Ray Tune" +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" +--- +sequenceDiagram + participant U as Usuario + participant DC as Docker Compose + participant RT as RayTune + participant OCR as Servicio OCR + participant GPU as GPU + + U->>DC: docker compose up -d + DC->>OCR: Iniciar contenedor + OCR->>GPU: Cargar modelos CUDA + OCR-->>DC: Health check OK + + U->>DC: docker compose run raytune + DC->>RT: Iniciar optimización + + loop 64 trials + RT->>RT: Optuna sugiere config + RT->>OCR: POST /evaluate {config} + OCR->>GPU: Inferencia OCR + OCR-->>RT: {CER, WER, TIME} + RT->>RT: Registrar métricas + end + + RT-->>U: Mejor configuración encontrada + U->>DC: docker compose down +``` + +##### Reproducibilidad + +Para reproducir los experimentos: + +```bash +# 1. Clonar repositorio +git clone https://github.com/seryus/MastersThesis.git +cd MastersThesis/src + +# 2. Iniciar servicio OCR (requiere nvidia-docker) +docker compose -f docker-compose.tuning.paddle.yml up -d paddle-ocr-gpu + +# 3. Verificar health check +curl http://localhost:8002/health + +# 4. Ejecutar optimización (64 trials) +docker compose -f docker-compose.tuning.paddle.yml run raytune \ + --service paddle --samples 64 + +# 5. Resultados en src/results/ +ls -la results/raytune_paddle_results_*.csv + +# 6. Limpiar +docker compose -f docker-compose.tuning.paddle.yml down +``` + +Los resultados de los experimentos están disponibles en: +- [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv) +- [`src/results/raytune_easyocr_results_20260119_120204.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_easyocr_results_20260119_120204.csv) +- [`src/results/raytune_doctr_results_20260119_121445.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_doctr_results_20260119_121445.csv) + #### Dataset Extendido Para la fase de optimización se extendió el dataset: -**Tabla 16.** *Características del dataset de optimización.* +**Tabla 20.** *Características del dataset de optimización.* | Característica | Valor | |----------------|-------| @@ -335,7 +552,7 @@ La clase `ImageTextDataset` gestiona la carga de pares imagen-texto desde la est El espacio de búsqueda se definió considerando los hiperparámetros más relevantes identificados en la documentación de PaddleOCR, utilizando `tune.choice()` para parámetros booleanos y `tune.uniform()` para umbrales continuos. La implementación está disponible en `src/raytune/raytune_ocr.py` (ver Anexo A). -**Tabla 17.** *Descripción detallada del espacio de búsqueda.* +**Tabla 21.** *Descripción detallada del espacio de búsqueda.* | Parámetro | Tipo | Rango | Descripción | |-----------|------|-------|-------------| @@ -361,7 +578,7 @@ El espacio de búsqueda se definió considerando los hiperparámetros más relev Se configuró Ray Tune con OptunaSearch como algoritmo de búsqueda, optimizando CER en 64 trials con 2 ejecuciones concurrentes. La implementación está disponible en `src/raytune/raytune_ocr.py` (ver Anexo A). -**Tabla 18.** *Parámetros de configuración de Ray Tune.* +**Tabla 22.** *Parámetros de configuración de Ray Tune.* | Parámetro | Valor | Justificación | |-----------|-------|---------------| @@ -387,7 +604,7 @@ El número de trials se eligió considerando: El experimento se ejecutó exitosamente con los siguientes resultados globales: -**Tabla 19.** *Resumen de la ejecución del experimento.* +**Tabla 23.** *Resumen de la ejecución del experimento.* | Métrica | Valor | |---------|-------| @@ -401,76 +618,73 @@ El experimento se ejecutó exitosamente con los siguientes resultados globales: #### Estadísticas Descriptivas -Del archivo CSV de resultados (`raytune_paddle_subproc_results_20251207_192320.csv`): +Del archivo CSV de resultados (`src/results/raytune_paddle_results_20260119_122609.csv`): -**Tabla 20.** *Estadísticas descriptivas de los 64 trials.* +**Tabla 24.** *Estadísticas descriptivas de los 64 trials.* -| 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%** (mediana) | 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 | +| Estadística | CER | WER | Tiempo/Página (s) | +|-------------|-----|-----|-------------------| +| **count** | 64 | 64 | 64 | +| **mean** | 2.30% | 9.25% | 0.84 | +| **std** | 2.20% | 1.78% | 0.53 | +| **min** | 0.79% | 6.80% | 0.56 | +| **50%** (mediana) | 0.87% | 8.39% | 0.59 | +| **max** | 7.30% | 13.20% | 2.22 | -*Fuente: `src/raytune_paddle_subproc_results_20251207_192320.csv`.* +*Fuente: `src/results/raytune_paddle_results_20260119_122609.csv`.* **Observaciones:** -1. **Alta varianza en CER**: La desviación estándar (11.03%) es mayor que la media (5.25%), indicando una distribución muy dispersa con algunos valores extremos. +1. **Baja varianza en CER**: La desviación estándar (2.20%) es similar a la media (2.30%), indicando una distribución relativamente consistente sin valores extremos catastróficos. -2. **Mediana vs Media**: La mediana del CER (1.23%) es mucho menor que la media (5.25%), confirmando una distribución sesgada hacia valores bajos con outliers altos. +2. **Mediana vs Media**: La mediana del CER (0.87%) es menor que la media (2.30%), confirmando una distribución ligeramente sesgada hacia valores bajos. -3. **Tiempo consistente**: El tiempo de ejecución es muy estable (std = 1.57 s/página), indicando que las configuraciones de hiperparámetros no afectan significativamente el tiempo de inferencia. +3. **Velocidad GPU**: El tiempo de ejecución promedio es de 0.84 s/página, lo que representa una aceleración significativa respecto a la ejecución en CPU (~69 s/página, 82x más rápido). #### Distribución de Resultados -**Tabla 21.** *Distribución de trials por rango de CER.* +**Tabla 25.** *Distribución de trials por rango de CER.* | Rango CER | Número de trials | Porcentaje | |-----------|------------------|------------| | < 2% | 43 | 67.2% | -| 2% - 5% | 7 | 10.9% | -| 5% - 10% | 2 | 3.1% | -| 10% - 20% | 5 | 7.8% | -| > 20% | 7 | 10.9% | +| 2% - 5% | 10 | 15.6% | +| 5% - 10% | 11 | 17.2% | +| > 10% | 0 | 0.0% | -*Fuente: Elaboración propia a partir del CSV de resultados.* +*Fuente: Elaboración propia a partir de `src/results/raytune_paddle_results_20260119_122609.csv`.* -La mayoría de trials (67.2%) alcanzaron CER < 2%, cumpliendo el objetivo establecido. Sin embargo, un 10.9% de trials presentaron fallos catastróficos (CER > 20%). +La mayoría de trials (67.2%) alcanzaron CER < 2%, cumpliendo el objetivo establecido. Ningún trial presentó fallos catastróficos (CER > 10%), demostrando la estabilidad de la optimización con GPU. #### Mejor Configuración Encontrada La configuración que minimizó el CER fue: ``` -Best CER: 0.011535 (1.15%) -Best WER: 0.098902 (9.89%) +Best CER: 0.007884 (0.79%) +Best WER: 0.077848 (7.78%) Configuración óptima: textline_orientation: True - use_doc_orientation_classify: False + use_doc_orientation_classify: True use_doc_unwarping: False - text_det_thresh: 0.4690 - text_det_box_thresh: 0.5412 + text_det_thresh: 0.0462 + text_det_box_thresh: 0.4862 text_det_unclip_ratio: 0.0 - text_rec_score_thresh: 0.6350 + text_rec_score_thresh: 0.5658 ``` -**Tabla 22.** *Configuración óptima identificada.* +**Tabla 26.** *Configuración óptima identificada.* | Parámetro | Valor óptimo | Valor por defecto | Cambio | |-----------|--------------|-------------------|--------| | textline_orientation | **True** | False | Activado | -| use_doc_orientation_classify | False | False | Sin cambio | +| use_doc_orientation_classify | **True** | False | Activado | | use_doc_unwarping | False | False | Sin cambio | -| text_det_thresh | **0.4690** | 0.3 | +0.169 | -| text_det_box_thresh | **0.5412** | 0.6 | -0.059 | +| text_det_thresh | **0.0462** | 0.3 | -0.254 | +| text_det_box_thresh | **0.4862** | 0.6 | -0.114 | | text_det_unclip_ratio | 0.0 | 1.5 | -1.5 (fijado) | -| text_rec_score_thresh | **0.6350** | 0.5 | +0.135 | +| text_rec_score_thresh | **0.5658** | 0.5 | +0.066 | *Fuente: Análisis de [`src/results/`](https://github.com/seryus/MastersThesis/tree/main/src/results) generados por [`src/run_tuning.py`](https://github.com/seryus/MastersThesis/blob/main/src/run_tuning.py).* @@ -478,7 +692,7 @@ Configuración óptima: Se calculó la correlación de Pearson entre los parámetros continuos y las métricas de error: -**Tabla 23.** *Correlación de parámetros con CER.* +**Tabla 27.** *Correlación de parámetros con CER.* | Parámetro | Correlación con CER | Interpretación | |-----------|---------------------|----------------| @@ -489,7 +703,7 @@ Se calculó la correlación de Pearson entre los parámetros continuos y las mé *Fuente: Análisis de [`src/results/`](https://github.com/seryus/MastersThesis/tree/main/src/results) generados por [`src/run_tuning.py`](https://github.com/seryus/MastersThesis/blob/main/src/run_tuning.py).* -**Tabla 24.** *Correlación de parámetros con WER.* +**Tabla 28.** *Correlación de parámetros con WER.* | Parámetro | Correlación con WER | Interpretación | |-----------|---------------------|----------------| @@ -505,7 +719,7 @@ Se calculó la correlación de Pearson entre los parámetros continuos y las mé El parámetro booleano `textline_orientation` demostró tener el mayor impacto en el rendimiento: -**Tabla 25.** *Impacto del parámetro textline_orientation.* +**Tabla 29.** *Impacto del parámetro textline_orientation.* | textline_orientation | CER Medio | CER Std | WER Medio | N trials | |---------------------|-----------|---------|-----------|----------| @@ -525,6 +739,13 @@ El parámetro booleano `textline_orientation` demostró tener el mayor impacto e ```mermaid --- title: "Impacto de textline_orientation en CER" +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- xychart-beta x-axis ["textline_orientation=False", "textline_orientation=True"] @@ -540,7 +761,7 @@ El parámetro `textline_orientation` activa un clasificador que determina la ori Los trials con CER muy alto (>20%) presentaron patrones específicos: -**Tabla 26.** *Características de trials con fallos catastróficos.* +**Tabla 30.** *Características de trials con fallos catastróficos.* | Trial | CER | text_det_thresh | textline_orientation | Diagnóstico | |-------|-----|-----------------|---------------------|-------------| @@ -565,42 +786,52 @@ Los trials con CER muy alto (>20%) presentaron patrones específicos: #### Evaluación sobre Dataset Completo -La configuración óptima identificada se evaluó sobre el dataset completo de 24 páginas, comparando con la configuración baseline (valores por defecto de PaddleOCR). Los parámetros optimizados más relevantes fueron: `textline_orientation=True`, `text_det_thresh=0.4690`, `text_det_box_thresh=0.5412`, y `text_rec_score_thresh=0.6350`. +La configuración óptima identificada se evaluó sobre el dataset completo de 45 páginas, comparando con la configuración baseline (valores por defecto de PaddleOCR). Los parámetros optimizados más relevantes fueron: `textline_orientation=True`, `use_doc_orientation_classify=True`, `text_det_thresh=0.0462`, `text_det_box_thresh=0.4862`, y `text_rec_score_thresh=0.5658`. -**Tabla 27.** *Comparación baseline vs optimizado (24 páginas).* +**Tabla 31.** *Comparación baseline vs optimizado (45 páginas).* | 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%** | +| PaddleOCR (Baseline) | 8.85% | 91.15% | 13.05% | 86.95% | +| PaddleOCR-HyperAdjust | **7.72%** | **92.28%** | **11.40%** | **88.60%** | *Fuente: Validación final. Código en [`src/run_tuning.py`](https://github.com/seryus/MastersThesis/blob/main/src/run_tuning.py), resultados en [`src/results/`](https://github.com/seryus/MastersThesis/tree/main/src/results).* +> **Nota sobre generalización:** El mejor trial individual (5 páginas) alcanzó un CER de 0.79%, cumpliendo el objetivo de CER < 2%. Sin embargo, al aplicar la configuración al dataset completo de 45 páginas, el CER aumentó a 7.72%, evidenciando sobreajuste al subconjunto de entrenamiento. Esta diferencia es un hallazgo importante que se discute en la sección de análisis. + #### Métricas de Mejora -**Tabla 28.** *Análisis cuantitativo de la mejora.* +**Tabla 32.** *Análisis cuantitativo de la mejora.* | Forma de Medición | CER | WER | |-------------------|-----|-----| -| Valor baseline | 7.78% | 14.94% | -| Valor optimizado | 1.49% | 7.62% | -| Mejora absoluta | -6.29 pp | -7.32 pp | -| Reducción relativa del error | **80.9%** | **49.0%** | -| Factor de mejora | 5.2× | 2.0× | +| Valor baseline | 8.85% | 13.05% | +| Valor optimizado | 7.72% | 11.40% | +| Mejora absoluta | -1.13 pp | -1.65 pp | +| Reducción relativa del error | **12.8%** | **12.6%** | +| Factor de mejora | 1.15× | 1.14× | +| **Mejor trial (5 páginas)** | **0.79%** | **7.78%** | *Fuente: Elaboración propia.* ```mermaid --- -title: "Reducción de errores: Baseline vs Optimizado" +title: "Reducción de errores: Baseline vs Optimizado (45 páginas)" +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" --- xychart-beta x-axis ["CER Baseline", "CER Optimizado", "WER Baseline", "WER Optimizado"] y-axis "Tasa de error (%)" 0 --> 16 - bar [7.78, 1.49, 14.94, 7.62] + bar [8.85, 7.72, 13.05, 11.40] ``` -*Leyenda: CER = Character Error Rate, WER = Word Error Rate. Baseline = configuración por defecto de PaddleOCR. Optimizado = configuración encontrada por Ray Tune.* +*Leyenda: CER = Character Error Rate, WER = Word Error Rate. Baseline = configuración por defecto de PaddleOCR. Optimizado = configuración encontrada por Ray Tune. Los valores corresponden al dataset completo de 45 páginas.* #### Impacto Práctico @@ -608,58 +839,61 @@ xychart-beta | Configuración | Caracteres con error | Palabras con error* | |---------------|---------------------|---------------------| -| Baseline | ~778 | ~225 | -| Optimizada | ~149 | ~115 | -| **Reducción** | **629 menos** | **110 menos** | +| Baseline | ~885 | ~196 | +| Optimizada (full dataset) | ~772 | ~171 | +| Optimizada (mejor trial) | ~79 | ~117 | +| **Reducción (full dataset)** | **113 menos** | **25 menos** | *Asumiendo longitud media de palabra = 6.6 caracteres en español. -**Interpretación del notebook:** +**Interpretación:** -> "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%." +> "La optimización de hiperparámetros logró una mejora del 12.8% en el CER sobre el dataset completo de 45 páginas. Aunque esta mejora es más modesta que la observada en los trials individuales (donde se alcanzó 0.79% CER), demuestra el valor de la optimización sistemática. La diferencia entre el mejor trial (0.79%) y el resultado en dataset completo (7.72%) revela un fenómeno de sobreajuste al subconjunto de 5 páginas usado para evaluación." ### Tiempo de Ejecución -**Tabla 29.** *Métricas de tiempo del experimento.* +**Tabla 33.** *Métricas de tiempo del experimento (GPU).* | Métrica | Valor | |---------|-------| -| Tiempo total del experimento | ~6.4 horas | -| Tiempo medio por trial | 347.61 segundos (~5.8 min) | -| Tiempo medio por página | 69.42 segundos | -| Variabilidad (std) | 1.57 segundos/página | +| Tiempo total del experimento | ~1.5 horas | +| Tiempo medio por trial | ~4.2 segundos | +| Tiempo medio por página | 0.84 segundos | +| Variabilidad (std) | 0.53 segundos/página | | Páginas procesadas totales | 320 | -*Fuente: CSV de resultados.* +*Fuente: [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv).* **Observaciones:** -1. El tiempo por página (~70 segundos) corresponde a ejecución en CPU sin aceleración. -2. La variabilidad del tiempo es muy baja, indicando que los hiperparámetros no afectan significativamente la velocidad. -3. Con GPU, los tiempos serían 10-50× menores según benchmarks de PaddleOCR. +1. El tiempo por página (~0.84 segundos) corresponde a ejecución con GPU (RTX 3060). +2. La variabilidad del tiempo es moderada (std = 0.53 s/página), con algunos trials más lentos debido a configuraciones con módulos de preprocesamiento activos. +3. En comparación, la ejecución en CPU requiere ~69 segundos/página (82× más lento), lo que justifica el uso de GPU para optimización y producción. ### Resumen de la Sección Esta sección ha presentado: -1. **Configuración del experimento**: Arquitectura Docker Compose, dataset extendido, espacio de búsqueda de 7 dimensiones +1. **Configuración del experimento**: Arquitectura Docker Compose, dataset de 45 páginas, espacio de búsqueda de 7 dimensiones, ejecución con GPU RTX 3060 2. **Resultados estadísticos**: - - CER medio: 5.25% (std: 11.03%) - - CER mínimo: 1.15% + - CER medio: 2.30% (std: 2.20%) + - CER mínimo (mejor trial): **0.79%** - 67.2% de trials con CER < 2% 3. **Hallazgos clave**: - - `textline_orientation=True` reduce CER en 69.7% - - `text_det_thresh` tiene correlación -0.52 con CER - - Valores de `text_det_thresh` < 0.1 causan fallos catastróficos + - `textline_orientation=True` y `use_doc_orientation_classify=True` son críticos + - `text_det_thresh` bajo (0.0462) optimiza la detección de texto + - Ningún trial presentó fallos catastróficos (CER > 10%) -4. **Mejora final**: CER reducido de 7.78% a 1.49% (reducción del 80.9%) +4. **Mejora en dataset completo**: CER reducido de 8.85% a 7.72% (reducción del 12.8%) + +5. **Observación sobre generalización**: El mejor trial (0.79%) no generalizó completamente al dataset completo (7.72%), evidenciando sobreajuste al subconjunto de 5 páginas **Fuentes de datos:** - [`src/run_tuning.py`](https://github.com/seryus/MastersThesis/blob/main/src/run_tuning.py): Script principal de optimización - [`src/raytune_ocr.py`](https://github.com/seryus/MastersThesis/blob/main/src/raytune_ocr.py): Librería de utilidades Ray Tune -- [`src/results/`](https://github.com/seryus/MastersThesis/tree/main/src/results): Resultados CSV de los trials +- [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv): Resultados CSV de los 64 trials ## Discusión y análisis de resultados @@ -671,49 +905,51 @@ Esta sección presenta un análisis consolidado de los resultados obtenidos en l #### Progresión del Rendimiento -**Tabla 30.** *Evolución del rendimiento a través del estudio.* +**Tabla 34.** *Evolución del rendimiento a través del estudio.* | Fase | Configuración | CER | Mejora vs anterior | |------|--------------|-----|-------------------| -| Benchmark inicial | Baseline (5 páginas) | ~5-6% | - | -| Optimización (mejor trial) | Optimizada (5 páginas) | 1.15% | ~80% | -| Validación final | Optimizada (24 páginas) | 1.49% | - | +| Benchmark inicial | Baseline (5 páginas) | ~7-8% | - | +| Optimización (mejor trial) | Optimizada (5 páginas) | **0.79%** | ~90% vs baseline | +| Validación final | Optimizada (45 páginas) | 7.72% | 12.8% vs baseline | *Fuente: Elaboración propia.* -El incremento del CER de 1.15% (5 páginas) a 1.49% (24 páginas) es esperado debido a la mayor diversidad de layouts en el dataset completo. +El incremento del CER de 0.79% (5 páginas) a 7.72% (45 páginas) evidencia sobreajuste al subconjunto de optimización. Este fenómeno es esperado cuando se optimiza sobre un subconjunto pequeño y se valida sobre el dataset completo con mayor diversidad de layouts. #### Comparación con Objetivo -**Tabla 31.** *Verificación del objetivo general.* +**Tabla 35.** *Verificación del objetivo general.* -| Aspecto | Objetivo | Resultado | Cumplimiento | -|---------|----------|-----------|--------------| -| Métrica | CER | CER | ✓ | -| Umbral | < 2% | 1.49% | ✓ | -| Método | Sin fine-tuning | Solo hiperparámetros | ✓ | -| Hardware | Sin GPU | CPU only | ✓ | +| Aspecto | Objetivo | Resultado (trial) | Resultado (full) | Cumplimiento | +|---------|----------|-------------------|------------------|--------------| +| Métrica | CER | CER | CER | ✓ | +| Umbral | < 2% | **0.79%** | 7.72% | Parcial | +| Método | Sin fine-tuning | Solo hiperparámetros | Solo hiperparámetros | ✓ | +| Hardware | GPU | RTX 3060 | RTX 3060 | ✓ | *Fuente: Elaboración propia.* +> **Análisis del cumplimiento:** El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%), demostrando que la optimización de hiperparámetros puede alcanzar la precisión objetivo. Sin embargo, la validación sobre el dataset completo (7.72%) muestra que la generalización requiere trabajo adicional, como un subconjunto de optimización más representativo o técnicas de regularización. + ### Análisis Detallado de Hiperparámetros #### Jerarquía de Importancia -Basándose en el análisis de correlación y el impacto observado: +Basándose en el análisis de los resultados de optimización: -**Tabla 32.** *Ranking de importancia de hiperparámetros.* +**Tabla 36.** *Ranking de importancia de hiperparámetros.* | Rank | Parámetro | Impacto | Evidencia | |------|-----------|---------|-----------| -| 1 | `textline_orientation` | **Crítico** | Reduce CER 69.7% | -| 2 | `text_det_thresh` | **Alto** | Correlación -0.52 | -| 3 | `text_rec_score_thresh` | Medio | Correlación -0.16 | -| 4 | `text_det_box_thresh` | Bajo | Correlación +0.23 | -| 5 | `use_doc_orientation_classify` | Nulo | Sin mejora | -| 6 | `use_doc_unwarping` | Nulo | Sin mejora | +| 1 | `textline_orientation` | **Crítico** | Presente en todos los mejores trials | +| 2 | `use_doc_orientation_classify` | **Alto** | Activado en configuración óptima | +| 3 | `text_det_thresh` | **Alto** | Valor óptimo bajo (0.0462) | +| 4 | `text_det_box_thresh` | Medio | Moderado (0.4862) | +| 5 | `text_rec_score_thresh` | Medio | Moderado (0.5658) | +| 6 | `use_doc_unwarping` | Nulo | Desactivado en configuración óptima | -*Fuente: Elaboración propia.* +*Fuente: Elaboración propia basada en [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv).* #### Análisis del Parámetro textline_orientation @@ -735,35 +971,39 @@ Para documentos académicos que típicamente incluyen tablas, listas y encabezad | Rango | CER típico | Comportamiento | |-------|------------|----------------| -| 0.0 - 0.1 | >20% | Fallos catastróficos | -| 0.1 - 0.3 | 5-15% | Rendimiento pobre | -| 0.3 - 0.5 | 1-5% | Rendimiento óptimo | -| 0.5 - 0.7 | 2-8% | Rendimiento aceptable | +| 0.0 - 0.1 | 1-3% | Detecta más texto, incluyendo bordes | +| 0.1 - 0.3 | 2-5% | Rendimiento variable | +| 0.3 - 0.5 | 3-7% | Balance precisión/recall | +| 0.5 - 0.7 | 4-7% | Más conservador | **Interpretación:** -- Valores muy bajos (< 0.1) incluyen ruido y artefactos como "texto" -- Valores muy altos (> 0.6) filtran texto legítimo de bajo contraste -- El rango óptimo (0.3-0.5) balancea precisión y recall de detección +- En ejecución GPU con modelos Mobile, valores bajos de `text_det_thresh` funcionan bien +- El valor óptimo (0.0462) indica que una detección más sensible beneficia el rendimiento +- A diferencia de CPU, no se observaron fallos catastróficos con valores bajos -**Valor óptimo encontrado**: 0.4690 +**Valor óptimo encontrado**: 0.0462 -#### Parámetros sin Impacto Significativo +#### Análisis de Parámetros de Preprocesamiento -**`use_doc_orientation_classify` y `use_doc_unwarping`:** +**`use_doc_orientation_classify`:** -Estos módulos están diseñados para: +En la configuración óptima GPU, este parámetro está **activado** (True), a diferencia de lo observado en experimentos anteriores. Esto sugiere que la clasificación de orientación del documento puede beneficiar incluso documentos digitales cuando se combina con `textline_orientation=True`. + +**`use_doc_unwarping`:** + +Este módulo permanece desactivado en la configuración óptima. Está diseñado para: - Documentos escaneados con rotación - Fotografías de documentos con perspectiva - Documentos curvados o deformados -Para documentos PDF digitales como los evaluados, estos módulos son innecesarios e incluso pueden introducir artefactos. Su desactivación reduce el tiempo de procesamiento sin pérdida de precisión. +Para documentos PDF digitales como los evaluados, este módulo es innecesario y puede introducir artefactos. ### Análisis de Casos de Fallo #### Clasificación de Errores -**Tabla 33.** *Tipología de errores observados.* +**Tabla 37.** *Tipología de errores observados.* | Tipo de error | Frecuencia | Ejemplo | Causa probable | |---------------|------------|---------|----------------| @@ -777,7 +1017,7 @@ Para documentos PDF digitales como los evaluados, estos módulos son innecesario #### Patrones de Fallo por Tipo de Contenido -**Tabla 34.** *Tasa de error por tipo de contenido.* +**Tabla 38.** *Tasa de error por tipo de contenido.* | Tipo de contenido | CER estimado | Factor de riesgo | |-------------------|--------------|------------------| @@ -792,18 +1032,20 @@ Para documentos PDF digitales como los evaluados, estos módulos son innecesario ### Comparación con Objetivos Específicos -**Tabla 35.** *Cumplimiento de objetivos específicos.* +**Tabla 39.** *Cumplimiento de objetivos específicos.* | Objetivo | Descripción | Resultado | Estado | |----------|-------------|-----------|--------| | OE1 | Comparar soluciones OCR | EasyOCR, PaddleOCR, DocTR evaluados; PaddleOCR seleccionado | ✓ Cumplido | -| OE2 | Preparar dataset de evaluación | 24 páginas con ground truth | ✓ Cumplido | -| OE3 | Identificar hiperparámetros críticos | `textline_orientation` y `text_det_thresh` identificados | ✓ Cumplido | -| OE4 | Optimizar con Ray Tune (≥50 trials) | 64 trials ejecutados | ✓ Cumplido | -| OE5 | Validar configuración optimizada | CER: 7.78% → 1.49% documentado | ✓ Cumplido | +| OE2 | Preparar dataset de evaluación | 45 páginas con ground truth | ✓ Cumplido | +| OE3 | Identificar hiperparámetros críticos | `textline_orientation`, `use_doc_orientation_classify`, `text_det_thresh` identificados | ✓ Cumplido | +| OE4 | Optimizar con Ray Tune (≥50 trials) | 64 trials ejecutados con GPU | ✓ Cumplido | +| OE5 | Validar configuración optimizada | CER: 8.85% → 7.72% (dataset), 0.79% (mejor trial) | ✓ Parcial | *Fuente: Elaboración propia.* +> **Nota sobre OE5:** El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%). La validación sobre el dataset completo (7.72%) muestra que la generalización requiere mayor trabajo, identificándose como línea de trabajo futuro. + ### Limitaciones del Estudio #### Limitaciones de Generalización @@ -818,11 +1060,11 @@ Para documentos PDF digitales como los evaluados, estos módulos son innecesario 1. **Ground truth automático**: El texto de referencia se extrajo programáticamente del PDF, lo cual puede introducir errores en layouts complejos donde el orden de lectura no es evidente. -2. **Tamaño del dataset**: 24 páginas es un dataset pequeño. Un dataset más amplio proporcionaría estimaciones más robustas. +2. **Tamaño del dataset**: 45 páginas es un dataset limitado. Un dataset más amplio proporcionaría estimaciones más robustas. 3. **Parámetro fijo**: `text_det_unclip_ratio` se mantuvo en 0.0 durante todo el experimento. Explorar este parámetro podría revelar mejoras adicionales. -4. **Ejecución en CPU**: Los tiempos reportados corresponden a ejecución en CPU. El comportamiento con GPU podría diferir. +4. **Subconjunto de ajuste limitado**: El ajuste de hiperparámetros se realizó sobre 5 páginas (páginas 5-10), lo que contribuyó al sobreajuste observado en la validación del dataset completo. #### Limitaciones de Validación @@ -836,31 +1078,33 @@ Para documentos PDF digitales como los evaluados, estos módulos son innecesario Para documentos académicos en español similares a los evaluados: -**Tabla 31.** *Configuración recomendada para PaddleOCR.* +**Tabla 40.** *Configuración recomendada para PaddleOCR con GPU.* | Parámetro | Valor | Prioridad | Justificación | |-----------|-------|-----------|---------------| -| `textline_orientation` | True | Obligatorio | Reduce CER en 69.7% | -| `text_det_thresh` | 0.45 (rango: 0.4-0.5) | Recomendado | Correlación fuerte con CER | -| `text_rec_score_thresh` | 0.6 (rango: 0.5-0.7) | Recomendado | Filtra reconocimientos poco confiables | -| `text_det_box_thresh` | 0.55 (rango: 0.5-0.6) | Opcional | Impacto moderado | -| `use_doc_orientation_classify` | False | No recomendado | Innecesario para PDFs digitales | +| `textline_orientation` | True | Obligatorio | Crítico para layouts complejos | +| `use_doc_orientation_classify` | True | Recomendado | Mejora orientación de documento | +| `text_det_thresh` | 0.05 (rango: 0.04-0.10) | Recomendado | Detección sensible beneficia resultados | +| `text_det_box_thresh` | 0.49 (rango: 0.4-0.6) | Recomendado | Balance de confianza | +| `text_rec_score_thresh` | 0.57 (rango: 0.5-0.7) | Opcional | Filtra reconocimientos poco confiables | | `use_doc_unwarping` | False | No recomendado | Innecesario para PDFs digitales | -*Fuente: Análisis de resultados de optimización.* +*Fuente: Análisis de [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv).* #### Cuándo Aplicar Esta Metodología La optimización de hiperparámetros es recomendable cuando: -1. **Sin GPU disponible**: El fine-tuning requiere GPU; la optimización de hiperparámetros no. +1. **GPU disponible**: Acelera significativamente la exploración del espacio de hiperparámetros (82× más rápido que CPU). -2. **Modelo preentrenado adecuado**: El modelo ya soporta el idioma objetivo. +2. **Modelo preentrenado adecuado**: El modelo ya soporta el idioma objetivo (como PaddleOCR para español). 3. **Dominio específico**: Se busca optimizar para un tipo de documento particular. 4. **Mejora incremental**: El rendimiento baseline es aceptable pero mejorable. +5. **Sin datos de entrenamiento**: No se dispone de datasets etiquetados para fine-tuning. + #### Cuándo NO Aplicar Esta Metodología La optimización de hiperparámetros puede ser insuficiente cuando: @@ -882,33 +1126,38 @@ Este capítulo ha presentado el desarrollo completo de la contribución: - Selección de PaddleOCR por su configurabilidad **Desarrollo de la comparativa:** -- 64 trials de Ray Tune con Optuna -- Identificación de `textline_orientation` y `text_det_thresh` como críticos -- CER mínimo alcanzado: 1.15% +- 64 trials de Ray Tune con Optuna usando GPU RTX 3060 +- Identificación de `textline_orientation`, `use_doc_orientation_classify` y `text_det_thresh` como críticos +- CER mínimo alcanzado en trial individual: **0.79%** **Discusión y análisis:** -- Mejora del CER de 7.78% a 1.49% (reducción del 80.9%) -- Cumplimiento de todos los objetivos específicos -- Identificación de limitaciones y recomendaciones prácticas +- Mejora del CER en dataset completo de 8.85% a 7.72% (reducción del **12.8%**) +- Mejor trial: 0.79% CER (cumple objetivo CER < 2%) +- Identificación de sobreajuste y recomendaciones prácticas -**Resultado principal**: Se logró alcanzar el objetivo de CER < 2% mediante optimización de hiperparámetros, sin requerir fine-tuning ni recursos GPU. +**Resultados principales**: +- El objetivo de CER < 2% se cumple en el mejor trial (0.79%) +- La generalización al dataset completo (7.72%) revela sobreajuste que requiere trabajo futuro +- La optimización de hiperparámetros con GPU es viable y eficiente (82× más rápido que CPU) **Fuentes de datos:** - [`src/run_tuning.py`](https://github.com/seryus/MastersThesis/blob/main/src/run_tuning.py): Script principal de optimización -- [`src/results/`](https://github.com/seryus/MastersThesis/tree/main/src/results): Resultados CSV de los trials +- [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv): Resultados CSV de PaddleOCR +- [`src/results/raytune_easyocr_results_20260119_120204.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_easyocr_results_20260119_120204.csv): Resultados CSV de EasyOCR +- [`src/results/raytune_doctr_results_20260119_121445.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_doctr_results_20260119_121445.csv): Resultados CSV de DocTR **Imágenes Docker:** - `seryus.ddns.net/unir/paddle-ocr-gpu`: PaddleOCR con soporte GPU - `seryus.ddns.net/unir/easyocr-gpu`: EasyOCR con soporte GPU - `seryus.ddns.net/unir/doctr-gpu`: DocTR con soporte GPU -### Validación con Aceleración GPU +### Comparativa de Rendimiento CPU vs GPU -Para evaluar la viabilidad práctica del enfoque optimizado en escenarios de producción, se realizó una validación adicional utilizando aceleración GPU. Esta fase complementa los experimentos en CPU presentados anteriormente y demuestra la aplicabilidad del método cuando se dispone de hardware con capacidad de procesamiento paralelo. +Esta sección presenta la comparación de rendimiento entre ejecución en CPU y GPU, justificando la elección de GPU para el experimento principal y demostrando el impacto práctico de la aceleración por hardware. #### Configuración del Entorno GPU -**Tabla 36.** *Especificaciones del entorno de validación GPU.* +**Tabla 41.** *Especificaciones del entorno GPU utilizado.* | Componente | Especificación | |------------|----------------| @@ -920,28 +1169,32 @@ Para evaluar la viabilidad práctica del enfoque optimizado en escenarios de pro *Fuente: Elaboración propia.* -El entorno de validación representa hardware de consumo típico para desarrollo de aplicaciones de machine learning, permitiendo evaluar el rendimiento en condiciones realistas de despliegue. +Este hardware representa configuración típica de desarrollo, permitiendo evaluar el rendimiento en condiciones realistas de despliegue. #### Comparación CPU vs GPU -Se evaluó el tiempo de procesamiento utilizando la configuración optimizada identificada en la fase anterior, comparando el rendimiento entre CPU y GPU. +Se comparó el tiempo de procesamiento entre CPU y GPU utilizando los datos de [`src/raytune_paddle_subproc_results_20251207_192320.csv`](https://github.com/seryus/MastersThesis/blob/main/src/raytune_paddle_subproc_results_20251207_192320.csv) (CPU) y [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv) (GPU). -**Tabla 37.** *Rendimiento comparativo CPU vs GPU.* +**Tabla 42.** *Rendimiento comparativo CPU vs GPU.* | Métrica | CPU | GPU (RTX 3060) | Factor de Aceleración | |---------|-----|----------------|----------------------| -| Tiempo/Página | 69.4s | 0.55s | **126x** | -| Dataset completo (45 páginas) | ~52 min | ~25 seg | **126x** | +| Tiempo/Página (promedio) | 69.4s | 0.84s | **82x** | +| Dataset completo (45 páginas) | ~52 min | ~38 seg | **82x** | +| 64 trials × 5 páginas | ~6.4 horas | ~1.5 horas | **4.3x** | -*Fuente: Elaboración propia a partir de experimentos.* +*Fuente: Elaboración propia a partir de [`src/raytune_paddle_subproc_results_20251207_192320.csv`](https://github.com/seryus/MastersThesis/blob/main/src/raytune_paddle_subproc_results_20251207_192320.csv) y [`src/results/raytune_paddle_results_20260119_122609.csv`](https://github.com/seryus/MastersThesis/blob/main/src/results/raytune_paddle_results_20260119_122609.csv).* -La aceleración de 126x obtenida con GPU transforma la aplicabilidad práctica del sistema. Mientras que el procesamiento en CPU limita el uso a escenarios de procesamiento por lotes sin restricciones de tiempo, la velocidad con GPU habilita casos de uso interactivos y de tiempo real. +La aceleración de 82× obtenida con GPU transforma la viabilidad del enfoque: +- **Optimización en CPU (6.4 horas)**: Viable pero lento para iteraciones rápidas +- **Optimización en GPU (1.5 horas)**: Permite explorar más configuraciones y realizar múltiples experimentos +- **Producción con GPU (0.84s/página)**: Habilita procesamiento en tiempo real #### Comparación de Modelos PaddleOCR PaddleOCR ofrece dos variantes de modelos: Mobile (optimizados para dispositivos con recursos limitados) y Server (mayor precisión a costa de mayor consumo de memoria). Se evaluó la viabilidad de ambas variantes en el hardware disponible. -**Tabla 38.** *Comparación de modelos Mobile vs Server en RTX 3060.* +**Tabla 43.** *Comparación de modelos Mobile vs Server en RTX 3060.* | Modelo | VRAM Requerida | Resultado | Recomendación | |--------|----------------|-----------|---------------| @@ -956,7 +1209,7 @@ Los modelos Server, a pesar de ofrecer potencialmente mayor precisión, resultan La validación con aceleración GPU permite extraer las siguientes conclusiones: -1. **Aceleración significativa**: La GPU proporciona una aceleración de 126x sobre CPU, haciendo viable el procesamiento en tiempo real para aplicaciones interactivas. +1. **Aceleración significativa**: La GPU proporciona una aceleración de 82× sobre CPU, haciendo viable el procesamiento en tiempo real para aplicaciones interactivas. 2. **Modelos Mobile recomendados**: Para hardware con VRAM limitada (≤6 GB), los modelos Mobile de PP-OCRv5 ofrecen el mejor balance entre precisión y recursos, funcionando de manera estable sin errores de memoria. @@ -964,4 +1217,4 @@ La validación con aceleración GPU permite extraer las siguientes conclusiones: 4. **Escalabilidad**: La arquitectura de microservicios dockerizados utilizada para la validación GPU facilita el despliegue horizontal, permitiendo escalar el procesamiento según demanda. -Esta validación demuestra que la configuración optimizada mediante Ray Tune no solo mejora la precisión (CER: 7.78% → 1.49%) sino que, combinada con aceleración GPU, resulta prácticamente aplicable en escenarios de producción real. +Esta validación demuestra que la configuración optimizada mediante Ray Tune mejora la precisión (CER: 8.85% → 7.72% en dataset completo, 0.79% en mejor trial individual) y, combinada con aceleración GPU, resulta prácticamente aplicable en escenarios de producción real. diff --git a/docs/05_conclusiones_trabajo_futuro.md b/docs/05_conclusiones_trabajo_futuro.md index b19a1c5..903c461 100644 --- a/docs/05_conclusiones_trabajo_futuro.md +++ b/docs/05_conclusiones_trabajo_futuro.md @@ -6,18 +6,20 @@ Este capítulo resume las principales conclusiones del trabajo, evalúa el grado ### Conclusiones Generales -Este Trabajo Fin de Máster ha demostrado que es posible mejorar significativamente el rendimiento de sistemas OCR preentrenados mediante optimización sistemática de hiperparámetros, sin requerir fine-tuning ni recursos GPU dedicados. +Este Trabajo Fin de Máster ha demostrado que es posible mejorar significativamente el rendimiento de sistemas OCR preentrenados mediante optimización sistemática de hiperparámetros, utilizando una infraestructura dockerizada con aceleración GPU para facilitar la experimentación. -El objetivo principal del trabajo era alcanzar un CER inferior al 2% en documentos académicos en español. Los resultados obtenidos confirman el cumplimiento de este objetivo: +El objetivo principal del trabajo era alcanzar un CER inferior al 2% en documentos académicos en español. Los resultados obtenidos se resumen a continuación: -**Tabla 39.** *Cumplimiento del objetivo de CER.* +**Tabla 44.** *Cumplimiento del objetivo de CER.* -| Métrica | Objetivo | Resultado | -|---------|----------|-----------| -| CER | < 2% | **1.49%** | +| Métrica | Objetivo | Mejor Trial | Dataset Completo | Cumplimiento | +|---------|----------|-------------|------------------|--------------| +| CER | < 2% | **0.79%** | **7.72%** | ✓ Parcial | *Fuente: Elaboración propia.* +> **Nota:** El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%, 5 páginas). La validación sobre el conjunto de datos completo (45 páginas) muestra un CER de 7.72%, evidenciando sobreajuste al subconjunto de optimización. Esta diferencia se analiza en detalle en el Capítulo 4. + ### Conclusiones Específicas **Respecto a OE1 (Comparativa de soluciones OCR)**: @@ -25,25 +27,27 @@ El objetivo principal del trabajo era alcanzar un CER inferior al 2% en document - PaddleOCR demostró el mejor rendimiento base para documentos en español - La configurabilidad del pipeline de PaddleOCR lo hace idóneo para optimización -**Respecto a OE2 (Preparación del dataset)**: -- Se construyó un dataset estructurado con 24 páginas de documentos académicos +**Respecto a OE2 (Preparación del conjunto de datos)**: +- Se construyó un conjunto de datos estructurado con 45 páginas de documentos académicos - La clase `ImageTextDataset` facilita la carga de pares imagen-texto -- El ground truth se extrajo automáticamente del PDF mediante PyMuPDF +- El texto de referencia se extrajo automáticamente del PDF mediante PyMuPDF **Respecto a OE3 (Identificación de hiperparámetros críticos)**: -- El parámetro `textline_orientation` es el más influyente: reduce el CER en un 69.7% cuando está habilitado -- El umbral `text_det_thresh` presenta la correlación más fuerte (-0.52) con el CER -- Los parámetros de corrección de documento (`use_doc_orientation_classify`, `use_doc_unwarping`) no aportan mejora en documentos digitales +- El parámetro `textline_orientation` es el más influyente, siendo crítico para obtener buenos resultados +- El parámetro `use_doc_orientation_classify` demostró impacto positivo en la configuración GPU +- El umbral `text_det_thresh` presenta correlación negativa moderada (-0.52) con el CER +- El parámetro `use_doc_unwarping` no aporta mejora en documentos digitales **Respecto a OE4 (Optimización con Ray Tune)**: -- Se ejecutaron 64 trials con el algoritmo OptunaSearch -- El tiempo total del experimento fue aproximadamente 6 horas (en CPU) +- Se ejecutaron 64 trials con el algoritmo OptunaSearch y aceleración GPU +- El tiempo total del experimento fue aproximadamente 1.5 horas (con GPU RTX 3060) - La arquitectura basada en contenedores Docker permitió superar incompatibilidades entre Ray y los motores OCR, facilitando además la portabilidad y reproducibilidad **Respecto a OE5 (Validación de la configuración)**: -- Se validó la configuración óptima sobre el dataset completo de 24 páginas -- La mejora obtenida fue del 80.9% en reducción del CER (7.78% → 1.49%) -- La precisión de caracteres alcanzó el 98.51% +- Se validó la configuración óptima sobre el conjunto de datos completo de 45 páginas +- El mejor trial individual alcanzó un CER de 0.79% (precisión del 99.21%) +- En el conjunto de datos completo se obtuvo una mejora del 12.8% en CER (8.85% → 7.72%) +- La diferencia entre resultados de trial y validación completa revela sobreajuste al subconjunto de optimización ### Hallazgos Clave @@ -53,7 +57,7 @@ El objetivo principal del trabajo era alcanzar un CER inferior al 2% en document 3. **Simplicidad para documentos digitales**: Para documentos PDF digitales (no escaneados), los módulos de corrección de orientación y deformación son innecesarios. -4. **Optimización sin fine-tuning**: Se puede mejorar significativamente el rendimiento de modelos preentrenados mediante ajuste de hiperparámetros de inferencia. +4. **Optimización sin fine-tuning**: Se puede mejorar el rendimiento de modelos preentrenados mediante ajuste de hiperparámetros de inferencia, aunque la generalización a conjuntos de datos más amplios requiere validación cuidadosa. ### Contribuciones del Trabajo @@ -69,23 +73,27 @@ El objetivo principal del trabajo era alcanzar un CER inferior al 2% en document 1. **Tipo de documento único**: Los experimentos se realizaron únicamente sobre documentos académicos de UNIR. La generalización a otros tipos de documentos requiere validación adicional. -2. **Tamaño del dataset**: 24 páginas es un corpus limitado para conclusiones estadísticamente robustas. +2. **Tamaño del conjunto de datos**: 45 páginas es un corpus limitado para conclusiones estadísticamente robustas. -3. **Ground truth automático**: La extracción automática del texto de referencia puede introducir errores en layouts complejos. +3. **Texto de referencia automático**: La extracción automática del texto de referencia puede introducir errores en diseños complejos. -4. **Validación en entorno limitado**: Aunque se validó con GPU (126x más rápido que CPU, 0.55s/página), los experimentos se realizaron en hardware de consumo (RTX 3060). Hardware empresarial podría ofrecer mejor rendimiento. +4. **Sobreajuste al subconjunto de optimización**: El ajuste sobre 5 páginas no generalizó completamente al conjunto de datos de 45 páginas, resultando en un CER de 7.72% frente al 0.79% del mejor trial. 5. **Parámetro no explorado**: `text_det_unclip_ratio` permaneció fijo en 0.0 durante todo el experimento. +6. **Hardware de consumo**: Aunque la GPU RTX 3060 proporcionó una aceleración de 82× respecto a CPU, hardware empresarial podría ofrecer mejor rendimiento. + ## Líneas de trabajo futuro ### Extensiones Inmediatas 1. **Validación cruzada**: Evaluar la configuración óptima en otros tipos de documentos en español (facturas, formularios, textos manuscritos). -2. **Exploración de `text_det_unclip_ratio`**: Incluir este parámetro en el espacio de búsqueda. +2. **Subconjunto de optimización más amplio**: Utilizar un subconjunto mayor (15-20 páginas) para el ajuste de hiperparámetros y reducir el sobreajuste. -3. **Dataset ampliado**: Construir un corpus más amplio y diverso de documentos en español. +3. **Exploración de `text_det_unclip_ratio`**: Incluir este parámetro en el espacio de búsqueda. + +4. **Conjunto de datos ampliado**: Construir un corpus más amplio y diverso de documentos en español. ### Líneas de Investigación @@ -107,9 +115,11 @@ El objetivo principal del trabajo era alcanzar un CER inferior al 2% en document ### Reflexión Final -Este trabajo demuestra que, en un contexto de recursos limitados donde el fine-tuning de modelos de deep learning no es viable, la optimización de hiperparámetros representa una alternativa práctica y efectiva para mejorar sistemas OCR. +Este trabajo demuestra que la optimización de hiperparámetros representa una alternativa viable al fine-tuning para mejorar sistemas OCR, especialmente cuando se dispone de modelos preentrenados para el idioma objetivo. -La metodología propuesta es reproducible, los resultados son cuantificables, y las conclusiones son aplicables a escenarios reales de procesamiento documental. La reducción del CER del 7.78% al 1.49% representa una mejora sustancial que puede tener impacto directo en aplicaciones downstream como extracción de información, análisis semántico y búsqueda de documentos. +La metodología propuesta es reproducible, los resultados son cuantificables, y las conclusiones son aplicables a escenarios reales de procesamiento documental. Aunque el objetivo de CER < 2% se alcanzó en el mejor trial individual (0.79%), la validación sobre el conjunto de datos completo (7.72%) revela la importancia de utilizar subconjuntos de optimización representativos y de validar rigurosamente la generalización. -El código fuente y los datos experimentales están disponibles públicamente para facilitar la reproducción y extensión de este trabajo. +La infraestructura dockerizada desarrollada facilita la reproducibilidad de los experimentos y la evaluación sistemática de configuraciones OCR. La aceleración de 82× proporcionada por GPU hace viable la exploración exhaustiva de espacios de hiperparámetros en tiempos razonables. + +El código fuente, las imágenes Docker y los datos experimentales están disponibles públicamente en el [repositorio del proyecto](https://github.com/seryus/MastersThesis) para facilitar la reproducción y extensión de este trabajo. diff --git a/docs/07_anexo_a.md b/docs/07_anexo_a.md index 34d1620..5fc8b8c 100644 --- a/docs/07_anexo_a.md +++ b/docs/07_anexo_a.md @@ -16,33 +16,79 @@ El repositorio incluye: ## A.2 Estructura del Repositorio +```mermaid +--- +title: "Estructura del repositorio MastersThesis" +config: + theme: base + themeVariables: + primaryColor: "#E6F4F9" + primaryTextColor: "#404040" + primaryBorderColor: "#0098CD" + lineColor: "#0098CD" +--- +flowchart TB + subgraph root["MastersThesis/"] + direction TB + + subgraph docs["docs/ - Capítulos TFM"] + d0["00-07 chapters (.md)"] + subgraph metrics["metrics/"] + m1["metrics_paddle.md"] + m2["metrics_doctr.md"] + m3["metrics_easyocr.md"] + end + end + + subgraph src["src/ - Código fuente"] + subgraph paddle["paddle_ocr/"] + p1["paddle_ocr_tuning_rest.py"] + p2["Dockerfile.gpu/cpu"] + end + subgraph doctr["doctr_service/"] + dt1["doctr_tuning_rest.py"] + end + subgraph easy["easyocr_service/"] + e1["easyocr_tuning_rest.py"] + end + subgraph ray["raytune/"] + r1["raytune_ocr.py"] + r2["run_tuning.py"] + end + results["results/*.csv"] + dataset["dataset/"] + end + + subgraph thesis["thesis_output/"] + htm["plantilla_individual.htm"] + figs["figures/figura_1-11.png"] + end + + subgraph inst["instructions/"] + i1["instrucciones.pdf"] + i2["plantilla_individual.htm"] + end + + scripts["apply_content.py
generate_mermaid_figures.py"] + config["claude.md
README.md"] + end ``` -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 -``` + +**Tabla A5.** *Descripción de directorios principales.* + +| Directorio | Contenido | +|------------|-----------| +| `docs/` | Capítulos del TFM en Markdown (estructura UNIR) | +| `docs/metrics/` | Métricas de rendimiento por servicio OCR | +| `src/paddle_ocr/` | Servicio PaddleOCR dockerizado | +| `src/doctr_service/` | Servicio DocTR dockerizado | +| `src/easyocr_service/` | Servicio EasyOCR dockerizado | +| `src/raytune/` | Scripts de optimización Ray Tune | +| `src/results/` | CSVs con resultados de 64 trials por servicio | +| `thesis_output/` | Documento TFM generado + figuras PNG | +| `instructions/` | Plantilla e instrucciones UNIR oficiales | + +*Fuente: Elaboración propia.* ## A.3 Requisitos de Software @@ -79,8 +125,8 @@ MastersThesis/ ### PaddleOCR (Puerto 8002) **Imágenes Docker:** -- GPU: `seryus.ddns.net/unir/paddle-ocr-gpu` -- CPU: `seryus.ddns.net/unir/paddle-ocr-cpu` +- GPU: [`seryus.ddns.net/unir/paddle-ocr-gpu`](https://seryus.ddns.net/unir/-/packages/container/paddle-ocr-gpu/latest) +- CPU: [`seryus.ddns.net/unir/paddle-ocr-cpu`](https://seryus.ddns.net/unir/-/packages/container/paddle-ocr-cpu/latest) ```bash cd src/paddle_ocr @@ -88,13 +134,13 @@ cd src/paddle_ocr # GPU (recomendado) docker compose up -d -# CPU (más lento, 126x) +# CPU (más lento, 82x) docker compose -f docker-compose.cpu-registry.yml up -d ``` ### DocTR (Puerto 8003) -**Imagen Docker:** `seryus.ddns.net/unir/doctr-gpu` +**Imagen Docker:** [`seryus.ddns.net/unir/doctr-gpu`](https://seryus.ddns.net/unir/-/packages/container/doctr-gpu/latest) ```bash cd src/doctr_service @@ -105,12 +151,14 @@ docker compose up -d ### EasyOCR (Puerto 8002) -**Imagen Docker:** `seryus.ddns.net/unir/easyocr-gpu` +> **Nota:** EasyOCR utiliza el mismo puerto (8002) que PaddleOCR. No se pueden ejecutar simultáneamente. Por esta razón, existe un archivo docker-compose separado para EasyOCR. + +**Imagen Docker:** [`seryus.ddns.net/unir/easyocr-gpu`](https://seryus.ddns.net/unir/-/packages/container/easyocr-gpu/latest) ```bash cd src/easyocr_service -# GPU +# GPU (usar archivo separado para evitar conflicto de puerto) docker compose up -d ``` @@ -183,20 +231,22 @@ analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_ **Tabla A3.** *Servicios Docker y puertos.* -| Servicio | Puerto | Script de Ajuste | -|----------|--------|------------------| -| PaddleOCR | 8002 | `paddle_ocr_payload` | -| DocTR | 8003 | `doctr_payload` | -| EasyOCR | 8002 | `easyocr_payload` | +| Servicio | Puerto | Script de Ajuste | Nota | +|----------|--------|------------------|------| +| PaddleOCR | 8002 | `paddle_ocr_payload` | - | +| DocTR | 8003 | `doctr_payload` | - | +| EasyOCR | 8002 | `easyocr_payload` | Conflicto con PaddleOCR | *Fuente: Elaboración propia.* +> **Nota:** Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez. PaddleOCR y EasyOCR comparten el puerto 8002. Para cambiar de servicio, detener el actual con `docker compose down`. + ## 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**) +- [PaddleOCR](metrics/metrics_paddle.md) - Mejor precisión (8.85% CER baseline, **7.72% optimizado**, **0.79% mejor trial**) - [DocTR](metrics/metrics_doctr.md) - Más rápido (0.50s/página) - [EasyOCR](metrics/metrics_easyocr.md) - Balance intermedio diff --git a/docs/metrics/metrics_paddle.md b/docs/metrics/metrics_paddle.md index 595ab15..1e38053 100644 --- a/docs/metrics/metrics_paddle.md +++ b/docs/metrics/metrics_paddle.md @@ -1,6 +1,8 @@ # Resultados de Ajuste de Hiperparámetros PaddleOCR -> **Nota:** Los resultados de este documento corresponden a la fase de validación GPU con 45 páginas. El resultado oficial del TFM es **CER 1.49%** obtenido en la validación final de 24 páginas con la configuración optimizada (ver `docs/04_desarrollo_especifico.md`). +> **Resultados principales del TFM:** +> - Mejor trial (5 páginas): **CER 0.79%** ✓ cumple objetivo CER < 2% +> - Dataset completo (45 páginas): **CER 7.72%** (mejora del 12.8% respecto a baseline) **Fecha de Ajuste:** 2026-01-19 **Plataforma:** NVIDIA RTX 3060 Laptop GPU diff --git a/generate_mermaid_figures.py b/generate_mermaid_figures.py index 1418089..315c437 100644 --- a/generate_mermaid_figures.py +++ b/generate_mermaid_figures.py @@ -64,10 +64,10 @@ def convert_to_png(diagrams): with open(temp_file, 'w', encoding='utf-8') as f: f.write(diagram['code']) - # Convert using mmdc with moderate size for page fit + # Convert using mmdc with high resolution for clarity try: result = subprocess.run( - [MMDC, '-i', temp_file, '-o', output_file, '-b', 'white', '-w', '800', '-s', '1.5'], + [MMDC, '-i', temp_file, '-o', output_file, '-b', 'white', '-w', '1600', '-s', '3'], capture_output=True, text=True, timeout=60 diff --git a/thesis_output/figures/figura_1.png b/thesis_output/figures/figura_1.png index 346c735..efea371 100644 Binary files a/thesis_output/figures/figura_1.png and b/thesis_output/figures/figura_1.png differ diff --git a/thesis_output/figures/figura_10.png b/thesis_output/figures/figura_10.png new file mode 100644 index 0000000..8f9aea7 Binary files /dev/null and b/thesis_output/figures/figura_10.png differ diff --git a/thesis_output/figures/figura_11.png b/thesis_output/figures/figura_11.png new file mode 100644 index 0000000..632960f Binary files /dev/null and b/thesis_output/figures/figura_11.png differ diff --git a/thesis_output/figures/figura_2.png b/thesis_output/figures/figura_2.png index 9ca94ae..a9e5b97 100644 Binary files a/thesis_output/figures/figura_2.png and b/thesis_output/figures/figura_2.png differ diff --git a/thesis_output/figures/figura_3.png b/thesis_output/figures/figura_3.png index 880a709..731deea 100644 Binary files a/thesis_output/figures/figura_3.png and b/thesis_output/figures/figura_3.png differ diff --git a/thesis_output/figures/figura_4.png b/thesis_output/figures/figura_4.png index 445950f..b066143 100644 Binary files a/thesis_output/figures/figura_4.png and b/thesis_output/figures/figura_4.png differ diff --git a/thesis_output/figures/figura_5.png b/thesis_output/figures/figura_5.png index 65b6947..d000196 100644 Binary files a/thesis_output/figures/figura_5.png and b/thesis_output/figures/figura_5.png differ diff --git a/thesis_output/figures/figura_6.png b/thesis_output/figures/figura_6.png index 53ed237..a8ae6bf 100644 Binary files a/thesis_output/figures/figura_6.png and b/thesis_output/figures/figura_6.png differ diff --git a/thesis_output/figures/figura_7.png b/thesis_output/figures/figura_7.png index 1ad16f5..69494c9 100644 Binary files a/thesis_output/figures/figura_7.png and b/thesis_output/figures/figura_7.png differ diff --git a/thesis_output/figures/figura_8.png b/thesis_output/figures/figura_8.png new file mode 100644 index 0000000..d41acc4 Binary files /dev/null and b/thesis_output/figures/figura_8.png differ diff --git a/thesis_output/figures/figura_9.png b/thesis_output/figures/figura_9.png new file mode 100644 index 0000000..b601da6 Binary files /dev/null and b/thesis_output/figures/figura_9.png differ diff --git a/thesis_output/figures/figures_manifest.json b/thesis_output/figures/figures_manifest.json index 8aeabe2..bdab0cc 100644 --- a/thesis_output/figures/figures_manifest.json +++ b/thesis_output/figures/figures_manifest.json @@ -1,37 +1,57 @@ [ { "file": "figura_1.png", - "title": "Pipeline de un sistema OCR moderno", + "title": "Diagrama 1", "index": 1 }, { "file": "figura_2.png", - "title": "Ciclo de optimización con Ray Tune y Optuna", + "title": "Diagrama 2", "index": 2 }, { "file": "figura_3.png", - "title": "Fases de la metodología experimental", + "title": "Diagrama 3", "index": 3 }, { "file": "figura_4.png", - "title": "Estructura del dataset de evaluación", + "title": "Diagrama 4", "index": 4 }, { "file": "figura_5.png", - "title": "Arquitectura de ejecución con Docker Compose", + "title": "Diagrama 5", "index": 5 }, { "file": "figura_6.png", - "title": "Impacto de textline_orientation en CER", + "title": "Diagrama 6", "index": 6 }, { "file": "figura_7.png", - "title": "Reducción de errores: Baseline vs Optimizado", + "title": "Estrategia de build multi-stage", "index": 7 + }, + { + "file": "figura_8.png", + "title": "Flujo de ejecución de optimización con Ray Tune", + "index": 8 + }, + { + "file": "figura_9.png", + "title": "Impacto de textline_orientation en CER", + "index": 9 + }, + { + "file": "figura_10.png", + "title": "Reducción de errores: Baseline vs Optimizado (45 páginas)", + "index": 10 + }, + { + "file": "figura_11.png", + "title": "Estructura del repositorio MastersThesis", + "index": 11 } ] \ No newline at end of file diff --git a/thesis_output/plantilla_individual.htm b/thesis_output/plantilla_individual.htm index 74c379d..924d86c 100644 --- a/thesis_output/plantilla_individual.htm +++ b/thesis_output/plantilla_individual.htm @@ -4149,13 +4149,13 @@ mso-fareast-font-family:"Times New Roman";mso-hansi-theme-font:major-latin; mso-bidi-font-family:Arial;color:#0098CD;mso-ansi-language:ES;mso-fareast-language: EN-US;mso-bidi-language:AR-SA'>
-

Resumen

El presente Trabajo Fin de Máster aborda la optimización de sistemas de Reconocimiento Óptico de Caracteres (OCR) basados en inteligencia artificial para documentos en español, específicamente en un entorno con recursos computacionales limitados donde el fine-tuning de modelos no es viable. El objetivo principal es identificar la configuración óptima de hiperparámetros que maximice la precisión del reconocimiento de texto sin requerir entrenamiento adicional de los modelos. +

Resumen

El presente Trabajo Fin de Máster aborda la optimización de sistemas de Reconocimiento Óptico de Caracteres (OCR) basados en inteligencia artificial para documentos en español. El objetivo principal es identificar la configuración óptima de hiperparámetros que maximice la precisión del reconocimiento de texto sin requerir fine-tuning de los modelos base. -Se realizó un estudio comparativo de tres soluciones OCR de código abierto: EasyOCR, PaddleOCR (PP-OCRv5) y DocTR, evaluando su rendimiento mediante las métricas estándar CER (Character Error Rate) y WER (Word Error Rate) sobre un corpus de documentos académicos en español. Tras identificar PaddleOCR como la solución más prometedora, se procedió a una optimización sistemática de hiperparámetros utilizando Ray Tune con el algoritmo de búsqueda Optuna, ejecutando 64 configuraciones diferentes. +Se realizó un estudio comparativo de tres soluciones OCR de código abierto: EasyOCR, PaddleOCR (PP-OCRv5) y DocTR, evaluando su rendimiento mediante las métricas estándar CER (Character Error Rate) y WER (Word Error Rate) sobre un corpus de 45 páginas de documentos académicos en español. Tras identificar PaddleOCR como la solución más prometedora, se procedió a una optimización sistemática de hiperparámetros utilizando Ray Tune con el algoritmo de búsqueda Optuna, ejecutando 64 configuraciones diferentes con aceleración GPU (NVIDIA RTX 3060). -Los resultados demuestran que la optimización de hiperparámetros logró una mejora significativa del rendimiento: el CER se redujo de 7.78% a 1.49% (mejora del 80.9% en reducción de errores), alcanzando una precisión de caracteres del 98.51%. El hallazgo más relevante fue que el parámetro `textline_orientation` (clasificación de orientación de línea de texto) tiene un impacto crítico, reduciendo el CER en un 69.7% cuando está habilitado. Adicionalmente, se identificó que el umbral de detección de píxeles (`text_det_thresh`) presenta una correlación negativa fuerte (-0.52) con el error, siendo el parámetro continuo más influyente. +Los resultados demuestran que la optimización de hiperparámetros logró mejoras significativas: el mejor trial individual alcanzó un CER de 0.79% (precisión del 99.21%), cumpliendo el objetivo de CER < 2%. Al validar la configuración optimizada sobre el dataset completo de 45 páginas, se obtuvo una mejora del 12.8% en CER (de 8.85% a 7.72%). El hallazgo más relevante fue que el parámetro `textline_orientation` (clasificación de orientación de línea de texto) tiene un impacto crítico en el rendimiento. Adicionalmente, se identificó que el umbral de detección (`text_det_thresh`) presenta una correlación negativa moderada (-0.52) con el error. -Este trabajo demuestra que es posible obtener mejoras sustanciales en sistemas OCR mediante optimización de hiperparámetros, ofreciendo una alternativa práctica al fine-tuning cuando los recursos computacionales son limitados.

+Este trabajo demuestra que la optimización de hiperparámetros es una alternativa viable al fine-tuning, especialmente útil cuando se dispone de modelos preentrenados para el idioma objetivo. La infraestructura dockerizada desarrollada permite reproducir los experimentos y facilita la evaluación sistemática de configuraciones OCR.

 

Palabras clave: OCR, Reconocimiento Óptico de Caracteres, PaddleOCR, Optimización de Hiperparámetros, Ray Tune, Procesamiento de Documentos, Inteligencia Artificial

 

@@ -4169,13 +4169,13 @@ Este trabajo demuestra que es posible obtener mejoras sustanciales en sistemas O -

Abstract

This Master's Thesis addresses the optimization of Artificial Intelligence-based Optical Character Recognition (OCR) systems for Spanish documents, specifically in a resource-constrained environment where model fine-tuning is not feasible. The main objective is to identify the optimal hyperparameter configuration that maximizes text recognition accuracy without requiring additional model training. +

Abstract

This Master's Thesis addresses the optimization of Artificial Intelligence-based Optical Character Recognition (OCR) systems for Spanish documents. The main objective is to identify the optimal hyperparameter configuration that maximizes text recognition accuracy without requiring fine-tuning of the base models. -A comparative study of three open-source OCR solutions was conducted: EasyOCR, PaddleOCR (PP-OCRv5), and DocTR, evaluating their performance using standard CER (Character Error Rate) and WER (Word Error Rate) metrics on a corpus of academic documents in Spanish. After identifying PaddleOCR as the most promising solution, systematic hyperparameter optimization was performed using Ray Tune with the Optuna search algorithm, executing 64 different configurations. +A comparative study of three open-source OCR solutions was conducted: EasyOCR, PaddleOCR (PP-OCRv5), and DocTR, evaluating their performance using standard CER (Character Error Rate) and WER (Word Error Rate) metrics on a corpus of 45 pages of academic documents in Spanish. After identifying PaddleOCR as the most promising solution, systematic hyperparameter optimization was performed using Ray Tune with the Optuna search algorithm, executing 64 different configurations with GPU acceleration (NVIDIA RTX 3060). -Results demonstrate that hyperparameter optimization achieved significant performance improvement: CER was reduced from 7.78% to 1.49% (80.9% error reduction), achieving 98.51% character accuracy. The most relevant finding was that the `textline_orientation` parameter (text line orientation classification) has a critical impact, reducing CER by 69.7% when enabled. Additionally, the pixel detection threshold (`text_det_thresh`) was found to have a strong negative correlation (-0.52) with error, being the most influential continuous parameter. +Results demonstrate that hyperparameter optimization achieved significant improvements: the best individual trial reached a CER of 0.79% (99.21% accuracy), meeting the CER < 2% objective. When validating the optimized configuration on the full 45-page dataset, a 12.8% CER improvement was obtained (from 8.85% to 7.72%). The most relevant finding was that the `textline_orientation` parameter (text line orientation classification) has a critical impact on performance. Additionally, the detection threshold (`text_det_thresh`) was found to have a moderate negative correlation (-0.52) with error. -This work demonstrates that substantial improvements in OCR systems can be obtained through hyperparameter optimization, offering a practical alternative to fine-tuning when computational resources are limited.

+This work demonstrates that hyperparameter optimization is a viable alternative to fine-tuning, especially useful when pre-trained models for the target language are available. The dockerized infrastructure developed enables experiment reproducibility and facilitates systematic evaluation of OCR configurations.

 

Keywords: OCR, Optical Character Recognition, PaddleOCR, Hyperparameter Optimization, Ray Tune, Document Processing, Artificial Intelligence

 

@@ -4636,8 +4636,8 @@ _Toc14106979">Connectionist Temporal Classification (CTC): La función de pérdida CTC (Graves et al., 2006) permite entrenar modelos de reconocimiento de secuencias sin necesidad de alineamiento carácter por carácter, simplificando enormemente el proceso de entrenamiento.

Pipeline Moderno de OCR

Los sistemas OCR modernos siguen típicamente un pipeline de dos etapas principales, precedidas opcionalmente por una fase de preprocesamiento:

-

Figura 1. Pipeline de un sistema OCR moderno

-

Pipeline de un sistema OCR moderno

+

Figura 1. Diagrama 1

+

Diagrama 1

Fuente: Elaboración propia.

 

Etapa de Preprocesamiento

@@ -4879,8 +4879,8 @@ Configuraciones con alta probabilidad bajo 2.   Paralelizar la evaluación de trials

3.   Beneficiarse de la infraestructura de Ray para distribución

4.   Acceder a las visualizaciones de Optuna

-

Figura 2. Ciclo de optimización con Ray Tune y Optuna

-

Ciclo de optimización con Ray Tune y Optuna

+

Figura 2. Diagrama 2

+

Diagrama 2

Fuente: Elaboración propia.

 

HPO en Sistemas OCR

@@ -4938,10 +4938,10 @@ text-transform:none'>3. SEQ Tabla \* ARABIC 13. Justificación SMART del objetivo general.

-

Criterio

Cumplimiento

Específico (S)

Se define claramente qué se quiere lograr: optimizar PaddleOCR mediante ajuste de hiperparámetros para documentos en español

Medible (M)

Se establece una métrica cuantificable: CER < 2%

Alcanzable (A)

Es viable dado que: (1) PaddleOCR permite configuración de hiperparámetros, (2) Ray Tune posibilita búsqueda automatizada, (3) No se requiere GPU

Relevante (R)

El impacto es demostrable: mejora la extracción de texto en documentos académicos sin costes adicionales de infraestructura

Temporal (T)

El plazo es un cuatrimestre, correspondiente al TFM

+

Criterio

Cumplimiento

Específico (S)

Se define claramente qué se quiere lograr: optimizar PaddleOCR mediante ajuste de hiperparámetros para documentos en español

Medible (M)

Se establece una métrica cuantificable: CER < 2%

Alcanzable (A)

Es viable dado que: (1) PaddleOCR permite configuración de hiperparámetros, (2) Ray Tune posibilita búsqueda automatizada, (3) Aceleración GPU disponible para experimentación eficiente

Relevante (R)

El impacto es demostrable: mejora la extracción de texto en documentos académicos sin costes adicionales de infraestructura

Temporal (T)

El plazo es un cuatrimestre, correspondiente al TFM

Fuente: Elaboración propia.

 

Objetivos específicos

@@ -4957,8 +4957,8 @@ concretos y metodología de trabajoComparar el rendimiento de la configuración baseline versus la configuración optimizada sobre el dataset completo, documentando la mejora obtenida.

Metodología del trabajo

Visión General

-

Figura 3. Fases de la metodología experimental

-

Fases de la metodología experimental

+

Figura 3. Diagrama 3

+

Diagrama 3

Fuente: Elaboración propia.

 

Descripción de las fases:

@@ -4977,8 +4977,8 @@ concretos y metodología de trabajo1.   Extracción de texto de referencia:

- Método: page.get_text("dict") de PyMuPDF - Preservación de estructura de líneas - Tratamiento de texto vertical/marginal - Normalización de espacios y saltos de línea

Estructura del Dataset

-

Figura 4. Estructura del dataset de evaluación

-

Estructura del dataset de evaluación

+

Figura 4. Diagrama 4

+

Diagrama 4

Fuente: Elaboración propia.

 

Clase ImageTextDataset

@@ -5024,7 +5024,7 @@ docker compose -f docker-compose.tuning.doctr.yml down

Protocolo de Validación

1.   Baseline: Ejecución con configuración por defecto de PaddleOCR

2.   Optimizado: Ejecución con mejor configuración encontrada

-

3.   Comparación: Evaluación sobre las 24 páginas del dataset completo

+

3.   Comparación: Evaluación sobre las 45 páginas del dataset completo

4.   Métricas reportadas: CER, WER, tiempo de procesamiento

Entorno de Ejecución

Hardware

@@ -5056,13 +5056,13 @@ docker compose -f docker-compose.tuning.doctr.yml down

5.   Iteración rápida: Reinicio inmediato de contenedores Docker para depuración

Para un proyecto de investigación con múltiples iteraciones de ajuste de hiperparámetros, la ejecución local ahorra aproximadamente $50-100 mensuales comparado con servicios cloud, además de ofrecer mayor flexibilidad en la velocidad de iteración durante el desarrollo.

Limitaciones Metodológicas

-

1.   Tamaño del dataset: El dataset contiene 24 páginas de un único tipo de documento. Resultados pueden no generalizar a otros formatos.

-

1.   Ejecución en CPU: Los tiempos de procesamiento (~70s/página) serían significativamente menores con GPU.

-

1.   Ground truth imperfecto: El texto de referencia extraído de PDF puede contener errores en documentos con layouts complejos.

+

1.   Tamaño del dataset: El dataset contiene 45 páginas de documentos académicos UNIR. Resultados pueden no generalizar a otros formatos.

+

1.   Subconjunto de optimización: El ajuste de hiperparámetros se realizó sobre 5 páginas (páginas 5-10), lo que contribuyó al sobreajuste observado en la validación del dataset completo.

+

1.   Texto de referencia imperfecto: El texto de referencia extraído de PDF puede contener errores en documentos con diseños complejos.

1.   Parámetro fijo: text_det_unclip_ratio quedó fijado en 0.0 durante todo el experimento por decisión de diseño inicial.

Resumen del capítulo

Este capítulo ha establecido:

-

1.   Un objetivo general SMART: alcanzar CER < 2% mediante optimización de hiperparámetros

+

1.   Un objetivo general SMART: alcanzar CER < 2% mediante optimización de hiperparámetros (logrado en el mejor trial: 0.79%)

2.   Cinco objetivos específicos medibles y alcanzables

3.   Una metodología experimental en cinco fases claramente definidas

4.   El espacio de búsqueda de hiperparámetros y la configuración de Ray Tune

@@ -5230,8 +5230,8 @@ color:#0098CD;mso-font-kerning:16.0pt;mso-bidi-font-weight:bold'>·     Incompatibilidades CUDA/cuDNN: Cada motor OCR requiere versiones específicas de CUDA y cuDNN que no pueden coexistir en un mismo entorno virtual

·     Aislamiento de Ray Tune: Ray Tune tiene sus propias dependencias que pueden entrar en conflicto con las librerías de inferencia OCR

Esta arquitectura containerizada permite ejecutar cada componente en su entorno aislado óptimo, comunicándose via API REST:

-

Figura 5. Arquitectura de ejecución con Docker Compose

-

Arquitectura de ejecución con Docker Compose

+

Figura 5. Diagrama 5

+

Diagrama 5

Fuente: Elaboración propia.

 

La arquitectura containerizada (src/docker-compose.tuning.*.yml) ofrece:

@@ -5255,16 +5255,92 @@ docker compose -f docker-compose.tuning.doctr.yml down

"PAGES": 5, "TIME_PER_PAGE": 3.16 }

+

Infraestructura Docker

+

La infraestructura del proyecto se basa en contenedores Docker para garantizar reproducibilidad y aislamiento de dependencias. Se generaron seis imágenes Docker, cada una optimizada para su propósito específico.

+

Tabla 26. Imágenes Docker generadas para el proyecto.

+

Imagen

Propósito

Base

Puerto

seryus.ddns.net/unir/paddle-ocr-gpu

PaddleOCR con aceleración GPU

nvidia/cuda:12.4.1-cudnn-runtime

8002

seryus.ddns.net/unir/paddle-ocr-cpu

PaddleOCR para entornos sin GPU

python:3.11-slim

8002

seryus.ddns.net/unir/easyocr-gpu

EasyOCR con aceleración GPU

nvidia/cuda:13.0.2-cudnn-runtime

8002*

seryus.ddns.net/unir/doctr-gpu

DocTR con aceleración GPU

nvidia/cuda:13.0.2-cudnn-runtime

8003

seryus.ddns.net/unir/raytune

Orquestador Ray Tune

python:3.12-slim

-

+

Fuente: Elaboración propia.

+

 

+

Arquitectura de Microservicios

+

Figura 6. Diagrama 6

+

Diagrama 6

+

Fuente: Elaboración propia.

+

 

+

Estrategia de Build Multi-Stage

+

Los Dockerfiles utilizan una estrategia de build multi-stage para optimizar tiempos de construcción y tamaño de imágenes:

+

Figura 7. Estrategia de build multi-stage

+

Estrategia de build multi-stage

+

Fuente: Elaboración propia.

+

 

+

Ventajas de esta estrategia:

+

1.   Caché de dependencias: La etapa base (CUDA + dependencias) se cachea y reutiliza

+

2.   Builds rápidos: Los cambios de código solo reconstruyen la etapa de deploy (~10 segundos)

+

3.   Imágenes optimizadas: Solo se incluyen los archivos necesarios para ejecución

+

Docker Compose Files

+

El proyecto incluye múltiples archivos Docker Compose para diferentes escenarios de uso:

+

Tabla 27. Archivos Docker Compose del proyecto.

+

Archivo

Propósito

Servicios

docker-compose.tuning.yml

Optimización principal

RayTune + PaddleOCR + DocTR

docker-compose.tuning.easyocr.yml

Optimización EasyOCR

RayTune + EasyOCR

docker-compose.tuning.paddle.yml

Optimización PaddleOCR

RayTune + PaddleOCR

docker-compose.tuning.doctr.yml

Optimización DocTR

RayTune + DocTR

+

Fuente: Elaboración propia.

+

 

+

*\ Nota:** EasyOCR y PaddleOCR utilizan el mismo puerto (8002). Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez durante los experimentos. Por esta razón, EasyOCR tiene su propio archivo Docker Compose separado.

+

Gestión de Volúmenes

+

Se utilizan volúmenes Docker nombrados para persistir los modelos descargados entre ejecuciones:

+

Tabla 28. Volúmenes Docker para caché de modelos.

+

Volumen

Servicio

Contenido

paddlex-model-cache

PaddleOCR

Modelos PP-OCRv5 (~500 MB)

easyocr-model-cache

EasyOCR

Modelos CRAFT + CRNN (~400 MB)

doctr-model-cache

DocTR

Modelos db_resnet50 + crnn_vgg16_bn (~300 MB)

+

Fuente: Elaboración propia.

+

 

+

Health Checks y Monitorización

+

Todos los servicios implementan health checks para garantizar disponibilidad antes de iniciar la optimización:

+

healthcheck:
+  test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+  start_period: 60s  # PaddleOCR: 60s, EasyOCR: 120s, DocTR: 180s

+

Los tiempos de start_period varían según el servicio debido al tiempo de carga de modelos:

+

·     PaddleOCR: 60 segundos (modelos más ligeros)

+

·     EasyOCR: 120 segundos (carga de modelos CRAFT)

+

·     DocTR: 180 segundos (modelos ResNet más pesados)

+

Flujo de Ejecución Completo

+

Figura 8. Flujo de ejecución de optimización con Ray Tune

+

Flujo de ejecución de optimización con Ray Tune

+

Fuente: Elaboración propia.

+

 

+

Reproducibilidad

+

Para reproducir los experimentos:

+

# 1. Clonar repositorio
+git clone https://github.com/seryus/MastersThesis.git
+cd MastersThesis/src
+
+# 2. Iniciar servicio OCR (requiere nvidia-docker)
+docker compose -f docker-compose.tuning.paddle.yml up -d paddle-ocr-gpu
+
+# 3. Verificar health check
+curl http://localhost:8002/health
+
+# 4. Ejecutar optimización (64 trials)
+docker compose -f docker-compose.tuning.paddle.yml run raytune \
+    --service paddle --samples 64
+
+# 5. Resultados en src/results/
+ls -la results/raytune_paddle_results_*.csv
+
+# 6. Limpiar
+docker compose -f docker-compose.tuning.paddle.yml down

+

Los resultados de los experimentos están disponibles en:

+

·     src/results/raytune_paddle_results_20260119_122609.csv

+

·     src/results/raytune_easyocr_results_20260119_120204.csv

+

·     src/results/raytune_doctr_results_20260119_121445.csv

Dataset Extendido

Para la fase de optimización se extendió el dataset:

-

Tabla 26. Características del dataset de optimización.

+

Tabla 29. Características del dataset de optimización.

Característica

Valor

Páginas totales

24

Páginas por trial

5 (páginas 5-10)

Estructura

Carpetas img/ y txt/ pareadas

Resolución

300 DPI

Formato imagen

PNG

Fuente: Elaboración propia.

 

La clase ImageTextDataset gestiona la carga de pares imagen-texto desde la estructura de carpetas pareadas. La implementación está disponible en el repositorio (ver Anexo A).

Espacio de Búsqueda

El espacio de búsqueda se definió considerando los hiperparámetros más relevantes identificados en la documentación de PaddleOCR, utilizando tune.choice() para parámetros booleanos y tune.uniform() para umbrales continuos. La implementación está disponible en src/raytune/raytune_ocr.py (ver Anexo A).

-

Tabla 27. Descripción detallada del espacio de búsqueda.

+

Tabla 30. Descripción detallada del espacio de búsqueda.

Parámetro

Tipo

Rango

Descripción

use_doc_orientation_classify

Booleano

{True, False}

Clasificación de orientación del documento completo

use_doc_unwarping

Booleano

{True, False}

Corrección de deformación/curvatura

textline_orientation

Booleano

{True, False}

Clasificación de orientación por línea de texto

text_det_thresh

Continuo

[0.0, 0.7]

Umbral de probabilidad para píxeles de texto

text_det_box_thresh

Continuo

[0.0, 0.7]

Umbral de confianza para cajas detectadas

text_det_unclip_ratio

Fijo

0.0

Coeficiente de expansión (no explorado)

text_rec_score_thresh

Continuo

[0.0, 0.7]

Umbral de confianza de reconocimiento

Fuente: Elaboración propia.

 

@@ -5274,7 +5350,7 @@ docker compose -f docker-compose.tuning.doctr.yml down

1.   Parámetros booleanos completos: Los tres parámetros de preprocesamiento se exploran completamente para identificar cuáles son necesarios para documentos digitales.

Configuración de Ray Tune

Se configuró Ray Tune con OptunaSearch como algoritmo de búsqueda, optimizando CER en 64 trials con 2 ejecuciones concurrentes. La implementación está disponible en src/raytune/raytune_ocr.py (ver Anexo A).

-

Tabla 28. Parámetros de configuración de Ray Tune.

+

Tabla 31. Parámetros de configuración de Ray Tune.

Parámetro

Valor

Justificación

Métrica objetivo

CER

Métrica estándar para OCR

Modo

min

Minimizar tasa de error

Algoritmo

OptunaSearch (TPE)

Eficiente para espacios mixtos

Número de trials

64

Balance entre exploración y tiempo

Trials concurrentes

2

Limitado por memoria disponible

Fuente: Elaboración propia.

 

@@ -5287,57 +5363,57 @@ docker compose -f docker-compose.tuning.doctr.yml down

Resultados de la Optimización

Ejecución del Experimento

El experimento se ejecutó exitosamente con los siguientes resultados globales:

-

Tabla 29. Resumen de la ejecución del experimento.

+

Tabla 32. Resumen de la ejecución del experimento.

Métrica

Valor

Trials completados

64/64

Trials fallidos

0

Tiempo total

~6.4 horas

Tiempo medio por trial

367.72 segundos

Páginas procesadas

320 (64 trials × 5 páginas)

Fuente: Elaboración propia.

 

Estadísticas Descriptivas

-

Del archivo CSV de resultados (raytune_paddle_subproc_results_20251207_192320.csv):

-

Tabla 30. Estadísticas descriptivas de los 64 trials.

-

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% (mediana)

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

+

Del archivo CSV de resultados (src/results/raytune_paddle_results_20260119_122609.csv):

+

Tabla 33. Estadísticas descriptivas de los 64 trials.

+

Estadística

CER

WER

Tiempo/Página (s)

count

64

64

64

mean

2.30%

9.25%

0.84

std

2.20%

1.78%

0.53

min

0.79%

6.80%

0.56

50% (mediana)

0.87%

8.39%

0.59

max

7.30%

13.20%

2.22

Fuente: Elaboración propia.

 

Observaciones:

-

1.   Alta varianza en CER: La desviación estándar (11.03%) es mayor que la media (5.25%), indicando una distribución muy dispersa con algunos valores extremos.

-

1.   Mediana vs Media: La mediana del CER (1.23%) es mucho menor que la media (5.25%), confirmando una distribución sesgada hacia valores bajos con outliers altos.

-

1.   Tiempo consistente: El tiempo de ejecución es muy estable (std = 1.57 s/página), indicando que las configuraciones de hiperparámetros no afectan significativamente el tiempo de inferencia.

+

1.   Baja varianza en CER: La desviación estándar (2.20%) es similar a la media (2.30%), indicando una distribución relativamente consistente sin valores extremos catastróficos.

+

1.   Mediana vs Media: La mediana del CER (0.87%) es menor que la media (2.30%), confirmando una distribución ligeramente sesgada hacia valores bajos.

+

1.   Velocidad GPU: El tiempo de ejecución promedio es de 0.84 s/página, lo que representa una aceleración significativa respecto a la ejecución en CPU (~69 s/página, 82x más rápido).

Distribución de Resultados

-

Tabla 31. Distribución de trials por rango de CER.

-

Rango CER

Número de trials

Porcentaje

< 2%

43

67.2%

2% - 5%

7

10.9%

5% - 10%

2

3.1%

10% - 20%

5

7.8%

> 20%

7

10.9%

+

Tabla 34. Distribución de trials por rango de CER.

+

Rango CER

Número de trials

Porcentaje

< 2%

43

67.2%

2% - 5%

10

15.6%

5% - 10%

11

17.2%

> 10%

0

0.0%

Fuente: Elaboración propia.

 

-

La mayoría de trials (67.2%) alcanzaron CER < 2%, cumpliendo el objetivo establecido. Sin embargo, un 10.9% de trials presentaron fallos catastróficos (CER > 20%).

+

La mayoría de trials (67.2%) alcanzaron CER < 2%, cumpliendo el objetivo establecido. Ningún trial presentó fallos catastróficos (CER > 10%), demostrando la estabilidad de la optimización con GPU.

Mejor Configuración Encontrada

La configuración que minimizó el CER fue:

-

Best CER: 0.011535 (1.15%)
-Best WER: 0.098902 (9.89%)
+
Best CER: 0.007884 (0.79%)
+Best WER: 0.077848 (7.78%)
 
 Configuración óptima:
   textline_orientation: True
-  use_doc_orientation_classify: False
+  use_doc_orientation_classify: True
   use_doc_unwarping: False
-  text_det_thresh: 0.4690
-  text_det_box_thresh: 0.5412
+  text_det_thresh: 0.0462
+  text_det_box_thresh: 0.4862
   text_det_unclip_ratio: 0.0
-  text_rec_score_thresh: 0.6350

-
Tabla 32. Configuración óptima identificada.

-
Parámetro
Valor óptimo
Valor por defecto
Cambio
textline_orientation
True
False
Activado
use_doc_orientation_classify
False
False
Sin cambio
use_doc_unwarping
False
False
Sin cambio
text_det_thresh
0.4690
0.3
+0.169
text_det_box_thresh
0.5412
0.6
-0.059
text_det_unclip_ratio
0.0
1.5
-1.5 (fijado)
text_rec_score_thresh
0.6350
0.5
+0.135

+  text_rec_score_thresh: 0.5658

+

Tabla 35. Configuración óptima identificada.

+

Parámetro

Valor óptimo

Valor por defecto

Cambio

textline_orientation

True

False

Activado

use_doc_orientation_classify

True

False

Activado

use_doc_unwarping

False

False

Sin cambio

text_det_thresh

0.0462

0.3

-0.254

text_det_box_thresh

0.4862

0.6

-0.114

text_det_unclip_ratio

0.0

1.5

-1.5 (fijado)

text_rec_score_thresh

0.5658

0.5

+0.066

Fuente: Elaboración propia.

 

Análisis de Correlación

Se calculó la correlación de Pearson entre los parámetros continuos y las métricas de error:

-

Tabla 33. Correlación de parámetros con CER.

+

Tabla 36. Correlación de parámetros con CER.

Parámetro

Correlación con CER

Interpretación

text_det_thresh

-0.523

Correlación moderada negativa

text_det_box_thresh

+0.226

Correlación débil positiva

text_rec_score_thresh

-0.161

Correlación débil negativa

text_det_unclip_ratio

NaN

Varianza cero (valor fijo)

Fuente: Elaboración propia.

 

-

Tabla 34. Correlación de parámetros con WER.

+

Tabla 37. Correlación de parámetros con WER.

Parámetro

Correlación con WER

Interpretación

text_det_thresh

-0.521

Correlación moderada negativa

text_det_box_thresh

+0.227

Correlación débil positiva

text_rec_score_thresh

-0.173

Correlación débil negativa

Fuente: Elaboración propia.

 

Hallazgo clave: El parámetro text_det_thresh muestra la correlación más fuerte (-0.52 con ambas métricas), indicando que valores más altos de este umbral tienden a reducir el error. Este umbral controla qué píxeles se consideran "texto" en el mapa de probabilidad del detector.

Impacto del Parámetro textline_orientation

El parámetro booleano textline_orientation demostró tener el mayor impacto en el rendimiento:

-

Tabla 35. Impacto del parámetro textline_orientation.

+

Tabla 38. Impacto del parámetro textline_orientation.

textline_orientation

CER Medio

CER Std

WER Medio

N trials

True

3.76%

7.12%

12.73%

32

False

12.40%

14.93%

21.71%

32

Fuente: Elaboración propia.

 

@@ -5345,15 +5421,15 @@ Configuración óptima:

1.   Reducción del CER: Con textline_orientation=True, el CER medio es 3.3 veces menor (3.76% vs 12.40%).

1.   Menor varianza: La desviación estándar también se reduce significativamente (7.12% vs 14.93%), indicando resultados más consistentes.

1.   Reducción del CER: 69.7% cuando se habilita la clasificación de orientación de línea.

-

Figura 6. Impacto de textline_orientation en CER

-

Impacto de textline_orientation en CER

+

Figura 9. Impacto de textline_orientation en CER

+

Impacto de textline_orientation en CER

Fuente: Elaboración propia.

 

Explicación técnica:

El parámetro textline_orientation activa un clasificador que determina la orientación de cada línea de texto detectada. Para documentos con layouts mixtos (tablas, encabezados laterales, direcciones postales), este clasificador asegura que el texto se lea en el orden correcto, evitando la mezcla de líneas de diferentes columnas o secciones.

Análisis de Fallos Catastróficos

Los trials con CER muy alto (>20%) presentaron patrones específicos:

-

Tabla 36. Características de trials con fallos catastróficos.

+

Tabla 39. Características de trials con fallos catastróficos.

Trial

CER

text_det_thresh

textline_orientation

Diagnóstico

#47

51.61%

0.017

True

Umbral muy bajo

#23

43.29%

0.042

False

Umbral bajo + sin orientación

#12

38.76%

0.089

False

Umbral bajo + sin orientación

#56

35.12%

0.023

False

Umbral muy bajo + sin orientación

Fuente: Elaboración propia.

 

@@ -5364,71 +5440,74 @@ Configuración óptima:

Recomendación: Evitar text_det_thresh < 0.1 en cualquier configuración.

Comparación Baseline vs Optimizado

Evaluación sobre Dataset Completo

-

La configuración óptima identificada se evaluó sobre el dataset completo de 24 páginas, comparando con la configuración baseline (valores por defecto de PaddleOCR). Los parámetros optimizados más relevantes fueron: textline_orientation=True, text_det_thresh=0.4690, text_det_box_thresh=0.5412, y text_rec_score_thresh=0.6350.

-

Tabla 37. Comparación baseline vs optimizado (24 páginas).

-

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%

+

La configuración óptima identificada se evaluó sobre el dataset completo de 45 páginas, comparando con la configuración baseline (valores por defecto de PaddleOCR). Los parámetros optimizados más relevantes fueron: textline_orientation=True, use_doc_orientation_classify=True, text_det_thresh=0.0462, text_det_box_thresh=0.4862, y text_rec_score_thresh=0.5658.

+

Tabla 40. Comparación baseline vs optimizado (45 páginas).

+

Modelo

CER

Precisión Caracteres

WER

Precisión Palabras

PaddleOCR (Baseline)

8.85%

91.15%

13.05%

86.95%

PaddleOCR-HyperAdjust

7.72%

92.28%

11.40%

88.60%

Fuente: Elaboración propia.

 

+

Nota sobre generalización: El mejor trial individual (5 páginas) alcanzó un CER de 0.79%, cumpliendo el objetivo de CER < 2%. Sin embargo, al aplicar la configuración al dataset completo de 45 páginas, el CER aumentó a 7.72%, evidenciando sobreajuste al subconjunto de entrenamiento. Esta diferencia es un hallazgo importante que se discute en la sección de análisis.

Métricas de Mejora

-

Tabla 38. Análisis cuantitativo de la mejora.

-

Forma de Medición

CER

WER

Valor baseline

7.78%

14.94%

Valor optimizado

1.49%

7.62%

Mejora absoluta

-6.29 pp

-7.32 pp

Reducción relativa del error

80.9%

49.0%

Factor de mejora

5.2×

2.0×

+

Tabla 41. Análisis cuantitativo de la mejora.

+

Forma de Medición

CER

WER

Valor baseline

8.85%

13.05%

Valor optimizado

7.72%

11.40%

Mejora absoluta

-1.13 pp

-1.65 pp

Reducción relativa del error

12.8%

12.6%

Factor de mejora

1.15×

1.14×

Mejor trial (5 páginas)

0.79%

7.78%

Fuente: Elaboración propia.

 

-

Figura 7. Reducción de errores: Baseline vs Optimizado

-

Reducción de errores: Baseline vs Optimizado

+

Figura 10. Reducción de errores: Baseline vs Optimizado (45 páginas)

+

Reducción de errores: Baseline vs Optimizado (45 páginas)

Fuente: Elaboración propia.

 

-

Leyenda: CER = Character Error Rate, WER = Word Error Rate. Baseline = configuración por defecto de PaddleOCR. Optimizado = configuración encontrada por Ray Tune.

+

Leyenda: CER = Character Error Rate, WER = Word Error Rate. Baseline = configuración por defecto de PaddleOCR. Optimizado = configuración encontrada por Ray Tune. Los valores corresponden al dataset completo de 45 páginas.

Impacto Práctico

En un documento típico de 10,000 caracteres:

-

Tabla 39. En un documento típico de 10,000 caracteres

-

Configuración

Caracteres con error

Palabras con error*

Baseline

~778

~225

Optimizada

~149

~115

Reducción

629 menos

110 menos

+

Tabla 42. En un documento típico de 10,000 caracteres

+

Configuración

Caracteres con error

Palabras con error*

Baseline

~885

~196

Optimizada (full dataset)

~772

~171

Optimizada (mejor trial)

~79

~117

Reducción (full dataset)

113 menos

25 menos

Fuente: Elaboración propia.

 

*Asumiendo longitud media de palabra = 6.6 caracteres en español.

-

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

+

Interpretación:

+

"La optimización de hiperparámetros logró una mejora del 12.8% en el CER sobre el dataset completo de 45 páginas. Aunque esta mejora es más modesta que la observada en los trials individuales (donde se alcanzó 0.79% CER), demuestra el valor de la optimización sistemática. La diferencia entre el mejor trial (0.79%) y el resultado en dataset completo (7.72%) revela un fenómeno de sobreajuste al subconjunto de 5 páginas usado para evaluación."

Tiempo de Ejecución

-

Tabla 40. Métricas de tiempo del experimento.

-

Métrica

Valor

Tiempo total del experimento

~6.4 horas

Tiempo medio por trial

347.61 segundos (~5.8 min)

Tiempo medio por página

69.42 segundos

Variabilidad (std)

1.57 segundos/página

Páginas procesadas totales

320

+

Tabla 43. Métricas de tiempo del experimento (GPU).

+

Métrica

Valor

Tiempo total del experimento

~1.5 horas

Tiempo medio por trial

~4.2 segundos

Tiempo medio por página

0.84 segundos

Variabilidad (std)

0.53 segundos/página

Páginas procesadas totales

320

Fuente: Elaboración propia.

 

Observaciones:

-

1.   El tiempo por página (~70 segundos) corresponde a ejecución en CPU sin aceleración.

-

2.   La variabilidad del tiempo es muy baja, indicando que los hiperparámetros no afectan significativamente la velocidad.

-

3.   Con GPU, los tiempos serían 10-50× menores según benchmarks de PaddleOCR.

+

1.   El tiempo por página (~0.84 segundos) corresponde a ejecución con GPU (RTX 3060).

+

2.   La variabilidad del tiempo es moderada (std = 0.53 s/página), con algunos trials más lentos debido a configuraciones con módulos de preprocesamiento activos.

+

3.   En comparación, la ejecución en CPU requiere ~69 segundos/página (82× más lento), lo que justifica el uso de GPU para optimización y producción.

Resumen de la Sección

Esta sección ha presentado:

-

1.   Configuración del experimento: Arquitectura Docker Compose, dataset extendido, espacio de búsqueda de 7 dimensiones

+

1.   Configuración del experimento: Arquitectura Docker Compose, dataset de 45 páginas, espacio de búsqueda de 7 dimensiones, ejecución con GPU RTX 3060

1.   Resultados estadísticos:

-

- CER medio: 5.25% (std: 11.03%) - CER mínimo: 1.15% - 67.2% de trials con CER < 2%

+

- CER medio: 2.30% (std: 2.20%) - CER mínimo (mejor trial): 0.79% - 67.2% de trials con CER < 2%

1.   Hallazgos clave:

-

- textline_orientation=True reduce CER en 69.7% - text_det_thresh tiene correlación -0.52 con CER - Valores de text_det_thresh < 0.1 causan fallos catastróficos

-

1.   Mejora final: CER reducido de 7.78% a 1.49% (reducción del 80.9%)

+

- textline_orientation=True y use_doc_orientation_classify=True son críticos - text_det_thresh bajo (0.0462) optimiza la detección de texto - Ningún trial presentó fallos catastróficos (CER > 10%)

+

1.   Mejora en dataset completo: CER reducido de 8.85% a 7.72% (reducción del 12.8%)

+

1.   Observación sobre generalización: El mejor trial (0.79%) no generalizó completamente al dataset completo (7.72%), evidenciando sobreajuste al subconjunto de 5 páginas

Fuentes de datos:

·     src/run_tuning.py: Script principal de optimización

·     src/raytune_ocr.py: Librería de utilidades Ray Tune

-

·     src/results/: Resultados CSV de los trials

+

·     src/results/raytune_paddle_results_20260119_122609.csv: Resultados CSV de los 64 trials

Discusión y análisis de resultados

Introducción

Esta sección presenta un análisis consolidado de los resultados obtenidos en las fases de benchmark comparativo y optimización de hiperparámetros. Se discuten las implicaciones prácticas, se evalúa el cumplimiento de los objetivos planteados y se identifican las limitaciones del estudio.

Resumen Consolidado de Resultados

Progresión del Rendimiento

-

Tabla 41. Evolución del rendimiento a través del estudio.

-

Fase

Configuración

CER

Mejora vs anterior

Benchmark inicial

Baseline (5 páginas)

~5-6%

-

Optimización (mejor trial)

Optimizada (5 páginas)

1.15%

~80%

Validación final

Optimizada (24 páginas)

1.49%

-

+

Tabla 44. Evolución del rendimiento a través del estudio.

+

Fase

Configuración

CER

Mejora vs anterior

Benchmark inicial

Baseline (5 páginas)

~7-8%

-

Optimización (mejor trial)

Optimizada (5 páginas)

0.79%

~90% vs baseline

Validación final

Optimizada (45 páginas)

7.72%

12.8% vs baseline

Fuente: Elaboración propia.

 

-

El incremento del CER de 1.15% (5 páginas) a 1.49% (24 páginas) es esperado debido a la mayor diversidad de layouts en el dataset completo.

+

El incremento del CER de 0.79% (5 páginas) a 7.72% (45 páginas) evidencia sobreajuste al subconjunto de optimización. Este fenómeno es esperado cuando se optimiza sobre un subconjunto pequeño y se valida sobre el dataset completo con mayor diversidad de layouts.

Comparación con Objetivo

-

Tabla 42. Verificación del objetivo general.

-

Aspecto

Objetivo

Resultado

Cumplimiento

Métrica

CER

CER

✓

Umbral

< 2%

1.49%

✓

Método

Sin fine-tuning

Solo hiperparámetros

✓

Hardware

Sin GPU

CPU only

✓

+

Tabla 45. Verificación del objetivo general.

+

Aspecto

Objetivo

Resultado (trial)

Resultado (full)

Cumplimiento

Métrica

CER

CER

CER

✓

Umbral

< 2%

0.79%

7.72%

Parcial

Método

Sin fine-tuning

Solo hiperparámetros

Solo hiperparámetros

✓

Hardware

GPU

RTX 3060

RTX 3060

✓

Fuente: Elaboración propia.

 

+

Análisis del cumplimiento: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%), demostrando que la optimización de hiperparámetros puede alcanzar la precisión objetivo. Sin embargo, la validación sobre el dataset completo (7.72%) muestra que la generalización requiere trabajo adicional, como un subconjunto de optimización más representativo o técnicas de regularización.

Análisis Detallado de Hiperparámetros

Jerarquía de Importancia

-

Basándose en el análisis de correlación y el impacto observado:

-

Tabla 43. Ranking de importancia de hiperparámetros.

-

Rank

Parámetro

Impacto

Evidencia

1

textline_orientation

Crítico

Reduce CER 69.7%

2

text_det_thresh

Alto

Correlación -0.52

3

text_rec_score_thresh

Medio

Correlación -0.16

4

text_det_box_thresh

Bajo

Correlación +0.23

5

use_doc_orientation_classify

Nulo

Sin mejora

6

use_doc_unwarping

Nulo

Sin mejora

+

Basándose en el análisis de los resultados de optimización:

+

Tabla 46. Ranking de importancia de hiperparámetros.

+

Rank

Parámetro

Impacto

Evidencia

1

textline_orientation

Crítico

Presente en todos los mejores trials

2

use_doc_orientation_classify

Alto

Activado en configuración óptima

3

text_det_thresh

Alto

Valor óptimo bajo (0.0462)

4

text_det_box_thresh

Medio

Moderado (0.4862)

5

text_rec_score_thresh

Medio

Moderado (0.5658)

6

use_doc_unwarping

Nulo

Desactivado en configuración óptima

Fuente: Elaboración propia.

 

Análisis del Parámetro textline_orientation

@@ -5441,38 +5520,41 @@ Configuración óptima:

Recomendación: Siempre activar textline_orientation=True para documentos estructurados.

Análisis del Parámetro text_det_thresh

Comportamiento observado:

-

Tabla 44. Comportamiento observado

-

Rango

CER típico

Comportamiento

0.0 - 0.1

>20%

Fallos catastróficos

0.1 - 0.3

5-15%

Rendimiento pobre

0.3 - 0.5

1-5%

Rendimiento óptimo

0.5 - 0.7

2-8%

Rendimiento aceptable

+

Tabla 47. Comportamiento observado

+

Rango

CER típico

Comportamiento

0.0 - 0.1

1-3%

Detecta más texto, incluyendo bordes

0.1 - 0.3

2-5%

Rendimiento variable

0.3 - 0.5

3-7%

Balance precisión/recall

0.5 - 0.7

4-7%

Más conservador

Fuente: Elaboración propia.

 

Interpretación:

-

·     Valores muy bajos (< 0.1) incluyen ruido y artefactos como "texto"

-

·     Valores muy altos (> 0.6) filtran texto legítimo de bajo contraste

-

·     El rango óptimo (0.3-0.5) balancea precisión y recall de detección

-

Valor óptimo encontrado: 0.4690

-

Parámetros sin Impacto Significativo

-

use_doc_orientation_classify y use_doc_unwarping:

-

Estos módulos están diseñados para:

+

·     En ejecución GPU con modelos Mobile, valores bajos de text_det_thresh funcionan bien

+

·     El valor óptimo (0.0462) indica que una detección más sensible beneficia el rendimiento

+

·     A diferencia de CPU, no se observaron fallos catastróficos con valores bajos

+

Valor óptimo encontrado: 0.0462

+

Análisis de Parámetros de Preprocesamiento

+

use_doc_orientation_classify:

+

En la configuración óptima GPU, este parámetro está activado (True), a diferencia de lo observado en experimentos anteriores. Esto sugiere que la clasificación de orientación del documento puede beneficiar incluso documentos digitales cuando se combina con textline_orientation=True.

+

use_doc_unwarping:

+

Este módulo permanece desactivado en la configuración óptima. Está diseñado para:

·     Documentos escaneados con rotación

·     Fotografías de documentos con perspectiva

·     Documentos curvados o deformados

-

Para documentos PDF digitales como los evaluados, estos módulos son innecesarios e incluso pueden introducir artefactos. Su desactivación reduce el tiempo de procesamiento sin pérdida de precisión.

+

Para documentos PDF digitales como los evaluados, este módulo es innecesario y puede introducir artefactos.

Análisis de Casos de Fallo

Clasificación de Errores

-

Tabla 45. Tipología de errores observados.

+

Tabla 48. Tipología de errores observados.

Tipo de error

Frecuencia

Ejemplo

Causa probable

Pérdida de acentos

Alta

más → mas

Modelo de reconocimiento

Duplicación de caracteres

Media

titulación → titulacióon

Solapamiento de detecciones

Confusión de puntuación

Media

¿ → ?

Caracteres similares

Pérdida de eñe

Baja

año → ano

Modelo de reconocimiento

Texto desordenado

Variable

Mezcla de líneas

Fallo de orientación

Fuente: Elaboración propia.

 

Patrones de Fallo por Tipo de Contenido

-

Tabla 46. Tasa de error por tipo de contenido.

+

Tabla 49. Tasa de error por tipo de contenido.

Tipo de contenido

CER estimado

Factor de riesgo

Párrafos de texto

~1%

Bajo

Listas numeradas

~2%

Medio

Tablas simples

~3%

Medio

Encabezados + pie de página

~2%

Medio

Tablas complejas

~5%

Alto

Texto en columnas

~4%

Alto

Fuente: Elaboración propia.

 

Comparación con Objetivos Específicos

-

Tabla 47. Cumplimiento de objetivos específicos.

-

Objetivo

Descripción

Resultado

Estado

OE1

Comparar soluciones OCR

EasyOCR, PaddleOCR, DocTR evaluados; PaddleOCR seleccionado

✓ Cumplido

OE2

Preparar dataset de evaluación

24 páginas con ground truth

✓ Cumplido

OE3

Identificar hiperparámetros críticos

textline_orientation y text_det_thresh identificados

✓ Cumplido

OE4

Optimizar con Ray Tune (≥50 trials)

64 trials ejecutados

✓ Cumplido

OE5

Validar configuración optimizada

CER: 7.78% → 1.49% documentado

✓ Cumplido

+

Tabla 50. Cumplimiento de objetivos específicos.

+

Objetivo

Descripción

Resultado

Estado

OE1

Comparar soluciones OCR

EasyOCR, PaddleOCR, DocTR evaluados; PaddleOCR seleccionado

✓ Cumplido

OE2

Preparar dataset de evaluación

45 páginas con ground truth

✓ Cumplido

OE3

Identificar hiperparámetros críticos

textline_orientation, use_doc_orientation_classify, text_det_thresh identificados

✓ Cumplido

OE4

Optimizar con Ray Tune (≥50 trials)

64 trials ejecutados con GPU

✓ Cumplido

OE5

Validar configuración optimizada

CER: 8.85% → 7.72% (dataset), 0.79% (mejor trial)

✓ Parcial

Fuente: Elaboración propia.

 

+

Nota sobre OE5: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%). La validación sobre el dataset completo (7.72%) muestra que la generalización requiere mayor trabajo, identificándose como línea de trabajo futuro.

Limitaciones del Estudio

Limitaciones de Generalización

1.   Tipo de documento único: Solo se evaluaron documentos académicos de UNIR. La configuración óptima puede no ser transferible a otros tipos de documentos (facturas, formularios, contratos).

@@ -5480,25 +5562,26 @@ Configuración óptima:

1.   Formato único: Solo se evaluaron PDFs digitales. Documentos escaneados o fotografías de documentos podrían beneficiarse de diferentes configuraciones.

Limitaciones Metodológicas

1.   Ground truth automático: El texto de referencia se extrajo programáticamente del PDF, lo cual puede introducir errores en layouts complejos donde el orden de lectura no es evidente.

-

1.   Tamaño del dataset: 24 páginas es un dataset pequeño. Un dataset más amplio proporcionaría estimaciones más robustas.

+

1.   Tamaño del dataset: 45 páginas es un dataset limitado. Un dataset más amplio proporcionaría estimaciones más robustas.

1.   Parámetro fijo: text_det_unclip_ratio se mantuvo en 0.0 durante todo el experimento. Explorar este parámetro podría revelar mejoras adicionales.

-

1.   Ejecución en CPU: Los tiempos reportados corresponden a ejecución en CPU. El comportamiento con GPU podría diferir.

+

1.   Subconjunto de ajuste limitado: El ajuste de hiperparámetros se realizó sobre 5 páginas (páginas 5-10), lo que contribuyó al sobreajuste observado en la validación del dataset completo.

Limitaciones de Validación

1.   Sin validación cruzada: No se realizó validación cruzada sobre diferentes subconjuntos del dataset.

1.   Sin test set independiente: El dataset de validación final se solapaba parcialmente con el de optimización.

Implicaciones Prácticas

Guía de Configuración Recomendada

Para documentos académicos en español similares a los evaluados:

-

Tabla 48. Configuración recomendada para PaddleOCR.

-

Parámetro

Valor

Prioridad

Justificación

textline_orientation

True

Obligatorio

Reduce CER en 69.7%

text_det_thresh

0.45 (rango: 0.4-0.5)

Recomendado

Correlación fuerte con CER

text_rec_score_thresh

0.6 (rango: 0.5-0.7)

Recomendado

Filtra reconocimientos poco confiables

text_det_box_thresh

0.55 (rango: 0.5-0.6)

Opcional

Impacto moderado

use_doc_orientation_classify

False

No recomendado

Innecesario para PDFs digitales

use_doc_unwarping

False

No recomendado

Innecesario para PDFs digitales

+

Tabla 51. Configuración recomendada para PaddleOCR con GPU.

+

Parámetro

Valor

Prioridad

Justificación

textline_orientation

True

Obligatorio

Crítico para layouts complejos

use_doc_orientation_classify

True

Recomendado

Mejora orientación de documento

text_det_thresh

0.05 (rango: 0.04-0.10)

Recomendado

Detección sensible beneficia resultados

text_det_box_thresh

0.49 (rango: 0.4-0.6)

Recomendado

Balance de confianza

text_rec_score_thresh

0.57 (rango: 0.5-0.7)

Opcional

Filtra reconocimientos poco confiables

use_doc_unwarping

False

No recomendado

Innecesario para PDFs digitales

Fuente: Elaboración propia.

 

Cuándo Aplicar Esta Metodología

La optimización de hiperparámetros es recomendable cuando:

-

1.   Sin GPU disponible: El fine-tuning requiere GPU; la optimización de hiperparámetros no.

-

1.   Modelo preentrenado adecuado: El modelo ya soporta el idioma objetivo.

+

1.   GPU disponible: Acelera significativamente la exploración del espacio de hiperparámetros (82× más rápido que CPU).

+

1.   Modelo preentrenado adecuado: El modelo ya soporta el idioma objetivo (como PaddleOCR para español).

1.   Dominio específico: Se busca optimizar para un tipo de documento particular.

1.   Mejora incremental: El rendimiento baseline es aceptable pero mejorable.

+

1.   Sin datos de entrenamiento: No se dispone de datasets etiquetados para fine-tuning.

Cuándo NO Aplicar Esta Metodología

La optimización de hiperparámetros puede ser insuficiente cuando:

1.   Idioma no soportado: El modelo no incluye el idioma en su vocabulario.

@@ -5511,87 +5594,98 @@ Configuración óptima:

·     Evaluación de EasyOCR, PaddleOCR y DocTR

·     Selección de PaddleOCR por su configurabilidad

Desarrollo de la comparativa:

-

·     64 trials de Ray Tune con Optuna

-

·     Identificación de textline_orientation y text_det_thresh como críticos

-

·     CER mínimo alcanzado: 1.15%

+

·     64 trials de Ray Tune con Optuna usando GPU RTX 3060

+

·     Identificación de textline_orientation, use_doc_orientation_classify y text_det_thresh como críticos

+

·     CER mínimo alcanzado en trial individual: 0.79%

Discusión y análisis:

-

·     Mejora del CER de 7.78% a 1.49% (reducción del 80.9%)

-

·     Cumplimiento de todos los objetivos específicos

-

·     Identificación de limitaciones y recomendaciones prácticas

-

Resultado principal: Se logró alcanzar el objetivo de CER < 2% mediante optimización de hiperparámetros, sin requerir fine-tuning ni recursos GPU.

+

·     Mejora del CER en dataset completo de 8.85% a 7.72% (reducción del 12.8%)

+

·     Mejor trial: 0.79% CER (cumple objetivo CER < 2%)

+

·     Identificación de sobreajuste y recomendaciones prácticas

+

Resultados principales:

+

·     El objetivo de CER < 2% se cumple en el mejor trial (0.79%)

+

·     La generalización al dataset completo (7.72%) revela sobreajuste que requiere trabajo futuro

+

·     La optimización de hiperparámetros con GPU es viable y eficiente (82× más rápido que CPU)

Fuentes de datos:

·     src/run_tuning.py: Script principal de optimización

-

·     src/results/: Resultados CSV de los trials

+

·     src/results/raytune_paddle_results_20260119_122609.csv: Resultados CSV de PaddleOCR

+

·     src/results/raytune_easyocr_results_20260119_120204.csv: Resultados CSV de EasyOCR

+

·     src/results/raytune_doctr_results_20260119_121445.csv: Resultados CSV de DocTR

Imágenes Docker:

·     seryus.ddns.net/unir/paddle-ocr-gpu: PaddleOCR con soporte GPU

·     seryus.ddns.net/unir/easyocr-gpu: EasyOCR con soporte GPU

·     seryus.ddns.net/unir/doctr-gpu: DocTR con soporte GPU

-

Validación con Aceleración GPU

-

Para evaluar la viabilidad práctica del enfoque optimizado en escenarios de producción, se realizó una validación adicional utilizando aceleración GPU. Esta fase complementa los experimentos en CPU presentados anteriormente y demuestra la aplicabilidad del método cuando se dispone de hardware con capacidad de procesamiento paralelo.

+

Comparativa de Rendimiento CPU vs GPU

+

Esta sección presenta la comparación de rendimiento entre ejecución en CPU y GPU, justificando la elección de GPU para el experimento principal y demostrando el impacto práctico de la aceleración por hardware.

Configuración del Entorno GPU

-

Tabla 49. Especificaciones del entorno de validación GPU.

+

Tabla 52. Especificaciones del entorno GPU utilizado.

Componente

Especificación

GPU

NVIDIA GeForce RTX 3060 Laptop

VRAM

5.66 GB

CUDA

12.4

Sistema Operativo

Ubuntu 24.04.3 LTS

Kernel

6.14.0-37-generic

Fuente: Elaboración propia.

 

-

El entorno de validación representa hardware de consumo típico para desarrollo de aplicaciones de machine learning, permitiendo evaluar el rendimiento en condiciones realistas de despliegue.

+

Este hardware representa configuración típica de desarrollo, permitiendo evaluar el rendimiento en condiciones realistas de despliegue.

Comparación CPU vs GPU

-

Se evaluó el tiempo de procesamiento utilizando la configuración optimizada identificada en la fase anterior, comparando el rendimiento entre CPU y GPU.

-

Tabla 50. Rendimiento comparativo CPU vs GPU.

-

Métrica

CPU

GPU (RTX 3060)

Factor de Aceleración

Tiempo/Página

69.4s

0.55s

126x

Dataset completo (45 páginas)

~52 min

~25 seg

126x

+

Se comparó el tiempo de procesamiento entre CPU y GPU utilizando los datos de src/raytune_paddle_subproc_results_20251207_192320.csv (CPU) y src/results/raytune_paddle_results_20260119_122609.csv (GPU).

+

Tabla 53. Rendimiento comparativo CPU vs GPU.

+

Métrica

CPU

GPU (RTX 3060)

Factor de Aceleración

Tiempo/Página (promedio)

69.4s

0.84s

82x

Dataset completo (45 páginas)

~52 min

~38 seg

82x

64 trials × 5 páginas

~6.4 horas

~1.5 horas

4.3x

Fuente: Elaboración propia.

 

-

La aceleración de 126x obtenida con GPU transforma la aplicabilidad práctica del sistema. Mientras que el procesamiento en CPU limita el uso a escenarios de procesamiento por lotes sin restricciones de tiempo, la velocidad con GPU habilita casos de uso interactivos y de tiempo real.

+

La aceleración de 82× obtenida con GPU transforma la viabilidad del enfoque:

+

·     Optimización en CPU (6.4 horas): Viable pero lento para iteraciones rápidas

+

·     Optimización en GPU (1.5 horas): Permite explorar más configuraciones y realizar múltiples experimentos

+

·     Producción con GPU (0.84s/página): Habilita procesamiento en tiempo real

Comparación de Modelos PaddleOCR

PaddleOCR ofrece dos variantes de modelos: Mobile (optimizados para dispositivos con recursos limitados) y Server (mayor precisión a costa de mayor consumo de memoria). Se evaluó la viabilidad de ambas variantes en el hardware disponible.

-

Tabla 51. Comparación de modelos Mobile vs Server en RTX 3060.

+

Tabla 54. Comparación de modelos Mobile vs Server en RTX 3060.

Modelo

VRAM Requerida

Resultado

Recomendación

PP-OCRv5 Mobile

0.06 GB

Funciona correctamente

✓ Recomendado

PP-OCRv5 Server

5.3 GB

OOM en página 2

✗ Requiere >8 GB VRAM

Fuente: Elaboración propia.

 

Los modelos Server, a pesar de ofrecer potencialmente mayor precisión, resultan inviables en hardware con VRAM limitada (≤6 GB) debido a errores de memoria (Out of Memory). Los modelos Mobile, con un consumo de memoria 88 veces menor, funcionan de manera estable y ofrecen rendimiento suficiente para el caso de uso evaluado.

Conclusiones de la Validación GPU

La validación con aceleración GPU permite extraer las siguientes conclusiones:

-

1.   Aceleración significativa: La GPU proporciona una aceleración de 126x sobre CPU, haciendo viable el procesamiento en tiempo real para aplicaciones interactivas.

+

1.   Aceleración significativa: La GPU proporciona una aceleración de 82× sobre CPU, haciendo viable el procesamiento en tiempo real para aplicaciones interactivas.

1.   Modelos Mobile recomendados: Para hardware con VRAM limitada (≤6 GB), los modelos Mobile de PP-OCRv5 ofrecen el mejor balance entre precisión y recursos, funcionando de manera estable sin errores de memoria.

1.   Viabilidad práctica: Con GPU, el procesamiento de un documento completo (45 páginas) toma menos de 30 segundos, validando la aplicabilidad en entornos de producción donde el tiempo de respuesta es crítico.

1.   Escalabilidad: La arquitectura de microservicios dockerizados utilizada para la validación GPU facilita el despliegue horizontal, permitiendo escalar el procesamiento según demanda.

-

Esta validación demuestra que la configuración optimizada mediante Ray Tune no solo mejora la precisión (CER: 7.78% → 1.49%) sino que, combinada con aceleración GPU, resulta prácticamente aplicable en escenarios de producción real.

5.   Conclusiones y trabajo futuro

Este capítulo resume las principales conclusiones del trabajo, evalúa el grado de cumplimiento de los objetivos planteados y propone líneas de trabajo futuro que permitirían ampliar y profundizar los resultados obtenidos.

Conclusiones

Conclusiones Generales

-

Este Trabajo Fin de Máster ha demostrado que es posible mejorar significativamente el rendimiento de sistemas OCR preentrenados mediante optimización sistemática de hiperparámetros, sin requerir fine-tuning ni recursos GPU dedicados.

-

El objetivo principal del trabajo era alcanzar un CER inferior al 2% en documentos académicos en español. Los resultados obtenidos confirman el cumplimiento de este objetivo:

-

Tabla 52. Cumplimiento del objetivo de CER.

-

Métrica

Objetivo

Resultado

CER

< 2%

1.49%

+

Este Trabajo Fin de Máster ha demostrado que es posible mejorar significativamente el rendimiento de sistemas OCR preentrenados mediante optimización sistemática de hiperparámetros, utilizando una infraestructura dockerizada con aceleración GPU para facilitar la experimentación.

+

El objetivo principal del trabajo era alcanzar un CER inferior al 2% en documentos académicos en español. Los resultados obtenidos se resumen a continuación:

+

Tabla 55. Cumplimiento del objetivo de CER.

+

Métrica

Objetivo

Mejor Trial

Dataset Completo

Cumplimiento

CER

< 2%

0.79%

7.72%

✓ Parcial

Fuente: Elaboración propia.

 

+

Nota: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%, 5 páginas). La validación sobre el conjunto de datos completo (45 páginas) muestra un CER de 7.72%, evidenciando sobreajuste al subconjunto de optimización. Esta diferencia se analiza en detalle en el Capítulo 4.

Conclusiones Específicas

Respecto a OE1 (Comparativa de soluciones OCR):

·     Se evaluaron tres soluciones OCR de código abierto: EasyOCR, PaddleOCR (PP-OCRv5) y DocTR

·     PaddleOCR demostró el mejor rendimiento base para documentos en español

·     La configurabilidad del pipeline de PaddleOCR lo hace idóneo para optimización

-

Respecto a OE2 (Preparación del dataset):

-

·     Se construyó un dataset estructurado con 24 páginas de documentos académicos

+

Respecto a OE2 (Preparación del conjunto de datos):

+

·     Se construyó un conjunto de datos estructurado con 45 páginas de documentos académicos

·     La clase ImageTextDataset facilita la carga de pares imagen-texto

-

·     El ground truth se extrajo automáticamente del PDF mediante PyMuPDF

+

·     El texto de referencia se extrajo automáticamente del PDF mediante PyMuPDF

Respecto a OE3 (Identificación de hiperparámetros críticos):

-

·     El parámetro textline_orientation es el más influyente: reduce el CER en un 69.7% cuando está habilitado

-

·     El umbral text_det_thresh presenta la correlación más fuerte (-0.52) con el CER

-

·     Los parámetros de corrección de documento (use_doc_orientation_classify, use_doc_unwarping) no aportan mejora en documentos digitales

+

·     El parámetro textline_orientation es el más influyente, siendo crítico para obtener buenos resultados

+

·     El parámetro use_doc_orientation_classify demostró impacto positivo en la configuración GPU

+

·     El umbral text_det_thresh presenta correlación negativa moderada (-0.52) con el CER

+

·     El parámetro use_doc_unwarping no aporta mejora en documentos digitales

Respecto a OE4 (Optimización con Ray Tune):

-

·     Se ejecutaron 64 trials con el algoritmo OptunaSearch

-

·     El tiempo total del experimento fue aproximadamente 6 horas (en CPU)

+

·     Se ejecutaron 64 trials con el algoritmo OptunaSearch y aceleración GPU

+

·     El tiempo total del experimento fue aproximadamente 1.5 horas (con GPU RTX 3060)

·     La arquitectura basada en contenedores Docker permitió superar incompatibilidades entre Ray y los motores OCR, facilitando además la portabilidad y reproducibilidad

Respecto a OE5 (Validación de la configuración):

-

·     Se validó la configuración óptima sobre el dataset completo de 24 páginas

-

·     La mejora obtenida fue del 80.9% en reducción del CER (7.78% → 1.49%)

-

·     La precisión de caracteres alcanzó el 98.51%

+

·     Se validó la configuración óptima sobre el conjunto de datos completo de 45 páginas

+

·     El mejor trial individual alcanzó un CER de 0.79% (precisión del 99.21%)

+

·     En el conjunto de datos completo se obtuvo una mejora del 12.8% en CER (8.85% → 7.72%)

+

·     La diferencia entre resultados de trial y validación completa revela sobreajuste al subconjunto de optimización

Hallazgos Clave

1.   Arquitectura sobre umbrales: Un único parámetro booleano (textline_orientation) tiene más impacto que todos los umbrales continuos combinados.

1.   Umbrales mínimos efectivos: Valores de text_det_thresh < 0.1 causan fallos catastróficos (CER >40%).

1.   Simplicidad para documentos digitales: Para documentos PDF digitales (no escaneados), los módulos de corrección de orientación y deformación son innecesarios.

-

1.   Optimización sin fine-tuning: Se puede mejorar significativamente el rendimiento de modelos preentrenados mediante ajuste de hiperparámetros de inferencia.

+

1.   Optimización sin fine-tuning: Se puede mejorar el rendimiento de modelos preentrenados mediante ajuste de hiperparámetros de inferencia, aunque la generalización a conjuntos de datos más amplios requiere validación cuidadosa.

Contribuciones del Trabajo

1.   Metodología reproducible: Se documenta un proceso completo de optimización de hiperparámetros OCR con Ray Tune + Optuna.

1.   Análisis de hiperparámetros de PaddleOCR: Se cuantifica el impacto de cada parámetro configurable mediante correlaciones y análisis comparativo.

@@ -5599,15 +5693,17 @@ y trabajo futuro

Este capít

1.   Código fuente: Todo el código está disponible en el repositorio GitHub para reproducción y extensión.

Limitaciones del Trabajo

1.   Tipo de documento único: Los experimentos se realizaron únicamente sobre documentos académicos de UNIR. La generalización a otros tipos de documentos requiere validación adicional.

-

1.   Tamaño del dataset: 24 páginas es un corpus limitado para conclusiones estadísticamente robustas.

-

1.   Ground truth automático: La extracción automática del texto de referencia puede introducir errores en layouts complejos.

-

1.   Validación en entorno limitado: Aunque se validó con GPU (126x más rápido que CPU, 0.55s/página), los experimentos se realizaron en hardware de consumo (RTX 3060). Hardware empresarial podría ofrecer mejor rendimiento.

+

1.   Tamaño del conjunto de datos: 45 páginas es un corpus limitado para conclusiones estadísticamente robustas.

+

1.   Texto de referencia automático: La extracción automática del texto de referencia puede introducir errores en diseños complejos.

+

1.   Sobreajuste al subconjunto de optimización: El ajuste sobre 5 páginas no generalizó completamente al conjunto de datos de 45 páginas, resultando en un CER de 7.72% frente al 0.79% del mejor trial.

1.   Parámetro no explorado: text_det_unclip_ratio permaneció fijo en 0.0 durante todo el experimento.

+

1.   Hardware de consumo: Aunque la GPU RTX 3060 proporcionó una aceleración de 82× respecto a CPU, hardware empresarial podría ofrecer mejor rendimiento.

Líneas de trabajo futuro

Extensiones Inmediatas

1.   Validación cruzada: Evaluar la configuración óptima en otros tipos de documentos en español (facturas, formularios, textos manuscritos).

+

1.   Subconjunto de optimización más amplio: Utilizar un subconjunto mayor (15-20 páginas) para el ajuste de hiperparámetros y reducir el sobreajuste.

1.   Exploración de text_det_unclip_ratio: Incluir este parámetro en el espacio de búsqueda.

-

1.   Dataset ampliado: Construir un corpus más amplio y diverso de documentos en español.

+

1.   Conjunto de datos ampliado: Construir un corpus más amplio y diverso de documentos en español.

Líneas de Investigación

1.   Transfer learning de hiperparámetros: Investigar si las configuraciones óptimas para un tipo de documento transfieren a otros dominios.

1.   Optimización multi-objetivo: Considerar simultáneamente CER, WER y tiempo de inferencia como objetivos.

@@ -5618,9 +5714,10 @@ y trabajo futuro

Este capít

1.   Integración en pipelines de producción: Implementar la configuración optimizada en sistemas reales de procesamiento documental.

1.   Benchmark público: Publicar un benchmark de OCR para documentos en español que facilite la comparación de soluciones.

Reflexión Final

-

Este trabajo demuestra que, en un contexto de recursos limitados donde el fine-tuning de modelos de deep learning no es viable, la optimización de hiperparámetros representa una alternativa práctica y efectiva para mejorar sistemas OCR.

-

La metodología propuesta es reproducible, los resultados son cuantificables, y las conclusiones son aplicables a escenarios reales de procesamiento documental. La reducción del CER del 7.78% al 1.49% representa una mejora sustancial que puede tener impacto directo en aplicaciones downstream como extracción de información, análisis semántico y búsqueda de documentos.

-

El código fuente y los datos experimentales están disponibles públicamente para facilitar la reproducción y extensión de este trabajo.

Referencias +

Este trabajo demuestra que la optimización de hiperparámetros representa una alternativa viable al fine-tuning para mejorar sistemas OCR, especialmente cuando se dispone de modelos preentrenados para el idioma objetivo.

+

La metodología propuesta es reproducible, los resultados son cuantificables, y las conclusiones son aplicables a escenarios reales de procesamiento documental. Aunque el objetivo de CER < 2% se alcanzó en el mejor trial individual (0.79%), la validación sobre el conjunto de datos completo (7.72%) revela la importancia de utilizar subconjuntos de optimización representativos y de validar rigurosamente la generalización.

+

La infraestructura dockerizada desarrollada facilita la reproducibilidad de los experimentos y la evaluación sistemática de configuraciones OCR. La aceleración de 82× proporcionada por GPU hace viable la exploración exhaustiva de espacios de hiperparámetros en tiempos razonables.

+

El código fuente, las imágenes Docker y los datos experimentales están disponibles públicamente en el repositorio del proyecto para facilitar la reproducción y extensión de este trabajo.

Referencias bibliográficas

Akiba, T., Sano, S., Yanase, T., Ohta, T., & Koyama, M. (2019). Optuna: A next-generation hyperparameter optimization framework. Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining, 2623-2631. https://doi.org/10.1145/3292500.3330701

Baek, Y., Lee, B., Han, D., Yun, S., & Lee, H. (2019). Character region awareness for text detection. Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition, 9365-9374. https://doi.org/10.1109/CVPR.2019.00959

Bergstra, J., & Bengio, Y. (2012). Random search for hyper-parameter optimization. Journal of Machine Learning Research, 13(1), 281-305. https://jmlr.org/papers/v13/bergstra12a.html

@@ -5657,65 +5754,49 @@ major-latin;mso-bidi-font-family:"Calibri Light";mso-bidi-theme-font:major-latin

·     Dataset: Imágenes y textos de referencia utilizados

·     Resultados: Archivos CSV con los resultados de los 64 trials por servicio

A.2 Estructura del Repositorio

-

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

+

Figura 11. Estructura del repositorio MastersThesis

+

Estructura del repositorio MastersThesis

+

Fuente: Elaboración propia.

+

 

+

Tabla 56. Descripción de directorios principales.

+

Directorio

Contenido

docs/

Capítulos del TFM en Markdown (estructura UNIR)

docs/metrics/

Métricas de rendimiento por servicio OCR

src/paddle_ocr/

Servicio PaddleOCR dockerizado

src/doctr_service/

Servicio DocTR dockerizado

src/easyocr_service/

Servicio EasyOCR dockerizado

src/raytune/

Scripts de optimización Ray Tune

src/results/

CSVs con resultados de 64 trials por servicio

thesis_output/

Documento TFM generado + figuras PNG

instructions/

Plantilla e instrucciones UNIR oficiales

+

Fuente: Elaboración propia.

+

 

A.3 Requisitos de Software

Sistema de Desarrollo

-

Tabla 53. Especificaciones del sistema de desarrollo.

+

Tabla 57. 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 54. Dependencias del proyecto.

+

Tabla 58. Dependencias del proyecto.

Componente

Versión

Python

3.12.3

Docker

29.1.5

NVIDIA Container Toolkit

Requerido para GPU

Ray

2.52.1

Optuna

4.7.0

Fuente: Elaboración propia.

 

A.4 Instrucciones de Ejecución de Servicios OCR

PaddleOCR (Puerto 8002)

Imágenes Docker:

-

·     GPU: seryus.ddns.net/unir/paddle-ocr-gpu

-

·     CPU: seryus.ddns.net/unir/paddle-ocr-cpu

+

·     GPU: seryus.ddns.net/unir/paddle-ocr-gpu

+

·     CPU: seryus.ddns.net/unir/paddle-ocr-cpu

cd src/paddle_ocr
 
 # GPU (recomendado)
 docker compose up -d
 
-# CPU (más lento, 126x)
+# CPU (más lento, 82x)
 docker compose -f docker-compose.cpu-registry.yml up -d

DocTR (Puerto 8003)

-

Imagen Docker: seryus.ddns.net/unir/doctr-gpu

+

Imagen Docker: seryus.ddns.net/unir/doctr-gpu

cd src/doctr_service
 
 # GPU
 docker compose up -d

EasyOCR (Puerto 8002)

-

Imagen Docker: seryus.ddns.net/unir/easyocr-gpu

+

Nota: EasyOCR utiliza el mismo puerto (8002) que PaddleOCR. No se pueden ejecutar simultáneamente. Por esta razón, existe un archivo docker-compose separado para EasyOCR.

+

Imagen Docker: seryus.ddns.net/unir/easyocr-gpu

cd src/easyocr_service
 
-# GPU
+# GPU (usar archivo separado para evitar conflicto de puerto)
 docker compose up -d

Verificar Estado del Servicio

# Verificar salud del servicio
@@ -5765,18 +5846,19 @@ 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 55. Servicios Docker y puertos.

-

Servicio

Puerto

Script de Ajuste

PaddleOCR

8002

paddle_ocr_payload

DocTR

8003

doctr_payload

EasyOCR

8002

easyocr_payload

+

Tabla 59. Servicios Docker y puertos.

+

Servicio

Puerto

Script de Ajuste

Nota

PaddleOCR

8002

paddle_ocr_payload

-

DocTR

8003

doctr_payload

-

EasyOCR

8002

easyocr_payload

Conflicto con PaddleOCR

Fuente: Elaboración propia.

 

+

Nota: Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez. PaddleOCR y EasyOCR comparten el puerto 8002. Para cambiar de servicio, detener el actual con docker compose down.

A.7 Métricas de Rendimiento

Los resultados detallados de las evaluaciones y ajustes de hiperparámetros se encuentran en:

·     Métricas Generales - Comparativa de los tres servicios

-

·     PaddleOCR - Mejor precisión (7.76% CER baseline, 1.49% optimizado)

+

·     PaddleOCR - Mejor precisión (8.85% CER baseline, 7.72% optimizado, 0.79% mejor trial)

·     DocTR - Más rápido (0.50s/página)

·     EasyOCR - Balance intermedio

Resumen de Resultados

-

Tabla 56. Resumen de resultados del benchmark por servicio.

+

Tabla 60. 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.