Bereitstellung

Alles, was Sie als Betreiber brauchen, um TurboOCR von „Ich will das in Produktion betreiben” zu „Es läuft, ist überwacht und kippt nicht um” zu bringen. Diese Seite behandelt die unterstützten Docker-Tags, die erforderliche GPU- und Treiberbasis, das TensorRT-Cache-Volume, die Modellumschaltung, MPS-basierte Skalierung, Monitoring-Endpoints und eine kurze Produktions-Checkliste.

Voraussetzungen

• Betriebssystem — Linux. Der Container basiert auf dem offiziellen NVIDIA-TensorRT-Image und ist auf Ubuntu 24.04 verifiziert.
• GPU — NVIDIA Turing oder neuer (RTX 20-series, GTX 16-series oder neuer).
• Treiber — NVIDIA-Treiber 595 oder neuer sowie das NVIDIA Container Toolkit, damit Docker --gpus all respektiert.
• VRAM — etwa ~4 GB für ein reines Text-Deployment und ~8 GB für die volle Pipeline (Layout + Tabellen + Formeln). Jedes zusätzliche PIPELINE_POOL_SIZE-Replica kostet rund einen weiteren vollen Satz.
• CPU-Fallback — ein reines CPU-Image existiert für Maschinen ohne GPU, der Durchsatz ist jedoch deutlich geringer (einstellige Bilder/Sekunde) und es ist nicht für die Produktion gedacht.

Docker-Images

Vorgefertigte Images werden in der GitHub Container Registry unter ghcr.io/aiptimizer/turboocr veröffentlicht. Zwei Varianten entstehen aus docker/Dockerfile.gpu und docker/Dockerfile.cpu im Quell-Repo.

Tag	Zweck	Hinweise
:latest	GPU-Image, folgt dem neuesten Release	Drogon-HTTP auf 8000 (über nginx), gRPC auf 50051. Enthält jeden Erkenner, PP-DocLayoutV3 sowie die Tabellen-/Formel-Gewichte. Praktisch für Demos; in Produktion pinnen.
:v3.1.0	Gepinntes GPU-Image	Das aktuelle Release — in Produktion verwenden.
turboocr-cpu:v3.1.0	CPU-Fallback	ONNX Runtime statt TensorRT (eigenes Image: ghcr.io/aiptimizer/turboocr-cpu). Einstellige Bilder/Sek. — nur für Dev/CI.

Achtung

In der Produktion eine Version pinnen. Nutzen Sie ein explizites Tag wie :v3.1.0 statt :latest. Damit bleibt ein Rollback trivial und ein überraschendes Upgrade kann nicht mitten im Vorfall TensorRT-Engines neu bauen.

Namen der Server-Binaries

Im Image wurden die Server-Binaries in v3 umbenannt: GPU ist turboocr-server (vormals paddle_highspeed_cpp) und CPU ist turboocr-cpu-server (vormals paddle_cpu_server). Docker-Nutzer sind nicht betroffen; das zählt nur für native Builds und --print-config.

GPU-Image

Das Standard-Image fährt die vollständige TensorRT-Pipeline. Beim ersten Start werden die Engines aus den ONNX-Dateien kompiliert (rund 90 Sekunden auf einer RTX 5090, bis zu ~1 Stunde auf älteren GPUs); das Named Volume trt-cache bewahrt sie auf, sodass jeder weitere Start sofort fertig ist.

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 läuft auf 8000 (nginx vor Drogon, zur Pufferung langsamer Clients) und gRPC auf 50051. Beide Protokolle teilen sich denselben GPU-Pipeline-Pool — Sie können sie gleichzeitig aus demselben Container betreiben.

Ersten Build mit TRT_OPT_LEVEL beschleunigen

Der Engine-Build nutzt standardmäßig die höchste Optimierungsstufe (TRT_OPT_LEVEL=5, schnellste Laufzeit). Setzen Sie auf einer langsamen GPU TRT_OPT_LEVEL=3, um diesen einmaligen Build um das 3–5-Fache zu verkürzen, bei einer kleinen (<5 %) Laufzeit-Einbuße. Die Stufe ist Teil des Engine-Cache-Schlüssels, ein Wechsel löst also einen Neubau aus.

CPU-Image

Das CPU-Image ist ein Drop-in-Fallback für Hosts ohne NVIDIA-GPU. Es nutzt ONNX Runtime statt TensorRT, läuft auf einfachem ubuntu:24.04 und stellt dieselbe HTTP-API bereit.

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

Achtung

Der Durchsatz liegt im einstelligen Bilder/Sek.-Bereich im Vergleich zu bis zu ~556 img/s auf einer einzelnen RTX 5090. Der CPU-Build ist für lokale Entwicklung, CI und Integrationstests gedacht — nicht für Produktionsverkehr.

TensorRT-Cache-Volume

TensorRT-Engines und Sprachpakete liegen im Container unter /home/ocr/.cache/turbo-ocr. Hängen Sie diesen Pfad als Named Volume ein — niemals als Host-Bind-Mount.

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

Warum ein Named Volume. Das Image setzt einen Symlink von /app/models/rec in das Cache-Verzeichnis, damit auch nicht-standardmäßige Sprachpakete dort liegen. Ein Bind-Mount auf ein leeres Hostverzeichnis würde diesen Pfad überdecken und der Server stünde ohne Modelle da. Named Volumes werden beim ersten Einsatz automatisch aus dem Image befüllt — genau das, was Sie wollen.

Wenn Sie das Volume löschen. Beim nächsten Start werden alle TensorRT-Engines aus den ONNX-Dateien neu gebaut (~90 s) und die mitgelieferten Pakete neu entpackt. Es geht nichts verloren — es dauert nur einen langsamen Kaltstart länger.

Modellauswahl

Setzen Sie die Umgebungsvariable OCR_MODEL beim Start. Alle Modelle sind beim Build-Vorgang aus gepinnten PaddleOCR-Releases ins Image eingebacken; zur Laufzeit wird nichts heruntergeladen.

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

Die PP-OCRv6-Stufen tiny (Standard) / small / medium decken Latein + Chinesisch + Japanisch ab und tauschen Genauigkeit gegen Geschwindigkeit. Andere Schriften nutzen die beibehaltenen PP-OCRv5-Erkenner über dieselbe Variable: arabic, eslav (Kyrillisch), korean, thai, greek. OCR_LANG funktioniert weiterhin als veralteter Alias (warnt bei Verwendung). Den vollständigen Aufschlüsselung finden Sie auf der Seite Konfiguration.

Web-GUI (Studio)

Das Repository liefert eine Browser-Oberfläche — legen Sie ein Bild oder PDF ab, führen Sie OCR aus, sehen Sie das Layout-Overlay und die Lesereihenfolge, markieren Sie erkannten Text und laden Sie ein durchsuchbares PDF herunter. Sie läuft als zweiter Container, der /api/* an den OCR-Server proxyt, sodass der Browser same-origin bleibt und der Server kein CORS braucht.

Aus dem Stammverzeichnis des Quell-Repos:

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

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

Öffnen Sie dann http://localhost:3000. Das Demo-Compose aktiviert TABLE_BACKEND=slanext und FORMULA_BACKEND=ppformulanet_s, sodass Tabellen und Formeln durchgängig verfügbar sind. Der OCR-Dienst bleibt für curl direkt unter http://localhost:8000 erreichbar.

Persistente Verbindungen

Achtung

Verwenden Sie HTTP-Keep-alive. Eine kurzlebige Verbindung pro Anfrage zu öffnen — etwa eine enge curl-Schleife — kann den Server überlasten und ihn zum Stillstand bringen. Jeder gängige HTTP-Client (requests.Session, aiohttp, httpx.Client, JDK HttpClient, Go http.Client, libcurl mit langlebigem Handle) verwendet Verbindungen standardmäßig wieder, sofern Sie das Client-Objekt wiederverwenden. Erzeugen Sie keinen frischen Client pro Anfrage.

Das mitgelieferte Image fährt nginx vor Drogon, um langsame Clients zu puffern, doch nginx kann einen Client nicht retten, der pro Anfrage eine neue TCP-Verbindung öffnet. Im Clients-Leitfaden finden Sie funktionierende Beispiele für Python, Java und C++.

Monitoring

Prometheus-Metriken

Scrapen Sie GET /metrics für Prometheus-kompatible Metriken. Der Server liefert pro Route Request-Counter, Latenz-Histogramme, VRAM-Auslastung und die Sättigung des Pipeline-Pools:

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

Tipp

Behalten Sie turbo_ocr_pool_exhaustions_total im Auge. Ein Wert ungleich null bedeutet, dass Clients am Pipeline-Pool warten — erhöhen Sie entweder PIPELINE_POOL_SIZE oder skalieren Sie Replicas. Latenz-Histogramme sind pro Route in Buckets aufgeteilt, sodass Sie jeden Endpoint einzeln per SLO überwachen können.

Health-Probes

Endpoint	Verwendung
GET /health	Einfache Lebenszeichenprüfung — liefert "ok".
GET /health/live	Kubernetes-Liveness-Probe. Liefert 200, sobald der Prozess hochgefahren ist.
GET /health/ready	Readiness-Probe. Liefert 200 erst, wenn die GPU-Pipeline einen Smoke-Test besteht — Traffic darauf gaten.

Aus dem Quellcode bauen

Für lokale Builds, eigene CUDA-Targets oder Air-Gapped-Bereitstellungen sehen Sie sich die Build-Anweisungen im GitHub-Repository an. Die Dockerfiles unter docker/ sind die kanonische Referenz; der Abschnitt „Building from Source” der README listet alle Abhängigkeiten und die CMake-Aufrufe für GPU- und CPU-Targets.

Konfiguration Jede Umgebungsvariable: Sprachpakete, Pipeline-Pool-Größe, PDF-Parallelität, Logging.

Clients Produktionsreife Rezepte für Python, Java und C++ — persistente Verbindungen, Fan-out, gRPC.