Schnellstart
TurboOCR wird als ein einziger Container ausgeliefert. Image ziehen, auf einer GPU starten, ein Dokument per POST schicken, JSON parsen — diese Seite bringt Sie in unter fünf Minuten zur ersten echten Antwort. Es ist ein vollständiger Dokumentparser — Text, Layout, Tabellen und Formeln — nicht nur OCR.
1. Voraussetzungen
Abschnitt betitelt „1. Voraussetzungen“Linux-Host mit einer NVIDIA-GPU ab Turing (RTX 20-Serie / GTX 16-Serie oder neuer) und Treiberversion 595+. Docker mit NVIDIA Container Toolkit, damit --gpus all funktioniert. Planen Sie ~4 GB VRAM für reinen Text und ~8 GB für die volle Pipeline (Layout + Tabellen + Formeln) ein. Alle Modelle und Sprachpakete sind ins Image eingebacken.
2. Container starten
Abschnitt betitelt „2. Container starten“Ziehen und starten Sie :latest von GHCR (in der Produktion :v3.1.0 pinnen). HTTP läuft auf Port 8000, gRPC auf 50051. Das Named Volume bewahrt die kompilierten TensorRT-Engines zwischen Neustarts auf.
docker run --gpus all -p 8000:8000 -p 50051:50051 \ -v trt-cache:/home/ocr/.cache/turbo-ocr \ ghcr.io/aiptimizer/turboocr:latestBeim ersten Start werden die TensorRT-Engines aus den ONNX-Dateien kompiliert (rund 90 Sekunden auf einer 5090, bis zu einer Stunde auf älteren GPUs — setzen Sie TRT_OPT_LEVEL=3, um das um das 3–5-Fache zu verkürzen, bei einer kleinen Geschwindigkeitseinbuße). Jeder weitere Start liest sie sofort aus dem trt-cache-Volume. Verwenden Sie ein Named Volume, kein Host-Bind-Mount — ein Bind-Mount auf ein leeres Verzeichnis überdeckt sonst die mitgelieferten Modelle.
Sobald die Logs Bereitschaft melden, können Sie den Server prüfen:
curl http://localhost:8000/health3. Erste Anfrage senden
Abschnitt betitelt „3. Erste Anfrage senden“Mehrere Endpoints decken die meisten Workloads ab. POST /ocr/raw nimmt rohe Bildbytes (der schnellste Weg); POST /ocr/pdf rendert und verarbeitet jede PDF-Seite parallel. Weitere Routen: POST /ocr (Base64-Bild im JSON), POST /ocr/pixels (roher Pixelpuffer ohne Decodierung), POST /ocr/batch (viele Bilder pro Anfrage), POST /infer (OCR + Layout / Lesereihenfolge / Blöcke in einer strukturierten Antwort) und POST /ocr/markdown (Seite → originalgetreues Markdown). Die vollständigen Schemas finden Sie in der API-Referenz.
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"Oder aus Python aufrufen
Abschnitt betitelt „Oder aus Python aufrufen“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. Antwort auswerten
Abschnitt betitelt „4. Antwort auswerten“Die Bild-Endpoints liefern ein flaches results-Array. Jeder Eintrag enthält den erkannten Text, eine Konfidenz im Bereich [0, 1] und ein Begrenzungspolygon mit vier Eckpunkten in Pixelkoordinaten (oben-links, oben-rechts, unten-rechts, unten-links).
{ "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]] } ]}PDF-Antworten verpacken pro Seite ein eigenes results-Array unter pages[], jeweils mit Seitenindex, Render-DPI und Pixelmaßen. Hängen Sie an beide Endpoints ?layout=1 an, um zusätzlich Dokumentbereiche zu erkennen; jedes Ergebnis bekommt dann eine layout_id, die auf den enthaltenden Bereich verweist. /infer akzeptiert außerdem ?reading_order=1 (fügt ein Lesereihenfolge-Array hinzu, XY-cut über die Layout-Regionen) und ?as_blocks=1 (gruppiert Zeilen zu Absatzblöcken); beide aktivieren automatisch ?layout=1.
Wenn eine konfigurierte Stufe nichts produziert, trägt das JSON text_degraded / table_degraded / formula_degraded (plus einen *_warning-String) statt eines stillen leeren Ergebnisses — ein Teilergebnis ist nie eine unmarkierte saubere 200.
5. Tabellen, Formeln & Markdown
Abschnitt betitelt „5. Tabellen, Formeln & Markdown“Tabellen und Formeln sind strikt opt-in: Das Backend muss beim Start geladen sein und die Anfrage muss es anfordern. Alle Gewichte sind bereits ins Image eingebacken — Sie setzen nur die Backend-Umgebungsvariable, um die Stufe zu laden (keine Pfade nötig). Layout ist standardmäßig an; jede zusätzliche Stufe läuft nur, wenn die Anfrage sie anfordert.
# 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) | vlmDann pro Anfrage aktivieren — ?tables=1 und ?formulas=1 lassen sich frei kombinieren und aktivieren automatisch Layout:
# 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"Die Antwort gewinnt ein tables-Array (HTML + Zell-Quads) und/oder ein formulas-Array (LaTeX). Eine Stufe anzufordern, mit der der Server nicht gestartet wurde, ist ein harter 400 (TABLE_BACKEND_DISABLED / FORMULA_BACKEND_DISABLED), nie ein stilles leeres Ergebnis.
Für einen Ganzseiten-Export liefert POST /ocr/markdown originalgetreues Markdown mit Tabellen und Formeln inline (GPU-Build; benötigt Layout):
# 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"Nicht sicher, welche Stufen ein laufender Server geladen hat? Fragen Sie ihn:
# Discover which stages and routes a running server actually has loaded.curl http://localhost:8000/capabilities6. Die Web-GUI (Studio) ausprobieren
Abschnitt betitelt „6. Die Web-GUI (Studio) ausprobieren“Lieber per Klick? Die Studio-Web-GUI lässt Sie ein Bild oder PDF ablegen, OCR ausführen, das Layout-Overlay und die Lesereihenfolge sehen, erkannten Text auf der Seite markieren und ein durchsuchbares PDF herunterladen. Server und GUI starten zusammen mit einem Befehl aus dem Repo-Stammverzeichnis (das Demo-Compose aktiviert die Tabellen- und Formelstufen bereits):
docker compose -f docker-compose.demo.yml up --buildÖffnen Sie dann http://localhost:3000. Für reine CPU-Entwicklung verwenden Sie stattdessen docker-compose.demo.cpu.yml (CPU ist nur für Dev/CI — einstellige Bilder/Sek.).