Prompt com arquivos de mídia


Ver em ai.google.dev Executar no Google Colab Veja o código-fonte no GitHub

A API Gemini oferece suporte a comandos com texto, imagem, áudio e dados de vídeo, também conhecidos como comandos multimodais, o que significa que você pode incluir esses tipos de arquivos de mídia nos seus comandos. No caso de arquivos pequenos, aponte o modelo Gemini diretamente para um arquivo local ao fornecer um comando. Faça upload de arquivos maiores com a API File antes de incluí-los nas solicitações.

A API File permite armazenar até 20 GB de arquivos por projeto, sendo que cada um deles não excede 2 GB. Os arquivos são armazenados por 48 horas e podem ser acessados com sua chave de API para geração dentro desse período. Não é possível fazer o download da API. A API Files está disponível sem custos financeiros em todas as regiões em que a API Gemini está disponível.

A API File processa entradas que podem ser usadas para gerar conteúdo com model.generateContent ou model.streamGenerateContent. Para mais informações sobre formatos de arquivo válidos (tipos MIME) e modelos compatíveis, consulte Formatos de arquivo compatíveis.

Este guia mostra como usar a API File para fazer upload de arquivos de mídia e incluí-los em uma chamada GenerateContent para a API Gemini. Para saber mais, consulte os exemplos de código (link em inglês).

Antes de começar: configurar o projeto e a chave de API

Antes de chamar a API Gemini (ou a API File), você precisa configurar seu projeto e sua chave de API.

Comandos com imagens

Neste tutorial, você fará upload de uma imagem de amostra usando a API File e a usará para gerar conteúdo.

Fazer upload de um arquivo de imagem

Consulte a seção Apêndice para aprender a fazer upload do seu próprio arquivo.

  1. Prepare uma imagem de amostra para fazer upload:

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

  2. Faça upload desse arquivo usando media.upload para poder acessá-lo com outras chamadas de 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}")

O response mostra que a imagem enviada está armazenada com o display_name especificado e tem um uri para referenciar o arquivo nas chamadas da API Gemini. Use o response para rastrear como os arquivos enviados são mapeados para URIs.

Dependendo do caso de uso, é possível armazenar os URIs em estruturas como dict ou um banco de dados.

Receber os metadados do arquivo de imagem

Depois de fazer upload do arquivo, é possível verificar se a API armazenou o arquivo e receber os metadados chamando files.get pelo SDK.

Esse método permite receber os metadados de um arquivo enviado associado ao projeto do Google Cloud vinculado à sua chave de API. Somente o name (e, por extensão, o uri) são exclusivos. Use o display_name para identificar arquivos somente se você gerenciar a exclusividade por conta própria.

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

Gerar conteúdo usando o arquivo de imagem enviado

Depois de fazer upload da imagem, é possível fazer solicitações GenerateContent que fazem referência ao uri na resposta, seja fazendo upload do arquivo ou recebendo diretamente os metadados dele.

Neste exemplo, você cria um prompt que começa com texto seguido pela referência de URI do arquivo enviado:

# 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)

Excluir o arquivo de imagem

Os arquivos são excluídos automaticamente após 48 horas. Também é possível excluí-los manualmente usando files.delete pelo SDK.

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

Comandos com vídeos

Neste tutorial, você fará upload de um vídeo de amostra usando a API File e o usará para gerar conteúdo.

Fazer upload de um arquivo de vídeo

A API Gemini aceita formatos de arquivos de vídeo diretamente. Este exemplo usa o curta "Big Buck Bunny".

"Big Buck Bunny" é (c) direitos autorais de 2008, Liquider Foundation / www.bigbuckbunny.org e licenciado sob a Licença Creative Commons Atribuição 3.0.

Consulte a seção Apêndice para aprender a fazer upload do seu próprio arquivo.

  1. Prepare o arquivo do vídeo de amostra para upload:

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

  2. Faça upload desse arquivo usando media.upload para poder acessá-lo com outras chamadas de 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}")

Verificar o estado de envio do arquivo de vídeo

Verifique se a API fez upload do arquivo de vídeo chamando o método files.get pelo SDK.

Os arquivos de vídeo têm um campo State da API File. Quando um vídeo é enviado, ele fica no estado PROCESSING até estar pronto para inferência. Somente arquivos ACTIVE podem ser usados para inferência 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)

Encontrar os metadados do arquivo de vídeo

É possível receber os metadados do arquivo de vídeo enviado a qualquer momento chamando o método files.get pelo SDK.

Esse método permite receber os metadados de um arquivo enviado associado ao projeto do Google Cloud vinculado à sua chave de API. Somente o name (e, por extensão, o uri) são exclusivos. Use o display_name para identificar arquivos somente se você gerenciar a exclusividade por conta própria.

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

Gerar conteúdo usando o arquivo de vídeo enviado

Depois de enviar o vídeo, você pode fazer solicitações GenerateContent que referenciam o uri na resposta, seja enviando o arquivo ou recebendo diretamente os metadados dele.

Confira se você verificou o estado de upload do arquivo de vídeo (seção acima) antes de executar a inferência no vídeo.

# 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)

Excluir o arquivo de vídeo

Os arquivos são excluídos automaticamente após 48 horas. Também é possível excluí-los manualmente usando files.delete pelo SDK.

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

Formatos de arquivo compatíveis

Os modelos do Gemini oferecem suporte a comandos com vários formatos de arquivo. Nesta seção, explicamos considerações sobre o uso de formatos de mídia gerais para solicitações, especificamente arquivos de imagem, áudio, vídeo e texto simples. É possível usar arquivos de mídia para comandos apenas com versões de modelo específicas, conforme mostrado na tabela a seguir.

Modelo Imagens Áudio Vídeo Texto simples
Gemini 1.5 Pro (versão 008 e mais recentes) ✔ (máximo de 3.600 arquivos de imagem) ✔ ✔ ✔

Formatos de imagem

Você pode usar dados de imagem para comandos nos modelos Gemini 1.5. Ao usar imagens para comandos, elas estão sujeitas às seguintes limitações e requisitos:

  • As imagens precisam estar em um dos seguintes tipos MIME de dados de imagem:
    • PNG - image/png
    • JPEG - image/jpeg
    • WEBP - image/webp
    • HEIC - image/heic
    • HEIF - image/heif
  • Máximo de 3.600 imagens para os modelos Gemini 1.5.
  • Não há limites específicos para o número de pixels em uma imagem. No entanto, imagens maiores são reduzidas para caber em uma resolução máxima de 3.072 x 3.072, sem preservar a proporção original.

Formatos de áudio

Você pode usar dados de áudio para comandos nos modelos Gemini 1.5. Ao usar áudio para comandos, eles estão sujeitos a estas limitações e requisitos:

  • Os dados de áudio são compatíveis com os seguintes tipos MIME de formato de áudio comuns:
    • WAV: áudio/wav
    • MP3: áudio/mp3
    • AIFF: áudio/aiff
    • AAC: áudio/aac
    • OGG Vorbis - áudio/ogg
    • FLAC: áudio/flac
  • A duração máxima aceita de dados de áudio em um único comando é de 9,5 horas.
  • Os arquivos de áudio são redimensionados para uma resolução de dados de 16 Kbps, e vários canais de áudio são combinados em um único canal.
  • Não há um limite específico para o número de arquivos de áudio em um comando.No entanto, a duração total combinada de todos os arquivos de áudio em um comando não pode exceder 9,5 horas.

Formatos de vídeo

Você pode usar dados de vídeo para comandos nos modelos Gemini 1.5.

  • Os dados de vídeo são compatíveis com os seguintes tipos MIME de formato de vídeo comuns:

    • video/mp4
    • video/mpeg
    • vídeo/mover
    • vídeo/avi
    • video/x-flv
    • vídeo/mpg
    • vídeo/webm
    • vídeo/wmv
    • vídeo/3gpp

  • O serviço da API File fornece amostras de vídeos em imagens a 1 quadro por segundo (QPS) e pode estar sujeito a alterações para oferecer a melhor qualidade de inferência. Imagens individuais ocupam 258 tokens, independentemente da resolução e da qualidade.

Formatos de texto simples

A API File é compatível com o upload de arquivos de texto simples com os seguintes tipos MIME:

  • text/plain
  • text/html
  • text/css
  • text/javascript
  • application/x-javascript
  • texto/x-typescript
  • aplicativo/x-typescript
  • text/csv
  • texto/marcação
  • texto/x-python
  • application/x-python-code
  • application/json
  • text/xml
  • aplicativo/rtf
  • texto/rtf

Para arquivos de texto simples com um tipo MIME que não esteja na lista, tente especificar manualmente um dos tipos MIME acima.

Apêndice: como fazer upload de arquivos para o Colab

Este notebook usa a API File com arquivos que foram transferidos por download da Internet. Se você estiver executando isso no Colab e quiser usar seus próprios arquivos, primeiro faça upload deles para a instância do Colab.

Primeiro, clique em Arquivos na barra lateral esquerda e, em seguida, clique no botão Fazer upload:

Em seguida, você fará upload desse arquivo para a API File. No formulário da célula de código abaixo, insira o nome do arquivo enviado e forneça um nome de exibição adequado. Em seguida, execute a célula.

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