MastersThesis/docs/07_anexo_a.md

Anexo A. Código fuente y datos analizados

Este anexo proporciona la información técnica necesaria para reproducir los experimentos descritos en este trabajo. Se incluyen las instrucciones de instalación, configuración de los servicios OCR dockerizados, ejecución de los scripts de optimización y acceso a los resultados experimentales.

A.1 Repositorio del Proyecto

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

El repositorio incluye:

• Servicios OCR dockerizados: PaddleOCR, DocTR, EasyOCR con soporte GPU
• Scripts de evaluación: Herramientas para evaluar y comparar modelos OCR
• Scripts de ajuste: Ray Tune con Optuna para optimización de hiperparámetros
• 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

---
title: "Estructura del repositorio MastersThesis"
config:
  theme: base
  themeVariables:
    primaryColor: "#E6F4F9"
    primaryTextColor: "#404040"
    primaryBorderColor: "#0098CD"
    lineColor: "#0098CD"
---
flowchart TB
    subgraph root["MastersThesis/"]
        direction TB
        docs["docs/ - Capítulos del TFM + métricas"]
        instructions["instructions/ - Plantilla UNIR"]

        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
    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
src/results/correlations/	Correlaciones de hiperparámetros por servicio
thesis_output/	Documento TFM generado + figuras PNG
instructions/	Plantilla e instrucciones UNIR oficiales
Fuente: Repositorio del proyecto.

A.3 Requisitos de Software

Sistema de Desarrollo

Tabla A2. 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: docs/metrics/metrics.md.

Dependencias

Dependencias

Tabla A3. Dependencias del proyecto.

Componente	Versión
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, src/raytune/requirements.txt, src/doctr_service/requirements.txt, src/easyocr_service/requirements.txt, src/README.md.

A.4 Instrucciones de Ejecución de Servicios OCR

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

cd src/paddle_ocr

# GPU (recomendado)
docker compose up -d

# 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(https://seryus.ddns.net/unir/-/packages/container/doctr-gpu/latest)

cd src/doctr_service

# GPU
docker compose up -d

EasyOCR (Puerto 8002)

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)

cd src/easyocr_service

# GPU (usar archivo separado para evitar conflicto de puerto)
docker compose up -d

Verificar Estado del Servicio

# Verificar salud del servicio
curl http://localhost:8002/health

# Respuesta esperada:
# {"status": "ok", "model_loaded": true, "gpu_name": "NVIDIA GeForce RTX 3060"}

A.5 Uso de la API OCR

Evaluar Dataset Completo

# PaddleOCR - Evaluación completa
curl -X POST http://localhost:8002/evaluate_full \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_folder": "/app/dataset",
    "save_output": true
  }'

Evaluar con Hiperparámetros Optimizados

# PaddleOCR con configuración óptima
curl -X POST http://localhost:8002/evaluate_full \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_folder": "/app/dataset",
    "use_doc_orientation_classify": true,
    "use_doc_unwarping": false,
    "textline_orientation": true,
    "text_det_thresh": 0.0462,
    "text_det_box_thresh": 0.4862,
    "text_det_unclip_ratio": 0.0,
    "text_rec_score_thresh": 0.5658,
    "save_output": true
  }'

A.6 Ajuste de Hiperparámetros con Ray Tune

Ejecutar Ajuste

cd src

# Activar entorno virtual
source ../.venv/bin/activate

# PaddleOCR (64 muestras)
python -c "
from raytune_ocr import *

ports = [8002]
check_workers(ports, 'PaddleOCR')
trainable = create_trainable(ports, paddle_ocr_payload)
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 A4. 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

Esta sección presenta los resultados completos de las evaluaciones comparativas y del ajuste de hiperparámetros realizado con Ray Tune sobre los tres servicios OCR evaluados.

Comparativa General de Servicios

Tabla A5. Comparativa de servicios OCR en dataset de 45 páginas (GPU RTX 3060).

Servicio	CER	WER	Tiempo/Página	Tiempo Total	VRAM
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: docs/metrics/metrics_paddle.md, docs/metrics/metrics_easyocr.md, docs/metrics/metrics_doctr.md.

Ganador: PaddleOCR (Mobile) - Mejor precisión (7.76% CER) con velocidad competitiva y mínimo consumo de VRAM.

Resultados de Ajuste de Hiperparámetros

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.

Servicio	CER Base	CER Ajustado	Mejora	Mejor Trial (5 páginas)
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, docs/metrics/metrics_easyocr.md, 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 amplio 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.

Figura A1. Distribución de trials por rango de CER (PaddleOCR).

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

Configuración Óptima PaddleOCR

La siguiente configuración logró el mejor rendimiento en el ajuste de hiperparámetros:

{
  "use_doc_orientation_classify": true,
  "use_doc_unwarping": false,
  "textline_orientation": true,
  "text_det_thresh": 0.0462,
  "text_det_box_thresh": 0.4862,
  "text_det_unclip_ratio": 0.0,
  "text_rec_score_thresh": 0.5658
}

Hallazgos clave:

• 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 A8. Comparación de rendimiento CPU vs GPU (PaddleOCR).

Métrica	CPU	GPU (RTX 3060)	Aceleración
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 y tiempos de GPU en trials de ajuste. Elaboración propia.

Figura A2. Tiempo de procesamiento: CPU vs GPU (segundos/página).

---
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 y 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 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	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.

Archivos de Resultados

Los resultados crudos de los 64 trials por servicio están disponibles en el repositorio:

Tabla A10. Ubicación de archivos de resultados.

Servicio	Archivo CSV
PaddleOCR	src/results/raytune_paddle_results_20260119_122609.csv
DocTR	src/results/raytune_doctr_results_20260119_121445.csv
EasyOCR	src/results/raytune_easyocr_results_20260119_120204.csv
Fuente: Elaboración propia.

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/
• 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.