Bài 16: Transformers library — load và chạy model trong 5 dòng code

Sau bài học, bạn sẽ:

• Cài đặt được transformers kèm backend PyTorch.
• Load và generate một câu từ Llama-3.2-1B trong 5 dòng code.
• Biết các module con của thư viện và chức năng từng phần.
• Phân biệt Auto class với class architecture-specific, biết khi nào nên dùng cái nào.
• Chọn đúng AutoModelFor* cho từng task: generation, classification, seq2seq, NER, QA.
• Điều chỉnh các tham số sinh văn bản (temperature, top_p, do_sample, max_new_tokens).
• Quản lý device (CPU / GPU đơn / multi-GPU) và dtype (float32, float16, bfloat16).
• Quantize model xuống 4-bit để chạy SLM trên máy ít VRAM.
• Apply chat template, save / load model local, cấu hình cache, hiểu rủi ro trust_remote_code.
• Stream từng token ra terminal khi generate.

Bài này tập trung vào core API. Pipeline API (mức trừu tượng cao hơn) ở Bài 17; AutoModel / AutoTokenizer deep dive ở Bài 18; sampling strategy (greedy, beam, top-k, top-p) ở Bài 30.

transformers là thư viện flagship của Hugging Face — phát hành 2018 dưới tên pytorch-pretrained-bert, đổi tên năm 2019. Bản chất: tập hợp implementation Python của hầu hết kiến trúc Transformer (BERT, GPT-2, T5, Llama, Mistral, Qwen, Whisper, CLIP…) cùng tiện ích load checkpoint trực tiếp từ Hub.

Đặt cạnh các thư viện anh em:

• huggingface_hub: client cho Hub (download / upload file, token, repo). transformers gọi nó ở dưới.
• tokenizers: tokenizer cài bằng Rust, được wrap bởi AutoTokenizer (Bài 11 đã đề cập).
• datasets: dataset (Bài 20).
• accelerate: hỗ trợ multi-GPU và mixed precision.
• peft, trl: fine-tune (Module 8).
• diffusers: model diffusion ảnh / video (không trong scope module này).

Khi bạn code from transformers import ... thì gần như chắc chắn các thư viện trên cũng sẽ xuất hiện ở project nào đó về sau.

Cài bản tối thiểu cho inference với PyTorch:

pip install transformers torch

Các extras hay dùng:

# Cài kèm PyTorch (alias gọn)
pip install "transformers[torch]"

# accelerate cho device_map="auto" và multi-GPU
pip install accelerate

# bitsandbytes cho quantization 4-bit / 8-bit (CUDA)
pip install bitsandbytes

# datasets nếu cần dữ liệu
pip install datasets

PyTorch phụ thuộc vào CUDA driver, nên trên máy có GPU NVIDIA nên cài theo hướng dẫn ở pytorch.org (chọn đúng CUDA version) thay vì pip install torch mặc định. Trên Mac Apple Silicon, PyTorch dùng MPS backend; bitsandbytes hiện chưa hỗ trợ đầy đủ — nên test trên Linux/Windows + CUDA cho quantization.

Ví dụ tối giản với Llama-3.2-1B (gated — cần accept terms như Bài 15 đã hướng dẫn):

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B")
inputs = tokenizer("Hello, AI!", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(outputs[0]))

Năm bước tương ứng với năm dòng:

1. Load model: tải weights về cache, build module PyTorch.
2. Load tokenizer: tải vocab + config tokenizer của cùng model.
3. Tokenize input: chuyển string thành tensor input_ids (return_tensors="pt" = PyTorch).
4. Generate: model sinh tối đa 50 token mới.
5. Decode: chuyển tensor token ngược lại thành string.

Nếu không muốn dùng model gated, đổi sang model open hơn như Qwen/Qwen2.5-0.5B hoặc microsoft/Phi-3.5-mini-instruct — pattern code không đổi.

Khi clone transformers, một số module con đáng nhớ:

• transformers.models.* — mỗi sub-package là một architecture: models.bert, models.llama, models.qwen2, models.t5… Bên trong gồm modeling_*.py (PyTorch model), configuration_*.py (config), tokenization_*.py (tokenizer).
• transformers.pipelines — Pipeline API mức cao, gói tokenize + forward + postprocess vào 1 lệnh (Bài 17).
• transformers.generation — utility cho text generation: GenerationConfig, các logits processor, các stopping criteria, streamer.
• transformers.trainer và transformers.training_args — vòng lặp training chuẩn, dùng cho fine-tune (gặp lại ở Module 8).
• Các Auto class (AutoModel, AutoTokenizer, AutoConfig…) nằm ở top-level transformers và dispatch về module con tương ứng dựa vào config của repo.

Cấu trúc theo nguyên tắc "single file per model": mỗi architecture có một file modeling_*.py tự chứa code; ít kế thừa chéo. Lợi ích là dễ đọc và copy-paste khi cần custom; chi phí là code lặp giữa các file.

Hai cách load tương đương:

# Cách 1: architecture-specific class
from transformers import LlamaForCausalLM, LlamaTokenizer
model = LlamaForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")

# Cách 2: Auto class
from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")

Khác biệt:

• Specific class (LlamaForCausalLM, BertForSequenceClassification): code phải khớp đúng architecture của repo, đổi model là đổi import.
• Auto class (AutoModelForCausalLM): đọc config.json trong repo, tự tìm class phù hợp. Đổi từ Llama sang Mistral không phải sửa import.

Khuyến nghị: dùng Auto class trong hầu hết tình huống. Specific class chỉ cần khi muốn IDE autocomplete chính xác hoặc khi gọi method riêng của architecture đó (hiếm). Bài 18 deep dive vào Auto API và cách from_pretrained dispatch.

Mỗi Auto class tương ứng một loại "head" trên backbone:

• AutoModelForCausalLM — text generation kiểu GPT, Llama, Mistral, Qwen.
• AutoModelForSeq2SeqLM — encoder-decoder: T5, BART, Marian (translation, summarization).
• AutoModelForSequenceClassification — sentiment, topic, intent.
• AutoModelForTokenClassification — NER, POS tagging.
• AutoModelForQuestionAnswering — span-based QA (SQuAD style).
• AutoModelForMaskedLM — BERT-style MLM (predict token bị mask).
• AutoModel — backbone trần, không có head. Dùng khi muốn lấy hidden states / embedding để gắn head riêng.

Chọn sai class thường vẫn load được weights nhưng head có thể bị init random — accuracy sẽ rất thấp. Quy tắc: model card thường ghi rõ class phù hợp; nếu không có, suy từ task tag trên Hub.

Method model.generate() nhận hàng chục tham số. Bộ thường dùng:

outputs = model.generate(
    **inputs,
    max_new_tokens=100,
    temperature=0.7,
    top_p=0.9,
    do_sample=True,
    num_return_sequences=1,
)

• max_new_tokens: số token sinh thêm tối đa (không tính prompt).
• do_sample=True: bật sampling. Nếu False, dùng greedy / beam — output deterministic.
• temperature: nhỏ (vd 0.1) → output đậm chất "chắc chắn"; lớn (vd 1.0) → đa dạng hơn.
• top_p: nucleus sampling — chỉ giữ phần token có xác suất tích luỹ ≤ p.
• num_return_sequences: số chuỗi sinh ra trong cùng một call.

Tham số khác hay gặp: top_k, repetition_penalty, num_beams, eos_token_id, pad_token_id, min_new_tokens. Có thể đóng gói thành GenerationConfig để tái sử dụng. Bài 30 sẽ phân tích chi tiết từng sampling strategy.

Cách thủ công: chuyển model + input cùng device.

model.to("cuda")
inputs = {k: v.to("cuda") for k, v in inputs.items()}
outputs = model.generate(**inputs, max_new_tokens=50)

Cách tự động qua accelerate — phù hợp khi có nhiều GPU hoặc khi model lớn hơn 1 GPU:

model = AutoModelForCausalLM.from_pretrained(
    "model-name",
    device_map="auto",
    torch_dtype="auto",
)

• device_map="auto": chia layer giữa các GPU; nếu thiếu VRAM tràn xuống CPU RAM, cuối cùng là disk.
• torch_dtype="auto": dùng dtype được khuyến nghị trong config.json (Llama / Mistral mặc định là bfloat16).

Trên Mac Apple Silicon, có thể thử device_map="mps" hoặc model.to("mps"); trên CPU thuần là "cpu" — chạy được nhưng chậm hơn nhiều lần GPU.

• float32 (fp32) — 4 byte / tham số. Là default khi torch_dtype không truyền. Ổn định nhất; tốn RAM gấp đôi fp16.
• float16 (fp16) — 2 byte / tham số. Nhanh trên GPU NVIDIA từ Turing trở lên. Range hẹp, dễ overflow nếu activation lớn.
• bfloat16 (bf16) — 2 byte / tham số. Cùng range với fp32 (8 bit mũ), kém chính xác hơn fp16 ở phần phân số nhưng an toàn hơn cho training. Yêu cầu GPU Ampere (A100, RTX 30xx) trở lên.

Mặc định khuyến nghị cho Llama, Mistral, Qwen 2024+ là bfloat16:

import torch
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-1B",
    torch_dtype=torch.bfloat16,
)

Quy tắc tay nhanh để ước lượng VRAM cho inference: VRAM ≈ số_tham_số × byte_mỗi_tham_số × 1.2 (hệ số 1.2 cho activation). Llama-3.2-1B ở bf16: 1B × 2B × 1.2 ≈ 2.4 GB.

Khi VRAM hạn chế (GPU 6-8 GB, hoặc muốn nhồi nhiều request), nén weight xuống 8-bit hoặc 4-bit qua thư viện bitsandbytes:

pip install bitsandbytes

import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

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

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-3B",
    quantization_config=bnb_config,
    device_map="auto",
)

Giải thích:

• load_in_4bit=True: weight giữ ở 4-bit, giảm RAM khoảng 4 lần so với fp16.
• bnb_4bit_compute_dtype: tính toán matmul ở bfloat16 (dequant tại chỗ), giữ accuracy.
• bnb_4bit_quant_type="nf4": NormalFloat4, đề xuất bởi paper QLoRA (Dettmers 2023, arXiv:2305.14314). Lựa chọn khác: "fp4".
• load_in_8bit=True: bản 8-bit, giảm RAM khoảng 2 lần — đơn giản hơn 4-bit, tổn thất accuracy ít hơn.

Hạn chế: bitsandbytes yêu cầu CUDA; chậm hơn fp16 thuần khi GPU dư VRAM; không train trực tiếp được (cần PEFT / QLoRA).

Khi chỉ inference (không train), nên bật eval mode và tắt autograd để tiết kiệm RAM và thời gian:

import torch

model.eval()
with torch.no_grad():
    outputs = model(**inputs)

• model.eval(): tắt dropout, fix batch norm (nếu có) — bắt buộc khi inference.
• torch.no_grad(): không lưu computation graph, giảm RAM đáng kể.
• Method generate() tự bọc trong no_grad, nên khi gọi model.generate() bạn không cần with ngoài.

PyTorch 2.x còn có torch.inference_mode() nhẹ hơn no_grad chút (không cho phép switch sang autograd ngay sau đó) — phù hợp khi pipeline inference thuần.

Model instruct / chat được train với một format prompt cố định (special token, role marker). Mỗi model một template — viết tay rất dễ sai. transformers cung cấp apply_chat_template:

messages = [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Hello!"},
]

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

• tokenize=False → trả về string prompt; True → trả thẳng input_ids.
• add_generation_prompt=True: thêm marker báo "đến lượt assistant nói" — không có thì model có thể bị "treo" sau khi sinh tag của user.

Template được lưu trong tokenizer_config.json (key chat_template) dưới dạng Jinja2 — bạn có thể override nếu cần, nhưng thường không nên. Nguyên tắc: dùng đúng template tác giả release.

Lưu vào thư mục riêng (vd sau fine-tune, hoặc để chạy offline):

model.save_pretrained("./local_model")
tokenizer.save_pretrained("./local_model")

Load lại:

model = AutoModelForCausalLM.from_pretrained("./local_model")
tokenizer = AutoTokenizer.from_pretrained("./local_model")

Thư mục output gồm: config.json, model.safetensors (hoặc nhiều shard model-00001-of-000xx.safetensors + model.safetensors.index.json nếu model lớn), tokenizer.json, tokenizer_config.json, special_tokens_map.json, optional generation_config.json.

Pattern này hữu ích cho: airgapped server, đóng gói model vào Docker image, snapshot reproducible cho experiment.

Mặc định cache nằm ở ~/.cache/huggingface/hub/. Mỗi repo là một thư mục với commit hash; file weights được symlink để tiết kiệm dung lượng khi reuse.

Một số biến môi trường thường gặp:

• HF_HOME — đổi gốc thư mục cache (vd HF_HOME=/data/hf_cache).
• HF_HUB_CACHE — chỉ đổi sub-folder cache của Hub (giữ token vẫn ở vị trí cũ).
• HF_HUB_OFFLINE=1 — bắt thư viện chỉ dùng cache, không gọi mạng. Hữu ích khi reproducible / chạy trong CI cô lập.
• TRANSFORMERS_OFFLINE=1 — phiên bản cũ tương đương, vẫn được hỗ trợ.

Quản lý cache qua CLI: huggingface-cli scan-cache để xem dung lượng, huggingface-cli delete-cache để xoá có chọn lọc.

Một số model dùng architecture chưa được merge chính thức vào transformers; tác giả ship kèm file modeling_*.py trong repo Hub. Để load, phải bật cờ:

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen-VL-Chat",
    trust_remote_code=True,
)

CẢNH BÁO: cờ này khiến Python thực thi code Python trong repo. Repo độc hại có thể chèn malware. Quy tắc:

• Chỉ bật với repo từ tổ chức đã verify (vd Qwen, deepseek-ai, microsoft).
• Pin revision để code không đổi sau khi review.
• Trong môi trường production, ưu tiên model đã được tích hợp chính thức (Llama, Mistral, Gemma, Qwen 2 / 2.5 / 3 đa số không cần cờ này từ transformers >= 4.40).

Cùng một pattern load → tokenize → forward → postprocess dùng cho nhiều task:

• Text classification: AutoModelForSequenceClassification + model(**inputs).logits.argmax(-1).
• NER: AutoModelForTokenClassification, sau đó map index → label qua id2label.
• Translation, summarization: AutoModelForSeq2SeqLM (T5, BART, Marian) + generate().
• Text generation: AutoModelForCausalLM (GPT, Llama, Mistral, Qwen) + generate().
• Embedding: thường dùng wrapper sentence-transformers — pool mean / cls của AutoModel rồi normalize. Bài về vector DB ở Module 6 sẽ chi tiết.

Pipeline API (Bài 17) đóng gói các pattern trên thành 1 dòng — phù hợp khi không cần tuỳ biến sâu. Khi cần điều khiển batching, dtype, sampling cụ thể thì viết tay với Auto class trực tiếp.

transformers hỗ trợ ba backend: PyTorch (mặc định), TensorFlow (class với prefix TF: TFAutoModel), JAX/Flax (prefix Flax: FlaxAutoModel). Cùng một checkpoint thường có ba phiên bản weight: pytorch_model.bin hoặc model.safetensors, tf_model.h5, flax_model.msgpack.

Có thể convert qua lại:

from transformers import TFAutoModel, AutoModel

# PyTorch → TensorFlow
pt_model = AutoModel.from_pretrained("bert-base-uncased")
tf_model = TFAutoModel.from_pretrained("bert-base-uncased", from_pt=True)

Thực tế 2024-2026, đại đa số model mới release chỉ có phiên bản PyTorch. TensorFlow / JAX vẫn được giữ cho user cũ và cho research lab dùng JAX (vd Google). Cho lộ trình này, mặc định PyTorch.

transformers release thường xuyên — gần như mỗi tháng có minor version mới để support model vừa ra mắt. Một số mốc đáng nhớ:

• 4.30+ (2023): hỗ trợ Llama 2, MPT, Falcon.
• 4.34+ (2023): Mistral.
• 4.37+ (2024): Mixtral, Qwen 2.
• 4.40+ (2024): Llama 3, Phi-3.
• 4.43+ (2024): Llama 3.1.
• 4.45+ (cuối 2024): Llama 3.2, Qwen 2.5.
• 4.46-4.49+ (2025): Qwen 3, DeepSeek-V3, hỗ trợ thêm sliding window và Mamba.

Khuyến nghị thực tế: pin version cụ thể trong requirements.txt cho production (vd transformers==4.46.0); lab cá nhân thì update định kỳ pip install -U transformers. Kiểm tra changelog ở github.com/huggingface/transformers/releases trước khi nâng major.

Mặc định generate() trả về toàn bộ output sau khi xong. Với UI chat, người dùng muốn thấy token chảy ra dần — dùng streamer:

from transformers import TextStreamer

streamer = TextStreamer(tokenizer, skip_prompt=True)
model.generate(**inputs, streamer=streamer, max_new_tokens=100)

• TextStreamer: in từng token ra stdout ngay khi sinh.
• TextIteratorStreamer: phiên bản trả về Python iterator — phù hợp khi cần forward token sang FastAPI / SSE / websocket.
• skip_prompt=True: không in lại prompt input, chỉ in token mới.

Bài 33 sẽ deep dive streaming khi build chat app: backpressure, cancel mid-generation, gửi qua SSE / websocket.

Bốn snippet sau gói lại nội dung bài, chạy độc lập sau khi đã pip install -U transformers torch accelerate bitsandbytes và huggingface-cli login.

1. Load Llama-3.2-1B và generate 1 câu.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

MODEL = "meta-llama/Llama-3.2-1B"

tokenizer = AutoTokenizer.from_pretrained(MODEL)
model = AutoModelForCausalLM.from_pretrained(
    MODEL,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

inputs = tokenizer("AI engineer là người", return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=40, do_sample=True, temperature=0.7, top_p=0.9)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

2. Quantize 4-bit và đo RAM.

import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

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

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-3B",
    quantization_config=bnb_config,
    device_map="auto",
)
print("VRAM (MB):", torch.cuda.memory_allocated() / 1024 ** 2)

So với bf16 thuần, 4-bit thường giảm VRAM khoảng 4 lần.

3. Apply chat template.

messages = [
    {"role": "system", "content": "Bạn là trợ lý ngắn gọn."},
    {"role": "user", "content": "Một câu giới thiệu Hugging Face?"},
]

prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=80, do_sample=True, temperature=0.7)
print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))

4. Save / load local.

model.save_pretrained("./local_llama")
tokenizer.save_pretrained("./local_llama")

# lần sau, kể cả không có internet
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("./local_llama")
model = AutoModelForCausalLM.from_pretrained("./local_llama", torch_dtype=torch.bfloat16, device_map="auto")

Bài 1 — Generate với SLM open. Load Qwen/Qwen2.5-0.5B (không gated), generate 5 câu khác nhau cho cùng một prompt bằng cách đổi temperature ở các giá trị 0.2, 0.7, 1.0, 1.3. Ghi nhận sự thay đổi về đa dạng và tính mạch lạc.

Bài 2 — So sánh dtype. Cùng một model (vd Qwen/Qwen2.5-1.5B), load lần lượt ở float32, float16, bfloat16, và 4-bit (bitsandbytes). Đo torch.cuda.memory_allocated() sau mỗi lần load (nhớ del model; torch.cuda.empty_cache() giữa các lần). Lập bảng VRAM.

Bài 3 — Chat template 3 messages. Với model instruct (vd meta-llama/Llama-3.2-1B-Instruct hoặc Qwen/Qwen2.5-1.5B-Instruct), tạo conversation 3 lượt (system → user → assistant_giả_lập → user). Apply chat template, in ra prompt thuần text để thấy special token. Generate response.

Bài 4 — List 5 AutoModel class. Cho 5 task sau, mỗi task ghi rõ AutoModelFor* phù hợp + 1 model trên Hub làm ví dụ: (a) phân loại sentiment EN, (b) NER tiếng Việt, (c) translation EN→FR, (d) extractive QA, (e) generation chat. Verify bằng cách load thật và in type(model).__name__.

Bài 5 — Streaming. Viết script đọc prompt từ stdin, generate với TextStreamer(skip_prompt=True), in từng token ra terminal. Thử với max_new_tokens lớn (vd 300) để cảm nhận tốc độ token/giây trên máy bạn.

• transformers là thư viện Python chính của Hugging Face để load và chạy model từ Hub. Cài bằng pip install transformers torch.
• 5 dòng đủ để load Llama-3.2-1B và generate: load model, load tokenizer, tokenize, generate, decode.
• Cấu trúc: models.*, pipelines, generation, trainer. Mỗi architecture có modeling_*.py tự chứa.
• Auto class (AutoModelForCausalLM…) tự dispatch theo config.json — nên dùng thay cho class architecture-specific.
• Có AutoModelFor* riêng cho từng task: CausalLM, Seq2SeqLM, SequenceClassification, TokenClassification, QuestionAnswering, MaskedLM. AutoModel là backbone trần.
• Generation parameters chính: max_new_tokens, do_sample, temperature, top_p, top_k, repetition_penalty.
• Device management: .to("cuda") thủ công, hoặc device_map="auto" qua accelerate cho multi-GPU.
• dtype: bfloat16 mặc định cho Llama / Mistral / Qwen modern; float16 cho GPU cũ; float32 tốn gấp đôi.
• Quantization 4-bit / 8-bit qua bitsandbytes + BitsAndBytesConfig: giảm RAM ~4 lần, NF4 + bf16 compute là cấu hình phổ biến.
• Inference: model.eval() + torch.no_grad(). generate() tự bọc no_grad.
• Chat template qua tokenizer.apply_chat_template(messages, ..., add_generation_prompt=True).
• Save / load local bằng save_pretrained() / from_pretrained("./local_dir").
• Cache mặc định ở ~/.cache/huggingface/hub/, đổi bằng HF_HOME. HF_HUB_OFFLINE=1 để chạy offline.
• trust_remote_code=True chỉ bật với repo verify; pin revision khi dùng.
• PyTorch là backend mặc định; TensorFlow (TFAutoModel), JAX (FlaxAutoModel) vẫn được hỗ trợ.
• Streaming bằng TextStreamer / TextIteratorStreamer cho UI chat.
• Bài 17 chuyển sang Pipeline API — wrapper 1-dòng-code trên các pattern của bài này.