Hugging Face Hub là nơi phần lớn model open-weight được phát hành, nhưng “tải về rồi chạy” không đủ. Bạn cần biết mình đang tải định dạng nào, tokenizer nào đi kèm, model có vừa VRAM không và giấy phép cho phép gì. Bài này là thao tác đầu tiên trên Hub: cài đúng phiên bản, xác thực, chạy pipeline, đọc tokenizer và hiểu dung lượng thật của một model.
Mục lục
Cập nhật 2026: phiên bản và định dạng đã đổi
- Transformers 5.22.2 (11/2026) là bản hiện hành. Từ v5.0.0 (01/2026), thư viện chỉ còn PyTorch, không còn TensorFlow hay Flax; tokenizer cũng chỉ còn một backend. Hướng dẫn cũ “cài thêm TensorFlow” không còn đúng cho v5.
- huggingface_hub 2.4.0 (10/2026) là SDK trung tâm để tải file, đăng nhập và gọi API. Nhiều thư viện khác dùng lại SDK này, nên cài đúng phiên bản giúp tránh lệch hành vi.
- safetensors là định dạng mặc định trên Hub. File
.binkiểu pickle là legacy; chỉ nên tải từ repo tin cậy và pin revision. - Model card ngày càng đầy đủ hơn, nhưng giấy phép và cờ gated vẫn là thứ bạn phải đọc trước khi tải, không phải sau khi deploy.
Hub có gì và bạn cần gì
Hub chứa bốn loại tài nguyên: models (trọng số, config, tokenizer), datasets (dữ liệu huấn luyện và đánh giá), Spaces (demo Gradio/Streamlit) và docs. Với người mới, bạn chỉ cần hai thứ: một repo model có model card tốt và thư viện Transformers biết cách đọc repo đó.
Mỗi repo là một thư mục Git. Các file quan trọng gồm config.json (kiến trúc), tokenizer.json hoặc tokenizer_config.json, model.safetensors (hoặc nhiều shard cộng model.safetensors.index.json) và README.md — chính là model card. Nếu repo có generation_config.json, đó là mặc định cho sinh văn bản; đừng giả định tham số sinh do bạn kiểm soát hoàn toàn.
Cài đặt đúng phiên bản
Tạo virtual environment trước, rồi cài Torch phù hợp với máy. Đừng copy lệnh CUDA 11.8 từ bài cũ; phiên bản wheel phải khớp driver và GPU của bạn. Trên máy chỉ có CPU, bản wheel CPU là đủ.
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install torch
pip install "transformers==5.22.2" "huggingface_hub==2.4.0"
safetensors được kéo theo làm dependency; bạn không cần cài riêng. Không cần cài tensorflow, flax hay sentencepiece cho mọi model — chỉ cài thêm khi model card yêu cầu. Nếu dùng GPU, kiểm tra torch.cuda.is_available() trước khi tin rằng pipeline đang chạy trên GPU.
Xác thực và model gated
Nhiều model công khai không cần token. Model gated thì cần: bạn vào trang model, chấp nhận điều khoản, rồi dùng token có quyền đọc. Cách sạch nhất là đặt biến môi trường HF_TOKEN; các thư viện của Hugging Face tự đọc biến này.
export HF_TOKEN="hf_xxx" # PowerShell: $env:HF_TOKEN = "hf_xxx"
Nếu muốn lưu token vào máy, dùng huggingface_hub.login() một lần. Token nên có scope read, không dùng token ghi cho ứng dụng chỉ đọc model. Không commit token vào repo, không đưa token xuống browser. Khi gặp 401 hoặc 403, kiểm tra ba thứ: token có tồn tại, tài khoản đã chấp nhận điều khoản model chưa, và token có quyền với repo đó không.
Pipeline đầu tiên
pipeline gói ba bước: tokenize input, chạy model, hậu xử lý output. Đây là cách nhanh nhất để kiểm tra một model có chạy được trên máy bạn không. Ví dụ dưới đây dùng một model phân loại cảm xúc tiếng Anh nhỏ; lần chạy đầu sẽ tải trọng số về cache.
from transformers import pipeline
model_id = "distilbert-base-uncased-finetuned-sst-2-english"
classifier = pipeline(
task="sentiment-analysis",
model=model_id,
device=-1, # -1 = CPU; 0 = GPU đầu tiên
)
texts = [
"I love this movie!",
"The service was slow and rude.",
"It is okay, nothing special.",
]
for text, pred in zip(texts, classifier(texts)):
print(f"{pred['label']:>8} {pred['score']:.4f} {text}")
Kết quả là nhãn và điểm số, không phải “cảm xúc” theo nghĩa bạn mong đợi. Model này được huấn luyện trên tiếng Anh, nên đừng dùng nó để đánh giá chất lượng tiếng Việt. Muốn thử tiếng Việt, tìm model có ghi ngôn ngữ phù hợp trong model card; bài sau đi sâu vào cách tìm và vet model.
Hai tham số cần nhớ: device=-1 chạy CPU, device=0 chạy GPU đầu tiên. Nếu không có GPU mà đặt device=0, pipeline sẽ lỗi hoặc rơi về CPU tùy bản. Với batch lớn, truyền cả list như trên để pipeline tự xử lý theo batch; với văn bản dài, đặt truncation=True và max_length rõ ràng thay vì để mặc định.
Pipeline thực sự làm gì
Tokenizer chuyển văn bản thành input_ids và attention_mask. Mỗi token là một số nguyên; attention_mask cho model biết token nào là padding để bỏ qua. Model nhận các tensor này và trả logits; pipeline lấy softmax, ánh xạ về nhãn rồi trả dictionary.
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained(model_id)
batch = tokenizer(
texts,
padding=True,
truncation=True,
max_length=128,
return_tensors="pt",
)
print(batch["input_ids"].shape)
print(tokenizer.convert_ids_to_tokens(batch["input_ids"][0]))
print(tokenizer.decode(batch["input_ids"][0], skip_special_tokens=True))
Ba điều dễ sai. Thứ nhất, tokenizer phải được load từ cùng repo và cùng revision với model; trộn tokenizer của model A với trọng số model B thường không báo lỗi ngay mà cho kết quả vô nghĩa. Thứ hai, max_length quá nhỏ sẽ cắt mất thông tin; quá lớn chỉ tốn bộ nhớ. Thứ ba, token đặc biệt như [CLS], [SEP], <s> phải được giữ đúng theo model card, không tự thêm bớt.
safetensors và vấn đề pickle
.safetensors lưu tensor kèm header mô tả shape và dtype, không chứa mã Python thi hành khi load. Nó cũng memory-map được, nên load nhanh và ít rủi ro hơn pickle. Đây là lý do định dạng này được đặt làm mặc định.
File .bin là pickle của PyTorch. Về lý thuyết, một pickle độc có thể chạy lệnh khi bạn load. Vì vậy chỉ tải .bin từ repo bạn tin, và pin revision về một commit cụ thể. Với trust_remote_code=True, bạn đang cho repo chạy code Python trên máy mình; chỉ dùng khi model card yêu cầu rõ và bạn đã đọc code. Nếu bắt buộc, hãy pin revision và cô lập môi trường.
Với model lớn, trọng số thường chia thành nhiều shard. File model.safetensors.index.json ánh xạ tên tensor sang shard; from_pretrained đọc index này. Đừng tải thủ công một shard rồi tự ghép nếu không có lý do; để thư viện làm.
Kích thước model và quantization
Công thức thô: số tham số nhân số byte mỗi tham số. Một model 7B ở FP16 cần khoảng 14GB chỉ cho trọng số; batch, activation và KV cache cộng thêm. Đây là lý do “7B” không có nghĩa là “chạy được trên GPU 16GB” trong mọi cấu hình.
| Độ chính xác | Byte / tham số | Trọng số 7B |
|---|---|---|
| FP32 | 4 | ~28GB |
| BF16 / FP16 | 2 | ~14GB |
| INT8 | 1 | ~7GB |
| INT4 | ~0,5 | ~3,5GB |
Với model 27B, FP16 cần khoảng 54GB trọng số, chưa tính overhead. Bản 4-bit còn khoảng 13,5GB, có thể vừa GPU 24GB nhưng phải thử với context và batch thật. Quantization không miễn phí: nó đổi chất lượng. Hãy chạy lại vài case đại diện trước khi chấp nhận bản 4-bit cho production.
Có ba nhóm định dạng quantization thường gặp: GGUF cho llama.cpp/Ollama, GPTQ/AWQ cho GPU, và các định dạng 4-bit/8-bit trong hệ sinh thái Transformers. Đừng trộn định dạng: GGUF không load bằng transformers.pipeline theo cách thông thường, còn GPTQ cần thư viện đi kèm. Chọn theo engine bạn sẽ dùng, không chỉ theo dung lượng file.
CPU hay GPU
CPU đủ cho model nhỏ, batch offline và thử nghiệm. Với model 7B trở lên, CPU chạy được nhưng chậm; đừng kết luận model kém khi mới đo trên CPU. GPU cần thiết khi bạn có người dùng chờ, cần throughput hoặc context dài. Kiểm tra VRAM thực tế bằng nvidia-smi trước khi mua model lớn hơn.
device_map="auto" giúp chia model qua nhiều GPU hoặc offload sang CPU, nhưng cần accelerate và có thể làm chậm đáng kể. Với pipeline đơn giản, device là đủ. Với model 27B trên một GPU 24GB, quantization là cách thực tế hơn là trông chờ offload thần kỳ.
Giấy phép trên model card
Mỗi model card có trường license, nhưng không phải model nào cũng dùng giấy phép bạn đoán từ tên họ. Apache 2.0 và MIT cho phép dùng thương mại rộng rãi; modified-MIT của Mistral cấm MaaS nếu không có thỏa thuận; Qwen3.8 bản lớn dùng giấy phép riêng; Llama 4 Community không phải giấy phép OSI. Với model gated, việc chấp nhận điều khoản là điều kiện tải, không phải điều kiện duy nhất để dùng.
Nếu bạn fine-tune một model, giấy phép của bản gốc vẫn áp lên bản dẫn xuất. Nếu bạn chỉ dùng pipeline để thử nghiệm nội bộ, rủi ro thấp hơn, nhưng đưa lên sản phẩm thương mại thì phải đọc lại. Bài AI mã nguồn mở so với đóng đi sâu vào phần này.
Kiểm tra repo trước khi tải
Một đoạn ngắn dùng huggingface_hub để xem config và xác nhận repo trả về đúng thứ bạn cần:
from huggingface_hub import hf_hub_download
import json
config_path = hf_hub_download(repo_id=model_id, filename="config.json")
with open(config_path, encoding="utf-8") as f:
config = json.load(f)
print(config["model_type"])
print(config.get("hidden_size"))
print(config.get("max_position_embeddings"))
max_position_embeddings là giới hạn kiến trúc, không phải cửa sổ ngữ cảnh hiệu dụng. Model có thể được huấn luyện với context ngắn hơn con số này, hoặc dùng RoPE scaling để mở rộng. Đọc model card để biết context thật, đừng suy ra từ một trường config.
Lỗi thường gặp
- OOM khi load. Giảm batch, giảm
max_length, dùng model nhỏ hơn hoặc quantization; đừng tăng swap rồi mong nó chạy. - Sai task.
pipeline("text-classification")trên model sinh văn bản sẽ không cho kết quả bạn muốn. Kiểm trapipeline_tagvà model card. - Dùng model instruct như model base. Model chat cần chat template; gọi thẳng có thể ra định dạng kém. Dùng
tokenizer.apply_chat_templatenếu model card hướng dẫn. - Trộn tokenizer và model. Luôn load cả hai từ cùng repo và cùng revision.
- Bật
trust_remote_codemặc định. Đây là quyền chạy code từ repo; chỉ bật khi cần và đã đọc code. - Bỏ qua giấy phép. Model tải được không có nghĩa là được bán dịch vụ dựa trên nó.
Checklist sau bài này
- Cài
transformers==5.22.2vàhuggingface_hub==2.4.0trong venv riêng. - Chạy pipeline trên ba câu tiếng Anh và một câu tiếng Việt để thấy khác biệt ngôn ngữ.
- In
input_ids, token string vàdecodeđể hiểu tokenizer đang làm gì. - Kiểm tra dung lượng file và VRAM trước khi tải model lớn hơn 7B.
- Đọc license,
pipeline_tagvà phần limitations trong model card. - Chỉ dùng
trust_remote_codekhi model card yêu cầu và đã pin revision.
Kết luận
Biết chạy pipeline chỉ là bước đầu. Kỹ năng thật là biết model nào vừa máy, tokenizer nào đi kèm, định dạng nào an toàn và giấy phép nào cho phép mục đích của bạn. Làm đúng sáu bước trên, bạn có một môi trường thử nghiệm tái lập được thay vì một notebook chạy được một lần.
Bài tiếp theo đi sâu vào cách tìm model trên Hub, đọc benchmark và vet model trước khi đưa vào dự án: Cách tìm và sử dụng mô hình trên Hugging Face. Nếu muốn chạy local bằng một lệnh, xem Giới thiệu về Ollama.
