Sobre el proyecto

PolyOCR Service es un servicio multilingüe de OCR, traducción opcional y servicio independiente PaddleOCR-VL construido sobre PaddleOCR 3.x y FastAPI. El autor aclara explícitamente que es un proyecto comunitario y no un componente oficial de PaddleOCR. Capacidades y límites La llamada básica de OCR utiliza predict() de PaddleOCR 3.x y es compatible con resultados de tipo mapeo/objeto de 3.x y con resultados de lista antiguos. Admite 78 idiomas, cubriendo sistemas de escritura como hanzi, japonés, coreano, latino, cirílico, árabe, devanagari, tailandés y griego, y acepta tres tipos de alias: código de idioma, nombre en inglés y nombre en chino (por ejemplo, fr / french / 法文). El idioma se valida en el límite de la solicitud; un idioma desconocido devuelve directamente 422 unsupported_language, sin esperar a cargar el modelo para fallar. Antes de la inferencia, la imagen pasa por validaciones de número de bytes, resultado de decodificación, número de píxeles y umbral de confianza; la inferencia síncrona se ejecuta en un grupo de hilos y la concurrencia está limitada por un semáforo. La entrada de traducción limita el número de elementos y el total de caracteres, y exige que el proveedor devuelva una cantidad coherente con la entrada. HTTP, autenticación, validación de solicitudes y errores de dominio usan una estructura de respuesta de error unificada. PaddleOCR-VL solo acepta contenido subido, rechaza URL, requiere una API Key independiente y limita el tamaño de carga. Las páginas del navegador renderizan los resultados del servidor con textContent y no interpretan el contenido devuelto como HTML. Instalación y ejecución Compatible con Python 3.10, 3.11 y 3.12, verificado por CI. Se instala con pip install -e ".[dev,ocr]", se copia .env.example a .env y se modifica la API Key antes de iniciar. La entrada de línea de comandos escucha por defecto en 127.0.0.1:8000 y se puede configurar con POLYOCR_HOST / POLYOCR_PORT; el README advierte especialmente que --host 0.0.0.0 expone el servicio en todas las interfaces de red. Dentro de un contenedor es necesario hacerlo así, pero ejecutarlo directamente en un portátil o en una red compartida permite que cualquiera en la LAN acceda a la instancia. La página web está en la ruta raíz y la documentación de la API en /docs. Resumen de la API La comprobación de estado /v1/health no requiere autenticación; /v1/languages devuelve el código de idioma, el código de idioma de PaddleOCR, el sistema de escritura y los alias disponibles. La solicitud de OCR /v1/ocr admite X-API-Key o Bearer Token; los campos de formulario incluyen file, language y score_threshold; la respuesta devuelve el código de idioma canónico e incluye items (text, score, bbox), cost_ms, request_id y warnings. La interfaz de traducción /v2/translate recibe texts y target_language. Las respuestas de fallo se unifican en un objeto error con code, message y request_id. Aviso de desenfoque de movimiento Cuando la varianza laplaciana de la imagen está por debajo del umbral (por defecto 45.0, ajustable con POLYOCR_BLUR_VARIANCE_FLOOR) pero el modelo aún devuelve texto con alta confianza, la respuesta incluye el aviso suspected_blur, y en detail se indican la varianza laplaciana y el umbral. El README explica su motivación: el desenfoque de movimiento devuelve texto con confianza normal pero contenido incorrecto, y quien llama originalmente no podía distinguirlo; este aviso convierte "no se puede distinguir" en "se puede distinguir". El aviso solo se evalúa cuando el modelo realmente devuelve texto; un resultado vacío no genera aviso. Opciones de configuración La documentación enumera el interruptor de autenticación y la API Key, los orígenes CORS, el límite de tamaño de carga (por defecto 10MB), el límite de píxeles tras decodificación (por defecto 25 millones), el número de inferencias concurrentes (por defecto 2), el número de hilos de trabajo de OCR, el umbral de varianza de desenfoque, los límites de elementos y caracteres de traducción, la clave/base/modelo del servicio de traducción compatible con OpenAI, y la clave independiente y el límite de carga del servicio VL. Si la autenticación está activada y POLYOCR_API_KEY está vacío, el servicio básico se niega a iniciar; el servicio VL siempre requiere POLYOCR_VL_API_KEY; CORS con credenciales no permite orígenes comodín. Docker y pruebas Se ofrece despliegue con docker compose up --build; la imagen fija la base de Python 3.10, se ejecuta como usuario no root y proporciona comprobación de estado. El primer OCR descargará el modelo y la caché se guarda en un volumen de Compose. El flujo de pruebas incluye formato y comprobación con ruff, pruebas pytest no de integración y python -m build; el E2E de OCR real requiere establecer explícitamente POLYOCR_RUN_OCR_E2E=1 y puede descargar modelos. CI solo ejecuta pruebas rápidas que no descargan modelos. Referencias y conclusiones medidas La referencia de precisión por idioma compara imágenes etiquetadas por idioma y reporta tanto exact (proporción de coincidencia exacta línea por línea) como cer (tasa de error de caracteres), sin verse afectada por el orden de detección. La referencia de robustez cubre desenfoque, compresión, rotación, reducción, ruido, contraste claro-oscuro, así como degradaciones de captura como desenfoque de movimiento, perspectiva, iluminación no uniforme, sombras y textura de papel. La conclusión medida que da el README es: rotación, perspectiva, compresión JPEG, contraste claro-oscuro, iluminación no uniforme, sombras y textura de papel casi no afectan el reconocimiento; las escenas combinadas de fotografía incluso obtienen puntuación perfecta; los únicos fallos reales son la pérdida de detalle, es decir, desenfoque superior a aproximadamente σ2 y reducción por debajo del 25%. Lo único a lo que hay que prestar atención es el desenfoque de movimiento: con un desplazamiento de 15px devuelve texto erróneo con confianza normal (Hello World → Heelco Ncotec), y por debajo de 9px es completamente normal. El parámetro preprocess no está implementado: las cinco canalizaciones de preprocesamiento tienen un beneficio neto negativo en las 17 degradaciones; el contraste automático perjudica 11 de 17, por lo que preprocess=true devuelve 400 preprocess_unsupported en lugar de ignorarse silenciosamente. La referencia de fotos reales usa CORD-v2 (CC-BY-4.0, con anotación manual palabra por palabra) para medición real; las imágenes sintéticas promedian 0.975 exact y las fotos reales 0.841 de recuperación de palabras; el README afirma que la puntuación de las imágenes sintéticas es optimista en unos 13 puntos. En fotos reales, el preprocesamiento tiene media positiva en las tres canalizaciones, pero la prueba bootstrap muestra que los intervalos de confianza del 95% de las cinco canalizaciones cruzan todos el 0, con un valor p mínimo de 0.371; la conclusión se mantiene como "no hay un beneficio estadísticamente detectable". Licencia Usa Apache License 2.0, coherente con PaddleOCR upstream; las atribuciones de terceros se registran en NOTICE. Los modelos PaddleOCR se descargan en tiempo de ejecución desde sus distribuidores originales y están sujetos a sus respectivas licencias y términos de uso.