Proxy réseau Gemini : configurer et diagnostiquer une connexion client

Faites passer google-genai par un proxy HTTP CONNECT, laissez le TLS activé, et distinguez un relais mort d'un refus d'API, sans traiter un tunnel comme un accès Google.

Ce guide s'adresse aux développeurs qui ont besoin que google-genai 2.30.1 sorte par un proxy HTTP CONNECT. Les contrôles ont utilisé une origine en loopback et un relais factice, pas un compte Google. Top Proxy ne vend pas d'IP, et il n'y a pas de clés gratuites ici. Un tunnel qui marche n'est pas un accès API.

01Choisissez un client Gemini et figez sa version#

Gemini est une famille de produits. L'application web grand public, l'API Gemini Developer, Vertex AI ou Gemini Enterprise Agent Platform, et le Gemini CLI ne partagent pas le même réglage de proxy. Les mélanger, c'est déboguer un navigateur pendant que votre processus Python part encore en direct. Ce parcours reste sur un seul client : le SDK Python Google Gen AI qui parle à l'API Gemini Developer.

La documentation de l'API Gemini, consultée le 15 octobre 2026, dernière mise à jour le 13 octobre 2026 UTC, décrit cette API comme le chemin de l'invite à la production. Elle ne documente pas de proxy. Le câblage proxy vit dans le README du SDK. Régions disponibles, dernière mise à jour le 28 avril 2026, est une liste de pays pour AI Studio et l'API. Un proxy n'ajoute pas une région manquante, un âge vérifié, ni un compte de facturation.

Figez les versions que vous importez. Cette exécution a utilisé Python 3.14.6, google-genai 2.30.1, httpx 0.28.1, et LibreSSL 3.3.6 comme binaire openssl pour une CA de laboratoire. PyPI listait 2.30.1 le même jour. Le client installé prenait par défaut l'API Gemini Developer sur https://generativelanguage.googleapis.com/ et v1beta. Vertex utilise un autre constructeur et un autre hôte. Laissez-le de côté ici.

1. Créez un venv sur le Python que vous lancerez vraiment. Cette machine a utilisé /opt/homebrew/bin/python3.14.
2. Installez google-genai==2.30.1. Ne laissez pas une roue plus récente réécrire la pile HTTP sous vous.
3. Affichez les versions avant de toucher un proxy. Gardez les lignes google-genai et httpx.

Le README, section Proxy autour du défaut httpx, dit que le SDK utilise httpx pour les clients sync et async. google-genai[aiohttp] est un extra pour un chemin async plus rapide, avec trust_env=True pour coller à httpx. Cet extra n'était pas installé dans cette exécution. Je ne vais pas prétendre qu'aiohttp a routé quoi que ce soit. SOCKS5 n'est documenté qu'après httpx[socks] et HttpOptions.client_args. Également non testé ici. HTTP CONNECT est le chemin qui a réellement bougé.

Passez api_key à genai.Client ou définissez GEMINI_API_KEY / GOOGLE_API_KEY avant l'init. La configuration de clé API est du travail de compte. Le laboratoire a utilisé la chaîne factice lab-not-a-google-key contre une origine en loopback. Cette clé n'a jamais quitté la machine vers Google.

02Définissez HTTPSPROXY avant de construire Client#

Le README est net. httpx comme aiohttp lisent urllib.request.getproxies dans l'environnement. Définissez le proxy avant de construire le client :

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

SSL_CERT_FILE est facultatif. Gemini en production sur des CA publiques n'a pas besoin d'un fichier de CA privée. Le laboratoire en avait besoin parce que le certificat d'origine avait été émis localement. La 2.30.1 installée fait un travail supplémentaire ici. _api_client.py construit un contexte SSL avec ssl.create_default_context(cafile=os.environ.get('SSL_CERT_FILE', certifi.where())) parce que, selon les auteurs du SDK, httpx ne lit pas SSL_CERT_FILE tout seul. Exportez la variable avant Client(...). L'exporter plus tard ne rétrofittera pas un client déjà vivant.

Le userinfo dans HTTPS_PROXY est l'authentification du proxy. Ce n'est pas votre clé API Gemini. Mettez la clé API dans Client(api_key=...) ou dans GEMINI_API_KEY. Si vous jetez l'URL du proxy dans un journal, masquez le mot de passe. Les listes de processus voient encore l'environnement un instant.

Le même README montre SOCKS5 via les arguments httpx, pas via 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 est en millisecondes. 2.30.1 le convertit avec / 1000.0 avant httpx. retry_options=None sur cette compilation veut dire que tenacity s'arrête après une tentative. Le dépannage dit encore que le SDK Python retente les erreurs transitoires jusqu'à quatre fois, avec environ 1 s puis 60 s au maximum. Cette page est datée du 13 octobre 2026. Le client installé ne le fait pas tant que vous ne passez pas HttpRetryOptions. Je préfère fixer attempts=1 pendant que je diagnostique un relais plutôt que de regarder un port mort prendre un backoff exponentiel.

1. Exportez seulement HTTPS_PROXY si la cible est HTTPS, ce que Gemini est. Cette exécution n'a pas défini HTTP_PROXY. urllib.request.getproxies() a alors renvoyé {'https': 'http://127.0.0.1:62748'}.
2. Gardez NO_PROXY vide quand vous voulez que le proxy voie le loopback. Un NO_PROXY=localhost oublié sautera le relais et ressemblera à un succès.
3. Construisez genai.Client après que l'environnement est défini. Fermez-le quand vous avez fini.

client_args={'proxy': ...} explicite est l'autre porte documentée. Elle a aussi envoyé CONNECT dans cette exécution. Utilisez-la quand un shell possède déjà HTTPS_PROXY et que vous ne voulez pas vous battre contre.

03Prouvez la route sur une cible que vous contrôlez#

Le statut 200 est un mauvais témoin. Les appels directs et proxifiés peuvent tous deux renvoyer 200. Il vous faut un journal de relais ou un tampon d'origine. Le laboratoire a pointé HttpOptions.base_url vers https://127.0.0.1:PORT/ pour que google-genai n'ouvre jamais generativelanguage.googleapis.com. L'origine a répondu avec du JSON étiqueté SIMULATED. C'est une preuve de routage. Ce n'est pas une réponse de modèle, un contrôle de quota, ni un passage de région.

Votre propre contrôle peut être plus petit qu'un laboratoire public. Il vous faut le client installé, un proxy que vous possédez, et une cible que vous possédez. Le loopback suffit. N'éteignez pas verify. Ne pointez pas cela vers Google tant que le relais n'est pas ennuyeux.

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()

Ce fragment parle à Google si vous laissez base_url non défini. Le contrôle en loopback ne l'a pas fait. Les ports des résultats enregistrés sont morts. Copiez hôte et port depuis un proxy encore debout.

1. Appelez une fois sans environnement de proxy et sans proxy client_args. Le direct a renvoyé du texte simulé. Le proxy CONNECT factice est resté inactif. proxy_events=0.
2. Exportez HTTPS_PROXY vers http://127.0.0.1:PROXY_PORT et rappelez. Le proxy a journalisé CONNECT 127.0.0.1:ORIGIN_PORT. L'origine a renvoyé le même texte SIMULATED. getproxies n'a montré que la clé https.
3. Répétez avec client_args={'proxy': 'http://127.0.0.1:PROXY_PORT'} et sans HTTPS_PROXY. CONNECT s'est produit à nouveau. Deux portes, un type de tunnel.

Une page navigateur Quelle est mon IP montre la sortie du navigateur. Elle ne montre pas ce processus Python. Le vérificateur de proxies dit si un hôte répond en HTTP ou SOCKS5. Utile avant de coller un point d'accès. Toujours pas google-genai.

04Laissez le TLS activé et les identifiants hors des journaux#

Le HTTPS à travers un proxy HTTP, c'est CONNECT, puis TLS vers l'origine à travers ce tunnel. L'URL du proxy reste http://.... Une URL de proxy https:// voudrait dire TLS vers le proxy lui-même. Cette exécution n'a pas mesuré cela.

La CA de laboratoire était un certificat d'un jour avec un subject alternative name pour 127.0.0.1. SSL_CERT_FILE pointait vers cette CA. La vérification est restée activée. Quand le même client proxifié a tourné sans SSL_CERT_FILE, CONNECT a quand même réussi et httpx a levé ConnectError en enveloppant CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate. Le relais allait bien. Le magasin de confiance, non. C'est le cas que les gens sautent, puis ils ajoutent verify=False et appellent ça terminé.

1. Gardez le chemin de vérification par défaut. Passez un fichier de CA seulement quand votre origine est privée.
2. Confirmez CONNECT dans le journal du proxy avant de célébrer une trace TLS. La trace n'est pas la preuve que le proxy a été contourné.
3. Masquez Proxy-Authorization, x-goog-api-key, et le userinfo du proxy. Le proxy de laboratoire a enregistré has_proxy_authorization: false parce que le relais factice n'avait pas d'authentification Basic. Celui de votre fournisseur en a probablement.

Ne copiez pas la CA de laboratoire dans le magasin de confiance système. Cette exécution n'a jamais touché la confiance macOS. SSL_CERT_FILE dans le processus enfant a suffi.

05Distinguez un relais mort d'une erreur qui ressemble à Google#

Le dépannage sépare les problèmes de SDK client des problèmes de backend. Retentez 429 et 503. Ne retentez pas 400, 402 ou 403. Ce sont des clés invalides, des crédits prépayés vides, ou une mauvaise syntaxe, pas une socket capricieuse. Rien de cela ne se déclenche si TCP ne se termine jamais.

Cette exécution a forcé trois échecs sur le même client installé.

Un port loopback fermé comme proxy client_args a levé ConnectError : [Errno 61] Connection refused en 0.001s. Pas de journal CONNECT. L'origine n'a jamais vu de requête. C'est un relais mort.

Une origine simulée 403 à travers un relais CONNECT vivant a levé ClientError : 403 PERMISSION_DENIED avec un corps qui disait SIMULATED. CONNECT a été journalisé. L'origine a compté un hit. Le transport a marché. L'application a refusé. Sur le vrai Google, cette classe d'erreur est du compte, de la facturation ou de la politique. Ce n'est pas « achetez un autre proxy et le modèle apparaît ».

Un HttpOptions.timeout de 200ms contre un sommeil d'origine de 1.5s a levé ReadTimeout : The read operation timed out à 0.205s. CONNECT a été journalisé. Le tunnel était debout. Le budget, non.

Les pages catalogue mobile et datacenter ne vous sauveront pas de ce tableau. Les proxies mobiles et les proxies datacenter changent l'IP que vous présentez. Ils ne réécrivent pas les classes d'erreur de google-genai. HTTP est le protocole que ce SDK a réellement utilisé. SOCKS5 reste un extra du README tant que vous n'installez pas httpx[socks] et ne le mesurez pas.

06Faites correspondre HTTP CONNECT à un point d'accès catalogue que vous pouvez ouvrir#

Choisissez un relais que le vendeur documente comme HTTP, avec identifiant et mot de passe que le vendeur documente. Puis prouvez google-genai contre une fixture que vous possédez. Les passerelles payantes n'ont pas été appelées.

Les proxies résidentiels Oxylabs, consultés le 15 octobre 2026, documentent une entrée HTTP. Le démarrage rapide résidentiel Decodo, le même jour, documente gate.decodo.com:7000 comme URL de proxy HTTP. Le catalogue anglais liste encore ce produit comme smartproxy-com. Comparez ces formes sur les cartes en direct d'Oxylabs et Smartproxy / Decodo. C'est un ajustement de catalogue, pas un test de pool.

1. Faites correspondre le schéma à ce que 2.30.1 a réellement envoyé : HTTP CONNECT. Une URL HTTPS-proxy-vers-le-proxy est un autre produit.
2. Mettez les préfixes du vendeur sur l'utilisateur du proxy, pas sur GEMINI_API_KEY.
3. Vérifiez l'accessibilité avec le vérificateur de proxies si vous n'avez besoin que de HTTP versus SOCKS sur un hôte. Prouvez le SDK sur votre processus.

Oxylabs — proxies résidentiels et datacenter4.0771

Oxylabs vend des proxies résidentiels, mobiles, ISP et datacenter sous un seul abonnement mensuel dès $30. Paiements acheteur : cartes, virement, AliPay, PayPal.

10 pays

0,45 $US

par 1 GB

Decodo (Smartproxy) — proxies résidentiels et datacenter4.22118

Decodo (anciennement Smartproxy) vend des proxies résidentiels et datacenter. Résidentiel : $4/GB sans forfait mensuel, ou packs mensuels dès $3.75/GB pour 3 GB. Paiements : cartes, PayPal, Alipay, Google/Apple Pay, crypto (avec limites).

83 pays

0,38 $US

par 1 GB

Faites sortir ce client par un relais que vous pouvez nommer, laissez le TLS activé, et cessez de traiter un tunnel comme un droit.