Documentation review. (#5)

docs/07_anexo_a.md

@@ -1,10 +1,12 @@
 # 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
 
-El código fuente completo y los datos utilizados en este trabajo están disponibles en el siguiente repositorio:
+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://github.com/seryus/MastersThesis
+**URL del repositorio:** https://seryus.ddns.net/unir/MastersThesis
 
 El repositorio incluye:
 
@@ -16,39 +18,85 @@ El repositorio incluye:
 
 ## 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
+
+        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
+        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
 ```
-MastersThesis/
-├── docs/                           # Documentación de la tesis
-│   └── metrics/                    # Métricas de rendimiento OCR
-│       ├── metrics.md              # Resumen comparativo
-│       ├── metrics_paddle.md       # Resultados PaddleOCR
-│       ├── metrics_doctr.md        # Resultados DocTR
-│       └── metrics_easyocr.md      # Resultados EasyOCR
-├── src/
-│   ├── paddle_ocr/                 # Servicio PaddleOCR
-│   │   ├── Dockerfile.gpu          # Imagen Docker GPU
-│   │   ├── Dockerfile.cpu          # Imagen Docker CPU
-│   │   ├── docker-compose.yml      # Configuración Docker
-│   │   └── main.py                 # API FastAPI
-│   ├── doctr_service/              # Servicio DocTR
-│   │   ├── Dockerfile.gpu
-│   │   ├── docker-compose.yml
-│   │   └── main.py
-│   ├── easyocr_service/            # Servicio EasyOCR
-│   │   ├── Dockerfile.gpu
-│   │   ├── docker-compose.yml
-│   │   └── main.py
-│   ├── dataset/                    # Dataset de evaluación
-│   ├── raytune_ocr.py              # Utilidades compartidas Ray Tune
-│   └── results/                    # Resultados de ajuste CSV
-└── .gitea/workflows/ci.yaml        # Pipeline CI/CD
-```
+
+**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 A1.** *Especificaciones del sistema de desarrollo.*
+**Tabla A2.** *Especificaciones del sistema de desarrollo.*
 
 | Componente | Especificación |
 |------------|----------------|
@@ -62,7 +110,7 @@ MastersThesis/
 
 ### Dependencias
 
-**Tabla A2.** *Dependencias del proyecto.*
+**Tabla A3.** *Dependencias del proyecto.*
 
 | Componente | Versión |
 |------------|---------|
@@ -79,8 +127,8 @@ MastersThesis/
 ### PaddleOCR (Puerto 8002)
 
 **Imágenes Docker:**
-- GPU: `seryus.ddns.net/unir/paddle-ocr-gpu`
-- CPU: `seryus.ddns.net/unir/paddle-ocr-cpu`
+- 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
@@ -88,13 +136,13 @@ cd src/paddle_ocr
 # GPU (recomendado)
 docker compose up -d
 
-# CPU (más lento, 126x)
+# 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`
+**Imagen Docker:** [`seryus.ddns.net/unir/doctr-gpu`](https://seryus.ddns.net/unir/-/packages/container/doctr-gpu/latest)
 
 ```bash
 cd src/doctr_service
@@ -105,12 +153,14 @@ docker compose up -d
 
 ### EasyOCR (Puerto 8002)
 
-**Imagen Docker:** `seryus.ddns.net/unir/easyocr-gpu`
+> **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
+# GPU (usar archivo separado para evitar conflicto de puerto)
 docker compose up -d
 ```
 
@@ -181,34 +231,109 @@ analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_
 
 ### Servicios y Puertos
 
-**Tabla A3.** *Servicios Docker y puertos.*
+**Tabla A4.** *Servicios Docker y puertos.*
 
-| Servicio | Puerto | Script de Ajuste |
-|----------|--------|------------------|
-| PaddleOCR | 8002 | `paddle_ocr_payload` |
-| DocTR | 8003 | `doctr_payload` |
-| EasyOCR | 8002 | `easyocr_payload` |
+| 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
 
-Los resultados detallados de las evaluaciones y ajustes de hiperparámetros se encuentran en:
+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.
 
-- [Métricas Generales](metrics/metrics.md) - Comparativa de los tres servicios
-- [PaddleOCR](metrics/metrics_paddle.md) - Mejor precisión (7.76% CER baseline, **1.49% optimizado**)
-- [DocTR](metrics/metrics_doctr.md) - Más rápido (0.50s/página)
-- [EasyOCR](metrics/metrics_easyocr.md) - Balance intermedio
+### Comparativa General de Servicios
 
-### Resumen de Resultados
+**Tabla A5.** *Comparativa de servicios OCR en dataset de 45 páginas (GPU RTX 3060).*
 
-**Tabla A4.** *Resumen de resultados del benchmark por servicio.*
+| 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 |
 
-| Servicio | CER Base | CER Ajustado | Mejora |
-|----------|----------|--------------|--------|
-| **PaddleOCR** | 8.85% | **7.72%** | 12.8% |
-| DocTR | 12.06% | 12.07% | 0% |
-| EasyOCR | 11.23% | 11.14% | 0.8% |
+*Fuente: Benchmark realizado el 2026-01-19. Elaboración propia.*
+
+**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: 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 grande (15-20 páginas) mejoraría la generalizació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 layouts mixtos
+- `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.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** |
+
+*Fuente: Datos CPU de `raytune_paddle_subproc_results_20251207_192320.csv`. Elaboración propia.*
+
+### 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 (~5%) | 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/-/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) |
 
 *Fuente: Elaboración propia.*