Bắt đầu nhanh

Hugging Face Hub là nơi để chia sẻ các mô hình machine learning, demo, dataset và metrics. Thư viện huggingface_hub giúp bạn tương tác với Hub mà không cần rời khỏi môi trường phát triển. Bạn có thể dễ dàng tạo và quản lý các repository, tải xuống và tải lên tệp, cũng như lấy metadata hữu ích về mô hình và dataset từ Hub.

Cài đặt

Để bắt đầu, hãy cài đặt thư viện huggingface_hub:

pip install --upgrade huggingface_hub

Để biết thêm chi tiết, hãy xem hướng dẫn cài đặt.

huggingface_hub cũng đi kèm với hf CLI cho phép bạn tương tác trực tiếp với Hub từ terminal. Nếu bạn đang sử dụng các AI agent (Claude Code, Codex, Cursor, …), hãy cài đặt Skill để agent của bạn có thể sử dụng CLI:

Đã sao chép

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Xem hướng dẫn Hugging Face CLI for AI Agents để biết thêm chi tiết.

Tải xuống các tệp

Các kho trên Hub được kiểm soát phiên bản bằng git, và người dùng có thể tải xuống một tệp duy nhất hoặc toàn bộ kho. Bạn có thể sử dụng hàm hf_hub_download() để tải tệp xuống. Hàm này sẽ tải tệp xuống và lưu vào bộ nhớ đệm trên ổ đĩa cục bộ của bạn. Lần sau khi bạn cần tệp đó, nó sẽ được nạp từ bộ nhớ đệm, nên bạn không cần tải lại.

Bạn sẽ cần id của kho và tên tệp của tệp bạn muốn tải xuống. Ví dụ, để tải xuống tệp cấu hình của mô hình Pegasus:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

Để tải xuống một phiên bản cụ thể của tệp, hãy sử dụng tham số revision để chỉ định tên nhánh, thẻ hoặc mã băm commit. Nếu bạn chọn sử dụng mã băm commit, nó phải là mã băm có độ dài đầy đủ thay vì mã băm commit ngắn 7 ký tự:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

Để biết thêm chi tiết và các tùy chọn, hãy xem tham chiếu API của hf_hub_download().

Xác thực

Trong nhiều trường hợp, bạn phải xác thực bằng tài khoản Hugging Face để tương tác với Hub: tải xuống các repo riêng tư, tải lên tệp, tạo PR,… Tạo tài khoản nếu bạn chưa có.

Lệnh đăng nhập

Cách dễ nhất để xác thực là sử dụng lệnh login():

hf auth login

Nếu bạn đã đăng nhập, lệnh sẽ trả về ngay lập tức. Để buộc đăng nhập lại, hãy sử dụng hf auth login --force. Nếu bạn chưa đăng nhập, hệ thống sẽ yêu cầu bạn đăng nhập bằng trình duyệt: mở URL được in ra, nhập mã ngắn, phê duyệt yêu cầu, và một access token sẽ được lấy về và lưu trong thư mục HF_HOME của bạn (mặc định là ~/.cache/huggingface/token). Token sẽ hết hạn sau một thời gian nhưng sẽ được làm mới tự động miễn là bạn tiếp tục sử dụng nó. Bất kỳ script hoặc thư viện nào tương tác với Hub sẽ sử dụng token này khi gửi yêu cầu. Ngoài ra, bạn có thể dán một User Access Token được tạo từ Settings page của bạn.

User Access Tokens có thể có quyền read hoặc write. Hãy đảm bảo bạn có token truy cập write nếu muốn tạo hoặc chỉnh sửa một kho lưu trữ. Ngược lại, tốt nhất là tạo một token read để giảm thiểu rủi ro trong trường hợp token của bạn bị lộ ra ngoài một cách vô ý.

Ngoài ra, bạn có thể đăng nhập bằng cách lập trình bằng cách sử dụng login() trong notebook hoặc script:

>>> from huggingface_hub import login
>>> login()

Bạn chỉ có thể đăng nhập vào một tài khoản tại một thời điểm. Việc đăng nhập vào một tài khoản mới sẽ tự động đăng xuất khỏi tài khoản trước đó. Để xác định tài khoản đang hoạt động hiện tại, chỉ cần chạy lệnh hf auth whoami.

Sau khi đăng nhập, tất cả các yêu cầu đến Hub - kể cả các phương thức không nhất thiết yêu cầu xác thực - sẽ mặc định sử dụng token truy cập của bạn. Nếu bạn muốn tắt việc sử dụng ngầm token của mình, hãy đặt HF_HUB_DISABLE_IMPLICIT_TOKEN=1 dưới dạng biến môi trường (xem tham khảo).

Quản lý nhiều token cục bộ

Bạn có thể lưu nhiều token trên máy của mình bằng cách đăng nhập bằng lệnh login() với từng token. Nếu bạn cần chuyển đổi giữa các token này cục bộ, bạn có thể sử dụng lệnh auth switch:

hf auth switch

Lệnh này sẽ yêu cầu bạn chọn một token theo tên từ danh sách các token đã lưu. Sau khi chọn, token được chọn sẽ trở thành token hiệu lực và sẽ được sử dụng cho mọi tương tác với Hub.

Bạn có thể liệt kê tất cả các access token khả dụng trên máy của mình bằng hf auth list.

Biến môi trường

Biến môi trường HF_TOKEN cũng có thể được sử dụng để xác thực danh tính của bạn. Điều này đặc biệt hữu ích trong một Space, nơi bạn có thể đặt HF_TOKEN như một Space secret.

MỚI: Google Colaboratory cho phép bạn định nghĩa khóa riêng tư cho các notebook của mình. Hãy định nghĩa bí mật HF_TOKEN để được xác thực tự động!

Xác thực thông qua biến môi trường hoặc bí mật có ưu tiên cao hơn so với token được lưu trên máy của bạn.

Tham số của phương thức

Cuối cùng, bạn cũng có thể xác thực bằng cách truyền token của mình vào bất kỳ phương thức nào nhận token làm tham số.

from huggingface_hub import whoami

user = whoami(token=...)

Điều này thường không được khuyến khích, ngoại trừ trong môi trường mà bạn không muốn lưu trữ token một cách vĩnh viễn hoặc khi bạn cần xử lý nhiều token cùng lúc.

Hãy cẩn thận khi truyền token dưới dạng tham số. Thực hành tốt nhất luôn là tải token từ một kho lưu trữ bảo mật thay vì hardcode nó trong codebase hoặc notebook của bạn. Token được hardcode tạo ra rủi ro rò rỉ nghiêm trọng nếu bạn vô tình chia sẻ mã nguồn của mình.

Tạo một kho lưu trữ

Sau khi bạn đã đăng ký và đăng nhập, hãy tạo một kho lưu trữ bằng hàm create_repo():

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

Nếu bạn muốn kho lưu trữ của mình là riêng tư, thì:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

Kho lưu trữ riêng sẽ không hiển thị cho bất kỳ ai ngoại trừ chính bạn.

Để tạo một kho lưu trữ hoặc đẩy nội dung lên Hub, bạn phải cung cấp một User Access Token có quyền write. Bạn có thể chọn quyền này khi tạo token trong trang Cài đặt của mình.

Tải tệp lên

Sử dụng hàm upload_file() để thêm một tệp vào kho vừa tạo. Bạn cần chỉ định:

1. Đường dẫn của tệp cần tải lên.
2. Đường dẫn của tệp trong kho.
3. ID của kho lưu trữ nơi bạn muốn thêm tệp.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

Để tải lên nhiều hơn một tệp cùng lúc, hãy xem hướng dẫn Upload sẽ giới thiệu cho bạn một số phương pháp để tải lên tệp (có hoặc không có git).

Các bước tiếp theo

Thư viện huggingface_hub cung cấp cách dễ dàng để người dùng tương tác với Hub bằng Python. Để tìm hiểu thêm về cách quản lý tệp và kho lưu trữ của bạn trên Hub, chúng tôi khuyên bạn nên đọc các hướng dẫn của chúng tôi để:

• Quản lý kho của bạn.
• Tải xuống các tệp từ Hub.
• Tải lên các tệp lên Hub.
• Tìm kiếm trên Hub để tìm mô hình hoặc bộ dữ liệu mong muốn.
• Chạy suy luận trên nhiều dịch vụ cho các mô hình được lưu trữ trên Hugging Face Hub.