Ir al contenido
Destacado

SDK de Python Google GenAI pour l'API de Gemini

Guide de référence et configuration avancée pour le nouveau SDK unifié google-genai de l'API de Gemini en Portelcore.

Difficulté technique :
0vues

Partie 1 : Concepts fondamentaux et configuration initiale

Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»

Cette section établit le contexte du nouveau SDK, abordant la principale confusion de l'utilisateur concernant le changement de bibliothèque, et fournit un guide robuste pour bien débuter, couvrant l'installation et les deux voies d'authentification critiques.

1.1. Le nouveau standard : migrer de google-generativeai à google-genai

Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»

L'écosystème de développement pour les modèles d'IA générative de Google a évolué. La bibliothèque google-genai est désormais le SDK Python officiel, unifié et recommandé pour interagir avec l'API Gemini et d'autres modèles d'IA générative de Google. Il a atteint la disponibilité générale (GA) en mai 2025 et remplace la bibliothèque héritée, google-generativeai.

L'ancienne bibliothèque, google-generativeai, a été marquée comme « inactive » sur le Python Package Index (PyPI) et se trouve sur une voie d'obsolescence. Le support de ce package, y compris les corrections de bugs critiques, cessera fin septembre 2025, bien que certaines sources indiquent une date de fin de support légèrement antérieure, le 31 août 2025. Il est recommandé aux développeurs de viser la date la plus précoce pour garantir une transition sans heurts.

Ce changement n'est pas simplement un changement de nom, mais une unification stratégique motivée par les retours des développeurs. L'objectif était de créer un SDK unique qui simplifie l'accès à toute la gamme de modèles d'IA générative de Google (Gemini, Veo, Imagen, etc.) et offre un parcours de développement plus clair et cohérent. L'une des décisions de conception les plus significatives du nouveau SDK google-genai est qu'il agit comme une interface unique pour deux services backend distincts : l'API développeur Gemini, facile d'accès, et la plateforme Vertex AI, de niveau entreprise.

Cette architecture unifiée offre une rampe d'accès fluide pour les développeurs. Ils peuvent commencer rapidement, souvent avec un niveau gratuit, en utilisant une clé API pour l'API développeur Gemini. À mesure que leurs applications mûrissent et nécessitent une plus grande évolutivité, gouvernance et intégration avec d'autres services Google Cloud, ils peuvent passer au backend Vertex AI avec un minimum de modifications dans le code, principalement lors de l'initialisation du client. Le SDK google-genai sert de pont, réduisant la barrière à l'entrée tout en offrant un chemin clair vers la production sur Google Cloud. Par conséquent, tous les utilisateurs de la bibliothèque héritée sont invités à migrer pour garantir l'accès aux dernières fonctionnalités (telles que Live API et Veo), aux améliorations de performance et au support continu.

1.2. Installation et environnement

Sección titulada «1.2. Instalación y Entorno»

Avant d'installer le SDK, il est recommandé de configurer un environnement virtuel Python. Cela isole les dépendances du projet, évitant ainsi les conflits avec d'autres projets ou avec les paquets du système.

Pour créer et activer un environnement virtuel en utilisant venv:

Ventana de terminal
# En macOS/Linux
python3 -m venv gemini-env
source gemini-env/bin/activate
# En Windows
py -m venv gemini-env
.\gemini-env\Scripts\activate

Une fois l'environnement virtuel activé, vous pouvez installer la dernière version du SDK Google Gen AI en utilisant pip. L'utilisation de l'indicateur --upgrade garantit l'obtention de la version la plus récente.

Ventana de terminal
pip install --upgrade google-genai

Il est essentiel de prendre en compte les exigences relatives à la version de Python. Le SDK google-genai nécessite Python 3.9 ou une version supérieure. L'utilisation d'une version non compatible peut entraîner des erreurs inattendues lors de l'installation ou de l'exécution.

Pour les applications nécessitant une haute performance asynchrone, le SDK offre l'option d'utiliser aiohttp comme backend de transport HTTP au lieu du mode par défaut httpx. Cela peut être installé en tant qu'extension :

Ventana de terminal
pip install google-genai[aiohttp]

1.3. Authentification : votre clé pour l'API Gemini

Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»

L'authentification est l'étape de configuration la plus critique et la méthode diffère selon le service backend que vous souhaitez utiliser : l'API développeur Gemini ou l'API Gemini sur Vertex AI.

1.3.1. La voie de l'API développeur Gemini (recommandée pour les prototypes et le niveau gratuit)

Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»

C'est la méthode la plus rapide pour commencer à construire avec Gemini. Elle nécessite une clé API qui peut être obtenue gratuitement via Google AI Studio.

Le processus pour obtenir une clé API est le suivant :

  1. Accédez à (https://ai.google.dev/) et connectez-vous avec un compte Google.
  2. Cliquez sur « Get API key » (Obtenir une clé API).
  3. Choisissez de créer la clé API dans un nouveau projet Google Cloud ou un projet existant.
  4. La clé API sera générée automatiquement.

Les clés API sont des identifiants sensibles et doivent être traitées comme des mots de passe. Elles doivent être stockées de manière sécurisée et ne doivent jamais être exposées dans le code côté client ou validées dans des systèmes de contrôle de version publics.

La méthode la plus sûre et recommandée pour utiliser la clé est de la configurer en tant que variable d'environnement. Le SDK est conçu pour détecter et utiliser automatiquement les variables d'environnement GOOGLE_API_KEY ou GEMINI_API_KEY. Si les deux sont configurées, GOOGLE_API_KEY a la priorité.

Pour configurer la variable d'environnement :

  • Sous Linux/macOS (bash) :

    Ventana de terminal
    export GOOGLE_API_KEY='SU_CLAVE_DE_API_AQUI'
    # Agregue esta línea a su archivo ~/.bashrc o ~/.zshrc para que sea permanente
  • Sous Windows : Utilisez l'interface graphique des « Variables d'environnement » dans les paramètres système pour ajouter une nouvelle variable utilisateur ou système nommée GOOGLE_API_KEY avec votre clé comme valeur.

1.3.2. La voie Vertex AI (recommandée pour la production et l'intégration avec Google Cloud)

Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»

Pour les applications à l'échelle de la production nécessitant les fonctionnalités professionnelles de Google Cloud, il est recommandé d'utiliser l'API Gemini via Vertex AI. Cette approche nécessite un projet Google Cloud avec la facturation activée.

Les étapes de configuration initiale incluent :

  1. Sélectionner ou créer un projet Google Cloud.
  2. S'assurer que la facturation est activée pour le projet.
  3. Activer l'API Vertex AI (aiplatform.googleapis.com) pour le projet.

L'authentification pour Vertex AI peut être effectuée de deux manières :

  • Identifiants d'application par défaut (ADC) (Recommandé pour la production) : C'est la méthode préférée pour la plupart des scénarios de production. ADC trouve automatiquement les identifiants en fonction de l'environnement. Dans un environnement de développement local, cela peut être configuré en exécutant une commande de la CLI gcloud :

    Ventana de terminal
    gcloud auth application-default login

    Lorsqu'il est exécuté dans un environnement Google Cloud (par exemple, Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC utilise automatiquement le compte de service associé à cette ressource, éliminant ainsi la nécessité de gérer des clés.

  • Clés d'API (pour les tests sur Vertex) : Il est possible d'utiliser une clé d'API pour s'authentifier sur l'endpoint de Vertex AI, mais le processus est plus complexe qu'avec l'API de développeur. Cela nécessite des autorisations au niveau de l'organisation pour permettre la création de clés d'API pour les comptes de service, la création d'un compte de service avec un rôle approprié (par exemple, Vertex AI User), puis la création d'une clé d'API restreinte à ce compte de service. En raison de sa complexité, cette méthode est généralement utilisée pour des scénarios de test spécifiques plutôt que pour le développement d'applications générales.

Une fois l'authentification configurée, l'étape suivante consiste à instancier l'objet genai.Client. Le SDK unifié simplifie cela en fournissant un client unique qui peut être configuré pour l'un ou l'autre des backends.

Voici les quatre principaux scénarios d'initialisation du client.

  • Scénario 1 : API Gemini pour développeurs (Clé explicite) Cette méthode est pratique pour les notebooks ou les scripts rapides où l'on ne souhaite pas configurer de variables d'environnement. La clé API est passée directement comme argument.

    from google import genai
    client = genai.Client(api_key="SU_CLAVE_DE_API_AQUI")
  • Scénario 2 : API Gemini pour développeurs (Variable d'environnement) C'est l'approche la plus propre et la plus recommandée pour le code de l'application, car elle sépare les identifiants du code. Le client trouve et utilise automatiquement la variable d'environnement GOOGLE_API_KEY.

    # Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configurada
    from google import genai
    client = genai.Client()
  • Scénario 3 : API Vertex AI (Paramètres explicites) Pour se connecter à Vertex AI, l'indicateur vertexai est défini sur True et l'ID du projet ainsi que l'emplacement sont fournis. Cette méthode utilisera automatiquement les Identifiants d'application par défaut (ADC) pour l'authentification.

    from google import genai
    client = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1")
  • Scénario 4 : API Vertex AI (Variables d'environnement) Comme alternative pour Vertex AI, la configuration peut être externalisée via des variables d'environnement. Le client détectera ces variables et sera configuré pour utiliser le backend Vertex AI.

    Ventana de terminal
    export GOOGLE_GENAI_USE_VERTEXAI=true
    export GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'
    export GOOGLE_CLOUD_LOCATION='us-central1'
    # El cliente se configurará automáticamente para Vertex AI
    from google import genai
    client = genai.Client()

Le tableau suivant résume ces méthodes pour une référence rapide.

Tableau 1 : Référence rapide de l'initialisation du client

Cas d'utilisationCode PythonVariables d'environnement requisesNotes
API de développeur avec clé expliciteclient = genai.Client(api_key="SU_CLAVE...")AucuneUtile pour les notebooks et les tests rapides. À éviter dans le code de production.
API de développeur avec var. d'environnementclient = genai.Client()GOOGLE_API_KEY ou GEMINI_API_KEYMéthode privilégiée pour un code d'application propre et sécurisé.
Vertex AI avec paramètres explicitesclient = genai.Client(vertexai=True, project="...", location="...")Aucune (utilise ADC)Méthode explicite pour pointer vers Vertex AI. Nécessite une authentification ADC (gcloud auth...).
Vertex AI avec variables d'environnementclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONConfigure le client pour Vertex AI sans paramètres dans le code. Nécessite une authentification ADC.

Partie 2 : Capacités principales : texte et chat

Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»

Cette partie explore les cas d'utilisation les plus courants : générer du texte et construire des agents conversationnels. Elle détaille les principales méthodes et les objets impliqués.

2.1. Génération de contenu : la méthode generate_content

Sección titulada «2.1. Generando Contenido: El Método generate_content»

La méthode principale pour toutes les tâches de génération en un seul tour est client.models.generate_content(). Cette méthode polyvalente est la base de l'interaction avec les modèles Gemini.

Une utilisation de base consiste à fournir une chaîne de texte simple telle que contents et à spécifier le nom du modèle à utiliser, comme gemini-2.5-flash.

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado como se describió anteriormente
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explica brevemente por qué el cielo es azul."
)
print(response.text)

Bien que le passage d'une chaîne simple soit pratique, il est essentiel de comprendre la structure de données sous-jacente utilisée par le SDK. En interne, le SDK convertit toutes les entrées en une structure standardisée composée d'objets types.Content et types.Part. Comprendre cette structure est la clé pour débloquer les capacités avancées du SDK, telles que les invites multimodales et les appels de fonctions.

  • types.Content : Représente un message ou un tour unique dans une conversation. Il possède deux attributs principaux : un role (généralement 'user' pour l'entrée ou 'model' pour la sortie) et une liste de parts.
  • types.Part : Représente un élément de données au sein d'un objet Content. Une partie peut être du texte, des données d'image, une référence de fichier, un appel de fonction, etc.

Le SDK gère intelligemment plusieurs types d'entrée pour l'argument contents, en les convertissant au format Content/Part approprié :

  • Une seule chaîne : contents='¿Por qué el cielo es azul?' est converti en un UserContent avec une seule Part de texte.
  • Une liste de chaînes : contents=['Pregunta 1', 'Pregunta 2'] est converti en un unique UserContent contenant deux Part de texte.
  • Un objet types.Part : Permet un contrôle plus détaillé, comme la spécification de données d'image.
  • Un objet types.Content complètement formé : Il offre un contrôle maximal sur le rôle et le contenu du message.

Pour accéder à la réponse générée, l'accesseur de convenance response.text est la méthode la plus simple. Cependant, il est important de savoir que cet accesseur ne fonctionne que pour les réponses simples consistant en une seule partie de texte. Si la réponse est bloquée par des filtres de sécurité, contient plusieurs candidats ou inclut des types de données non textuels, l'accès à response.text générera une erreur. La méthode la plus robuste et la plus sûre pour la production consiste à accéder directement au candidat et à ses parties :

try:
# Método robusto para acceder al texto
text_response = response.candidates.content.parts.text
print(text_response)
except (IndexError, AttributeError):
# Manejar el caso en que no hay respuesta de texto válida
print("No se pudo obtener una respuesta de texto válida.")
# Se puede inspeccionar response.prompt_feedback para ver si fue bloqueado
print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}")

Pour les applications interactives telles que les chatbots, le streaming de la réponse du modèle améliore considérablement l'expérience utilisateur. Au lieu d'attendre que toute la réponse soit générée, les fragments de texte s'affichent à mesure qu'ils arrivent, fournissant un retour immédiat.

Cette fonctionnalité est obtenue grâce à la méthode generate_content_stream(). Cette méthode renvoie un itérateur qui produit des fragments de la réponse au fur et à mesure qu'ils sont générés par le modèle.

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
response_stream = client.models.generate_content_stream(
model="gemini-2.0-flash",
contents="Escribe un poema largo sobre el océano y sus misterios."
)
print("Respuesta del modelo:")
for chunk in response_stream:
print(chunk.text, end="")
print() # Para una nueva línea al final

2.3. Maîtriser l'IA conversationnelle : l'interface de chat

Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»

Le SDK fournit deux mécanismes principaux pour gérer les conversations multi-tours. Une approche consiste à gérer manuellement l'historique de la conversation en construisant une liste d'objets Content représentant chaque tour et en la passant à generate_content() à chaque appel. Bien que flexible, cette méthode peut être fastidieuse.

L'approche recommandée et la plus pratique pour créer des chatbots consiste à utiliser l'interface de chat avec état fournie par client.chats. Cet objet de haut niveau abstrait la gestion de l'historique, simplifiant considérablement le code de l'application. Il s'agit d'une décision de conception délibérée dans le SDK : fournir une abstraction de haut niveau et avec état (client.chats) pour un cas d'utilisation courant (chat), ce qui simplifie énormément le développement par rapport à la méthode de bas niveau et sans état generate_content.

Le flux de travail pour utiliser l'interface de chat est le suivant :

  1. Initialiser une session de chat : client.chats.create() est utilisé pour démarrer une nouvelle conversation. Vous pouvez spécifier le modèle et, facultativement, fournir un historique initial pour contextualiser la conversation.
  2. Envoyer des messages : la méthode chat.send_message() est utilisée pour envoyer le message suivant de l'utilisateur. Le SDK gère automatiquement l'état, en ajoutant le message de l'utilisateur et la réponse ultérieure du modèle à l'historique de la conversation.
  3. Accéder à l'historique : à tout moment, l'historique complet de la conversation peut être récupéré en utilisant chat.get_history().

Voici un exemple complet d'une conversation à plusieurs tours :

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Crear una nueva sesión de chat
chat_session = client.chats.create(
model="gemini-2.0-flash"
)
# 2. Enviar el primer mensaje
print("Usuario: Hola, ¿puedes ayudarme a planificar un viaje a la luna?")
response = chat_session.send_message("Hola, ¿puedes ayudarme a planificar un viaje a la luna?")
print(f"Modelo: {response.text}\n")
# 3. Enviar un segundo mensaje de seguimiento
print("Usuario: ¿Qué tres cosas debería empacar?")
response = chat_session.send_message("¿Qué tres cosas debería empacar?")
print(f"Modelo: {response.text}\n")
# 4. Mostrar el historial completo de la conversación
print("--- Historial de la Conversación ---")
for message in chat_session.get_history():
# El rol y el texto están en message.role y message.parts.text
role = "Usuario" if message.role == "user" else "Modelo"
print(f"{role}: {message.parts.text}")

2.4. Contrôle avancé de la génération

Sección titulada «2.4. Control Avanzado de la Generación»

Pour affiner le comportement du modèle, la méthode generate_content accepte un paramètre config, qui prend un objet types.GenerateContentConfig. Cet objet permet aux développeurs de contrôler plusieurs aspects du processus de génération.

L'une des configurations les plus utiles est system_instruction. Une instruction système fournit un guide de haut niveau ou établit une personnalité pour le modèle qui persiste tout au long de la conversation. Par exemple, on peut instruire le modèle pour qu'il agisse comme un personnage spécifique ou qu'il suive certaines règles dans ses réponses.

from google.genai import types
# Asumiendo que 'client' ha sido inicializado
response = client.models.generate_content(
model='gemini-2.0-flash',
contents='¡Ah del barco! Cuéntame un chiste sobre un loro.',
config=types.GenerateContentConfig(
system_instruction='Hablas como un pirata malhumorado y conciso.'
)
)
print(response.text)

En plus des instructions système, il existe plusieurs autres paramètres qui peuvent être ajustés pour contrôler la créativité et la structure de la sortie du modèle. Le tableau suivant détaille les plus importants.

Tableau 2 : Paramètres clés de configuration de la génération

ParamètreDescriptionPlageEffet sur la sortie
temperatureContrôle l'aléatoire de la sélection des jetons.0.0 - 1.0Des valeurs plus basses (p. ex., 0.2) rendent la sortie plus déterministe et moins créative. Des valeurs plus élevées (p. ex., 0.9) augmentent l'aléa et la créativité.
top_pÉchantillonnage de noyau (nucleus sampling). Considère le plus petit ensemble de jetons dont la probabilité cumulée est supérieure à top_p.0.0 - 1.0Une valeur comme 0.95 signifie que seuls les jetons comprenant les 95 % supérieurs de la masse de probabilité sont pris en compte. Cela aide à éviter les jetons très improbables.
top_kNe considère que les k jetons les plus probables à chaque étape de la génération.EntierUn top_k de 1 est un décodage glouton (greedy). Une valeur comme 40 limite la sélection aux 40 jetons les plus probables.
candidate_countLe nombre de réponses candidates à générer.Entier (p. ex., 1-8)Génère plusieurs réponses possibles pour la même instruction. Utile pour proposer des options à l'utilisateur.
max_output_tokensLe nombre maximal de tokens pouvant être générés dans la réponse.EntierLimite la longueur de la sortie. Essentiel pour contrôler les coûts et la latence.
stop_sequencesUne liste de chaînes qui, lorsqu'elles sont générées, arrêteront la sortie.Liste de chaînesUtile pour arrêter la génération à un point spécifique, comme un marqueur de fin de phrase ou un format particulier.
seedGraine aléatoire pour la génération.EntierFournir une graine rend la sortie déterministe et reproductible (tant que temperature n'est pas 0).

Partie 3 : Interactions avancées : multimodalité et appel de fonctions

Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»

Cette partie montre le véritable pouvoir des modèles Gemini en expliquant comment travailler avec des entrées non textuelles et connecter le modèle à des outils externes.

3.1. Au-delà du texte : comprendre les entrées multimodales

Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»

L'une des caractéristiques définissant la famille de modèles Gemini est sa capacité multimodale intrinsèque. Cela signifie qu'ils peuvent traiter et raisonner sur différents types de données, ou « modalités », tels que le texte, les images, l'audio et la vidéo, au sein d'une seule requête de prompt.

Cette capacité est activée en construisant l'argument contents sous la forme d'une liste contenant plusieurs objets Part, où chaque Part peut contenir un type de données différent. Par exemple, une seule requête peut inclure une image et une question textuelle sur cette image.

Le SDK fournit deux méthodes stratégiquement distinctes pour gérer les données d'image. Le choix entre elles dépend des exigences spécifiques du cas d'utilisation, telles que la taille du fichier et la réutilisation.

Cette dualité de méthodes n'est pas une redondance, mais une conception délibérée qui répond à différents besoins opérationnels. La méthode en ligne est simple et excellente pour les analyses uniques et la commodité du développement. L'API Files, bien qu'elle implique une étape de chargement supplémentaire, est essentielle pour les scénarios de production où l'efficacité, l'évolutivité et la gestion de fichiers volumineux sont primordiales.

Méthode 1 : Données d'image en ligne (Inline)

Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»

Cette méthode est idéale pour les fichiers d'image plus petits (la requête totale, incluant les instructions et les octets, doit être inférieure à 20 Mo) et pour la simplicité du développement. Les données de l'image sont passées directement dans l'appel à generate_content.

  • Depuis un fichier local : Le fichier d'image est lu en mode binaire ('rb') et transmis à types.Part.from_bytes(), en spécifiant le type MIME correct.

    import google.genai as genai
    from google.genai import types
    # Asumiendo que 'client' ha sido inicializado
    with open('imagen_scones.jpg', 'rb') as f:
    image_bytes = f.read()
    image_part = types.Part.from_bytes(
    data=image_bytes,
    mime_type='image/jpeg'
    )
    prompt_part = "Describe lo que ves en esta imagen."
    # Combinar imagen y texto en una sola solicitud
    response = client.models.generate_content(
    model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-vision
    contents=[prompt_part, image_part]
    )
    print(response.text)
  • Depuis une URL : Vous pouvez utiliser une bibliothèque comme requests pour obtenir les octets de l'image à partir d'une URL, puis les transmettre de la même manière.

Méthode 2 : L'API de fichiers (Files API)

Sección titulada «Método 2: La API de Archivos (Files API)»

Cette méthode est recommandée pour les fichiers image volumineux (supérieurs à 20 Mo) ou pour les scénarios où le même fichier sera réutilisé dans plusieurs requêtes de prompt. L'utilisation de l'API de fichiers évite de devoir recharger les mêmes octets à chaque appel.

Le flux de travail se compose de deux étapes :

  1. Charger : client.files.upload() est utilisé pour charger le fichier sur les serveurs de Google. Cette méthode renvoie un objet de fichier qui fait office de référence.
  2. Indiquer : L'objet de fichier renvoyé est transmis directement dans la liste contents d'un appel à generate_content. Le SDK se charge de résoudre la référence au fichier chargé.
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar el archivo usando la API de Archivos
print("Cargando archivo...")
sample_file = client.files.upload(
file_path="imagen_grande.png",
display_name="Mi Imagen de Muestra"
)
print(f"Archivo cargado: {sample_file.uri}")
# 2. Usar el archivo cargado en una indicación
prompt = "Analiza esta imagen y describe los objetos principales y su disposición espacial."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=[prompt, sample_file] # Pasar el objeto de archivo directamente
)
print(response.text)
# Opcional: Eliminar el archivo después de su uso
client.files.delete(name=sample_file.name)
print(f"Archivo eliminado: {sample_file.name}")

Les fichiers téléchargés via l'API Files sont stockés temporairement pendant 48 heures avant d'être automatiquement supprimés. L'API fournit également des méthodes pour gérer ces fichiers, telles que get(), list() et delete().

3.3. Interaction avec l'audio et la vidéo

Sección titulada «3.3. Interacción con Audio y Vídeo»

Les concepts de gestion d'images s'étendent directement à d'autres modalités telles que l'audio et la vidéo. Étant donné que ces fichiers sont souvent volumineux, l'API Files est la méthode principale pour travailler avec eux.

Le processus est identique à celui des images volumineuses :

  1. Utilisez client.files.upload() pour charger le fichier audio (ex. : MP3, WAV) ou vidéo (ex. : MP4).
  2. Incluez l'objet de fichier renvoyé dans le prompt de generate_content.

L'exemple suivant montre comment charger un fichier audio et demander au modèle de le transcrire.

import google.genai as genai
import time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audio
print("Cargando archivo de audio...")
audio_file = client.files.upload(
file_path="discurso_muestra.mp3",
display_name="Discurso de Muestra"
)
# El procesamiento del archivo puede llevar tiempo, se espera a que esté ACTIVO
while audio_file.state.name == "PROCESSING":
print("Procesando archivo... esperando.")
time.sleep(10)
audio_file = client.files.get(name=audio_file.name)
if audio_file.state.name == "FAILED":
raise ValueError(audio_file.state.name)
# 2. Usar el archivo de audio en una indicación
prompt = "Transcribe el discurso en este archivo de audio."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=[prompt, audio_file]
)
print("\n--- Transcripción ---")
print(response.text)

3.4. Appel de fonctions : Étendre les capacités du modèle

Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»

L'appel de fonctions, également connu sous le nom d'utilisation d'outils (tool use), est une technique puissante qui permet au modèle de langage d'interagir avec des systèmes externes. Il permet au modèle de répondre à des questions ou d'effectuer des actions qui vont au-delà de sa connaissance intrinsèque, comme obtenir des données en temps réel via une API, consulter une base de données ou contrôler un appareil.

Le flux de travail général est le suivant :

  1. Définir les outils : Un ensemble d'outils (fonctions Python) que le modèle peut appeler est défini. Cette définition comprend le nom de la fonction, une description de ce qu'elle fait et le schéma de ses paramètres.
  2. Passer les outils au modèle : La liste des outils définis est transmise au modèle lors de l'appel à generate_content.
  3. Le modèle décide d'appeler : Le modèle analyse l'invite de l'utilisateur et, s'il détermine que l'un des outils fournis peut aider à répondre, au lieu de générer du texte, sa réponse contiendra un objet Part de type function_call. Cet objet spécifie le nom de la fonction à appeler et les arguments nécessaires pour l'appeler.
  4. Exécuter la fonction : Le code de l'application détecte cet function_call, exécute la fonction Python correspondante avec les arguments fournis et obtient un résultat.
  5. Renvoyer le résultat au modèle : Un second appel est effectué à generate_content, en fournissant l'historique de la conversation plus le résultat de l'exécution de la fonction (enveloppé dans un types.Part.from_function_response()).
  6. Réponse finale : Le modèle utilise le résultat de la fonction pour générer une réponse finale en langage naturel pour l'utilisateur.

Bien que les extraits de recherche ne fournissent pas d'exemple de code d'appel de fonction de bout en bout, la structure des objets Part pour function_call et function_response constitue la base de l'implémentation de ce modèle avancé.


Partie 4 : Préparation à la production : traitement des erreurs, sécurité et gestion

Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»

Cette dernière partie fournit les informations critiques nécessaires pour construire des applications robustes, fiables et responsables.

4.1. Traitement robuste des erreurs

Sección titulada «4.1. Manejo Robusto de Errores»

Dans un environnement de production, un traitement robuste des erreurs n'est pas négociable. Les appels API peuvent échouer pour diverses raisons, telles que des identifiants non valides, des problèmes de réseau, l'épuisement des quotas ou des entrées malformées.

Le SDK utilise le système d'exceptions standard de Python. La plupart des erreurs liées à l'API peuvent être capturées en utilisant un bloc try...except qui recherche des exceptions du module google.api_core.exceptions ou, si disponible, une classe plus spécifique comme errors.APIError.

from google.api_core import exceptions as core_exceptions
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
try:
response = client.models.generate_content(
model="nombre-de-modelo-invalido",
contents="¿Cuál es tu nombre?"
)
print(response.text)
except core_exceptions.GoogleAPICallError as e:
# 'e' es una superclase para muchos errores de API
print(f"Ha ocurrido un error en la API: {e}")
# En muchos casos, 'e' tendrá atributos como 'code' y 'message'
# aunque esto puede variar. Se recomienda inspeccionar el objeto de excepción.
except core_exceptions.NotFound as e:
# Un error más específico si se sabe qué buscar
print(f"Error: Recurso no encontrado. ¿Es correcto el nombre del modelo? - {e.message}")
except core_exceptions.ResourceExhausted as e:
# Específico para errores de cuota
print(f"Error: Se ha excedido la cuota de la API. - {e.message}")

Lors de la capture d'une exception, l'objet d'exception contient souvent des informations précieuses pour la journalisation et le débogage, telles qu'un code d'état et un message descriptif.

Il est important de considérer que les messages d'erreur, bien qu'utiles pour les développeurs, peuvent être une arme à double tranchant. Ils peuvent divulguer des détails de l'implémentation interne qui pourraient être exploités lors d'attaques adverses. Par exemple, une analyse des messages d'erreur de validation de sécurité pourrait révéler des seuils internes ou des mécanismes de défense, aidant ainsi un acteur malveillant à contourner les protections. Par conséquent, bien que les erreurs doivent être enregistrées de manière exhaustive dans le backend, les informations présentées aux utilisateurs finaux doivent être soigneusement contrôlées. Il est souvent plus sûr d'afficher un message générique tel que « Une erreur est survenue lors du traitement de votre demande » plutôt que d'exposer le message d'erreur brut de l'API.

Le tableau suivant résume les codes d'erreur d'API les plus courants et la manière de les résoudre.

Tableau 3 : Codes d'erreur API courants et résolutions

Code HTTPÉtatCause probableAction recommandée en Python
400INVALID_ARGUMENTLe corps de la requête est mal formé (par exemple, un paramètre avec un type incorrect, un champ obligatoire manquant).Vérifiez que les paramètres dans GenerateContentConfig et le format de contents sont corrects. Assurez-vous que le modèle est compatible avec les caractéristiques demandées.
403PERMISSION_DENIEDLa clé API est incorrecte, vous ne disposez pas des permissions nécessaires ou vous tentez d'accéder à une ressource restreinte (par exemple, un modèle ajusté).Vérifiez que la clé API (ou l'authentification ADC pour Vertex) est correctement configurée et dispose des permissions nécessaires.
429RESOURCE_EXHAUSTEDLa limite de débit de l'API a été dépassée (requêtes par minute).Implémentez un retrait exponentiel (exponential backoff) dans votre logique de tentative. Envisagez de demander une augmentation de quota si cela est nécessaire pour votre application.
500INTERNALUne erreur inattendue est survenue du côté de Google. Cela peut parfois être causé par un contexte d'entrée trop long.Réduisez la longueur de l'invite. Réessayez la requête après une courte attente. Si le problème persiste, envisagez de changer temporairement de modèle.
503UNAVAILABLELe service est temporairement surchargé ou indisponible.Réessayez la requête après une courte attente en utilisant une stratégie de retrait exponentiel. Si le problème persiste, signalez le problème.

L'API Gemini inclut des fonctionnalités de sécurité intégrées pour filtrer le contenu potentiellement nuisible. Ces fonctionnalités sont conçues pour aider les développeurs à construire des applications plus sûres et responsables.

L'API classe le contenu en quatre catégories principales de dommages :

  • Harcèlement (HARM_CATEGORY_HARASSMENT)
  • Incitation à la haine (HARM_CATEGORY_HATE_SPEECH)
  • Contenu sexuellement explicite (HARM_CATEGORY_SEXUALLY_EXPLICIT)
  • Contenu dangereux (HARM_CATEGORY_DANGEROUS_CONTENT)

Pour chaque catégorie, le modèle attribue une probabilité que le contenu soit dangereux. Par défaut, l'API bloque les instructions et les réponses qui ont une probabilité MEDIUM ou HIGH d'être dangereuses dans l'une de ces catégories.

Les développeurs peuvent annuler cette configuration par défaut par requête en passant une liste d'objets SafetySetting au paramètre safety_settings. Cela permet un contrôle granulaire du seuil de blocage pour chaque catégorie.

from google.genai import types
# Asumiendo que 'client' ha sido inicializado
# Ejemplo: Relajar el umbral para el acoso, pero mantener el predeterminado para otros.
# ¡Use esta configuración con precaución y solo si es necesario para su caso de uso!
safety_config =
try:
response = client.models.generate_content(
model='gemini-2.0-flash',
contents="Escribe un diálogo entre dos personajes que están discutiendo acaloradamente.",
safety_settings=safety_config
)
print(response.text)
except ValueError:
# A menudo, una respuesta bloqueada puede generar un ValueError al intentar acceder a.text
print("La respuesta fue bloqueada o está vacía.")
# Inspeccionar la retroalimentación de seguridad para depurar
print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}")
if response.candidates:
print(f"Calificaciones de seguridad del candidato: {response.candidates.safety_ratings}")

Lorsqu'une réponse semble vide ou qu'une erreur se produit, il est crucial d'inspecter le retour d'information sur la sécurité. L'objet de réponse contient prompt_feedback (pour l'instruction d'entrée) et candidates.safety_ratings (pour la réponse générée). Ces attributs révéleront si le contenu a été bloqué et pourquoi, ce qui est essentiel pour le débogage.

Le tableau suivant clarifie la signification des différents seuils de blocage.

Tableau 4 : Seuils de configuration de la sécurité

Constante de l'APIConfiguration dans Google AI StudioDescription
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/ALe seuil n'est pas spécifié ; le seuil par défaut du modèle est utilisé.
BLOCK_NONEBlock none (Aucun blocage)Ne jamais bloquer le contenu, quelle que soit la probabilité qu'il soit dangereux. Doit être utilisé avec une extrême prudence.
BLOCK_ONLY_HIGHBlock few (Peu de blocages)Bloquer uniquement lorsque la probabilité de contenu dangereux est HIGH.
BLOCK_MEDIUM_AND_ABOVEBloquer certains(Par défaut pour la plupart des modèles) Bloquer lorsque la probabilité de contenu non sécurisé est MEDIUM ou HIGH.
BLOCK_LOW_AND_ABOVEBloquer la plupartBloquer lorsque la probabilité de contenu non sécurisé est LOW, MEDIUM ou HIGH.

Le SDK fournit un moyen programmatique de découvrir les modèles disponibles et leurs capacités. Cela est utile pour construire des applications capables de s'adapter à différents modèles ou pour vérifier les capacités d'un modèle avant de l'utiliser.

La méthode client.models.list() renvoie un itérateur sur les modèles disponibles.

Python

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
print("Modelos disponibles:")
for model in client.models.list():
# El objeto 'model' contiene metadatos detallados
print(f" - Nombre: {model.name}")
print(f" - Nombre para mostrar: {model.display_name}")
print(f" - Métodos soportados: {model.supported_generation_methods}")
# Verificar si el modelo soporta chat (create_chat)
if 'create_chat' in model.supported_generation_methods:
print(" - ¡Este modelo soporta chat!")
print("-" * 20)

Cette fonctionnalité peut également être utilisée pour lister spécifiquement les modèles qui ont été affinés (fine-tuned) par l'utilisateur, en définissant query_base=False dans la configuration de la requête de liste. Cela permet aux applications de découvrir et d'utiliser dynamiquement des modèles personnalisés.


Partie 5 : Validation de l'environnement et checklist technique

Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»

Pour finaliser le provisionnement des intégrations basées sur le SDK unifié google-genai dans le tenant Portelcore, validez le respect des jalons techniques suivants :

  • J'ai migré tous les scripts du tenant de la bibliothèque obsolète google-generativeai vers la nouvelle norme google-genai. ✓
  • Les clés API sont gérées exclusivement via la variable d'environnement GOOGLE_API_KEY ou obfusquées dans le gestionnaire de secrets de Google Cloud au lieu d'être écrites en texte clair. ✓
  • Un contrôle d'exceptions robuste (google.api_core.exceptions) est implémenté pour capturer les codes d'état 429 (Resource Exhausted) avec des politiques de backoff exponentiel (exponential backoff). ✓
  • La température et les seuils de sécurité (safety_settings) sont formellement paramétrés conformément au cas d'utilisation du domaine portelcore.com. ✓