Menyesuaikan Gemma untuk Tugas Visi menggunakan Hugging Face Transformers dan QLoRA

Panduan ini memandu Anda cara menyesuaikan Gemma pada set data gambar dan teks kustom untuk tugas visi (membuat deskripsi produk) menggunakan Transformer dan TRL Hugging Face. Anda akan mempelajari:

  • Apa yang dimaksud dengan Quantized Low-Rank Adaptation (QLoRA)
  • Menyiapkan lingkungan pengembangan
  • Membuat dan menyiapkan set data penyesuaian halus untuk tugas visi
  • Menyesuaikan Gemma menggunakan TRL dan SFTTrainer
  • Uji Inferensi Model dan buat deskripsi produk dari gambar dan teks.

Apa yang dimaksud dengan Quantized Low-Rank Adaptation (QLoRA)

Panduan ini menunjukkan penggunaan Quantized Low-Rank Adaptation (QLoRA), yang muncul sebagai metode populer untuk menyesuaikan LLM secara efisien karena mengurangi persyaratan resource komputasi sekaligus mempertahankan performa tinggi. Di QloRA, model terlatih dikuantifikasi menjadi 4-bit dan bobotnya dibekukan. Kemudian, lapisan adaptor yang dapat dilatih (LoRA) akan dilampirkan dan hanya lapisan adaptor yang dilatih. Setelah itu, bobot adaptor dapat digabungkan dengan model dasar atau disimpan sebagai adaptor terpisah.

Menyiapkan lingkungan pengembangan

Langkah pertama adalah menginstal Library Hugging Face, termasuk TRL, dan set data untuk menyesuaikan model terbuka.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0" tensorboard torchvision

# Install Gemma release branch from Hugging Face
%pip install "transformers>=4.51.3"

# Install Hugging Face libraries
%pip install  --upgrade \
  "datasets==3.3.2" \
  "accelerate==1.4.0" \
  "evaluate==0.4.3" \
  "bitsandbytes==0.45.3" \
  "trl==0.15.2" \
  "peft==0.14.0" \
  "pillow==11.1.0" \
  protobuf \
  sentencepiece

Sebelum dapat memulai pelatihan, Anda harus memastikan bahwa Anda telah menyetujui persyaratan penggunaan untuk Gemma. Anda dapat menyetujui lisensi di Hugging Face dengan mengklik tombol Agree and access repository di halaman model di: http://huggingface.co/google/gemma-3-4b-pt (atau halaman model yang sesuai untuk model Gemma yang memiliki kemampuan visi yang Anda gunakan).

Setelah menyetujui lisensi, Anda memerlukan Token Hugging Face yang valid untuk mengakses model. Jika Anda menjalankannya di dalam Google Colab, Anda dapat menggunakan Token Hugging Face dengan aman menggunakan secret Colab; jika tidak, Anda dapat menetapkan token langsung di metode login. Pastikan token Anda juga memiliki akses tulis, saat Anda mendorong model ke Hub selama pelatihan.

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)

Membuat dan menyiapkan set data penyesuaian

Saat menyesuaikan LLM, penting untuk mengetahui kasus penggunaan dan tugas yang ingin Anda selesaikan. Hal ini membantu Anda membuat set data untuk menyesuaikan model. Jika belum menentukan kasus penggunaan, sebaiknya kembali ke papan gambar.

Sebagai contoh, panduan ini berfokus pada kasus penggunaan berikut:

  • Menyesuaikan model Gemma untuk membuat deskripsi produk yang ringkas dan dioptimalkan untuk SEO bagi platform e-commerce, yang disesuaikan secara khusus untuk penelusuran seluler.

Panduan ini menggunakan set data philschmid/amazon-product-descriptions-vlm, yaitu set data deskripsi produk Amazon, termasuk gambar dan kategori produk.

Hugging Face TRL mendukung percakapan multi-modal. Bagian yang penting adalah peran "image", yang memberi tahu class pemrosesan bahwa class tersebut harus memuat gambar. Strukturnya harus mengikuti:

{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}

Sekarang Anda dapat menggunakan library Set Data Hugging Face untuk memuat set data dan membuat template perintah untuk menggabungkan gambar, nama produk, dan kategori, serta menambahkan pesan sistem. Set data menyertakan gambar sebagai objek Pil.Image.

from datasets import load_dataset
from PIL import Image

# System message for the assistant
system_message = "You are an expert product description writer for Amazon."

# User prompt that combines the user query and the schema
user_prompt = """Create a Short Product description based on the provided <PRODUCT> and <CATEGORY> and image.
Only return description. The description should be SEO optimized and for a better mobile search experience.

<PRODUCT>
{product}
</PRODUCT>

<CATEGORY>
{category}
</CATEGORY>
"""

# Convert dataset to OAI messages
def format_data(sample):
    return {
        "messages": [
            {
                "role": "system",
                "content": [{"type": "text", "text": system_message}],
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": user_prompt.format(
                            product=sample["Product Name"],
                            category=sample["Category"],
                        ),
                    },
                    {
                        "type": "image",
                        "image": sample["image"],
                    },
                ],
            },
            {
                "role": "assistant",
                "content": [{"type": "text", "text": sample["description"]}],
            },
        ],
    }

def process_vision_info(messages: list[dict]) -> list[Image.Image]:
    image_inputs = []
    # Iterate through each conversation
    for msg in messages:
        # Get content (ensure it's a list)
        content = msg.get("content", [])
        if not isinstance(content, list):
            content = [content]

        # Check each content element for images
        for element in content:
            if isinstance(element, dict) and (
                "image" in element or element.get("type") == "image"
            ):
                # Get the image and convert to RGB
                if "image" in element:
                    image = element["image"]
                else:
                    image = element
                image_inputs.append(image.convert("RGB"))
    return image_inputs

# Load dataset from the hub
dataset = load_dataset("philschmid/amazon-product-descriptions-vlm", split="train")

# Convert dataset to OAI messages
# need to use list comprehension to keep Pil.Image type, .mape convert image to bytes
dataset = [format_data(sample) for sample in dataset]

print(dataset[345]["messages"])

Menyesuaikan Gemma menggunakan TRL dan SFTTrainer

Sekarang Anda siap untuk meningkatkan kualitas model. SFTTrainer Hugging Face TRL memudahkan pengawasan untuk meningkatkan kualitas LLM terbuka. SFTTrainer adalah subclass dari Trainer dari library transformers dan mendukung semua fitur yang sama, termasuk logging, evaluasi, dan checkpointing, tetapi menambahkan fitur kualitas hidup tambahan, termasuk:

  • Pemformatan set data, termasuk format percakapan dan petunjuk
  • Pelatihan hanya pada penyelesaian, mengabaikan perintah
  • Mengemas set data untuk pelatihan yang lebih efisien
  • Dukungan parameter-efficient fine-tuning (PEFT) termasuk QloRA
  • Menyiapkan model dan tokenizer untuk penyesuaian percakapan (seperti menambahkan token khusus)

Kode berikut memuat model dan tokenizer Gemma dari Hugging Face dan menginisialisasi konfigurasi kuantisasi.

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig

# Hugging Face model id
model_id = "google/gemma-3-4b-pt" # or `google/gemma-3-12b-pt`, `google/gemma-3-27-pt`

# Check if GPU benefits from bfloat16
if torch.cuda.get_device_capability()[0] < 8:
    raise ValueError("GPU does not support bfloat16, please use a GPU that supports bfloat16.")

# Define model init arguments
model_kwargs = dict(
    attn_implementation="eager", # Use "flash_attention_2" when running on Ampere or newer GPU
    torch_dtype=torch.bfloat16, # What torch dtype to use, defaults to auto
    device_map="auto", # Let torch decide how to load the model
)

# BitsAndBytesConfig int-4 config
model_kwargs["quantization_config"] = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=model_kwargs["torch_dtype"],
    bnb_4bit_quant_storage=model_kwargs["torch_dtype"],
)

# Load model and tokenizer
model = AutoModelForImageTextToText.from_pretrained(model_id, **model_kwargs)
processor = AutoProcessor.from_pretrained("google/gemma-3-4b-it")

SFTTrainer mendukung integrasi bawaan dengan peft, yang memudahkan penyesuaian LLM secara efisien menggunakan QLoRA. Anda hanya perlu membuat LoraConfig dan memberikannya kepada pelatih.

from peft import LoraConfig

peft_config = LoraConfig(
    lora_alpha=16,
    lora_dropout=0.05,
    r=16,
    bias="none",
    target_modules="all-linear",
    task_type="CAUSAL_LM",
    modules_to_save=[
        "lm_head",
        "embed_tokens",
    ],
)

Sebelum dapat memulai pelatihan, Anda harus menentukan hyperparameter yang ingin digunakan di SFTConfig dan collate_fn kustom untuk menangani pemrosesan visi. collate_fn mengonversi pesan dengan teks dan gambar menjadi format yang dapat dipahami model.

from trl import SFTConfig

args = SFTConfig(
    output_dir="gemma-product-description",     # directory to save and repository id
    num_train_epochs=1,                         # number of training epochs
    per_device_train_batch_size=1,              # batch size per device during training
    gradient_accumulation_steps=4,              # number of steps before performing a backward/update pass
    gradient_checkpointing=True,                # use gradient checkpointing to save memory
    optim="adamw_torch_fused",                  # use fused adamw optimizer
    logging_steps=5,                            # log every 5 steps
    save_strategy="epoch",                      # save checkpoint every epoch
    learning_rate=2e-4,                         # learning rate, based on QLoRA paper
    bf16=True,                                  # use bfloat16 precision
    max_grad_norm=0.3,                          # max gradient norm based on QLoRA paper
    warmup_ratio=0.03,                          # warmup ratio based on QLoRA paper
    lr_scheduler_type="constant",               # use constant learning rate scheduler
    push_to_hub=True,                           # push model to hub
    report_to="tensorboard",                    # report metrics to tensorboard
    gradient_checkpointing_kwargs={
        "use_reentrant": False
    },  # use reentrant checkpointing
    dataset_text_field="",                      # need a dummy field for collator
    dataset_kwargs={"skip_prepare_dataset": True},  # important for collator
)
args.remove_unused_columns = False # important for collator

# Create a data collator to encode text and image pairs
def collate_fn(examples):
    texts = []
    images = []
    for example in examples:
        image_inputs = process_vision_info(example["messages"])
        text = processor.apply_chat_template(
            example["messages"], add_generation_prompt=False, tokenize=False
        )
        texts.append(text.strip())
        images.append(image_inputs)

    # Tokenize the texts and process the images
    batch = processor(text=texts, images=images, return_tensors="pt", padding=True)

    # The labels are the input_ids, and we mask the padding tokens and image tokens in the loss computation
    labels = batch["input_ids"].clone()

    # Mask image tokens
    image_token_id = [
        processor.tokenizer.convert_tokens_to_ids(
            processor.tokenizer.special_tokens_map["boi_token"]
        )
    ]
    # Mask tokens for not being used in the loss computation
    labels[labels == processor.tokenizer.pad_token_id] = -100
    labels[labels == image_token_id] = -100
    labels[labels == 262144] = -100

    batch["labels"] = labels
    return batch

Sekarang Anda memiliki setiap elemen penyusun yang diperlukan untuk membuat SFTTrainer guna memulai pelatihan model.

from trl import SFTTrainer

trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=dataset,
    peft_config=peft_config,
    processing_class=processor,
    data_collator=collate_fn,
)

Mulai pelatihan dengan memanggil metode train().

# Start training, the model will be automatically saved to the Hub and the output directory
trainer.train()

# Save the final model again to the Hugging Face Hub
trainer.save_model()

Sebelum dapat menguji model, pastikan untuk mengosongkan memori.

# free the memory again
del model
del trainer
torch.cuda.empty_cache()

Saat menggunakan QLoRA, Anda hanya melatih adaptor, bukan model lengkap. Artinya, saat menyimpan model selama pelatihan, Anda hanya menyimpan bobot adaptor, bukan model lengkap. Jika ingin menyimpan model lengkap, yang mempermudah penggunaan dengan stack penayangan seperti vLLM atau TGI, Anda dapat menggabungkan bobot adaptor ke dalam bobot model menggunakan metode merge_and_unload, lalu menyimpan model dengan metode save_pretrained. Tindakan ini akan menyimpan model default, yang dapat digunakan untuk inferensi.

from peft import PeftModel

# Load Model base model
model = AutoModelForImageTextToText.from_pretrained(model_id, low_cpu_mem_usage=True)

# Merge LoRA and base model and save
peft_model = PeftModel.from_pretrained(model, args.output_dir)
merged_model = peft_model.merge_and_unload()
merged_model.save_pretrained("merged_model", safe_serialization=True, max_shard_size="2GB")

processor = AutoProcessor.from_pretrained(args.output_dir)
processor.save_pretrained("merged_model")

Menguji Inferensi Model dan membuat deskripsi produk

Setelah pelatihan selesai, sebaiknya evaluasi dan uji model Anda. Anda dapat memuat berbagai sampel dari set data pengujian dan mengevaluasi model pada sampel tersebut.

import torch

# Load Model with PEFT adapter
model = AutoModelForImageTextToText.from_pretrained(
  args.output_dir,
  device_map="auto",
  torch_dtype=torch.bfloat16,
  attn_implementation="eager",
)
processor = AutoProcessor.from_pretrained(args.output_dir)

Anda dapat menguji inferensi dengan memberikan nama, kategori, dan gambar produk. sample menyertakan action figure marvel.

import requests
from PIL import Image

# Test sample with Product Name, Category and Image
sample = {
  "product_name": "Hasbro Marvel Avengers-Serie Marvel Assemble Titan-Held, Iron Man, 30,5 cm Actionfigur",
  "category": "Toys & Games | Toy Figures & Playsets | Action Figures",
  "image": Image.open(requests.get("https://m.media-amazon.com/images/I/81+7Up7IWyL._AC_SY300_SX300_.jpg", stream=True).raw).convert("RGB")
}

def generate_description(sample, model, processor):
    # Convert sample into messages and then apply the chat template
    messages = [
        {"role": "system", "content": [{"type": "text", "text": system_message}]},
        {"role": "user", "content": [
            {"type": "image","image": sample["image"]},
            {"type": "text", "text": user_prompt.format(product=sample["product_name"], category=sample["category"])},
        ]},
    ]
    text = processor.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    # Process the image and text
    image_inputs = process_vision_info(messages)
    # Tokenize the text and process the images
    inputs = processor(
        text=[text],
        images=image_inputs,
        padding=True,
        return_tensors="pt",
    )
    # Move the inputs to the device
    inputs = inputs.to(model.device)

    # Generate the output
    stop_token_ids = [processor.tokenizer.eos_token_id, processor.tokenizer.convert_tokens_to_ids("<end_of_turn>")]
    generated_ids = model.generate(**inputs, max_new_tokens=256, top_p=1.0, do_sample=True, temperature=0.8, eos_token_id=stop_token_ids, disable_compile=True)
    # Trim the generation and decode the output to text
    generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
    output_text = processor.batch_decode(
        generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
    )
    return output_text[0]

# generate the description
description = generate_description(sample, model, processor)
print(description)

Ringkasan dan langkah berikutnya

Tutorial ini membahas cara menyesuaikan model Gemma untuk tugas visi menggunakan TRL dan QLoRA, khususnya untuk membuat deskripsi produk. Lihat dokumen berikut: