Executar o Gemma com o Hugging Face Transformers

Conferir em ai.google.dev Executar no Google Colab Executar no Kaggle Abrir na Vertex AI Conferir o código-fonte no GitHub

Gerar texto, resumir e analisar conteúdo são apenas algumas das tarefas que podem ser realizadas com modelos abertos do Gemma. Este tutorial mostra como começar a executar o Gemma usando o Hugging Face Transformers com entrada de texto e imagem para gerar conteúdo de texto. A biblioteca Python Transformers fornece uma API para acessar modelos de IA generativa pré-treinados, incluindo o Gemma. Para mais informações, consulte a documentação do Transformers.

Configuração

Antes de iniciar este tutorial, conclua as seguintes etapas:

  • Acesse o Gemma fazendo login no Hugging Face e selecionando Acknowledge license para um modelo do Gemma.
  • Selecione um ambiente de execução do Colab com recursos suficientes para executar o tamanho do modelo do Gemma que você quer usar. Saiba mais.
  • Gere um token de acesso do Hugging Face e adicione-o ao ambiente do Colab.

Configurar o token de acesso

Adicione seu token de acesso ao Colab para permitir o download de modelos do Gemma no site do Hugging Face. Use o recurso Secrets do Colab para salvar seu token com segurança sem adicioná-lo ao código de trabalho.

Para adicionar seu token de acesso do Hugging Face como um secret:

  1. Abra a guia "Secrets" selecionando o ícone de chave no lado esquerdo da interface ou selecione Tools > Command pallete , digite secrets e pressione Enter.
  2. Selecione Add new secret para adicionar uma nova entrada de secret.
  3. No campo Name, insira HF_TOKEN.
  4. No campo Value, insira o texto do seu token de acesso do Hugging Face.
  5. No campo Notebook access, selecione a opção para ativar o acesso.

Depois de inserir o token de acesso como HF_TOKEN e o valor, você poderá acessá-lo e defini-lo no ambiente do notebook do Colab usando o código a seguir:

from google.colab import userdata
from huggingface_hub import login

# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)

Instalar pacotes Python

Instale as bibliotecas do Hugging Face necessárias para executar o modelo do Gemma e fazer solicitações.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0"

# Install a transformers version that supports Gemma 3 (>= 4.51.3)
%pip install "transformers>=4.51.3"

Gerar texto com base em texto

Solicitar um modelo do Gemma com texto para receber uma resposta de texto é a maneira mais simples de usar o Gemma e funciona com quase todas as variantes do Gemma. Esta seção mostra como usar a biblioteca Hugging Face Transformers para carregar e configurar um modelo do Gemma para geração de texto.

Carregar modelo

Use as bibliotecas torch e transformers para criar uma instância de uma classe pipeline de execução de modelo com o Gemma. Ao usar um modelo para gerar saída ou seguir instruções, selecione um modelo ajustado (IT, na sigla em inglês), que normalmente tem it na string de ID do modelo. Usando o objeto pipeline, especifique a variante do Gemma que você quer usar, o tipo de tarefa que você quer realizar, especificamente "text-generation" para geração de texto para texto, conforme mostrado no exemplo de código a seguir:

import torch
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="google/gemma-3-4b-it",
    device=0, # "cuda" for Colab, "msu" for iOS devices
    torch_dtype=torch.bfloat16
)

O Gemma oferece suporte apenas a algumas configurações de task para geração. Para mais informações sobre as configurações task disponíveis, consulte a documentação da tarefa Pipelines do Hugging Face (link em inglês). Use o tipo de dados do torch torch.bfloat16 para reduzir a precisão do modelo e os recursos de computação necessários, sem afetar significativamente a qualidade da saída do modelo. Para a configuração device, você pode usar "cuda" para o Colab ou "msu" para dispositivos iOS ou apenas definir como 0 (zero) para especificar a primeira GPU no seu sistema. Para mais informações sobre como usar a classe Pipeline, consulte a documentação do Hugging Face Pipelines (link em inglês).

Executar a geração de texto

Depois de carregar e configurar o modelo do Gemma em um objeto pipeline, você pode enviar comandos ao modelo. O exemplo de código a seguir mostra uma solicitação básica usando o parâmetro text_inputs:

pipeline(text_inputs="roses are red")

[{'generated_text': 'roses are red, violets are blue, \ni love you more than you ever knew.\n\n**Explanation'}]

Usar um modelo de comando

Ao gerar conteúdo com comandos mais complexos, use um modelo de comando para estruturar sua solicitação. Um modelo de comando permite especificar a entrada de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar interações de conversa multiturno com modelos do Gemma. O exemplo de código a seguir mostra como construir um modelo de comando para o Gemma:

messages = [
    [
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."},]
        },
        {
            "role": "user",
            "content": [{"type": "text", "text": "Roses are red..."},]
        },
    ],
]

pipeline(messages, max_new_tokens=50)

Gerar texto com base em dados de imagem

A partir do Gemma 3, para tamanhos de modelo de 4B e mais, você pode usar dados de imagem como parte do comando. Esta seção mostra como usar a biblioteca Transformers para carregar e configurar um modelo do Gemma para usar dados de imagem e entrada de texto para gerar saída de texto.

Carregar modelo

Ao carregar um modelo do Gemma para uso com dados de imagem, você configura a instância pipeline do Transformer especificamente para uso com imagens. Em particular, é necessário selecionar uma configuração de pipeline que possa processar dados visuais definindo o parâmetro task como "image-text-to-text", conforme mostrado no exemplo de código a seguir:

import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text", # required for image input
    model="google/gemma-3-4b-it",
    device=0,
    torch_dtype=torch.bfloat16
)

Executar a geração de texto

Depois de configurar o modelo do Gemma para processar a entrada de imagem com uma instância pipeline, você pode enviar comandos com imagens para o modelo. Use o token <start_of_image> para adicionar a imagem ao texto do comando. O exemplo de código a seguir mostra uma solicitação básica usando o parâmetro pipeline:

pipeline(
    "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg",
    text="<start_of_image> What is shown in this image?"
)

[{'input_text': '<start_of_image> What is shown in this image?',
  'generated_text': '<start_of_image> What is shown in this image?\n\nThis image showcases a traditional Indian Thali. A Thali is a platter that contains a variety'}]

Usar um modelo de comando

Ao gerar conteúdo com comandos mais complexos, use um modelo de comando para estruturar sua solicitação. Um modelo de comando permite especificar a entrada de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar interações de conversa multiturno com modelos do Gemma. O exemplo de código a seguir mostra como construir um modelo de comando para o Gemma:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "This image shows"},
        ],
    },
]

pipeline(text=messages, max_new_tokens=50, return_full_text=False)

É possível incluir várias imagens no comando, incluindo outras entradas "type": "image", na lista content.

Gerar texto com base em dados de áudio

Com Gemma 3n, você pode usar dados de áudio como parte do comando. Esta seção mostra como usar a biblioteca Transformers para carregar e configurar um modelo do Gemma para usar dados de áudio e entrada de texto para gerar saída de texto.

Instalar pacotes Python

Uma versão recente das bibliotecas Transformers é necessária para usar a entrada de áudio com o Gemma. Instale as bibliotecas do Hugging Face para executar o modelo do Gemma e fazer solicitações com dados de áudio, conforme mostrado abaixo.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0"

# Install a transformers version that supports Gemma 3n (>= 4.53)
%pip install "transformers>=4.53.0"

Carregar modelo

Ao carregar um modelo do Gemma para uso com dados de áudio, você configura a instância do Transformer especificamente para uso com dados de áudio. Em particular, é necessário definir um objeto processor e model usando as classes AutoProcessor e AutoModelForImageTextToText, conforme mostrado no exemplo de código a seguir:

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

GEMMA_MODEL_ID = "google/gemma-3n-E4B-it"

processor = AutoProcessor.from_pretrained(GEMMA_MODEL_ID, device_map="auto")
model = AutoModelForImageTextToText.from_pretrained(
            GEMMA_MODEL_ID, torch_dtype="auto", device_map="auto")

Usar um modelo de comando

Ao gerar conteúdo com áudio, use um modelo de comando para estruturar sua solicitação. Um modelo de comando permite especificar a entrada de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar interações de conversa multiturno com modelos do Gemma. O exemplo de código a seguir mostra como construir um modelo de comando para o Gemma com entrada de dados de áudio:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
            {"type": "text", "text": "Transcribe this audio and complete the statement"},
        ]
    }
]

É possível incluir vários arquivos de áudio no comando, incluindo outras entradas "type": "audio", na lista content. Se você estiver solicitando com dados de áudio, mas sem um modelo, use a sintaxe <audio_soft_token> no texto do comando.

Executar a geração de texto

Depois de configurar o modelo do Gemma com um objeto processor e model e criar um comando com dados de áudio usando um modelo de comando, você pode enviar o comando para gerar a saída. O exemplo de código a seguir mostra uma solicitação usando um modelo de chat, geração de saída e decodificação da resposta:

input_ids = processor.apply_chat_template(
        messages,
        add_generation_prompt=True,
        tokenize=True, return_dict=True,
        return_tensors="pt",
)
input_ids = input_ids.to(model.device, dtype=model.dtype)

# Generate output from the model
outputs = model.generate(**input_ids, max_new_tokens=128)

# decode and print the output as text
text = processor.batch_decode(
    outputs,
    skip_special_tokens=False,
    clean_up_tokenization_spaces=False
)
print(text[0])

Próximas etapas

Crie e explore mais com os modelos do Gemma: