# Anexo A. Código fuente y datos analizados {.unnumbered}

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](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

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

## A.3 Requisitos de Software

### Sistema de Desarrollo

**Tabla A1.** *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`](https://seryus.ddns.net/unir/MastersThesis/src/branch/main/docs/metrics/metrics.md).

### Dependencias

**Tabla A2.** *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`](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

### PaddleOCR (Puerto 8002)

**Imágenes Docker:**
- 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

# 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)

```bash
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)

```bash
cd src/easyocr_service

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

### Verificar Estado del Servicio

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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 A3.** *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 A4.** *Servicios OCR en 45 páginas (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`](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.

### 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 A5.** *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`](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 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).

> **Nota:** Ver [Figura 15](#figura-15) en el Capítulo 4 para la representación gráfica de esta distribución.

### Configuración Óptima PaddleOCR

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

```json
{
  "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 A7.** *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`](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.

> **Nota:** Ver [Figura 20](#figura-20) en el Capítulo 4 para la representación gráfica de esta comparación.

### Análisis de Errores por Servicio

**Tabla A8.** *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 A9.** *Ubicación de archivos de resultados.*

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

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

## A.11 Índice de acrónimos

**Tabla A10.** *Acrónimos utilizados en el trabajo.*

| Acrónimo | Significado |
|----------|-------------|
| OCR | Reconocimiento Óptico de Caracteres |
| CER | Character Error Rate (tasa de error de caracteres) |
| WER | Word Error Rate (tasa de error de palabras) |
| GPU | Graphics Processing Unit |
| CPU | Central Processing Unit |
| API | Application Programming Interface |

**Fuente:** Elaboración propia.