Cómo solicitar instrucciones con archivos multimedia


Ver en ai.google.dev Ejecutar en Google Colab Ver el código fuente en GitHub

La API de Gemini admite instrucciones con datos de texto, imagen, audio y video, también conocidas como instrucciones multimodales, lo que significa que puedes incluir esos tipos de archivos multimedia en tus instrucciones. Para archivos pequeños, puedes apuntar el modelo de Gemini a un archivo local cuando proporciones una instrucción. Sube archivos más grandes con la API de File antes de incluirlos en las instrucciones.

La API de File te permite almacenar hasta 20 GB de archivos por proyecto, y cada archivo no debe superar los 2 GB de tamaño. Los archivos se almacenan por 48 horas y se puede acceder a ellos con tu clave de API para generarlos dentro de ese período y no se pueden descargar desde la API. La API de Files está disponible sin costo en todas las regiones donde está disponible la API de Gemini.

La API de File controla las entradas que se pueden usar para generar contenido con model.generateContent o model.streamGenerateContent. Para obtener información sobre los formatos de archivo válidos (tipos de MIME) y los modelos compatibles, consulta Formatos de archivo admitidos.

En esta guía, se muestra cómo usar la API de File para subir archivos multimedia e incluirlos en una llamada GenerateContent a la API de Gemini. Para obtener más información, consulta las muestras de código.

Antes de comenzar: Configura tu proyecto y clave de API

Antes de llamar a la API de Gemini (o su API de archivos), debes configurar tu proyecto y la clave de API.

Instrucciones con imágenes

En este instructivo, subirás una imagen de muestra con la API de File y, luego, la usarás para generar contenido.

Sube un archivo de imagen

Consulta la sección Apéndice para obtener información sobre cómo subir tu propio archivo.

  1. Prepara una imagen de muestra para subirla:

      curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg

  2. Sube ese archivo con media.upload para poder acceder a él con otras llamadas a la API:

    sample_file = genai.upload_file(path="image.jpg",
                            display_name="Sample drawing")

print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")

response muestra que la imagen subida se almacena con el display_name especificado y tiene un uri para hacer referencia al archivo en las llamadas a la API de Gemini. Usa response para realizar un seguimiento de cómo se asignan los archivos subidos a los URI.

Según tu caso de uso, puedes almacenar los URIs en estructuras, como un dict o una base de datos.

Obtén los metadatos del archivo de imagen

Después de subir el archivo, puedes verificar que la API almacenó correctamente el archivo y obtener sus metadatos llamando a files.get a través del SDK.

Este método te permite obtener los metadatos de un archivo subido que está asociado con el proyecto de Google Cloud vinculado a tu clave de API. Solo los name (y, por extensión, uri) son únicos. Usa display_name para identificar archivos solo si tú administras la unicidad.

file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")

Genera contenido con el archivo de imagen que subiste

Después de subir la imagen, puedes realizar solicitudes GenerateContent que hagan referencia al uri en la respuesta (ya sea desde la carga del archivo o la obtención directa de los metadatos del archivo).

En este ejemplo, crearás una instrucción que comience con texto seguido de la referencia del URI del archivo subido:

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

response = model.generate_content([sample_file, "Describe the image with a creative description."])

Markdown(">" + response.text)

Borra el archivo de imagen

Los archivos se borran automáticamente después de 48 horas. También puedes borrarlos manualmente con files.delete a través del SDK.

genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')

Instrucciones con videos

En este instructivo, subirás un video de muestra con la API de File y, luego, lo usarás para generar contenido.

Subir un archivo de video

La API de Gemini acepta formatos de archivo de video directamente. En este ejemplo, se usa el corto "Big Buck Bunny".

"Big Buck Bunny" (c) está protegido por derechos de autor de 2008, Smoother Foundation / www.bigbuckbunny.org y está bajo la licencia Creative Commons Atribución 3.0.

Consulta la sección Apéndice para obtener información sobre cómo subir tu propio archivo.

  1. Prepara el archivo de video de muestra para subirlo:

    wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4

  2. Sube ese archivo con media.upload para poder acceder a él con otras llamadas a la API:

    video_file_name = "BigBuckBunny_320x180.mp4"

print(f"Uploading file...")
video_file = genai.upload_file(path=video_file_name)
print(f"Completed upload: {video_file.uri}")

Verifica el estado de carga del archivo de video

Verifica que la API haya subido correctamente el archivo de video. Para ello, llama al método files.get a través del SDK.

Los archivos de video tienen un campo State de la API de File. Cuando se suba un video, estará en un estado PROCESSING hasta que esté listo para la inferencia. Solo se pueden usar archivos ACTIVE para la inferencia de modelo.

import time

while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(10)
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

Obtén los metadatos del archivo de video

Para obtener los metadatos del archivo de video que subiste en cualquier momento, puedes llamar al método files.get a través del SDK.

Este método te permite obtener los metadatos de un archivo subido que está asociado con el proyecto de Google Cloud vinculado a tu clave de API. Solo los name (y, por extensión, uri) son únicos. Usa display_name para identificar archivos solo si tú administras la unicidad.

file = genai.get_file(name=video_file.name)
print(f"Retrieved file '{file.display_name}' as: {video_file.uri}")

Genera contenido con el archivo de video que subiste

Después de subir el video, puedes realizar solicitudes GenerateContent que hagan referencia al uri en la respuesta (ya sea desde subir el archivo, o bien obtener directamente sus metadatos).

Asegúrate de haber verificado el estado de carga del archivo de video (sección anterior) antes de ejecutar la inferencia en el video.

# Create the prompt.
prompt = "Describe this video."

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

# Make the LLM request.
print("Making LLM inference request...")
response = model.generate_content([video_file, prompt],
                                  request_options={"timeout": 600})
print(response.text)

Cómo borrar el archivo de video

Los archivos se borran automáticamente después de 48 horas. También puedes borrarlos manualmente con files.delete a través del SDK.

genai.delete_file(file_response.name)
print(f'Deleted file {file_response.uri}')

Formatos de archivo compatibles

Los modelos de Gemini admiten instrucciones con múltiples formatos de archivo. En esta sección, se explican las consideraciones sobre el uso de formatos multimedia generales para instrucciones, específicamente archivos de imagen, audio, video y texto sin formato. Puedes usar archivos multimedia para hacer instrucciones solo con versiones específicas del modelo, como se muestra en la siguiente tabla.

Modelo Imágenes Audio Video Texto sin formato
Gemini 1.5 Pro (versión 008 y posteriores) ✔ (3600 archivos de imagen máx.) ✔ ✔ ✔

Formatos de imagen

Puedes usar datos de imágenes para crear instrucciones con los modelos de Gemini 1.5. Cuando usas imágenes para las instrucciones, estas están sujetas a las siguientes limitaciones y requisitos:

  • Las imágenes deben estar en uno de los siguientes tipos de MIME de datos de imagen:
    • PNG: image/png
    • JPEG: image/jpeg
    • WEBP: image/webp
    • HEIC: image/heic
    • HEIF: image/heif
  • Un máximo de 3,600 imágenes para los modelos de Gemini 1.5.
  • No hay límites específicos para la cantidad de píxeles de una imagen. Sin embargo, las imágenes más grandes se reducen para adaptarse a una resolución máxima de 3072 x 3072 y, al mismo tiempo, conservar su relación de aspecto original.

Formatos de audio

Puedes usar datos de audio para crear instrucciones con los modelos de Gemini 1.5. Cuando usas audio para las instrucciones, estas están sujetas a las siguientes limitaciones y requisitos:

  • Los datos de audio son compatibles con los siguientes tipos de MIME de formato de audio comunes:
    • WAV: audio/WAV
    • MP3: audio/mp3
    • AIFF: audio/aiff
    • AAC: audio/aac
    • OGG Vorbis - audio/ogg
    • FLAC: audio/flac
  • La duración máxima admitida de datos de audio en un solo mensaje es de 9.5 horas.
  • Los archivos de audio se vuelven a muestrear a una resolución de datos de 16 Kbps, y se combinan varios canales de audio en un solo canal.
  • No hay un límite específico para la cantidad de archivos de audio en un solo mensaje. Sin embargo, la duración combinada total de todos los archivos de audio en un solo mensaje no puede superar las 9.5 horas.

Formatos de video

Puedes usar datos de video para crear instrucciones con los modelos de Gemini 1.5.

  • Los datos de video son compatibles con los siguientes tipos de MIME de formato de video comunes:

    • video/mp4
    • video/mpeg
    • video/movimiento
    • video/avi
    • video/x-flv
    • video/mpg
    • video/webm
    • video/WMV
    • video/3gpp

  • El servicio de la API de archivos muestra videos en imágenes a 1 fotograma por segundo (FPS) y puede estar sujeto a cambios para proporcionar la mejor calidad de inferencia. Las imágenes individuales consumen 258 tokens, sin importar la resolución ni la calidad.

Formatos de texto sin formato

La API de File admite la carga de archivos de texto sin formato con los siguientes tipos de MIME:

  • text/plain
  • text/html
  • text/css
  • text/javascript
  • application/x-javascript
  • texto/x-typescript
  • aplicación/x-typescript
  • texto/csv
  • texto/markdown
  • texto/x-python
  • application/x-python-code
  • application/json
  • text/xml
  • aplicación/rtf
  • texto/rtf

Para los archivos de texto sin formato con un tipo de MIME que no están en la lista, puedes intentar especificar uno de los tipos de MIME anteriores manualmente.

Apéndice: Cómo subir archivos a Colab

Este notebook usa la API de File con archivos que se descargaron de Internet. Si ejecutas esto en Colab y deseas usar tus propios archivos, primero debes subirlos a la instancia de Colab.

Primero, haz clic en Archivos en la barra lateral izquierda y, luego, en el botón Subir:

A continuación, subirás el archivo a la API de File. En el formulario de la celda de código que aparece a continuación, ingresa el nombre del archivo que subiste, proporciona un nombre visible adecuado para el archivo y, luego, ejecuta la celda.

my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}

my_file = genai.upload_file(path=my_filename,
                            display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")