feat: Agregar soporte OCR con Tesseract para PDFs escaneados
- Integrar Tesseract OCR para leer PDFs escaneados automáticamente - Detectar automáticamente si el PDF tiene texto o requiere OCR - Agregar servicio ocr_service.py con funciones de OCR - Actualizar Dockerfile con tesseract-ocr, tesseract-ocr-spa y poppler-utils - Agregar variables de configuración OCR (OCR_ENABLED, OCR_LANGUAGE, OCR_DPI, OCR_TIMEOUT) - Crear endpoint de debug para ver texto extraído (/api/v1/debug/extract-text) - Agregar scripts de instalación y prueba (install_ocr.ps1, test_ocr.py, debug_pdf.ps1) - Documentación completa (OCR_SETUP.md, DOCKER_OCR.md, COMO_PROBAR.md) - Actualizar docker-compose.yml con variables de entorno OCR - Modificar pdf_text.py para usar OCR cuando sea necesario - Actualizar requirements.txt con pytesseract, Pillow, pdf2image
This commit is contained in:
Ernesto Herrera
275
OCR_SETUP.md
Normal file
275
OCR_SETUP.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Guía de Instalación y Configuración de OCR
|
||||
|
||||
## <20> ¿Usas Docker? (Recomendado)
|
||||
|
||||
Si usas **Docker Compose**, **NO necesitas instalar nada localmente**. Todo está incluido en el contenedor.
|
||||
|
||||
### Instalación con Docker
|
||||
|
||||
1. **Asegúrate de tener tu archivo `.env` configurado:**
|
||||
```env
|
||||
OCR_ENABLED=true
|
||||
OCR_LANGUAGE=spa
|
||||
OCR_DPI=300
|
||||
OCR_TIMEOUT=300
|
||||
```
|
||||
|
||||
2. **Construir y levantar los contenedores:**
|
||||
```bash
|
||||
docker-compose build
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
3. **Verificar que Tesseract está instalado en el contenedor:**
|
||||
```bash
|
||||
docker exec mve-incrementables-parser tesseract --version
|
||||
docker exec mve-incrementables-parser tesseract --list-langs
|
||||
```
|
||||
|
||||
¡Eso es todo! El Dockerfile ya incluye:
|
||||
- ✅ Tesseract OCR
|
||||
- ✅ Paquete de idioma español (spa)
|
||||
- ✅ Poppler-utils (para conversión PDF a imagen)
|
||||
- ✅ Todas las dependencias Python
|
||||
|
||||
**Salta al final de este documento para ver cómo probar**.
|
||||
|
||||
---
|
||||
|
||||
## 💻 Instalación Local (Sin Docker)
|
||||
|
||||
Solo sigue estas instrucciones si **NO usas Docker** y ejecutas el servicio directamente en tu máquina.
|
||||
|
||||
## <20>📋 Requisitos
|
||||
|
||||
El sistema ahora soporta **OCR (Reconocimiento Óptico de Caracteres)** usando Tesseract para leer PDFs escaneados o no editables.
|
||||
|
||||
## 🔧 Instalación de Tesseract
|
||||
|
||||
### Windows
|
||||
|
||||
1. **Descargar el instalador:**
|
||||
- Visita: https://github.com/UB-Mannheim/tesseract/wiki
|
||||
- Descarga `tesseract-ocr-w64-setup-5.3.x.exe` (versión más reciente)
|
||||
|
||||
2. **Instalar Tesseract:**
|
||||
- Ejecuta el instalador
|
||||
- **IMPORTANTE**: Asegúrate de instalar el paquete de idioma **Español (spa)** durante la instalación
|
||||
- Ruta recomendada: `C:\Program Files\Tesseract-OCR`
|
||||
|
||||
3. **Agregar Tesseract al PATH:**
|
||||
- Botón derecho en "Este equipo" → Propiedades → Configuración avanzada del sistema
|
||||
- Variables de entorno → Path → Editar → Nuevo
|
||||
- Agregar: `C:\Program Files\Tesseract-OCR`
|
||||
- Guardar y reiniciar la terminal
|
||||
|
||||
4. **Verificar instalación:**
|
||||
```powershell
|
||||
tesseract --version
|
||||
```
|
||||
Deberías ver algo como: `tesseract 5.3.x`
|
||||
|
||||
5. **Verificar idioma español:**
|
||||
```powershell
|
||||
tesseract --list-langs
|
||||
```
|
||||
Deberías ver `spa` en la lista
|
||||
|
||||
### Linux (Ubuntu/Debian)
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install tesseract-ocr tesseract-ocr-spa
|
||||
tesseract --version
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
```bash
|
||||
brew install tesseract tesseract-lang
|
||||
```
|
||||
|
||||
## 📦 Instalación de Dependencias Python
|
||||
|
||||
```powershell
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Esto instalará:
|
||||
- `pytesseract` - Interface Python para Tesseract
|
||||
- `Pillow` - Procesamiento de imágenes
|
||||
- `pdf2image` - Conversión de PDF a imágenes
|
||||
|
||||
**Nota para Windows**: También necesitas instalar **poppler**:
|
||||
1. Descarga poppler para Windows: https://github.com/oschwartz10612/poppler-windows/releases
|
||||
2. Extrae el archivo ZIP
|
||||
3. Agrega `poppler-xx\Library\bin` al PATH del sistema
|
||||
|
||||
## ⚙️ Configuración
|
||||
|
||||
Edita tu archivo `.env` para configurar el OCR:
|
||||
|
||||
```env
|
||||
# OCR Settings
|
||||
OCR_ENABLED=true # true para habilitar OCR, false para deshabilitarlo
|
||||
OCR_LANGUAGE=spa # "spa" para español, "eng" para inglés
|
||||
OCR_DPI=300 # Calidad de escaneo (300 recomendado, más alto = más lento)
|
||||
OCR_TIMEOUT=300 # Tiempo máximo en segundos para procesar
|
||||
```
|
||||
|
||||
## 🚀 Cómo Funciona
|
||||
|
||||
El sistema ahora funciona de manera **inteligente y automática**:
|
||||
|
||||
### 1. PDFs Editables (con texto seleccionable)
|
||||
- Se extrae el texto normalmente usando PyMuPDF o pdfplumber
|
||||
- **Rápido** y eficiente
|
||||
- No usa OCR
|
||||
|
||||
### 2. PDFs Escaneados (imágenes, sin texto)
|
||||
- El sistema **detecta automáticamente** que el PDF no tiene texto
|
||||
- Activa el OCR automáticamente
|
||||
- Extrae el texto de las imágenes usando Tesseract
|
||||
- **Más lento** pero funcional
|
||||
|
||||
### 3. Proceso Automático
|
||||
```
|
||||
PDF recibido
|
||||
↓
|
||||
Intentar extracción normal (PyMuPDF)
|
||||
↓
|
||||
¿Tiene texto? → SÍ → Retornar texto
|
||||
↓
|
||||
NO
|
||||
↓
|
||||
¿OCR habilitado? → NO → Error
|
||||
↓
|
||||
SÍ
|
||||
↓
|
||||
Convertir PDF a imágenes
|
||||
↓
|
||||
Aplicar OCR a cada página
|
||||
↓
|
||||
Retornar texto extraído
|
||||
```
|
||||
|
||||
## 📝 Ejemplo de Uso
|
||||
|
||||
```python
|
||||
from app.services.pdf_text import extract_text_from_pdf
|
||||
|
||||
# Leer PDF
|
||||
with open("documento.pdf", "rb") as f:
|
||||
pdf_bytes = f.read()
|
||||
|
||||
# Extraer texto (OCR automático si es necesario)
|
||||
text, pages, method = extract_text_from_pdf(
|
||||
pdf_bytes,
|
||||
enable_ocr=True, # Habilitar OCR
|
||||
ocr_lang="spa" # Idioma español
|
||||
)
|
||||
|
||||
print(f"Método usado: {method}") # "pymupdf", "pdfplumber", o "ocr"
|
||||
print(f"Páginas: {pages}")
|
||||
print(f"Texto extraído: {text[:500]}...")
|
||||
```
|
||||
|
||||
## 🔍 Métodos de Extracción
|
||||
|
||||
El sistema retorna uno de estos métodos en `method`:
|
||||
|
||||
- **`pymupdf`**: Extracción exitosa con PyMuPDF (texto seleccionable)
|
||||
- **`pdfplumber`**: Extracción con pdfplumber (fallback)
|
||||
- **`ocr`**: Texto extraído usando OCR (PDF escaneado)
|
||||
|
||||
## ⚡ Rendimiento
|
||||
|
||||
### PDFs Editables
|
||||
- ⚡ **Muy rápido**: < 1 segundo para documentos de 10 páginas
|
||||
- 💾 Bajo uso de CPU y memoria
|
||||
|
||||
### PDFs Escaneados (OCR)
|
||||
- 🐌 **Más lento**: 5-30 segundos por página (depende de DPI)
|
||||
- 💻 Mayor uso de CPU y memoria
|
||||
- 📊 Calidad depende de:
|
||||
- Resolución del escaneo original
|
||||
- Claridad del texto en la imagen
|
||||
- DPI configurado (más alto = mejor pero más lento)
|
||||
|
||||
### Optimización
|
||||
Para mejorar velocidad del OCR:
|
||||
- Reducir `OCR_DPI` a 200 (menos calidad, más rápido)
|
||||
- Usar procesamiento asíncrono con Celery (ya implementado)
|
||||
|
||||
## 🧪 Pruebas
|
||||
|
||||
### Con Docker
|
||||
|
||||
```bash
|
||||
# Verificar Tesseract en el contenedor
|
||||
docker exec mve-incrementables-parser tesseract --version
|
||||
docker exec mve-incrementables-parser tesseract --list-langs
|
||||
|
||||
# Probar el endpoint con un PDF
|
||||
curl -X POST http://localhost:9876/api/v1/incrementables/parse \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-F "file=@documento_escaneado.pdf"
|
||||
```
|
||||
|
||||
### Local (sin Docker)
|
||||
|
||||
Para probar con un PDF escaneado:
|
||||
|
||||
```powershell
|
||||
# Usando el endpoint síncrono
|
||||
curl -X POST http://localhost:8000/api/v1/incrementables/parse \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-F "file=@documento_escaneado.pdf"
|
||||
|
||||
# Usando el endpoint asíncrono (recomendado para OCR)
|
||||
curl -X POST http://localhost:8000/api/v1/incrementables/parse-async \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-F "file=@documento_escaneado.pdf"
|
||||
```
|
||||
|
||||
## 🐛 Solución de Problemas
|
||||
|
||||
### Error: "tesseract is not installed"
|
||||
- Verifica que Tesseract esté instalado: `tesseract --version`
|
||||
- Verifica que esté en el PATH del sistema
|
||||
- Reinicia la terminal/IDE después de agregar al PATH
|
||||
|
||||
### Error: "Failed to load language 'spa'"
|
||||
- Instala el paquete de idioma español
|
||||
- Windows: Reinstala Tesseract y marca la opción "Spanish language data"
|
||||
- Linux: `sudo apt install tesseract-ocr-spa`
|
||||
|
||||
### Error: "Unable to load library 'libpoppler'"
|
||||
- Windows: Instala poppler y agrégalo al PATH
|
||||
- Linux: `sudo apt install poppler-utils`
|
||||
- macOS: `brew install poppler`
|
||||
|
||||
### OCR muy lento
|
||||
- Reduce `OCR_DPI` en el archivo `.env`
|
||||
- Usa el endpoint asíncrono para procesar en background
|
||||
- Considera procesar solo las páginas necesarias
|
||||
|
||||
### OCR no detecta texto correctamente
|
||||
- Aumenta `OCR_DPI` a 400 o 600
|
||||
- Verifica que el PDF escaneado tenga buena calidad
|
||||
- Prueba con otro idioma si el documento está en inglés: `OCR_LANGUAGE=eng`
|
||||
|
||||
## 📚 Recursos Adicionales
|
||||
|
||||
- [Documentación Tesseract](https://github.com/tesseract-ocr/tesseract)
|
||||
- [pytesseract GitHub](https://github.com/madmaze/pytesseract)
|
||||
- [pdf2image Documentation](https://github.com/Belval/pdf2image)
|
||||
|
||||
## 🎯 Próximos Pasos
|
||||
|
||||
Para mejorar aún más:
|
||||
1. **Pre-procesamiento de imágenes**: Aplicar filtros para mejorar calidad
|
||||
2. **Detección de idioma automática**
|
||||
3. **Caché de resultados OCR** para evitar reprocesar el mismo PDF
|
||||
4. **Procesamiento paralelo** de páginas para mayor velocidad
|
||||
5. **Migrar a servicios cloud** (AWS Textract) para mejor precisión
|
||||
Reference in New Issue
Block a user