O Gemma 3n foi lançado com entrada de áudio e otimizado para uso em dispositivos do dia a dia. Saiba mais

Esta página foi traduzida pela API Cloud Translation.

Executar o Gemma com o Hugging Face Transformers

Conferir no ai.google.dev

Executar no Google Colab

Executar no Kaggle

Abrir na Vertex AI

Ver o 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. 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 Transformers Python oferece uma API para acessar modelos de IA generativa pré-treinados, incluindo o Gemma. Para mais informações, consulte a documentação Transformers.

Configuração

Antes de iniciar este tutorial, conclua as seguintes etapas:

Para ter acesso ao Gemma, faça login no Hugging Face e selecione Aceitar licença 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 seu 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 o token de acesso do Hugging Face como um secret:

Abra a guia "Secrets" selecionando o ícone de chave no lado esquerdo da interface ou selecione Tools > Command palette, digite secrets e pressione Enter.
Selecione Adicionar novo secret para adicionar uma nova entrada de secret.
No campo Nome, use HF_TOKEN.
No campo Valor, insira o texto do seu token de acesso do Hugging Face.
No campo Acesso ao notebook, selecione a chave para ativar o acesso.

Depois de inserir o token de acesso como HF_TOKEN e o valor, você pode acessá-lo e defini-lo 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 do 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

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 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 por instruções (IT, na sigla em inglês), que normalmente tem it na string de ID do modelo. Usando o objeto pipeline, você especifica a variante do Gemma que 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 abaixo:

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 task para geração. Para mais informações sobre as configurações task disponíveis, consulte a documentação task() dos pipelines do Hugging Face. Use o tipo de dados torch.bfloat16 da tocha 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 ou "msu" para dispositivos iOS. Você também pode definir esse valor como 0 (zero) para especificar a primeira GPU no sistema. Para mais informações sobre o uso da classe Pipeline, consulte a documentação de pipelines do Hugging Face.

Gerar texto

Depois de carregar e configurar o modelo 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. Com um modelo de comando, você pode especificar a entrada de funções específicas, como user ou model, e é um formato necessário para gerenciar interações de chat com vários turnos com modelos do Gemma. O exemplo de código abaixo mostra como criar um modelo de comando para 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 modelos de tamanho 4B e mais recentes, é 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 pipeline do Transformer especificamente para uso com imagens. Em particular, você precisa 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
)

Gerar texto

Depois de configurar o modelo Gemma para processar a entrada 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

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 outras 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 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ária uma versão recente das bibliotecas Transformers para usar a entrada de áudio com o 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 transformador 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 abaixo:

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. Com um modelo de comando, você pode especificar a entrada de funções específicas, como user ou model, e é um formato necessário para gerenciar interações de chat com vários turnos com modelos do Gemma. O exemplo de código abaixo mostra como criar um modelo de comando para 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árias imagens no comando adicionando outras entradas "type": "audio", à lista content. Se você estiver solicitando dados de áudio, mas sem um modelo, use a sintaxe <audio_soft_token> no texto da solicitação.

Gerar 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 Gemma: