Proxy di rete per Gemini: configurare e diagnosticare la connessione del client

Instradi google-genai attraverso un proxy HTTP CONNECT, tenga TLS acceso e distingua un hop morto da un rifiuto dell'API, senza trattare un tunnel come accesso a Google.

Questa guida è per gli sviluppatori che hanno bisogno che google-genai 2.30.1 esca attraverso un proxy HTTP CONNECT. I controlli hanno usato un'origine loopback e un hop fittizio, non un account Google. Top Proxy non vende IP e qui non ci sono chiavi gratis. Un tunnel che funziona non è accesso all'API.

01Scelga un client Gemini e lo fissi#

Gemini è una famiglia di prodotti. L'app web consumer, la Gemini Developer API, Vertex AI o Gemini Enterprise Agent Platform e la Gemini CLI non condividono un interruttore proxy. Mescolarli è il modo in cui si fa debug di un browser mentre il processo Python continua a uscire senza proxy. Questa procedura resta su un client: l'SDK Python Google Gen AI che parla con la Gemini Developer API.

La documentazione dell'API Gemini, consultata il 15 ottobre 2026, ultimo aggiornamento 13 ottobre 2026 UTC, descrive quell'API come il percorso dal prompt alla produzione. Non documentano un proxy. Il cablaggio del proxy sta nel README dell'SDK. Regioni disponibili, ultimo aggiornamento 28 aprile 2026, è un elenco di paesi per AI Studio e l'API. Un proxy non aggiunge una regione mancante, un'età verificata o un account di fatturazione.

Fissi le versioni dei pacchetti che importa. Questa esecuzione ha usato Python 3.14.6, google-genai 2.30.1, httpx 0.28.1 e LibreSSL 3.3.6 come binario openssl per una CA di laboratorio. PyPI elencava 2.30.1 lo stesso giorno. Il client installato impostava di default la Gemini Developer API su https://generativelanguage.googleapis.com/ e v1beta. Vertex usa un costruttore diverso e un host diverso. Qui lo si lascia stare.

1. Creare un venv sul Python che eseguirà davvero. Questa macchina ha usato /opt/homebrew/bin/python3.14.
2. Installare google-genai==2.30.1. Non lasci che una wheel successiva le sostituisca lo stack HTTP.
3. Stampare le versioni prima di toccare un proxy. Tenga le righe google-genai e httpx.

Il README, sezione Proxy intorno al default httpx, dice che l'SDK usa httpx sia per i client sync sia per quelli async. google-genai[aiohttp] è un extra per un percorso async più veloce, con trust_env=True per allinearsi a httpx. Quell'extra non era installato in questa esecuzione. Non farò finta che aiohttp abbia instradato qualcosa. SOCKS5 è documentato solo dopo httpx[socks] e HttpOptions.client_args. Anche quello non testato qui. HTTP CONNECT è il percorso che si è mosso davvero.

Passi api_key in genai.Client oppure imposti GEMINI_API_KEY / GOOGLE_API_KEY prima dell'init. Configurazione della chiave API è lavoro da account. Il laboratorio ha usato la stringa fittizia lab-not-a-google-key contro un'origine loopback. Quella chiave non è mai uscita dalla macchina verso Google.

02Imposti HTTPSPROXY prima di costruire Client#

Il README è netto. Sia httpx sia aiohttp leggono urllib.request.getproxies dall'ambiente. Imposti il proxy prima di costruire il client:

export HTTPS_PROXY='http://USER:PASS@PROXY_HOST:PROXY_PORT'
export SSL_CERT_FILE='/path/to/extra-ca.pem'

SSL_CERT_FILE è facoltativo. Gemini di produzione sulle CA pubbliche non ha bisogno di un file CA privato. Il laboratorio ne aveva bisogno perché il certificato di origine era emesso in locale. La 2.30.1 installata fa un lavoro extra qui. _api_client.py costruisce un contesto SSL con ssl.create_default_context(cafile=os.environ.get('SSL_CERT_FILE', certifi.where())) perché, a detta degli autori dell'SDK, httpx non prende SSL_CERT_FILE da solo. Esporti la variabile prima di Client(...). Esportarla dopo non adatta un client già vivo.

Lo userinfo in HTTPS_PROXY è autenticazione del proxy. Non è la sua chiave API Gemini. Metta la chiave API in Client(api_key=...) o in GEMINI_API_KEY. Se registra l'URL del proxy in un log, oscuri la password. Un listing dei processi vede comunque l'ambiente per un attimo.

Lo stesso README mostra SOCKS5 attraverso gli argomenti httpx, non attraverso HTTPS_PROXY:

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options=types.HttpOptions(
        client_args={"proxy": "http://USER:PASS@PROXY_HOST:PROXY_PORT"},
        timeout=60000,
        retry_options=types.HttpRetryOptions(attempts=1),
    ),
)

HttpOptions.timeout è in millisecondi. 2.30.1 lo converte con / 1000.0 prima di httpx. retry_options=None su questa build significa che tenacity si ferma dopo un tentativo. Risoluzione dei problemi dice ancora che l'SDK Python ritenta gli errori transitori fino a quattro volte, con circa 1s poi 60s al massimo. Quella pagina è datata 13 ottobre 2026. Il client installato non lo fa a meno che lei non passi HttpRetryOptions. Preferisco impostare attempts=1 mentre diagnostico un hop piuttosto che guardare una porta morta prendere backoff esponenziale.

1. Esportare solo HTTPS_PROXY se il target è HTTPS, e Gemini lo è. Questa esecuzione non ha impostato HTTP_PROXY. urllib.request.getproxies() ha allora restituito {'https': 'http://127.0.0.1:62748'}.
2. Tenere NO_PROXY vuoto quando intende che il proxy veda il loopback. Un NO_PROXY=localhost rimasto salta l'hop e sembra un successo.
3. Costruire genai.Client dopo che l'ambiente è impostato. Chiuderlo quando ha finito.

client_args={'proxy': ...} esplicito è l'altra porta documentata. Anche quella ha inviato CONNECT in questa esecuzione. La usi quando una shell possiede già HTTPS_PROXY e non vuole combatterci.

03Provi il percorso su un target che controlla lei#

Lo stato 200 è un testimone scarso. Chiamate dirette e con proxy possono entrambe restituire 200. Serve un log dell'hop o un timbro di origine. Il laboratorio ha puntato HttpOptions.base_url su https://127.0.0.1:PORT/ così google-genai non ha mai aperto generativelanguage.googleapis.com. L'origine ha risposto con JSON etichettato SIMULATED. È una prova di instradamento. Non è una risposta del modello, un controllo di quota o un via libera di regione.

Il suo controllo può essere più piccolo di un laboratorio pubblico. Servono il client installato, un proxy suo e un target suo. Il loopback basta. Non spenga verify. Non punti questo su Google finché l'hop non è noioso.

import os
from google import genai
from google.genai import types

os.environ["HTTPS_PROXY"] = "http://USER:PASS@PROXY_HOST:PROXY_PORT"

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options=types.HttpOptions(
        timeout=60000,
        retry_options=types.HttpRetryOptions(attempts=1),
    ),
)
try:
    response = client.models.generate_content(
        model="gemini-flash-latest",
        contents="ping",
    )
    print(response.text)
finally:
    client.close()

Quel frammento parla con Google se lascia base_url non impostato. Il controllo loopback no. Le porte nei risultati salvati sono morte. Copi host e porta da un proxy che è ancora su.

1. Chiamare una volta senza ambiente proxy e senza proxy in client_args. Il diretto ha restituito testo simulato. Il proxy CONNECT fittizio è rimasto inattivo. proxy_events=0.
2. Esportare HTTPS_PROXY su http://127.0.0.1:PROXY_PORT e chiamare di nuovo. Il proxy ha registrato CONNECT 127.0.0.1:ORIGIN_PORT. L'origine ha restituito lo stesso testo SIMULATED. getproxies ha mostrato solo la chiave https.
3. Ripetere con client_args={'proxy': 'http://127.0.0.1:PROXY_PORT'} e senza HTTPS_PROXY. CONNECT è successo di nuovo. Due porte, un tipo di tunnel.

Una pagina browser Il mio IP mostra l'uscita del browser. Non mostra questo processo Python. Il controllo proxy le dice se un host risponde HTTP o SOCKS5. Utile prima di incollare un endpoint. Non è comunque google-genai.

04Tenga TLS acceso e le credenziali fuori dai log#

HTTPS attraverso un proxy HTTP è CONNECT, poi TLS verso l'origine attraverso quel tunnel. L'URL del proxy resta http://.... Un URL proxy https:// significherebbe TLS verso il proxy stesso. Questa esecuzione non l'ha misurato.

La CA di laboratorio era un certificato di un giorno con un subject alternative name per 127.0.0.1. SSL_CERT_FILE puntava a quella CA. La verifica è restata accesa. Quando lo stesso client con proxy è partito senza SSL_CERT_FILE, CONNECT è comunque riuscito e httpx ha sollevato ConnectError che avvolgeva CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate. L'hop andava bene. L'archivio di fiducia no. È il caso che la gente salta, poi aggiunge verify=False e lo chiama fatto.

1. Tenere il percorso di verify di default. Passare un file CA solo quando l'origine è privata.
2. Confermare CONNECT nel log del proxy prima di festeggiare un traceback TLS. Il traceback non prova che il proxy sia stato saltato.
3. Oscurare Proxy-Authorization, x-goog-api-key e lo userinfo del proxy. Il proxy di laboratorio ha registrato has_proxy_authorization: false perché l'hop fittizio non aveva Basic auth. L'hop del suo fornitore probabilmente sì.

Non copi la CA di laboratorio nell'archivio di fiducia di sistema. Questa esecuzione non ha mai toccato il trust di macOS. SSL_CERT_FILE nel processo figlio è bastato.

05Distinguere un hop morto da un errore che sembra Google#

Risoluzione dei problemi separa i problemi dell'SDK client da quelli del backend. Ritenti 429 e 503. Non ritenti 400, 402 o 403. Quelli sono chiavi non valide, crediti prepagati vuoti o sintassi sbagliata, non un socket instabile. Niente di tutto questo scatta se TCP non completa.

Questa esecuzione ha forzato tre fallimenti sullo stesso client installato.

Una porta loopback chiusa come proxy client_args ha sollevato ConnectError: [Errno 61] Connection refused in 0,001s. Nessun log CONNECT. L'origine non ha mai visto una richiesta. Quello è un hop morto.

Un 403 di origine simulata attraverso un hop CONNECT vivo ha sollevato ClientError: 403 PERMISSION_DENIED con testo del body che diceva SIMULATED. CONNECT era registrato. L'origine ha contato un colpo. Il trasporto ha funzionato. L'applicazione ha rifiutato. Su Google reale quella classe di errore è account, fatturazione o policy. Non è «compri un proxy diverso e il modello compare».

Un HttpOptions.timeout di 200ms contro uno sleep di origine di 1,5s ha sollevato ReadTimeout: The read operation timed out a 0,205s. CONNECT era registrato. Il tunnel era su. Il budget no.

Le pagine catalogo mobile e datacenter non la salvano da quella tabella. Proxy mobili e proxy datacenter cambiano l'IP che presenta. Non riscrivono le classi di errore di google-genai. HTTP è il protocollo che questo SDK ha usato davvero. SOCKS5 resta un extra del README finché non installa httpx[socks] e lo misura.

06Allineare HTTP CONNECT a un endpoint di catalogo che può aprire#

Scelga un hop che il venditore documenta come HTTP, con nome utente e password che il venditore documenta. Poi provi google-genai contro un fixture suo. I gateway a pagamento non sono stati chiamati.

I proxy residenziali Oxylabs, consultati il 15 ottobre 2026, documentano un ingresso HTTP. Il quick start residenziale Decodo, lo stesso giorno, documenta gate.decodo.com:7000 come URL di proxy HTTP. Il catalogo inglese elenca ancora quel prodotto come smartproxy-com. Confronti quelle forme sulle schede vive di Oxylabs e Smartproxy / Decodo. È aderenza al catalogo, non un test di pool.

1. Allineare lo schema a ciò che 2.30.1 ha inviato davvero: HTTP CONNECT. Un URL HTTPS-proxy-verso-il-proxy è un prodotto diverso.
2. Mettere i prefissi del venditore sull'utente del proxy, non su GEMINI_API_KEY.
3. Controllare la raggiungibilità con il controllo proxy se le serve solo HTTP contro SOCKS su un host. Provare l'SDK sul suo processo.

Oxylabs — proxy residenziali e datacenter4.0771

Oxylabs vende proxy residenziali, mobile, ISP e datacenter sotto un unico abbonamento mensile da $30. Pagamenti: carte, bonifico, AliPay, PayPal.

10 paesi

0,45 USD

per 1 GB

Decodo (Smartproxy) — proxy residenziali e datacenter4.22118

Decodo (ex Smartproxy) vende proxy residenziali e datacenter. Residenziali: $4/GB senza piano mensile, o pacchetti mensili da $3.75/GB per 3 GB. Pagamenti: carte, PayPal, Alipay, Google/Apple Pay, crypto (con limiti).

83 paesi

0,38 USD

per 1 GB

Faccia uscire questo client da un hop che può nominare, tenga TLS acceso e smetta di trattare un tunnel come un diritto.