Déploiement

Tout ce dont vous avez besoin pour passer TurboOCR de « je veux faire tourner ça en prod » à « ça tourne, c’est monitoré et ça ne s’effondre pas ». Cette page couvre les tags Docker pris en charge, le socle GPU et pilote requis, le volume de cache TensorRT, le changement de modèle, la mise à l’échelle via MPS, les endpoints de monitoring et une courte checklist de production.

Prérequis

• Système d’exploitation — Linux. Le conteneur est construit sur l’image officielle NVIDIA TensorRT et est validé sur Ubuntu 24.04.
• GPU — NVIDIA Turing ou plus récent (RTX 20-series, GTX 16-series ou postérieur).
• Pilote — pilote NVIDIA 595 ou plus récent, plus le NVIDIA Container Toolkit pour que --gpus all soit honoré par Docker.
• VRAM — environ ~4 Go pour un déploiement texte seul et ~8 Go pour le pipeline complet (mise en page + tableaux + formules). Chaque replica PIPELINE_POOL_SIZE supplémentaire ajoute environ un jeu complet.
• Repli CPU — une image CPU-only existe pour le développement sur des machines sans GPU, mais le débit est nettement plus faible (quelques img/s) et elle ne doit pas être utilisée en production.

Images Docker

Les images préconstruites sont publiées sur GitHub Container Registry sous ghcr.io/aiptimizer/turboocr. Deux variantes sont produites depuis docker/Dockerfile.gpu et docker/Dockerfile.cpu du dépôt source.

Tag	Usage	Notes
:latest	Image GPU, suit la dernière version	Drogon HTTP sur 8000 (via nginx), gRPC sur 50051. Embarque tous les reconnaisseurs, PP-DocLayoutV3 et les poids tableaux/formules. Pratique pour les démos ; à épingler en prod.
:v3.1.0	Image GPU épinglée	La version actuelle — à utiliser en production.
turboocr-cpu:v3.1.0	Repli CPU	ONNX Runtime à la place de TensorRT (image dédiée : ghcr.io/aiptimizer/turboocr-cpu). Quelques img/s — dev/CI uniquement.

Attention

Épinglez une version en production. Utilisez un tag explicite comme :v3.1.0 plutôt que :latest. L’épinglage rend les rollbacks triviaux et empêche une mise à jour surprise de reconstruire des moteurs TensorRT en plein incident.

Noms des binaires serveur

Dans l’image, les binaires serveur ont été renommés en v3 : le GPU est turboocr-server (anciennement paddle_highspeed_cpp) et le CPU est turboocr-cpu-server (anciennement paddle_cpu_server). Les utilisateurs Docker ne sont pas concernés ; cela ne compte que pour les builds natifs et --print-config.

Image GPU

L’image par défaut exécute le pipeline TensorRT complet. Le premier démarrage compile les moteurs depuis ONNX (environ 90 secondes sur un RTX 5090, jusqu’à ~1 heure sur un GPU plus ancien) ; le volume nommé trt-cache les conserve, de sorte que les redémarrages suivants sont instantanés.

docker volume create trt-cache

docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  ghcr.io/aiptimizer/turboocr:latest

HTTP écoute sur 8000 (nginx en frontal de Drogon, pour bufferiser les clients lents) et gRPC sur 50051. Les deux protocoles partagent le même pool de pipelines GPU — vous pouvez les exposer simultanément depuis le même conteneur.

Accélérez le premier build avec TRT_OPT_LEVEL

Le build des moteurs utilise par défaut le plus haut niveau d’optimisation (TRT_OPT_LEVEL=5, runtime le plus rapide). Sur un GPU lent, réglez TRT_OPT_LEVEL=3 pour réduire de 3 à 5× ce build unique au prix d’une petite régression runtime (<5 %). Le niveau fait partie de la clé de cache du moteur, donc le changer déclenche une reconstruction.

Image CPU

L’image CPU est un repli direct pour les hôtes sans GPU NVIDIA. Elle utilise ONNX Runtime à la place de TensorRT, tourne sur un simple ubuntu:24.04 et expose la même API HTTP.

docker run -p 8000:8000 \
  ghcr.io/aiptimizer/turboocr-cpu:v3.1.0

Attention

Le débit se compte en quelques img/s contre jusqu’à ~556 img/s sur un seul RTX 5090. Le build CPU existe pour le développement local, la CI et les tests d’intégration — pas pour le trafic de production.

Volume de cache TensorRT

Les moteurs TensorRT et les packs de langues sont stockés dans le conteneur sous /home/ocr/.cache/turbo-ocr. Montez ce chemin en volume nommé — jamais en bind-mount hôte.

docker volume create trt-cache
docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  ghcr.io/aiptimizer/turboocr:latest

Pourquoi un volume nommé. L’image crée un lien symbolique de /app/models/rec vers le répertoire de cache pour que les packs de langues non par défaut y résident également. Un bind-mount d’un répertoire hôte vide masquerait ce chemin et le serveur n’aurait plus rien à charger. Les volumes nommés se peuplent automatiquement depuis l’image au premier usage — c’est exactement ce que vous voulez.

Si vous supprimez le volume. Le prochain démarrage reconstruira chaque moteur TensorRT depuis ONNX (~90 s) et ré-extraira les packs embarqués. Aucune perte de données — juste un démarrage à froid plus lent.

Sélection de modèle

Définissez la variable d’environnement OCR_MODEL au démarrage. Tous les modèles sont embarqués dans l’image au moment du build depuis des releases PaddleOCR épinglées ; aucun téléchargement à l’exécution.

docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  -e OCR_MODEL=medium \
  ghcr.io/aiptimizer/turboocr:latest

Les paliers PP-OCRv6 tiny (défaut) / small / medium couvrent latin + chinois + japonais et échangent précision contre vitesse. Les autres écritures utilisent les reconnaisseurs PP-OCRv5 conservés via la même variable : arabic, eslav (cyrillique), korean, thai, greek. OCR_LANG fonctionne toujours comme alias déprécié (avertit à l’usage). Voyez la page Configuration pour le détail complet.

Interface Web (Studio)

Le dépôt livre une interface navigateur — déposez une image ou un PDF, lancez l’OCR, voyez la superposition de mise en page et l’ordre de lecture, sélectionnez le texte reconnu et téléchargez un PDF cherchable. Elle tourne comme un second conteneur qui proxy /api/* vers le serveur OCR, de sorte que le navigateur reste same-origin et que le serveur n’a pas besoin de CORS.

Depuis la racine du dépôt source :

# GPU
docker compose -f docker-compose.demo.yml up --build

# CPU (dev/CI)
docker compose -f docker-compose.demo.cpu.yml up --build

Ouvrez ensuite http://localhost:3000. Le compose de démo active TABLE_BACKEND=slanext et FORMULA_BACKEND=ppformulanet_s, donc les tableaux et formules sont disponibles de bout en bout. Le service OCR reste accessible directement sur http://localhost:8000 pour curl.

Connexions persistantes

Attention

Utilisez HTTP keep-alive. Ouvrir une connexion courte par requête — par exemple une boucle serrée de curl — peut saturer le serveur et le bloquer. Tout client HTTP standard (requests.Session, aiohttp, httpx.Client, JDK HttpClient, Go http.Client, libcurl avec un handle persistant) réutilise les connexions par défaut à condition que vous réutilisiez l’objet client. Ne construisez pas un client neuf à chaque requête.

L’image livrée fait tourner nginx en frontal de Drogon pour bufferiser les clients lents, mais nginx ne peut pas sauver un client qui ouvre une nouvelle connexion TCP par requête. Voyez le guide Clients pour des exemples opérationnels en Python, Java et C++.

Monitoring

Métriques Prometheus

Scrappez GET /metrics pour des métriques compatibles Prometheus. Le serveur expose des compteurs de requêtes par route, des histogrammes de latence, l’utilisation VRAM et la saturation du pool de pipelines :

turbo_ocr_requests_total{route="/ocr/raw",status="2xx"} 1042
turbo_ocr_request_duration_seconds_bucket{route="/ocr/raw",le="0.025"} 980
turbo_ocr_request_duration_seconds_sum{route="/ocr/raw"} 12.345
turbo_ocr_request_duration_seconds_count{route="/ocr/raw"} 1042
turbo_ocr_gpu_vram_used_bytes 9052815360
turbo_ocr_gpu_vram_total_bytes 33661911040
turbo_ocr_pipeline_pool_size 5
turbo_ocr_pool_exhaustions_total 0
turbo_ocr_request_bytes_total 49493243
turbo_ocr_request_body_avg_bytes 9407

Astuce

Surveillez turbo_ocr_pool_exhaustions_total. Une valeur non nulle signifie que des clients font la queue sur le pool de pipelines — augmentez PIPELINE_POOL_SIZE ou ajoutez des replicas. Les histogrammes de latence sont bucketisés par route, ce qui permet de définir un SLO indépendant par endpoint.

Sondes de santé

Endpoint	Usage
GET /health	Vérification de vie basique — renvoie "ok".
GET /health/live	Sonde liveness Kubernetes. Renvoie 200 dès que le processus est démarré.
GET /health/ready	Sonde readiness. Renvoie 200 uniquement quand le pipeline GPU passe un test de fumée — utilisez-la pour gater le trafic.

Compilation depuis les sources

Pour des builds locaux, des cibles CUDA personnalisées ou des déploiements air-gappés, consultez les instructions de build dans le dépôt GitHub. Les Dockerfiles dans docker/ sont la référence canonique ; la section « Building from Source » du README liste toutes les dépendances et les invocations CMake pour les cibles GPU et CPU.

Configuration Toutes les variables d'environnement : packs de langues, taille du pool de pipelines, parallélisme PDF, logs.

Clients Recettes prêtes pour la production en Python, Java et C++ — connexions persistantes, fan-out, gRPC.