Ejecuta Gemma con Transformers de Hugging Face

Ver en ai.google.dev Ejecutar en Google Colab Ejecutar en Kaggle Abrir en Vertex AI Ver el 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 previamente entrenados, incluido Gemma. Para obtener más información, consulta la documentación de Transformers.

Instala paquetes de Python

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

# Install Pytorch
%pip install torch

# Install a transformers
%pip install transformers

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 "any-to-any" para la generación multimodal, como se muestra en el siguiente ejemplo de código:

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]

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. 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 código de ejemplo, se muestra una solicitud básica con el 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?**'}]

Cómo usar 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 instrucciones te permite especificar la entrada de roles específicos, como user o model, y es un formato obligatorio para administrar las 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:

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.'}]

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.

Cómo usar 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 instrucciones te permite especificar la entrada de roles específicos, como user o model, y es un formato obligatorio para administrar las 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:

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

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 4 y 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 como entrada para generar texto como salida.

Cómo usar una plantilla de instrucción

Cuando generes contenido con audio, usa una plantilla de instrucciones para estructurar tu solicitud. Una plantilla de instrucciones te permite especificar la entrada de roles específicos, como user o model, y es un formato obligatorio para administrar las 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:

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.'}]

Puedes incluir varios archivos de audio en tu instrucción agregando entradas "type": "audio", adicionales en la lista content.

Próximos pasos

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