TL;DR: Cách khắc phục nhanh
Việc hết dung lượng lưu trữ giữa chừng khi đang tải xuống rất khó chịu. Cách nhanh nhất là chuyển hướng tải xuống sang một ổ đĩa còn trống nhiều dung lượng. Hãy chạy lệnh này trong terminal trước khi khởi chạy script Python của bạn:
export HF_HOME="/path/to/your/large/disk/huggingface"
Ngoài ra, bạn có thể thiết lập đường dẫn trực tiếp bên trong script Python trước khi import bất kỳ thư viện Hugging Face nào:
import os
os.environ["HF_HOME"] = "/path/to/your/large/disk/huggingface"
Tại sao lỗi này xảy ra
Các mô hình AI hiện đại thường rất lớn. Khi bạn gọi hàm from_pretrained(), các thư viện như Transformers hoặc Diffusers sẽ tải xuống các trọng số (weights) có thể dễ dàng làm đầy ổ đĩa khởi động tiêu chuẩn. Trong khi mô hình BERT cơ bản chỉ khoảng 400MB, các mô hình phổ biến như Llama 3-8B (15GB) hoặc Stable Diffusion XL (6.5GB) yêu cầu dung lượng lưu trữ đáng kể.
Theo mặc định, Hugging Face lưu các tệp này trong thư mục home của bạn:
- Linux/macOS:
~/.cache/huggingface - Windows:
C:\Users\username\.cache\huggingface
Lỗi này xảy ra khi ổ đĩa chính của bạn—thường là phân vùng gốc (/)—đạt đến giới hạn. Đây là vấn đề thường gặp trong Docker container, các máy ảo cloud với ổ đĩa khởi động chỉ 20GB, hoặc các cụm HPC có hạn ngạch thư mục home hạn chế.
Các giải pháp từng bước
1. Thay đổi vị trí Cache (Khuyên dùng)
Chuyển cache sang một ổ đĩa ngoài hoặc phân vùng dữ liệu (như /mnt/data/) là giải pháp bền vững nhất. Hugging Face sẽ tìm biến môi trường HF_HOME để quyết định nơi lưu trữ dữ liệu.
Tùy chọn A: Thay đổi vĩnh viễn (Linux/macOS)
Mở tệp ~/.bashrc hoặc ~/.zshrc và thêm dòng sau vào cuối tệp:
export HF_HOME="/mnt/external_drive/hf_cache"
Áp dụng các thay đổi bằng cách chạy lệnh source ~/.bashrc.
Tùy chọn B: Thay đổi tạm thời trong Script Nếu bạn đang làm việc trên một máy tính dùng chung, bạn có thể chỉ muốn thay đổi đường dẫn cho một dự án cụ thể. Hãy thiết lập biến môi trường ở ngay đầu script của bạn:
import os
# Bạn phải thiết lập dòng này TRƯỚC KHI import transformers hoặc diffusers
os.environ["HF_HOME"] = "/mnt/data/huggingface_cache"
from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-uncased")
2. Dọn dẹp trọng số mô hình cũ
Có thể bạn đã quên các phiên bản mô hình cũ hoặc các bản tải xuống bị lỗi đang chiếm dụng không gian ổ đĩa. huggingface-cli cung cấp một công cụ tích hợp để xác định và xóa các tệp này.
# Cài đặt CLI nếu bạn chưa có
pip install -U "huggingface_hub[cli]"
# Khởi chạy công cụ xóa tương tác
huggingface-cli delete-cache
Công cụ này sẽ hiển thị danh sách các mô hình trong bộ nhớ cache và kích thước của chúng. Sau đó, bạn có thể chọn chính xác phiên bản nào cần xóa để giải phóng hàng gigabyte dung lượng.
3. Sử dụng Symbolic Links (Liên kết biểu tượng)
Đôi khi bạn không thể dễ dàng sửa đổi các biến môi trường trong môi trường production bị hạn chế quyền. Trong những trường hợp này, hãy di chuyển thư mục hiện có và "đánh lừa" hệ thống bằng một liên kết biểu tượng (symbolic link).
# 1. Tạo một thư mục trên ổ đĩa lớn
mkdir -p /mnt/large_disk/huggingface_cache
# 2. Di chuyển các tệp hiện có sang vị trí mới
mv ~/.cache/huggingface/* /mnt/large_disk/huggingface_cache/
# 3. Liên kết đường dẫn cũ tới đường dẫn mới
rm -rf ~/.cache/huggingface
ln -s /mnt/large_disk/huggingface_cache ~/.cache/huggingface
4. Khắc phục lưu trữ trong Docker Container
Các Docker container thường có kích thước "lớp có thể ghi" (writable layer) hạn chế (thường là 10GB hoặc 20GB). Để tránh làm đầy container, hãy gắn (mount) một thư mục máy chủ làm volume:
docker run -it \
-v /home/user/my_large_disk:/cache_dir \
-e HF_HOME=/cache_dir \
my_ai_image
Xác minh: Đã thành công chưa?
Kiểm tra lại công việc của bạn để đảm bảo thư viện thực sự đang sử dụng đường dẫn mới. Sử dụng lệnh df -h trong terminal để theo dõi việc sử dụng đĩa trên các phân vùng theo thời gian thực.
Xác minh đường dẫn trong Python: Chạy đoạn mã này để xem Hugging Face hiện đang trỏ đến đâu:
from huggingface_hub import constants
print(f"Thư mục cache HF đang hoạt động: {constants.HF_HUB_CACHE}")
Nếu kết quả phản ánh đúng thư mục mới của bạn, lỗi OSError sẽ được giải quyết.