Text Generation Inference mit Docker selbst betreiben
Mit Text Generation Inference betreiben Sie ein offenes Sprachmodell als Container auf einem eigenen Server. Anfragen bleiben im Firmennetz, sodass keine Texte an einen Cloud-Anbieter gehen.

Ziel und Voraussetzungen
Am Ende läuft auf Ihrem Server ein Container, der ein offenes Sprachmodell über HTTP bereitstellt. Sie fragen es mit curl ab, und zwar über die eigene Schnittstelle ebenso wie über eine Schnittstelle im Format der OpenAI Chat Completion API. Die Grundlage ist das README von Text Generation Inference von Hugging Face.
Sie brauchen einen Linux-Server mit Docker und eine NVIDIA-Grafikkarte. Dafür verlangt die Dokumentation das NVIDIA Container Toolkit und empfiehlt Treiber mit CUDA 12.2 oder höher. Für AMD Instinct MI210 und MI250 gibt es ein eigenes Image mit dem Zusatz rocm. Beim ersten Start lädt der Container die Modellgewichte aus dem Internet, danach arbeitet er mit den lokal gespeicherten Dateien.
Zur Einordnung: Das Projekt befindet sich laut README im Wartungsmodus. Es nimmt nur noch kleine Fehlerkorrekturen und Verbesserungen der Dokumentation an. Als Alternativen nennen die Entwickler vllm und SGLang sowie lokale Engines wie llama.cpp oder MLX.
Container starten und Modell laden
Der folgende Befehl legt zunächst das Modell und ein Datenverzeichnis fest. Das Verzeichnis wird in den Container eingebunden, damit die Gewichte nicht bei jedem Start neu heruntergeladen werden. Der Container lauscht intern auf Port 80, der Befehl veröffentlicht ihn als Port 8080.
model=HuggingFaceH4/zephyr-7b-beta
# share a volume with the container to avoid downloading weights every run
volume=$PWD/data
docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data \
ghcr.io/huggingface/text-generation-inference:3.3.5 --model-id $modelDer Schalter --shm-size 1g gibt dem Container ein Gigabyte gemeinsamen Speicher. Diesen braucht die Kommunikationsbibliothek NCCL, wenn Daten zwischen mehreren Grafikkarten ausgetauscht werden. Warten Sie mit der ersten Anfrage, bis der Start abgeschlossen ist.
Das Image trägt im Beispiel die Version 3.3.5. Übernehmen Sie diese Angabe zunächst unverändert, damit Ihr Aufbau mit der Dokumentation übereinstimmt. Welche Modelle der Server optimiert unterstützt, steht in einer Liste, auf die das README verweist. Andere Architekturen laufen nach Angabe der Entwickler nach bestem Bemühen über die Transformers-Bibliothek.
Das Modell über HTTP abfragen
Die erste Abfrage nutzt den Endpunkt generate_stream. Sie sendet einen Text und begrenzt die Antwort über max_new_tokens auf 20 Token. Die Antwort kommt als Datenstrom per Server-Sent Events zurück.
curl 127.0.0.1:8080/generate_stream \
-X POST \
-d '{"inputs":"What is Deep Learning?","parameters":{"max_new_tokens":20}}' \
-H 'Content-Type: application/json'Für bestehende Anwendungen eignet sich die Messages API, die zur OpenAI Chat Completion API kompatibel ist. Der Aufruf geht an /v1/chat/completions und enthält eine Liste von Nachrichten mit Rollen. Der Wert tgi im Feld model entspricht dem Beispiel der Dokumentation.
curl localhost:8080/v1/chat/completions \
-X POST \
-d '{"model":"tgi","stream":true,"max_tokens":20,\
"messages":[{"role":"user","content":"What is deep learning?"}]}' \
-H 'Content-Type: application/json'Prüfen, ob alles funktioniert
Kommen bei beiden Aufrufen Textstücke zurück, läuft der Dienst. Die Schnittstellenbeschreibung erreichen Sie über die Route /docs auf demselben Port, dort steht die OpenAPI-Dokumentation mit allen Parametern. Alle Startoptionen zeigt der Launcher selbst an.
text-generation-launcher --helpMöchten Sie das Verhalten im Betrieb beobachten, nennt das README Prometheus-Metriken und verteilte Nachverfolgung mit OpenTelemetry. Die Adresse eines OTLP-Collectors setzen Sie mit dem Argument --otlp-endpoint. Den Dienstnamen ändern Sie mit --otlp-service-name.
Typische Stolpersteine
- Ohne Grafikkarte entfernen Sie --gpus all und ergänzen --disable-custom-kernels. Die CPU ist laut Dokumentation nicht die vorgesehene Plattform, die Leistung fällt dann womöglich schwach aus.
- Geschützte Modelle wie meta-llama/Meta-Llama-3.1-8B-Instruct verlangen ein Zugriffstoken. Sie übergeben es mit -e HF_TOKEN=$token an den Container.
- Läuft der Dienst in Kubernetes, richten Sie ein Volume vom Typ emptyDir mit medium Memory und sizeLimit 1Gi ein und binden es unter /dev/shm ein.
- Mit NCCL_SHM_DISABLE=1 lässt sich der gemeinsame Speicher abschalten, das kostet laut README Leistung.
Der Port 8080 im Beispiel ist ohne Anmeldung erreichbar. Die Dokumentation beschreibt keine Authentifizierung für die Schnittstelle. Schränken Sie den Zugriff deshalb über Firewall oder vorgeschalteten Proxy auf das interne Netz ein.
Reicht der Grafikspeicher nicht aus, bietet das README Quantisierung an. Vorquantisierte Gewichte oder die Umrechnung zur Laufzeit senken den Bedarf an VRAM. Der Schalter --quantize bitsandbytes-nf4 aktiviert die 4-Bit-Variante, --quantize bitsandbytes-fp4 die verwandte Form. Prüfen Sie nach einer Umstellung die Antwortqualität an Ihren eigenen Beispielen.
Einordnung im Unternehmen
Ein solcher Container braucht einen Verantwortlichen, der Images aktualisiert, Speicherplatz für Gewichte bereitstellt und die Metriken im Blick behält. Da das Projekt im Wartungsmodus ist, sollten Sie früh klären, ob ein späterer Wechsel auf eine der genannten Engines möglich ist. Die Messages API erleichtert das, weil Anwendungen ein verbreitetes Format sprechen.
Datenschutzrechtlich bleibt die Frage, welche Daten Nutzer eingeben und wer Zugriff auf die Protokolle hat. Beim Modelldownload fließen keine Firmendaten, die Abfragen selbst verlassen das Netz nicht. Mehr zum Thema finden Sie auf unseren Seiten zu lokaler KI und zu Sicherheit und Datenschutz.
Wer Container nicht selbst pflegen möchte, findet bei souveraen.ai die gleiche Software als Private Spark im eigenen Netz oder gehostet in Deutschland. Eine OpenAI-kompatible Entwickler-API bindet Modelle in eigene Anwendungen ein.
Quellen
- Text Generation Inference README, Hugging Face


