SDK de Python Google GenAI para a API de Gemini
Guia de referência e configuração avançada para o novo SDK unificado google-genai da API de Gemini na Portelcore.
Parte 1: Conceptos Fundamentales y Configuración Inicial
Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»Esta seção estabelece o contexto para o novo SDK, abordando a principal confusão do usuário sobre a mudança de biblioteca, e fornece uma guia robusta para começar corretamente, cobrindo a instalação e as duas vias de autenticação críticas.
1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»El ecosistema de desarrollo para los modelos de IA generativa de Google ha evolucionado.
La biblioteca anterior, google-generativeai, ha sido marcada como ‘Inactiva’ en el Python Package Index (PyPI) y se encuentra en un camino de obsolescencia.
Este cambio no es simplemente un cambio de nombre, sino una unificación estratégica impulsada por los comentarios de los desarrolladores.
Esta arquitectura unificada proporciona una rampa de acceso fluida para los desarrolladores.
1.2. Instalación y Entorno
Sección titulada «1.2. Instalación y Entorno»Antes de instalar o SDK, é uma prática recomendada configurar um ambiente virtual de Python. Isso isola as dependências do projeto, evitando conflitos com outros projetos ou com os pacotes do sistema.
Para crear y activar un entorno virtual usando venv:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateUna vez que el entorno virtual esté activo, se puede instalar la última versión del SDK de Google Gen AI usando pip. El uso del indicador --upgrade asegura que se obtenga la versión más reciente.
pip install --upgrade google-genaiEs fundamental tener en cuenta los requisitos de la versión de Python. El SDK google-genai requiere Python 3.9 o superior. El uso de una versión no compatible puede provocar errores inesperados durante la instalación o el tiempo de ejecución.
Para aplicaciones que requieren un rendimiento asíncrono de alto rendimiento, el SDK ofrece una opción para usar aiohttp como backend de transporte HTTP en lugar del predeterminado httpx. Esto se puede instalar como un extra:
pip install google-genai[aiohttp]1.3. Autenticación: Su Clave para la API de Gemini
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»A autenticação é o passo de configuração mais crítico e o método difere de acordo com o serviço de backend que se pretende utilizar: a API de desenvolvedor de Gemini ou a API de Gemini no Vertex AI.
1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»Esta é a forma mais rápida de começar a construir com Gemini. Requer uma chave de API que pode ser obtida de forma gratuita a partir do Google AI Studio.
El proceso para obtener una clave de API es el siguiente:
- Navegue a (https://ai.google.dev/) e inicie sesión com uma conta de Google.
- Clique em “Get API key” (Obter chave de API).
- Escolha criar a chave de API em um projeto de Google Cloud novo ou existente.
- A chave de API será gerada automaticamente.
As chaves de API são credenciais sensíveis e devem ser tratadas como senhas. Devem ser armazenadas de forma segura e nunca devem ser expostas no código do lado do cliente ou confirmadas em sistemas de controle de versões públicos.
O método mais seguro e recomendado para usar a chave é configurá-la como uma variável de ambiente. O SDK está projetado para detectar e usar automaticamente as variáveis de ambiente GOOGLE_API_KEY ou GEMINI_API_KEY. Se ambas estiverem configuradas, GOOGLE_API_KEY tem prioridade.
Para configurar a variável de ambiente:
-
Em 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 -
En Windows: Use la interfaz gráfica de “Variables de entorno” en la configuración del sistema para agregar una nueva variable de usuario o de sistema llamada GOOGLE_API_KEY con su clave como valor.
1.3.2. A Vía de Vertex AI (Recomendada para Produção e Integración con Google Cloud)
Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»Para aplicativos a escala de produção que requerem as características empresariais de Google Cloud, se recomenda usar a API de Gemini a través de Vertex AI. Este enfoque requer um projeto de Google Cloud com a faturação habilitada.
Os passos de configuração iniciais incluem:
- Selecionar ou criar um projeto de Google Cloud.
- Asegurar-se de que a faturação esteja habilitada para o projeto.
- Habilitar a API de Vertex AI (
aiplatform.googleapis.com) para o projeto.
A autenticação para Vertex AI pode ser realizada de duas maneiras:
-
Credenciais Predeterminadas de Aplicação (ADC) (Recomendado para produção): Este é o método preferido para a maioria dos cenários de produção. ADC encontra automaticamente as credenciais de acordo com o ambiente. Em um ambiente de desenvolvimento local, isso pode ser configurado executando um comando da CLI de gcloud:
Ventana de terminal gcloud auth application-default loginQuando executado em um ambiente de Google Cloud (por exemplo, Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC utiliza automaticamente a conta de serviço associada a esse recurso, eliminando a necessidade de gerenciar chaves.
-
Claves de API (para testes em Vertex): É possível usar uma chave de API para se autenticar no endpoint de Vertex AI, mas o processo é mais complexo que com a API de desenvolvedor. Requer permissões a nível de organização para habilitar a criação de chaves de API de contas de serviço, criar uma conta de serviço com um papel apropriado (por exemplo,
Vertex AI User), e criar uma chave de API restringida a essa conta de serviço. Devido à sua complexidade, esse método é usado geralmente para cenários de teste específicos em vez de desenvolvimento de aplicativos gerais.
1.4. Inicialização do Cliente: Conectando-se ao Modelo
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»Una vez que la autenticación está configurada, el siguiente paso es instanciar el objeto genai.Client.
A seguir são apresentados os quatro cenários principais para a inicialização do cliente.
-
Escenario 1: API de Desarrollador de Gemini (Clave Explícita) Este método es conveniente para cuadernos o scripts rápidos donde no se desea configurar variables de entorno.
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
Escenario 2: API de Desarrollador de Gemini (Variable de Entorno) Este es el enfoque más limpio y recomendado para el código de la aplicación, ya que desacopla las credenciales del código.
# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
Escenario 3: API de Vertex AI (Parámetros Explícitos) Para conectarse a Vertex AI, se establece el indicador vertexai en True y se proporcionan el ID del proyecto y la ubicación.
from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
Escenario 4: API de Vertex AI (Variables de Entorno) Como alternativa para Vertex AI, la configuración se puede externalizar a variables de entorno.
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()
A tabela a seguir resume estes métodos para uma referência rápida.
Tabla 1: Referencia Rápida de Inicialización del Cliente
| Caso de Uso | Código Python | Variables de Entorno Requeridas | Notas |
|---|---|---|---|
| API de Desarrollador con Clave Explícita | client = genai.Client(api_key="SU_CLAVE...") | Ninguna | Útil para cadernos e testes rápidos. Evitar em código de produção. |
| API de Desarrollador con Var. de Entorno | client = genai.Client() | GOOGLE_API_KEY o GEMINI_API_KEY | Método preferido para código de aplicação limpo e seguro. |
| Vertex AI con Parámetros Explícitos | client = genai.Client(vertexai=True, project="...", location="...") | Ninguna (usa ADC) | Método explícito para apuntar a Vertex AI. Requiere autenticación ADC (gcloud auth...). |
| Vertex AI con Var. de Entorno | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Configura o cliente para Vertex AI sem parâmetros no código. Requer autenticação ADC. |
Parte 2: Capacidades Principales: Texto y Chat
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»Esta parte se aprofunda nos casos de uso mais comuns: gerar texto e construir agentes conversacionais. Detalha os principais métodos e objetos envolvidos.
2.1. Generando Contenido: El Método generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»O metodo principal para todas as tarefas de geracao de um turno e o client.models.generate_content().
Un uso básico implica proporcionar una cadena de texto simple como contents y especificar el nombre del modelo a utilizar, como 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)A estrutura de dados subyacente que utiliza o SDK e composta por objetos types.Content e types.Part.
- types.Content: Representa un único mensaje o turno en una conversación. Tiene dos atributos principales: un role (generalmente ‘user’ para la entrada o ‘model’ para la salida) y una lista de parts.
- types.Part: Representa una pieza de datos dentro de un objeto Content. Una parte puede ser texto, datos de imagen, una referencia de archivo, una llamada a función, etc.
El SDK maneja de forma inteligente varios tipos de entrada para el argumento contents, convirtiéndolos al formato Content/Part apropiado:
- Una sola cadena: contents='¿Por qué el cielo es azul?' se convierte en un UserContent con una sola Part de texto.
- Una lista de cadenas: contents=['Pregunta 1', 'Pregunta 2'] se convierte en un único UserContent que contiene dos Part de texto.
- Un objeto types.Part: Permite un control más detallado, como especificar datos de imagen.
- Un objeto types.Content completamente formado: Proporciona el máximo control sobre el rol y el contenido del mensaje.
Para acceder a la respuesta generada, el accesor de conveniencia response.text es el método más simple. Sin embargo, es importante saber que este accesor solo funciona para respuestas simples que consisten en una única parte de texto. Si la respuesta es bloqueada por filtros de seguridad, contiene múltiples candidatos o incluye tipos de datos no textuales, acceder a response.text generará un error. El método más robusto y seguro para producción es acceder directamente al candidato y a sus partes:
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. Respuestas en Streaming para Retroalimentación en Tiempo Real
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»Para aplicações interativas como os chatbots, o streaming da resposta do modelo melhora drasticamente a experiência do usuário. Em vez de esperar que toda a resposta seja gerada, os fragmentos de texto são exibidos à medida que chegam, fornecendo uma retroalimentação imediata.
Esta funcionalidad se logra con el método generate_content_stream(). Este método devuelve un iterador que produce fragmentos de la respuesta a medida que son generados por el modelo.
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. Dominando la IA Conversacional: La Interfaz de Chat
Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»El SDK proporciona dos mecanismos principales para gestionar conversaciones de múltiples turnos. Un enfoque es gestionar manualmente el historial de la conversación, construyendo una lista de objetos Content que representan cada turno y pasándola a generate_content() en cada llamada. Si bien es flexible, este método puede ser engorroso.
O enfoque recomendado e mais conveniente para criar chatbots e utilizar a interface de chat com estado proporcionada por client.chats.
El flujo de trabajo para usar la interfaz de chat es el siguiente:
- Inicializar una sesión de chat: Se utiliza client.chats.create() para iniciar una nueva conversación. Se puede especificar el modelo y, opcionalmente, proporcionar un historial inicial para contextualizar la conversación.
- Enviar mensajes: Se utiliza el método chat.send_message() para enviar el siguiente mensaje del usuario. El SDK gestiona automáticamente el estado, añadiendo el mensaje del usuario y la posterior respuesta del modelo al historial de la conversación.
- Acceder al historial: En cualquier momento, se puede recuperar el historial completo de la conversación utilizando chat.get_history().
A seguir é mostrado um exemplo completo de uma conversa de vários turnos:
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. Control Avanzado de la Generación
Sección titulada «2.4. Control Avanzado de la Generación»Para afinar el comportamiento del modelo, el método generate_content() acepta un parámetro config, que toma un objeto types.GenerateContentConfig. Este objeto permite a los desarrolladores controlar varios aspectos del proceso de generación.
Una de las configuraciones más útiles es system_instruction. Una instrucción del sistema proporciona una guía de alto nivel o establece una personalidad para el modelo que persiste a lo largo de toda la conversación.
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)Além das instruções do sistema, há vários outros parâmetros que podem ser ajustados para controlar a criatividade e a estrutura da saída do modelo. A tabela a seguir detalha os mais importantes.
Tabla 2: Parámetros Clave de Configuración de la Generación
| Parâmetro | Descripción | Rango | Efecto en la Salida |
|---|---|---|---|
| temperature | Controla a aleatoriedade da seleção de tokens. | 0.0 - 1.0 | Valores más bajos (p. ej., 0.2) hacen que la salida sea más determinista y menos creativa. Valores más altos (p. ej., 0.9) aumentan la aleatoriedad y la creatividad. |
| top_p | Muestreo de núcleo (nucleus sampling). Considera el conjunto más pequeño de tokens cuya probabilidad acumulada es mayor que top_p. | 0.0 - 1.0 | Un valor como 0.95 significa que solo se consideran los tokens que comprenden el 95% superior de la masa de probabilidad. Ayuda a evitar tokens muy improbables. |
| top_k | Considera solo los k tokens más probables en cada paso de la generación. | Entero | Un top_k de 1 es una decodificación codiciosa (greedy). Un valor como 40 restringe la selección a los 40 tokens más probables. |
| candidate_count | El número de respuestas candidatas a generar. | Entero (p. ej., 1-8) | Gera múltiplas respostas possíveis para a mesma instrução. Útil para oferecer opções ao usuário. |
| max_output_tokens | O número máximo de tokens que podem ser gerados na resposta. | Entero | Limita o comprimento da saída. Essencial para controlar os custos e a latência. |
| stop_sequences | Uma lista de strings que, quando geradas, interromperão a saída. | Lista de strings | Útil para interromper a geração em um ponto específico, como um marcador de fim de frase ou um formato particular. |
| seed | Semente aleatória para a geração. | Entero | Fornecer uma semente torna a saída determinística e reprodutível (desde que temperature não seja 0). |
Parte 3: Interações Avançadas: Multimodalidade e Chamada de Funções
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»Esta parte mostra o verdadeiro poder dos modelos Gemini ao explicar como trabalhar com entradas não textuais e conectar o modelo a ferramentas externas.
Mais Allá do Texto: Compreendendo as Entradas Multimodais
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Uma das características definitorias da família de modelos Gemini é sua capacidade multimodal inherente. Isso significa que podem processar e raciocinar sobre diferentes tipos de dados, ou “modalidades”, como texto, imagens, áudio e vídeo, dentro de uma única solicitação de indicação.
Esta capacidad se habilita construyendo el argumento contents como una lista que contiene múltiples objetos Part, donde cada Part puede contener un tipo de datos diferente.
Mais Allá do Texto: Compreendendo as Entradas Multimodais
Sección titulada «3.2. Trabajando con Imágenes»O SDK fornece dois métodos estratégicamente distintos para gerenciar dados de imagens. A escolha entre eles depende dos requisitos específicos do caso de uso, como o tamanho do arquivo e a reutilização.
Essa dualidade de métodos não é uma redundância, mas um design deliberado que aborda diferentes necessidades operativas. O método em linha é simples e excelente para análises únicas e conveniência no desenvolvimento. A API de Arquivos, embora implique um passo de carga adicional, é fundamental para cenários de produção onde a eficiência, a escalabilidade e o gerenciamento de arquivos grandes são primordiais.
Método 1: Dados de Imagem em Línea (Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»Esse método é ideal para arquivos de imagem mais pequenos (a solicitação total, incluindo as indicações e os bytes, deve ser inferior a 20 MB) e para a simplicidade no desenvolvimento. Os dados da imagem são passados diretamente na chamada a generate_content.
-
Desde un archivo local: El archivo de imagen se lee en modo binario y se pasa a types.Part.from_bytes(), especificando el tipo MIME correcto.
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) -
Desde uma URL:
Método 2: La API de Archivos (Files API)
Sección titulada «Método 2: La API de Archivos (Files API)»Este método se recomienda para archivos de imagen grandes (superiores a 20 MB) o para escenarios en los que el mismo archivo se reutilizará en múltiples solicitudes de indicación.
El flujo de trabajo consta de dos pasos:
- Cargar: Se utiliza client.files.upload() para cargar el archivo a los servidores de Google.
- Indicar: Se pasa el objeto de archivo devuelto directamente en la lista contents de una llamada a generate_content().
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}")Los archivos cargados a través de la API de Archivos se almacenan temporalmente durante 48 horas antes de ser eliminados automáticamente.
3.3. Interacción con Audio y Vídeo
Sección titulada «3.3. Interacción con Audio y Vídeo»Los conceptos de manejo de imágenes se extienden directamente a otras modalidades como el audio y el vídeo.
El proceso es idéntico al de las imágenes grandes:
- Use client.files.upload() para cargar el archivo de audio (p. ej., MP3, WAV) o de vídeo (p. ej., MP4).
- Incluya el objeto de archivo devuelto en la indicación a generate_content().
O exemplo a seguir mostra como carregar um arquivo de áudio e pedir ao modelo que o transcreva.
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. Llamada a Funciones: Ampliando las Capacidades del Modelo
Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»La llamada a funciones, también conocida como uso de herramientas (tool use), es una técnica poderosa que permite al modelo de lenguaje interactuar con sistemas externos.
El flujo de trabajo general es el siguiente:
- Definir Herramientas:
- Pasar Herramientas al Modelo: Se pasa la lista de herramientas definidas al modelo en la llamada a generate_content.
- El Modelo Decide Llamar: El modelo analiza la indicación del usuario y, si determina que una de las herramientas proporcionadas puede ayudar a responder, en lugar de generar texto, su respuesta contendrá un objeto Part de tipo function_call. Este objeto especifica el nombre de la función a llamar y los argumentos con los que llamarla.
- Ejecutar la Función: El código de la aplicación detecta esta function_call, ejecuta la función de Python correspondiente con los argumentos proporcionados y obtiene un resultado.
- Devolver el Resultado al Modelo: Se realiza una segunda llamada a generate_content, proporcionando el historial de la conversación más el resultado de la ejecución de la función (envuelto en un types.Part.from_function_response()).
- Respuesta Final: El modelo utiliza el resultado de la función para generar una respuesta final en lenguaje natural para el usuario.
Aunque los fragmentos de investigación no proporcionan un ejemplo de código de llamada a funciones de extremo a extremo, la estructura de los objetos Part para function_call y function_response es la base para implementar este patrón avanzado.
Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»Esta parte final fornece a informação crítica necessária para construir aplicações robustas, fiáveis e responsáveis.
4.1. Manejo Robusto de Errores
Sección titulada «4.1. Manejo Robusto de Errores»Em um ambiente de produção, um manejo de erros robusto não é negociável. As chamadas à API podem falhar por diversas razões, como credenciais não válidas, problemas de rede, esgotamento de quotas ou entradas malformadas.
O SDK utiliza o sistema de excecoes estandard de Python. A maioria dos erros relacionados com a API se pode capturar utilizando um bloco try...except que busca excecoes do modulo google.api_core.exceptions ou, se estiver disponivel, uma classe mais especifica como 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}")Ao capturar uma exceção, o objeto da exceção frequentemente contém informação valiosa para o registro e a depuração, como um código de estado e uma mensagem descritiva.
Es importante considerar que los mensajes de error, si bien son útiles para los desarrolladores, pueden ser una espada de doble filo. Pueden filtrar detalles de implementación interna que podrían ser explotados en ataques adversarios.
A tabela a seguir resume os códigos de erro da API mais comuns e como resolvê-los.
Tabla 3: Códigos de Error Comunes de la API y Resoluciones
| Código HTTP | Estado | Causa Probable | Acción Recomendada en Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | O corpo da solicitação está malformado (p. ex., um parâmetro com um tipo incorreto, um campo obrigatório ausente). | Verifique que los parámetros en GenerateContentConfig y el formato de contents sean correctos. Asegúrese de que el modelo sea compatible con las características solicitadas. |
| 403 | PERMISSION_DENIED | A chave de API é incorreta, não tem os permissões necessárias ou está tentando acessar um recurso restrito (p. ex., um modelo ajustado). | Verifique que a chave de API (ou a autenticação ADC para Vertex) esteja configurada corretamente e tenha as permissões necessárias. |
| 429 | RESOURCE_EXHAUSTED | Foi excedido o limite de velocidade da API (solicitações por minuto). | Implemente uma retirada exponencial em sua lógica de reintento. Considere solicitar um aumento de quota se necessário para sua aplicação. |
| 500 | INTERNAL | Ocorreu um erro inesperado no lado do Google. Às vezes pode ser causado por um contexto de entrada muito longo. | Reduza a longitude da indicação. Tente novamente a solicitação após uma breve espera. Se o problema persistir, considere mudar para um modelo diferente temporariamente. |
| 503 | UNAVAILABLE | O serviço está temporariamente sobrecarregado ou não disponível. | Tente novamente a solicitação após uma breve espera utilizando uma estratégia de retirada exponencial. Se o problema persistir, informe do problema. |
4.2. Gestión de la Seguridad del Contenido
Sección titulada «4.2. Gestión de la Seguridad del Contenido»A API de Gemini inclui características de segurança integradas para filtrar conteúdo potencialmente danoso. Estas características estão projetadas para ajudar os desenvolvedores a construir aplicações mais seguras e responsáveis.
A API classifica o conteúdo em quatro categorias principais de dano:
- Acoso (HARM_CATEGORY_HARASSMENT)
- Incitación al odio (HARM_CATEGORY_HATE_SPEECH)
- Contenido sexualmente explícito (HARM_CATEGORY_SEXUALLY_EXPLICIT)
- Contenido peligroso (HARM_CATEGORY_DANGEROUS_CONTENT)
Para cada categoría, el modelo asigna una probabilidad de que el contenido sea inseguro. Por defecto, la API bloquea las indicaciones y respuestas que tienen una probabilidad MEDIUM o HIGH de ser inseguras en cualquiera de estas categorías.
Os desenvolvedores podem anular essa configuracao predeterminada por solicitacao passando uma lista de objetos SafetySetting ao parmetro safety_settings.
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}")Cuando una respuesta parece vacía o se produce un error, es crucial inspeccionar la retroalimentación de seguridad. El objeto de respuesta contiene prompt_feedback (para la indicación de entrada) y candidates.safety_ratings (para la respuesta generada). Estos atributos revelarán si el contenido fue bloqueado y por qué, lo cual es esencial para la depuración.
La siguiente tabla aclara el significado de los diferentes umbrales de bloqueo.
Tabla 4: Umbrales de Configuración de Seguridad
| Constante de la API | Configuración en Google AI Studio | Descripción |
|---|---|---|
| HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | O limiar não está especificado; utiliza-se o limiar padrão do modelo. |
| BLOCK_NONE | Block none (Bloquear ninguno) | Nunca bloquear conteúdo, independentemente da probabilidade de que seja inseguro. Deve ser usado com extrema precaução. |
| BLOCK_ONLY_HIGH | Block few (Bloquear pocos) | Bloquear solo cuando la probabilidad de contenido inseguro es HIGH. |
| BLOCK_MEDIUM_AND_ABOVE | Block some (Bloquear algunos) | Block some (Bloquear algunos) |
| BLOCK_LOW_AND_ABOVE | Block most (Bloquear la mayoría) | Bloquear cuando la probabilidad de contenido inseguro es LOW, MEDIUM o HIGH. |
4.3. Gestión de Modelos
Sección titulada «4.3. Gestión de Modelos»O SDK fornece uma forma programática de descobrir os modelos disponíveis e suas capacidades. Isso é útil para construir aplicações que podem se adaptar a diferentes modelos ou para verificar as capacidades de um modelo antes de usá-lo.
El método client.models.list() devuelve un iterador sobre los modelos 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)Esta funcionalidade tambem se pode utilizar para listar especificamente os modelos que foram ajustados (fine-tuned) pelo usuario, estabelecendo query_base=False na configuracao da solicitacao de lista.
Parte 5: Validacao do Entorno e Checklist Tecnica
Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»Para finalizar o aprovisionamento de integracoes baseadas no SDK unificado google-genai em o tenant de Portelcore, valida o cumprimento de os seguintes hitos tecnicos:
- He migrado todos os scripts do tenant da libreria obsoleta google-generativeai para o novo estandar google-genai.
- As chaves de API estao gerenciadas exclusivamente atraves da variavel de ambiente GOOGLE_API_KEY ou ofuscadas no gestor de secretos de Google Cloud em lugar de escritas em texto plano.
- Se implementa um controle de excecoes robusto para capturar códigos de estado 429 (Resource Exhausted) com politicas de reintento exponencial.
- A temperatura e os umbrais de seguranca estao parametrizados formalmente de acordo com o caso de uso do dominio portelcore.com.
Recursos e Enlaces Oficiais
Sección titulada «Recursos y Enlaces Oficiales»- Documentacao Oficial do SDK Google Gen AI Python
- Referencia da API de Gemini
- Google AI Studio - Gestao de Chaves
- Vertex AI em Google Cloud

