Hugging Face Transformers ve QloRA'yı kullanarak Gemma'yı hassas ayarlama

Bu kılavuzda, Hugging Face Transformers ve TRL kullanarak Gemma'yı özel bir metinden SQL'e veri kümesinde nasıl ince ayar yapacağınız açıklanmaktadır. Öğrenecekleriniz:

  • Quantized Low-Rank Adaptation (QLoRA) nedir?
  • Geliştirme ortamını kurma
  • İnce ayar veri kümesini oluşturma ve hazırlama
  • TRL ve SFTTrainer'ı kullanarak Gemma'ya ince ayar yapma
  • Model çıkarımını test etme ve SQL sorguları oluşturma

Quantized Low-Rank Adaptation (QLoRA) nedir?

Bu kılavuzda, yüksek performansı korurken işlem kaynağı gereksinimlerini azalttığı için LLM'lere verimli bir şekilde ince ayar yapma konusunda popüler bir yöntem olarak ortaya çıkan Quantized Low-Rank Adaptation (QLoRA)'nın kullanımı gösterilmektedir. QloRA'da önceden eğitilmiş model 4 bit'e nicelleştirilir ve ağırlıklar dondurulur. Ardından, eğitilebilir uyarlanabilir katmanlar (LoRA) eklenir ve yalnızca uyarlanabilir katmanlar eğitilir. Daha sonra, bağdaştırıcı ağırlıkları temel modelle birleştirilebilir veya ayrı bir bağdaştırıcı olarak tutulabilir.

Geliştirme ortamını kurma

İlk adım, farklı RLHF ve hizalama teknikleri de dahil olmak üzere açık modeli ince ayarlamak için TRL ve veri kümeleri gibi Hugging Face kitaplıklarını yüklemektir.

# 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.21.0" \
  "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

Not: Ampere mimarisine (ör. NVIDIA L4) veya daha yeni bir mimariye sahip bir GPU kullanıyorsanız Flash dikkat mekanizmasını kullanabilirsiniz. Flash Attention, hesaplamaları önemli ölçüde hızlandıran ve bellek kullanımını sıra uzunluğunda kareselden doğrusal hale getiren bir yöntemdir. Bu sayede eğitim 3 kata kadar hızlandırılabilir. Daha fazla bilgi için FlashAttention sayfasını ziyaret edin.

Eğitime başlamadan önce Gemma'nın kullanım şartlarını kabul ettiğinizden emin olmanız gerekir. http://huggingface.co/google/gemma-3-1b-pt adresindeki model sayfasında "Kabul et ve depoya eriş" düğmesini tıklayarak Hugging Face'te lisansı kabul edebilirsiniz.

Lisansı kabul ettikten sonra modele erişmek için geçerli bir Hugging Face jetonuna ihtiyacınız vardır. Google Colab'de çalışıyorsanız Colab sırlarını kullanarak Hugging Face jetonunuzu güvenli bir şekilde kullanabilirsiniz. Aksi takdirde, jetonu doğrudan login yönteminde ayarlayabilirsiniz. Eğitim sırasında modelinizi Hub'a aktaracağınız için jetonunuzun yazma erişimine de sahip olduğundan emin olun.

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)

İnce ayar veri kümesini oluşturma ve hazırlama

Büyük dil modellerini ince ayarlarken kullanım alanınızı ve çözmek istediğiniz görevi bilmeniz önemlidir. Bu sayede, modelinizi ince ayarlamak için bir veri kümesi oluşturabilirsiniz. Kullanım alanınızı henüz tanımlamadıysanız tekrar planlama aşamasına dönmek isteyebilirsiniz.

Örneğin, bu kılavuzda aşağıdaki kullanım alanı ele alınmıştır:

  • Bir veri analizi aracına sorunsuz entegrasyon için doğal dil-SQL modelini ince ayar yapın. Amaç, SQL sorgusu oluşturmak için gereken süreyi ve uzmanlığı önemli ölçüde azaltarak teknik bilgisi olmayan kullanıcıların bile verilerden anlamlı analizler elde etmesini sağlamaktır.

Metinden SQL'e dönüştürme, LLM'lere ince ayar yapmak için iyi bir kullanım alanı olabilir. Çünkü bu, veriler ve SQL dili hakkında çok fazla (dahili) bilgi gerektiren karmaşık bir görevdir.

İnce ayarın doğru çözüm olduğuna karar verdikten sonra ince ayar için bir veri kümesine ihtiyacınız olur. Veri kümesi, çözmek istediğiniz görevlerin çeşitli gösterimlerinden oluşmalıdır. Bu tür bir veri kümesi oluşturmanın birkaç yolu vardır. Örneğin:

  • Spider gibi mevcut açık kaynaklı veri kümelerini kullanma
  • Alpaca gibi LLM'ler tarafından oluşturulan sentetik veri kümelerini kullanma
  • Dolly gibi insanlar tarafından oluşturulan veri kümelerini kullanma
  • Orca gibi yöntemlerin bir kombinasyonunu kullanma

Yöntemlerin her birinin kendine özgü avantajları ve dezavantajları vardır ve bütçe, süre ve kalite koşullarına bağlıdır. Örneğin, mevcut bir veri kümesini kullanmak en kolay yöntem olsa da belirli kullanım alanınıza uygun olmayabilir. Alan uzmanlarından yararlanmak ise en doğru yöntem olsa da zaman alıcı ve maliyetli olabilir. Orca: Progressive Learning from Complex Explanation Traces of GPT-4'te (Orca: GPT-4'ün Karmaşık Açıklama İzlerinden Aşamalı Öğrenme) gösterildiği gibi, bir talimat veri kümesi oluşturmak için çeşitli yöntemleri birleştirmek de mümkündür.

Bu kılavuzda, doğal dil talimatları, şema tanımları, muhakeme ve ilgili SQL sorgusunu içeren yüksek kaliteli bir sentetik Text-to-SQL veri kümesi olan philschmid/gretel-synthetic-text-to-sql adlı mevcut bir veri kümesi kullanılmaktadır.

Hugging Face TRL, sohbet veri kümesi biçimlerinin otomatik olarak şablonlanmasını destekler. Bu, veri kümenizi yalnızca doğru JSON nesnelerine dönüştürmeniz gerektiği ve trl'nın şablon oluşturma ve doğru biçime getirme işlemlerini yapacağı anlamına gelir.

{"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, 100 binden fazla örnek içerir. Rehberin boyutunu küçük tutmak için yalnızca 10.000 örnek kullanılacak şekilde örnekleme sıklığı azaltılmıştır.

Artık veri kümesini yüklemek ve doğal dil talimatını, şema tanımını birleştirmek için bir istem şablonu oluşturmak ve asistanınız için bir sistem mesajı eklemek üzere Hugging Face Datasets kitaplığını kullanabilirsiniz.

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

TRL ve SFTTrainer'ı kullanarak Gemma'ya ince ayar yapma

Artık modelinizde ince ayar yapmaya hazırsınız. Hugging Face TRL SFTTrainer, açık LLM'lerin ince ayarını denetlemeyi kolaylaştırır. SFTTrainer, transformers kitaplığındaki Trainer sınıfının bir alt sınıfıdır ve günlük kaydı, değerlendirme ve kontrol noktası oluşturma dahil olmak üzere aynı özelliklerin tümünü destekler. Bununla birlikte, aşağıdakiler gibi ek kullanım kolaylığı özellikleri de sunar:

  • Sohbet ve talimat biçimleri dahil olmak üzere veri kümesi biçimlendirme
  • Yalnızca tamamlama konusunda eğitim, istemleri yoksayma
  • Daha verimli eğitim için veri kümelerini paketleme
  • QloRA dahil olmak üzere parametrelerin verimli şekilde kullanıldığı ayarlama (PEFT) desteği
  • Modeli ve belirteçleştiriciyi, sohbet için ince ayar yapmaya hazırlama (ör. özel belirteçler ekleme)

Aşağıdaki kod, Gemma modelini ve belirteçleştiriciyi Hugging Face'ten yükler ve nicemleme yapılandırmasını başlatır.

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, peft ile yerel entegrasyonu destekler. Bu sayede, QLoRA kullanarak LLM'leri verimli bir şekilde ayarlamak kolaylaşır. Yalnızca bir LoraConfig oluşturup eğitmenle paylaşmanız gerekir.

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
)

Eğitiminize başlamadan önce, SFTConfig örneğinde kullanmak istediğiniz hiperparametreleri tanımlamanız gerekir.

from trl import SFTConfig

args = SFTConfig(
    output_dir="gemma-text-to-sql",         # directory to save and repository id
    max_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
    }
)

Artık modelinizin eğitimine başlamak için SFTTrainer oluşturmanız gereken tüm yapı taşlarına sahipsiniz.

from trl import SFTTrainer

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

train() yöntemini çağırarak eğitime başlayın.

# 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()

Modelinizi test etmeden önce belleği boşalttığınızdan emin olun.

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

QLoRA kullanırken yalnızca bağdaştırıcıları eğitirsiniz, modelin tamamını eğitmezsiniz. Bu, eğitim sırasında modeli kaydederken yalnızca bağdaştırıcı ağırlıklarını kaydettiğiniz ve modelin tamamını kaydetmediğiniz anlamına gelir. vLLM veya TGI gibi sunum yığınlarıyla kullanmayı kolaylaştıran tam modeli kaydetmek istiyorsanız merge_and_unload yöntemini kullanarak bağdaştırıcı ağırlıklarını model ağırlıklarıyla birleştirebilir, ardından save_pretrained yöntemini kullanarak modeli kaydedebilirsiniz. Bu işlem, çıkarım için kullanılabilecek bir varsayılan modeli kaydeder.

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

Model çıkarımını test etme ve SQL sorguları oluşturma

Eğitim tamamlandıktan sonra modelinizi değerlendirip test etmeniz gerekir. Test veri kümesinden farklı örnekler yükleyebilir ve modeli bu örnekler üzerinde değerlendirebilirsiniz.

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)

Test veri kümesinden rastgele bir örnek yükleyelim ve bir SQL komutu oluşturalım.

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"])-1)
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()}")

Özet ve sonraki adımlar

Bu eğitimde, TRL ve QLoRA kullanarak Gemma modelinde ince ayar yapma konusu ele alındı. Ardından aşağıdaki dokümanlara göz atın: