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

206
docs/07_anexo_a.md
View File

@@ -32,47 +32,17 @@ 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
```
@@ -80,17 +50,17 @@ flowchart TB
| 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.*
| [`docs/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/)| Capítulos del TFM en Markdown (estructura UNIR) |
| [`docs/metrics/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/)| Métricas de rendimiento por servicio OCR |
| [`src/paddle_ocr/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/paddle_ocr/)| Servicio PaddleOCR dockerizado |
| [`src/doctr_service/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/doctr_service/)| Servicio DocTR dockerizado |
| [`src/easyocr_service/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/easyocr_service/)| Servicio EasyOCR dockerizado |
| [`src/raytune/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/raytune/)| Scripts de optimización Ray Tune |
| [`src/results/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/results/)| CSVs con resultados de 64 trials por servicio |
| [`src/results/correlations/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/src/results/correlations/)| Correlaciones de hiperparámetros por servicio |
| [`thesis_output/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/thesis_output/)| Documento TFM generado + figuras PNG |
| [`instructions/`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/instructions/)| Plantilla e instrucciones UNIR oficiales |
Fuente: [Repositorio del proyecto](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/).
## A.3 Requisitos de Software
@@ -105,8 +75,9 @@ flowchart TB
| RAM | 16 GB DDR4 |
| GPU | NVIDIA RTX 3060 Laptop (5.66 GB VRAM) |
| CUDA | 12.4 |
Fuente: [`docs/metrics/metrics.md`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).
*Fuente: Elaboración propia.*
### Dependencias
### Dependencias
@@ -114,13 +85,17 @@ flowchart TB
| 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: [`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).
*Fuente: Elaboración propia.*
## A.4 Instrucciones de Ejecución de Servicios OCR
## A.4 Instrucciones de Ejecución de Servicios OCR
@@ -142,7 +117,7 @@ docker compose -f docker-compose.cpu-registry.yml up -d
### DocTR (Puerto 8003)
**Imagen Docker:** [`seryus.ddns.net/unir/doctr-gpu`](https://seryus.ddns.net/unir/-/packages/container/doctr-gpu/latest)
**Imagen Docker:** `seryus.ddns.net/unir/doctr-gpu`(https://seryus.ddns.net/unir/-/packages/container/doctr-gpu/latest)
```bash
cd src/doctr_service
@@ -155,7 +130,7 @@ docker compose up -d
> **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)
**Imagen Docker:** `seryus.ddns.net/unir/easyocr-gpu`(https://seryus.ddns.net/unir/-/packages/container/easyocr-gpu/latest)
```bash
cd src/easyocr_service
@@ -238,8 +213,7 @@ analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_
| PaddleOCR | 8002 | `paddle_ocr_payload` | - |
| 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`.
@@ -256,8 +230,7 @@ Esta sección presenta los resultados completos de las evaluaciones comparativas
| **PaddleOCR (Mobile)** | **7.76%** | **11.62%** | 0.58s | 32.0s | 0.06 GB |
| 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.
@@ -272,10 +245,43 @@ Se ejecutaron 64 trials por servicio utilizando Ray Tune con Optuna sobre las p
| **PaddleOCR** | 8.85% | **7.72%** | **12.8%** | **0.79%** ✓ |
| DocTR | 12.06% | 12.07% | 0% | 7.43% |
| EasyOCR | 11.23% | 11.14% | 0.8% | 5.83% |
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).
*Fuente: Resultados de 64 trials Ray Tune por servicio. Elaboración propia.*
> **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.
> **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.
### Distribución de trials por rango de CER (PaddleOCR)
**Tabla A7.** *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,49 +300,89 @@ 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
### Rendimiento CPU vs GPU
**Tabla A7.** *Comparación de rendimiento CPU vs GPU (PaddleOCR).*
**Tabla A8.** *Comparación de rendimiento CPU vs GPU (PaddleOCR).*
| 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 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.
*Fuente: Datos CPU de `raytune_paddle_subproc_results_20251207_192320.csv`. 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 **82×** con GPU. El procesamiento de una página pasa de 69.4s (CPU) a 0.84s (GPU).
### Análisis de Errores por Servicio
**Tabla A8.** *Tipos de errores identificados por servicio OCR.*
**Tabla A9.** *Tipos de errores identificados por servicio OCR.*
| 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
Los resultados crudos de los 64 trials por servicio están disponibles en el repositorio:
**Tabla A9.** *Ubicación de archivos de resultados.*
**Tabla A10.** *Ubicación de archivos de resultados.*
| 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 Fuentes de precios cloud
## A.8 Licencia
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/
- Google Colab Pro: https://colab.research.google.com/signup
- Google Colab Pro+: https://colab.research.google.com/signup
## A.9 Requisitos documentados por dependencias
Requisitos extraidos de la documentacion oficial de las dependencias usadas:
- DocTR: requiere Python 3.10 o superior.
Fuente: https://github.com/mindee/doctr
- DocTR Docker: imagenes basadas en CUDA 12.2, el host debe ser al menos 12.2.
Fuente: https://github.com/mindee/doctr
- PaddleOCR: soporte de inferencia con CUDA 12.
Fuente: https://github.com/PaddlePaddle/PaddleOCR
- PaddleOCR: soporte de Python 3.12 en dependencias.
Fuente: https://github.com/PaddlePaddle/PaddleOCR
## A.10 Licencia
El código se distribuye bajo licencia MIT.