Executar o Gemma com o Hugging Face Transformers

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

Gerar texto, resumir e analisar conteúdo são apenas algumas das tarefas que você pode realizar com os modelos abertos do Gemma. Neste tutorial, mostramos como começar a executar a Gemma usando o Hugging Face Transformers com entradas de texto e imagem para gerar conteúdo de texto. A biblioteca Python Transformers oferece uma API para acessar modelos de IA generativa pré-treinados, incluindo o Gemma. Para mais informações, consulte a documentação do Transformers (em inglês).

Configuração

Antes de iniciar este tutorial, conclua as seguintes etapas:

  • Faça login no Hugging Face e selecione Confirmar licença para um modelo do Gemma.
  • Selecione um ambiente de execução do Colab com recursos suficientes para executar o tamanho do modelo Gemma que você quer usar. Saiba mais.
  • Gere um token de acesso do Hugging Face e adicione-o ao ambiente do Colab.

Configurar 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 em uso.

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 Ferramentas > Paleta de comandos, digite secrets e pressione Enter.
  2. Selecione Adicionar novo secret para adicionar uma nova entrada de secret.
  3. No campo Nome, use HF_TOKEN.
  4. No campo Valor, insira o texto do seu token de acesso do Hugging Face.
  5. No campo Acesso ao notebook, selecione a chave para ativar o acesso.

Depois de inserir o token de acesso como HF_TOKEN e valor, você pode acessar e definir no ambiente do notebook do Colab usando o seguinte código:

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

Pedir a um modelo Gemma para gerar uma resposta de texto é a maneira mais simples de usar o Gemma e funciona com quase todas as variantes. Esta seção mostra como usar a biblioteca Transformers do Hugging Face para carregar e configurar um modelo 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 a Gemma. Ao usar um modelo para gerar saída ou seguir instruções, selecione um modelo ajustado por instruções (IT, na sigla em inglês), que geralmente tem it na string de ID do modelo. Usando o objeto pipeline, especifique a variante da Gemma que você quer usar, o tipo de tarefa que 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 só oferece suporte a algumas configurações de task para geração. Para mais informações sobre as configurações de task disponíveis, consulte a documentação task() do Hugging Face Pipelines. Use o tipo de dados do PyTorch 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, use "cuda" para o Colab, "msu" para dispositivos iOS ou defina 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 de Pipelines do Hugging Face.

Executar a geração de texto

Depois de carregar e configurar o modelo do Gemma em um objeto pipeline, é possível enviar comandos para ele. 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 entradas de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar interações de chat em várias etapas com modelos da Gemma. O exemplo de código a seguir mostra como criar um modelo de comando para a 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 da Gemma 3, para tamanhos de modelo de 4B e superiores, é possível usar dados de imagem como parte do comando. Esta seção mostra como usar a biblioteca Transformers para carregar e configurar um modelo Gemma para usar dados de imagem e entrada de texto para gerar saída de texto.

Carregar modelo

Ao carregar um modelo Gemma para uso com dados de imagem, você configura a instância do Transformer pipeline especificamente para uso com imagens. Em particular, selecione 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 Gemma para processar entradas de imagem com uma instância pipeline, é possível 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 entradas de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar interações de chat em várias etapas com modelos da Gemma. O exemplo de código a seguir mostra como criar um modelo de comando para a 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 adicionando mais entradas "type": "image", à lista content.

Gerar texto com base em dados de áudio

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

Instalar pacotes Python

É necessário ter uma versão recente das bibliotecas Transformers para usar a entrada de áudio com a Gemma. Instale as bibliotecas do Hugging Face para executar o modelo 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 Gemma para uso com dados de áudio, você configura a instância do Transformer especificamente para uso com dados de áudio. Em particular, você precisa 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 entradas de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar interações de chat em várias etapas com modelos da Gemma. O exemplo de código a seguir mostra como criar um modelo de solicitação para a 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 adicionando mais entradas "type": "audio", à lista content. Se você estiver fazendo uma solicitação 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 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: