Fine-Tuning Qwen3-4B-Instruct with Unsloth: Instruction Alignment and Response Masking

Step 1: Model Loading & 4-bit LoRA Initialization

from __future__ import annotations

import torch
from unsloth import FastLanguageModel

max_seq_length = 2048

# Load pre-quantized Qwen3-4B-Instruct
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Qwen3-4B-Instruct-2507",
    max_seq_length=max_seq_length,
    dtype=None,             # Auto-selects FP16 on T4, BF16 on Ampere+/Hopper
    load_in_4bit=True,
)

# Attach LoRA adapters to attention and feed-forward projections
lora_rank = 32
model = FastLanguageModel.get_peft_model(
    model,
    r=lora_rank,
    lora_alpha=lora_rank,   # Scaling alpha = r
    target_modules=[
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    lora_dropout=0.0,       # 0 is optimized for Unsloth
    bias="none",
    use_gradient_checkpointing="unsloth",
    random_state=3407,
)

model.print_trainable_parameters()
# Trainable parameters: 66,060,288 / 4,088,528,384 (1.62% trained)

Step 2: Dataset Standardization & Response-Only Masking

from datasets import load_dataset
from unsloth.chat_templates import get_chat_template, standardize_data_formats

# Load FineTome-100k instruction corpus
raw_dataset = load_dataset("mlabonne/FineTome-100k", split="train")

# Automatically standardize various conversation formats
standardized_dataset = standardize_data_formats(raw_dataset)

# Configure Qwen3 instruction template
tokenizer = get_chat_template(tokenizer, chat_template="qwen3-instruct")


def formatting_prompts_func(examples: dict) -> dict:
    convos = examples["conversations"]
    texts = [
        tokenizer.apply_chat_template(
            convo,
            tokenize=False,
            add_generation_prompt=False,
        )
        for convo in convos
    ]
    return {"text": texts}


dataset = standardized_dataset.map(formatting_prompts_func, batched=True)

Step 3: Supervised Fine-Tuning Execution

from trl import SFTConfig, SFTTrainer
from unsloth.chat_templates import train_on_responses_only
from model_init import model, tokenizer, max_seq_length
from dataset_prep import dataset

training_args = SFTConfig(
    output_dir="outputs/qwen3_4b_instruct",
    dataset_text_field="text",
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,      # Effective batch size = 8
    warmup_steps=5,
    max_steps=60,                       # Quick calibration or full epoch (max_steps=None)
    learning_rate=2e-4,                 # Optimal LR for 4-bit LoRA on 4B SLMs
    fp16=not torch.cuda.is_bf16_supported(),
    bf16=torch.cuda.is_bf16_supported(),
    logging_steps=1,
    optim="adamw_8bit",                 # 8-bit AdamW reduces optimizer footprint
    weight_decay=0.001,
    lr_scheduler_type="linear",
    seed=3407,
    report_to="none",
)

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    max_seq_length=max_seq_length,
    dataset_num_proc=2,
    packing=False,
    args=training_args,
)

# Apply exact token masking across Qwen3 ChatML delimiters
trainer = train_on_responses_only(
    trainer,
    instruction_part="<|im_start|>user\n",
    response_part="<|im_start|>assistant\n",
)

trainer.train()

Step Convergence & Loss Trajectory

Step 4: Generation Inference & Streamer Testing

from transformers import TextStreamer
from unsloth import FastLanguageModel

# Fuse dequantization kernels for fast evaluation
FastLanguageModel.for_inference(model)

messages = [
    {"role": "user", "content": "Explain the architectural differences between GQA and MHA in transformer decoders."}
]

prompt_text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)

inputs = tokenizer(prompt_text, return_tensors="pt").to("cuda")

streamer = TextStreamer(tokenizer, skip_prompt=True)

_ = model.generate(
    **inputs,
    max_new_tokens=512,
    temperature=0.7,
    top_p=0.8,
    top_k=20,
    streamer=streamer,
)

Step 5: Multi-Format GGUF & Hugging Face Hub Export

# 1. Save standalone LoRA adapter (~120 MB)
model.save_pretrained("outputs/qwen3_4b_lora")
tokenizer.save_pretrained("outputs/qwen3_4b_lora")

# 2. Export to GGUF format with multiple quantization schemes
model.save_pretrained_gguf(
    "outputs/qwen3_4b_gguf",
    tokenizer,
    quantization_method="q4_k_m",  # Recommended size/quality trade-off (~2.9 GB)
)

# 3. Batch export to Hugging Face Hub
# model.push_to_hub_gguf(
#     "YOUR_USERNAME/qwen3-4b-instruct-gguf",
#     tokenizer,
#     quantization_method=["q4_k_m", "q5_k_m", "q8_0"],
#     token="YOUR_HF_TOKEN",
# )

Empirical Benchmark Evaluation

We evaluated Qwen3-4B-Instruct across standard academic and instruction benchmarks:

Troubleshooting Common Synthesis Faults

1. Model Hallucinates User Dialogue during Generation

• Symptom: Generated text emits <|im_start|>user and fabricates follow-up user queries.
• Remedy: Ensure train_on_responses_only is applied with exact newline delimiters ("<|im_start|>user\n" and "<|im_start|>assistant\n").

2. Loss Instability / Sudden Gradient Explosions

• Symptom: Loss diverges to NaN or spikes beyond $2.5$ after Step 30.
• Remedy: Restrict learning rate to $\le 2\times 10^{-4}$ for LoRA $r=32$, and verify weight_decay=0.001.

3. Out of Memory on 8 GB GPUs

• Symptom: CUDA OOM error during initial batch allocation.
• Remedy: Set per_device_train_batch_size=1, increase gradient_accumulation_steps=8, and verify use_gradient_checkpointing="unsloth" is active.