Se stai cercando di scaricare un modello tramite ollama pull
da una rete aziendale, tramite VPN o attraverso un proxy esterno, è probabile che tu abbia già incontrato errori del tipo
dial tcp: lookup registry.ollama.ai o
context deadline exceeded.
Ollama per impostazione predefinita non sempre acquisisce correttamente le impostazioni di sistema del proxy, e le grandi dimensioni dei modelli (da 2 a 70+ GB) aggravano il problema —
la connessione si interrompe a metà del download. In questo articolo vedremo come impostare correttamente le variabili di ambiente, configurare il proxy in Docker e systemd,
e analizzeremo gli errori di pull più comuni e i modi per risolverli.
Come Ollama lavora con la rete e il proxy
Ollama è un'applicazione client-server: il server locale (ollama serve)
riceve comandi dalla CLI ed esegue richieste di rete al registro dei modelli registry.ollama.ai e al CDN, dove sono memorizzati i layer dei modelli.
Il comando ollama pull llama3 esegue in realtà una serie di richieste HTTPS,
simili a Docker pull: prima viene richiesto il manifesto del modello, poi i layer binari (file GGUF dei pesi) vengono scaricati sequenzialmente o in parallelo.
Un aspetto importante: le richieste di rete sono eseguite dal processo server di Ollama, non dal comando CLI. Questo significa che le variabili di ambiente
con le impostazioni del proxy devono essere impostate dove è in esecuzione il processo ollama serve,
e non nel terminale da cui chiami ollama pull.
Se il servizio è avviato come unità systemd o in un contenitore Docker, l'esportazione della variabile in una normale sessione bash non avrà alcun effetto —
questa è la causa più comune per cui "il proxy sembra configurato, ma il pull non funziona comunque".
Variabili di ambiente HTTP_PROXY, HTTPS_PROXY, NO_PROXY
Ollama è scritto in Go, e la libreria HTTP standard di Go legge le impostazioni del proxy dalle classiche variabili di ambiente:
HTTP_PROXY— proxy per le normali richieste HTTPHTTPS_PROXY— proxy per le richieste HTTPS (è necessario per il download dei modelli, poiché il registro funziona tramite TLS)NO_PROXY— elenco di host da escludere dalla proxy (ad esempio, API locale di Ollama su 127.0.0.1:11434)
Il formato del valore: http://user:password@host:port per proxy con autorizzazione
oppure socks5://host:port per SOCKS5. Go supporta entrambe le opzioni,
ma per SOCKS5 è importante che il binario di Ollama sia stato compilato con supporto per questo proxy — nella maggior parte delle versioni attuali è così, ma in caso di errori è meglio
testare prima con proxy HTTP/HTTPS, per escludere questa variabile.
Importante: specifica le variabili sia in minuscolo che in maiuscolo
(http_proxy e HTTP_PROXY).
Alcune distribuzioni Linux leggono solo in minuscolo, mentre le applicazioni Go a volte si aspettano in maiuscolo — è meglio specificare entrambe le varianti, per non avere dubbi.
Configurazione su Linux e macOS
Se esegui Ollama direttamente dal terminale (non come servizio di sistema), è sufficiente esportare le variabili prima di avviare il server:
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
Per mantenere le impostazioni tra le sessioni, aggiungi queste righe a ~/.bashrc,
~/.zshrc o ~/.profile
a seconda della shell utilizzata. Dopo aver modificato, esegui source ~/.bashrc
e riavvia il processo Ollama — le variabili di ambiente vengono lette solo all'avvio del processo, non è previsto il riavvio a caldo.
Su macOS, se Ollama è installato come applicazione (e non tramite Homebrew), le variabili di ambiente dal terminale potrebbero non arrivare al processo
avviato tramite GUI. In questo caso, è più sicuro impostare le variabili tramite launchctl setenv:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Dopo di che riavvia completamente l'applicazione Ollama (esci dall'area di notifica, non chiudere semplicemente la finestra)
Configurazione su Windows
In PowerShell, le variabili vengono impostate per la sessione corrente con il comando:
$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
Se Ollama è avviato come servizio in background (icona nell'area di notifica), le variabili di sessione non sono sufficienti — il servizio si avvia all'accesso al sistema
prima che tu apra PowerShell. Devi impostare le variabili a livello utente o di sistema tramite
"Impostazioni → Sistema → Informazioni → Impostazioni avanzate di sistema → Variabili d'ambiente", dopo di che chiudi completamente il processo
ollama.exe tramite il task manager e riavvia l'applicazione.
Proxy per Ollama in Docker
Se Ollama è avviato in un contenitore (un caso comune per le distribuzioni server), le variabili di ambiente dell'host non vengono automaticamente trasferite all'interno del contenitore —
devono essere passate esplicitamente tramite -e o la sezione environment
in docker-compose:
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
Analogamente 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:
Dopo aver modificato le variabili, è necessario ricreare il contenitore (docker compose up -d --force-recreate),
un semplice riavvio non è sufficiente, poiché le variabili di ambiente vengono fissate al momento della creazione del contenitore.
Proxy per il servizio systemd di Ollama
Nei server Linux, Ollama è spesso installato come servizio systemd tramite lo script di installazione ufficiale. In questo caso, le variabili di ambiente
vengono impostate tramite un file di override, e non tramite export nel terminale:
sudo systemctl edit ollama.service
Nell'editor che si apre, aggiungi:
[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"
Poi applica le modifiche:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
L'ultimo comando mostrerà quali variabili il processo vede realmente — un modo utile per assicurarsi che la configurazione sia stata applicata, prima di provare di nuovo a eseguire il pull.
Analisi degli errori di pull e loro risoluzione
Analizziamo i messaggi di errore più comuni durante il download dei modelli tramite proxy e cosa fare con essi.
dial tcp: lookup registry.ollama.ai: no such host
La risoluzione DNS non funziona dietro il proxy — di solito significa che la richiesta sta cercando di andare direttamente, bypassando il server proxy, oppure che la macchina non ha accesso
a DNS (rete aziendale chiusa). Soluzione: assicurati che HTTPS_PROXY
sia effettivamente acquisito dal processo (vedi il comando systemctl show sopra),
e che il server proxy stesso sia in grado di risolvere i domini esterni (i proxy SOCKS5 risolvono DNS dalla loro parte, i proxy HTTP anche, ma alcuni proxy locali non lo fanno).
proxyconnect tcp: dial tcp: connection refused
Ollama sta cercando di connettersi al proxy, ma riceve un rifiuto. Controlla la porta e l'host per errori di battitura, assicurati che il server proxy stia effettivamente ascoltando la porta specificata dall'esterno (e non solo su localhost), e che il firewall non blocchi la connessione in uscita alla porta del proxy.
407 Proxy Authentication Required
Il proxy richiede nome utente e password, ma non sono stati forniti o sono stati forniti in modo errato. Assicurati che nella variabile di ambiente il nome utente e la password siano incorporati nell'URL
nel formato http://user:password@host:port, e che i caratteri speciali nella password
(ad esempio, @ o :)
siano codificati tramite URL-encoding (%40, %3A).
x509: certificate signed by unknown authority
Questo è un segno di un proxy aziendale con ispezione TLS (MITM), che sostituisce il certificato SSL con il proprio root. Il client Go di Ollama non si fida
di questo certificato. La soluzione è aggiungere il certificato root aziendale nel deposito di certificati di fiducia del sistema
(su Linux di solito tramite update-ca-certificates dopo aver copiato il file .crt in
/usr/local/share/ca-certificates/). Disabilitare la verifica dei certificati globalmente non è consigliato — questo apre la strada all'intercettazione del traffico.
context deadline exceeded / i/o timeout durante il download di un layer
La connessione si interrompe a metà del download di un grande layer del modello (spesso si tratta di file da 4 a 40 GB). Questo errore indica quasi sempre instabilità o bassa larghezza di banda del server proxy, e non di Ollama stessa. I proxy pubblici gratuiti o sovraccarichi interrompono lunghe sessioni TCP, soprattutto se il download richiede più di qualche minuto. In questi casi, è utile passare a un canale più stabile — ad esempio, proxy di data center, che offrono alta velocità e connessione stabile per scaricare grandi file senza interruzioni.
Quale tipo di proxy scegliere per Ollama
La scelta del tipo di proxy dipende dalla ragione per cui hai bisogno di un proxy per Ollama. Se l'obiettivo è semplicemente aggirare le restrizioni del firewall aziendale all'interno della propria rete, va bene praticamente qualsiasi proxy HTTP(S) stabile. Ma se l'obiettivo è aggirare il geo-blocco del registro dei modelli o nascondere che la richiesta proviene da un data center (alcuni CDN limitano la velocità per intervalli IP noti dei fornitori di cloud), la scelta del tipo di proxy diventa critica.
| Tipo di proxy | Velocità | Quando usarlo per Ollama |
|---|---|---|
| Data center | Alta | Scaricamento di grandi layer di modelli (4-40+ GB) senza interruzioni, test da diverse località di DC |
| Residenziali | Media | Aggirare le restrizioni geo del registro, quando l'IP del data center è soggetto a limitazione regionale |
| Mobili | Variabile | Ultima risorsa in caso di blocco completo per intervalli IP dei fornitori, meno efficace per grandi download a causa delle fluttuazioni di velocità |
Per la maggior parte degli scenari con Ollama — quando è necessario semplicemente scaricare stabilmente un modello di decine di gigabyte — la scelta ottimale rimane proxy di data center: offrono la massima larghezza di banda e latenze minime, che sono critiche durante il download di grandi layer binari. Gli IP residenziali dovrebbero essere utilizzati solo se gli indirizzi dei data center sono effettivamente soggetti a restrizioni da parte del registro dei modelli.
Diagnostica della connessione
Prima di perdere tempo a debug di Ollama stessa, controlla il proxy direttamente tramite curl — questo escluderà confusione tra un problema nell'applicazione e un problema nel server proxy stesso:
# Verifica della disponibilità del registro tramite proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Misura della velocità di download tramite proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Avvio di ollama serve con log dettagliati
OLLAMA_DEBUG=1 ollama serve
Se curl riceve una risposta con successo, ma ollama pull continua a fallire —
il problema è quasi sicuramente che le variabili di ambiente non sono arrivate al processo del server (il servizio è avviato con un altro utente, da un'altra shell
o come unità systemd senza override). Torna alla sezione su systemd e controlla l'output di systemctl show ollama --property Environment.
Se curl si interrompe anche durante il download di un grande file o mostra una velocità instabile — la causa è lato server proxy, e dovresti considerare di cambiare fornitore di proxy con un'opzione più stabile, orientata alla trasmissione di grandi volumi di dati.
Conclusione
La configurazione di Ollama dietro un proxy si riduce a tre punti chiave: le variabili di ambiente devono essere impostate precisamente per il processo
ollama serve, e non per il terminale da cui chiami il pull;
il formato dell'URL del proxy deve includere correttamente codificati nome utente e password; e in caso di errori di certificato, è necessario aggiungere il certificato root aziendale nel deposito di fiducia, e non disabilitare la verifica TLS. La maggior parte degli errori di pull non sono bug di Ollama stessa,
ma conseguenze del fatto che le impostazioni di rete non sono state applicate al processo giusto o che il server proxy non regge un lungo trasferimento di grandi file.
Se il tuo obiettivo principale è scaricare modelli di decine di gigabyte in modo stabile e veloce senza interruzioni di connessione, ti consigliamo di provare proxy di data center — offrono alta larghezza di banda, necessaria per il caricamento di grandi layer di modelli. E se il motivo per utilizzare un proxy è aggirare le restrizioni geo del registro dei modelli, presta attenzione ai proxy residenziali, che raramente sono soggetti a limiti regionali applicati agli intervalli IP dei fornitori di cloud.