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 entradas de texto e imágenes para generar contenido de texto. La biblioteca de Python de Transformers proporciona una API para acceder a modelos de IA generativa previamente entrenados, incluido Gemma. Para obtener más información, consulta la documentación de Transformers.

Configuración

Antes de comenzar con este instructivo, completa los siguientes pasos:

  • Para obtener acceso a Gemma, accede 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 deseas ejecutar. 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.

Para agregar tu token de acceso de Hugging Face como Secret, sigue estos pasos:

  1. Para abrir la pestaña 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 nueva entrada de secreto.
  3. En el campo Nombre, ingresa HF_TOKEN.
  4. En el campo Valor, ingresa el texto de tu token de acceso de Hugging Face.
  5. En el campo Acceso a Notebook, selecciona el interruptor para habilitar el acceso.

Una vez que hayas ingresado tu token de acceso como HF_TOKEN y valor, puedes acceder a él y configurarlo en el entorno de tu 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

Solicitar un modelo de Gemma con texto para obtener una respuesta de texto es la forma más sencilla de usar Gemma y funciona con casi todas las variantes de Gemma. En esta sección, se muestra cómo usar la carga de la biblioteca de Hugging Face Transformers 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 de modelos con Gemma. Cuando uses un modelo para generar resultados o seguir instrucciones, selecciona un modelo ajustado por 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 antorcha 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 o "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 canalizaciones 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 enviar instrucciones al modelo. En el siguiente código de ejemplo, 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 entradas de roles específicos, como user o model, y es un formato obligatorio para administrar interacciones de chat de varios turnos con modelos de Gemma. En el siguiente ejemplo de código, se muestra cómo crear una plantilla de instrucción 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 los tamaños de modelo 4B y superiores, puedes usar datos de imagen como parte de la instrucción. En esta sección, se muestra cómo usar la biblioteca de Transformers para cargar y configurar un modelo de Gemma para usar datos de imagen y entrada de texto para generar un resultado de texto.

Carga el modelo

Cuando cargas un modelo de Gemma para usarlo con datos de imágenes, configuras la instancia de pipeline de Transformer específicamente para usarlo con imágenes. En particular, debes seleccionar una configuración de canalización que pueda controlar los datos visuales. Para ello, establece el parámetro task en "image-text-to-text", como se muestra en la siguiente muestra 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 controlar la entrada de imágenes con una instancia de pipeline, puedes enviar instrucciones con imágenes al modelo. Usa el token <start_of_image> para agregar la imagen al texto de la instrucción. En el siguiente código de ejemplo, 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 entradas de roles específicos, como user o model, y es un formato obligatorio para administrar interacciones de chat de varios turnos con modelos de Gemma. En el siguiente ejemplo de código, se muestra cómo crear una plantilla de instrucción 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)

Para incluir varias imágenes en tu instrucción, incluye entradas "type": "image", adicionales en 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 entradas de texto para generar salidas de texto.

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 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 usarlo 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 instrucción para estructurar tu solicitud. Una plantilla de instrucción te permite especificar entradas de roles específicos, como user o model, y es un formato obligatorio para administrar interacciones de chat de varios turnos con modelos de Gemma. En el siguiente ejemplo de código, se muestra cómo crear una plantilla de instrucción para Gemma con entrada de datos de audio:

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

Para incluir varias imágenes en tu instrucción, incluye entradas "type": "audio", adicionales en la lista content. Si proporcionas instrucciones con datos de audio, pero sin una plantilla, usa la sintaxis <audio_soft_token> en el texto de la instrucción.

Ejecuta la generación de texto

Una vez que tengas el modelo de Gemma configurado con un objeto processor y model, y hayas creado una instrucción con datos de audio mediante una plantilla de instrucción, puedes enviar la instrucción para generar un resultado. En el siguiente código de ejemplo, 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

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