assit commands for claude

2026-01-20 11:35:56 +01:00
parent c7ed7b2b9c
commit 6b98aeacac
26 changed files with 1135 additions and 609 deletions
--- a/README.md
+++ b/README.md
@@ -10,36 +10,39 @@

 ## Objetivo

-Optimizar el rendimiento de PaddleOCR para documentos académicos en español mediante ajuste de hiperparámetros, alcanzando un **CER inferior al 2%** sin requerir fine-tuning del modelo ni recursos GPU dedicados.
+Optimizar el rendimiento de PaddleOCR para documentos académicos en español mediante ajuste de hiperparámetros, alcanzando un **CER inferior al 2%** sin requerir fine-tuning del modelo.

-**Resultado alcanzado:** CER = **1.49%** (objetivo cumplido)
+**Resultado alcanzado:**
+- **Mejor trial (5 páginas):** CER = **0.79%** ✓ objetivo cumplido
+- **Dataset completo (45 páginas):** CER = **7.72%** (mejora del 12.8% respecto a baseline)

 ---

 ## Resultados Principales

-**Tabla.** *Comparación de métricas OCR entre configuración baseline y optimizada.*
+**Tabla.** *Comparación de métricas OCR entre configuración baseline y optimizada (GPU).*

 | Modelo | CER | Precisión Caracteres | WER | Precisión Palabras |
 |--------|-----|---------------------|-----|-------------------|
-| PaddleOCR (Baseline) | 7.78% | 92.22% | 14.94% | 85.06% |
-| **PaddleOCR-HyperAdjust** | **1.49%** | **98.51%** | **7.62%** | **92.38%** |
+| PaddleOCR (Baseline) | 8.85% | 91.15% | 13.05% | 86.95% |
+| **PaddleOCR-HyperAdjust (dataset)** | **7.72%** | **92.28%** | **11.40%** | **88.60%** |
+| **PaddleOCR-HyperAdjust (mejor trial)** | **0.79%** | **99.21%** | **7.78%** | **92.22%** |

-*Fuente: Elaboración propia.*
+*Fuente: [`src/results/raytune_paddle_results_20260119_122609.csv`](src/results/raytune_paddle_results_20260119_122609.csv)*

-**Mejora obtenida:** Reducción del CER en un **80.9%**
+**Mejora obtenida (dataset completo):** Reducción del CER en un **12.8%**

-### Configuración Óptima Encontrada
+### Configuración Óptima Encontrada (GPU)

 ```python
 config_optimizada = {
-    "textline_orientation": True,           # CRÍTICO - reduce CER ~70%
-    "use_doc_orientation_classify": False,
+    "textline_orientation": True,                # CRÍTICO para layouts complejos
+    "use_doc_orientation_classify": True,        # Mejora orientación de documento
    "use_doc_unwarping": False,
-    "text_det_thresh": 0.4690,              # Correlación -0.52 con CER
-    "text_det_box_thresh": 0.5412,
+    "text_det_thresh": 0.0462,                   # Correlación -0.52 con CER
+    "text_det_box_thresh": 0.4862,
    "text_det_unclip_ratio": 0.0,
-    "text_rec_score_thresh": 0.6350,
+    "text_rec_score_thresh": 0.5658,
 }
 ```

@@ -68,7 +71,7 @@ PDF (académico UNIR)
 | Algoritmo de búsqueda | OptunaSearch (TPE) |
 | Métrica objetivo | CER (minimizar) |
 | Trials concurrentes | 2 |
-| Tiempo total | ~6 horas (CPU) |
+| Tiempo total | ~1.5 horas (GPU RTX 3060) |

 *Fuente: Elaboración propia.*

@@ -76,63 +79,95 @@ PDF (académico UNIR)

 ## Estructura del Repositorio

+```mermaid
+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/                    # Capítulos del TFM en Markdown (estructura UNIR)
-│   ├── 00_resumen.md                      # Resumen + Abstract + Keywords
-│   ├── 01_introduccion.md                 # Cap. 1: Introducción (1.1-1.3)
-│   ├── 02_contexto_estado_arte.md         # Cap. 2: Contexto y estado del arte (2.1-2.3)
-│   ├── 03_objetivos_metodologia.md        # Cap. 3: Objetivos y metodología (3.1-3.4)
-│   ├── 04_desarrollo_especifico.md        # Cap. 4: Desarrollo específico (4.1-4.3)
-│   ├── 05_conclusiones_trabajo_futuro.md  # Cap. 5: Conclusiones (5.1-5.2)
-│   ├── 06_referencias_bibliograficas.md   # Referencias bibliográficas (APA)
-│   └── 07_anexo_a.md                      # Anexo A: Código fuente y datos
-├── thesis_output/           # Documento final generado
-│   ├── plantilla_individual.htm           # TFM completo (abrir en Word)
-│   └── figures/                           # Figuras generadas desde Mermaid
-│       ├── figura_1.png ... figura_7.png
-│       └── figures_manifest.json
-├── src/
-│   ├── paddle_ocr_fine_tune_unir_raytune.ipynb  # Experimento principal
-│   ├── paddle_ocr_tuning.py                      # Script de evaluación CLI
-│   ├── dataset_manager.py                        # Clase ImageTextDataset
-│   ├── prepare_dataset.ipynb                     # Preparación del dataset
-│   └── raytune_paddle_subproc_results_*.csv      # Resultados de 64 trials
-├── results/                 # Resultados de benchmarks
-├── instructions/            # Plantilla e instrucciones UNIR
-│   ├── instrucciones.pdf
-│   ├── plantilla_individual.pdf
-│   └── plantilla_individual.htm
-├── apply_content.py         # Genera documento TFM desde docs/ + plantilla
-├── generate_mermaid_figures.py  # Convierte diagramas Mermaid a PNG
-├── ocr_benchmark_notebook.ipynb  # Benchmark comparativo inicial
-└── README.md
-```
+
+**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 |

 ---

 ## Hallazgos Clave

-1. **`textline_orientation=True` es crítico**: Reduce el CER en un 69.7%. Para documentos con layouts mixtos (tablas, encabezados), la clasificación de orientación de línea es esencial.
+1. **`textline_orientation=True` es crítico**: Para documentos con layouts mixtos (tablas, encabezados), la clasificación de orientación de línea es esencial.

-2. **Umbral `text_det_thresh` importante**: Correlación -0.52 con CER. Valores óptimos entre 0.4-0.5. Valores < 0.1 causan fallos catastróficos (CER >40%).
+2. **`use_doc_orientation_classify=True` mejora resultados**: En la configuración GPU, la clasificación de orientación del documento demostró impacto positivo.

-3. **Componentes innecesarios para PDFs digitales**: `use_doc_orientation_classify` y `use_doc_unwarping` no mejoran el rendimiento en documentos académicos digitales.
+3. **Umbral `text_det_thresh` importante**: Correlación -0.52 con CER. En GPU, el valor óptimo fue 0.0462. Valores < 0.01 causan fallos catastróficos (CER >40%).
+
+4. **`use_doc_unwarping` innecesario para PDFs digitales**: La corrección de deformación no mejora el rendimiento en documentos académicos digitales.

 ---

 ## Rendimiento GPU

-Se realizó una validación adicional con aceleración GPU para evaluar la viabilidad práctica del enfoque en escenarios de producción.
+Los experimentos principales se ejecutaron con aceleración GPU para maximizar la eficiencia de la exploración de hiperparámetros.

 **Tabla.** *Comparación de rendimiento CPU vs GPU.*

 | Métrica | CPU | GPU (RTX 3060) | Aceleración |
 |---------|-----|----------------|-------------|
-| Tiempo/Página | 69.4s | 0.55s | **126x** |
-| Dataset completo (45 páginas) | ~52 min | ~25 seg | **126x** |
+| Tiempo/Página | 69.4s | 0.84s | **82x** |
+| Dataset completo (45 páginas) | ~52 min | ~38 seg | **82x** |
+| 64 trials completos | ~6.4 horas | ~1.5 horas | **4.3x** |

-*Fuente: Elaboración propia.*
+*Fuente: [`src/raytune_paddle_subproc_results_20251207_192320.csv`](src/raytune_paddle_subproc_results_20251207_192320.csv) (CPU) y [`src/results/raytune_paddle_results_20260119_122609.csv`](src/results/raytune_paddle_results_20260119_122609.csv) (GPU).*

 ### Recomendación de Modelos

@@ -145,7 +180,7 @@ Se realizó una validación adicional con aceleración GPU para evaluar la viabi

 *Fuente: Elaboración propia.*

-**Conclusión:** Para hardware con VRAM limitada (≤6 GB), los modelos Mobile ofrecen el mejor balance entre precisión y recursos. La aceleración GPU hace viable el procesamiento en tiempo real.
+**Conclusión:** Para hardware con VRAM limitada (≤6 GB), los modelos Mobile ofrecen el mejor balance entre precisión y recursos. La aceleración GPU (82×) hace viable la exploración exhaustiva de hiperparámetros y el procesamiento en tiempo real.

 ---

@@ -196,101 +231,8 @@ python src/paddle_ocr_tuning.py \
 ## Fuentes de Datos

 - **Dataset**: 2 documentos UNIR (45 páginas total): Instrucciones TFE (24 pág.) + Plantilla TFE (21 pág.)
- **Resultados Ray Tune (PRINCIPAL)**: `src/raytune_paddle_subproc_results_20251207_192320.csv` - 64 trials de optimización con todas las métricas y configuraciones
-
---
-
-## Generación del Documento TFM
-
-### Prerrequisitos
-
-```bash
-# Instalar dependencias de Python
-pip install beautifulsoup4
-
-# Instalar mermaid-cli para generación de figuras
-npm install @mermaid-js/mermaid-cli
-```
-
-### Flujo de Generación del Documento
-
-El documento TFM se genera en **3 pasos** que deben ejecutarse en orden:
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  PASO 1: generate_mermaid_figures.py                                │
-│  ────────────────────────────────────────────────────────────────── │
-│  • Lee diagramas Mermaid de docs/*.md                               │
-│  • Genera thesis_output/figures/figura_*.png                        │
-│  • Crea figures_manifest.json con títulos                           │
-└─────────────────────────────────────────────────────────────────────┘
-                                ↓
-┌─────────────────────────────────────────────────────────────────────┐
-│  PASO 2: apply_content.py                                           │
-│  ────────────────────────────────────────────────────────────────── │
-│  • Lee plantilla desde instructions/plantilla_individual.htm        │
-│  • Inserta contenido de docs/*.md en cada capítulo                  │
-│  • Genera tablas con formato APA y figuras con referencias          │
-│  • Guarda en thesis_output/plantilla_individual.htm                 │
-└─────────────────────────────────────────────────────────────────────┘
-                                ↓
-┌─────────────────────────────────────────────────────────────────────┐
-│  PASO 3: Abrir en Microsoft Word                                    │
-│  ────────────────────────────────────────────────────────────────── │
-│  • Abrir thesis_output/plantilla_individual.htm                     │
-│  • Ctrl+A → F9 para actualizar índices (contenidos/figuras/tablas)  │
-│  • Guardar como TFM_Sergio_Jimenez.docx                             │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### Comandos de Generación
-
-```bash
-# Desde el directorio raíz del proyecto:
-
-# PASO 1: Generar figuras PNG desde diagramas Mermaid
-python3 generate_mermaid_figures.py
-# Output: thesis_output/figures/figura_1.png ... figura_8.png
-
-# PASO 2: Aplicar contenido de docs/ a la plantilla UNIR
-python3 apply_content.py
-# Output: thesis_output/plantilla_individual.htm
-
-# PASO 3: Abrir en Word y finalizar documento
-# - Abrir thesis_output/plantilla_individual.htm en Microsoft Word
-# - Ctrl+A → F9 para actualizar todos los índices
-# - IMPORTANTE: Ajustar manualmente el tamaño de las imágenes para legibilidad
-#   (seleccionar imagen → clic derecho → Tamaño y posición → ajustar al ancho de página)
-# - Guardar como .docx
-```
-
-### Notas Importantes para Edición en Word
-
-1. **Ajuste de imágenes**: Las figuras Mermaid pueden requerir ajuste manual de tamaño para ser legibles. Seleccionar cada imagen y ajustar al ancho de texto (~16cm).
-
-2. **Actualización de índices**: Después de cualquier cambio, usar Ctrl+A → F9 para regenerar índices.
-
-3. **Formato de código**: Los bloques de código usan Consolas 9pt. Verificar que no se corten líneas largas.
-
-### Archivos de Entrada y Salida
-
-**Tabla.** *Relación de scripts de generación con sus archivos de entrada y salida.*
-
-| Script | Entrada | Salida |
-|--------|---------|--------|
-| `generate_mermaid_figures.py` | `docs/*.md` (bloques ```mermaid```) | `thesis_output/figures/figura_*.png`, `figures_manifest.json` |
-| `apply_content.py` | `instructions/plantilla_individual.htm`, `docs/*.md`, `thesis_output/figures/*.png` | `thesis_output/plantilla_individual.htm` |
-
-*Fuente: Elaboración propia.*
-
-### Contenido Generado Automáticamente
-
- **53 tablas** con formato APA (Tabla X. *Título* + Fuente: ...)
- **8 figuras** desde Mermaid (Figura X. *Título* + Fuente: Elaboración propia)
- **25 referencias** en formato APA con sangría francesa
- **Resumen/Abstract** con palabras clave
- **Índices** actualizables (contenidos, figuras, tablas)
- Eliminación automática de textos de instrucción de la plantilla
+- **Resultados GPU (PRINCIPAL)**: [`src/results/raytune_paddle_results_20260119_122609.csv`](src/results/raytune_paddle_results_20260119_122609.csv) - 64 trials de optimización con GPU
+- **Resultados CPU (referencia de tiempo)**: [`src/raytune_paddle_subproc_results_20251207_192320.csv`](src/raytune_paddle_subproc_results_20251207_192320.csv) - Para comparación de rendimiento CPU vs GPU

 ---

@@ -301,10 +243,10 @@ python3 apply_content.py
 Este trabajo adoptó la estrategia de **optimización de hiperparámetros** en lugar de **fine-tuning** debido a que el fine-tuning de modelos OCR requiere datasets etiquetados extensos y tiempos de entrenamiento prohibitivos.

 **Hardware utilizado:**
- **Optimización (CPU)**: Los 64 trials de Ray Tune se ejecutaron en CPU (~69s/página)
- **Validación (GPU)**: Se validó con RTX 3060 logrando 126x de aceleración (0.55s/página)
+- **Optimización (GPU)**: Los 64 trials de Ray Tune se ejecutaron con GPU RTX 3060 (~0.84s/página, ~1.5 horas total)
+- **Referencia CPU**: Se midió el tiempo en CPU para comparación (~69s/página)

-La optimización de hiperparámetros demostró ser una **alternativa efectiva** al fine-tuning, logrando una reducción del 80.9% en el CER sin reentrenar el modelo.
+La optimización de hiperparámetros demostró ser una **alternativa viable** al fine-tuning. El mejor trial alcanzó un CER de 0.79%, mientras que la validación sobre el dataset completo logró una mejora del 12.8%.

 ### Tareas Pendientes

@@ -321,9 +263,10 @@ La optimización de hiperparámetros demostró ser una **alternativa efectiva**

 #### Completadas
 - [x] **Estructura docs/ según plantilla UNIR**
- [x] **Diagramas Mermaid**: 8 figuras generadas
+- [x] **Diagramas Mermaid**: 8+ figuras generadas
 - [x] **Documento TFM unificado**: Script `apply_content.py`
- [x] **Evaluación con GPU**: RTX 3060 - 126x más rápido (0.55s/página)
+- [x] **Optimización con GPU**: RTX 3060 - 82× más rápido (0.84s/página)
+- [x] **Infraestructura Docker**: 5 imágenes (PaddleOCR, EasyOCR, DocTR, RayTune)

 ### Dataset