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.
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:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateUne 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.
pip install --upgrade google-genaiIl 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 :
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 :
- Accédez à (https://ai.google.dev/) et connectez-vous avec un compte Google.
- Cliquez sur « Get API key » (Obtenir une clé API).
- Choisissez de créer la clé API dans un nouveau projet Google Cloud ou un projet existant.
- 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_KEYavec 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 :
- Sélectionner ou créer un projet Google Cloud.
- S'assurer que la facturation est activée pour le projet.
- 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 loginLorsqu'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.
1.4. Initialisation du client : Connexion au modèle
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»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 genaiclient = 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é configuradafrom google import genaiclient = genai.Client() -
Scénario 3 : API Vertex AI (Paramètres explicites) Pour se connecter à Vertex AI, l'indicateur
vertexaiest défini surTrueet 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 genaiclient = 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=trueexport GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'export GOOGLE_CLOUD_LOCATION='us-central1'# El cliente se configurará automáticamente para Vertex AIfrom google import genaiclient = 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'utilisation | Code Python | Variables d'environnement requises | Notes |
|---|---|---|---|
| API de développeur avec clé explicite | client = genai.Client(api_key="SU_CLAVE...") | Aucune | Utile pour les notebooks et les tests rapides. À éviter dans le code de production. |
| API de développeur avec var. d'environnement | client = genai.Client() | GOOGLE_API_KEY ou GEMINI_API_KEY | Méthode privilégiée pour un code d'application propre et sécurisé. |
| Vertex AI avec paramètres explicites | client = 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'environnement | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Configure 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ó anteriormenteresponse = 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 : unrole(généralement 'user' pour l'entrée ou 'model' pour la sortie) et une liste departs.types.Part: Représente un élément de données au sein d'un objetContent. 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 unUserContentavec une seulePartde texte. - Une liste de chaînes :
contents=['Pregunta 1', 'Pregunta 2']est converti en un uniqueUserContentcontenant deuxPartde texte. - Un objet
types.Part: Permet un contrôle plus détaillé, comme la spécification de données d'image. - Un objet
types.Contentcomplè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}")2.2. Réponses en streaming pour un retour en temps réel
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»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 inicializadoresponse_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 final2.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 :
- 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. - 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. - 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 chatchat_session = client.chats.create( model="gemini-2.0-flash")
# 2. Enviar el primer mensajeprint("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 seguimientoprint("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ónprint("--- 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 inicializadoresponse = 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ètre | Description | Plage | Effet sur la sortie |
|---|---|---|---|
temperature | Contrôle l'aléatoire de la sélection des jetons. | 0.0 - 1.0 | Des 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.0 | Une 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_k | Ne considère que les k jetons les plus probables à chaque étape de la génération. | Entier | Un 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_count | Le 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_tokens | Le nombre maximal de tokens pouvant être générés dans la réponse. | Entier | Limite la longueur de la sortie. Essentiel pour contrôler les coûts et la latence. |
stop_sequences | Une liste de chaînes qui, lorsqu'elles sont générées, arrêteront la sortie. | Liste de chaînes | Utile pour arrêter la génération à un point spécifique, comme un marqueur de fin de phrase ou un format particulier. |
seed | Graine aléatoire pour la génération. | Entier | Fournir 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.
3.2. Travailler avec des images
Sección titulada «3.2. Trabajando con Imágenes»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 genaifrom google.genai import types# Asumiendo que 'client' ha sido inicializadowith 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 solicitudresponse = client.models.generate_content(model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-visioncontents=[prompt_part, image_part])print(response.text) -
Depuis une URL : Vous pouvez utiliser une bibliothèque comme
requestspour 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 :
- 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. - Indiquer : L'objet de fichier renvoyé est transmis directement dans la liste
contentsd'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 Archivosprint("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ónprompt = "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 usoclient.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 :
- Utilisez
client.files.upload()pour charger le fichier audio (ex. : MP3, WAV) ou vidéo (ex. : MP4). - 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 genaiimport time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audioprint("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é ACTIVOwhile 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ónprompt = "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 :
- 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.
- Passer les outils au modèle : La liste des outils définis est transmise au modèle lors de l'appel à
generate_content. - 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
Partde typefunction_call. Cet objet spécifie le nom de la fonction à appeler et les arguments nécessaires pour l'appeler. - 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. - 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 untypes.Part.from_function_response()). - 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_exceptionsimport google.genai as genai
# Asumiendo que 'client' ha sido inicializadotry: 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 | État | Cause probable | Action recommandée en Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | Le 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. |
| 403 | PERMISSION_DENIED | La 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. |
| 429 | RESOURCE_EXHAUSTED | La 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. |
| 500 | INTERNAL | Une 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. |
| 503 | UNAVAILABLE | Le 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. |
4.2. Gestion de la sécurité du contenu
Sección titulada «4.2. Gestión de la Seguridad del Contenido»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'API | Configuration dans Google AI Studio | Description |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | Le seuil n'est pas spécifié ; le seuil par défaut du modèle est utilisé. |
BLOCK_NONE | Block 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_HIGH | Block few (Peu de blocages) | Bloquer uniquement lorsque la probabilité de contenu dangereux est HIGH. |
BLOCK_MEDIUM_AND_ABOVE | Bloquer 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_ABOVE | Bloquer la plupart | Bloquer lorsque la probabilité de contenu non sécurisé est LOW, MEDIUM ou HIGH. |
4.3. Gestion des modèles
Sección titulada «4.3. Gestión de Modelos»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 inicializadoprint("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-generativeaivers la nouvelle normegoogle-genai. ✓ - Les clés API sont gérées exclusivement via la variable d'environnement
GOOGLE_API_KEYou 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 domaineportelcore.com. ✓

