使用 Hugging Face Transformers 和 QloRA 微調 Gemma

本指南逐步說明如何使用 Hugging Face Transformers 和 TRL，在自訂文字轉 SQL 資料集上微調 Gemma。您將學會：

  • 什麼是量化低秩調整 (QLoRA)
  • 設定開發環境
  • 建立及準備微調資料集
  • 使用 TRL 和 SFTTrainer 微調 Gemma
  • 測試模型推論並生成 SQL 查詢

什麼是量化低秩調整 (QLoRA)

本指南將示範如何使用量化低秩適應 (QLoRA)。這項技術可減少運算資源需求，同時維持高效能，因此成為有效微調大型語言模型的熱門方法。在 QloRA 中，預先訓練的模型會量化為 4 位元，且權重會凍結。接著附加可訓練的適應器層 (LoRA)，並只訓練適應器層。之後，您可以將轉接器權重與基礎模型合併，或保留為獨立的轉接器。

設定開發環境

第一步是安裝 Hugging Face 程式庫 (包括 TRL) 和資料集，以微調開放模型，包括不同的 RLHF 和對齊技術。

# 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

注意：如果您使用 Ampere 架構的 GPU (例如 NVIDIA L4) 或更新版本，可以使用 Flash attention。Flash Attention 是一種方法，可大幅加快運算速度，並將記憶體用量從二次方減少至序列長度的線性，進而加快訓練速度達 3 倍。詳情請參閱 FlashAttention。

開始訓練前，請務必接受 Gemma 的使用條款。如要接受 Hugging Face 的授權，請前往模型頁面 (http://huggingface.co/google/gemma-3-1b-pt)，然後點選「Agree and access repository」(同意並存取存放區) 按鈕。

接受授權後，您需要有效的 Hugging Face 權杖才能存取模型。如果您在 Google Colab 中執行，可以使用 Colab 密碼安全地使用 Hugging Face 權杖，否則可以直接在 login 方法中設定權杖。訓練期間，您會將模型推送至 Hub，因此請確保權杖也具有寫入權限。

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)

建立及準備微調資料集

微調大型語言模型時，請務必瞭解您的用途和要解決的任務。這有助於建立資料集，微調模型。如果尚未定義用途，建議您重新思考。

舉例來說，本指南著重於下列用途：

  • 微調自然語言轉 SQL 模型，順暢整合至資料分析工具。目標是大幅減少產生 SQL 查詢所需的時間和專業知識，讓非技術人員也能從資料中擷取有意義的洞察資料。

文字轉 SQL 是微調 LLM 的絕佳用途，因為這項工作相當複雜，需要大量 (內部) 資料和 SQL 語言知識。

確定微調是合適的解決方案後，您需要用來微調的資料集。資料集應包含您想解決的各種工作示範。建立這類資料集的方式有很多種，包括：

  • 使用現有的開放原始碼資料集，例如 Spider
  • 使用 LLM 建立的合成資料集，例如 Alpaca
  • 使用人類建立的資料集，例如 Dolly。
  • 結合使用多種方法，例如 Orca

每種方法各有優缺點，取決於預算、時間和品質要求。舉例來說，使用現有資料集最簡單，但可能無法配合特定用途；使用領域專家可能最準確，但可能耗時且昂貴。您也可以結合多種方法來建立指令資料集，如 Orca：從 GPT-4 的複雜說明軌跡逐步學習所示。

本指南使用現有資料集 (philschmid/gretel-synthetic-text-to-sql)，這是高品質的合成 Text-to-SQL 資料集，包含自然語言指令、結構定義、推理和對應的 SQL 查詢。

Hugging Face TRL 支援自動範本化對話資料集格式。也就是說，您只需要將資料集轉換為正確的 JSON 物件，trl 就會負責範本化並轉換為正確格式。

{"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 包含超過 10 萬個樣本。為縮小指南大小，系統會將樣本數下取樣至 10,000 個。

您現在可以使用 Hugging Face Datasets 程式庫載入資料集，並建立提示範本，結合自然語言指令、結構定義，以及為助理新增系統訊息。

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 和 SFTTrainer 微調 Gemma

現在可以開始微調模型了。Hugging Face TRL SFTTrainer 可輕鬆監督微調開放式 LLM。SFTTrainer 是 transformers 程式庫中 Trainer 的子類別，支援所有相同的功能，包括記錄、評估和檢查點，但新增了其他提升生活品質的功能，包括：

  • 資料集格式設定，包括對話和指令格式
  • 只訓練完成內容，忽略提示
  • 封裝資料集，提高訓練效率
  • 支援高效參數微調 (PEFT)，包括 QloRA
  • 準備模型和代碼化工具，以進行對話微調 (例如新增特殊符記)

下列程式碼會從 Hugging Face 載入 Gemma 模型和權杖化工具，並初始化量化設定。

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 的原生整合，因此可輕鬆使用 QLoRA 高效率地微調 LLM。您只需要建立 LoraConfig 並提供給訓練師即可。

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
)

開始訓練前，您需要先在 SFTConfig 例項中定義要使用的超參數。

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

您現在已擁有建立 SFTTrainer 的所有建構區塊，可以開始訓練模型。

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() 方法開始訓練。

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

測試模型前，請務必釋放記憶體。

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

使用 QLoRA 時，您只會訓練轉接器，而非完整模型。也就是說，訓練期間儲存模型時，您只會儲存適應器權重，而非完整模型。如要儲存完整模型，以便搭配 vLLM 或 TGI 等服務堆疊使用，可以透過 merge_and_unload 方法將轉接器權重合併至模型權重，然後使用 save_pretrained 方法儲存模型。這會儲存預設模型，可用於推論。

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

測試模型推論並生成 SQL 查詢

訓練完成後，請評估及測試模型。您可以從測試資料集載入不同樣本，並評估模型在這些樣本上的表現。

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)

我們從測試資料集載入隨機樣本，並產生 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"])-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()}")

摘要和後續步驟

本教學課程說明如何使用 TRL 和 QLoRA 微調 Gemma 模型。接下來請參閱下列文件：