Zum Inhalt springen

Versteckte Online-Abhängigkeiten von KI-Software finden

Ein lokales Sprachmodell ist schnell gestartet. Schwieriger ist der Nachweis, dass der gesamte Stack danach wirklich nichts mehr aus dem Internet holt: Viele Bibliotheken laden Tokenizer nach, melden Nutzungsdaten oder installieren Pakete beim ersten Aufruf. Diese Checkliste sammelt die typischen Stellen, nennt die Schalter dafür und zeigt, wie Sie das Ergebnis prüfen. Stand der genannten Dokumentationen: November 2026.

Wofür ist diese Checkliste gedacht?

Die Checkliste richtet sich an Entwickler und Betreiber, die einen KI-Stack in einem abgeschotteten oder streng gefilterten Netz betreiben. Sie ergänzt den Überblick zu Air-Gapped KI in abgeschotteten Netzen um die Frage, was die Software selbst zur Laufzeit nachlädt.

Abgrenzung zum Geschwisterartikel: Modelle in ein Air-Gap-Netz bringen behandelt den einmaligen Transport der Gewichte durch die Schleuse. Hier geht es um alles, was danach trotzdem noch versucht, eine Verbindung aufzubauen. Wer beides sauber trennt, findet Fehler schneller: Ein fehlendes Modell ist ein Transportproblem, ein Verbindungsversuch beim Start ist ein Konfigurationsproblem.

Gruppe 1: Modelle und Tokenizer, die zur Laufzeit nachgeladen werden

Die häufigste versteckte Abhängigkeit ist der Hugging Face Hub. Auch wenn alle Dateien im Cache liegen, prüft die Bibliothek ohne weitere Einstellung, ob es eine neuere Version gibt. Diese Prüfung schalten Sie mit HF_HUB_OFFLINE=1 ab; fehlende Dateien führen dann zu einem Fehler statt zu einem Download.

  • HF_HUB_OFFLINE=1 setzen. Laut Dokumentation von huggingface_hub löst hf_hub_download selbst bei vorhandenem Cache eine HTTP-Anfrage aus, um nach neuen Versionen zu suchen; mit der Variable entfällt sie. Wichtig: Die Variablen werden beim Import gelesen, also vor dem Start des Python-Prozesses setzen.
  • Revisionen per Commit-Hash festlegen. Nach der Transformers-Dokumentation fragt ein Ladevorgang mit Branch oder Tag den Hub einmal zu Beginn, um den Commit zu bestimmen. Mit Commit-Hash bleibt es beim Cache. local_files_only=True in from_pretrained() ist die Alternative im Code.
  • Cache-Pfad fest vorgeben. HF_HOME oder HF_HUB_CACHE auf ein Verzeichnis zeigen lassen, das zum Image oder Volume gehört, nicht auf das Home-Verzeichnis eines Benutzers.
  • tiktoken-Encodings vorab ablegen. Die Encodings wie cl100k_base und o200k_base kommen laut Quellcode von openaipublic.blob.core.windows.net. Der Cache liegt laut load.py ohne TIKTOKEN_CACHE_DIR im temporären Verzeichnis unter data-gym-cache. Setzen Sie TIKTOKEN_CACHE_DIR auf ein dauerhaftes Verzeichnis und befüllen Sie es vor dem Transport.
  • Embedding-, Reranking- und Sprachmodelle mitdenken. Die Open-WebUI-Anleitung zum Offline-Betrieb warnt, dass eine frische Installation zwar starten, aber beim ersten Dokument-Upload scheitern kann, wenn das Embedding-Modell fehlt.

Gruppe 2: Telemetrie abschalten

Mehrere verbreitete Komponenten senden standardmäßig Nutzungsdaten. Das ist im abgeschotteten Netz nicht nur eine Datenschutzfrage: Gesperrte Verbindungen erzeugen Timeouts und Log-Rauschen. Schalten Sie Telemetrie je Komponente ab und verlassen Sie sich nicht auf einen einzigen globalen Schalter.

  • Hugging Face: HF_HUB_DISABLE_TELEMETRY=1. Laut Dokumentation wirkt DO_NOT_TRACK=1 im Python-Ökosystem von Hugging Face gleich, also auch für transformers, diffusers und gradio.
  • vLLM: Sammelt laut vLLM-Dokumentation standardmäßig anonyme Nutzungsdaten. Abschalten mit VLLM_NO_USAGE_STATS=1, DO_NOT_TRACK=1 oder der Datei ~/.config/vllm/do_not_track.
  • Chroma: In config.py steht anonymized_telemetry standardmäßig auf True, die Implementierung nutzt PostHog. Abschalten mit ANONYMIZED_TELEMETRY=False, wie es Chroma selbst in seinen Test-Compose-Dateien tut, oder per Settings(anonymized_telemetry=False) im Client.
  • Gradio: GRADIO_ANALYTICS_ENABLED steht laut Gradio-Dokumentation standardmäßig auf "True"; für den Offline-Betrieb auf "False" setzen.
  • Streamlit: Die Option gatherUsageStats im Abschnitt [browser] der config.toml steht standardmäßig auf true.
# Beispiel: Umgebung für einen Offline-Dienst
export HF_HUB_OFFLINE=1
export HF_HUB_DISABLE_TELEMETRY=1
export DO_NOT_TRACK=1
export VLLM_NO_USAGE_STATS=1
export ANONYMIZED_TELEMETRY=False
export GRADIO_ANALYTICS_ENABLED=False
export TIKTOKEN_CACHE_DIR=/opt/ki/tiktoken-cache

Gruppe 3: Update-Checks und Versionsprüfungen

Update-Prüfungen sind harmlos gemeint, aber im abgeschotteten Netz eine weitere Verbindung pro Start. Sie verlangsamen den Start oder erzeugen Warnungen. Deaktivieren Sie sie ausdrücklich, statt auf das Netzwerk-Timeout zu warten.

  • hf-Kommandozeile: Prüft laut Dokumentation höchstens alle 24 Stunden auf PyPI, ob es eine neuere Version gibt. HF_HUB_DISABLE_UPDATE_CHECK=1 schaltet das ab.
  • Open WebUI: OFFLINE_MODE=true setzt laut Offline-Anleitung HF_HUB_OFFLINE=1, deaktiviert die Versionsprüfung und die Auto-Update-Schalter für Modelle. Die Anleitung betont zugleich, dass diese Variablen ausgehende Verbindungen nicht blockieren.
  • Sprach-Modelle in Open WebUI: WHISPER_MODEL_AUTO_UPDATE=false allein verhindert laut derselben Anleitung keinen Download, wenn das Modell fehlt; erst HF_HUB_OFFLINE=1 stoppt den Versuch.
  • Eigene Container und Skripte: Startskripte auf apt-get update, git pull oder curl durchsuchen. Solche Zeilen gehören in den Build, nicht in den Start.

Gruppe 4: Installationen beim Start

Manche Anwendungen installieren Python-Pakete erst dann, wenn eine Erweiterung geladen wird. Ohne Netz bricht das Laden ab, mit Netz ändert sich die Software ungeprüft im Betrieb. Beides ist im abgeschotteten Netz unerwünscht.

  • Open WebUI Tools und Functions: Anforderungen aus dem Frontmatter einer Erweiterung werden laut plugin.py per pip install in einem Unterprozess installiert. Der Schalter ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS steht in env.py standardmäßig auf True; im Offline-Modus wird die Installation übersprungen. Die Pakete müssen dann bereits im Image sein.
  • pip auf ein lokales Verzeichnis umstellen. Mit --no-index und --find-links liest pip laut pip-Dokumentation nur aus einem Wheel-Verzeichnis; --require-hashes prüft jede Anforderung gegen einen Hash.
  • Fremdcode aus Modell-Repositories. trust_remote_code=True lädt Modellcode, der nicht aus Transformers stammt. Die Transformers-Dokumentation empfiehlt, dafür eine feste Revision anzugeben. Im Air-Gap muss dieser Code mit dem Modell transportiert und geprüft werden.
  • Nachgeladene Sprachdaten. NLTK-Pakete lassen sich laut NLTK-Dokumentation manuell in ein nltk_data-Verzeichnis legen; NLTK_DATA zeigt darauf. Prüfen Sie, ob Ihre Dokumentenverarbeitung nltk.download() aufruft.
# Pakete aus einem lokalen Wheel-Verzeichnis installieren, Hashes erzwingen
pip install --no-index --find-links /opt/ki/wheels --require-hashes -r requirements.txt

Gruppe 5: Lizenzprüfungen und Aktivierungen

Kommerzielle Komponenten wie Treiber-Pakete, Entwicklungsumgebungen oder Datenbanken können eine Online-Aktivierung oder einen Lizenzserver verlangen. Klären Sie das vor der Beschaffung, denn eine fehlende Aktivierung zeigt sich oft erst nach Tagen.

  • Aktivierungsart im Lizenzvertrag oder in der Herstellerdokumentation nachlesen: online, offline per Datei oder über einen lokalen Lizenzserver.
  • Ablaufdaten notieren. Hat eine Offline-Lizenzdatei eine Laufzeit, verhindert ein Kalendereintrag den Stillstand.
  • Lizenzserver in das abgeschottete Netz stellen, wenn der Hersteller das anbietet, statt eine Ausnahme in der Firewall zu öffnen.

Wie prüfen Sie, ob der Stack wirklich offline läuft?

Der zuverlässigste Test ist ein Lauf ohne Netzwerk, bei dem jede Funktion einmal ausgelöst wird. Ein erfolgreicher Start beweist wenig, weil viele Downloads erst beim ersten Upload, der ersten Suche oder der ersten Spracheingabe passieren.

  • Container ohne Netz starten. Mit --network none bekommt ein Container laut Docker-Dokumentation nur das Loopback-Interface.
  • Funktionsliste abarbeiten: Chat, Dokument hochladen, Suche, Reranking, Spracheingabe, jede installierte Erweiterung.
  • Logs auf Verbindungsversuche durchsuchen: Timeouts, DNS-Fehler und Hinweise wie „offline mode".
  • Ausgehende Verbindungen an der Firewall protokollieren, auch wenn sie geblockt werden. Jeder Eintrag ist ein Hinweis auf eine vergessene Abhängigkeit.

Typische Lücken

Die meisten Probleme entstehen nicht beim ersten Start, sondern später. Sie zeigen sich nach einem Neustart, einer Erweiterung oder einem Update. Auf diese vier Muster sollten Sie achten.

  • Cache im temporären Verzeichnis, der nach einem Neustart fehlt, zum Beispiel der tiktoken-Cache ohne gesetztes TIKTOKEN_CACHE_DIR.
  • Umgebungsvariablen nur in der Shell gesetzt, nicht im Dienst, im Container oder in der systemd-Unit.
  • Neue Erweiterung oder neues Modell ohne erneuten Offline-Test.
  • Offline-Schalter mit Netzsperre verwechselt: Offline-Variablen ändern Programmverhalten, sie ersetzen keine Firewall-Regeln.

Nächster Schritt

Legen Sie die Umgebungsvariablen zentral in der Dienstkonfiguration ab, versionieren Sie sie mit dem Image und wiederholen Sie den Offline-Test bei jeder Änderung. Wie sich ein solcher Betrieb insgesamt aufstellen lässt, beschreibt die Seite zu souveräner KI.

Häufige Fragen

Reicht HF_HUB_OFFLINE=1, um einen KI-Stack offline zu betreiben?

Nein. Die Variable stoppt nur Aufrufe an den Hugging Face Hub. Telemetrie anderer Bibliotheken, tiktoken-Downloads, pip-Installationen und Update-Checks fremder Tools laufen davon unabhängig weiter.

Ist DO_NOT_TRACK=1 ein allgemeiner Schalter gegen Telemetrie?

Nur für Software, die die Variable ausdrücklich auswertet, etwa das Hugging-Face-Ökosystem und vLLM laut deren Dokumentation. Für jede weitere Komponente prüfen Sie den eigenen Opt-out-Schalter.

Warum startet die Anwendung im Test, scheitert aber später im Betrieb?

Viele Downloads passieren erst bei der ersten Nutzung einer Funktion, etwa beim ersten Dokument-Upload oder der ersten Spracheingabe. Der Test muss deshalb jede Funktion einmal ohne Netz auslösen, nicht nur den Start.

Muss ich Telemetrie abschalten, wenn das Netz ohnehin gesperrt ist?

Ja, empfehlenswert. Gesperrte Verbindungen erzeugen sonst Timeouts, Wiederholungsversuche und Fehlermeldungen in den Logs, die echte Probleme verdecken.

Quellen

  1. huggingface_hub: Environment variables huggingface.co
  2. Transformers: Installation, Cache und Offline-Modus huggingface.co
  3. Transformers: Loading models (Custom models, trust_remote_code) huggingface.co
  4. vLLM: Usage Stats Collection docs.vllm.ai
  5. tiktoken: load.py (Cache und Download der BPE-Dateien) github.com
  6. tiktoken: openai_public.py (Download-URLs der Encodings) github.com
  7. Chroma: config.py (anonymized_telemetry) github.com
  8. Chroma: docker-compose.test.yml (ANONYMIZED_TELEMETRY=False) github.com
  9. Open WebUI: Running in offline mode docs.openwebui.com
  10. Open WebUI: env.py (ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS, OFFLINE_MODE) github.com
  11. Open WebUI: plugin.py (pip install der Tool-Anforderungen) github.com
  12. Gradio: Environment Variables gradio.app
  13. Streamlit: config.toml docs.streamlit.io
  14. pip install: --no-index, --find-links, --require-hashes pip.pypa.io
  15. NLTK: Installing NLTK Data nltk.org
  16. Docker: None network driver docs.docker.com