Démarrage rapide
TurboOCR est livré sous la forme d’un seul conteneur. Tirez l’image, lancez-la sur un GPU, envoyez un document en POST, parsez le JSON — cette page vous mène à votre première réponse réelle en moins de cinq minutes. C’est un parseur de documents complet — texte, mise en page, tableaux et formules — pas seulement de l’OCR.
1. Pré-requis
Section intitulée « 1. Pré-requis »Hôte Linux avec un GPU NVIDIA Turing ou plus récent (RTX série 20 / GTX série 16 et au-delà) et un pilote 595+. Docker avec le NVIDIA Container Toolkit, pour que --gpus all fonctionne. Prévoyez ~4 Go de VRAM en texte seul et ~8 Go pour le pipeline complet (mise en page + tableaux + formules). Tous les modèles et packs de langues sont déjà intégrés à l’image.
2. Lancer le conteneur
Section intitulée « 2. Lancer le conteneur »Tirez et lancez :latest depuis GHCR (épinglez :v3.1.0 en production). HTTP écoute sur le port 8000, gRPC sur 50051. Le volume nommé conserve les moteurs TensorRT compilés entre les redémarrages.
docker run --gpus all -p 8000:8000 -p 50051:50051 \ -v trt-cache:/home/ocr/.cache/turbo-ocr \ ghcr.io/aiptimizer/turboocr:latestAu premier démarrage, les moteurs TensorRT sont compilés à partir des ONNX (environ 90 secondes sur un 5090, jusqu’à une heure sur un GPU plus ancien — réglez TRT_OPT_LEVEL=3 pour réduire ce temps de 3 à 5× avec une légère régression de vitesse). Chaque redémarrage suivant les recharge instantanément depuis le volume trt-cache. Utilisez un volume nommé, pas un bind-mount sur un dossier hôte — un bind-mount d’un dossier vide masquerait les modèles fournis avec l’image.
Une fois que les logs indiquent que le serveur est prêt, vérifiez-le rapidement :
curl http://localhost:8000/health3. Envoyer votre première requête
Section intitulée « 3. Envoyer votre première requête »Plusieurs endpoints couvrent la plupart des charges. POST /ocr/raw prend des octets d’image bruts (le chemin le plus rapide) ; POST /ocr/pdf rend et passe à l’OCR chaque page de PDF en parallèle. Autres routes : POST /ocr (image base64 dans du JSON), POST /ocr/pixels (tampon de pixels brut sans décodage), POST /ocr/batch (plusieurs images par requête), POST /infer (OCR + mise en page / ordre de lecture / blocs dans une seule réponse structurée) et POST /ocr/markdown (page → Markdown fidèle). Voyez la référence API pour les schémas complets.
curl -X POST http://localhost:8000/ocr/raw \ --data-binary @document.png \ -H "Content-Type: image/png"curl -X POST http://localhost:8000/ocr/pdf \ --data-binary @document.pdf \ -H "Content-Type: application/pdf"Ou appeler depuis Python
Section intitulée « Ou appeler depuis Python »pip install turboocrfrom turboocr import Client
with Client( base_url="http://localhost:8000", api_key="tocr_live_...",) as client: response = client.recognize_image("invoice.jpg") print(response.results[0].text)4. Lire la réponse
Section intitulée « 4. Lire la réponse »Les endpoints d’image renvoient un tableau results plat. Chaque entrée contient le texte reconnu, un score de confiance dans [0, 1] et un polygone englobant à quatre points en coordonnées pixel (haut-gauche, haut-droit, bas-droit, bas-gauche).
{ "results": [ { "text": "Invoice Total", "confidence": 0.97, "bounding_box": [[42, 10], [210, 10], [210, 38], [42, 38]] }, { "text": "$1,284.00", "confidence": 0.95, "bounding_box": [[220, 10], [320, 10], [320, 38], [220, 38]] } ]}Les réponses PDF encapsulent un tableau results par page sous pages[], avec l’index de page, le DPI de rendu et les dimensions en pixels. Ajoutez ?layout=1 à n’importe quel endpoint pour détecter en plus les régions du document ; chaque résultat reçoit alors un layout_id qui pointe vers la région qui le contient. /infer accepte aussi ?reading_order=1 (ajoute un tableau d’ordre de lecture, XY-cut sur les régions de layout) et ?as_blocks=1 (agrège les lignes en blocs de paragraphes) ; les deux activent automatiquement ?layout=1.
Si une étape configurée ne produit rien, le JSON porte text_degraded / table_degraded / formula_degraded (plus une chaîne *_warning) au lieu d’un résultat vide silencieux — un résultat partiel n’est jamais un 200 propre non signalé.
5. Tableaux, formules et Markdown
Section intitulée « 5. Tableaux, formules et Markdown »Les tableaux et les formules sont strictement opt-in : le backend doit être chargé au démarrage et la requête doit le demander. Tous les poids sont déjà intégrés à l’image — il suffit de définir la variable d’env du backend pour charger l’étape (aucun chemin nécessaire). La mise en page est active par défaut ; chaque étape supplémentaire ne s’exécute que si la requête la demande.
# Text + layout is the default. Add backends to load the table and# formula stages, and pick a bigger / other-language OCR tier.docker run --gpus all -p 8000:8000 -p 50051:50051 \ -e TABLE_BACKEND=slanext \ -e FORMULA_BACKEND=ppformulanet_s \ -e OCR_MODEL=medium \ -v trt-cache:/home/ocr/.cache/turbo-ocr \ ghcr.io/aiptimizer/turboocr:latest
# OCR_MODEL: tiny (default) | small | medium | arabic | eslav | korean | thai | greek# FORMULA_BACKEND: ppformulanet_s (Latin/EN) | ppformulanet_plus_m (Chinese-capable) | vlmPuis activez-les par requête — ?tables=1 et ?formulas=1 se combinent librement et activent automatiquement la mise en page :
# Full structured parse: layout regions + tables -> HTML + formulas -> LaTeX.# tables=1 / formulas=1 auto-enable layout. The backends must be loaded at# startup (TABLE_BACKEND / FORMULA_BACKEND) or you get a 400, never empties.curl -X POST "http://localhost:8000/ocr/raw?layout=1&tables=1&formulas=1" \ --data-binary @paper.png \ -H "Content-Type: image/png"La réponse gagne un tableau tables (HTML + quads de cellules) et/ou un tableau formulas (LaTeX). Demander une étape avec laquelle le serveur n’a pas été démarré est une erreur dure 400 (TABLE_BACKEND_DISABLED / FORMULA_BACKEND_DISABLED), jamais un résultat vide silencieux.
Pour un export pleine page, POST /ocr/markdown renvoie du Markdown fidèle avec tableaux et formules en ligne (build GPU ; nécessite la mise en page) :
# Page -> faithful Markdown (GPU build). Requires layout; tables + formulas# are always included best-effort, since a faithful export needs them.curl -X POST "http://localhost:8000/ocr/markdown" \ --data-binary @page.png \ -H "Content-Type: image/png"Pas sûr des étapes chargées par un serveur en cours d’exécution ? Demandez-lui :
# Discover which stages and routes a running server actually has loaded.curl http://localhost:8000/capabilities6. Essayer l’interface Web (Studio)
Section intitulée « 6. Essayer l’interface Web (Studio) »Vous préférez pointer-cliquer ? L’interface Web Studio vous laisse déposer une image ou un PDF, lancer l’OCR, voir la superposition de mise en page et l’ordre de lecture, sélectionner le texte reconnu sur la page et télécharger un PDF cherchable. Le serveur et l’interface démarrent ensemble avec une seule commande depuis la racine du dépôt (le compose de démo active déjà les étapes tableaux et formules) :
docker compose -f docker-compose.demo.yml up --buildOuvrez ensuite http://localhost:3000. Pour du dev CPU uniquement, utilisez docker-compose.demo.cpu.yml à la place (le CPU est réservé au dev/CI — quelques img/s).