polyocr-service

PolyOCR Service est un service OCR multilingue, avec traduction optionnelle et un service PaddleOCR-VL indépendant, construit sur PaddleOCR 3.x et FastAPI. L'auteur précise explicitement qu'il s'agit d'un projet communautaire, non d'un composant officiel de PaddleOCR. Capacités et limites L'OCR de base utilise predict() de PaddleOCR 3.x, compatible avec les résultats de mapping/objets 3.x et les anciens résultats de liste. Il prend en charge 78 langues, couvrant les systèmes d'écriture chinois, japonais, coréen, latin, cyrillique, arabe, devanagari, thaï, grec, etc., et accepte trois types d'alias : codes de langue, noms anglais et noms chinois (par exemple fr / french / 法文). La langue est validée à la limite de la requête ; une langue inconnue renvoie directement 422 unsupported_language, sans attendre le chargement du modèle. Les images sont validées avant l'inférence via le nombre d'octets, le résultat de décodage, le nombre de pixels et le seuil de confiance ; l'inférence synchrone est exécutée dans un pool de threads et limitée en concurrence par un sémaphore. La traduction limite le nombre d'entrées et le nombre total de caractères, et exige que le fournisseur renvoie un nombre de résultats identique à l'entrée. Les erreurs HTTP, d'authentification, de validation de requête et de domaine utilisent une structure de réponse d'erreur unifiée. PaddleOCR-VL n'accepte que le contenu téléversé, refuse les URL, exige une clé API indépendante et limite la taille du téléversement. La page navigateur utilise textContent pour rendre les résultats côté serveur, n'interprétant pas le contenu renvoyé comme du HTML. Installation et exécution Python 3.10, 3.11, 3.12 sont pris en charge et vérifiés par CI. Installation via pip install -e ".[dev,ocr]", copier .env.example en .env et modifier la clé API avant de démarrer. L'entrée en ligne de commande écoute par défaut sur 127.0.0.1:8000, configurable avec POLYOCR_HOST / POLYOCR_PORT ; le README rappelle particulièrement que --host 0.0.0.0 expose sur toutes les interfaces réseau, nécessaire dans un conteneur, mais sur un ordinateur portable ou un réseau partagé, cela permet à quiconque sur le réseau local d'accéder à l'instance. La page Web se trouve à la racine, la documentation API à /docs. Aperçu de l'API La vérification de santé /v1/health ne nécessite pas d'authentification ; /v1/languages renvoie les codes de langue, les codes PaddleOCR, les systèmes d'écriture et les alias disponibles. La requête OCR /v1/ocr prend en charge X-API-Key ou Bearer Token, avec des champs de formulaire incluant file, language, score_threshold ; la réponse renvoie le code de langue normalisé et inclut items (text, score, bbox), cost_ms, request_id et warnings. L'interface de traduction /v2/translate reçoit texts et target_language. Les réponses d'échec sont unifiées en objet error, contenant code, message, request_id. Avertissement de flou de mouvement Lorsque la variance du Laplacien de l'image est inférieure au seuil (par défaut 45,0, ajustable avec POLYOCR_BLUR_VARIANCE_FLOOR) mais que le modèle renvoie toujours un texte à haute confiance, la réponse inclut un avertissement suspected_blur, avec dans detail la variance du Laplacien et le seuil. Le README explique la motivation : le flou de mouvement renvoie un texte avec une confiance normale mais un contenu erroné, que l'appelant ne pouvait pas distinguer auparavant ; cet avertissement transforme « impossible à distinguer » en « distinguable ». L'avertissement n'est évalué que si le modèle renvoie effectivement du texte ; un résultat vide ne produit pas d'avertissement. Options de configuration La documentation liste l'interrupteur d'authentification et la clé API, les origines CORS, la limite de taille de téléversement (10 Mo par défaut), la limite de pixels après décodage (25 millions par défaut), le nombre d'inférences concurrentes (2 par défaut), le nombre de threads de travail OCR, le seuil de variance de flou, les limites d'entrées et de caractères de traduction, la clé/base/modèle du service de traduction compatible OpenAI, ainsi que la clé indépendante et la limite de téléversement du service VL. Si l'authentification est activée et POLYOCR_API_KEY est vide, le service de base refuse de démarrer ; le service VL exige toujours POLYOCR_VL_API_KEY ; le CORS avec identifiants n'autorise pas les origines génériques. Docker et tests Le déploiement via docker compose up --build est fourni, avec une image fixée sur Python 3.10, exécutée en utilisateur non root et avec vérification de santé ; le premier OCR télécharge les modèles, le cache est stocké dans un volume Compose. Le processus de test inclut le formatage et la vérification ruff, les tests non-intégration pytest et python -m build ; les tests E2E OCR réels nécessitent de définir explicitement POLYOCR_RUN_OCR_E2E=1, ce qui peut télécharger des modèles. La CI n'exécute que les tests rapides sans téléchargement de modèles. Benchmarks et conclusions mesurées Le benchmark de précision par langue compare des images annotées par langue, rapportant à la fois exact (proportion de correspondance ligne par ligne complète) et cer (taux d'erreur de caractères), sans être affecté par l'ordre de détection. Le benchmark de robustesse couvre le flou, la compression, la rotation, la réduction, le bruit, le contraste clair/sombre, ainsi que les dégradations de type photographie : flou de mouvement, perspective, éclairage non uniforme, ombres, texture de papier. Les conclusions mesurées du README sont : la rotation, la perspective, la compression JPEG, le contraste clair/sombre, l'éclairage non uniforme, les ombres et la texture de papier n'affectent presque pas la reconnaissance ; les scénarios de photographie combinés obtiennent même un score parfait. La seule véritable défaillance est la perte de détails : flou au-delà d'environ σ2, réduction en dessous de 25 %. Le seul point de vigilance est le flou de mouvement : à 15 px de déplacement, un texte erroné avec une confiance normale est renvoyé (Hello World → Heelco Ncotec), mais en dessous de 9 px, tout est parfaitement normal. Le paramètre preprocess n'est pas implémenté : les cinq pipelines de prétraitement ont un bénéfice net négatif sur les 17 dégradations, le contraste automatique nuit à 11 des 17 éléments ; ainsi preprocess=true renvoie 400 preprocess_unsupported, plutôt que d'être silencieusement ignoré. Le benchmark de photos réelles utilise CORD-v2 (CC-BY-4.0, avec annotations manuelles mot par mot) : les images synthétiques obtiennent en moyenne 0,975 exact, les photos réelles 0,841 de rappel de mots ; le README indique que les scores synthétiques sont optimistes d'environ 13 points. Le prétraitement sur photos réelles a une moyenne positive pour les trois pipelines, mais le test bootstrap montre que les intervalles de confiance à 95 % des cinq pipelines traversent tous zéro, avec un p minimum de 0,371 ; la conclusion reste « aucun bénéfice statistiquement détectable ». Licence Sous licence Apache License 2.0, cohérente avec PaddleOCR en amont ; les attributions tierces sont enregistrées dans NOTICE. Les modèles PaddleOCR sont téléchargés à l'exécution depuis leurs distributeurs d'origine, soumis à leurs licences et conditions d'utilisation respectives.