Ejecuta Gemma con Transformers de Hugging Face

Ver en ai.google.dev Ejecutar en Google Colab Ejecutar en Kaggle Abrir en Vertex AI Ver código fuente en GitHub

Generar texto, resumir y analizar contenido son solo algunas de las tareas que puedes realizar con los modelos abiertos de Gemma. En este instructivo, se muestra cómo comenzar a ejecutar Gemma con Hugging Face Transformers usando texto y una imagen como entrada para generar contenido de texto. La biblioteca de Transformers de Python proporciona una API para acceder a modelos de IA generativa entrenados previamente, incluido Gemma. Para obtener más información, consulta la documentación de Transformers.

Configuración

Antes de comenzar este instructivo, completa los siguientes pasos:

  • Para acceder a Gemma, ingresa a Hugging Face y selecciona Acknowledge license para un modelo de Gemma.
  • Selecciona un entorno de ejecución de Colab con recursos suficientes para ejecutar el tamaño del modelo de Gemma que desees. Obtén más información.
  • Genera un token de acceso de Hugging Face y agrégalo a tu entorno de Colab.

Configura el token de acceso

Agrega tu token de acceso a Colab para habilitar la descarga de modelos de Gemma desde el sitio web de Hugging Face. Usa la función Secrets de Colab para guardar tu token de forma segura sin agregarlo a tu código de trabajo.

Sigue estos pasos para agregar tu token de acceso de Hugging Face como un Secret:

  1. Para abrir la pestaña de secretos, selecciona el ícono de llave en el lado izquierdo de la interfaz o selecciona Tools > Command palette, escribe secrets y presiona Intro.
  2. Selecciona Agregar secreto nuevo para agregar una entrada de secreto nueva.
  3. En el campo Nombre, ingresa HF_TOKEN.
  4. En el campo Value, ingresa el texto de tu token de acceso de Hugging Face.
  5. En el campo Acceso al notebook, selecciona el interruptor para habilitar el acceso.

Una vez que ingreses tu token de acceso como HF_TOKEN y valor, podrás acceder a él y configurarlo en tu entorno de notebook de Colab con el siguiente 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)

Instala paquetes de Python

Instala las bibliotecas de Hugging Face necesarias para ejecutar el modelo de Gemma y realizar solicitudes.

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

Genera texto a partir de texto

La forma más sencilla de usar Gemma es solicitarle a un modelo de Gemma que genere una respuesta de texto. Esto funciona con casi todas las variantes de Gemma. En esta sección, se muestra cómo usar la biblioteca de Hugging Face Transformers para cargar y configurar un modelo de Gemma para la generación de texto a texto.

Carga el modelo

Usa las bibliotecas torch y transformers para crear una instancia de una clase pipeline de ejecución del modelo con Gemma. Cuando uses un modelo para generar resultados o seguir instrucciones, selecciona un modelo ajustado para instrucciones (IT), que suele tener it en la cadena de ID del modelo. Con el objeto pipeline, especificas la variante de Gemma que deseas usar, el tipo de tarea que deseas realizar, específicamente "text-generation" para la generación de texto a texto, como se muestra en el siguiente ejemplo de código:

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
)

Gemma solo admite algunos parámetros de configuración de task para la generación. Para obtener más información sobre la configuración de task disponible, consulta la documentación de task() de Hugging Face Pipelines. Usa el tipo de datos de Torch torch.bfloat16 para reducir la precisión del modelo y los recursos de procesamiento necesarios, sin afectar de manera significativa la calidad del resultado del modelo. Para el parámetro de configuración device, puedes usar "cuda" para Colab, "msu" para dispositivos iOS o simplemente establecerlo en 0 (cero) para especificar la primera GPU de tu sistema. Para obtener más información sobre el uso de la clase Pipeline, consulta la documentación de Pipelines de Hugging Face.

Ejecuta la generación de texto

Una vez que hayas cargado y configurado el modelo de Gemma en un objeto pipeline, podrás enviarle instrucciones. En el siguiente ejemplo de código, se muestra una solicitud básica con el 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'}]

Usa una plantilla de instrucción

Cuando generes contenido con instrucciones más complejas, usa una plantilla de instrucción para estructurar tu solicitud. Una plantilla de instrucción te permite especificar la entrada de roles específicos, como user o model, y es un formato obligatorio para administrar interacciones de chat de varios turnos con los modelos de Gemma. En el siguiente ejemplo de código, se muestra cómo construir una plantilla de instrucciones 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)

Genera texto a partir de datos de imágenes

A partir de Gemma 3, para tamaños de modelos de 4B y superiores, puedes usar datos de imágenes como parte de tu instrucción. En esta sección, se muestra cómo usar la biblioteca de Transformers para cargar y configurar un modelo de Gemma que use datos de imágenes y texto de entrada para generar texto de salida.

Carga el modelo

Cuando cargas un modelo de Gemma para usarlo con datos de imágenes, configuras la instancia de Transformer pipeline específicamente para usarla con imágenes. En particular, debes seleccionar una configuración de canalización que pueda controlar datos visuales estableciendo el parámetro task en "image-text-to-text", como se muestra en el siguiente ejemplo de código:

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
)

Ejecuta la generación de texto

Una vez que hayas configurado el modelo de Gemma para que controle la entrada de imágenes con una instancia de pipeline, puedes enviarle instrucciones con imágenes. Usa el token <start_of_image> para agregar la imagen al texto de tu instrucción. En el siguiente ejemplo de código, se muestra una solicitud básica con el 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'}]

Usa una plantilla de instrucción

Cuando generes contenido con instrucciones más complejas, usa una plantilla de instrucción para estructurar tu solicitud. Una plantilla de instrucción te permite especificar la entrada de roles específicos, como user o model, y es un formato obligatorio para administrar interacciones de chat de varios turnos con los modelos de Gemma. En el siguiente ejemplo de código, se muestra cómo construir una plantilla de instrucciones para 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)

Puedes incluir varias imágenes en tu instrucción si agregas entradas "type": "image", adicionales a la lista content.

Genera texto a partir de datos de audio

Con Gemma 3n, puedes usar datos de audio como parte de tu instrucción. En esta sección, se muestra cómo usar la biblioteca de Transformers para cargar y configurar un modelo de Gemma que use datos de audio y texto de entrada para generar texto de salida.

Instala paquetes de Python

Se requiere una versión reciente de las bibliotecas de Transformers para usar la entrada de audio con Gemma. Instala las bibliotecas de Hugging Face para ejecutar el modelo de Gemma y realizar solicitudes con datos de audio, como se muestra a continuación.

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

Carga el modelo

Cuando cargas un modelo de Gemma para usarlo con datos de audio, configuras la instancia de Transformer específicamente para usarla con datos de audio. En particular, debes definir un objeto processor y model con las clases AutoProcessor y AutoModelForImageTextToText, como se muestra en el siguiente ejemplo de código:

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

Usa una plantilla de instrucción

Cuando generes contenido con audio, usa una plantilla de instrucciones para estructurar tu solicitud. Una plantilla de instrucción te permite especificar la entrada de roles específicos, como user o model, y es un formato obligatorio para administrar interacciones de chat de varios turnos con los modelos de Gemma. En el siguiente ejemplo de código, se muestra cómo construir una plantilla de instrucción para Gemma con datos de audio como entrada:

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

Puedes incluir varios archivos de audio en tu instrucción agregando entradas "type": "audio", adicionales a la lista content. Si usas datos de audio en la instrucción, pero no usas una plantilla, usa la sintaxis <audio_soft_token> en el texto de la instrucción.

Ejecuta la generación de texto

Una vez que hayas configurado el modelo de Gemma con un objeto processor y model, y hayas creado una instrucción con datos de audio usando una plantilla de instrucción, podrás enviar la instrucción para generar la salida. En el siguiente ejemplo de código, se muestra una solicitud que usa una plantilla de chat, la generación de resultados y la decodificación de la respuesta:

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óximos pasos

Crea y explora más con los modelos de Gemma: