sangtran12/eduflowai-gemma4b-adapter-qlora

🎓 EduFlowAI Gemma 3 4B QLoRA Adapter

This repository provides the official QLoRA (4-bit NF4) fine-tuned adapter for unsloth/gemma-3-4b-it, specifically optimized for Vietnamese National High School Graduation Exam (VNHSGE) question extraction and structured quiz generation.

Part of Master's Thesis research at FPT University under the EduFlow Multi-Tenant SaaS LMS project.

---

📊 Training Specifications & Hardware

• Base Model: unsloth/gemma-3-4b-it (Google Gemma 3 architecture, 4 billion parameters, 256k vocabulary)
• Fine-Tuning Method: QLoRA (NF4 4-bit Base + 16-bit LoRA Adapters via Unsloth)
• Dataset: 667 verified Vietnamese High School National Exam papers (VNHSGE) with 25,000+ extracted questions
• Hardware: 1x NVIDIA RTX PRO 4000 Blackwell (24.4 GB VRAM, sm_120, CUDA 13.0, PyTorch 2.12.1+cu130)
• Hyperparameters:
  • Rank ($r$): 16
  • Alpha ($lpha$): 16 (scaling factor $lpha/r = 1.0$)
  • Target Modules: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
  • Learning Rate: $5 imes 10^{-5}$ (Cosine schedule with 10% warmup)
  • Gradient Clipping: max_grad_norm = 0.3
  • Max Sequence Length: 8,192 tokens
  • Batch Size: 1 per device, 8 gradient accumulation steps (Effective batch size = 8)

---

📈 Empirical Results (RQ2 Benchmark)

Metric	Measurement
Peak VRAM During Training	13.3 GB (Feasible on consumer 16GB GPUs like RTX 4080 / T4)
Training Time (1 Epoch)	21.7 minutes (84 steps, ~14.5s per step)
Final Training Loss	2.6323
Validation Loss	10.09
JSON Syntax Validity on Unseen Test Set	100% Valid JSON
EduFlow Schema Compliance	100% (type, content, options, correct_index, points)

---

🚀 How to Use with Unsloth / Hugging Face Transformers

from unsloth import FastLanguageModel
import torch

# 1. Load fine-tuned adapter on 4-bit base model
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "sangtran12/eduflowai-gemma4b-adapter-qlora",
    max_seq_length = 8192,
    load_in_4bit = True,
)
FastLanguageModel.for_inference(model)

# 2. Format input prompt
messages = [
    {
        "role": "user",
        "content": "Hãy trích xuất câu hỏi sau sang JSON: Câu 1: Kim loại nào sau đây có tính dẫn điện tốt nhất? A. Cu. B. Ag. C. Al. D. Au."
    }
]

inputs = tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_tensors="pt").to("cuda")

# 3. Generate structured quiz
outputs = model.generate(
    input_ids=inputs,
    max_new_tokens=2048,
    temperature=0.1,
    top_p=0.9,
    eos_token_id=[tokenizer.eos_token_id, 106], # 106 is Gemma 3 <end_of_turn>
)

print(tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True))

---

🔗 Related Models

• GGUF Format (Ollama / Local Mac): sangtran12/eduflowai-gemma4b-gguf
• LoRA bf16 Benchmark Arm: sangtran12/eduflowai-gemma4b-adapter-lora