Appeler Gemini depuis du code
En Python, Gemini s'appelle avec le SDK google-genai (pip install google-genai), le même pour la Gemini Developer API et pour Gemini Enterprise Agent Platform. Les modules vertexai.generative_models déconseillé de google-cloud-aiplatform sont dépréciés : tout code neuf part de google-genai. Les exemples ci-dessous suivent la version 2.25 du SDK (septembre 2026) ; le choix du modèle est traité dans Choisir un modèle génératif.
Le client
from google import genai
from google.genai import types
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
enterprise=Trueenvoie les requêtes vers Agent Platform (aiplatform.googleapis.com) au lieu de la Developer API. Le SDK accepte aussivertexai=True, la forme qu'emploie une bonne partie de la documentation.- Sans argument,
genai.Client()lit les variablesGOOGLE_GENAI_USE_ENTERPRISE=true(ouGOOGLE_GENAI_USE_VERTEXAI=true),GOOGLE_CLOUD_PROJECTetGOOGLE_CLOUD_LOCATION. C'est la forme à préférer dans un conteneur : la configuration vient de l'environnement. locationvautglobal, une multirégion (us,eu) ou une région (europe-west3). Le SDK choisit l'hôte correspondant ; ce choix fixe la résidence du traitement.- Authentification : le client utilise les Application Default Credentials (ADC) du poste ou du compte de service attaché (voir Authentifier un appel à une API). Le principal a besoin de
roles/aiplatform.user. Une clé API est acceptée pour un essai, pas pour la production. - Le SDK appelle l'API
v1beta1par défaut, pour exposer les fonctions en preview ;http_options=types.HttpOptions(api_version="v1")le cantonne à l'API stable.
Fonctionnalités et paramètres
| Besoin | Paramètre ou méthode du SDK | Remarque |
|---|---|---|
| Génération simple | client.models.generate_content(model=, contents=, config=) |
response.text, response.usage_metadata |
| Réponse en flux | client.models.generate_content_stream(...) |
Réduit le délai avant le premier jeton, pas le coût |
| Instructions système | GenerateContentConfig(system_instruction=...) |
Rôle, ton, règles ; hors du fil de conversation |
| Conversation | client.chats.create(model=...), puis chat.send_message(...) |
L'historique est renvoyé à chaque tour, donc refacturé |
| Réflexion | thinking_config=types.ThinkingConfig(thinking_level="LOW") |
Gemini 3 : MINIMAL, LOW, MEDIUM, HIGH selon le modèle ; jetons de réflexion facturés en sortie |
| Sortie structurée | response_mime_type="application/json" avec response_schema= (classe Pydantic) ou response_json_schema= (JSON Schema) |
response.parsed rend l'objet validé ; ne pas répéter le schéma dans le prompt |
| Appel de fonctions | tools=[types.Tool(function_declarations=[...])], tool_config= |
response.function_calls ; exécution par l'application |
| Fichier Cloud Storage | types.Part.from_uri(file_uri="gs://...", mime_type=...) |
Jusqu'à 30 Mo par image et 50 Mo par PDF depuis Cloud Storage, 7 Mo en ligne |
| Ancrage Google Search | tools=[types.Tool(google_search=types.GoogleSearch())] |
Sources dans candidates[0].grounding_metadata |
| Cache de contexte | client.caches.create(...), puis cached_content=cache.name |
Implicite et automatique ; explicite pour garantir la remise |
| Inférence par lots | client.batches.create(model=, src="bq://..." ou "gs://...") |
−50 %, résultat sous 24 h en général |
| Compter les jetons | client.models.count_tokens(...), compute_tokens(...) |
Avant l'envoi, pour tenir une limite ou estimer un coût |
| Filtres de contenu | safety_settings=[types.SafetySetting(...)] |
Voir Évaluer et sécuriser |
| Model Armor | model_armor_config=types.ModelArmorConfig(...) |
Exclusif avec safety_settings |
| Étiquettes de coût | labels={"app": "support"} |
Ventilation dans l'export de facturation |
| Nouvelles tentatives | HttpOptions(retry_options=types.HttpRetryOptions(...), timeout=...) |
Sur le client ou par requête |
| Embeddings | client.models.embed_content(model="gemini-embedding-2", contents=...) |
EmbedContentConfig(output_dimensionality=768) ; la tâche se donne en préfixe du texte (task: search result | query: ...), pas par task_type |
Exemples
Génération avec instructions système, puis en flux :
config = types.GenerateContentConfig(
system_instruction="Tu es l'assistant du support. Réponds en français, en trois phrases au plus.",
thinking_config=types.ThinkingConfig(thinking_level="LOW"),
max_output_tokens=1024,
labels={"app": "support"},
)
response = client.models.generate_content( # [*]
model="gemini-3.5-flash", contents="Comment réinitialiser mon mot de passe ?", config=config,
)
print(response.text, response.usage_metadata.total_token_count)
for chunk in client.models.generate_content_stream(
model="gemini-3.5-flash", contents="Rédige la procédure détaillée.", config=config,
):
print(chunk.text or "", end="")
[*] Gemini 3.8 Flash (
gemini-3.8-flash), le plus récent des Flash, peut être testé à la place de 3.5 Flash : il est plus capable, mais sa disponibilité est courte (pas de date de retrait garantie, préavis d'au moins 45 jours), il ne se règle pas, et il n'est servi que surglobal,useteu(voir Choisir un modèle).
Extraction structurée d'un PDF stocké dans Cloud Storage — l'agent de service de la plateforme doit pouvoir lire l'objet :
from pydantic import BaseModel
class Facture(BaseModel):
fournisseur: str
montant_ttc: float
echeance: str
response = client.models.generate_content(
model="gemini-3.5-flash-lite",
contents=[
types.Part.from_uri(file_uri="gs://BUCKET/factures/f-001.pdf", mime_type="application/pdf"),
"Extrais le fournisseur, le montant TTC et la date d'échéance.",
],
config=types.GenerateContentConfig(response_mime_type="application/json", response_schema=Facture),
)
facture: Facture = response.parsed
Appel de fonction déclarée à la main, en deux allers-retours :
stock = types.FunctionDeclaration(
name="stock_article",
description="Renvoie le stock disponible d'un article.",
parameters_json_schema={"type": "object", "properties": {"sku": {"type": "string"}}, "required": ["sku"]},
)
config = types.GenerateContentConfig(tools=[types.Tool(function_declarations=[stock])])
contents = [types.Content(role="user", parts=[types.Part.from_text(text="Reste-t-il du A-42 ?")])]
response = client.models.generate_content(model="gemini-3.5-flash", contents=contents, config=config) # [*]
contents.append(response.candidates[0].content) # tour du modèle complet, signatures comprises
reponses = [
types.Part.from_function_response(name=appel.name, response={"stock": lire_stock(**appel.args)})
for appel in response.function_calls or []
]
contents.append(types.Content(role="user", parts=reponses))
final = client.models.generate_content(model="gemini-3.5-flash", contents=contents, config=config)
Passer une fonction Python dans tools= déclenche l'appel automatique (automatic function calling) : le SDK exécute la fonction et relance le modèle. Pratique en conversation, mais sans contrôle sur ce qui est exécuté ; pour un agent complet, ADK prend le relais (voir Construire un agent).
Cache explicite d'un gros document réutilisé par de nombreuses requêtes :
cache = client.caches.create(
model="gemini-3.5-flash",
config=types.CreateCachedContentConfig(
contents=[types.Content(role="user", parts=[
types.Part.from_uri(file_uri="gs://BUCKET/contrats/cadre.pdf", mime_type="application/pdf"),
])],
system_instruction="Tu réponds uniquement à partir du contrat fourni.",
ttl="3600s",
),
)
response = client.models.generate_content(
model="gemini-3.5-flash", contents="Quel est le préavis de résiliation ?",
config=types.GenerateContentConfig(cached_content=cache.name),
)
Le cache implicite est actif par défaut et s'applique dès 4 096 jetons de préfixe commun sur Gemini 3 (6 144 pour 3.7 et 3.8 Flash) : placer le contenu stable en tête du prompt suffit souvent. Le cache explicite garantit la remise de 90 %, mais son stockage est facturé à la durée ; le supprimer (client.caches.delete) dès qu'il ne sert plus. En amont du modèle, un cache des réponses de l'application, par clé exacte ou sémantique (index vectoriel dans Memorystore), évite tout appel pour une question déjà traitée (Well-Architected Framework, efficacité énergétique de l'IA).
Inférence par lots, depuis une table BigQuery :
job = client.batches.create(
model="gemini-3.5-flash-lite",
src="bq://PROJECT_ID.DATASET.prompts",
config=types.CreateBatchJobConfig(dest="bq://PROJECT_ID.DATASET.reponses"),
)
print(client.batches.get(name=job.name).state)
Un lot contient jusqu'à 200 000 requêtes (fichier JSONL de 1 Go au plus depuis Cloud Storage). Le service relance lui-même les requêtes en échec ; les remises du lot et du cache ne se cumulent pas, celle du cache l'emporte.
Débit, quotas et erreurs 429
| Option | Principe | Pour quoi |
|---|---|---|
| Standard PayGo (défaut) | Capacité partagée ; débit de référence en jetons par minute fixé par palier, selon les dépenses de l'organisation sur 30 jours ; dépassements servis au mieux | Trafic courant et variable |
| Priority PayGo | Tarif majoré, traitement prioritaire ; en-tête X-Vertex-AI-LLM-Shared-Request-Type: priority ; global, us, eu |
Application critique sans engagement |
| préversion Flex PayGo | −50 %, latence et délestage plus élevés ; en-tête ...: flex ; global seulement, délai jusqu'à 30 min |
Traitements synchrones non urgents |
| Provisioned Throughput | Débit réservé en GSU, engagement d'une semaine à un an ; débordement facturé en PayGo | Charge de base constante, SLA |
| Inférence par lots | Pool partagé, pas de quota prédéfini ; mise en file possible | Gros volumes asynchrones |
Le palier Standard PayGo s'applique à chaque modèle séparément et se mesure sur l'endpoint global, qui puise dans la capacité de plusieurs régions. usage_metadata.traffic_type indique si une réponse a été servie en PayGo (ON_DEMAND, ON_DEMAND_PRIORITY, ON_DEMAND_FLEX) ou sur le débit provisionné. Le tableau de bord d'observabilité des modèles de la console suit, par modèle et par emplacement, les requêtes par seconde, le débit de jetons, la latence du premier jeton et les taux d'erreur des appels à l'API ; ces métriques Cloud Monitoring servent aussi aux alertes. Les modèles auto-déployés n'y figurent pas.
Une erreur 429 (RESOURCE_EXHAUSTED) signale une capacité partagée saturée ou un débit provisionné dépassé. Dans l'ordre : passer par global si la résidence le permet, lisser le trafic à la seconde (les pics brefs sont limités même sous la moyenne), monter progressivement en charge, relancer avec un délai exponentiel, puis réserver du débit.
client = genai.Client(
enterprise=True, project="PROJECT_ID", location="global",
http_options=types.HttpOptions(
retry_options=types.HttpRetryOptions(attempts=5, initial_delay=1.0, max_delay=60.0),
timeout=120_000, # millisecondes
),
)
Sans retry_options, le client Python 2.25 ne relance rien : c'est ce que montre son code source (retry_args(None) arrête à la première tentative), même si la page Retry strategy annonce des relances par défaut. Le déclarer explicitement lève l'ambiguïté. Les codes relancés par défaut sont 408, 429 et 5xx ; 400, 401 et 403 ne se relancent pas. Les erreurs remontent en errors.ClientError (4xx) et errors.ServerError (5xx), avec e.code et e.message.
Pièges
- Signatures de réflexion perdues. Avec Gemini 3, le tour du modèle contient des signatures de réflexion à renvoyer telles quelles avec le résultat des fonctions. Reconstruire ce tour à la main, ou n'en garder que la partie
function_call, produit une erreur 400. Toujours réinjecterresponse.candidates[0].contententier. response.textvide. Une réponse bloquée par un filtre, arrêtée parMAX_TOKENSou réduite à des appels de fonction n'a pas de texte. Lirecandidates[0].finish_reasonetprompt_feedbackavant de conclure à un bug.- Réflexion qui mange la sortie. Les jetons de réflexion comptent dans
max_output_tokenset sont facturés : une limite trop basse coupe la réponse avant qu'elle commence. Surveillerthoughts_token_count. - Relances en rafale. Une boucle de relance sans délai ni plafond aggrave la saturation. En temps réel, peu de tentatives et un échec rapide ; en Flex, allonger le délai d'attente plutôt que relancer ; pour un lot, ne rien relancer soi-même.
- Aucun repli. Quand les erreurs persistent malgré les relances, un disjoncteur (circuit breaker) cesse d'appeler le modèle saturé et bascule sur un repli prévu : modèle plus léger, autre emplacement compatible avec la résidence, réponse en cache ou message dégradé (Well-Architected Framework, fiabilité). Le repli se teste et s'évalue comme le chemin principal.
- Client recréé à chaque requête. Créer le client une fois par processus et le fermer (
client.close(), ou blocwith) : chaque instance ouvre son propre pool de connexions. - Recherche et fonctions dans la même requête. L'ancrage Google Search ne se combine pas avec l'appel de fonctions ni avec l'outil de récupération de RAG Engine dans un même
generateContent: plusieurs outils ne sont acceptés que s'ils sont tous des outils de recherche. Séparer les appels, ou confier l'orchestration à un agent. - Endpoint et modèle incompatibles. Tous les modèles ne sont pas sur tous les endpoints : Gemini 3.8 Flash n'existe qu'en
global,useteu, pas en région. Une erreur 404 sur un modèle valide vient souvent de là. - Fichier Cloud Storage illisible. La lecture d'un
gs://se fait avec l'identité de la plateforme, pas celle de l'appelant : accorderroles/storage.objectViewersur le bucket à l'agent de serviceservice-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, et, si un périmètre VPC Service Controls protège le projet, y inclure aussi le projet du bucket.
Alternatives en logiciel libre
L'équivalent libre de cet appel est un modèle aux poids libres (voir Choisir un modèle) servi derrière une API compatible OpenAI.
- vLLM (Apache 2.0) : serveur compatible OpenAI avec cache automatique des préfixes (l'équivalent du cache implicite), sortie structurée par schéma JSON, appel de fonctions et inférence par lots hors ligne ; la capacité et les quotas sont ceux de ses propres GPU.
- Ollama (MIT) et llama.cpp (MIT) : la même API compatible OpenAI sur un poste ou un petit serveur, avec sortie contrainte par schéma JSON.
- LiteLLM (MIT, hors répertoire
enterprise) : une interface unique vers une centaine de fournisseurs, Gemini et serveurs locaux compris ; en proxy, il ajoute clés virtuelles, budgets, limites de débit, relances et bascule d'un modèle à l'autre. - Outlines (Apache 2.0) : génération contrainte au niveau des jetons par schéma JSON, expression régulière ou grammaire ; la sortie respecte le format par construction.
- Instructor (MIT) : sortie structurée validée par Pydantic, avec nouvelle tentative quand la validation échoue, sur la plupart des API de modèles ; l'équivalent de
response_schemaetresponse.parsed.