Menjalankan Gemma dengan Hugging Face Transformers

Lihat di ai.google.dev Jalankan di Google Colab Jalankan di Kaggle Buka di Vertex AI Lihat sumber di GitHub

Membuat teks, meringkas, dan menganalisis konten hanyalah beberapa tugas yang dapat Anda selesaikan dengan model terbuka Gemma. Tutorial ini menunjukkan cara mulai menjalankan Gemma menggunakan Hugging Face Transformers dengan input teks dan gambar untuk membuat konten teks. Library Python Transformers menyediakan API untuk mengakses model AI generatif terlatih, termasuk Gemma. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Transformers.

Penyiapan

Sebelum memulai tutorial ini, selesaikan langkah-langkah berikut:

  • Dapatkan akses ke Gemma dengan login ke Hugging Face dan memilih Acknowledge license untuk model Gemma.
  • Pilih runtime Colab dengan resource yang memadai untuk menjalankan ukuran model Gemma yang ingin Anda jalankan. Pelajari lebih lanjut.
  • Buat Token Akses Hugging Face dan tambahkan ke lingkungan Colab Anda.

Mengonfigurasi Token Akses

Tambahkan token akses Anda ke Colab untuk mengaktifkan download model Gemma dari situs Hugging Face. Gunakan fitur Secrets Colab untuk menyimpan token Anda dengan aman tanpa menambahkannya ke kode kerja Anda.

Untuk menambahkan Token Akses Hugging Face sebagai Secret:

  1. Buka tab rahasia dengan memilih ikon kunci di sisi kiri antarmuka, atau pilih Tools > Command pallete, ketik secrets, lalu tekan Enter.
  2. Pilih Tambahkan secret baru untuk menambahkan entri secret baru.
  3. Di kolom Name, masukkan HF_TOKEN.
  4. Di kolom Value, masukkan teks Token Akses Hugging Face Anda.
  5. Di kolom Akses notebook, pilih tombol untuk mengaktifkan akses.

Setelah memasukkan Token Akses sebagai HF_TOKEN dan nilai, Anda dapat mengakses dan menyetelnya dalam lingkungan notebook Colab menggunakan kode berikut:

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)

Menginstal paket Python

Instal library Hugging Face yang diperlukan untuk menjalankan model Gemma dan membuat permintaan.

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

Membuat teks dari teks

Memberi perintah model Gemma dengan teks untuk mendapatkan respons teks adalah cara paling sederhana untuk menggunakan Gemma dan berfungsi dengan hampir semua varian Gemma. Bagian ini menunjukkan cara menggunakan library Hugging Face Transformers untuk memuat dan mengonfigurasi model Gemma untuk pembuatan teks ke teks.

Memuat model

Gunakan library torch dan transformers untuk membuat instance class pipeline eksekusi model dengan Gemma. Saat menggunakan model untuk menghasilkan output atau mengikuti petunjuk, pilih model yang dioptimalkan untuk petunjuk (IT), yang biasanya memiliki it dalam string ID model. Dengan menggunakan objek pipeline, Anda menentukan varian Gemma yang ingin digunakan, jenis tugas yang ingin dilakukan, khususnya "text-generation" untuk pembuatan teks-ke-teks, seperti yang ditunjukkan dalam contoh kode berikut:

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 hanya mendukung beberapa setelan task untuk pembuatan. Untuk mengetahui informasi selengkapnya tentang setelan task yang tersedia, lihat dokumentasi task() Hugging Face Pipelines. Gunakan jenis data torch torch.bfloat16 untuk mengurangi presisi model dan resource komputasi yang diperlukan, tanpa memengaruhi kualitas output model secara signifikan. Untuk setelan device, Anda dapat menggunakan "cuda" untuk Colab, atau "msu" untuk perangkat iOS, atau cukup tetapkan ini ke 0 (nol) untuk menentukan GPU pertama di sistem Anda. Untuk mengetahui informasi selengkapnya tentang penggunaan class Pipeline, lihat dokumentasi Pipelines Hugging Face.

Menjalankan pembuatan teks

Setelah model Gemma dimuat dan dikonfigurasi dalam objek pipeline, Anda dapat mengirimkan perintah ke model. Contoh kode berikut menunjukkan permintaan dasar menggunakan parameter 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'}]

Menggunakan template perintah

Saat membuat konten dengan perintah yang lebih kompleks, gunakan template perintah untuk menyusun permintaan Anda. Template perintah memungkinkan Anda menentukan input dari peran tertentu, seperti user atau model, dan merupakan format yang diperlukan untuk mengelola interaksi chat multi-giliran dengan model Gemma. Contoh kode berikut menunjukkan cara membuat template perintah untuk 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)

Membuat teks dari data gambar

Mulai dari Gemma 3, untuk ukuran model 4B dan yang lebih tinggi, Anda dapat menggunakan data gambar sebagai bagian dari perintah Anda. Bagian ini menunjukkan cara menggunakan library Transformers untuk memuat dan mengonfigurasi model Gemma agar menggunakan data gambar dan input teks untuk menghasilkan output teks.

Memuat model

Saat memuat model Gemma untuk digunakan dengan data gambar, Anda mengonfigurasi instance Transformer pipeline secara khusus untuk digunakan dengan gambar. Khususnya, Anda harus memilih konfigurasi pipeline yang dapat menangani data visual dengan menyetel parameter task ke "image-text-to-text", seperti yang ditunjukkan dalam contoh kode berikut:

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
)

Menjalankan pembuatan teks

Setelah mengonfigurasi model Gemma untuk menangani input gambar dengan instance pipeline, Anda dapat mengirimkan perintah dengan gambar ke model. Gunakan token <start_of_image> untuk menambahkan gambar ke teks perintah Anda. Contoh kode berikut menunjukkan permintaan dasar menggunakan parameter 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'}]

Menggunakan template perintah

Saat membuat konten dengan perintah yang lebih kompleks, gunakan template perintah untuk menyusun permintaan Anda. Template perintah memungkinkan Anda menentukan input dari peran tertentu, seperti user atau model, dan merupakan format yang diperlukan untuk mengelola interaksi chat multi-giliran dengan model Gemma. Contoh kode berikut menunjukkan cara membuat template perintah untuk 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)

Anda dapat menyertakan beberapa gambar dalam perintah dengan menyertakan entri "type": "image", tambahan dalam daftar content.

Membuat teks dari data audio

Dengan Gemma 3n, Anda dapat menggunakan data audio sebagai bagian dari perintah Anda. Bagian ini menunjukkan cara menggunakan library Transformers untuk memuat dan mengonfigurasi model Gemma agar menggunakan data audio dan input teks untuk menghasilkan output teks.

Menginstal paket Python

Versi terbaru library Transformers diperlukan untuk menggunakan input audio dengan Gemma. Instal library Hugging Face untuk menjalankan model Gemma dan membuat permintaan dengan data audio seperti yang ditunjukkan di bawah.

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

Memuat model

Saat memuat model Gemma untuk digunakan dengan data audio, Anda mengonfigurasi instance Transformer secara khusus untuk digunakan dengan data audio. Secara khusus, Anda harus menentukan objek processor dan model menggunakan class AutoProcessor dan AutoModelForImageTextToText, seperti yang ditunjukkan dalam contoh kode berikut:

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

Menggunakan template perintah

Saat membuat konten dengan audio, gunakan template perintah untuk menyusun permintaan Anda. Template perintah memungkinkan Anda menentukan input dari peran tertentu, seperti user atau model, dan merupakan format yang diperlukan untuk mengelola interaksi chat multi-giliran dengan model Gemma. Contoh kode berikut menunjukkan cara membuat template perintah untuk Gemma dengan input data 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"},
        ]
    }
]

Anda dapat menyertakan beberapa file audio dalam perintah dengan menyertakan entri "type": "audio", tambahan dalam daftar content. Jika Anda memberikan perintah dengan data audio, tetapi tanpa template, gunakan sintaksis <audio_soft_token> dalam teks perintah Anda.

Menjalankan pembuatan teks

Setelah mengonfigurasi model Gemma dengan objek processor dan model, serta membuat perintah dengan data audio menggunakan template perintah, Anda dapat mengirim perintah untuk menghasilkan output. Contoh kode berikut menunjukkan permintaan menggunakan template chat, pembuatan output, decoding respons:

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

Langkah berikutnya

Bangun dan jelajahi lebih banyak dengan model Gemma: