From 9f9fda4cc337cd82be51bbe08addaf6562e1b902 Mon Sep 17 00:00:00 2001 From: sergio Date: Tue, 20 Jan 2026 12:11:34 +0100 Subject: [PATCH] doc gen --- .claude/commands/documentation-review.md | 7 +++++- apply_content.py | 2 +- docs/02_contexto_estado_arte.md | 4 +-- docs/03_objetivos_metodologia.md | 4 +-- docs/04_desarrollo_especifico.md | 6 ++--- thesis_output/plantilla_individual.htm | 32 ++++++++++++------------ 6 files changed, 30 insertions(+), 25 deletions(-) diff --git a/.claude/commands/documentation-review.md b/.claude/commands/documentation-review.md index 3d26bdf..8c66992 100644 --- a/.claude/commands/documentation-review.md +++ b/.claude/commands/documentation-review.md @@ -10,8 +10,12 @@ Review and validate the documentation for this Master's Thesis project. - `src/results/*.csv` - Raw data from 64 trials per service 2. **Review UNIR guidelines** for formatting and structure rules: + - **`instructions/plantilla_individual.htm`** - **PRIMARY REFERENCE** for all styling (CSS classes, Word styles) + - **`instructions/plantilla_individual_files/`** - Support files with additional style definitions - `instructions/instrucciones.pdf` - TFE writing instructions - - `instructions/plantilla_individual.pdf` - Official template with required format + - `instructions/plantilla_individual.pdf` - Official template preview + + **IMPORTANT:** When styling elements (tables, figures, notes, quotes), ALWAYS check `plantilla_individual.htm` for existing Word/CSS classes (e.g., `MsoQuote`, `MsoCaption`, `Piedefoto-tabla`). Use these classes instead of custom inline styles. 3. **Validate each documentation file** checking: @@ -49,6 +53,7 @@ Review and validate the documentation for this Master's Thesis project. ``` - Colors: `#0098CD` (UNIR blue for borders/lines), `#E6F4F9` (light blue background) - All diagrams must have a descriptive `title:` in YAML frontmatter +- Titles MUST be quoted: `title: "Descriptive Title"` (not `title: Descriptive Title`) - Titles should describe the diagram content, not generic "Diagrama N" - Verify theme is applied to all diagrams in `docs/*.md` diff --git a/apply_content.py b/apply_content.py index 5a58a5c..576caee 100644 --- a/apply_content.py +++ b/apply_content.py @@ -271,7 +271,7 @@ def parse_md_to_html_blocks(md_content): while i < len(lines) and lines[i].startswith('>'): quote_text += ' ' + lines[i][1:].strip() i += 1 - html_blocks.append(f'

{md_to_html_para(quote_text)}

') + html_blocks.append(f'

{md_to_html_para(quote_text)}

') continue # Bullet list diff --git a/docs/02_contexto_estado_arte.md b/docs/02_contexto_estado_arte.md index 457c120..5651f07 100644 --- a/docs/02_contexto_estado_arte.md +++ b/docs/02_contexto_estado_arte.md @@ -61,7 +61,7 @@ Los sistemas OCR modernos siguen típicamente un pipeline de dos etapas principa ```mermaid --- -title: Pipeline de un sistema OCR moderno +title: "Pipeline de un sistema OCR moderno" config: theme: base themeVariables: @@ -493,7 +493,7 @@ La combinación de Ray Tune con OptunaSearch permite: ```mermaid --- -title: Ciclo de optimización con Ray Tune y Optuna +title: "Ciclo de optimización con Ray Tune y Optuna" config: theme: base themeVariables: diff --git a/docs/03_objetivos_metodologia.md b/docs/03_objetivos_metodologia.md index 05a38c1..f2a23ef 100644 --- a/docs/03_objetivos_metodologia.md +++ b/docs/03_objetivos_metodologia.md @@ -45,7 +45,7 @@ Este capítulo establece los objetivos del trabajo siguiendo la metodología SMA ```mermaid --- -title: Fases de la metodología experimental +title: "Fases de la metodología experimental" config: theme: base themeVariables: @@ -89,7 +89,7 @@ El script `prepare_dataset.ipynb` implementa: ```mermaid --- -title: Estructura del dataset de evaluación +title: "Estructura del dataset de evaluación" config: theme: base themeVariables: diff --git a/docs/04_desarrollo_especifico.md b/docs/04_desarrollo_especifico.md index 34d5a17..bbac85e 100644 --- a/docs/04_desarrollo_especifico.md +++ b/docs/04_desarrollo_especifico.md @@ -272,7 +272,7 @@ Esta arquitectura containerizada permite ejecutar cada componente en su entorno ```mermaid --- -title: Arquitectura de ejecución con Docker Compose +title: "Arquitectura de ejecución con Docker Compose" config: theme: base themeVariables: @@ -340,7 +340,7 @@ La infraestructura del proyecto se basa en contenedores Docker para garantizar r ```mermaid --- -title: Arquitectura de microservicios para optimización OCR +title: "Arquitectura de microservicios para optimización OCR" config: theme: base themeVariables: @@ -425,7 +425,7 @@ El proyecto incluye múltiples archivos Docker Compose para diferentes escenario *Fuente: Elaboración propia.* -> **\* Nota:** EasyOCR y PaddleOCR utilizan el mismo puerto (8002). Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez durante los experimentos. Por esta razón, EasyOCR tiene su propio archivo Docker Compose separado. +> **Nota:** EasyOCR y PaddleOCR utilizan el mismo puerto (8002). Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez durante los experimentos. Por esta razón, EasyOCR tiene su propio archivo Docker Compose separado. ##### Gestión de Volúmenes diff --git a/thesis_output/plantilla_individual.htm b/thesis_output/plantilla_individual.htm index 0aeb5c7..14b65a4 100644 --- a/thesis_output/plantilla_individual.htm +++ b/thesis_output/plantilla_individual.htm @@ -4566,7 +4566,7 @@ mso-bidi-font-family:"Calibri Light";mso-bidi-theme-font:major-latin'>Planteamiento del trabajo

Formulación del problema

El problema central que aborda este trabajo puede formularse de la siguiente manera:

-

¿Es posible mejorar significativamente el rendimiento de modelos OCR preentrenados para documentos en español mediante la optimización sistemática de hiperparámetros, sin requerir fine-tuning ni recursos GPU?

+

¿Es posible mejorar significativamente el rendimiento de modelos OCR preentrenados para documentos en español mediante la optimización sistemática de hiperparámetros, sin requerir fine-tuning ni recursos GPU?

Este planteamiento parte de una observación fundamental: los sistemas OCR modernos exponen múltiples parámetros configurables que afectan su comportamiento durante la inferencia. Estos parámetros incluyen umbrales de detección, opciones de preprocesamiento, y filtros de calidad. En la práctica habitual, estos parámetros se dejan en sus valores por defecto, asumiendo que fueron optimizados por los desarrolladores del modelo. Sin embargo, los valores por defecto representan compromisos generales que pueden no ser óptimos para dominios específicos.

Preguntas de investigación

Este planteamiento se descompone en las siguientes cuestiones específicas:

@@ -4938,7 +4938,7 @@ text-transform:none'>3. SEQ Tabla \* ARABIC 13. Justificación SMART del objetivo general.

Criterio

Cumplimiento

Específico (S)

Se define claramente qué se quiere lograr: optimizar PaddleOCR mediante ajuste de hiperparámetros para documentos en español

Medible (M)

Se establece una métrica cuantificable: CER < 2%

Alcanzable (A)

Es viable dado que: (1) PaddleOCR permite configuración de hiperparámetros, (2) Ray Tune posibilita búsqueda automatizada, (3) Aceleración GPU disponible para experimentación eficiente

Relevante (R)

El impacto es demostrable: mejora la extracción de texto en documentos académicos sin costes adicionales de infraestructura

Temporal (T)

El plazo es un cuatrimestre, correspondiente al TFM

@@ -4946,15 +4946,15 @@ concretos y metodología de trabajo 

Objetivos específicos

OE1: Comparar soluciones OCR de código abierto

-

Evaluar el rendimiento base de EasyOCR, PaddleOCR y DocTR en documentos académicos en español, utilizando CER y WER como métricas, para seleccionar el modelo más prometedor.

+

Evaluar el rendimiento base de EasyOCR, PaddleOCR y DocTR en documentos académicos en español, utilizando CER y WER como métricas, para seleccionar el modelo más prometedor.

OE2: Preparar un dataset de evaluación

-

Construir un dataset estructurado de imágenes de documentos académicos en español con su texto de referencia (ground truth) extraído del PDF original.

+

Construir un dataset estructurado de imágenes de documentos académicos en español con su texto de referencia (ground truth) extraído del PDF original.

OE3: Identificar hiperparámetros críticos

-

Analizar la correlación entre los hiperparámetros de PaddleOCR y las métricas de error para identificar los parámetros con mayor impacto en el rendimiento.

+

Analizar la correlación entre los hiperparámetros de PaddleOCR y las métricas de error para identificar los parámetros con mayor impacto en el rendimiento.

OE4: Optimizar hiperparámetros con Ray Tune

-

Ejecutar una búsqueda automatizada de hiperparámetros utilizando Ray Tune con Optuna, evaluando al menos 50 configuraciones diferentes.

+

Ejecutar una búsqueda automatizada de hiperparámetros utilizando Ray Tune con Optuna, evaluando al menos 50 configuraciones diferentes.

OE5: Validar la configuración optimizada

-

Comparar el rendimiento de la configuración baseline versus la configuración optimizada sobre el dataset completo, documentando la mejora obtenida.

+

Comparar el rendimiento de la configuración baseline versus la configuración optimizada sobre el dataset completo, documentando la mejora obtenida.

Metodología del trabajo

Visión General

Figura 3. Fases de la metodología experimental

@@ -5164,7 +5164,7 @@ color:#0098CD;mso-font-kerning:16.0pt;mso-bidi-font-weight:bold'>·     titulación → titulacióon (carácter duplicado)

·     documento → doccumento (consonante duplicada)

Ejemplo de predicción de PaddleOCR para una página:

-

"Escribe siempre al menos un párrafo de introducción en cada capítulo o apartado, explicando de qué vas a tratar en esa sección. Evita que aparezcan dos encabezados de nivel consecutivos sin ningún texto entre medias. [...] En esta titulacióon se cita de acuerdo con la normativa Apa."

+

"Escribe siempre al menos un párrafo de introducción en cada capítulo o apartado, explicando de qué vas a tratar en esa sección. Evita que aparezcan dos encabezados de nivel consecutivos sin ningún texto entre medias. [...] En esta titulacióon se cita de acuerdo con la normativa Apa."

Errores identificados en este ejemplo:

·     titulacióon en lugar de titulación (carácter duplicado)

·     Apa en lugar de APA (capitalización)

@@ -5282,7 +5282,7 @@ docker compose -f docker-compose.tuning.doctr.yml down

Archivo

Propósito

Servicios

docker-compose.tuning.yml

Optimización principal

RayTune + PaddleOCR + DocTR

docker-compose.tuning.easyocr.yml

Optimización EasyOCR

RayTune + EasyOCR

docker-compose.tuning.paddle.yml

Optimización PaddleOCR

RayTune + PaddleOCR

docker-compose.tuning.doctr.yml

Optimización DocTR

RayTune + DocTR

Fuente: Elaboración propia.

 

-

*\ Nota:** EasyOCR y PaddleOCR utilizan el mismo puerto (8002). Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez durante los experimentos. Por esta razón, EasyOCR tiene su propio archivo Docker Compose separado.

+

Nota: EasyOCR y PaddleOCR utilizan el mismo puerto (8002). Debido a limitaciones de recursos GPU (VRAM insuficiente para ejecutar múltiples modelos OCR simultáneamente), solo se ejecuta un servicio a la vez durante los experimentos. Por esta razón, EasyOCR tiene su propio archivo Docker Compose separado.

Gestión de Volúmenes

Se utilizan volúmenes Docker nombrados para persistir los modelos descargados entre ejecuciones:

Tabla 28. Volúmenes Docker para caché de modelos.

@@ -5445,7 +5445,7 @@ Configuración óptima:

Modelo

CER

Precisión Caracteres

WER

Precisión Palabras

PaddleOCR (Baseline)

8.85%

91.15%

13.05%

86.95%

PaddleOCR-HyperAdjust

7.72%

92.28%

11.40%

88.60%

Fuente: Elaboración propia.

 

-

Nota sobre generalización: El mejor trial individual (5 páginas) alcanzó un CER de 0.79%, cumpliendo el objetivo de CER < 2%. Sin embargo, al aplicar la configuración al dataset completo de 45 páginas, el CER aumentó a 7.72%, evidenciando sobreajuste al subconjunto de entrenamiento. Esta diferencia es un hallazgo importante que se discute en la sección de análisis.

+

Nota sobre generalización: El mejor trial individual (5 páginas) alcanzó un CER de 0.79%, cumpliendo el objetivo de CER < 2%. Sin embargo, al aplicar la configuración al dataset completo de 45 páginas, el CER aumentó a 7.72%, evidenciando sobreajuste al subconjunto de entrenamiento. Esta diferencia es un hallazgo importante que se discute en la sección de análisis.

Métricas de Mejora

Tabla 41. Análisis cuantitativo de la mejora.

Forma de Medición

CER

WER

Valor baseline

8.85%

13.05%

Valor optimizado

7.72%

11.40%

Mejora absoluta

-1.13 pp

-1.65 pp

Reducción relativa del error

12.8%

12.6%

Factor de mejora

1.15×

1.14×

Mejor trial (5 páginas)

0.79%

7.78%

@@ -5464,7 +5464,7 @@ Configuración óptima:

 

*Asumiendo longitud media de palabra = 6.6 caracteres en español.

Interpretación:

-

"La optimización de hiperparámetros logró una mejora del 12.8% en el CER sobre el dataset completo de 45 páginas. Aunque esta mejora es más modesta que la observada en los trials individuales (donde se alcanzó 0.79% CER), demuestra el valor de la optimización sistemática. La diferencia entre el mejor trial (0.79%) y el resultado en dataset completo (7.72%) revela un fenómeno de sobreajuste al subconjunto de 5 páginas usado para evaluación."

+

"La optimización de hiperparámetros logró una mejora del 12.8% en el CER sobre el dataset completo de 45 páginas. Aunque esta mejora es más modesta que la observada en los trials individuales (donde se alcanzó 0.79% CER), demuestra el valor de la optimización sistemática. La diferencia entre el mejor trial (0.79%) y el resultado en dataset completo (7.72%) revela un fenómeno de sobreajuste al subconjunto de 5 páginas usado para evaluación."

Tiempo de Ejecución

Tabla 43. Métricas de tiempo del experimento (GPU).

Métrica

Valor

Tiempo total del experimento

~1.5 horas

Tiempo medio por trial

~4.2 segundos

Tiempo medio por página

0.84 segundos

Variabilidad (std)

0.53 segundos/página

Páginas procesadas totales

320

@@ -5502,7 +5502,7 @@ Configuración óptima:

Aspecto

Objetivo

Resultado (trial)

Resultado (full)

Cumplimiento

Métrica

CER

CER

CER

✓

Umbral

< 2%

0.79%

7.72%

Parcial

Método

Sin fine-tuning

Solo hiperparámetros

Solo hiperparámetros

✓

Hardware

GPU

RTX 3060

RTX 3060

✓

Fuente: Elaboración propia.

 

-

Análisis del cumplimiento: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%), demostrando que la optimización de hiperparámetros puede alcanzar la precisión objetivo. Sin embargo, la validación sobre el dataset completo (7.72%) muestra que la generalización requiere trabajo adicional, como un subconjunto de optimización más representativo o técnicas de regularización.

+

Análisis del cumplimiento: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%), demostrando que la optimización de hiperparámetros puede alcanzar la precisión objetivo. Sin embargo, la validación sobre el dataset completo (7.72%) muestra que la generalización requiere trabajo adicional, como un subconjunto de optimización más representativo o técnicas de regularización.

Análisis Detallado de Hiperparámetros

Jerarquía de Importancia

Basándose en el análisis de los resultados de optimización:

@@ -5554,7 +5554,7 @@ Configuración óptima:

Objetivo

Descripción

Resultado

Estado

OE1

Comparar soluciones OCR

EasyOCR, PaddleOCR, DocTR evaluados; PaddleOCR seleccionado

✓ Cumplido

OE2

Preparar dataset de evaluación

45 páginas con ground truth

✓ Cumplido

OE3

Identificar hiperparámetros críticos

textline_orientation, use_doc_orientation_classify, text_det_thresh identificados

✓ Cumplido

OE4

Optimizar con Ray Tune (≥50 trials)

64 trials ejecutados con GPU

✓ Cumplido

OE5

Validar configuración optimizada

CER: 8.85% → 7.72% (dataset), 0.79% (mejor trial)

✓ Parcial

Fuente: Elaboración propia.

 

-

Nota sobre OE5: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%). La validación sobre el dataset completo (7.72%) muestra que la generalización requiere mayor trabajo, identificándose como línea de trabajo futuro.

+

Nota sobre OE5: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%). La validación sobre el dataset completo (7.72%) muestra que la generalización requiere mayor trabajo, identificándose como línea de trabajo futuro.

Limitaciones del Estudio

Limitaciones de Generalización

1.   Tipo de documento único: Solo se evaluaron documentos académicos de UNIR. La configuración óptima puede no ser transferible a otros tipos de documentos (facturas, formularios, contratos).

@@ -5657,7 +5657,7 @@ y trabajo futuro

Este capít

Métrica

Objetivo

Mejor Trial

Dataset Completo

Cumplimiento

CER

< 2%

0.79%

7.72%

✓ Parcial

Fuente: Elaboración propia.

 

-

Nota: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%, 5 páginas). La validación sobre el conjunto de datos completo (45 páginas) muestra un CER de 7.72%, evidenciando sobreajuste al subconjunto de optimización. Esta diferencia se analiza en detalle en el Capítulo 4.

+

Nota: El objetivo de CER < 2% se cumple en el mejor trial individual (0.79%, 5 páginas). La validación sobre el conjunto de datos completo (45 páginas) muestra un CER de 7.72%, evidenciando sobreajuste al subconjunto de optimización. Esta diferencia se analiza en detalle en el Capítulo 4.

Conclusiones Específicas

Respecto a OE1 (Comparativa de soluciones OCR):

·     Se evaluaron tres soluciones OCR de código abierto: EasyOCR, PaddleOCR (PP-OCRv5) y DocTR

@@ -5792,7 +5792,7 @@ docker compose -f docker-compose.cpu-registry.yml up -d

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

+

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

cd src/easyocr_service
 
@@ -5850,7 +5850,7 @@ analyze_results(results, prefix='raytune_paddle', config_keys=PADDLE_OCR_CONFIG_
 
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.

+
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:

 
·     Métricas Generales - Comparativa de los tres servicios