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.
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.
1.2. Instalación y Entorno
Sección titulada «1.2. Instalación y Entorno»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:
# 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»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 :
- Navegue a(https://ai.google.dev/) e inicie sesión con una cuenta de Google.
- Haga clic en “Get API key” (Obtener clave de API).
- Elija crear la clave de API en un proyecto de Google Cloud nuevo o existente.
- 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_KEYcon 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:
- Seleccionar o crear un proyecto de Google Cloud.
- Asegurarse de que la facturación esté habilitada para el proyecto.
- 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 loginCuando 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 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. 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é 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
vertexaienTruey 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 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. El cliente detectará estas variables y se configurará para usar el backend de 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()
La siguiente tabla resume estos métodos para una referencia 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 cuadernos y pruebas rápidas. Evitar en código de producción. |
| API de Desarrollador con Var. de Entorno | client = genai.Client() | GOOGLE_API_KEY o GEMINI_API_KEY | Método preferido para código de aplicación limpio y 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 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ó anteriormenteresponse = 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: unrole(generalmente ‘user’ para la entrada o ‘model’ para la salida) y una lista departs.types.Part: Representa una pieza de datos dentro de un objetoContent. 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 unUserContentcon una solaPartde texto. - Una lista de cadenas:
contents=['Pregunta 1', 'Pregunta 2']se convierte en un únicoUserContentque contiene dosPartde texto. - Un objeto
types.Part: Permite un control más detallado, como especificar datos de imagen. - Un objeto
types.Contentcompletamente 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 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.
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:
- 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 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 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. 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 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)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ámetro | Descripción | Rango | Efecto en la Salida |
|---|---|---|---|
temperature | Controla la aleatoriedad de la selección 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) | Genera múltiples respuestas posibles para la misma indicación. Útil para ofrecer opciones al usuario. |
max_output_tokens | El número máximo de tokens que se pueden generar en la respuesta. | Entero | Limita la longitud de la salida. Esencial para controlar los costos y la latencia. |
stop_sequences | Una 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. |
seed | Semilla aleatoria para la generación. | Entero | Proporcionar 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.
3.2. Trabajando con Imágenes
Sección titulada «3.2. Trabajando con Imágenes»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 atypes.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 una URL: Se puede usar una biblioteca como
requestspara obtener los bytes de la imagen de una URL y luego pasarlos de la misma manera.
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 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:
- 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. - Indicar: Se pasa el objeto de archivo devuelto directamente en la lista
contentsde una llamada agenerate_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 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. La API también proporciona métodos para gestionar estos archivos, como get(), list() y delete().
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. 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:
- 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.
El siguiente ejemplo muestra cómo cargar un archivo de audio y pedirle al modelo que lo transcriba.
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. 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:
- 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.
- 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
Partde tipofunction_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 untypes.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 proporciona la información crítica necesaria para construir aplicaciones robustas, fiables y responsables.
4.1. Manejo Robusto de Errores
Sección titulada «4.1. Manejo Robusto de Errores»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_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}")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 HTTP | Estado | Causa Probable | Acción Recomendada en Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | El 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. |
| 403 | PERMISSION_DENIED | La 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. |
| 429 | RESOURCE_EXHAUSTED | Se 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. |
| 500 | INTERNAL | Ocurrió 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. |
| 503 | UNAVAILABLE | El 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. |
4.2. Gestión de la Seguridad del Contenido
Sección titulada «4.2. Gestión de la Seguridad del Contenido»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 API | Configuración en Google AI Studio | Descripción |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | El umbral no está especificado; se utiliza el umbral predeterminado del modelo. |
BLOCK_NONE | Block none (Bloquear ninguno) | Nunca bloquear contenido, independientemente de la probabilidad de que sea inseguro. Debe usarse con extrema precaución. |
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) | (Predeterminado para la mayoría de los modelos) Bloquear cuando la probabilidad de contenido inseguro es MEDIUM o HIGH. |
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»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 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 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-generativeaial nuevo estándargoogle-genai. ✓ - Las llaves de API están gestionadas exclusivamente a través de la variable de entorno
GOOGLE_API_KEYu 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 dominioportelcore.com. ✓

