Menyesuaikan Gemma menggunakan Hugging Face Transformers dan QloRA

Panduan ini memandu Anda cara menyesuaikan Gemma pada set data text-to-sql kustom menggunakan Transformers 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
  • Menyesuaikan Gemma menggunakan TRL dan SFTTrainer
  • Menguji Inferensi Model dan membuat kueri SQL

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, termasuk teknik RLHF dan penyelarasan yang berbeda.

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

# 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" \
  protobuf \
  sentencepiece

# COMMENT IN: if you are running on a GPU that supports BF16 data type and flash attn, such as NVIDIA L4 or NVIDIA A100
#% pip install flash-attn

Catatan: Jika menggunakan GPU dengan arsitektur Ampere (seperti NVIDIA L4) atau yang lebih baru, Anda dapat menggunakan perhatian Flash. Flash Attention adalah metode yang secara signifikan mempercepat komputasi dan mengurangi penggunaan memori dari kuadrat menjadi linear dalam durasi urutan, sehingga mempercepat pelatihan hingga 3x lipat. Pelajari lebih lanjut di FlashAttention.

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 Setuju dan akses repositori di halaman model di: http://huggingface.co/google/gemma-3-1b-pt

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 secara langsung dalam 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:

  • Sesuaikan model natural language ke SQL untuk integrasi yang lancar ke dalam alat analisis data. Tujuannya adalah untuk secara signifikan mengurangi waktu dan keahlian yang diperlukan untuk pembuatan kueri SQL, sehingga pengguna non-teknis sekalipun dapat mengekstrak insight yang bermakna dari data.

Text-to-SQL dapat menjadi kasus penggunaan yang baik untuk menyesuaikan LLM, karena merupakan tugas kompleks yang memerlukan banyak pengetahuan (internal) tentang data dan bahasa SQL.

Setelah menentukan bahwa penyesuaian adalah solusi yang tepat, Anda memerlukan set data untuk disesuaikan. Set data harus berupa kumpulan demonstrasi yang beragam dari tugas yang ingin Anda pecahkan. Ada beberapa cara untuk membuat set data tersebut, termasuk:

  • Menggunakan set data open source yang ada, seperti Spider
  • Menggunakan set data sintetis yang dibuat oleh LLM, seperti Alpaca
  • Menggunakan set data yang dibuat oleh manusia, seperti Dolly.
  • Menggunakan kombinasi metode, seperti Orca

Setiap metode memiliki kelebihan dan kekurangannya sendiri serta bergantung pada persyaratan anggaran, waktu, dan kualitas. Misalnya, menggunakan set data yang ada adalah cara termudah, tetapi mungkin tidak disesuaikan dengan kasus penggunaan spesifik Anda, sedangkan menggunakan pakar domain mungkin paling akurat, tetapi dapat memakan waktu dan mahal. Anda juga dapat menggabungkan beberapa metode untuk membuat set data petunjuk, seperti yang ditunjukkan dalam Orca: Progressive Learning from Complex Explanation Traces of GPT-4.

Panduan ini menggunakan set data yang sudah ada (philschmid/gretel-synthetic-text-to-sql), set data Text-to-SQL sintetis berkualitas tinggi yang mencakup petunjuk bahasa alami, definisi skema, penalaran, dan kueri SQL yang sesuai.

Hugging Face TRL mendukung pembuatan template otomatis untuk format set data percakapan. Artinya, Anda hanya perlu mengonversi set data menjadi objek JSON yang tepat, dan trl akan menangani pembuatan template dan memasukkannya ke dalam format yang tepat.

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

philschmid/gretel-synthetic-text-to-sql berisi lebih dari 100 ribu sampel. Agar panduan tetap kecil, panduan ini didownsample agar hanya menggunakan 10.000 sampel.

Sekarang Anda dapat menggunakan library Set Data Hugging Face untuk memuat set data dan membuat template perintah untuk menggabungkan petunjuk bahasa alami, definisi skema, dan menambahkan pesan sistem untuk asisten Anda.

from datasets import load_dataset

# System message for the assistant
system_message = """You are a text to SQL query translator. Users will ask you questions in English and you will generate a SQL query based on the provided SCHEMA."""

# User prompt that combines the user query and the schema
user_prompt = """Given the <USER_QUERY> and the <SCHEMA>, generate the corresponding SQL command to retrieve the desired data, considering the query's syntax, semantics, and schema constraints.

<SCHEMA>
{context}
</SCHEMA>

<USER_QUERY>
{question}
</USER_QUERY>
"""
def create_conversation(sample):
  return {
    "messages": [
      # {"role": "system", "content": system_message},
      {"role": "user", "content": user_prompt.format(question=sample["sql_prompt"], context=sample["sql_context"])},
      {"role": "assistant", "content": sample["sql"]}
    ]
  }

# Load dataset from the hub
dataset = load_dataset("philschmid/gretel-synthetic-text-to-sql", split="train")
dataset = dataset.shuffle().select(range(12500))

# Convert dataset to OAI messages
dataset = dataset.map(create_conversation, remove_columns=dataset.features,batched=False)
# split dataset into 10,000 training samples and 2,500 test samples
dataset = dataset.train_test_split(test_size=2500/12500)

# Print formatted user prompt
print(dataset["train"][345]["messages"][1]["content"])

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 AutoTokenizer, AutoModelForCausalLM, AutoModelForImageTextToText, BitsAndBytesConfig

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

# Select model class based on id
if model_id == "google/gemma-3-1b-pt":
    model_class = AutoModelForCausalLM
else:
    model_class = AutoModelForImageTextToText

# Check if GPU benefits from bfloat16
if torch.cuda.get_device_capability()[0] >= 8:
    torch_dtype = torch.bfloat16
else:
    torch_dtype = torch.float16

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

# BitsAndBytesConfig: Enables 4-bit quantization to reduce model size/memory usage
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 = model_class.from_pretrained(model_id, **model_kwargs)
tokenizer = AutoTokenizer.from_pretrained("google/gemma-3-1b-it") # Load the Instruction Tokenizer to use the official Gemma template

SFTTrainer mendukung integrasi native 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"] # make sure to save the lm_head and embed_tokens as you train the special tokens
)

Sebelum dapat memulai pelatihan, Anda harus menentukan hyperparameter yang ingin digunakan dalam instance SFTConfig.

from trl import SFTConfig

args = SFTConfig(
    output_dir="gemma-text-to-sql",         # directory to save and repository id
    max_seq_length=512,                     # max sequence length for model and packing of the dataset
    packing=True,                           # Groups multiple samples in the dataset into a single sequence
    num_train_epochs=3,                     # 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=10,                       # log every 10 steps
    save_strategy="epoch",                  # save checkpoint every epoch
    learning_rate=2e-4,                     # learning rate, based on QLoRA paper
    fp16=True if torch_dtype == torch.float16 else False,   # use float16 precision
    bf16=True if torch_dtype == torch.bfloat16 else False,   # 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
    dataset_kwargs={
        "add_special_tokens": False, # We template with special tokens
        "append_concat_token": True, # Add EOS token as separator token between examples
    }
)

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

from trl import SFTTrainer

# Create Trainer object
trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=dataset["train"],
    peft_config=peft_config,
    processing_class=tokenizer
)

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 = model_class.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 = AutoTokenizer.from_pretrained(args.output_dir)
processor.save_pretrained("merged_model")

Menguji Inferensi Model dan membuat kueri SQL

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
from transformers import pipeline

model_id = "gemma-text-to-sql"

# Load Model with PEFT adapter
model = model_class.from_pretrained(
  model_id,
  device_map="auto",
  torch_dtype=torch_dtype,
  attn_implementation="eager",
)
tokenizer = AutoTokenizer.from_pretrained(model_id)

Mari kita muat sampel acak dari set data pengujian dan buat perintah SQL.

from random import randint
import re

# Load the model and tokenizer into the pipeline
pipe = pipeline("text-generation", model=model, tokenizer=tokenizer)

# Load a random sample from the test dataset
rand_idx = randint(0, len(dataset["test"]))
test_sample = dataset["test"][rand_idx]

# Convert as test example into a prompt with the Gemma template
stop_token_ids = [tokenizer.eos_token_id, tokenizer.convert_tokens_to_ids("<end_of_turn>")]
prompt = pipe.tokenizer.apply_chat_template(test_sample["messages"][:2], tokenize=False, add_generation_prompt=True)

# Generate our SQL query.
outputs = pipe(prompt, max_new_tokens=256, do_sample=False, temperature=0.1, top_k=50, top_p=0.1, eos_token_id=stop_token_ids, disable_compile=True)

# Extract the user query and original answer
print(f"Context:\n", re.search(r'<SCHEMA>\n(.*?)\n</SCHEMA>', test_sample['messages'][0]['content'], re.DOTALL).group(1).strip())
print(f"Query:\n", re.search(r'<USER_QUERY>\n(.*?)\n</USER_QUERY>', test_sample['messages'][0]['content'], re.DOTALL).group(1).strip())
print(f"Original Answer:\n{test_sample['messages'][1]['content']}")
print(f"Generated Answer:\n{outputs[0]['generated_text'][len(prompt):].strip()}")

Ringkasan dan langkah berikutnya

Tutorial ini membahas cara menyesuaikan model Gemma menggunakan TRL dan QLoRA. Selanjutnya, lihat dokumen berikut: