Lỗi gặp phải
Bạn thử tải một model Llama 3 từ Hugging Face — qua transformers, huggingface_hub, vLLM, hoặc bất kỳ thư viện nào khác bọc HF API — và gặp ngay lỗi này:
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
Lỗi này xảy ra trên Linux, macOS và Windows như nhau. Nó xuất hiện ngay khi thư viện cố kéo file đầu tiên từ repo model.
Nguyên nhân thực sự
Các model Llama của Meta — cùng với Mistral, Gemma, Falcon và hàng chục model khác — được lưu trong các kho lưu trữ có cổng kiểm soát (gated repositories) trên HuggingFace. Để vượt qua cổng này, bạn cần đáp ứng đồng thời ba điều kiện:
- Có tài khoản Hugging Face đang hoạt động
- Đã truy cập trang model và chấp nhận điều khoản sử dụng
- Môi trường cục bộ đã xác thực bằng token HF hợp lệ từ tài khoản đó
Lỗi 401 có nghĩa là máy chủ HuggingFace không thể xác minh danh tính của bạn. Có thể không có token nào được gửi đi, token không hợp lệ, hoặc — nguyên nhân phổ biến nhất — tài khoản của bạn chưa chấp nhận điều khoản của gated repo.
Bước 1: Chấp nhận giấy phép model (Đừng bỏ qua bước này)
Nhiều người nghĩ chỉ cần có token là đủ. Không phải vậy. Bạn phải chấp nhận điều kiện truy cập của model một cách tường minh thông qua website HuggingFace — không có lệnh CLI nào thay thế được bước này.
- Truy cập https://huggingface.co/meta-llama/Llama-3-8B
- Nhấn "Request access" hoặc "Acknowledge license" (tên nút có thể khác nhau tùy model)
- Điền các trường thông tin bắt buộc và gửi yêu cầu
- Chờ email phê duyệt — Meta thường phản hồi trong vài phút đến vài giờ
Bạn sẽ nhận được email xác nhận khi được chấp thuận. Chỉ sau đó token của bạn mới có thể mở khóa repo cụ thể này.
Bước 2: Lấy Read Token
Truy cập https://huggingface.co/settings/tokens và tạo một token với quyền tối thiểu là Read. Token trông giống như hf_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567 — khoảng 37 ký tự bắt đầu bằng hf_. Hãy sao chép ngay; bạn sẽ không thấy lại nó sau khi rời khỏi trang.
Cách nhanh nhất: Xác thực qua CLI
Cách nhanh nhất để giải quyết vấn đề:
pip install -U huggingface_hub
huggingface-cli login
Dán token của bạn khi được yêu cầu. Token sẽ được lưu vào ~/.cache/huggingface/token và mọi lệnh gọi HF sau đó sẽ tự động sử dụng nó. Chạy lại script của bạn — quá trình tải xuống sẽ bắt đầu.
Cách triệt để: Truyền token trực tiếp trong code
Đăng nhập qua CLI sẽ không tồn tại trong Docker container, CI pipeline, hay VM mới. Với môi trường tự động, hãy truyền token một cách tường minh:
from transformers import AutoModelForCausalLM, AutoTokenizer
import os
hf_token = os.environ.get("HF_TOKEN")
model = AutoModelForCausalLM.from_pretrained(
"meta-llama/Llama-3-8B",
token=hf_token
)
tokenizer = AutoTokenizer.from_pretrained(
"meta-llama/Llama-3-8B",
token=hf_token
)
Hoặc dùng trực tiếp với huggingface_hub:
from huggingface_hub import snapshot_download
import os
snapshot_download(
repo_id="meta-llama/Llama-3-8B",
token=os.environ.get("HF_TOKEN")
)
Đặt biến môi trường trước khi chạy:
# Linux / macOS
export HF_TOKEN="hf_your_token_here"
python your_script.py
# Windows (PowerShell)
$env:HF_TOKEN = "hf_your_token_here"
python your_script.py
# Docker
docker run -e HF_TOKEN="hf_your_token_here" your-image python your_script.py
Làm việc trong notebook? Gọi login() trực tiếp — nhưng đừng commit token vào version control:
from huggingface_hub import login
login(token="hf_your_token_here")
Kiểm tra sau khi sửa
Trước khi chạy lại script, hãy xác nhận HuggingFace đã nhận được thông tin xác thực của bạn:
huggingface-cli whoami
Bạn sẽ thấy tên tài khoản của mình. Nếu hiện "Not logged in" nghĩa là token chưa được ghi nhận.
Sau đó kiểm tra xem tài khoản của bạn có thực sự có quyền truy cập vào gated model không:
from huggingface_hub import model_info
info = model_info("meta-llama/Llama-3-8B", token="hf_your_token_here")
print(info.id) # Nên in ra: meta-llama/Llama-3-8B
Vẫn nhận lỗi 403 thay vì 401? Điều đó có nghĩa là yêu cầu chấp nhận giấy phép vẫn đang chờ xử lý hoặc chưa được cập nhật. Chờ vài phút rồi thử lại.
Các lỗi thường gặp
- Sai loại token: Token chi tiết (fine-grained) với phạm vi hạn chế có thể không bao gồm quyền đọc repo. Dùng token Read thông thường để tránh vấn đề này.
- Sai tài khoản: Tài khoản chấp nhận giấy phép phải trùng với tài khoản sở hữu token. Nếu bạn có nhiều tài khoản HF, hãy kiểm tra lại bạn đã dùng tài khoản nào.
- Token cũ còn trong cache: Đã đổi token mới? Token cũ có thể vẫn đang nằm trong cache. Xóa bằng lệnh
rm ~/.cache/huggingface/token, rồi đăng nhập lại. - Yêu cầu chưa được duyệt: Thời gian xử lý của Meta thường khá nhanh — nhưng không tức thì. Nếu bạn vừa gửi form, hãy chờ 15–30 phút trước khi kết luận có sự cố.
Mẹo hay
Sau khi tải xuống thành công, model sẽ nằm trong ~/.cache/huggingface/hub/ — Llama 3 8B chiếm khoảng 16 GB ở định dạng float16, vì vậy hãy đảm bảo bạn có đủ dung lượng ổ đĩa trước khi bắt đầu tải. Cần xem file config.json của model?
JSON Formatter trên ToolCraft rất tiện để phát hiện các vấn đề về cấu trúc — chạy hoàn toàn trên trình duyệt, không upload dữ liệu. Đang làm việc với config model dạng YAML? YAML ↔ JSON Converter trên cùng trang web đó tiện hơn nhiều so với việc viết một script Python chỉ để kiểm tra một giá trị config duy nhất.