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

deliberable_04_01_2026
All checks were successful
build_docker / essential (push) Successful in 1s
Details
build_docker / build_paddle_ocr (push) Successful in 5m12s
Details
build_docker / build_paddle_ocr_gpu (push) Successful in 20m54s
Details
build_docker / build_easyocr (push) Successful in 18m19s
Details
build_docker / build_doctr (push) Successful in 19m49s
Details
build_docker / build_easyocr_gpu (push) Successful in 24m6s
Details
build_docker / build_raytune (push) Successful in 4m10s
Details
build_docker / build_doctr_gpu (push) Successful in 16m26s
Details

Browse Source 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Sergio Jimenez Jimenez
2026-02-04 18:43:22 +01:00
parent 9ee2490097
commit d746a3c73f
55 changed files with 2273 additions and 1720 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
docs/07_anexo_a.md
View File

@@ -6,7 +6,7 @@ Este anexo proporciona la información técnica necesaria para reproducir los ex
Todo el código fuente y los datos utilizados en este trabajo están disponibles públicamente en el siguiente repositorio:
**URL del repositorio:** https://seryus.ddns.net/unir/MastersThesis
**URL del repositorio:** [https://seryus.ddns.net/unir/MastersThesis](https://seryus.ddns.net/unir/MastersThesis)
El repositorio incluye:
@@ -32,71 +32,25 @@ config:
flowchart TB
subgraph root["MastersThesis/"]
direction TB
docs["docs/ - Capítulos del TFM + métricas"]
instructions["instructions/ - Plantilla UNIR"]
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
subgraph src["src/ - Código y resultados"]
paddle["paddle_ocr/ - Microservicio PaddleOCR"]
easy["easyocr_service/ - Microservicio EasyOCR"]
doctr["doctr_service/ - Microservicio DocTR"]
ray["raytune/ - Orquestación Ray Tune"]
results["results/ - CSV de trials"]
corr["results/correlations/ - Correlaciones"]
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<br/>generate_mermaid_figures.py"]
config["claude.md<br/>README.md"]
end
```
**Tabla A1.** *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 A2.** *Especificaciones del sistema de desarrollo.*
**Tabla A1.** *Especificaciones del sistema de desarrollo.*
| Componente | Especificación |
|------------|----------------|
@@ -106,21 +60,24 @@ flowchart TB
| GPU | NVIDIA RTX 3060 Laptop (5.66 GB VRAM) |
| CUDA | 12.4 |
*Fuente: Elaboración propia.*
**Fuente:** [`docs/metrics/metrics.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).
### Dependencias
**Tabla A3.** *Dependencias del proyecto.*
**Tabla A2.** *Dependencias del proyecto.*
| Componente | Versión |
|------------|---------|
| Python | 3.12.3 |
| Docker | 29.1.5 |
| NVIDIA Container Toolkit | Requerido para GPU |
| Ray | 2.52.1 |
| PaddlePaddle | 3.2.2 |
| PaddleOCR | 3.3.2 |
| Ray Tune | 2.52.1 |
| Optuna | 4.7.0 |
| DocTR (python-doctr) | >= 0.8.0 |
| EasyOCR | >= 1.7.0 |
| Docker | Requerido para contenedores |
| NVIDIA Container Toolkit | Requerido para GPU |
*Fuente: Elaboración propia.*
**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), [`src/README.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/README.md).
## A.4 Instrucciones de Ejecución de Servicios OCR
@@ -231,7 +188,7 @@ analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_
### Servicios y Puertos
**Tabla A4.** *Servicios Docker y puertos.*
**Tabla A3.** *Servicios Docker y puertos.*
| Servicio | Puerto | Script de Ajuste | Nota |
|----------|--------|------------------|------|
@@ -239,7 +196,7 @@ analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_
| DocTR | 8003 | `doctr_payload` | - |
| EasyOCR | 8002 | `easyocr_payload` | Conflicto con PaddleOCR |
*Fuente: Elaboración propia.*
**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`.
@@ -249,7 +206,7 @@ Esta sección presenta los resultados completos de las evaluaciones comparativas
### Comparativa General de Servicios
**Tabla A5.** *Comparativa de servicios OCR en dataset de 45 páginas (GPU RTX 3060).*
**Tabla A4.** *Comparativa de servicios OCR en dataset de 45 páginas (GPU RTX 3060).*
| Servicio | CER | WER | Tiempo/Página | Tiempo Total | VRAM |
|----------|-----|-----|---------------|--------------|------|
@@ -257,7 +214,7 @@ Esta sección presenta los resultados completos de las evaluaciones comparativas
| EasyOCR | 11.23% | 36.36% | 1.88s | 88.5s | ~2 GB |
| DocTR | 12.06% | 42.01% | 0.50s | 28.4s | ~1 GB |
*Fuente: Benchmark realizado el 2026-01-19. Elaboración propia.*
**Fuente:** [`docs/metrics/metrics_paddle.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics_paddle.md), [`docs/metrics/metrics_easyocr.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics_easyocr.md), [`docs/metrics/metrics_doctr.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics_doctr.md).
**Ganador:** PaddleOCR (Mobile) - Mejor precisión (7.76% CER) con velocidad competitiva y mínimo consumo de VRAM.
@@ -265,7 +222,7 @@ Esta sección presenta los resultados completos de las evaluaciones comparativas
Se ejecutaron 64 trials por servicio utilizando Ray Tune con Optuna sobre las páginas 5-10 del primer documento.
**Tabla A6.** *Resultados del ajuste de hiperparámetros por servicio.*
**Tabla A5.** *Resultados del ajuste de hiperparámetros por servicio.*
| Servicio | CER Base | CER Ajustado | Mejora | Mejor Trial (5 páginas) |
|----------|----------|--------------|--------|-------------------------|
@@ -273,9 +230,44 @@ Se ejecutaron 64 trials por servicio utilizando Ray Tune con Optuna sobre las p
| DocTR | 12.06% | 12.07% | 0% | 7.43% |
| EasyOCR | 11.23% | 11.14% | 0.8% | 5.83% |
*Fuente: Resultados de 64 trials Ray Tune por servicio. Elaboración propia.*
**Fuente:** [`docs/metrics/metrics_paddle.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics_paddle.md), [`docs/metrics/metrics_easyocr.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics_easyocr.md), [`docs/metrics/metrics_doctr.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics_doctr.md).
> **Nota sobre sobreajuste:** La diferencia entre los resultados del mejor trial (subconjunto de 5 páginas) y el dataset completo (45 páginas) indica sobreajuste parcial a las páginas de ajuste. Un subconjunto más grande (15-20 páginas) mejoraría la generalización.
> **Nota sobre sobreajuste:** La diferencia entre los resultados del mejor trial (subconjunto de 5 páginas) y el dataset completo (45 páginas) indica sobreajuste parcial a las páginas de ajuste. Un subconjunto más amplio mejoraría la generalización.
### Distribución de trials por rango de CER (PaddleOCR)
**Tabla A6.** *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:** [`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).
**Figura A1.** *Distribución de trials por rango de CER (PaddleOCR).*
```mermaid
---
title: "Distribución de trials por rango de CER (PaddleOCR)"
config:
theme: base
themeVariables:
primaryColor: "#E6F4F9"
primaryTextColor: "#404040"
primaryBorderColor: "#0098CD"
lineColor: "#0098CD"
---
pie showData
title Distribución de 64 trials
"CER < 2%" : 43
"CER 2-5%" : 10
"CER 5-10%" : 11
```
**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).
### Configuración Óptima PaddleOCR
@@ -294,7 +286,7 @@ La siguiente configuración logró el mejor rendimiento en el ajuste de hiperpar
```
**Hallazgos clave:**
- `textline_orientation=true`: Crítico para documentos con layouts mixtos
- `textline_orientation=true`: Crítico para documentos con secciones y encabezados
- `use_doc_orientation_classify=true`: Mejora detección de orientación
- `use_doc_unwarping=false`: Innecesario para PDFs digitales
- `text_det_thresh` bajo (0.0462): Detección más sensible mejora resultados
@@ -305,11 +297,33 @@ La siguiente configuración logró el mejor rendimiento en el ajuste de hiperpar
| Métrica | CPU | GPU (RTX 3060) | Aceleración |
|---------|-----|----------------|-------------|
| Tiempo/Página | 69.4s | 0.55s | **126x más rápido** |
| Mejor CER | 1.15% | 0.79% | GPU mejor |
| 45 páginas | ~52 min | ~25 seg | **126x más rápido** |
| Tiempo/Página | 69.4s | 0.84s | **82x más rápido** |
| 45 páginas | ~52 min | ~38 seg | **82x más rápido** |
*Fuente: Datos CPU de `raytune_paddle_subproc_results_20251207_192320.csv`. Elaboración propia.*
**Fuente:** Datos de tiempo CPU de [`src/raytune_paddle_subproc_results_20251207_192320.csv`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/raytune_paddle_subproc_results_20251207_192320.csv) y tiempos de GPU en trials de ajuste. Elaboración propia.
**Figura A2.** *Tiempo de procesamiento: CPU vs GPU (segundos/página).*
```mermaid
---
title: "Tiempo de procesamiento: CPU vs GPU (segundos/página)"
config:
theme: base
themeVariables:
primaryColor: "#E6F4F9"
primaryTextColor: "#404040"
primaryBorderColor: "#0098CD"
lineColor: "#0098CD"
xyChart:
plotColorPalette: "#0098CD"
---
xychart-beta
x-axis ["CPU", "GPU (RTX 3060)"]
y-axis "Segundos por página" 0 --> 75
bar [69.4, 0.84]
```
**Fuente:** [`src/raytune_paddle_subproc_results_20251207_192320.csv`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/raytune_paddle_subproc_results_20251207_192320.csv) y [`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). Leyenda: Aceleración de **82x** con GPU. El procesamiento de una página pasa de 69.4s (CPU) a 0.84s (GPU).
### Análisis de Errores por Servicio
@@ -317,11 +331,11 @@ La siguiente configuración logró el mejor rendimiento en el ajuste de hiperpar
| Servicio | Fortalezas | Debilidades | ¿Fine-tuning recomendado? |
|----------|------------|-------------|---------------------------|
| **PaddleOCR** | Preserva estructura, buen manejo de español | Errores menores de acentos (~5%) | No (ya excelente) |
| **PaddleOCR** | Preserva estructura, buen manejo de español | Errores menores de acentos | No (ya excelente) |
| DocTR | Más rápido | Pierde estructura, omite TODOS los diacríticos | Sí (para diacríticos) |
| EasyOCR | Modelo correcto para español | Caracteres espurios, confunde `o`/`0` | Sí (problemas del detector) |
*Fuente: Análisis manual del debugset. Elaboración propia.*
**Fuente:** Análisis manual del debugset. Elaboración propia.
### Archivos de Resultados
@@ -331,12 +345,33 @@ Los resultados crudos de los 64 trials por servicio están disponibles en el rep
| Servicio | Archivo CSV |
|----------|-------------|
| PaddleOCR | [`src/results/raytune_paddle_results_20260119_122609.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/results/raytune_paddle_results_20260119_122609.csv) |
| DocTR | [`src/results/raytune_doctr_results_20260119_121445.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/results/raytune_doctr_results_20260119_121445.csv) |
| EasyOCR | [`src/results/raytune_easyocr_results_20260119_120204.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/results/raytune_easyocr_results_20260119_120204.csv) |
| PaddleOCR | [`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)|
| DocTR | [`src/results/raytune_doctr_results_20260119_121445.csv`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/results/raytune_doctr_results_20260119_121445.csv)|
| EasyOCR | [`src/results/raytune_easyocr_results_20260119_120204.csv`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/results/raytune_easyocr_results_20260119_120204.csv)|
*Fuente: Elaboración propia.*
**Fuente:** Elaboración propia.
## A.8 Licencia
## A.8 Fuentes de precios cloud
Las tablas de costos cloud se basan en las páginas oficiales de precios. Se consultaron en enero de 2026.
- AWS EC2 g4dn.xlarge: [https://aws.amazon.com/ec2/instance-types/g4/](https://aws.amazon.com/ec2/instance-types/g4/)
- Google Colab Pro: [https://colab.research.google.com/signup](https://colab.research.google.com/signup)
- Google Colab Pro+: [https://colab.research.google.com/signup](https://colab.research.google.com/signup)
## A.9 Requisitos documentados por dependencias
Requisitos extraídos de la documentación oficial de las dependencias usadas:
- DocTR: requiere Python 3.10 o superior.
**Fuente:** [https://github.com/mindee/doctr](https://github.com/mindee/doctr)
- DocTR Docker: imágenes basadas en CUDA 12.2, el host debe ser al menos 12.2.
**Fuente:** [https://github.com/mindee/doctr](https://github.com/mindee/doctr)
- PaddleOCR: soporte de inferencia con CUDA 12.
**Fuente:** [https://github.com/PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- PaddleOCR: soporte de Python 3.12 en dependencias.
**Fuente:** [https://github.com/PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
## A.10 Licencia
El código se distribuye bajo licencia MIT.