# Resultados de Ajuste de Hiperparámetros PaddleOCR

> **Nota:** Los resultados de este documento corresponden a la fase de validación GPU con 45 páginas. El resultado oficial del TFM es **CER 1.49%** obtenido en la validación final de 24 páginas con la configuración optimizada (ver `docs/04_desarrollo_especifico.md`).

**Fecha de Ajuste:** 2026-01-19
**Plataforma:** NVIDIA RTX 3060 Laptop GPU
**Muestras:** 64
**Páginas de Prueba:** 5-10 (primer documento)

### ¿Por Qué Solo 5 Páginas?

Usamos solo 5 páginas (páginas 5-10) para el ajuste de hiperparámetros porque:

1. **Velocidad**: 64 pruebas × 5 páginas = 320 evaluaciones de página. Con 45 páginas, serían 2,880 evaluaciones (~9x más tiempo)
2. **Eficiencia de recursos**: Cada prueba toma ~3-10 segundos en GPU; el dataset completo tomaría ~1 hora por prueba en CPU

**Riesgo de Sobreajuste**: El ajuste de hiperparámetros en un subconjunto pequeño PUEDE causar sobreajuste. Nuestros resultados confirman esto:
- Subconjunto de ajuste: **90% mejora** (0.79% CER)
- Dataset completo: **12.8% mejora** (7.72% CER)

La diferencia dramática muestra que los hiperparámetros se sobreajustaron parcialmente a las páginas 5-10. Un subconjunto de ajuste más grande (ej. 15-20 páginas) podría producir parámetros que generalicen mejor, pero aumentaría el tiempo de ajuste proporcionalmente.

## Evaluación del Dataset Completo (45 páginas)

| Métrica | Base | Ajustado | Mejora |
|---------|------|----------|--------|
| **CER** | 8.85% | **7.72%** | **12.8%** |
| **WER** | 13.05% | **11.40%** | **12.6%** |
| Tiempo/Página | 0.51s | 0.55s | - |

## Resultados del Subconjunto de Ajuste (páginas 5-10)

| Métrica | Base | Ajustado | Mejora |
|---------|------|----------|--------|
| **CER** | 7.76% | **0.79%** | **90%** |
| **WER** | 11.62% | **7.78%** | **33%** |

> Nota: El subconjunto de ajuste mostró mayores mejoras, sugiriendo que algunos hiperparámetros son específicos de la página.

## Mejor Configuración Encontrada

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

1. **textline_orientation: true** - Crítico para la precisión
2. **use_doc_orientation_classify: true** - Ayuda con la detección de orientación de página
3. **use_doc_unwarping: false** - El enderezamiento de documentos perjudica la precisión en este dataset
4. **Bajo text_det_thresh (0.0462)** - Detección de texto más sensible ayuda
5. **Mayor text_rec_score_thresh (0.5658)** - Filtra reconocimientos de baja confianza

## Impacto de Parámetros

Parámetros que mejoraron la precisión:
- `textline_orientation=True` consistentemente en los mejores resultados
- `use_doc_orientation_classify=True` en las mejores pruebas
- Valores más bajos de `text_det_thresh` (0.04-0.10)

Parámetros que perjudicaron la precisión:
- `use_doc_unwarping=True` aumentó el CER significativamente
- `text_det_box_thresh` muy bajo (<0.01) causó problemas

## Evaluación del Dataset Completo

**Estado:** Completado

```bash
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
  }'
```

**Resultado:** CER 7.72%, WER 11.40%, 0.55s/página

## Configuración del Modelo

### Modelo Actual (Correcto para Español)

| Componente | Modelo | Estado |
|------------|--------|--------|
| Detección | `PP-OCRv5_mobile_det` | Correcto |
| Reconocimiento | `PP-OCRv5_mobile_rec` | Correcto |

Los modelos PP-OCRv5 mobile soportan múltiples idiomas incluyendo español con buen manejo de diacríticos.

### Nota sobre Modelos Server

PaddleOCR ofrece modelos "server" más precisos:
- `PP-OCRv5_server_det` + `PP-OCRv5_server_rec`
- Requieren ~5.3 GB VRAM

**Limitación:** En la RTX 3060 (5.66 GB VRAM) los modelos server causan **OOM (Out of Memory)** en la página 2. Los modelos mobile usados (7.72% CER) son la mejor opción práctica para este hardware.

Para hardware con más VRAM (8+ GB), los modelos server podrían mejorar la precisión.

## Análisis de Errores del Debugset

### Errores Observados

| Ground Truth | PaddleOCR | Tipo de Error |
|--------------|-----------|---------------|
| `bibliografía` | `bibliografia` | Acento omitido |
| `amplían` | `amplian` | Acento omitido |
| `, debes` | `， debes` | Coma Unicode china |
| Líneas separadas | Footer fusionado | Estructura menor |

### Fortalezas

- **Preserva estructura de líneas**: Mantiene saltos de línea correctamente
- **Buen manejo de español**: La mayoría de acentos se reconocen bien
- **Bajo ruido**: No inserta caracteres espurios

### ¿Fine-tuning Recomendado?

**No.** Con 7.72% CER, PaddleOCR ya tiene excelente precisión para documentos españoles. Los errores observados son menores:

- Acentos omitidos: ~5% de casos
- Puntuación Unicode: Muy ocasional
- Impacto en legibilidad: Mínimo

El esfuerzo de fine-tuning no se justifica para ganancias marginales. Para casos de uso críticos donde se requiera <5% CER, considerar post-procesamiento con corrector ortográfico