Wenn Sie versuchen, ein Modell über ollama pull
aus einem Unternehmensnetzwerk, über VPN oder über einen externen Proxy-Server herunterzuladen, sind Sie wahrscheinlich bereits auf Fehler wie
dial tcp: lookup registry.ollama.ai oder
context deadline exceeded gestoßen.
Ollama erfasst standardmäßig nicht immer korrekt die Systemeinstellungen für den Proxy, und die großen Modellgrößen (von 2 bis 70+ GB) verschärfen das Problem –
die Verbindung bricht während des Downloads ab. In diesem Artikel werden wir erläutern, wie man Umgebungsvariablen richtig festlegt, den Proxy in Docker und systemd konfiguriert,
sowie die häufigsten Pull-Fehler entschlüsseln und Lösungen dafür anbieten.
Wie Ollama mit Netzwerken und Proxys funktioniert
Ollama ist eine Client-Server-Anwendung: Der lokale Server (ollama serve)
empfängt Befehle von der CLI und führt Netzwerkabfragen an das Modell-Registry registry.ollama.ai und an das CDN aus, wo die Schichten (layers) der Modelle gespeichert sind.
Der Befehl ollama pull llama3 führt tatsächlich eine Reihe von HTTPS-Anfragen aus,
ähnlich wie bei Docker pull: Zuerst wird das Manifest des Modells angefordert, dann werden die binären Schichten (GGUF-Dateien der Gewichte) nacheinander oder parallel heruntergeladen.
Ein wichtiger Punkt: Die Netzwerkabfragen werden vom Serverprozess von Ollama und nicht vom CLI-Befehl ausgeführt. Das bedeutet, dass die Umgebungsvariablen
mit den Proxy-Einstellungen dort festgelegt werden müssen, wo der Prozess ollama serve läuft,
und nicht im Terminal, von dem aus Sie ollama pull aufrufen.
Wenn der Dienst als systemd-Einheit oder in einem Docker-Container ausgeführt wird, hat das Exportieren der Variablen in einer normalen Bash-Sitzung keinen Einfluss darauf –
das ist der häufigste Grund, warum "der Proxy scheint konfiguriert zu sein, aber pull funktioniert trotzdem nicht".
Umgebungsvariablen HTTP_PROXY, HTTPS_PROXY, NO_PROXY
Ollama ist in Go geschrieben, und die Standard-HTTP-Bibliothek von Go liest die Proxy-Einstellungen aus den klassischen Umgebungsvariablen:
HTTP_PROXY– Proxy für normale HTTP-AnfragenHTTPS_PROXY– Proxy für HTTPS-Anfragen (dies wird benötigt, um Modelle herunterzuladen, da das Registry über TLS funktioniert)NO_PROXY– Liste von Hosts, die vom Proxy ausgeschlossen werden sollen (z. B. die lokale API von Ollama auf 127.0.0.1:11434)
Format des Wertes: http://user:password@host:port für Proxy mit Authentifizierung
oder socks5://host:port für SOCKS5. Go unterstützt beide Varianten,
aber für SOCKS5 ist es wichtig, dass das Ollama-Binärpaket mit Unterstützung für diesen Proxy kompiliert wurde – in den meisten aktuellen Builds ist dies der Fall, aber bei Fehlern sollte man zuerst
auf HTTP/HTTPS-Proxys testen, um diese Variable auszuschließen.
Wichtig: Geben Sie die Variablen sowohl in Klein- als auch in Großbuchstaben an
(http_proxy und HTTP_PROXY).
Einige Linux-Distributionen lesen nur Kleinbuchstaben, während Go-Anwendungen manchmal Großbuchstaben erwarten – es ist besser, beide Varianten anzugeben, um keine Unsicherheiten zu haben.
Einrichtung unter Linux und macOS
Wenn Sie Ollama direkt aus dem Terminal (nicht als Systemdienst) starten, reicht es aus, die Variablen vor dem Start des Servers zu exportieren:
export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"
ollama serve &
ollama pull llama3
Um die Einstellungen zwischen den Sitzungen zu speichern, fügen Sie diese Zeilen in ~/.bashrc,
~/.zshrc oder ~/.profile
je nach verwendeter Shell hinzu. Nach der Bearbeitung führen Sie source ~/.bashrc
aus und starten den Ollama-Prozess neu – die Umgebungsvariablen werden nur beim Start des Prozesses gelesen, eine heiße Neuladefunktion ist nicht vorgesehen.
Unter macOS, wenn Ollama als Anwendung (nicht über Homebrew) installiert ist, können die Umgebungsvariablen aus dem Terminal möglicherweise nicht zum Prozess gelangen,
der über die GUI gestartet wurde. In diesem Fall ist es zuverlässiger, die Variablen über launchctl setenv festzulegen:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Danach starten Sie die Ollama-Anwendung vollständig neu (aus dem Tray aussteigen, nicht nur das Fenster schließen)
Einrichtung unter Windows
In PowerShell werden die Variablen für die aktuelle Sitzung mit folgendem Befehl festgelegt:
$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"
ollama pull mistral
Wenn Ollama als Hintergrunddienst (Symbol im System-Tray) ausgeführt wird, sind Sitzungvariablen nicht ausreichend – der Dienst startet beim Anmelden
bevor Sie PowerShell öffnen. Sie müssen die Variablen auf Benutzer- oder Systemeinstellungen über
"Einstellungen → System → Über → Erweiterte Systemeinstellungen → Umgebungsvariablen" festlegen, danach den Prozess
ollama.exe über den Task-Manager vollständig beenden und die Anwendung neu starten.
Proxy für Ollama in Docker
Wenn Ollama in einem Container ausgeführt wird (häufiger Fall bei Serverbereitstellungen), gelangen die Umgebungsvariablen des Hosts nicht automatisch in den Container –
sie müssen explizit über -e oder den Abschnitt environment
in docker-compose weitergeleitet werden:
docker run -d \
-e HTTP_PROXY="http://user:[email protected]:8000" \
-e HTTPS_PROXY="http://user:[email protected]:8000" \
-e NO_PROXY="localhost,127.0.0.1" \
-v ollama:/root/.ollama \
-p 11434:11434 \
--name ollama ollama/ollama
Analog in docker-compose.yml:
version: "3.8"
services:
ollama:
image: ollama/ollama
environment:
- HTTP_PROXY=http://user:[email protected]:8000
- HTTPS_PROXY=http://user:[email protected]:8000
- NO_PROXY=localhost,127.0.0.1
volumes:
- ollama:/root/.ollama
ports:
- "11434:11434"
volumes:
ollama:
Nach der Änderung der Variablen muss der Container neu erstellt werden (docker compose up -d --force-recreate),
ein einfacher Neustart reicht nicht aus, da die Umgebungsvariablen beim Erstellen des Containers festgelegt werden.
Proxy für den systemd-Dienst Ollama
Auf Linux-Servern wird Ollama häufig als systemd-Dienst über das offizielle Installationsskript installiert. In diesem Fall werden die Umgebungsvariablen
über die Override-Datei festgelegt, nicht über export im Terminal:
sudo systemctl edit ollama.service
Fügen Sie im geöffneten Editor Folgendes hinzu:
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"
Wenden Sie dann die Änderungen an:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
Der letzte Befehl zeigt, welche Variablen der Prozess tatsächlich sieht – eine praktische Möglichkeit, um sicherzustellen, dass die Konfiguration angewendet wurde, bevor Sie erneut versuchen, Pull auszuführen.
Analyse von Pull-Fehlern und deren Lösungen
Lassen Sie uns die häufigsten Fehlermeldungen beim Herunterladen von Modellen über einen Proxy und deren Lösungen betrachten.
dial tcp: lookup registry.ollama.ai: no such host
DNS-Resolution funktioniert nicht über den Proxy – normalerweise bedeutet dies, dass die Anfrage direkt versucht, den Proxy-Server zu umgehen, oder dass der Computer überhaupt keinen Zugang
zu DNS hat (geschlossenes Unternehmensnetzwerk). Lösung: Stellen Sie sicher, dass HTTPS_PROXY
tatsächlich vom Prozess erfasst wird (siehe den Befehl systemctl show oben),
und dass der Proxy-Server selbst in der Lage ist, externe Domains aufzulösen (SOCKS5-Proxys lösen DNS auf ihrer Seite auf, HTTP-Proxys ebenfalls, aber einige lokale Proxys tun dies nicht).
proxyconnect tcp: dial tcp: connection refused
Ollama versucht, sich mit dem Proxy zu verbinden, erhält jedoch eine Ablehnung. Überprüfen Sie den Port und den Host auf Tippfehler, stellen Sie sicher, dass der Proxy-Server tatsächlich auf dem angegebenen Port von außen hört (und nicht nur auf localhost), und dass die Firewall die ausgehende Verbindung zum Proxy-Port nicht blockiert.
407 Proxy Authentication Required
Der Proxy erfordert einen Benutzernamen und ein Passwort, die jedoch nicht übergeben oder falsch übergeben wurden. Stellen Sie sicher, dass der Benutzername und das Passwort in der Umgebungsvariablen im Format http://user:password@host:port eingebettet sind und dass spezielle Zeichen im Passwort
(z. B. @ oder :)
durch URL-Encoding kodiert sind (%40, %3A).
x509: certificate signed by unknown authority
Dies ist ein Zeichen für einen Unternehmensproxy mit TLS-Inspektion (MITM), der das SSL-Zertifikat durch sein eigenes Root-Zertifikat ersetzt. Der Go-Client von Ollama vertraut
diesem Zertifikat nicht. Die Lösung besteht darin, das Unternehmens-Root-Zertifikat in das Systemzertifikatsspeicher der vertrauenswürdigen Zertifizierungsstellen
hinzuzufügen (unter Linux normalerweise über update-ca-certificates nach dem Kopieren der .crt-Datei in
/usr/local/share/ca-certificates/). Es wird nicht empfohlen, die Zertifikatsprüfung global zu deaktivieren – dies öffnet den Weg für den Datenverkehrsübergriff.
context deadline exceeded / i/o timeout beim Herunterladen einer Schicht
Die Verbindung bricht während des Downloads einer großen Modellschicht ab (häufig handelt es sich um Dateien mit 4-40 GB). Ein solcher Fehler weist fast immer auf eine Instabilität oder eine niedrige Bandbreite des Proxy-Servers hin und nicht auf Ollama selbst. Kostenlose oder überlastete öffentliche Proxys brechen lange TCP-Sitzungen ab, insbesondere wenn der Download länger als einige Minuten dauert. In solchen Fällen hilft der Wechsel zu einem stabileren Kanal – beispielsweise Datacenter-Proxys, die hohe Geschwindigkeit und eine stabile Verbindung für den Download großer Dateien ohne Unterbrechungen bieten.
Welchen Proxytyp für Ollama wählen
Die Wahl des Proxytyps hängt von dem Grund ab, warum Sie überhaupt einen Proxy für Ollama benötigen. Wenn das Ziel darin besteht, einfach die Einschränkungen der Unternehmensfirewall innerhalb Ihres eigenen Netzwerks zu umgehen, ist nahezu jeder stabile HTTP(S)-Proxy geeignet. Wenn das Ziel jedoch darin besteht, die Geo-Blockierung des Modell-Registrys zu umgehen oder zu verbergen, dass die Anfrage aus einem Rechenzentrum stammt (einige CDNs drosseln die Geschwindigkeit für bekannte IP-Bereiche von Cloud-Anbietern), wird die Wahl des Proxytyps entscheidend.
| Proxytyp | Geschwindigkeit | Wann für Ollama verwenden |
|---|---|---|
| Datacenter | Hoch | Herunterladen großer Modellschichten (4-40+ GB) ohne Unterbrechungen, Tests aus verschiedenen Rechenzentrumsstandorten |
| Residential | Mittel | Umgehen von Geo-Einschränkungen des Registrys, wenn die IP des Rechenzentrums unter regionalen Rate-Limits fällt |
| Mobile | Variabel | Extremfall bei vollständiger Blockierung nach IP-Bereichen von Anbietern, weniger effektiv für große Downloads aufgrund von Geschwindigkeitschwankungen |
Für die meisten Szenarien mit Ollama – wenn Sie einfach ein Modell mit einem Gewicht von mehreren Gigabyte stabil herunterladen müssen – bleibt die optimale Wahl Datacenter-Proxys: Sie bieten maximale Bandbreite und minimale Latenz, was entscheidend ist, wenn große binäre Schichten heruntergeladen werden. Residential IPs sollten nur dann verwendet werden, wenn die Adressen von Datacentern tatsächlich unter den Einschränkungen des Modell-Registrys fallen.
Diagnose der Verbindung
Bevor Sie Zeit mit der Fehlersuche bei Ollama verbringen, überprüfen Sie den Proxy direkt über curl – dies schließt Verwirrung zwischen einem Problem in der Anwendung und einem Problem im Proxy-Server aus:
# Überprüfung der Erreichbarkeit des Registrys über den Proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Messung der Downloadgeschwindigkeit über den Proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Start von ollama serve mit detailliertem Log
OLLAMA_DEBUG=1 ollama serve
Wenn curl erfolgreich eine Antwort erhält, aber ollama pull trotzdem fehlschlägt –
liegt das Problem höchstwahrscheinlich daran, dass die Umgebungsvariablen nicht zum Serverprozess gelangt sind (der Dienst wurde mit einem anderen Benutzer, aus einer anderen Shell
oder als systemd-Einheit ohne Override gestartet). Kehren Sie zum Abschnitt über systemd zurück und überprüfen Sie die Ausgabe von systemctl show ollama --property Environment.
Wenn curl ebenfalls beim Herunterladen einer großen Datei abbricht oder eine instabile Geschwindigkeit anzeigt – liegt die Ursache beim Proxy-Server, und es ist ratsam, über einen stabileren Proxy-Anbieter nachzudenken, der auf die Übertragung großer Datenmengen ausgerichtet ist.
Fazit
Die Einrichtung von Ollama hinter einem Proxy reduziert sich auf drei Schlüsselpunkte: Die Umgebungsvariablen müssen genau für den Prozess
ollama serve festgelegt werden, nicht für das Terminal, von dem aus Sie pull aufrufen;
das Format der Proxy-URL muss korrekt kodierte Anmeldeinformationen enthalten; und bei Zertifikatfehlern muss das Unternehmens-Root-Zertifikat in den vertrauenswürdigen Speicher hinzugefügt werden, anstatt die TLS-Prüfung zu deaktivieren. Die meisten Pull-Fehler sind keine Bugs in Ollama selbst,
sondern die Folge davon, dass die Netzwerkeinstellungen nicht auf den richtigen Prozess angewendet wurden oder der Proxy-Server nicht in der Lage ist, große Dateien über längere Zeiträume zu übertragen.
Wenn Ihr Hauptziel darin besteht, Modelle mit einem Gewicht von mehreren Gigabyte stabil und schnell herunterzuladen, empfehlen wir, es mit Datacenter-Proxys zu versuchen – sie bieten die hohe Bandbreite, die für das Herunterladen großer Modellschichten erforderlich ist. Wenn der Grund für die Verwendung eines Proxys darin besteht, die Geo-Einschränkungen des Modell-Registrys zu umgehen, achten Sie auf Residential Proxys, die seltener unter regionalen Limits fallen, die auf IP-Bereiche von Cloud-Anbietern angewendet werden.