Cài đặt

Trước khi bắt đầu, bạn cần thiết lập môi trường bằng cách cài đặt các gói phù hợp.

huggingface_hub được kiểm thử trên Python 3.10+.

Cài đặt bằng pip

Rất khuyến nghị cài đặt huggingface_hub trong một môi trường ảo. Nếu bạn chưa quen với môi trường ảo Python, hãy xem hướng dẫn này. Môi trường ảo giúp quản lý các dự án khác nhau dễ dàng hơn và tránh các vấn đề tương thích giữa các phụ thuộc.

Bắt đầu bằng cách tạo một môi trường ảo trong thư mục dự án của bạn:

python -m venv .venv

Kích hoạt môi trường ảo. Trên Linux và macOS:

source .venv/bin/activate

Kích hoạt môi trường ảo trên Windows:

.venv/Scripts/activate

Bây giờ bạn đã sẵn sàng để cài đặt huggingface_hub từ kho PyPi:

pip install --upgrade huggingface_hub

Khi hoàn tất, kiểm tra cài đặt đang hoạt động chính xác.

Cài đặt các phụ thuộc tùy chọn

Một số phụ thuộc của huggingface_hub là tùy chọn vì chúng không bắt buộc để chạy các tính năng cốt lõi của huggingface_hub. Tuy nhiên, một số tính năng của huggingface_hub có thể không khả dụng nếu các phụ thuộc tùy chọn chưa được cài đặt.

Bạn có thể cài đặt các phụ thuộc tùy chọn thông qua pip:

# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

Dưới đây là danh sách các phụ thuộc tùy chọn trong huggingface_hub:

• fastai, torch: các phụ thuộc để chạy các tính năng đặc thù của framework.
• dev: các phụ thuộc để đóng góp cho thư viện. Bao gồm testing (để chạy các bài kiểm thử), typing (để chạy trình kiểm tra kiểu) và quality (để chạy các trình kiểm tra mã nguồn).

Cài đặt từ mã nguồn

Trong một số trường hợp, việc cài đặt huggingface_hub trực tiếp từ mã nguồn là hữu ích. Điều này cho phép bạn sử dụng phiên bản main mới nhất thay vì phiên bản ổn định gần nhất. Phiên bản main hữu ích để cập nhật các phát triển mới nhất, chẳng hạn khi một lỗi đã được sửa kể từ lần phát hành chính thức cuối cùng nhưng một bản phát hành mới vẫn chưa được tung ra.

Tuy nhiên, điều này có nghĩa là phiên bản main có thể không luôn ổn định. Chúng tôi nỗ lực giữ cho phiên bản main hoạt động, và hầu hết các vấn đề thường được giải quyết trong vòng vài giờ hoặc một ngày. Nếu bạn gặp sự cố, vui lòng mở một Issue để chúng tôi có thể khắc phục càng sớm càng tốt!

pip install git+https://github.com/huggingface/huggingface_hub

Khi cài đặt từ mã nguồn, bạn cũng có thể chỉ định một nhánh cụ thể. Điều này hữu ích nếu bạn muốn kiểm tra một tính năng mới hoặc một bản sửa lỗi mới mà chưa được hợp nhất:

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

Khi hoàn tất, kiểm tra cài đặt đang hoạt động chính xác.

Cài đặt có thể chỉnh sửa

Cài đặt từ mã nguồn cho phép bạn thiết lập một cài đặt có thể chỉnh sửa. Đây là phương pháp cài đặt nâng cao hơn nếu bạn có kế hoạch đóng góp cho huggingface_hub và cần kiểm tra các thay đổi trong mã. Bạn cần sao chép (clone) một bản địa phương của huggingface_hub trên máy của mình.

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

Các lệnh này sẽ liên kết thư mục bạn đã clone kho mã nguồn với các đường dẫn thư viện Python của bạn. Python sẽ tìm kiếm bên trong thư mục bạn đã clone ngoài các đường dẫn thư viện thông thường. Ví dụ, nếu các gói Python của bạn thường được cài đặt trong ./.venv/lib/python3.13/site-packages/, Python cũng sẽ tìm kiếm trong thư mục bạn đã clone ./huggingface_hub/.

Cài đặt Hugging Face CLI

Sử dụng trình cài đặt một dòng của chúng tôi để thiết lập CLI hf mà không cần đụng chạm đến môi trường Python của bạn:

Trên macOS và Linux:

curl -LsSf https://hf.co/cli/install.sh | bash

Trên Windows:

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Để nâng cấp bản cài đặt hiện có, hãy chạy hf update — lệnh này sẽ phát hiện cách hf được cài đặt (trình cài đặt độc lập, Homebrew, hoặc pip) và chạy lệnh tương ứng.

Cài đặt bằng conda

Nếu bạn quen thuộc hơn với nó, bạn có thể cài đặt huggingface_hub bằng cách sử dụng kênh conda-forge:

conda install -c conda-forge huggingface_hub

Khi hoàn tất, kiểm tra cài đặt đang hoạt động chính xác.

Kiểm tra cài đặt

Sau khi cài đặt, hãy kiểm tra xem huggingface_hub có hoạt động đúng không bằng cách chạy lệnh sau:

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

Lệnh này sẽ lấy thông tin từ Hub về mô hình gpt2. Đầu ra nên trông như sau:

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

Hạn chế trên Windows

Với mục tiêu dân chủ hóa ML chất lượng ở mọi nơi, chúng tôi đã xây dựng huggingface_hub như một thư viện đa nền tảng, đặc biệt là hoạt động chính xác trên cả hệ thống dựa trên Unix và Windows. Tuy nhiên, có một số trường hợp mà huggingface_hub gặp phải một số hạn chế khi chạy trên Windows. Dưới đây là danh sách đầy đủ các vấn đề đã biết. Vui lòng cho chúng tôi biết nếu bạn gặp bất kỳ vấn đề nào chưa được tài liệu hóa bằng cách mở một issue trên Github.

• Hệ thống cache của huggingface_hub dựa vào symlink để cache hiệu quả các tệp đã tải xuống từ Hub. Trên Windows, bạn phải bật developer mode hoặc chạy script với quyền admin để kích hoạt symlink. Nếu chưa được kích hoạt, hệ thống cache vẫn hoạt động nhưng theo cách không được tối ưu. Vui lòng đọc phần giới hạn của cache để biết thêm chi tiết.
• Đường dẫn tệp trên Hub có thể chứa các ký tự đặc biệt (ví dụ: "path/to?/my/file"). Windows hạn chế hơn về các ký tự đặc biệt, khiến việc tải xuống các tệp đó trên Windows trở nên không thể. Hy vọng đây là một trường hợp hiếm gặp. Vui lòng liên hệ với chủ sở hữu kho nếu bạn cho rằng đây là một sai sót, hoặc liên hệ với chúng tôi để tìm ra giải pháp.

Các bước tiếp theo

Khi huggingface_hub đã được cài đặt đúng cách trên máy của bạn, bạn có thể muốn cấu hình các biến môi trường hoặc xem một trong các hướng dẫn của chúng tôi để bắt đầu.