# Bắt đầu nhanh [Hugging Face Hub](https://huggingface.co/) 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`: ```bash pip install --upgrade huggingface_hub ``` Để biết thêm chi tiết, hãy xem hướng dẫn [cài đặt](installation). > [!TIP] > `huggingface_hub` cũng đi kèm với [CLI `hf`](./guides/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: > ```bash > # 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](https://huggingface.co/docs/hub/agents-cli) để 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.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 mô hình [Pegasus](https://huggingface.co/google/pegasus-xsum): ```py >>> 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ự: ```py >>> 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.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 kho riêng tư, tải lên tệp, tạo PR,... [Tạo tài khoản](https://huggingface.co/join) 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/authentication#huggingface_hub.login): ```bash 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](https://huggingface.co/docs/hub/security-tokens) được tạo từ [Settings page](https://huggingface.co/settings/tokens) của bạn. > [!TIP] > 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/authentication#huggingface_hub.login) trong notebook hoặc script: ```py >>> 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`. > [!WARNING] > 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](../package_reference/environment_variables#hfhubdisableimplicittoken)). ### 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/authentication#huggingface_hub.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`: ```bash 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](https://huggingface.co/docs/hub/spaces-overview#managing-secrets). > [!TIP] > **MỚI:** Google Colaboratory cho phép bạn định nghĩa [khóa riêng tư](https://twitter.com/GoogleColab/status/1719798406195867814) 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 của mình một cách vĩnh viễn hoặc khi bạn cần xử lý nhiều token cùng lúc. > [!WARNING] > 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.create_repo): ```py >>> 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ì: ```py >>> 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. > [!TIP] > Để 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](https://huggingface.co/settings/tokens) của mình. ## Tải tệp lên Sử dụng hàm [upload_file()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.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. ```py >>> 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](./guides/upload), trong đó giới thiệu một số phương pháp để tải tệp lên (có hoặc không dùng 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](./guides/overview) của chúng tôi để: - [Quản lý kho của bạn](./guides/repository). - [Tải xuống](./guides/download) các tệp từ Hub. - [Tải lên](./guides/upload) các tệp lên Hub. - [Tìm kiếm trên Hub](./guides/search) để tìm mô hình hoặc bộ dữ liệu mong muốn. - [Chạy suy luận](./guides/inference) trên nhiều dịch vụ cho các mô hình được lưu trữ trên Hugging Face Hub.