Tinh chỉnh Qwen3.5 Small bằng QLoRA cho phân loại tin tức

Qwen3.5 Small là một mô hình thực tiễn cho tinh chỉnh gọn nhẹ vì được thiết kế cho thử nghiệm nhanh, thích ứng theo tác vụ và quy trình nghiên cứu. Kết hợp với QLoRA, chúng ta có thể tinh chỉnh mô hình trên nền một mô hình gốc đã được lượng tử hóa 4-bit và cố định, giúp quy trình tiết kiệm bộ nhớ hơn nhiều và dễ tiếp cận trên phần cứng hạn chế.

Trong hướng dẫn này, chúng ta sẽ thiết lập môi trường, tải mô hình và bộ dữ liệu AG News, đánh giá mô hình gốc, sau đó tinh chỉnh Qwen3.5 Small cho tác vụ phân loại tin tức. Cuối cùng, chúng ta sẽ so sánh kết quả trước và sau khi huấn luyện, rồi lưu và xuất bản bộ chuyển tiếp LoRA lên Hugging Face để tái sử dụng. 

Tôi khuyến nghị bạn học Hugging Face Fundamentals skill track nếu bạn chưa quen với cách thức hoạt động của nền tảng này.

Qwen3.5 Small là gì?

Trước khi đi vào mã, sẽ hữu ích khi hiểu mô hình mà chúng ta làm việc cùng. Qwen3.5 là một họ mô hình nền tảng, và dòng "Small" đề cập đến dải mô hình nhẹ, cụ thể là các mô hình dưới 10 tỷ tham số. Trong hướng dẫn này, chúng ta sẽ dùng phiên bản 0.8B.

Mặc dù chỉ có 800 triệu tham số, Qwen3.5-0.8B rất mạnh và cực kỳ hiệu quả. Khi nạp ở độ chính xác 4-bit, nó cần ít hơn 2GB VRAM. Điều này khiến nó rất phù hợp cho laptop phổ thông, các môi trường đám mây miễn phí như Kaggle, và các triển khai nhẹ ở biên.

Ngoài ra, kiến trúc Qwen3.5 hỗ trợ cửa sổ ngữ cảnh lên đến 262K và đa phương thức gốc. Dù trong hướng dẫn này chúng ta chỉ tập trung vào phân loại văn bản, các khái niệm nền tảng được đề cập có thể dễ dàng mở rộng sang các tác vụ thị giác sau này. Mô hình cũng có chế độ lập luận lai, nhưng chúng ta sẽ tắt để tối đa hóa tốc độ suy luận cho nhiệm vụ gán nhãn đơn giản.

Tổng thể, Qwen3.5-0.8B là lựa chọn thực tiễn cho thử nghiệm nhanh. Nó cung cấp cách thức nhanh và tiết kiệm chi phí để kiểm thử quy trình tinh chỉnh trong khi vẫn cho ra kết quả hạ nguồn mạnh.

1. Thiết lập môi trường Kaggle

Trong hướng dẫn này, chúng ta sẽ dùng notebook Kaggle làm môi trường huấn luyện. Kaggle cung cấp GPU, là nền tảng tiện lợi để huấn luyện, tinh chỉnh và đánh giá mô hình. Trước khi chạy notebook, hãy tạo notebook Kaggle mới, mở phần Session và chọn GPU P100 làm bộ tăng tốc. 

Tiếp theo, chúng ta sẽ thiết lập môi trường, thêm token Hugging Face vào Kaggle và import các thư viện Python dùng xuyên suốt hướng dẫn.

Tạo token truy cập Hugging Face

Trước khi chạy notebook, hãy tạo token truy cập Hugging Face từ trang cài đặt tài khoản của bạn. Vào Settings, mở Access Tokens và tạo token mới. Nếu bạn muốn xuất bản bộ chuyển tiếp LoRA đã tinh chỉnh lên Hugging Face Hub ở cuối hướng dẫn, hãy đảm bảo token có quyền ghi.

Thêm token vào Kaggle secrets

Sau khi tạo token, mở notebook Kaggle của bạn và thêm nó dưới dạng secret. Trong trình soạn thảo notebook, vào Add-ons, rồi Secrets, và tạo secret mới tên HUGGINGFACE_TOKEN. Dán giá trị token của bạn vào đó để notebook có thể truy cập an toàn mà không phải lộ trong mã.

Cài đặt các thư viện cần thiết

Giờ chúng ta có thể cài các thư viện chính cho quy trình này. Các gói này bao gồm tải mô hình, lượng tử hóa, tinh chỉnh hiệu quả tham số, xử lý dữ liệu và đánh giá.

!pip install -q -U transformers accelerate
!pip install -q peft trl bitsandbytes datasets scikit-learn

Xác thực với Hugging Face

Tiếp theo, chúng ta nạp token Hugging Face từ Kaggle secrets và dùng để xác thực. Điều này cho phép notebook truy cập mô hình và sau đó đẩy bộ chuyển tiếp đã huấn luyện.

from huggingface_hub import login
from kaggle_secrets import UserSecretsClient

user_secrets = UserSecretsClient()
login(token=user_secrets.get_secret("HUGGINGFACE_TOKEN"))

Import các thư viện Python

Cuối cùng, chúng ta import các thư viện Python sẽ dùng xuyên suốt hướng dẫn cho việc tải mô hình, huấn luyện, xử lý dữ liệu và đánh giá.

import torch
from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer, SFTConfig
from transformers import TrainingArguments
from sklearn.metrics import accuracy_score, f1_score
from tqdm.notebook import tqdm

2. Tải mô hình Qwen3.5 và bộ dữ liệu AG News

Sau khi môi trường sẵn sàng, chúng ta có thể tải mô hình gốc và chuẩn bị bộ dữ liệu cho tinh chỉnh. 

Trong phần này, chúng ta sẽ tải Qwen3.5-0.8B ở độ chính xác 4-bit để huấn luyện tiết kiệm bộ nhớ hơn, thiết lập tokenizer, và tải một tập con nhỏ của AG News cho huấn luyện và đánh giá.

Tải Qwen3.5-0.8B với lượng tử hóa 4-bit

Chúng ta bắt đầu bằng việc tải Qwen3.5-0.8B với lượng tử hóa 4-bit bằng BitsAndBytes. Cách này giảm mức dùng bộ nhớ và giúp mô hình thực tiễn hơn trong môi trường notebook Kaggle.

model_id = "Qwen/Qwen3.5-0.8B"

bnb_config = BitsAndBytesConfig(
  load_in_4bit=True,
  bnb_4bit_quant_type="nf4",
  bnb_4bit_compute_dtype=torch.bfloat16
)

model = AutoModelForCausalLM.from_pretrained(
  model_id,
  quantization_config=bnb_config,
  device_map="auto",
  dtype=torch.bfloat16
)

Tải tokenizer

Tiếp theo, chúng ta tải tokenizer cho cùng mô hình. Chúng ta cũng đặt token đệm là token kết thúc chuỗi để mô hình xử lý đúng các đầu vào đã đệm trong quá trình huấn luyện và sinh văn bản.

tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token

model.config.pad_token_id = tokenizer.eos_token_id
model.generation_config.pad_token_id = tokenizer.eos_token_id

Tải bộ dữ liệu AG News

Cuối cùng, chúng ta tải bộ dữ liệu AG News và tạo các tập huấn luyện và kiểm thử nhỏ hơn cho hướng dẫn này. Dùng một tập con giúp quy trình nhanh hơn trong khi vẫn đủ dữ liệu để đánh giá tác động của tinh chỉnh.

dataset = load_dataset("ag_news")

train_dataset = dataset["train"].select(range(2500))
test_dataset = dataset["test"].select(range(200))

3. Định dạng prompt và đánh giá đường cơ sở

Trước khi tinh chỉnh, chúng ta cần xác định cách mô hình nhìn nhận tác vụ và đo lường mức độ hiệu quả ở trạng thái ban đầu. 

Trong phần này, chúng ta sẽ tạo một prompt dạng hướng dẫn cho phân loại tin tức, trích xuất dự đoán từ đầu ra của mô hình, chạy thử suy luận mẫu và đánh giá mô hình gốc trên tập kiểm thử trước khi huấn luyện.

Tạo prompt hướng dẫn

Chúng ta bắt đầu bằng cách định nghĩa tên nhãn và xây dựng prompt yêu cầu mô hình phân loại một bài báo. Prompt được viết để mô hình chỉ trả về nhãn dạng số, giúp việc phân tích đầu ra dễ dàng hơn khi đánh giá.

labels = ['World','Sports','Business','Sci/Tech']

def build_prompt(text):

    return f"""
Classify the news article.

Article:
{text}

Return ONLY the number of the correct label.

0 = World
1 = Sports
2 = Business
3 = Sci/Tech

Answer:
"""

Trích xuất dự đoán từ đầu ra của mô hình

Tiếp theo, chúng ta tạo một hàm trợ giúp nhỏ để trích xuất nhãn dự đoán từ văn bản sinh ra. Hàm này loại bỏ mọi token lập luận thừa và trả về nhãn cuối cùng dưới dạng số nguyên.

import re

def extract_label(text):

   text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
   matches = re.findall(r"[0-3]", text)

   if matches:
       return int(matches[-1])

   return -1

Chạy suy luận mẫu

Trước khi đánh giá trên toàn bộ tập kiểm thử, chúng ta thử trên một ví dụ đơn lẻ. Điều này giúp xem nội dung bài báo, kiểm tra nhãn đúng và quan sát dự đoán của mô hình trước khi tinh chỉnh.

sample = train_dataset[10]

sample_text = sample["text"]
sample_label = sample["label"]

print("Ground truth label:", sample_label)
print("Sample text:")
print(sample_text[:300])

Đầu ra cho thấy nhãn đúng là 2, tương ứng với Business.

Ground truth label: 2
Sample text:
Oil and Economy Cloud Stocks' Outlook  NEW YORK (Reuters) - Soaring crude prices plus worries  about the economy 
and the outlook for earnings are expected to  hang over the stock market next week during the depth of the  summer doldrums.

Tiếp theo, chúng ta định dạng prompt, truyền vào mô hình và tạo dự đoán.

prompt = build_prompt(sample_text)

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

with torch.inference_mode():
    outputs = model.generate(
        **inputs,
        max_new_tokens=5,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id
    )

prediction = tokenizer.decode(outputs[0], skip_special_tokens=True)

print("Model prediction (before training):")
print(extract_label(prediction))

Mô hình cũng dự đoán 2, tức phân loại đúng ví dụ này. Điều này cho thấy định dạng prompt và pipeline dự đoán đang hoạt động như mong đợi.

Model prediction (before training):
2

Đánh giá mô hình gốc trước tinh chỉnh

Giờ chúng ta đánh giá mô hình gốc trên tập kiểm thử để thiết lập đường cơ sở. Đây là điểm tham chiếu để so sánh hiệu năng trước và sau tinh chỉnh.

def evaluate_model(dataset):

    preds = []
    refs = []

    model.eval()

    for example in tqdm(dataset):

        text = example["text"]
        label = example["label"]

        prompt = build_prompt(text)

        inputs = tokenizer(prompt, return_tensors="pt", truncation=True)
        inputs = {k: v.to("cuda") for k, v in inputs.items()}

        with torch.inference_mode():

            outputs = model.generate(
                **inputs,
                max_new_tokens=5,
                do_sample=False,
                pad_token_id=tokenizer.eos_token_id
            )

        prediction = tokenizer.decode(outputs[0], skip_special_tokens=True)

        pred_label = extract_label(prediction)

        preds.append(pred_label)
        refs.append(label)

    acc = accuracy_score(refs, preds)
    f1 = f1_score(refs, preds, average="weighted")

    print("Accuracy:", acc)
    print("F1:", f1)


print('Pre-fine-tuning evaluation')
evaluate_model(test_dataset)

Đầu ra cho thấy độ chính xác 0.52 và điểm F1 có trọng số là 0.4589. Các kết quả đường cơ sở này cho thấy mô hình đã có một số khả năng thực hiện tác vụ, đồng thời vẫn còn dư địa rõ ràng để cải thiện thông qua tinh chỉnh.

Pre-fine-tuning evaluation
Accuracy: 0.52
F1: 0.45889163289429247

4. Tinh chỉnh Qwen3.5 với QLoRA

Sau khi đã có đường cơ sở, chúng ta có thể tinh chỉnh mô hình cho tác vụ phân loại tin tức. Trong phần này, chúng ta sẽ định dạng dữ liệu huấn luyện, cấu hình bộ chuyển tiếp LoRA, đặt thiết lập huấn luyện, huấn luyện mô hình và lưu bộ chuyển tiếp cuối cùng để dùng sau.

Chuẩn bị dữ liệu huấn luyện

Đầu tiên, chúng ta định dạng mỗi ví dụ huấn luyện để khớp với cấu trúc prompt dùng trong suy luận. Chúng ta nối nhãn đúng vào cuối prompt để mô hình học cách sinh câu trả lời đúng trong quá trình tinh chỉnh.

def format_train(example):
    prompt = build_prompt(example['text'])
    answer = str(example['label'])
    return {'text': prompt + ' ' + answer}

train_dataset = train_dataset.map(format_train)

Cấu hình bộ chuyển tiếp LoRA

Tiếp theo, chúng ta định nghĩa cấu hình LoRA. Cấu hình này cho biết các lớp nào sẽ được thích ứng trong quá trình tinh chỉnh, cho phép huấn luyện một tập nhỏ tham số bổ sung thay vì cập nhật toàn bộ mô hình.

lora_config = LoraConfig(
    r=16,
    lora_alpha=16,
    lora_dropout=0,
    bias='none',
    task_type='CAUSAL_LM',
    target_modules=[
        'q_proj','k_proj','v_proj','o_proj',
        'gate_proj','up_proj','down_proj'
    ]
)

Đặt cấu hình huấn luyện

Sau đó, chúng ta đặt các tham số huấn luyện cho tinh chỉnh có giám sát. Các thiết lập này kiểm soát số ví dụ được xử lý mỗi lần, cách tích lũy gradient, thời lượng huấn luyện và nơi lưu tệp đầu ra.

training_args = SFTConfig(
    output_dir="./qwen35-lora",
    per_device_train_batch_size=8,
    gradient_accumulation_steps=2,
    learning_rate=2e-4,
    num_train_epochs=1,
    logging_steps=10,
    bf16=True,
    dataset_text_field="text",
    packing=False,
)

Huấn luyện mô hình

Giờ chúng ta khởi tạo trainer với mô hình, bộ dữ liệu, cấu hình LoRA, thiết lập huấn luyện và tokenizer. Sau đó bắt đầu tinh chỉnh mô hình trên tập huấn luyện AG News đã định dạng.

trainer = SFTTrainer(
    model=model,
    train_dataset=train_dataset,
    peft_config=lora_config,
    args=training_args,
    processing_class=tokenizer
)
trainer.train()

Đầu ra: 

TrainOutput(global_step=157, training_loss=1.9094241804378047, metrics={'train_runtime': 616.477, 'train_samples_per_second': 4.055, 'train_steps_per_second': 0.255, 'total_flos': 1041693973114368.0, 'train_loss': 1.9094241804378047})

Lưu bộ chuyển tiếp đã huấn luyện

Sau khi huấn luyện kết thúc, chúng ta lưu bộ chuyển tiếp LoRA và tokenizer. Điều này cho phép tải lại bộ chuyển tiếp đã tinh chỉnh sau này để đánh giá, chia sẻ hoặc xuất bản lên Hugging Face.

trainer.model.save_pretrained("qwen35-small-news-class")
tokenizer.save_pretrained("qwen35-small-news-class")

5. Đánh giá mô hình đã tinh chỉnh

Sau khi huấn luyện, chúng ta tải lại mô hình gốc và gắn bộ chuyển tiếp LoRA đã lưu. Nhờ vậy, chúng ta có thể chạy đánh giá bằng trọng số đã tinh chỉnh và so sánh với đường cơ sở trước đó.

Tải lại mô hình gốc và gắn bộ chuyển tiếp LoRA

Trước tiên, chúng ta tải lại mô hình Qwen3.5 gốc, rồi gắn bộ chuyển tiếp LoRA đã tinh chỉnh được lưu trong thư mục làm việc của Kaggle. Sau đó chuyển mô hình sang chế độ đánh giá và xem tóm tắt tham số có thể huấn luyện.

from transformers import AutoModelForCausalLM
base_model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    dtype=torch.bfloat16
)


from peft import PeftModel

model = PeftModel.from_pretrained(
    base_model,
    "/kaggle/working/qwen35-small-news-class"
)

model.eval()
model.print_trainable_parameters()

Đầu ra cho thấy không còn tham số có thể huấn luyện ở giai đoạn này vì quá trình huấn luyện đã hoàn tất và chúng ta đang dùng bộ chuyển tiếp đã lưu cho suy luận và đánh giá.

trainable params: 0 || all params: 758,782,784 || trainable%: 0.0000

Đánh giá mô hình đã tinh chỉnh

Tiếp theo, chúng ta chạy lại hàm đánh giá trên tập kiểm thử. Nhờ đó, chúng ta đo được mức cải thiện của mô hình sau tinh chỉnh.

print('Post-fine-tuning evaluation')
evaluate_model(test_dataset)

Đầu ra cho thấy độ chính xác 0.865 và điểm F1 có trọng số 0.8661. So với đường cơ sở, điều này thể hiện mức cải thiện lớn sau khi tinh chỉnh.

Post-fine-tuning evaluation
Accuracy: 0.865
F1: 0.8660926258753361

So sánh kết quả

Giờ chúng ta có thể so sánh hiệu năng trước và sau tinh chỉnh. Cả độ chính xác và điểm F1 đều cải thiện đáng kể, cho thấy tinh chỉnh bằng QLoRA giúp mô hình thích ứng tốt với tác vụ phân loại tin tức.

Như có thể thấy, tinh chỉnh Qwen3.5 Small với QLoRA cải thiện đáng kể hiệu năng phân loại.

6. Xuất bản mô hình lên Hugging Face

Sau khi đánh giá xong, chúng ta có thể tải lên bộ chuyển tiếp đã tinh chỉnh và tokenizer lên Hugging Face. Điều này giúp mô hình dễ tái sử dụng, chia sẻ và nạp trong các dự án sau mà không cần lặp lại toàn bộ quá trình huấn luyện.

model.push_to_hub("kingabzpro/qwen35-small-news-class")
tokenizer.push_to_hub("kingabzpro/qwen35-small-news-class")

Sau khi tải lên hoàn tất, mô hình sẽ có tại:

Model:
https://huggingface.co/kingabzpro/qwen35-small-news-class

Nguồn: kingabzpro/qwen35-small-news-class

Notebook Kaggle cho hướng dẫn này cũng sẵn có. Tôi khuyên bạn chỉ sử dụng khi gặp vấn đề khi tái hiện các bước ở trên. Bạn cũng có thể sao chép notebook và chạy trên hệ thống của riêng bạn, nhưng nhớ cập nhật tên người dùng và token Hugging Face cho khớp với tài khoản của bạn.

7. Kết luận

Trong hướng dẫn này, chúng ta đã tinh chỉnh Qwen3.5-0.8B với QLoRA cho phân loại tin tức và đạt kết quả mạnh mẽ với thiết lập rất gọn nhẹ. Chỉ sau một epoch trên một tập dữ liệu nhỏ, độ chính xác tăng từ 0.52 lên 0.865, và F1 có trọng số tăng từ 0.4589 lên 0.8661. 

Với một mô hình nhỏ như vậy, điều đáng ngạc nhiên nhất là: chúng ta không cần mô hình lớn, dữ liệu khổng lồ hay thời gian huấn luyện dài để có kết quả hạ nguồn tốt.

Điều làm cho thiết lập này hữu dụng hơn là tính thực tiễn. Qwen mô tả mô hình 0.8B là phù hợp với thử nghiệm nhanh và tinh chỉnh theo tác vụ, còn QLoRA giữ mức dùng bộ nhớ thấp bằng cách huấn luyện các bộ chuyển tiếp trên nền mô hình gốc 4-bit cố định. Nghĩa là đây không chỉ là quy trình notebook đám mây. Nó cũng thực tế cho việc thử nghiệm trên GPU tiêu dùng và laptop nhỏ hơn.

Một lý do khác khiến tôi hứng thú với mô hình này là họ Qwen3.5 hỗ trợ cả tinh chỉnh văn bản và thị giác. Vì vậy, dù ở đây chúng ta dùng cho phân loại văn bản, cùng ý tưởng có thể mở rộng sang phân loại ảnh, chuyển ảnh thành văn bản và các tác vụ văn bản-văn bản. Điều đó khiến một mô hình nhỏ như thế này trở thành lựa chọn rất thực tiễn khi bạn muốn thử ý tưởng nhanh, tinh chỉnh rẻ và vẫn giữ triển khai gọn nhẹ.

Tôi cũng khuyên bạn xem thêm các tài nguyên khác của chúng tôi, bao gồm hướng dẫn về Qwen3.5 và hướng dẫn chạy Qwen3.5 cục bộ trên một GPU.