unir/MastersThesis
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation review and data consistency.
Some checks failed
build_docker / essential (push) Successful in 0s
Details
build_docker / build_paddle_ocr (push) Successful in 4m57s
Details
build_docker / build_raytune (push) Has been cancelled
Details
build_docker / build_easyocr_gpu (push) Has been cancelled
Details
build_docker / build_doctr (push) Has been cancelled
Details
build_docker / build_doctr_gpu (push) Has been cancelled
Details
build_docker / build_paddle_ocr_gpu (push) Has been cancelled
Details
build_docker / build_easyocr (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Sergio Jimenez Jimenez
2026-01-24 15:53:34 +01:00
parent 9ee2490097
commit 0089b34cb3
48 changed files with 1030 additions and 930 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/03_objetivos_metodologia.md
View File

@@ -17,8 +17,7 @@ La motivación presentada en el capítulo anterior se traduce ahora en objetivos
| **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.*
Fuente: [`docs/metrics/metrics.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).
## Objetivos específicos
@@ -41,7 +40,7 @@ La motivación presentada en el capítulo anterior se traduce ahora en objetivos
### Visión General
La metodología se estructura en cinco fases secuenciales, cada una de las cuales produce resultados que alimentan la siguiente. Desde la preparación del dataset hasta la validación final, el proceso sigue un diseño experimental que permite reproducir y verificar cada paso.
La metodología se estructura en cinco fases secuenciales, cada una de las cuales produce resultados que alimentan la siguiente. Desde la preparación del dataset hasta la validación final, el proceso sigue un diseño experimental. Esto permite reproducir y verificar cada paso.
```mermaid
---
@@ -118,7 +117,7 @@ flowchart LR
#### Clase ImageTextDataset
Se implementó una clase Python para cargar pares imagen-texto que retorna tuplas (PIL.Image, str) desde carpetas pareadas. La implementación completa está disponible en `src/ocr_benchmark_notebook.ipynb` (ver Anexo A).
Se implementó una clase Python para cargar pares imagen-texto que retorna tuplas (PIL.Image, str) desde carpetas pareadas. La implementación se encuentra en [`src/prepare_dataset.ipynb`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/prepare_dataset.ipynb) y en [`src/paddle_ocr/dataset_manager.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/paddle_ocr/dataset_manager.py), [`src/easyocr_service/dataset_manager.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/easyocr_service/dataset_manager.py), [`src/doctr_service/dataset_manager.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/doctr_service/dataset_manager.py).)
### Fase 2: Benchmark Comparativo
@@ -129,14 +128,13 @@ Se implementó una clase Python para cargar pares imagen-texto que retorna tupla
| Modelo | Versión | Configuración |
|--------|---------|---------------|
| EasyOCR | - | Idiomas: ['es', 'en'] |
| PaddleOCR | PP-OCRv5 | Modelos server_det + server_rec |
| PaddleOCR | PP-OCRv5 | Modelos Mobile (limitación de VRAM) |
| DocTR | - | db_resnet50 + sar_resnet31 |
*Fuente: Elaboración propia.*
Fuente: [`docs/metrics/metrics.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).
#### Métricas de Evaluación
Se utilizó la biblioteca `jiwer` para calcular CER y WER comparando el texto de referencia con la predicción del modelo OCR. La implementación está disponible en `src/ocr_benchmark_notebook.ipynb` (ver Anexo A).
Se utilizó la biblioteca `jiwer` para calcular CER y WER comparando el texto de referencia con la predicción del modelo OCR. La implementación se encuentra en [`src/paddle_ocr/paddle_ocr_tuning_rest.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/paddle_ocr/paddle_ocr_tuning_rest.py), [`src/easyocr_service/easyocr_tuning_rest.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/easyocr_service/easyocr_tuning_rest.py) y [`src/doctr_service/doctr_tuning_rest.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/doctr_service/doctr_tuning_rest.py).)
### Fase 3: Espacio de Búsqueda
@@ -153,12 +151,11 @@ Se utilizó la biblioteca `jiwer` para calcular CER y WER comparando el texto de
| `text_det_box_thresh` | Continuo | [0.0, 0.7] | Umbral de caja de detección |
| `text_det_unclip_ratio` | Fijo | 0.0 | Coeficiente de expansión (fijado) |
| `text_rec_score_thresh` | Continuo | [0.0, 0.7] | Umbral de confianza de reconocimiento |
*Fuente: Elaboración propia.*
Fuente: Elaboración propia.
#### Configuración de Ray Tune
El espacio de búsqueda se definió utilizando `tune.choice()` para parámetros booleanos y `tune.uniform()` para parámetros continuos, con OptunaSearch como algoritmo de optimización configurado para minimizar CER en 64 trials. La implementación completa está disponible en `src/raytune/raytune_ocr.py` (ver Anexo A).
El espacio de búsqueda se definió utilizando `tune.choice()` para parámetros booleanos y `tune.uniform()` para parámetros continuos, con OptunaSearch como algoritmo de optimización configurado para minimizar CER en 64 trials. La implementación completa está disponible en [`src/raytune/raytune_ocr.py`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/raytune/raytune_ocr.py) (ver Anexo A).
### Fase 4: Ejecución de Optimización
@@ -168,7 +165,7 @@ Se implementó una arquitectura basada en contenedores Docker para aislar los se
#### Ejecución con Docker Compose
Los servicios se orquestan mediante Docker Compose (`src/docker-compose.tuning.*.yml`):
Los servicios se orquestan mediante Docker Compose ([`src/docker-compose.tuning.paddle.yml`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/docker-compose.tuning.paddle.yml), [`src/docker-compose.tuning.doctr.yml`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/docker-compose.tuning.doctr.yml), [`src/docker-compose.tuning.easyocr.yml`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/docker-compose.tuning.easyocr.yml), [`src/docker-compose.tuning.yml`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/docker-compose.tuning.yml)):
```bash
# Iniciar servicio OCR
@@ -181,18 +178,18 @@ docker compose -f docker-compose.tuning.doctr.yml run raytune --service doctr --
docker compose -f docker-compose.tuning.doctr.yml down
```
El servicio OCR expone una API REST que retorna métricas en formato JSON:
El servicio OCR expone una API REST que retorna métricas en formato JSON. Ejemplo real de un trial con mejor CER:
```json
{
"CER": 0.0149,
"WER": 0.0762,
"TIME": 15.8,
"PAGES": 5,
"TIME_PER_PAGE": 3.16
"CER": 0.007884,
"WER": 0.077848,
"TIME_PER_PAGE": 0.5895
}
```
Fuente: [`src/results/raytune_paddle_results_20260119_122609.csv`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/results/raytune_paddle_results_20260119_122609.csv).
### Fase 5: Validación
#### Protocolo de Validación
@@ -214,23 +211,21 @@ El servicio OCR expone una API REST que retorna métricas en formato JSON:
| RAM | 16 GB DDR4 |
| GPU | NVIDIA RTX 3060 Laptop (5.66 GB VRAM) |
| Almacenamiento | SSD |
*Fuente: Elaboración propia.*
Fuente: [`docs/metrics/metrics.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).
#### Software
**Tabla 17.** *Versiones de software utilizadas.*
**Tabla 17.** *Software utilizado en el entorno de desarrollo.*
| Componente | Versión |
|------------|---------|
| Sistema Operativo | Ubuntu 24.04.3 LTS |
| Python | 3.12.3 |
| PaddleOCR | 3.3.2 |
| PaddlePaddle | 3.2.2 |
| Ray | 2.52.1 |
| PaddleOCR | 3.3.2 |
| Ray Tune | 2.52.1 |
| Optuna | 4.7.0 |
*Fuente: Elaboración propia.*
| DocTR (python-doctr) | >= 0.8.0 |
| EasyOCR | >= 1.7.0 |
Fuente: [`src/paddle_ocr/requirements.txt`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/paddle_ocr/requirements.txt), [`src/raytune/requirements.txt`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/raytune/requirements.txt), [`src/doctr_service/requirements.txt`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/doctr_service/requirements.txt), [`src/easyocr_service/requirements.txt`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/easyocr_service/requirements.txt).
#### Justificación de Ejecución Local vs Cloud
@@ -243,8 +238,7 @@ La decisión de ejecutar los experimentos en hardware local en lugar de utilizar
| AWS EC2 g4dn.xlarge | NVIDIA T4 (16 GB) | $0.526 | ~$384 |
| Google Colab Pro | T4/P100 | ~$1.30 | $10 + CU extras |
| Google Colab Pro+ | T4/V100/A100 | ~$1.30 | $50 + CU extras |
*Fuente: Elaboración propia a partir de precios públicos de AWS y Google Cloud (enero 2026).*
Fuente: Precios públicos de AWS y Google Cloud. Ver Anexo A, sección de fuentes de precios cloud (enero 2026).
Para las tareas específicas de este proyecto, los costos estimados en cloud serían:
@@ -255,8 +249,7 @@ Para las tareas específicas de este proyecto, los costos estimados en cloud ser
| Ajuste hiperparámetros (64×3 trials) | ~3 horas | ~$1.58 | ~$3.90 |
| Evaluación completa (45 páginas) | ~5 min | ~$0.04 | ~$0.11 |
| Desarrollo y depuración (20 horas/mes) | 20 horas | ~$10.52 | ~$26.00 |
*Fuente: Elaboración propia.*
Fuente: Elaboración propia a partir de precios públicos. Ver Anexo A, sección de fuentes de precios cloud (enero 2026).
Las ventajas de la ejecución local incluyen:
@@ -266,7 +259,7 @@ Las ventajas de la ejecución local incluyen:
4. **Almacenamiento local**: Dataset y resultados en disco sin costos de transferencia
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.
Para un proyecto de investigación con múltiples iteraciones de ajuste de hiperparámetros, la ejecución local reduce costos frente a servicios cloud. Este análisis se detalla en [`docs/metrics/metrics.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).)
### Limitaciones Metodológicas
@@ -280,9 +273,8 @@ Para un proyecto de investigación con múltiples iteraciones de ajuste de hiper
## Síntesis del capítulo
Los objetivos y la metodología definidos en este capítulo establecen el marco para la experimentación. El objetivo general —alcanzar un CER inferior al 2% mediante optimización de hiperparámetros— se descompone en cinco objetivos específicos que abarcan desde la comparativa inicial de soluciones hasta la validación final de la configuración optimizada.
Los objetivos y la metodología definidos en este capítulo establecen el marco para la experimentación. El objetivo general, alcanzar un CER inferior al 2% mediante optimización de hiperparámetros, se descompone en cinco objetivos específicos que abarcan desde la comparativa inicial de soluciones hasta la validación final de la configuración optimizada.
La metodología experimental en cinco fases garantiza un proceso sistemático y reproducible: preparación de un dataset de 45 páginas, benchmark comparativo de tres motores OCR, definición del espacio de búsqueda, ejecución de 64 trials con Ray Tune y Optuna, y validación de la configuración resultante. Las limitaciones metodológicas —tamaño del dataset, subconjunto de optimización reducido, texto de referencia automático— se reconocen explícitamente para contextualizar la interpretación de resultados.
La metodología experimental en cinco fases garantiza un proceso sistemático y reproducible: preparación de un dataset de 45 páginas, benchmark comparativo de tres motores OCR, definición del espacio de búsqueda, ejecución de 64 trials con Ray Tune y Optuna, y validación de la configuración resultante. Las limitaciones metodológicas, como el tamaño del dataset, el subconjunto de optimización reducido y el texto de referencia automático, se reconocen explícitamente para contextualizar la interpretación de resultados.
El capítulo siguiente pone en práctica esta metodología, presentando el desarrollo experimental completo con sus resultados y análisis.