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 lakukan dengan model terbuka Gemma. Tutorial ini menunjukkan cara mulai menjalankan Gemma menggunakan Hugging Face Transformers menggunakan input teks dan gambar untuk membuat konten teks. Library Python Transformers menyediakan API untuk mengakses model AI generatif terlatih, termasuk Gemma. Untuk informasi selengkapnya, lihat dokumentasi Transformer.

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 Secret Colab untuk menyimpan token dengan aman tanpa menambahkannya ke kode yang sedang berjalan.

Untuk menambahkan Token Akses Hugging Face sebagai Secret:

  1. Buka tab secret dengan memilih ikon kunci di sisi kiri antarmuka, atau pilih Tools > Command palette, 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 Notebook access, pilih tombol untuk mengaktifkan akses.

Setelah memasukkan Token Akses sebagai HF_TOKEN dan nilai, Anda dapat mengakses dan menetapkannya 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

Meminta model Gemma dengan teks untuk mendapatkan respons teks adalah cara termudah untuk menggunakan Gemma dan berfungsi dengan hampir semua varian Gemma. Bagian ini menunjukkan cara menggunakan pemuatan library Hugging Face Transformers 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 disesuaikan dengan 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 ke 0 (nol) untuk menentukan GPU pertama di sistem Anda. Untuk informasi selengkapnya tentang penggunaan class Pipeline, lihat dokumentasi Pipeline Hugging Face.

Menjalankan pembuatan teks

Setelah model Gemma dimuat dan dikonfigurasi dalam objek pipeline, Anda dapat mengirim 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. 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 pipeline Transformer secara khusus untuk digunakan dengan gambar. Secara khusus, Anda harus memilih konfigurasi pipeline yang dapat menangani data visual dengan menetapkan 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 mengirim 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. 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

Library Transformers versi terbaru 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 gambar dalam perintah dengan menyertakan entri "type": "audio", tambahan dalam daftar content. Jika Anda meminta 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

Buat dan jelajahi lebih lanjut dengan model Gemma: