Identidad Clara

panel OCR

DOCUMENTACIÓN TÉCNICA

OCR local, explicado de principio a fin.

Arquitectura, pipeline de procesamiento, herramientas y formas de ejecutar el proyecto con CPU o GPU NVIDIA.

Ejecutar localmente Ver repositorio

Procesamiento local CPU + NVIDIA Código abierto

pipeline / procesamiento

Entrada

Documento PDF

Hasta 25 MB y 50 páginas por trabajo.

Motor OCR

PaddleOCR

Resultado

JSON · CSV · XLSX

Next.jsFastAPISQLite

Arquitectura

Tres capas conectadas por HTTP

El navegador se comunica con Next.js. El frontend reenvía las solicitudes al backend privado, donde el pipeline procesa los archivos y persiste los resultados.

Next.js + React

Frontend

Carga, progreso, revisión, exportación y comparación.

FastAPI + Python

Backend

Validación, trabajos, servicios y contratos REST.

OCR + SQLite

Procesamiento

Imágenes, reconocimiento, campos y persistencia.

Navegador :3000

Next.js rewrite

FastAPI :8000

PyMuPDF + OpenCV

PaddleOCR

SQLite

Flujo de datos

De PDF a datos revisables

Cada trabajo atraviesa seis etapas. El frontend consulta el avance y recupera los resultados cuando el procesamiento termina.

PDF

El frontend carga el archivo y FastAPI valida formato, peso y cantidad de páginas.

Imagen

PyMuPDF renderiza cada página y OpenCV corrige perspectiva, rotación y contraste.

OCR

PaddleOCR reconoce las líneas y devuelve texto, confianza y coordenadas.

Campos

El extractor normaliza documentos, nombres, fechas y otros valores estructurados.

Revisión

La interfaz permite comprobar campos inciertos y guardar correcciones.

Salida

Los resultados se exportan a CSV/XLSX o se comparan con otro Excel.

Instalación

Clonar y ejecutar

Docker Compose construye el frontend y el backend, conecta los servicios y conserva la base de datos y los modelos en volúmenes.

1. Descargar el código

Requiere Git, Docker Desktop o Docker Engine y Docker Compose.

Clonar repositorio

git clone https://github.com/JhonatanC4STRO/ocr.git
cd ocr

2. Iniciar con GPU NVIDIA

Opción recomendada: acelera PaddleOCR y ofrece mayor capacidad para PDFs extensos.

GPU NVIDIA · Docker Compose

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d

OPCIÓN RECOMENDADA

GPU NVIDIA

Es la mejor opción para este proyecto cuando está disponible: CUDA acelera la inferencia de PaddleOCR y reduce el tiempo de procesamiento. Requiere una GPU NVIDIA, controlador compatible y acceso desde Docker.

✓ Mejor rendimiento en PDFs largos o uso frecuente
✓ Mayor capacidad de procesamiento OCR
✓ Script automático para Windows y Linux

Requisito recomendado

Una GPU NVIDIA mejora la experiencia

La GPU acelera la parte más costosa del flujo: el reconocimiento OCR. La precisión usa los mismos modelos; la diferencia principal es la velocidad y la cantidad de documentos que puede procesar.

Antes de iniciar, valida que Docker vea la GPU:

docker run --rm --gpus all nvidia/cuda:12.9.1-base-ubuntu22.04 nvidia-smi

Inicio rápido NVIDIA

El script valida la GPU antes de levantar el proyecto

En Windows necesita Docker Desktop con WSL 2. En Linux necesita NVIDIA Container Toolkit.

Windows · PowerShell

powershell -ExecutionPolicy Bypass -File .\\scripts\\start-gpu.ps1

Linux · Bash

bash scripts/start-gpu.sh

Última alternativa

3. Iniciar con CPU

Úsala solo si no cuentas con GPU NVIDIA. La aplicación funciona completa, pero OCR tarda más y tiene menor capacidad en PDFs extensos.

✓ Compatible con equipos y VPS convencionales
− Menor velocidad de reconocimiento

CPU · Docker Compose

docker compose up --build -d

Stack técnico

Herramientas del proyecto

Cada tecnología ocupa una responsabilidad concreta dentro del flujo, desde la interfaz hasta el reconocimiento y la persistencia.

Next.js 16

Interfaz, estado y comunicación HTTP

FastAPI

API REST y procesamiento en segundo plano

PaddleOCR

Detección y reconocimiento local de texto

OpenCV

Corrección y preparación de imágenes

PyMuPDF

Validación y renderizado de páginas PDF

SQLite

Documentos, correcciones y reportes

Docker

Entorno reproducible para CPU o NVIDIA

pandas

Comparación y exportación de Excel

Referencia técnica

API, configuración y entorno

Datos operativos para desarrollar, integrar o diagnosticar la aplicación sin tener que recorrer el código fuente.

Endpoints principales

Base pública en Docker: /backend-api

Método	Ruta	Operación
POST	/api/documents/process	Crear trabajo OCR
GET	/api/documents/{job_id}	Consultar progreso
GET	/api/documents/{job_id}/results	Obtener resultados
PATCH	/api/documents/{job_id}/results/{id}	Guardar corrección
GET	/api/documents/{job_id}/export	Exportar CSV/XLSX
POST	/api/documents/{job_id}/compare	Comparar Excel

Variables principales

Se configuran mediante el archivo .env.

Variable	Base	Controla
PADDLE_OCR_DEVICE	cpu / gpu:0	Dispositivo de inferencia
PDF_RENDER_DPI	240	Resolución del PDF
OCR_MIN_CONFIDENCE	0.35	Líneas aceptadas
REVIEW_THRESHOLD	85	Campos para revisión
MAX_PDF_SIZE_MB	25	Peso máximo
MAX_PDF_PAGES	50	Páginas máximas

GPU NVIDIA en Windows

Preparación mínima del host

01
Instalar WSL 2 con wsl --install y reiniciar Windows.
02
Actualizar con wsl --update y confirmar versión 2.
03
Activar el motor WSL 2 dentro de Docker Desktop.
04
Validar Windows y Docker mediante nvidia-smi.

Servicios disponibles localmente

Interfaz

http://localhost:3000

Documentación OpenAPI

http://localhost:3000/backend-api/docs

Estado del backend

http://localhost:3000/backend-api/health

Leer README completo

Proyecto completo

Revisa el código o ejecuta el pipeline localmente.

Abrir GitHub Ver instalación