ErrorNotes

Sửa lỗi HuggingFace OSError: Can't Load Tokenizer for Model

beginner🧠 AI Tools2026-05-17| Python 3.8+, HuggingFace Transformers 4.x, Linux/macOS/Windows

Error Message

OSError: Can't load tokenizer for
#huggingface#tokenizer#transformers#model-loading

Lỗi Xảy Ra

Bạn gọi AutoTokenizer.from_pretrained() và nhận được thông báo lỗi này:

OSError: Can't load tokenizer for 'bert-base-uncased'. If you were trying to load it from 'https://huggingface.co/models', make sure you don't have a local directory with the same name. Otherwise, make sure 'bert-base-uncased' is the correct identifier of a pretrained model listed on 'https://huggingface.co/models'.

Hoặc phiên bản ngắn gọn hơn:

OSError: Can't load tokenizer for 'your-model-name'.

Trông có vẻ đáng sợ nhưng thường không phức tạp lắm. Nguyên nhân hầu hết rơi vào một trong ba trường hợp: sai tên model, mạng bị chặn, hoặc cache cục bộ bị hỏng.

Nguyên Nhân Gây Ra Lỗi

  • Gõ sai hoặc nhầm tên model — định danh không tồn tại trên Hub.
  • Không có kết nối internet — tường lửa, proxy công ty, hoặc máy chạy môi trường cách ly mạng.
  • Cache bị hỏng — tải xuống không hoàn chỉnh để lại các file lỗi trong ~/.cache/huggingface/.
  • Phiên bản transformers quá cũ — một số lớp tokenizer chỉ được giới thiệu sau phiên bản 4.20; các bản cũ hơn không hỗ trợ chúng.
  • Model riêng tư hoặc bị giới hạn truy cập — Llama 2, Mistral và các repo tương tự yêu cầu chấp nhận giấy phép và có HF token hợp lệ.
  • Nhầm đường dẫn cục bộ — bạn truyền đường dẫn thư mục nhưng các file cần thiết không có bên trong đó.

Cách Khắc Phục Từng Bước

Bước 1 — Kiểm Tra Tên Model

Tên model phân biệt chữ hoa chữ thường. Bert-Base-Uncased sẽ lỗi; bert-base-uncased mới đúng.

# Sai
tokenizer = AutoTokenizer.from_pretrained("Bert-Base-Uncased")

# Đúng
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

Các model cộng đồng cũng cần tiền tố tên người dùng — hãy sao chép ID trực tiếp từ URL trang model card:

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

Bước 2 — Kiểm Tra Mạng và Xác Thực

Trước khi làm bất cứ điều gì khác, hãy xác nhận bạn có thể kết nối đến Hub không:

python -c "from huggingface_hub import HfApi; print(HfApi().model_info('bert-base-uncased'))"

Nếu lệnh trên báo lỗi kết nối thì vấn đề nằm ở mạng, không phải code của bạn.

Các model bị giới hạn truy cập như Llama 2 yêu cầu bạn phải chấp nhận giấy phép trên trang model và có token hợp lệ:

# Cách A: Đăng nhập qua CLI (lưu lại cho các phiên sau)
huggingface-cli login

# Cách B: Truyền token trực tiếp
tokenizer = AutoTokenizer.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    token="hf_your_token_here"
)

Tạo token tại huggingface.co/settings/tokens. Quyền đọc là đủ để tải xuống.

Bước 3 — Xóa Cache Bị Hỏng

Các lần tải xuống bị gián đoạn để lại file không hoàn chỉnh, gây cản trở cho các lần tải sau. Hãy xóa thư mục model cụ thể đó và để nó tải lại từ đầu:

# Tìm vị trí cache trước
python -c "from huggingface_hub import constants; print(constants.HF_HUB_CACHE)"

# Chỉ xóa model bị lỗi (Linux/macOS)
rm -rf ~/.cache/huggingface/hub/models--bert-base-uncased

# Xóa toàn bộ cache (phương án mạnh tay)
rm -rf ~/.cache/huggingface/hub/

Lưu ý: các model phổ biến như bert-base-uncased có dung lượng khoảng 440 MB. Các model lớn hơn (Llama 2 7B) có thể lên đến 13+ GB. Hãy đảm bảo bạn có đủ dung lượng ổ đĩa trước khi tải lại.

Bước 4 — Nâng Cấp Transformers

Backend tokenizer nhanh và các kiểu model mới thường yêu cầu phiên bản gần đây. Hãy nâng cấp toàn bộ bộ thư viện cùng một lúc:

pip install --upgrade transformers tokenizers huggingface_hub

Kiểm tra phiên bản hiện tại:

python -c "import transformers; print(transformers.__version__)"

Bất kỳ phiên bản nào dưới 4.30 sẽ gặp vấn đề với các model phát hành từ năm 2023 trở đi. Hầu hết các model hiện đại (Mistral, Phi, Gemma) cần phiên bản 4.35 trở lên.

Bước 5 — Tải Từ Thư Mục Cục Bộ

Đã tải model về rồi? Bỏ qua mạng hoàn toàn bằng cách trỏ thẳng đến đường dẫn cục bộ:

from transformers import AutoTokenizer

# Lưu xuống một lần
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
tokenizer.save_pretrained("./local_tokenizer/")

# Tải offline từ đó về sau
tokenizer = AutoTokenizer.from_pretrained("./local_tokenizer/")

Thư mục phải chứa file tokenizer_config.json. Tùy loại tokenizer, bạn cũng cần vocab.txt (kiểu BERT), vocab.json (kiểu GPT-2), hoặc tokenizer.json (fast tokenizer). Kiểm tra bằng ls ./local_tokenizer/ nếu bạn nghi ngờ có file bị thiếu.

Bước 6 — Bật Chế Độ Offline Tường Minh

Trên các máy cách ly mạng, hãy đặt TRANSFORMERS_OFFLINE=1 trước khi chạy bất cứ thứ gì:

# Trong shell
export TRANSFORMERS_OFFLINE=1
python your_script.py

# Hoặc bên trong Python
import os
os.environ["TRANSFORMERS_OFFLINE"] = "1"

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

Khi bật cờ này, Transformers bỏ qua tất cả các lệnh gọi mạng và chỉ tải từ cache. Nếu cache không có, bạn sẽ nhận được thông báo lỗi rõ ràng ngay lập tức — không bị treo trong khi cố kết nối đến huggingface.co.

Bước 7 — Dùng Slow Tokenizer Thay Thế

Đôi khi fast tokenizer (dựa trên Rust) bị xung đột phiên bản với thư viện tokenizers. Hãy chuyển sang bản triển khai Python thuần túy như một bước chẩn đoán:

tokenizer = AutoTokenizer.from_pretrained(
    "bert-base-uncased",
    use_fast=False
)

Chậm hơn với các batch lớn, nhưng tránh hoàn toàn mọi vấn đề về ABI của thư viện Rust.

Kiểm Tra Sau Khi Khắc Phục

Chạy đoạn kiểm tra nhanh sau khi áp dụng cách sửa của bạn:

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
output = tokenizer("Hello, HuggingFace!", return_tensors="pt")
print(output)
# Kết quả mong đợi: {'input_ids': tensor([[101, 7592, 1010, ...]]), 'attention_mask': tensor([[1, 1, ...]])}

Nếu output ra tensor là tokenizer đã tải thành công. Nếu vẫn lỗi thì vấn đề vẫn nằm ở ID model hoặc file.

Danh Sách Kiểm Tra Nhanh

  • Sao chép tên model trực tiếp từ URL trên Hub — đừng gõ lại thủ công.
  • Chạy huggingface-cli whoami để xác nhận bạn đã xác thực.
  • Kiểm tra trang model xem có thông báo "Access restricted" hoặc "Gated model" không.
  • Kiểm tra dung lượng ổ đĩa — cache tokenizer dao động từ 500 MB đến 13+ GB.
  • Khi tải cục bộ, xác nhận file tokenizer_config.json tồn tại trong thư mục đích.
  • Trên mạng công ty, hãy đặt HTTPS_PROXY — nhiều lỗi tải HuggingFace là do proxy chặn âm thầm.

Khắc Phục Proxy và Tường Lửa

Proxy công ty thường chặn các lượt tải HuggingFace mà không báo lỗi rõ ràng. Hãy thiết lập proxy trước khi chạy script của bạn:

export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
python your_script.py

Hoặc đặt bên trong Python nếu bạn không thể chỉnh sửa môi trường shell:

import os
os.environ["HTTPS_PROXY"] = "http://proxy.company.com:8080"

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

Related Error Notes

Fix GatedRepoError: Không Thể Truy Cập Gated Repo trên Hugging Face (401 Client Error)

huggingface_hub.utils._errors.GatedRepoError: 401 Client Error. Cannot access gated repo for url https://huggingface.co/meta-llama/Llama-3-8B/resolve/main/config.json

Khắc phục lỗi WeaviateConnectionError: 'Failed to connect to localhost:8080'

weaviate.exceptions.WeaviateConnectionError: Failed to connect to Weaviate at http://localhost:8080. Error: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: /v1/.well-known/ready

Sửa lỗi PyTorch RuntimeError: "Expected all tensors to be on the same device" trong HuggingFace

RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu! (when checking argument for argument mat2 in method wrapper_CUDA_mm)