Embedding-Modell selbst im Docker-Container betreiben

Für eine interne Dokumentensuche brauchen Sie ein Embedding-Modell, das Texte in Vektoren umrechnet. Mit Text Embeddings Inference von Hugging Face läuft es als Container im eigenen Netz und antwortet über eine einfache HTTP-Schnittstelle.

Niklas Schult4 Min. Lesezeit

Illustration: Ein offener Container mit einem Karteikasten darin ist per Schlauch mit einer kleinen Holzkiste samt Sieb verbunden.

Was Sie am Ende haben und was Sie vorher brauchen

Am Ende läuft in Ihrem Netz ein Server, der Texte per HTTP in Vektoren umwandelt und Suchtreffer nach Relevanz neu ordnet. Beide Funktionen bilden die Grundlage einer Dokumentensuche, bei der kein Text das Haus verlassen muss. Als Vorlage dient die README von Text Embeddings Inference, die wir hier auf eine konkrete Aufgabe zuschneiden.

Sie benötigen einen Linux-Rechner mit Docker. Für den GPU-Betrieb verlangt die Dokumentation das NVIDIA Container Toolkit und Treiber, die zu CUDA 12.2 oder höher passen. Wer keine passende Grafikkarte hat, nutzt das CPU-Image, das die Dokumentation ebenfalls nennt. Beim ersten Start lädt der Container die Modellgewichte aus dem Hugging Face Hub, danach genügt ein lokales Verzeichnis.

Embedding-Server mit Docker starten

Der folgende Aufruf setzt zwei Variablen und startet den Container mit dem Modell Qwen/Qwen3-Embedding-0.6B. Das Verzeichnis data wird eingebunden, damit die Gewichte nicht bei jedem Start neu heruntergeladen werden. Der Container hört intern auf Port 80 und ist nach außen auf Port 8080 gelegt.

Shell
model=Qwen/Qwen3-Embedding-0.6B
volume=$PWD/data # keep the weights between runs

docker run --gpus all -p 8080:80 -v $volume:/data --pull always \
  ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 --model-id $model

Die Dokumentation führt Images für verschiedene Grafikkarten auf, etwa 86-1.9 für Ampere 8.6 oder hopper-1.9 für H100. Ohne GPU verwenden Sie auf x86_64 das Image cpu-1.9 und lassen den Schalter --gpus all weg. Wählen Sie das Image also passend zu Ihrer Hardware, bevor Sie den Container zum ersten Mal starten.

Welches Modell sich eignet, hängt von Sprache und Hardware ab. Die Dokumentation listet Beispiele mit Größenangaben, darunter das mehrsprachige intfloat/multilingual-e5-large-instruct. Größere Modelle wie Qwen/Qwen3-Embedding-8B stuft die Dokumentation als sehr aufwendig im Betrieb ein, das hier gewählte Qwen/Qwen3-Embedding-0.6B ist deutlich kleiner.

Texte einbetten und Treffer neu ordnen

Der Server nimmt Anfragen an der Route /embed entgegen. Der folgende Aufruf sendet einen Text als JSON und erhält den Vektor zurück, den Sie später in einer Vektordatenbank oder einem Suchindex ablegen.

Shell
curl 127.0.0.1:8080/embed \
    -X POST \
    -d '{"inputs":"Wie lange beträgt die Kündigungsfrist?"}' \
    -H 'Content-Type: application/json'

Ein Reranking-Modell sortiert die Treffer der ersten Suche nach ihrer Nähe zur Frage. Dafür starten Sie einen zweiten Container mit einem Reranker, hier BAAI/bge-reranker-large. Legen Sie ihn auf einen anderen Host-Port als den Embedding-Server.

Shell
model=BAAI/bge-reranker-large
volume=$PWD/data

docker run --gpus all -p 8081:80 -v $volume:/data --pull always \
  ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 --model-id $model

Die Route /rerank erwartet eine Frage und eine Liste von Texten. Das Ergebnis bewertet jeden Text im Verhältnis zur Frage, sodass Sie die besten Treffer an die Anwendung weitergeben können.

Shell
curl 127.0.0.1:8081/rerank \
    -X POST \
    -d '{"query": "Kündigungsfrist", "texts": ["Text A", "Text B"]}' \
    -H 'Content-Type: application/json'

Betrieb ohne Internetzugang und mit Schlüssel

Für Netze ohne Verbindung nach außen beschreibt die Dokumentation einen Weg. Sie laden die Gewichte vorab mit git lfs herunter und binden das Verzeichnis als Volume ein. Die Modell-ID zeigt dann auf einen Pfad im Container, etwa /data/Qwen3-Embedding-0.6B, und der Zugriff auf den Hub zur Laufzeit entfällt.

Der Server beantwortet standardmäßig jede Anfrage. Mit der Option --api-key oder der Umgebungsvariable API_KEY muss jeder Aufruf den Schlüssel als Bearer Token im Header Authorization mitsenden. Setzen Sie diese Option, sobald mehrere Anwendungen im Netz den Dienst erreichen können.

Die Reihenfolge der Schritte lässt sich so planen: Zuerst laden Sie auf einem Rechner mit Internetzugang die Gewichte herunter. Danach übertragen Sie das Verzeichnis auf den Zielrechner und starten den Container mit dem Pfad als Modell-ID. Wie Sie das Image selbst ohne Verbindung auf den Zielrechner bringen, lässt die Dokumentation offen.

Prüfen, ob es funktioniert, und typische Stolpersteine

Rufen Sie /embed mit einem Beispieltext auf und kontrollieren Sie, ob eine Zahlenliste zurückkommt. Die OpenAPI-Beschreibung der Schnittstelle erreichen Sie unter der Route /docs des laufenden Servers. Die Logs zeigen beim Start, welches Modell geladen wurde.

  • Die Eingabe wird standardmäßig gekürzt, wenn sie die maximale Länge des Modells überschreitet. Setzen Sie --auto-truncate auf false, startet der Server in manchen Fällen gar nicht.
  • Pro Anfrage sind standardmäßig höchstens 32 Eingaben erlaubt, und die Nutzlast ist auf 2 MB begrenzt.
  • Volta-Karten werden nicht unterstützt, Turing ist als experimentell gekennzeichnet.
  • Gesperrte Modelle wie google/embeddinggemma-300m benötigen einen Hugging Face Token in HF_TOKEN.

Wenn Anfragen abgelehnt werden, prüfen Sie zuerst --max-concurrent-requests mit dem Standardwert 512. Den Durchsatz steuert --max-batch-tokens, das die Dokumentation als wichtigste Stellschraube nennt.

Einordnung im Unternehmen

Ein solcher Dienst gehört in ein internes Netz hinter eine Zugriffskontrolle, und jemand muss Modellstand, Image-Version und Schlüssel pflegen. Prometheus-Metriken und OpenTelemetry sind laut Dokumentation vorgesehen, sodass sich der Betrieb in vorhandene Überwachung einhängen lässt. Welche Dokumente Sie einbetten und wie lange Vektoren gespeichert werden, klären Sie am besten mit Ihrer Datenschutzstelle, denn Vektoren können Rückschlüsse auf Inhalte erlauben.

Wer die Dokumentensuche nicht selbst zusammenbauen will, findet bei lokaler KI und bei der Wissensmanagement-Software fertige Wege. souveraen.ai läuft in zwei Betriebsarten, gehostet in Deutschland oder on-premise auf einer NVIDIA DGX Spark im Firmennetz. Eigene Anwendungen binden Sie über die OpenAI-kompatible Entwickler-API an.

Quellen

Weitere Beiträge

Alle Beiträge

KI-API-Zugänge bei Resellern: Was die Dragos-Tests zeigen

Sicherheitsforscher von Dragos haben mit rund zwei Millionen Testanfragen gezeigt, dass Zwischenhändler und kompromittierte Anbieter Anfragen an KI-Modelle mitlesen. Wer KI per Schnittstelle nutzt, sollte daher klären, über wen die eigenen Daten tatsächlich laufen.

Datenschutz4 Min.

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.

Anleitung4 Min.

Haftung bei Cloud-Ausfall: Wer trägt das Risiko?

Der Ausfall von Exchange Online und Outlook am 12. November 2026 dauerte etwa 36 Stunden und traf viele Betriebe. Wer dafür einstehen muss, betrifft jede Firma, die Cloud- und KI-Dienste nutzt.

Regulierung4 Min.

Testen Sie es mit Ihren eigenen Dokumenten.

3 Tage kostenlos, danach ab 24,90 € je Nutzer und Monat. Monatlich kündbar.

3 Tage kostenlos, danach ab 24,90 € je Nutzer und Monat.3 Tage kostenlos
3 Tage kostenlos testen