Ir al contenido
Destacado

SDK de Python Google GenAI para la API de Gemini

Guía de referencia y configuración avanzada para el nuevo SDK unificado google-genai de la API de Gemini en Portelcore.

Dificultad técnica:
0lecturas

Parte 1: Conceptos Fundamentales y Configuración Inicial

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

Esta sección establece el contexto para el nuevo SDK, abordando la principal confusión del usuario sobre el cambio de biblioteca, y proporciona una guía robusta para comenzar correctamente, cubriendo la instalación y las dos vías de autenticación 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 google-genai es ahora el SDK de Python oficial, unificado y recomendado para interactuar con la API de Gemini y otros modelos de IA generativa de Google. Alcanzó la Disponibilidad General (GA) en mayo de 2025 y reemplaza a la biblioteca heredada, google-generativeai.

La biblioteca anterior, google-generativeai, ha sido marcada como “Inactiva” en el Python Package Index (PyPI) y se encuentra en un camino de obsolescencia. El soporte para este paquete, incluidas las correcciones de errores críticos, cesará a finales de septiembre de 2025, aunque algunas fuentes indican una fecha de finalización del soporte ligeramente anterior, el 31 de agosto de 2025. Se recomienda a los desarrolladores que se dirijan a la fecha más temprana para garantizar una transición sin problemas.

Este cambio no es simplemente un cambio de nombre, sino una unificación estratégica impulsada por los comentarios de los desarrolladores. El objetivo era crear un único SDK que simplificara el acceso a toda la gama de modelos de IA generativa de Google (Gemini, Veo, Imagen, etc.) y ofreciera una ruta de desarrollo más clara y coherente. Una de las decisiones de diseño más significativas del nuevo SDK google-genai es que actúa como una interfaz única para dos servicios de backend distintos: la API de desarrollador de Gemini, de fácil acceso, y la plataforma Vertex AI, de nivel empresarial.

Esta arquitectura unificada proporciona una rampa de acceso fluida para los desarrolladores. Pueden comenzar rápidamente, a menudo con un nivel gratuito, utilizando una clave de API para la API de desarrollador de Gemini. A medida que sus aplicaciones maduran y requieren mayor escalabilidad, gobernanza y integración con otros servicios de Google Cloud, pueden cambiar al backend de Vertex AI con cambios mínimos en el código, principalmente en la inicialización del cliente. El SDK google-genai funciona como un puente, reduciendo la barrera de entrada al tiempo que proporciona un camino claro hacia la producción en Google Cloud. Por lo tanto, se insta a todos los usuarios de la biblioteca heredada a migrar para garantizar el acceso a las últimas características (como Live API y Veo), mejoras de rendimiento y soporte continuo.

Antes de instalar el SDK, es una práctica recomendada configurar un entorno virtual de Python. Esto aísla las dependencias del proyecto, evitando conflictos con otros proyectos o con los paquetes del sistema.

Para crear y activar un entorno virtual usando 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

Una 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.

Ventana de terminal
pip install --upgrade google-genai

Es 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 :

Ventana de terminal
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»

La autenticación es el paso de configuración más crítico y el método difiere según el servicio de backend que se pretenda utilizar: la API de desarrollador de Gemini o la API de Gemini en 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 es la forma más rápida de empezar a construir con Gemini. Requiere una clave de API que se puede obtener de forma gratuita desde Google AI Studio.

El proceso para obtener una clave de API es el siguiente :

  1. Navegue a(https://ai.google.dev/) e inicie sesión con una cuenta de Google.
  2. Haga clic en “Get API key” (Obtener clave de API).
  3. Elija crear la clave de API en un proyecto de Google Cloud nuevo o existente.
  4. La clave de API se generará automáticamente.

Las claves de API son credenciales sensibles y deben tratarse como contraseñas. Deben almacenarse de forma segura y nunca deben ser expuestas en el código del lado del cliente o confirmadas en sistemas de control de versiones públicos.

El método más seguro y recomendado para usar la clave es configurarla como una variable de entorno. El SDK está diseñado para detectar y usar automáticamente las variables de entorno GOOGLE_API_KEY o GEMINI_API_KEY. Si ambas están configuradas, GOOGLE_API_KEY tiene prioridad.

Para configurar la variable de entorno:

  • En 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. La Vía de Vertex AI (Recomendada para Producción 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 aplicaciones a escala de producción que requieren las características empresariales de Google Cloud, se recomienda usar la API de Gemini a través de Vertex AI. Este enfoque requiere un proyecto de Google Cloud con la facturación habilitada.

Los pasos de configuración iniciales incluyen:

  1. Seleccionar o crear un proyecto de Google Cloud.
  2. Asegurarse de que la facturación esté habilitada para el proyecto.
  3. Habilitar la API de Vertex AI (aiplatform.googleapis.com) para el proyecto.

La autenticación para Vertex AI se puede realizar de dos maneras:

  • Credenciales Predeterminadas de Aplicación (ADC) (Recomendado para producción): Este es el método preferido para la mayoría de los escenarios de producción. ADC encuentra automáticamente las credenciales según el entorno. En un entorno de desarrollo local, esto se puede configurar ejecutando un comando de la CLI de gcloud :

    Ventana de terminal
    gcloud auth application-default login

    Cuando se ejecuta en un entorno de Google Cloud (por ejemplo, Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC utiliza automáticamente la cuenta de servicio adjunta a ese recurso, eliminando la necesidad de gestionar claves.

  • Claves de API (para pruebas en Vertex): Es posible usar una clave de API para autenticarse en el endpoint de Vertex AI, pero el proceso es más complejo que con la API de desarrollador. Requiere permisos a nivel de organización para habilitar la creación de claves de API de cuentas de servicio, crear una cuenta de servicio con un rol apropiado (por ejemplo, Vertex AI User), y luego crear una clave de API restringida a esa cuenta de servicio. Debido a su complejidad, este método se usa generalmente para escenarios de prueba específicos en lugar de desarrollo de aplicaciones generales.

1.4. Inicialización del Cliente: Conectándose al 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. El SDK unificado simplifica esto al proporcionar un único cliente que puede configurarse para cualquiera de los dos backends.

A continuación se presentan los cuatro escenarios principales para la inicialización del 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. La clave de API se pasa directamente como un argumento.

    from google import genai
    client = 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. El cliente encuentra y utiliza automáticamente la variable de entorno GOOGLE_API_KEY.

    # Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configurada
    from google import genai
    client = 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. Este método utilizará automáticamente las Credenciales Predeterminadas de Aplicación (ADC) para la autenticación.

    from google import genai
    client = 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. El cliente detectará estas variables y se configurará para usar el backend de 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()

La siguiente tabla resume estos métodos para una referencia rápida.

Tabla 1: Referencia Rápida de Inicialización del Cliente

Caso de UsoCódigo PythonVariables de Entorno RequeridasNotas
API de Desarrollador con Clave Explícitaclient = genai.Client(api_key="SU_CLAVE...")NingunaÚtil para cuadernos y pruebas rápidas. Evitar en código de producción.
API de Desarrollador con Var. de Entornoclient = genai.Client()GOOGLE_API_KEY o GEMINI_API_KEYMétodo preferido para código de aplicación limpio y seguro.
Vertex AI con Parámetros Explícitosclient = 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 Entornoclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONConfigura el cliente para Vertex AI sin parámetros en el código. Requiere autenticación ADC.

Parte 2: Capacidades Principales: Texto y Chat

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

Esta parte se sumerge en los casos de uso más comunes: generar texto y construir agentes conversacionales. Detalla los principales métodos y objetos involucrados.

2.1. Generando Contenido: El Método generate_content

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

El método principal para todas las tareas de generación de un solo turno es client.models.generate_content(). Este método versátil es la base para interactuar con los modelos de Gemini.

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ó anteriormente
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explica brevemente por qué el cielo es azul."
)
print(response.text)

Aunque pasar una cadena simple es conveniente, es fundamental comprender la estructura de datos subyacente que utiliza el SDK. Internamente, el SDK convierte todas las entradas en una estructura estandarizada que consta de objetos types.Content y types.Part. Comprender esta estructura es clave para desbloquear las capacidades avanzadas del SDK, como las indicaciones multimodales y las llamadas a funciones.

  • 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 aplicaciones interactivas como los chatbots, el streaming de la respuesta del modelo mejora drásticamente la experiencia del usuario. En lugar de esperar a que se genere toda la respuesta, los fragmentos de texto se muestran a medida que llegan, proporcionando una retroalimentación inmediata.

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 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. 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.

El enfoque recomendado y más conveniente para crear chatbots es utilizar la interfaz de chat con estado proporcionada por client.chats. Este objeto de nivel superior abstrae la gestión del historial, simplificando significativamente el código de la aplicación. Esta es una decisión de diseño deliberada en el SDK: proporcionar una abstracción de alto nivel y con estado (client.chats) para un caso de uso común (chat), lo que simplifica enormemente el desarrollo en comparación con el método de bajo nivel y sin estado generate_content.

El flujo de trabajo para usar la interfaz de chat es el siguiente:

  1. 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.
  2. 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.
  3. Acceder al historial: En cualquier momento, se puede recuperar el historial completo de la conversación utilizando chat.get_history().

A continuación se muestra un ejemplo completo de una conversación de varios turnos:

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}")

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. Por ejemplo, se puede instruir al modelo para que actúe como un personaje específico o para que siga ciertas reglas en sus respuestas.

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)

Además de las instrucciones del sistema, hay varios otros parámetros que se pueden ajustar para controlar la creatividad y la estructura de la salida del modelo. La siguiente tabla detalla los más importantes.

Tabla 2: Parámetros Clave de Configuración de la Generación

ParámetroDescripciónRangoEfecto en la Salida
temperatureControla la aleatoriedad de la selección de tokens.0.0 - 1.0Valores 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_pMuestreo 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.0Un 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_kConsidera solo los k tokens más probables en cada paso de la generación.EnteroUn 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_countEl número de respuestas candidatas a generar.Entero (p. ej., 1-8)Genera múltiples respuestas posibles para la misma indicación. Útil para ofrecer opciones al usuario.
max_output_tokensEl número máximo de tokens que se pueden generar en la respuesta.EnteroLimita la longitud de la salida. Esencial para controlar los costos y la latencia.
stop_sequencesUna lista de cadenas que, cuando se generan, detendrán la salida.Lista de cadenasÚtil para detener la generación en un punto específico, como un marcador de fin de oración o un formato particular.
seedSemilla aleatoria para la generación.EnteroProporcionar una semilla hace que la salida sea determinista y reproducible (siempre que temperature no sea 0).

Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones

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

Esta parte muestra el verdadero poder de los modelos Gemini al explicar cómo trabajar con entradas no textuales y conectar el modelo a herramientas externas.

3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales

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

Una de las características definitorias de la familia de modelos Gemini es su capacidad multimodal inherente. Esto significa que pueden procesar y razonar sobre diferentes tipos de datos, o “modalidades”, como texto, imágenes, audio y video, dentro de una única solicitud de indicación.

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. Por ejemplo, una sola solicitud puede incluir una imagen y una pregunta de texto sobre esa imagen.

El SDK proporciona dos métodos estratégicamente distintos para manejar datos de imágenes. La elección entre ellos depende de los requisitos específicos del caso de uso, como el tamaño del archivo y la reutilización.

Esta dualidad de métodos no es una redundancia, sino un diseño deliberado que aborda diferentes necesidades operativas. El método en línea es simple y excelente para análisis únicos y conveniencia en el desarrollo. La API de Archivos, aunque implica un paso de carga adicional, es fundamental para escenarios de producción donde la eficiencia, la escalabilidad y el manejo de archivos grandes son primordiales.

Método 1: Datos de Imagen en Línea (Inline)

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

Este método es ideal para archivos de imagen más pequeños (la solicitud total, incluidas las indicaciones y los bytes, debe ser inferior a 20 MB) y para la simplicidad en el desarrollo. Los datos de la imagen se pasan directamente en la llamada a generate_content.

  • Desde un archivo local: El archivo de imagen se lee en modo binario ('rb') y se pasa a types.Part.from_bytes(), especificando el tipo MIME correcto.

    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)
  • Desde una URL: Se puede usar una biblioteca como requests para obtener los bytes de la imagen de una URL y luego pasarlos de la misma manera.

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 uso de la API de Archivos evita la necesidad de volver a cargar los mismos bytes con cada llamada.

El flujo de trabajo consta de dos pasos:

  1. Cargar: Se utiliza client.files.upload() para cargar el archivo a los servidores de Google. Este método devuelve un objeto de archivo que actúa como una referencia.
  2. Indicar: Se pasa el objeto de archivo devuelto directamente en la lista contents de una llamada a generate_content. El SDK se encarga de resolver la referencia al archivo cargado.
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}")

Los archivos cargados a través de la API de Archivos se almacenan temporalmente durante 48 horas antes de ser eliminados automáticamente. La API también proporciona métodos para gestionar estos archivos, como get(), list() y delete().

Los conceptos de manejo de imágenes se extienden directamente a otras modalidades como el audio y el vídeo. Debido a que estos archivos suelen ser grandes, la API de Archivos es el método principal para trabajar con ellos.

El proceso es idéntico al de las imágenes grandes:

  1. Use client.files.upload() para cargar el archivo de audio (p. ej., MP3, WAV) o de vídeo (p. ej., MP4).
  2. Incluya el objeto de archivo devuelto en la indicación a generate_content.

El siguiente ejemplo muestra cómo cargar un archivo de audio y pedirle al modelo que lo transcriba.

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. 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. Permite al modelo responder preguntas o realizar acciones que van más allá de su conocimiento inherente, como obtener datos en tiempo real de una API, consultar una base de datos o controlar un dispositivo.

El flujo de trabajo general es el siguiente:

  1. Definir Herramientas: Se define un conjunto de herramientas (funciones de Python) que el modelo puede llamar. Esta definición incluye el nombre de la función, una descripción de lo que hace y el esquema de sus parámetros.
  2. Pasar Herramientas al Modelo: Se pasa la lista de herramientas definidas al modelo en la llamada a generate_content.
  3. 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.
  4. 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.
  5. 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()).
  6. 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 proporciona la información crítica necesaria para construir aplicaciones robustas, fiables y responsables.

En un entorno de producción, un manejo de errores robusto no es negociable. Las llamadas a la API pueden fallar por diversas razones, como credenciales no válidas, problemas de red, agotamiento de cuotas o entradas malformadas.

El SDK utiliza el sistema de excepciones estándar de Python. La mayoría de los errores relacionados con la API se pueden capturar utilizando un bloque try...except que busca excepciones del módulo google.api_core.exceptions o, si está disponible, una clase más específica como 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}")

Al capturar una excepción, el objeto de la excepción a menudo contiene información valiosa para el registro y la depuración, como un código de estado y un mensaje descriptivo.

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. Por ejemplo, un análisis de los mensajes de error de validación de seguridad podría revelar umbrales internos o mecanismos de defensa, ayudando a un actor malicioso a eludir las protecciones. Por lo tanto, si bien los errores deben registrarse exhaustivamente en el backend, la información presentada a los usuarios finales debe ser cuidadosamente controlada. A menudo es más seguro mostrar un mensaje genérico como “Ocurrió un error al procesar su solicitud” en lugar de exponer el mensaje de error sin procesar de la API.

La siguiente tabla resume los códigos de error de la API más comunes y cómo resolverlos.

Tabla 3: Códigos de Error Comunes de la API y Resoluciones

Código HTTPEstadoCausa ProbableAcción Recomendada en Python
400INVALID_ARGUMENTEl cuerpo de la solicitud está malformado (p. ej., un parámetro con un tipo incorrecto, un campo obligatorio 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.
403PERMISSION_DENIEDLa clave de API es incorrecta, no tiene los permisos necesarios o está intentando acceder a un recurso restringido (p. ej., un modelo ajustado).Verifique que la clave de API (o la autenticación ADC para Vertex) esté configurada correctamente y tenga los permisos necesarios.
429RESOURCE_EXHAUSTEDSe ha excedido el límite de velocidad de la API (solicitudes por minuto).Implemente una retirada exponencial (exponential backoff) en su lógica de reintento. Considere solicitar un aumento de cuota si es necesario para su aplicación.
500INTERNALOcurrió un error inesperado en el lado de Google. A veces puede ser causado por un contexto de entrada muy largo.Reduzca la longitud de la indicación. Intente de nuevo la solicitud después de una breve espera. Si el problema persiste, considere cambiar a un modelo diferente temporalmente.
503UNAVAILABLEEl servicio está temporalmente sobrecargado o no disponible.Intente de nuevo la solicitud después de una breve espera utilizando una estrategia de retirada exponencial. Si el problema persiste, informe del problema.

La API de Gemini incluye características de seguridad integradas para filtrar contenido potencialmente dañino. Estas características están diseñadas para ayudar a los desarrolladores a construir aplicaciones más seguras y responsables.

La API clasifica el contenido en cuatro categorías principales de daño:

  • 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.

Los desarrolladores pueden anular esta configuración predeterminada por solicitud pasando una lista de objetos SafetySetting al parámetro safety_settings. Esto permite un control granular sobre el umbral de bloqueo para cada categoría.

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 APIConfiguración en Google AI StudioDescripción
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/AEl umbral no está especificado; se utiliza el umbral predeterminado del modelo.
BLOCK_NONEBlock none (Bloquear ninguno)Nunca bloquear contenido, independientemente de la probabilidad de que sea inseguro. Debe usarse con extrema precaución.
BLOCK_ONLY_HIGHBlock few (Bloquear pocos)Bloquear solo cuando la probabilidad de contenido inseguro es HIGH.
BLOCK_MEDIUM_AND_ABOVEBlock some (Bloquear algunos)(Predeterminado para la mayoría de los modelos) Bloquear cuando la probabilidad de contenido inseguro es MEDIUM o HIGH.
BLOCK_LOW_AND_ABOVEBlock most (Bloquear la mayoría)Bloquear cuando la probabilidad de contenido inseguro es LOW, MEDIUM o HIGH.

El SDK proporciona una forma programática de descubrir los modelos disponibles y sus capacidades. Esto es útil para construir aplicaciones que pueden adaptarse a diferentes modelos o para verificar las capacidades de un modelo antes de usarlo.

El método client.models.list() devuelve un iterador sobre los modelos 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)

Esta funcionalidad también se puede utilizar para listar específicamente los modelos que han sido ajustados (fine-tuned) por el usuario, estableciendo query_base=False en la configuración de la solicitud de lista. Esto permite a las aplicaciones descubrir y utilizar dinámicamente modelos personalizados.


Parte 5: Validación del Entorno y Checklist Técnica

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

Para finalizar el aprovisionamiento de integraciones basadas en el SDK unificado google-genai en el tenant de Portelcore, valida el cumplimiento de los siguientes hitos técnicos:

  • He migrado todos los scripts del tenant de la librería obsoleta google-generativeai al nuevo estándar google-genai. ✓
  • Las llaves de API están gestionadas exclusivamente a través de la variable de entorno GOOGLE_API_KEY u ofuscadas en el gestor de secretos de Google Cloud en lugar de escribirse en texto plano. ✓
  • Se implementa un control de excepciones robusto (google.api_core.exceptions) para capturar códigos de estado 429 (Resource Exhausted) con políticas de reintento exponencial (exponential backoff). ✓
  • La temperatura y los umbrales de seguridad (safety_settings) están parametrizados formalmente de acuerdo con el caso de uso del dominio portelcore.com. ✓