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

Instalar pacotes Python

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

# Install Pytorch
%pip install torch

# Install a transformers
%pip install transformers

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 do Gemma que você quer usar e o tipo de tarefa que quer realizar, especificamente "any-to-any" para geração multimodal, conforme mostrado no exemplo de código a seguir:

from transformers import pipeline

MODEL_ID = "google/gemma-4-E2B-it"

pipe = pipeline(
    task="any-to-any",
    model=MODEL_ID,
    device_map="auto",
    dtype="auto"
)

config.json: 0.00B [00:00, ?B/s]
model.safetensors:   0%|          | 0.00/10.2G [00:00<?, ?B/s]
Loading weights:   0%|          | 0/2011 [00:00<?, ?it/s]
generation_config.json:   0%|          | 0.00/208 [00:00<?, ?B/s]
processor_config.json: 0.00B [00:00, ?B/s]
chat_template.jinja: 0.00B [00:00, ?B/s]
tokenizer_config.json: 0.00B [00:00, ?B/s]
tokenizer.json:   0%|          | 0.00/32.2M [00:00<?, ?B/s]

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. 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, você pode enviar comandos para ele. O exemplo de código a seguir mostra uma solicitação básica usando o parâmetro text:

pipe(text="<|turn>user\nroses are red<turn|>\n<|turn>model\n")

Both `max_new_tokens` (=256) and `max_length`(=20) seem to have been set. `max_new_tokens` will take precedence. Please refer to the documentation for more information. (https://huggingface.co/docs/transformers/main/en/main_classes/text_generation)
[{'input_text': '<|turn>user\nroses are red<turn|>\n<|turn>model\n',
  'generated_text': '<|turn>user\nroses are red<turn|>\n<|turn>model\nThat\'s a classic phrase, often used to highlight a contrast or a truth.\n\n**"Roses are red"** is a very popular, simple, and sweet arrangement.\n\nWhat would you like to do with this phrase? Are you looking for:\n\n1. **More rhymes or phrases?**\n2. **A continuation of a thought?**\n3. **Just appreciating the simplicity?**'}]

Usar um modelo de comando

Ao gerar conteúdo com comandos mais complexos, use um modelo para estruturar seu pedido. Um modelo de comando permite especificar entradas de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar conversas multiturno com modelos da Gemma. O exemplo de código a seguir mostra como criar um modelo de comando para a Gemma:

from transformers import GenerationConfig
config = GenerationConfig.from_pretrained(MODEL_ID)
config.max_new_tokens = 512
gen_kwargs = dict(generation_config=config)

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

pipe(messages, return_full_text=False, generate_kwargs=gen_kwargs)

[{'input_text': [{'role': 'system',
    'content': [{'type': 'text', 'text': 'You are a helpful assistant.'}]},
   {'role': 'user',
    'content': [{'type': 'text', 'text': 'Roses are red...'}]}],
  'generated_text': 'Roses are red,\nViolets are blue,\nHow lovely to see\nA beautiful view.'}]

Gerar texto com base em dados de imagem

A partir do 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 da Gemma para usar dados de imagem e entrada de texto para gerar saída de texto.

Usar um modelo de comando

Ao gerar conteúdo com comandos mais complexos, use um modelo para estruturar seu pedido. Um modelo de comando permite especificar entradas de papéis específicos, como user ou model, e é um formato obrigatório para gerenciar conversas multiturno com modelos da Gemma. O exemplo de código a seguir mostra como criar um modelo de comando para a Gemma:

from transformers import GenerationConfig
config = GenerationConfig.from_pretrained(MODEL_ID)
config.max_new_tokens = 512
gen_kwargs = dict(generation_config=config)

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"},
        ],
    },
]

pipe(text=messages, return_full_text=False, generate_kwargs=gen_kwargs)

[{'input_text': [{'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'}]}],
  'generated_text': " a platter of Indian food, likely a meal or an assortment of dishes.\n\nHere's a breakdown of what is visible:\n\n*   **Flatbread:** There is a large, golden-brown flatbread (possibly naan or roti) dominating the center of the platter.\n*   **Dips/Sides:** There are several small bowls containing various accompaniments:\n    *   A bowl of **yellow/mustard-colored dip** (perhaps a chutney or sauce).\n    *   A bowl of **white creamy dip** (like raita or yogurt sauce).\n    *   A portion of **white rice**.\n    *   Several bowls of **curries or sauces** in different colors:\n        *   An **orange/brown curry**.\n        *   A **deep yellow/orange sauce**.\n        *   A **green sauce** (likely a chutney).\n*   **Garnish/Side Item:** In the upper right corner, there appears to be some darker, textured items, possibly fried pieces or spices.\n*   **Platter:** The food is served on a metal platter.\n\nOverall, it looks like a traditional Indian meal setup featuring bread, rice, and various flavorful sauces/curries."}]

É 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 4 e 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.

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 conversas multiturno 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:

from transformers import GenerationConfig
config = GenerationConfig.from_pretrained(MODEL_ID)
config.max_new_tokens = 512
gen_kwargs = dict(generation_config=config)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe the following speech segment in its original language. Follow these specific instructions for formatting the answer:\n* Only output the transcription, with no newlines.\n* When transcribing numbers, write the digits, i.e. write 1.7 and not one point seven, and write 3 instead of three."},
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
        ]
    }
]

pipe(text=messages, return_full_text=False, generate_kwargs=gen_kwargs)

[{'input_text': [{'role': 'user',
    'content': [{'type': 'text',
      'text': 'Transcribe the following speech segment in its original language. Follow these specific instructions for formatting the answer:\n* Only output the transcription, with no newlines.\n* When transcribing numbers, write the digits, i.e. write 1.7 and not one point seven, and write 3 instead of three.'},
     {'type': 'audio',
      'audio': 'https://ai.google.dev/gemma/docs/audio/roses-are.wav'}]}],
  'generated_text': 'Roses are red, violets are blue.'}]

É possível incluir vários arquivos de áudio no comando adicionando mais entradas "type": "audio", à lista content.

Próximas etapas

Crie e descubra mais com os modelos do Gemma: