Giao diện dòng lệnh (CLI)

Gói Python huggingface_hub đi kèm với một CLI tích hợp có tên là hf. Công cụ này cho phép bạn tương tác trực tiếp với Hugging Face Hub từ terminal. Ví dụ, bạn có thể đăng nhập vào tài khoản, tạo một repository, tải lên và tải xuống tệp, v.v. Nó cũng đi kèm với các tính năng tiện lợi để cấu hình máy hoặc quản lý cache của bạn. Trong hướng dẫn này, chúng ta sẽ xem xét các tính năng chính của CLI và cách sử dụng chúng.

Hướng dẫn này bao gồm các tính năng quan trọng nhất của CLI hf. Để tham khảo đầy đủ tất cả các lệnh và tùy chọn, hãy xem tham chiếu CLI.

Đang dùng hf CLI với các AI agent? Cài đặt Skill và xem hướng dẫn Hugging Face CLI for AI Agents.

Đã sao chép

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

Trình cài đặt độc lập sẽ cài đặt nó cho bạn (xem bên dưới), và hf update sẽ làm mới nó.

Bắt đầu

Trình cài đặt độc lập (Được khuyến nghị)

Bạn có thể cài đặt CLI hf bằng một lệnh duy nhất:

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"

Trình cài đặt cũng cài đặt skill hf-cli toàn cục, dành cho Claude Code và bất kỳ agent nào đọc ~/.agents/skills. Truyền --exclude-skill để bỏ qua nó:

>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill

>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"

Sau khi cài đặt, bạn có thể kiểm tra xem CLI đã được thiết lập đúng chưa:

>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --skills              Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  -h, --help            Show this message and exit.

Main commands:
  auth                 Manage authentication (login, logout, etc.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  upload               Upload a file or a folder to the Hub.

Help commands:
  env      Print information about the environment.
  version  Print information about the hf version.

Nếu CLI được cài đặt đúng cách, bạn sẽ thấy danh sách tất cả các tùy chọn có sẵn trong CLI. Nếu bạn nhận được thông báo lỗi như command not found: hf, vui lòng tham khảo hướng dẫn Cài đặt.

Tùy chọn --help rất tiện lợi để xem thêm chi tiết về một lệnh. Bạn có thể sử dụng nó bất cứ lúc nào để liệt kê tất cả các tùy chọn khả dụng cùng chi tiết của chúng. Ví dụ, hf upload --help cung cấp thêm thông tin về cách tải tệp lên bằng CLI.

Sử dụng uv

Cách dễ nhất để sử dụng CLI hf là với uvx. Nó luôn chạy phiên bản mới nhất trong một môi trường cô lập - không cần cài đặt!

Hãy đảm bảo uv đã được cài đặt trước. Xem hướng dẫn cài đặt uv để biết các bước thực hiện.

Sau đó, sử dụng CLI trực tiếp:

>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...

uvx hf sử dụng gói PyPI hf.

Cài đặt bằng pip

CLI cũng được phát hành cùng với gói huggingface_hub lõi:

>>> pip install -U "huggingface_hub"

Sử dụng Homebrew

Bạn cũng có thể cài đặt CLI bằng Homebrew:

>>> brew install hf

Xem trang Homebrew huggingface tại đây để biết thêm chi tiết.

Đang cập nhật

Để nâng cấp lên phiên bản mới nhất, hãy chạy:

>>> hf update

Điều này phát hiện cách hf được cài đặt (Homebrew, trình cài đặt độc lập, hoặc pip) và chạy lệnh cập nhật tương ứng. Nếu kỹ năng hf-cli được cài đặt toàn cục, nó cũng sẽ được làm mới để các tác nhân nhìn thấy bề mặt lệnh mới. Nếu không, nó sẽ ở trạng thái chưa được cài đặt: việc cập nhật sẽ không bao giờ cài lại nó nếu bạn đã bỏ qua hoặc gỡ bỏ nó.

Mặc định, CLI cũng in một dòng cảnh báo màu vàng ra stderr khi có phiên bản mới hơn trên PyPI. Để tắt cảnh báo này (ví dụ trong CI ngoại tuyến), hãy đặt HF_HUB_DISABLE_UPDATE_CHECK=1.

Định dạng đầu ra

Hầu hết các lệnh hf đều chấp nhận cùng một tập hợp các cờ định dạng toàn cục. Chúng được tài liệu hóa trong phần Formatting options riêng biệt trên mọi trang --help và có thể được thêm vào bất kỳ lệnh nào mà không cần phải khai báo riêng cho từng lệnh:

auto (mặc định) sẽ chọn human cho terminal tương tác và agent khi CLI được gọi bởi một AI agent. human thêm màu sắc và bảng trình bày đẹp; agent tạo ra các giá trị phân tách bằng tab mà không bị cắt ngắn; json xuất ra một đối tượng hoặc mảng JSON gọn gàng. Việc trộn lẫn hai cờ chế độ đầu ra (ví dụ --json cùng với --format human) sẽ gây ra lỗi sử dụng.

Bảng dạng văn bản tự động điều chỉnh theo chiều rộng của terminal: các cột rộng nhất chỉ bị rút ngắn khi chiều rộng tự nhiên vượt quá màn hình (do đó trên terminal rộng, bạn thường thấy giá trị đầy đủ mà không có ...). Truyền --no-truncate để ép hiển thị giá trị đầy đủ bất kể chiều rộng; dùng --format json để có đầu ra có cấu trúc cho các cột dạng list/dict.

# JSON output for scripting
>>> hf models ls --search bert --limit 2 --json | jq '.[].id'

# IDs only, one per line
>>> hf collections ls --owner nvidia -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171ea

hf auth login

Trong nhiều trường hợp, bạn phải đăng nhập vào tài khoản Hugging Face để tương tác với Hub (tải kho riêng tư, tải lên tệp, tạo PR, v.v.). Để làm điều này, hãy chạy lệnh sau trong terminal của bạn:

>>> hf auth login

Nếu bạn đã đăng nhập, lệnh này sẽ bỏ qua lời nhắc và hiển thị một thông báo. Để buộc đăng nhập lại (ví dụ: để chuyển đổi token), hãy sử dụng --force:

>>> hf auth login --force

Mặc định, lệnh này đăng nhập cho bạn bằng trình duyệt: nó in ra một URL và một mã ngắn. Mở URL, nhập mã, phê duyệt yêu cầu, và CLI sẽ lấy và lưu trữ một access token trên máy của bạn. Token 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ó.

? How would you like to log in?  [Use arrows, Enter to confirm]
> Log in with your browser
  Paste an access token

    Open this URL in your browser:
        https://huggingface.co/oauth/device

    And enter the code: ABCD-EFGH

    Waiting for authorization...
Token is valid.
The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful.

Bạn cũng có thể chọn dán User Access Token được tạo từ Settings page của bạn, theo cách tương tác (chọn Paste an access token) hoặc trực tiếp từ dòng lệnh. Để an toàn hơn, chúng tôi khuyến nghị truyền token của bạn dưới dạng biến môi trường để tránh dán nó vào lịch sử lệnh.

# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`

Khi được chạy bởi một tác nhân AI (tự động phát hiện, hoặc với --format agent), lệnh sẽ không bao giờ hỏi: nó chạy luồng trình duyệt và in ra các hướng dẫn đơn giản để tác nhân có thể chuyển tiếp cho người dùng của mình, sau đó chờ cho phép:

>>> hf auth login --format agent
Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization...
Login successful: logged in as wauplin (token saved as 'oauth-wauplin').

hf auth login là tương tác, do đó --format json và --format quiet không được hỗ trợ: hãy truyền --token cho các lần đăng nhập không tương tác, được chạy bằng script.

Để biết thêm chi tiết về xác thực, hãy xem mục này.

hf auth whoami

Nếu bạn muốn biết mình đã đăng nhập hay chưa, bạn có thể sử dụng hf auth whoami. Lệnh này không có tùy chọn nào và chỉ hiển thị tên người dùng của bạn cùng các tổ chức mà bạn là thành viên trên Hub:

hf auth whoami
Wauplin
orgs:  huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster

Nếu bạn chưa đăng nhập, một thông báo lỗi sẽ được in ra.

hf auth logout

Lệnh này sẽ đăng xuất bạn. Trên thực tế, nó sẽ xóa tất cả các token được lưu trên máy của bạn. Nếu bạn muốn xóa một token cụ thể, bạn có thể chỉ định tên token như một đối số.

Lệnh này sẽ không đăng xuất bạn nếu bạn đang đăng nhập bằng biến môi trường HF_TOKEN (xem tham khảo). Nếu đúng như vậy, bạn phải hủy đặt biến môi trường trong cấu hình máy của mình.

hf download

Sử dụng lệnh hf download để tải trực tiếp các tệp từ Hub. Bên trong, lệnh này sử dụng các hàm trợ giúp hf_hub_download() và snapshot_download() được mô tả trong hướng dẫn Tải xuống và in đường dẫn trả về ra terminal. Trong các ví dụ bên dưới, chúng ta sẽ đi qua các trường hợp sử dụng phổ biến nhất. Để xem danh sách đầy đủ các tùy chọn khả dụng, bạn có thể chạy:

hf download --help

Tải xuống một tệp duy nhất

Để tải một tệp duy nhất từ một kho, chỉ cần cung cấp repo_id và tên tệp như sau:

>>> hf download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

Lệnh sẽ luôn in ra đường dẫn đến tệp trên máy cục bộ của bạn ở dòng cuối cùng.

Để tải xuống một tệp nằm trong thư mục con của kho, bạn nên cung cấp đường dẫn của tệp trong kho ở định dạng posix như sau:

>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors

Tải xuống toàn bộ kho

Trong một số trường hợp, bạn chỉ muốn tải xuống tất cả các tệp từ một kho lưu trữ. Bạn có thể thực hiện điều này bằng cách chỉ cần chỉ định id của kho:

>>> hf download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files:   0%|                                                | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720

Tải xuống nhiều tệp

Bạn cũng có thể tải xuống một tập con các tệp từ một kho bằng một lệnh duy nhất. Điều này có thể thực hiện theo hai cách. Nếu bạn đã có danh sách chính xác các tệp muốn tải xuống, bạn chỉ cần cung cấp chúng theo thứ tự:

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files:   0%|                                                                        | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00,  3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

Cách tiếp cận khác là cung cấp các mẫu để lọc các tệp bạn muốn tải xuống bằng --include và --exclude. Ví dụ, nếu bạn muốn tải xuống tất cả các tệp safetensors từ stabilityai/stable-diffusion-xl-base-1.0, ngoại trừ các tệp ở độ chính xác FP16:

>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files:   0%|                                                                         | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b

Tải xuống một tập dữ liệu, một Space hoặc một kernel

Các ví dụ trên cho thấy cách tải xuống từ một kho lưu trữ mô hình. Để tải xuống một tập dữ liệu, một Space hoặc một kernel, hãy sử dụng tùy chọn --repo-type:

# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset

# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space

...

Tải xuống một bản sửa đổi cụ thể

Các ví dụ trên cho thấy cách tải xuống từ commit mới nhất trên nhánh main. Để tải xuống từ một revision cụ thể (hash commit, tên nhánh hoặc tag), hãy sử dụng tùy chọn --revision:

>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...

Sử dụng URI hf://

Thay vì truyền loại kho, phiên bản và đường dẫn tệp dưới dạng các đối số và tùy chọn riêng biệt, bạn có thể cung cấp một URI hf:// duy nhất. URI mã hóa mọi thứ cùng lúc, tuân theo ngữ pháp hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (xem tham chiếu HF URIs để biết cú pháp đầy đủ):

# Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download hf://datasets/bigcode/the-stack@v1.1

# Download a single file from a specific revision
>>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/HuggingFaceM4/FineVision/art/

# A bare id still works and defaults to a model repo
>>> hf download hf://openai-community/gpt2/config.json

Khi một URI được cung cấp, --repo-type và --revision cũng không thể được đặt vì chúng đã là một phần của URI (một lỗi sẽ được ném ra nếu không), và đường dẫn tệp nhúng trong URI không thể kết hợp với các tên tệp vị trí. Một / ở cuối đường dẫn chỉ định một thư mục con (giống như với đối số vị trí). Các tên nhánh chứa / phải được mã hóa URL thành %2F (ví dụ: hf://my-org/my-model@feature%2Ffoo).

Tải xuống thư mục cục bộ

Cách được khuyến nghị (và mặc định) để tải tệp từ Hub là sử dụng hệ thống cache. Tuy nhiên, trong một số trường hợp, bạn muốn tải tệp và di chuyển chúng sang một thư mục cụ thể. Điều này hữu ích để có quy trình làm việc gần với những gì các lệnh git cung cấp. Bạn có thể thực hiện điều đó bằng cách sử dụng tùy chọn --local-dir.

Một thư mục .cache/huggingface/ được tạo tại gốc của thư mục cục bộ, chứa các siêu dữ liệu về các tệp đã tải xuống. Điều này ngăn việc tải lại các tệp nếu chúng đã ở phiên bản mới nhất. Nếu siêu dữ liệu đã thay đổi, phiên bản tệp mới sẽ được tải xuống. Nhờ đó, local-dir được tối ưu hóa để chỉ lấy các thay đổi mới nhất.

Để biết thêm chi tiết về cách tải xuống tệp cục bộ hoạt động, hãy xem hướng dẫn download.

>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensors

Chế độ chạy thử

Trong một số trường hợp, bạn có thể muốn kiểm tra các tệp sẽ được tải xuống trước khi thực sự tải chúng. Bạn có thể kiểm tra điều này bằng tham số --dry-run. Tham số này liệt kê tất cả các tệp cần tải xuống trong repo và kiểm tra xem chúng đã được tải xuống hay chưa. Điều này giúp bạn có cái nhìn tổng quan về số lượng tệp cần tải xuống và kích thước của chúng.

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

Để biết thêm chi tiết, hãy xem hướng dẫn tải xuống.

Chỉ định thư mục cache

Nếu không sử dụng --local-dir, tất cả các tệp sẽ được tải xuống thư mục cache mặc định được định nghĩa bởi biến môi trường HF_HOME. Bạn có thể chỉ định một thư mục cache tùy chỉnh bằng --cache-dir:

>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745

Chỉ định một token

Để truy cập các kho lưu trữ riêng tư hoặc có kiểm soát, bạn phải sử dụng token. Mặc định, token được lưu cục bộ (dùng hf auth login) sẽ được sử dụng. Nếu bạn muốn xác thực một cách rõ ràng, hãy dùng tùy chọn --token:

>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

Chế độ im lặng

Mặc định, lệnh hf download sẽ hiển thị chi tiết. Lệnh này sẽ in ra các thông tin như thông báo cảnh báo, thông tin về các tệp đã tải xuống và thanh tiến trình. Nếu bạn muốn tắt toàn bộ những thông tin này, hãy sử dụng tùy chọn --quiet. Chỉ dòng cuối cùng (tức là đường dẫn đến các tệp đã tải xuống) sẽ được in ra. Điều này có thể hữu ích nếu bạn muốn truyền kết quả đầu ra sang một lệnh khác trong script.

>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

Thời gian chờ tải xuống

Trên các máy có kết nối chậm, bạn có thể gặp các vấn đề về hết thời gian chờ (timeout) như sau:

`httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`

Để giảm thiểu vấn đề này, bạn có thể đặt biến môi trường HF_HUB_DOWNLOAD_TIMEOUT thành một giá trị cao hơn (mặc định là 10):

export HF_HUB_DOWNLOAD_TIMEOUT=30

Để biết thêm chi tiết, hãy xem tham chiếu biến môi trường. Và chạy lại lệnh tải xuống của bạn.

hf upload

Sử dụng lệnh hf upload để tải tệp lên Hub trực tiếp. Bên trong, lệnh này sử dụng các hàm trợ giúp upload_file() và upload_folder() giống như đã mô tả trong hướng dẫn Upload. Trong các ví dụ bên dưới, chúng ta sẽ đi qua các trường hợp sử dụng phổ biến nhất. Để xem danh sách đầy đủ các tùy chọn khả dụng, bạn có thể chạy:

>>> hf upload --help

Tải lên một thư mục

Cách sử dụng mặc định của lệnh này là:

# Usage:  hf upload [repo_id] [local_path] [path_in_repo]

Để tải lên thư mục hiện tại ở gốc của kho, hãy sử dụng:

>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

Nếu kho chưa tồn tại, nó sẽ được tạo tự động.

Bạn cũng có thể tải lên một thư mục cụ thể:

>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

Cuối cùng, bạn có thể tải lên một thư mục đến một vị trí cụ thể trên kho:

>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train

Tải lên một tệp

Bạn cũng có thể tải lên một tệp duy nhất bằng cách đặt local_path trỏ đến một tệp trên máy của bạn. Nếu đó là trường hợp, path_in_repo là tùy chọn và sẽ mặc định là tên tệp cục bộ của bạn:

>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors

Nếu bạn muốn tải lên một tệp duy nhất vào một thư mục cụ thể, hãy đặt path_in_repo tương ứng:

>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors

Tải lên nhiều tệp

Để tải lên nhiều tệp từ một thư mục cùng lúc mà không tải lên toàn bộ thư mục, hãy sử dụng các mẫu --include và --exclude. Bạn cũng có thể kết hợp với tùy chọn --delete để xóa các tệp trên kho trong khi tải lên các tệp mới. Trong ví dụ bên dưới, chúng tôi đồng bộ hóa Space cục bộ bằng cách xóa các tệp từ xa và tải lên tất cả các tệp ngoại trừ các tệp trong /logs:

# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...

Tải lên một tập dữ liệu hoặc Space

Để tải lên một dataset hoặc một Space, hãy sử dụng tùy chọn --repo-type:

>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...

Tải lên một tổ chức

Để tải nội dung lên một kho thuộc về một tổ chức thay vì một kho cá nhân, bạn phải chỉ định rõ điều này trong repo_id:

>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/

Tải lên một bản sửa đổi cụ thể

Mặc định, các tệp được tải lên nhánh main. Nếu bạn muốn tải tệp lên một nhánh hoặc tham chiếu khác, hãy sử dụng tùy chọn --revision:

# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...

Lưu ý: nếu revision không tồn tại và --create-pr không được đặt, một nhánh sẽ được tạo tự động từ nhánh main.

Sử dụng URI hf://

Tương tự như hf download, đích có thể được biểu diễn dưới dạng một URI hf:// duy nhất theo ngữ pháp hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (xem tham chiếu HF URIs để biết cú pháp đầy đủ). Loại kho, phiên bản và path_in_repo đều được đọc từ URI:

# Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv

# Upload a whole folder to the root of a model repo
>>> hf upload hf://Wauplin/my-cool-model ./models

Khi một URI được cung cấp, --repo-type và --revision cũng không thể được đặt vì chúng đã là một phần của URI (một lỗi sẽ được ném ra nếu không), và một đường dẫn nhúng trong URI không thể được kết hợp với đối số path_in_repo.

Tải lên và tạo một PR

Nếu bạn không có quyền đẩy lên một kho, bạn phải mở một PR và cho các tác giả biết về những thay đổi bạn muốn thực hiện. Điều này có thể được thực hiện bằng cách đặt tùy chọn --create-pr:

# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/

Tải lên theo các khoảng thời gian đều đặn

Trong một số trường hợp, bạn có thể muốn đẩy các bản cập nhật định kỳ lên một kho. Ví dụ, điều này hữu ích nếu bạn đang huấn luyện một mô hình và muốn tải lên thư mục logs mỗi 10 phút. Bạn có thể thực hiện điều này bằng cách sử dụng tùy chọn --every:

# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10

Chỉ định thông báo commit

Sử dụng --commit-message và --commit-description để đặt thông báo và mô tả tùy chỉnh cho commit của bạn thay vì thông báo mặc định

>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

Chỉ định một token

Để tải tệp lên, bạn phải sử dụng token. Mặc định, token được lưu cục bộ (dùng hf auth login) sẽ được sử dụng. Nếu bạn muốn xác thực một cách rõ ràng, hãy dùng tùy chọn --token:

>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

Chế độ im lặng

Mặc định, lệnh hf upload sẽ hiển thị chi tiết. Lệnh này sẽ in ra các thông tin như thông báo cảnh báo, thông tin về các tệp đã tải lên và thanh tiến trình. Nếu bạn muốn tắt toàn bộ những thông tin này, hãy sử dụng tùy chọn --quiet. Chỉ dòng cuối cùng (tức là URL của các tệp đã tải lên) sẽ được in ra. Điều này có thể hữu ích nếu bạn muốn truyền kết quả đầu ra sang một lệnh khác trong script.

>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/main

hf buckets

Sử dụng hf buckets để quản lý các bucket trên Hugging Face Hub. Bucket cung cấp lưu trữ đối tượng kiểu S3 trên Hugging Face, được hỗ trợ bởi backend lưu trữ Xet. Khác với repository (dựa trên git và theo dõi lịch sử tệp), bucket là các container lưu trữ đối tượng từ xa được thiết kế cho các tệp quy mô lớn với tính năng khử trùng lặp dựa trên địa chỉ nội dung. Chúng được thiết kế cho các trường hợp sử dụng cần lưu trữ đơn giản, nhanh và có thể thay đổi, chẳng hạn như lưu trữ checkpoint huấn luyện, log, các sản phẩm trung gian, hoặc bất kỳ bộ sưu tập tệp lớn nào không cần kiểm soát phiên bản. Trong các ví dụ bên dưới, chúng ta sẽ đi qua các trường hợp sử dụng phổ biến nhất. Để xem hướng dẫn đầy đủ, hãy tham khảo hướng dẫn về Bucket.

Tạo một bucket

Để tạo một bucket mới, hãy sử dụng hf buckets create. Bucket sẽ được tạo dưới namespace của bạn theo mặc định:

>>> hf buckets create my-bucket

Bạn cũng có thể tạo một bucket riêng tư bằng cách sử dụng cờ --private:

>>> hf buckets create my-bucket --private

Liệt kê và kiểm tra các bucket

Để liệt kê tất cả các bucket của bạn, hãy sử dụng hf buckets list (hoặc dạng viết tắt hf buckets ls). Bạn cũng có thể liệt kê các bucket trong một tổ chức cụ thể:

>>> hf buckets list
ID                   PRIVATE       SIZE TOTAL_FILES CREATED_AT
-------------------- ------- ---------- ----------- ----------
username/my-bucket                   32           5 2026-02-16
username/checkpoints         117609095         700 2026-02-13
username/logs                321757477        2000 2026-02-13

# Human-readable sizes
>>> hf buckets list -h
ID                   PRIVATE     SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket               32 B           5 2026-02-16
username/checkpoints         117.6 MB         700 2026-02-13
username/logs                321.8 MB        2000 2026-02-13

# List buckets in a specific namespace
>>> hf buckets ls my-org

# Filter buckets by name
>>> hf buckets list --search "checkpoint"

Để lấy thông tin chi tiết về một bucket cụ thể (được trả về dưới dạng JSON), hãy sử dụng hf buckets info:

>>> hf buckets info username/my-bucket
{
  "id": "username/my-bucket",
  "private": false,
  "created_at": "2026-02-16T15:28:32+00:00",
  "size": 32,
  "total_files": 5
}

Thay đổi khả năng hiển thị của bucket

Để chuyển đổi một bucket giữa chế độ riêng tư và công khai, hãy sử dụng hf buckets settings:

# Make a bucket private
>>> hf buckets settings username/my-bucket --private

# Make it public again
>>> hf buckets settings username/my-bucket --public

Xóa một bucket

Để xóa một bucket, hãy sử dụng hf buckets delete. Bạn sẽ được yêu cầu xác nhận trừ khi bạn truyền --yes:

>>> hf buckets delete username/my-bucket --yes

Xóa tệp

Sử dụng hf buckets remove (hoặc dạng viết tắt hf buckets rm) để xóa các tệp khỏi một bucket.

Để xóa một tệp duy nhất, hãy chỉ định đường dẫn của tệp đó:

>>> hf buckets rm username/my-bucket/old-model.bin

Để xóa tất cả các tệp dưới một tiền tố, hãy sử dụng --recursive:

>>> hf buckets rm username/my-bucket/logs/ --recursive

Bạn cũng có thể nhắm đến tất cả các tệp trong một bucket mà không có tiền tố:

>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"

Sử dụng --dry-run để xem trước những gì sẽ bị xóa mà không thực sự xóa bất kỳ thứ gì:

>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Xem tệp

Sử dụng hf buckets list với một ID bucket để liệt kê các tệp trong bucket:

>>> hf buckets list username/my-bucket
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
              2026-01-15 10:30:00  sub/

Thêm -R để liệt kê đệ quy và -h để hiển thị kích thước tệp dễ đọc cùng ngày ngắn. Bạn cũng có thể hiển thị cây ASCII với --tree, hoặc dùng --tree --quiet để có cây sạch không có metadata:

# Recursive with human-readable sizes
>>> hf buckets list username/my-bucket -R -h
      2.0 KB         Jan 15 10:30  big.bin
         5 B         Jan 15 10:30  file.txt
        14 B         Jan 15 10:30  sub/nested.txt
         4 B         Jan 15 10:30  sub/deep/file.txt

# Tree with human-readable sizes
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB  Jan 15 10:30  ├── big.bin
   5 B  Jan 15 10:30  ├── file.txt
                      └── sub/
                          ├── deep/
   4 B  Jan 15 10:30  │       └── file.txt
  14 B  Jan 15 10:30  └── nested.txt

# Clean tree without metadata
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
    ├── deep/
    │   └── file.txt
    └── nested.txt

Để lọc theo tiền tố, hãy thêm tiền tố vào đường dẫn của bucket:

>>> hf buckets list username/my-bucket/sub -R

Sao chép tệp

Sử dụng hf cp để sao chép một tệp duy nhất giữa máy cục bộ, các kho lưu trữ và các bucket. Nguồn và đích có thể lần lượt là một đường dẫn cục bộ, một URI hf:// (kho hoặc bucket), hoặc - (stdin/stdout).

hf cp cũng được truy cập qua hf repos cp và hf buckets cp — cả ba đều là cùng một lệnh. Hãy dùng cách nào dễ đọc nhất cho quy trình làm việc của bạn.

Để tải lên một tệp (cục bộ → kho hoặc bucket):

# To a repository
>>> hf cp ./model.safetensors hf://username/my-model/model.safetensors

# To a bucket (uses the local filename when the destination ends with /)
>>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/

Để tải xuống một tệp (kho hoặc bucket → cục bộ):

# From a repository
>>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv

# From a bucket, to the current directory (destination omitted)
>>> hf cp hf://buckets/username/my-bucket/config.json

Bạn cũng có thể stream đến stdout hoặc từ stdin bằng cách sử dụng -:

# Download to stdout
>>> hf cp hf://buckets/username/my-bucket/config.json - | jq .

# Upload from stdin
>>> echo "hello" | hf cp - hf://username/my-model/hello.txt

Để sao chép giữa hai vị trí trên Hub (repo/bucket → repo/bucket):

# Repo to repo
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Repo to bucket
>>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/

# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/

Khi sao chép thư mục giữa hai vị trí trên Hub, ký tự / ở cuối đường dẫn nguồn quyết định xem chính thư mục đó có được lồng vào hay chỉ nội dung của nó được sao chép (theo kiểu rsync):

# Without trailing slash: "logs" dir is nested => archive/logs/...
>>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/

# With trailing slash: only contents of "logs" are copied => archive/...
>>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/

Ghi chú:

• hf cp sao chép một tệp duy nhất khi có liên quan đến đường dẫn cục bộ. Để sao chép toàn bộ thư mục tới/từ cục bộ, hãy sử dụng hf upload/hf download (kho) hoặc hf buckets sync (buckets).
• Chưa hỗ trợ sao chép từ bucket sang repo.
• Sao chép từ cục bộ sang cục bộ không được hỗ trợ (hãy sử dụng cp của shell).
• Việc sao chép giữa hai vị trí trên Hub chỉ hoạt động trong cùng một khu vực lưu trữ.

Đồng bộ hóa các thư mục

Sử dụng hf buckets sync để đồng bộ hóa các thư mục giữa máy cục bộ và một bucket. Lệnh này so sánh nguồn và đích, sau đó chỉ chuyển các tệp đã thay đổi.

Để tải một thư mục cục bộ lên một bucket:

>>> hf buckets sync ./data hf://buckets/username/my-bucket

Để tải từ một bucket xuống một thư mục cục bộ:

>>> hf buckets sync hf://buckets/username/my-bucket ./data

Sử dụng --delete để xóa các tệp đích không có trong nguồn:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --delete

Bạn có thể lọc các tệp cần đồng bộ bằng cách sử dụng các mẫu --include và --exclude:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"

Để chỉ cập nhật các tệp hiện có (bỏ qua tệp mới), hãy sử dụng --existing. Để chỉ tạo các tệp mới (bỏ qua tệp hiện có), hãy sử dụng --ignore-existing:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing

Để an toàn hơn, bạn có thể tạo một kế hoạch để xem xét trước khi thực thi, sau đó áp dụng nó:

# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl

# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonl

Sử dụng --dry-run để in kế hoạch đồng bộ dưới dạng JSONL ra stdout mà không thực thi bất kỳ thao tác nào. Cách này rất tiện lợi để đưa vào jq hoặc các công cụ khác:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .

hf sync là một alias cấp cao tiện lợi cho hf buckets sync. Xem hướng dẫn Buckets để biết chi tiết đầy đủ về tất cả các tùy chọn đồng bộ hóa.

hf models

Sử dụng hf models để liệt kê các model trên Hub và lấy thông tin chi tiết về một model cụ thể.

Danh sách các mô hình

# List trending models
>>> hf models ls

# Search for models
>>> hf models ls --search "lora"

# Filter by author
>>> hf models ls --author Qwen

# Filter by pipeline tag
>>> hf models ls --pipeline-tag summarization

# Filter by parameter count
>>> hf models ls --num-parameters min:6B,max:128B

# Only non-gated models
>>> hf models ls --no-gated --author google

# Only models runnable by a given app
>>> hf models ls --apps llama.cpp

# Sort by downloads
>>> hf models ls --sort downloads --limit 10

Khi được gọi với một ID mô hình, hf models ls sẽ liệt kê các tệp trong kho mô hình đó:

# List files in a model repo
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct

# List files recursively
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R

# Tree view with human-readable sizes
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h

# List files at a specific revision
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision main

Lấy thông tin mô hình

>>> hf models info Lightricks/LTX-2

Sử dụng --expand để lấy thêm các thuộc tính như downloads, likes, tags, v.v.

Lấy thẻ mô hình

Sử dụng hf models card để lấy thẻ mô hình (README) của một mô hình. Mặc định, in toàn bộ nội dung thẻ ra stdout.

# Full card (metadata + text)
>>> hf models card google/gemma-4-31B-it

# Just the metadata (from the YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --metadata

# Metadata as JSON (useful for scripting and agents)
>>> hf models card google/gemma-4-31B-it --metadata --format json

# Just the text body (no YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --text

hf datasets

Sử dụng hf datasets để liệt kê các bộ dữ liệu trên Hub và lấy thông tin chi tiết về một bộ dữ liệu cụ thể.

Liệt kê các bộ dữ liệu

# List trending datasets
>>> hf datasets ls

# Search for datasets
>>> hf datasets ls --search "code"

# List official benchmark datasets
>>> hf datasets ls --filter benchmark:official

# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10

Khi được gọi với một ID tập dữ liệu, hf datasets ls sẽ liệt kê các tệp trong kho tập dữ liệu đó:

# List files in a dataset repo
>>> hf datasets ls HuggingFaceFW/fineweb

# List files recursively with human-readable sizes
>>> hf datasets ls HuggingFaceFW/fineweb -R -h

# Tree view
>>> hf datasets ls HuggingFaceFW/fineweb --tree

Liệt kê bảng xếp hạng bộ dữ liệu

Sử dụng hf datasets leaderboard để hiển thị điểm của các mô hình đã được gửi đến một bộ dữ liệu chuẩn, giúp bạn tìm ra các mô hình tốt nhất cho một tác vụ hoặc so sánh các mô hình dựa trên điểm chuẩn.

>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format json

Lấy thông tin bộ dữ liệu

>>> hf datasets info HuggingFaceFW/fineweb

Lấy thẻ dữ liệu

Sử dụng hf datasets card để lấy thẻ dữ liệu (README) của một bộ dữ liệu. Mặc định, in toàn bộ nội dung thẻ ra stdout.

# Full card (metadata + text)
>>> hf datasets card HuggingFaceFW/fineweb

# Just the metadata (from the YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --metadata

# Metadata as JSON (useful for scripting and agents)
>>> hf datasets card HuggingFaceFW/fineweb --metadata --format json

# Just the text body (no YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --text

Liệt kê các URL parquet

Sử dụng hf datasets parquet để khám phá các URL tệp parquet của một dataset trước khi viết truy vấn SQL. Các dataset trên Hub được tự động chuyển đổi sang Parquet ở phía backend bởi dịch vụ Dataset Viewer (đối với các dataset đủ điều kiện). Xem hướng dẫn chuyển đổi Parquet để biết thêm chi tiết.

>>> hf datasets parquet cfahlgren1/hub-stats
>>> hf datasets parquet cfahlgren1/hub-stats --subset models
>>> hf datasets parquet cfahlgren1/hub-stats --split train
>>> hf datasets parquet cfahlgren1/hub-stats --format json

Bảng đầu ra mặc định bao gồm subset, split và URL tệp parquet từ Hub API.

Chạy SQL trên tập dữ liệu parquet

Sử dụng hf datasets sql để thực thi các truy vấn SQL thô bằng DuckDB trên các URL parquet của dataset. Trước tiên, khám phá các URL bằng hf datasets parquet, sau đó truy vấn chúng trực tiếp bằng read_parquet(...).

>>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"
>>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format json

Cài đặt DuckDB trước nếu cần:

# Python package
>>> pip install duckdb

# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdb

hf spaces

Sử dụng hf spaces để liệt kê các Spaces trên Hub và lấy thông tin chi tiết về một Space cụ thể.

Danh sách Spaces

# List trending Spaces
>>> hf spaces ls

# Search for Spaces
>>> hf spaces ls --search "3d"

# Sort by likes
>>> hf spaces ls --sort likes --limit 10

Khi được gọi với một ID Space, hf spaces ls sẽ liệt kê các tệp trong kho Space đó:

# List files in a Space repo
>>> hf spaces ls victor/deepsite

# List files recursively with tree view
>>> hf spaces ls victor/deepsite --tree -R -h

Lấy thông tin Space

>>> hf spaces info victor/deepsite

Lấy thẻ Space

Sử dụng hf spaces card để lấy thẻ Space (README) của một Space. Mặc định, in toàn bộ nội dung thẻ ra stdout.

# Full card (metadata + text)
>>> hf spaces card mteb/leaderboard

# Just the card metadata (from the YAML frontmatter)
>>> hf spaces card mteb/leaderboard --metadata

# Card metadata as JSON
>>> hf spaces card mteb/leaderboard --metadata --format json

# Just the text body (no YAML frontmatter)
>>> hf spaces card mteb/leaderboard --text

Việc tạm dừng hoặc khởi động lại một Space sẽ hủy bỏ container của nó, do đó mọi thứ được ghi vào hệ thống tệp tạm thời sẽ bị mất. Để lưu trữ dữ liệu qua các lần khởi động lại, hãy gắn một Volume hoặc bucket bằng hf spaces volumes set (chạy hf spaces volumes --help để xem chi tiết).

Tạm dừng một Space

Sử dụng hf spaces pause để tạm dừng một Space khi bạn không sử dụng nó (thời gian tạm dừng không bị tính phí). Khởi động lại sau đó bằng hf spaces restart.

>>> hf spaces pause username/my-space

Khởi động lại một Space

Sử dụng hf spaces restart để khởi động lại một Space. Truyền --factory-reboot để xây dựng lại Space từ đầu mà không sử dụng bộ nhớ đệm build.

>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-reboot

Chờ một Space

Sử dụng hf spaces wait để chặn cho đến khi Space hoàn tất quá trình build/khởi động và đạt đến trạng thái ổn định. Lệnh sẽ thoát với mã 0 nếu Space đang RUNNING, hoặc khác 0 trong các trường hợp khác (ví dụ: BUILD_ERROR). Tiện lợi cho việc viết script sau khi khởi động lại hoặc thay đổi phần cứng.

>>> hf spaces wait username/my-space

# With a timeout
>>> hf spaces wait username/my-space --timeout 5m

# Chain with restart
>>> hf spaces restart username/my-space && hf spaces wait username/my-space

Liệt kê phần cứng khả dụng

Sử dụng hf spaces hardware để liệt kê tất cả các tùy chọn phần cứng khả dụng cho Spaces, bao gồm cả giá cả.

>>> hf spaces hardware

Kiểm tra hạn mức ZeroGPU của bạn

Sử dụng hf spaces zero-gpu quota để kiểm tra xem bạn còn bao nhiêu hạn mức ZeroGPU và khi nào nó được đặt lại. Điều này hữu ích để theo dõi mức sử dụng của bạn khi gọi các Spaces ZeroGPU từ các script, ứng dụng hoặc agent.

>>> hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
  remaining: 1810
  base: 2400
  resets_at: 2026-09-30T18:12:03+00:00
  overquota_used: 0

>>> hf spaces zero-gpu quota --format json
{"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0}

Nếu hạn mức của bạn sắp hết, lệnh sẽ gợi ý mua thêm tín dụng từ cài đặt thanh toán của bạn để tiếp tục sử dụng ZeroGPU vượt quá hạn mức hàng ngày (chỉ dành cho người dùng PRO, Team và Enterprise).

Cập nhật cài đặt Space

Sử dụng hf spaces settings để cập nhật cài đặt của một Space.

>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium

• --sleep-time: thời gian chờ (tính bằng giây) trước khi Space ngủ. Sử dụng -1 để không bao giờ ngủ. Chỉ khả dụng trên phần cứng nâng cấp (xem tài liệu về thời gian ngủ của Spaces).
• --hardware: loại phần cứng (ví dụ: cpu-basic, t4-medium, l4x4). Chạy hf spaces hardware để xem tất cả các tùy chọn.

Quản lý bí mật của Space

Sử dụng hf spaces secrets ls để liệt kê các secrets trên một Space, hf spaces secrets add để thêm hoặc cập nhật một hoặc nhiều secrets, và hf spaces secrets delete để xóa một secret. Truyền --secrets-file PATH để tải secrets từ một tệp theo kiểu .env. Các khóa hiện có sẽ bị ghi đè.

>>> hf spaces secrets ls username/my-space
>>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
>>> hf spaces secrets add username/my-space --secrets-file .env.secrets
>>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yes

Các giá trị bí mật chỉ có thể ghi nên hf spaces secrets ls hiển thị các khóa, mô tả và thời gian cập nhật, nhưng không bao giờ hiển thị chính các giá trị bí mật.

Quản lý biến môi trường của Space

Sử dụng hf spaces variables để quản lý các biến môi trường không phải bí mật trên một Space. Khác với secrets, variables có thể đọc được, do đó ls hiển thị cả keys và values. Truyền --env-file PATH vào add để nạp từ một tệp theo kiểu .env.

>>> hf spaces variables ls username/my-space
>>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
>>> hf spaces variables add username/my-space --env-file .env
>>> hf spaces variables delete username/my-space MAX_TOKENS --yes

Truy cập Space qua SSH (Chế độ Dev)

Sử dụng hf spaces ssh để mở phiên SSH vào container Dev Mode của một Space. Nếu Dev Mode chưa được bật, CLI sẽ yêu cầu bạn bật nó (hoặc sử dụng --auto để bỏ qua lời nhắc).

Khóa công khai SSH của bạn phải được đăng ký trong cài đặt của bạn. Xem tài liệu Dev Mode để biết thêm chi tiết.

# SSH into a Space
>>> hf spaces ssh username/my-space

# Print the SSH command without running it
>>> hf spaces ssh username/my-space --dry-run

# Auto-enable Dev Mode if disabled
>>> hf spaces ssh username/my-space --auto

# Use a specific SSH key
>>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519

hf papers

Sử dụng hf papers để liệt kê, tìm kiếm, lấy thông tin có cấu trúc và đọc nội dung markdown của các bài báo trên Hub.

Danh sách các bài báo

# List most recent daily papers
>>> hf papers ls

# List trending papers
>>> hf papers ls --sort=trending

# List papers from a specific date
>>> hf papers ls --date=2025-01-23

# List today's papers
>>> hf papers ls --date=today

# List papers from a specific week
>>> hf papers ls --week=2025-W09

# List papers from a specific month
>>> hf papers ls --month=2025-02

# List papers submitted by a specific user
>>> hf papers ls --submitter=akhaliq

# Limit results
>>> hf papers ls --sort=trending --limit=5

Tìm kiếm các bài báo

# Search papers by keyword
>>> hf papers search "vision language"

# Limit search results
>>> hf papers search "diffusion models" --limit=10

# Output as JSON
>>> hf papers search "attention" --format=json

Lấy thông tin bài báo

# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621

Đọc bài báo dưới dạng markdown

# Read the full paper content as markdown
>>> hf papers read 2601.15621

hf discussions

Sử dụng hf discussions để quản lý các cuộc thảo luận và pull request trên các kho Hub trực tiếp từ terminal của bạn. Bạn có thể liệt kê, xem, tạo, bình luận, đóng, mở lại và hợp nhất cả thảo luận lẫn PR. Để xem hướng dẫn đầy đủ về cách các tính năng cộng đồng của Hub hoạt động, hãy xem hướng dẫn về Thảo luận và Pull Request.

Danh sách các cuộc thảo luận

Để liệt kê các cuộc thảo luận và PR đang mở trên một kho lưu trữ, hãy truyền ID kho vào hf discussions list (hoặc dạng viết tắt hf discussions ls):

>>> hf discussions list username/my-model

Bạn có thể thu hẹp kết quả theo loại (discussion hoặc pull_request), trạng thái (open, closed, merged hoặc all) hoặc tác giả:

>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author alice

Để viết script, hãy dùng --format json để nhận đầu ra có cấu trúc, hoặc --quiet để chỉ in ra các số thứ tự thảo luận (mỗi dòng một số):

>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quiet

Lấy thông tin cho một cuộc thảo luận hoặc PR

Để kiểm tra một cuộc thảo luận hoặc PR cụ thể, hãy truyền ID của repo và số thứ tự của cuộc thảo luận:

>>> hf discussions info username/my-model 5

Đầu ra bao gồm metadata của cuộc thảo luận (tiêu đề, trạng thái, tác giả, v.v.) cùng với danh sách đầy đủ các sự kiện hội thoại. Để hiển thị diff của một pull request, hãy sử dụng hf discussions diff thay thế.

Sử dụng --format json cho đầu ra có thể đọc được bằng máy, và đặt NO_COLOR=1 để loại bỏ màu ANSI khi chuyển hướng (pipe) sang các công cụ khác.

Tạo một cuộc thảo luận hoặc PR

Để mở một cuộc thảo luận mới, hãy cung cấp tiêu đề bằng --title. Bạn có thể tùy chọn bao gồm mô tả trực tiếp bằng --body, hoặc tải nó từ một tệp bằng --body-file:

>>> hf discussions create username/my-model --title "Bug report"
>>> hf discussions create username/my-model --title "Feature request" --body "Please add X"
>>> hf discussions create username/my-model --title "Report" --body-file report.md

Để tạo một pull request thay vì một cuộc thảo luận thông thường, hãy thêm cờ --pull-request:

>>> hf discussions create username/my-model --title "Fix typo" --pull-request

Bình luận về một cuộc thảo luận hoặc PR

Thêm bình luận vào một cuộc thảo luận hoặc PR hiện có bằng cách chỉ định số của nó. Nội dung bình luận có thể được truyền trực tiếp với --body, đọc từ một tệp với --body-file, hoặc được truyền từ stdin bằng cách sử dụng --body-file -:

>>> hf discussions comment username/my-model 5 --body "Thanks for reporting!"
>>> hf discussions comment username/my-model 5 --body-file review.md
>>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file -

Chỉnh sửa bình luận

Sửa một bình luận hiện có tại chỗ bằng cách truyền số thảo luận và ID của bình luận. ID của bình luận có thể được lấy bằng hf discussions info:

>>> hf discussions edit username/my-model 5 abc123 --body "Updated comment."
>>> hf discussions edit username/my-model 5 abc123 --body-file fixed.md

Gắn ảnh và video

Truyền --attach vào hf discussions create, comment hoặc edit để tải lên tệp hình ảnh, video hoặc âm thanh và nhúng nó vào nội dung, giống như khi bạn kéo tệp vào ô bình luận trên Hub. Nếu nội dung đã tham chiếu đến tệp, như trong ![Before the fix](./before.png), thì tham chiếu đó sẽ trỏ đến tệp đã tải lên. Ngược lại, tệp sẽ được thêm vào cuối nội dung. Để đặt văn bản alt cho một hình ảnh được thêm vào, hãy thêm nó sau #:

>>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: ![Before the fix](./before.png)" --attach ./before.png --attach "./after.png#After the fix"
>>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4

Các định dạng được hỗ trợ là PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 và WAV, tối đa 10MB (50MB đối với video).

Đóng, mở lại và hợp nhất

Bạn có thể đóng một cuộc thảo luận hoặc PR bằng hf discussions close. Mặc định, bạn sẽ được yêu cầu xác nhận. Truyền --yes để bỏ qua lời nhắc, và --comment để để lại một thông báo đóng:

>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"

Để mở lại một cuộc thảo luận đã đóng trước đó, hãy sử dụng hf discussions reopen:

>>> hf discussions reopen username/my-model 5 --yes

Để hợp nhất một pull request, hãy sử dụng hf discussions merge:

>>> hf discussions merge username/my-model 5 --yes

Đổi tên và so sánh

Bạn có thể đổi tên một cuộc thảo luận bằng cách cung cấp tiêu đề mới:

>>> hf discussions rename username/my-model 5 "Updated title"

Để xem diff của một pull request trực tiếp trong terminal, hãy sử dụng hf discussions diff:

>>> hf discussions diff username/my-model 5

hf repos

hf repos cho phép bạn liệt kê, tạo, sao chép, xóa, di chuyển các kho lưu trữ, cập nhật cài đặt của chúng và xóa các tệp trên Hugging Face Hub. Nó cũng bao gồm các lệnh con để quản lý các nhánh và thẻ.

Danh sách kho

Sử dụng hf repos ls để liệt kê tất cả các kho lưu trữ của bạn (mô hình, bộ dữ liệu, spaces và buckets) kèm thông tin lưu trữ, sắp xếp theo mức sử dụng lưu trữ. Mặc định, chỉ hiển thị 30 kho lưu trữ đầu tiên:

# List all your repos (first 30)
>>> hf repos ls
REPOSITORY                TYPE     UPDATED      VISIBILITY   STORAGE  % OF TOTAL
------------------------  -------  ----------   ----------  --------  ----------
username/bucket-raw       bucket   2026-04-29   public        1.7 TB       72.3%
username/my-model         model    2026-05-06   public        4.8 GB       18.1%
username/my-dataset       dataset  2024-09-14   private     598.4 MB        5.2%
Hint: Showing 30 of 42 repos. Use `--limit 0` to list all.

Lọc theo loại kho, tìm kiếm theo tên hoặc điều chỉnh giới hạn:

# List only models
>>> hf repos ls --type model

# Search by name
>>> hf repos ls --search "bert"

# List repos from an organization
>>> hf repos ls --namespace my-org

# Combine filters
>>> hf repos ls --namespace my-org --type dataset --search "train"

# List all repos (no limit)
>>> hf repos ls --limit 0

Sử dụng --format json cho kịch bản tự động hóa hoặc -q để chỉ lấy ID. Khi dùng pipe, hãy dùng --limit 0 để xuất tất cả các repo:

>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -q

Tạo một kho

>>> hf repos create Wauplin/my-cool-model
Successfully created Wauplin/my-cool-model on the Hub.
Your repo is now available at https://huggingface.co/Wauplin/my-cool-model

Tạo một bộ dữ liệu hoặc một Space riêng tư:

>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradio

Sử dụng --exist-ok nếu kho có thể đã tồn tại, và --resource-group-id để nhắm đến nhóm tài nguyên Enterprise.

Tạo một kho trong một khu vực cụ thể:

>>> hf repos create my-model --region us

Nhân bản một kho

Sử dụng hf repos duplicate để sao chép một model, dataset hoặc Space hiện có vào tài khoản của bạn (hoặc vào một tổ chức). Bản sao được tạo trên máy chủ và giữ nguyên lịch sử git:

>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --private

Các tệp LFS/Xet của kho mới có thể vẫn đang được sao chép ở chế độ nền sau khi lệnh hoàn tất. Trong trường hợp đó, một cảnh báo sẽ được in ra và việc tải xuống các tệp này từ kho mới có thể thất bại cho đến khi quá trình sao chép hoàn tất.

Xóa một kho

>>> hf repos delete Wauplin/my-cool-model

Bộ dữ liệu và Spaces:

>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type space

Chuyển một kho

>>> hf repos move old-namespace/my-model new-namespace/my-model

Cập nhật cài đặt kho

>>> hf repos settings Wauplin/my-cool-model --gated auto
>>> hf repos settings Wauplin/my-cool-model --private true
>>> hf repos settings Wauplin/my-cool-model --private false

• --gated: một trong auto, manual, false
• --private true|false: đặt quyền riêng tư của kho

Xóa tệp khỏi kho

Lệnh con hf repos delete-files <repo_id> cho phép bạn xóa các tệp khỏi một kho lưu trữ. Dưới đây là một số ví dụ về cách sử dụng.

Xóa một thư mục:

>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

Xóa nhiều tệp:

>>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

Sử dụng mẫu wildcard để xóa các tập hợp tệp. Các mẫu là Standard Wildcards (mẫu globbing) như được tài liệu hóa tại đây. Việc khớp mẫu dựa trên fnmatch.

Lưu ý rằng fnmatch khớp * qua các ranh giới đường dẫn, khác với globbing của shell Unix truyền thống. Ví dụ, "data/*.json" sẽ khớp cả data/file.json và data/subdir/file.json. Để chỉ khớp các tệp trong thư mục trực tiếp, bạn cần liệt kê chúng một cách rõ ràng hoặc sử dụng các mẫu cụ thể hơn.

>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

Để xóa tệp khỏi một repo, bạn phải được xác thực và cấp quyền. Mặc định, token được lưu cục bộ (dùng hf auth login) sẽ được sử dụng. Nếu bạn muốn xác thực một cách rõ ràng, hãy dùng tùy chọn --token:

>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txt

hf repos branch

Sử dụng hf repos branch để tạo và xóa các nhánh cho các kho trên Hub.

# Create a branch
>>> hf repos branch create Wauplin/my-cool-model dev

# Create a branch from a specific revision
>>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104

# Delete a branch
>>> hf repos branch delete Wauplin/my-cool-model dev

Tất cả các lệnh đều chấp nhận --repo-type (một trong model, dataset, space) và --token nếu bạn cần xác thực một cách rõ ràng. Sử dụng --help trên bất kỳ lệnh nào để xem tất cả các tùy chọn.

hf cache

Sử dụng hf cache để quản lý thư mục cache Hugging Face cục bộ của bạn. Cache lưu trữ các model, datasets, Spaces và kernels đã tải xuống từ Hub.

# List cached repositories
>>> hf cache ls

# List cached revisions
>>> hf cache ls --revisions

# Remove specific items from cache
>>> hf cache rm model/gpt2

# Remove unreferenced revisions
>>> hf cache prune

# Verify cached file checksums
>>> hf cache verify gpt2

hf cache ls

Sử dụng hf cache ls để kiểm tra những gì được lưu trữ cục bộ trong bộ nhớ đệm Hugging Face của bạn. Mặc định, lệnh này tổng hợp thông tin theo từng kho lưu trữ:

>>> hf cache ls
ID                          SIZE     LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue          157.4M 2 days ago    2 days ago    main script
model/LiquidAI/LFM2-VL-1.6B     3.2G 4 days ago    4 days ago    main
model/microsoft/UserLM-8b      32.1G 4 days ago    4 days ago    main

Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.

Thêm --revisions để xem chi tiết các snapshot cụ thể, và kết nối các bộ lọc để tập trung vào những gì quan trọng:

>>> hf cache ls --filter "size>30g" --revisions
ID                        REVISION                                 SIZE     LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691    32.1G 4 days ago    main

Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.

Lệnh hỗ trợ một số định dạng đầu ra để viết script: --format json in ra các đối tượng có cấu trúc, --format csv ghi các dòng phân tách bằng dấu phẩy, và --quiet chỉ in ra các ID. Sử dụng --sort để sắp xếp các mục theo accessed, modified, name hoặc size (thêm :asc hoặc :desc để kiểm soát thứ tự), và --limit để giới hạn kết quả ở N mục đầu tiên. Kết hợp các tùy chọn này với --cache-dir để nhắm đến các vị trí cache thay thế. Xem hướng dẫn Quản lý cache của bạn để biết các quy trình nâng cao.

Xóa các mục cache được chọn bằng hf cache ls --q bằng cách chuyển các ID vào hf cache rm:

>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
  - model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
  - model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.

hf cache rm

hf cache rm xóa các kho lưu trữ được lưu trong bộ nhớ đệm, các phiên bản riêng lẻ hoặc các tệp đơn lẻ. Truyền một hoặc nhiều ID kho (model/bert-base-uncased), URI hf://, hoặc mã băm phiên bản:

>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
  - model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.

Các URI hf:// ở cấp độ repo cũng được hỗ trợ:

>>> hf cache rm hf://models/openai-community/gpt2 --dry-run
About to delete 1 repo(s) totalling 1.1G.
  - model/openai-community/gpt2 (entire repo)
Dry run: no files were deleted.

Để xóa một tệp duy nhất thay vì toàn bộ kho, chẳng hạn một lượng tử hóa GGUF, hãy truyền một URI tệp hf://. Tệp sẽ bị xóa khỏi mọi bản sửa đổi đã được lưu trong kho, và blob của nó chỉ bị xóa nếu không còn tệp nào khác trong bộ nhớ đệm tham chiếu đến nó:

>>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
  - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.

Phiên bản vẫn có thể sử dụng, và một tệp đã bị xóa sẽ được tải xuống lại vào lần cần đến tiếp theo. Đường dẫn phải khớp chính xác: không hỗ trợ thư mục và mẫu glob, và không thể trộn lẫn các mục tiêu tệp với kho hoặc phiên bản trong cùng một cuộc gọi.

Trộn các kho và các phiên bản cụ thể trong cùng một lệnh gọi. Sử dụng --dry-run để xem trước tác động, hoặc --yes để bỏ qua lời nhắc xác nhận—tiện lợi trong các script tự động:

>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
  - model/t5-small:
      8f3ad1c [main] 1.1G
Dry run: no files were deleted.

Khi làm việc ngoài vị trí cache mặc định, hãy kết hợp lệnh với --cache-dir PATH.

hf cache prune

hf cache prune là một lệnh tắt tiện lợi để thu hồi dung lượng bị chiếm bởi rác trong bộ nhớ đệm: mọi phiên bản đã tách rời (không còn tham chiếu) (chỉ giữ lại các phiên bản vẫn có thể truy cập thông qua một nhánh hoặc thẻ), các tệp .incomplete còn sót lại từ các lượt tải bị gián đoạn, và các blob dùng chung không còn được tham chiếu bởi bất kỳ kho nào trong bộ nhớ đệm:

>>> hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
  - model/t5-small:
      1c610f6b [refs/pr/1] 820.1M
      d4ec9b72 [(detached)] 640.5M
  - dataset/google/fleurs:
      2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.

Các tệp .incomplete là những bản tải xuống chưa hoàn tất còn sót lại khi quá trình tải bị gián đoạn. Chúng không được theo dõi bởi hf cache ls/rm (vốn hoạt động ở cấp độ revision), do đó hf cache ls sẽ chỉ ra chúng kèm theo một gợi ý và hf cache prune sẽ tự động xóa chúng.

Tương tự như các lệnh cache khác, --dry-run, --yes và --cache-dir đều khả dụng. Tham khảo hướng dẫn Quản lý cache của bạn để xem thêm các ví dụ.

hf cache verify

Sử dụng hf cache verify để xác thực các tệp cục bộ theo giá trị băm (checksum) của chúng trên Hub. Bạn có thể xác thực một bản chụp (snapshot) của cache hoặc một thư mục cục bộ thông thường.

Ví dụ:

# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR

# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4

# Verify a private repo
>>> hf cache verify me/private-model --token hf_***

# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset

# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo

Mặc định, lệnh sẽ cảnh báo về các tệp bị thiếu hoặc thừa. Sử dụng cờ để chuyển các cảnh báo này thành lỗi:

>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-files

Khi thành công, bạn sẽ thấy một bản tóm tắt:

✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6
  All checksums match.

Nếu phát hiện sự không khớp, lệnh sẽ in ra danh sách chi tiết và thoát với mã trạng thái khác không.

hf repos tag

Sử dụng hf repos tag để tạo, liệt kê và xóa các thẻ cho các kho trên Hub.

# Create a tag
>>> hf repos tag create my-model v1.0

# List tags
>>> hf repos tag list my-model

# Delete a tag
>>> hf repos tag delete my-model v1.0

Đánh dấu một mô hình

Để gắn thẻ cho một kho, bạn cần cung cấp repo_id và tên tag:

>>> hf repos tag create Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-model

Đánh dấu một mô hình tại một phiên bản cụ thể

Nếu bạn muốn gắn thẻ cho một bản sửa đổi cụ thể, bạn có thể sử dụng tùy chọn --revision. Mặc định, thẻ sẽ được tạo trên nhánh main:

>>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-model

Đánh dấu một bộ dữ liệu hoặc một Space

Nếu bạn muốn gắn thẻ cho một tập dữ liệu hoặc Space, bạn phải chỉ định tùy chọn --repo-type:

>>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stack

Danh sách thẻ

Để liệt kê tất cả các thẻ của một kho lưu trữ, hãy sử dụng lệnh con list (hoặc ls):

>>> hf repos tag list Wauplin/gradio-space-ci --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1

Xóa một thẻ

Để xóa một thẻ, hãy sử dụng lệnh con delete:

>>> hf repos tag delete Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-model

Bạn cũng có thể truyền -y để bỏ qua bước xác nhận.

hf env

Lệnh hf env in ra các chi tiết về cấu hình máy của bạn. Điều này hữu ích khi bạn mở một issue trên GitHub để giúp các nhà bảo trì điều tra vấn đề của bạn.

>>> hf env

Copy-and-paste the text below in your GitHub issue.

- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx2: 2.0.0
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_DISABLE_SHARED_BLOBS: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10

hf jobs

Chạy các tác vụ tính toán trên hạ tầng của Hugging Face với giao diện tương tự Docker.

hf jobs là công cụ dòng lệnh cho phép bạn chạy bất kỳ thứ gì trên hạ tầng của Hugging Face (bao gồm cả GPU và TPU!) bằng các lệnh đơn giản. Hãy nghĩ đến docker run, nhưng dành cho việc chạy code trên A100.

Để có cái nhìn tổng quan về Jobs và bảng giá, hãy xem tài liệu Hub Jobs. Để sử dụng Python API cùng với CLI, hãy xem hướng dẫn Chạy và quản lý Jobs.

# Directly run Python code
>>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'

# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"

# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'

# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'

# Run a Python script with `uv` (experimental)
>>> hf jobs uv run --name my-script my_script.py

Hugging Face Jobs có sẵn cho bất kỳ người dùng hoặc tổ chức nào có điểm tín dụng trả trước.

Bắt đầu nhanh

1. Chạy công việc đầu tiên

# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'

Lệnh này chạy tác vụ và hiển thị nhật ký. Bạn có thể truyền --detach để chạy Job ở nền và chỉ in ra Job ID. Thêm -q để chỉ in ra Job ID, rất tiện để bắt nó trong một script:

>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"

2. Kiểm tra trạng thái công việc

# List your running jobs
>>> hf jobs ls
# List all jobs
>>> hf jobs ls -a

# Inspect the status of a job
>>> hf jobs inspect <job_id>

# View logs from a job
>>> hf jobs logs <job_id>

# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Follow live stats until the jobs complete
>>> hf jobs stats -f [job_ids]...

# Cancel a job
>>> hf jobs cancel <job_id>

# Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully)
>>> hf jobs wait <job_id> [<job_id>...]

# Wait for all currently running jobs
>>> hf jobs ls -q | xargs hf jobs wait

Các lệnh hf jobs run và hf jobs wait không tách rời sẽ thoát với mã khác không nếu Job thất bại, do đó bạn có thể nối các lệnh với nhau bằng &&:

>>> hf jobs run python:3.12 python train.py && echo "training succeeded"

3. Chạy trên GPU

Bạn cũng có thể chạy các tác vụ trên GPU hoặc TPU bằng tùy chọn --flavor. Ví dụ, để chạy một tác vụ PyTorch trên GPU A10G:

# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'

Chạy lệnh này sẽ hiển thị kết quả sau!

This code ran with the following GPU: NVIDIA A10G

Sử dụng -- để tách các tùy chọn của Jobs khỏi các đối số được truyền cho lệnh hoặc script của bạn. Jobs không diễn giải các tùy chọn sau --.

>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help

Xong rồi! Bạn đã chạy mã trên hạ tầng của Hugging Face.

Các trường hợp sử dụng phổ biến

• Đào tạo mô hình: Tinh chỉnh hoặc đào tạo mô hình trên GPU (T4, A10G, A100) mà không cần quản lý hạ tầng
• Tạo dữ liệu tổng hợp: Tạo các bộ dữ liệu quy mô lớn bằng cách sử dụng LLM trên phần cứng mạnh
• Xử lý dữ liệu: Xử lý các bộ dữ liệu lớn với cấu hình CPU cao cho các tác vụ song song
• Suy luận theo lô: Chạy suy luận ngoại tuyến trên hàng nghìn mẫu bằng cách sử dụng các cấu hình GPU được tối ưu hóa
• Thí nghiệm & Đánh giá hiệu năng: Chạy các thí nghiệm ML trên phần cứng nhất quán để có kết quả tái lập được
• Phát triển & gỡ lỗi: Kiểm tra mã GPU mà không cần cài đặt CUDA cục bộ

Truyền biến môi trường và Mật khẩu

Bạn có thể truyền các biến môi trường cho tác vụ của mình bằng

# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass secrets by name - the value is read from your environment, never from the command line
>>> hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'

# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'

# Or pipe them in, so the values touch neither the command line nor the disk
>>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'

Secrets được mã hóa phía máy chủ ở cả ba dạng. -s MY_SECRET=psswrd cũng hoạt động, nhưng giá trị sau đó sẽ xuất hiện trong lịch sử shell và trong danh sách tiến trình (/proc/<pid>/cmdline trên Linux), vì vậy CLI sẽ in cảnh báo ra stderr khi bạn sử dụng nó; hãy giữ dạng này cho các giá trị không thực sự nhạy cảm. Điều tương tự áp dụng cho --token <value>: hãy ưu tiên hf auth login hoặc biến môi trường HF_TOKEN. File env hoặc secrets nên chỉ có quyền đọc bởi bạn (chmod 600) — CLI sẽ cảnh báo nếu không.

Sử dụng --secrets HF_TOKEN để truyền token Hugging Face cục bộ của bạn một cách ngầm. Với cú pháp này, bí mật sẽ được lấy từ biến môi trường. Đối với HF_TOKEN, nếu biến môi trường chưa được đặt, hệ thống có thể đọc tệp token nằm trong thư mục home của Hugging Face.

Biến Môi Trường Tích Hợp

Bên trong container của job, các biến môi trường sau được tự động khả dụng:

# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"

Thời gian chờ quá hạn của tác vụ

Jobs có thời gian chờ mặc định là 30 phút, sau đó chúng sẽ tự động dừng. Đối với các tác vụ chạy lâu như huấn luyện mô hình, hãy đặt thời gian chờ tùy chỉnh bằng tùy chọn --timeout:

# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py

# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py  # floats are supported

Tùy chọn --timeout cũng hoạt động với các script UV và các công việc được lên lịch:

# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py

# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.py

Nếu công việc của bạn vượt quá thời gian chờ, nó sẽ bị kết thúc tự động. Luôn đặt một thời gian chờ phù hợp với một khoảng đệm cho các tác vụ chạy lâu để tránh việc công việc bị kết thúc ngoài ý muốn.

Thử lại và chạy lại một Job

--attempts đặt số lần thử tối đa, bao gồm lần chạy đầu tiên. Tham số này hoạt động với Docker, UV và các Job được lên lịch. Chạy lại một Job sẽ khởi tạo một Job mới với cùng spec đã lưu:

>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>

Số lần thử là 3 cho phép tối đa hai lần thử lại khi một Job thất bại. hf jobs rerun cũng tái sử dụng số lần thử ban đầu. Giống như hf jobs run, lệnh này sẽ stream log của Job mới cho đến khi hoàn tất. Sử dụng --detach để trả về ngay lập tức.

Phần cứng

Các tùy chọn --flavor khả dụng:

• CPU: cpu-basic, cpu-upgrade
• GPU: t4-small, t4-medium, l4x1, l4x4, a10g-small, a10g-large, a10g-largex2, a10g-largex4,a100-large
• TPU: v5e-1x1, v5e-2x2, v5e-2x4

(cập nhật vào 07/2025 từ tài liệu suggested_hardware của Hugging Face)

Dung lượng

Gắn một volume vào đĩa của Job bằng cách sử dụng -v hoặc --volume.

Bạn có thể gắn bất kỳ kho Hugging Face nào (mô hình/dataset/space) hoặc Storage Bucket bằng cách sử dụng định dạng URL hf://. Ví dụ:

• gắn kho mô hình: -v hf://openai/gpt-oss-120b:/model
• gắn một kho dữ liệu: -v hf://datasets/HuggingFaceFW/fineweb:/data
• gắn một bucket lưu trữ: -v hf://buckets/username/my-bucket:/mnt
• gắn một space: -v hf://spaces/username/my-space:/app
• gắn một thư mục con bên trong một kho: -v hf://datasets/org/ds/train:/data

Sau đó, bạn có thể sử dụng volume đã gắn như một thư mục cục bộ:

# Docker Job with a mounted volume as input
>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

# UV Job with a mounted volume to save checkpoints when training a model
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
...     sft.py --output-dir /training-outputs/training-v3-final ...

Các mô hình, bộ dữ liệu và không gian luôn được gắn ở chế độ chỉ đọc. Các bucket lưu trữ mặc định ở chế độ đọc + ghi — điều này đặc biệt hữu ích cho dữ liệu thay đổi thường xuyên, vì các tệp có thể được ghi đè hoặc xóa tại chỗ.

Sử dụng :ro để bật chế độ chỉ đọc:

• gắn một bucket lưu trữ ở chế độ chỉ đọc: -v hf://buckets/username/my-bucket:/mnt:ro

Gắn dữ liệu cục bộ

Bên nguồn của -v cũng có thể là một thư mục cục bộ. Trước tiên, nó được đồng bộ hóa vào Storage Bucket jobs-artifacts của bạn và thư mục bucket kết quả sẽ được gắn vào Job:

>>> hf jobs uv run -v ./my-data:/data process.py

Chạy lại lệnh chỉ tải lên các tệp mới hoặc đã sửa đổi. Các thư mục cục bộ được gắn (mount) ở chế độ chỉ đọc theo mặc định. Sử dụng :rw để cho phép Job ghi vào volume, ví dụ để lấy các kết quả đầu ra sau khi Job hoàn tất (một thư mục cục bộ trống cũng hoạt động được):

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
...
Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with:
  hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-out

Nhãn

Thêm nhãn vào một Job bằng -l hoặc --label. Nhãn là các cặp key=value dùng để áp dụng metadata cho một Job. Để gắn hai nhãn cho một Job, hãy lặp lại cờ nhãn (-l hoặc --label):

>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"

Khóa my-label không chỉ định giá trị nên giá trị của nó mặc định là chuỗi rỗng ("").

Sử dụng --name để thêm nhãn name khi tạo một Job. Tên giúp việc tìm kiếm và nhận diện Job trong UI dễ dàng hơn; chúng là tùy chọn và không bắt buộc phải duy nhất. Nếu bạn không truyền --name, tên sẽ được suy ra tự động từ hình ảnh Docker hoặc script, kèm theo một hash ngắn của lệnh và các cài đặt runtime đã được phân giải (flavor, timeout, giá trị môi trường, …), do đó cùng một cấu hình luôn tạo ra cùng một tên (ví dụ: python:3.12 foo --truc → python-3-12-1a2b3c4d). Việc thay đổi một cài đặt sẽ làm thay đổi tên, ngay cả khi lệnh giữ nguyên. Bạn cũng có thể đổi tên một Job hiện có:

>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2

Sử dụng --status, --label và --name trong hf jobs ls để lọc Jobs. --status nhận một hoặc nhiều trạng thái, --label nhận các cặp key=value, và --name là cách viết tắt cho --label name=NAME. Một Job phải khớp với mọi bộ lọc để được liệt kê. Tên Job cũng được hiển thị dưới dạng cột NAME riêng:

# Show completed Jobs
>>> hf jobs ls -a --status completed

# Show running or scheduling Jobs
>>> hf jobs ls --status running,scheduling

# Show Jobs named `training-v2`
>>> hf jobs ls -a --name training-v2

# Show Jobs with the `model=Qwen3-06B` label
>>> hf jobs ls -a --label model=Qwen3-06B

# Combine filters: running Jobs labelled both `env=prod` and `team=ml`
>>> hf jobs ls --status running --label env=prod --label team=ml

Mặc định, hf jobs ps hiển thị tối đa 100 Job để tránh làm đầy terminal. Sử dụng --limit để thay đổi điều này, hoặc --limit 0 để hiển thị tất cả:

# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500

# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0

Tiết lộ các cổng của Job

Sử dụng --expose cho cổng được bảo vệ bằng token và --expose-public cho cổng cho phép truy cập không xác thực. Cả hai cờ đều có thể được lặp lại và kết hợp, và hoạt động với Docker, UV và các Job được lên lịch.

# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000

# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000

# Close all exposed ports
>>> hf jobs expose <job_id> --clear

hf jobs expose nhận các cổng được bảo vệ bằng token dưới dạng đối số vị trí và các cổng công khai với --public. Lệnh này áp dụng thay đổi mà không chạy lại Job. Các cổng không được liệt kê trong danh sách thay thế sẽ bị đóng.

Truy cập Job qua SSH

Truyền --ssh cho hf jobs run (hoặc hf jobs uv run) để container của Job có thể truy cập qua SSH, sau đó kết nối bằng hf jobs ssh:

# Start a job with SSH enabled
>>> hf jobs run --ssh --detach python:3.12 sleep infinity

# Open an SSH session into it
>>> hf jobs ssh <job_id>

# Print the SSH command instead of running it
>>> hf jobs ssh <job_id> --dry-run

# Use a specific identity file
>>> hf jobs ssh <job_id> -i ~/.ssh/id_ed25519

Chỉ những người dùng có quyền ghi vào namespace của Job (người tạo Job, hoặc các thành viên của tổ chức sở hữu) mới được phép truy cập, xác thực bằng khóa công khai SSH đã đăng ký tại https://huggingface.co/settings/keys.

Các nhóm mạng

Truyền --network-group <name> cho hf jobs run (hoặc hf jobs uv run) để các Jobs trong cùng namespace và resource group có thể liên lạc với nhau trên mọi port. Bên trong mỗi thành viên, $HF_NETWORK_GROUP_HOSTNAME sẽ phân giải thành mọi Job trong nhóm, và ${HF_NETWORK_GROUP_PREFIX}<alias> sẽ phân giải thành các thành viên đã khai báo alias bằng --network-alias <alias>:

# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000

# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'

Các thành viên có thể được phân giải trước khi chúng sẵn sàng, vì vậy hãy kết nối với các lần thử lại. Tên nhóm và các alias là các ký tự alphanumerics chữ thường và gạch nối, tối đa 46 và 34 ký tự.

UV Scripts (Thử nghiệm)

Chạy các script UV (script Python có các phụ thuộc được khai báo trực tiếp trong file) trên hạ tầng của HF. Script UV là các script Python bao gồm các phụ thuộc của chúng ngay trong file bằng cách sử dụng cú pháp chú thích đặc biệt.

# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py

# Run with persistent repo
>>> hf jobs uv run --repo my-uv-scripts my_script.py

# Run with GPU
>>> hf jobs uv run --flavor t4-small ml_training.py

# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet

# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py

# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py

# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'

UV scripts là các script Python bao gồm trực tiếp các phụ thuộc của chúng ngay trong tệp bằng cú pháp chú thích đặc biệt. Điều này khiến chúng trở nên hoàn hảo cho các tác vụ tự chứa không yêu cầu cấu hình dự án phức tạp. Tìm hiểu thêm về UV scripts trong tài liệu UV.

Sử dụng -- để truyền các tùy chọn xung đột đến script của bạn. Ở đây, --help sẽ đến train.py thay vì hiển thị trợ giúp cho Jobs:

>>> hf jobs uv run --flavor t4-small train.py -- --help

Điều này cũng áp dụng cho các cờ định dạng: hf jobs run, hf jobs uv run và các biến thể scheduled của chúng sẽ tiêu thụ --format, --json và -q ở bất kỳ vị trí nào chúng xuất hiện, vì vậy hãy dùng -- khi script của bạn cần chúng.

Đóng gói cấu hình khởi chạy cùng với script

Một số script chỉ chạy chính xác trên một môi trường runtime cụ thể: một image nhất định, một loại GPU, một trình thông dịch hệ thống, v.v. Một script có thể mang theo cấu hình đó trong bảng tùy chọn [tool.hf-jobs] trong phần header PEP 723 của nó:

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# name    = "unlimited-ocr"
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# timeout = "2h"
# env     = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" }
# secrets = ["HF_TOKEN"]
# labels  = { task = "ocr" }
# volumes = ["hf://datasets/org/pdfs:/input"]
# ///

hf jobs uv run ocr.py in_ds out_ds sau đó khởi chạy với runtime phù hợp, thay vì chạy âm thầm trên image CPU với trình thông dịch sai. Bảng này không hiển thị với uv run thông thường: các bảng [tool.*] là một phần của PEP 723 và các công cụ sẽ bỏ qua những bảng không thuộc về chúng.

Các khóa được hỗ trợ, tất cả đều tùy chọn: image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group và network_aliases. Chúng ánh xạ đến các cờ có cùng tên (name được lưu dưới dạng nhãn name, volumes nhận các thông số hf://...:/MOUNT_PATH giống như -v, network_aliases là một danh sách các giá trị --network-alias). Một khóa không xác định sẽ gây ra lỗi thay vì bị bỏ qua một cách im lặng — một lỗi chính tả như flavour chính là sự cố mà tính năng này tồn tại để ngăn chặn.

Tất cả các giá trị phải là chuỗi, bao gồm cả giá trị của env và labels: -e BATCH_SIZE=64 được chuyển thành env = { BATCH_SIZE = "64" }, không phải env = { BATCH_SIZE = 64 } (TOML đọc phần sau là một số nguyên và bảng sẽ bị từ chối). Ngoại lệ duy nhất là timeout, cũng chấp nhận một số nguyên biểu thị số giây (timeout = 7200 tương đương với timeout = "2h").

Các giá trị từ script là mặc định: một cờ rõ ràng luôn được ưu tiên, và env, secrets, labels và volumes được gộp lại từng mục một, do đó -e và -v có thể bổ sung vào những gì script khai báo:

# Same script, on bigger hardware, with one extra env var
>>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_ds

network_aliases là ngoại lệ: các alias mà một Job khai báo tạo thành một tập hợp, do đó --network-alias thay thế danh sách trong script thay vì thêm vào đó. Scheduled Jobs không có network group nào, vì vậy hf jobs scheduled uv run sẽ từ chối một script khai báo network_group hoặc network_aliases.

secrets chỉ liệt kê tên của các secret: giá trị luôn được lấy từ môi trường của người chạy script, không bao giờ từ chính script (HF_TOKEN cũng được phân giải từ hf auth login). Một secret được yêu cầu nhưng không được đặt cục bộ sẽ gây ra lỗi, thay vì Job âm thầm nhận giá trị rỗng. Khi dùng --dry-run, nó sẽ được hiển thị là <not set> để cấu hình của script mà các secret chưa được cấp phát vẫn có thể nhìn thấy.

Mỗi lần chạy sẽ in lại cấu hình được gửi đi, đánh dấu các giá trị đến từ script. Sử dụng --dry-run để in ra cấu hình mà không khởi chạy bất kỳ thứ gì:

>>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds
Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job.
Job configuration:
  script   ocr.py
  args     in_ds out_ds
  image    vllm/vllm-openai:unlimited-ocr (from script)
  flavor   a10g-large
  python   /usr/bin/python3 (from script)
  timeout  2h (from script)
  env      PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script)
           BATCH_SIZE=64 (from script)
  secrets  HF_TOKEN=*** (from script)
  volumes  hf://datasets/org/pdfs:/input (from script)
  labels   task=ocr (from script)
           name=unlimited-ocr (from script)
(dry run) Job not submitted.

Điều này cũng hoạt động với các script nằm sau một URL: script sẽ được tải xuống một lần khi Job được gửi (để đọc phần header) và được chuyển đến Job như một script cục bộ, thay vì được tải xuống lại bởi container. URL phải có thể truy cập được từ máy của bạn. Giống như các script cục bộ, các script URL sử dụng điểm gắn artifacts /data được dành riêng; hãy sử dụng đường dẫn gắn khác cho các volume đầu vào của bạn.

Đối với hf jobs scheduled uv run, điều này cố định script theo nội dung của nó tại thời điểm tạo. Việc cập nhật URL nguồn sẽ không còn thay đổi các lần chạy trong tương lai: hãy tạo lại Job đã lên lịch để áp dụng phiên bản mới.

--dry-run cũng có sẵn trong hf jobs run, hf jobs scheduled run và hf jobs scheduled uv run. Nó bỏ qua việc gửi và tải lên local volume. Tên được tạo tự động cho cả Docker và UV Jobs bao gồm cấu hình khởi động đã được phân giải, do đó việc thay đổi cài đặt runtime hoặc giá trị môi trường sẽ làm thay đổi tên.

hf jobs scheduled

Lập lịch và quản lý các công việc sẽ chạy trên hạ tầng của HF.

Lịch trình phải là một trong @annually, @yearly, @monthly, @weekly, @daily, @hourly, hoặc một biểu thức lịch trình CRON (ví dụ: "0 9 * * 1" cho 9 giờ sáng mỗi thứ Hai).

# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'

# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'

# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'

# Schedule a UV script
>>> hf jobs scheduled uv run @hourly --name hourly-script my_script.py

Sử dụng các tham số giống như hf jobs run để truyền các biến môi trường, bí mật, thời gian chờ, v.v.

Quản lý các công việc được lên lịch bằng

# List your active scheduled jobs
>>> hf jobs scheduled ls

# Same filters as `hf jobs ls`: --status, --label and --name
>>> hf jobs scheduled ls --all
>>> hf jobs scheduled ls --status suspended
>>> hf jobs scheduled ls --name hourly-task --label env=prod

# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>

# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>

# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>

# Change future run times (Mondays at 9:00)
>>> hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"

# Trigger a scheduled job to run right now (does not change the schedule)
>>> hf jobs scheduled trigger <scheduled_job_id>

# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>

hf sandbox

hf sandbox khởi tạo các máy chủ đám mây cách ly được xây dựng trên nền Jobs: tạo một máy, chạy các lệnh với đầu ra được phát trực tiếp, và sao chép tệp vào/ra. Bất kỳ ảnh Docker nào có /bin/sh đều hoạt động. Xem hướng dẫn Sandboxes cho API Python và hướng dẫn khái niệm để tìm hiểu cách nó hoạt động bên trong.

Sandboxes là thử nghiệm, và API cũng như hành vi của chúng có thể thay đổi mà không có thông báo trước. Các sandbox dùng chung được thiết kế cho các tác vụ nằm trong cùng một ranh giới tin cậy; hãy sử dụng một sandbox riêng cho các tác vụ không tin tưởng lẫn nhau.

# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s

# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra

# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi

# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json

# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50a

Sử dụng --flavor để chọn phần cứng (ví dụ a10g-small), --idle-timeout để giới hạn thời gian tồn tại của sandbox, và -l / --label để gắn nhãn vào Job của nó. Để triển khai nhiều sandbox CPU giá rẻ, hãy khởi tạo một pool bằng hf sandbox pool create và tạo sandbox trong pool đó bằng hf sandbox create --pool <id> (xem hướng dẫn về Sandboxes).

Truyền biến môi trường và bí mật vào một sandbox

Có hai kênh riêng biệt, với các thuộc tính lưu trữ khác nhau:

# Plain environment variables
>>> hf sandbox create -e LOG_LEVEL=debug --env-file .env

# Secrets, read from your environment by name (nothing sensitive on the command line)
>>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN

# Secrets from a file, or piped in on stdin
>>> hf sandbox create --secrets-file .env.secrets
>>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file -

-s KEY=value cũng hoạt động, nhưng giá trị sẽ xuất hiện trong lịch sử shell và trong danh sách tiến trình, nên CLI sẽ cảnh báo về điều này trên stderr, kể cả ở chế độ im lặng. Các sandbox dạng pooled từ chối --secrets hoàn toàn: một pool không có kênh secrets được mã hóa, và hf sandbox create --pool <id> -s KEY=value sẽ báo lỗi kèm theo chỉ dẫn đến --env.

hf webhooks

hf webhooks cho phép bạn quản lý webhook trên Hugging Face Hub trực tiếp từ terminal. Webhook cho phép bạn lắng nghe các sự kiện (push, thảo luận, v.v.) trên repo, người dùng hoặc tổ chức và kích hoạt các hành động — bằng cách ping một URL từ xa hoặc bằng cách chạy một Job trên hạ tầng của Hugging Face.

Danh sách webhooks

>>> hf webhooks ls
ID           URL                                DISABLED  DOMAINS  WATCHED
wh-abc123    https://example.com/hook            False     repo     model:bert-base-uncased
wh-def456    https://example.com/other-hook      False     repo     org:HuggingFace

Sử dụng --format json cho đầu ra có thể đọc được bằng máy, hoặc -q để chỉ in các ID:

>>> hf webhooks ls --format json
>>> hf webhooks ls -q

Lấy thông tin webhook

>>> hf webhooks info wh-abc123

In ra chi tiết đầy đủ của webhook dưới dạng JSON.

Tạo webhook

Tạo một webhook để gửi các payload đến một URL:

>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased
>>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repo

Hoặc tạo một webhook kích hoạt một Job thay thế:

>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-c

Các bí mật của Job nguồn không được sao chép sang webhook. Hãy sử dụng --secrets hoặc --secrets-file (cùng cú pháp với hf jobs run) để truyền chúng cho Job được kích hoạt. Ví dụ, --secrets HF_TOKEN sẽ truyền token Hugging Face cục bộ của bạn:

>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKEN

Tùy chọn --watch sử dụng định dạng type:name trong đó type là một trong model, dataset, space, bucket, org, hoặc user. Tùy chọn này có thể được lặp lại để theo dõi nhiều mục. Sử dụng --domain để lọc sự kiện thành repo hoặc discussion, và --secret để đặt bí mật ký.

Cập nhật webhook

>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repo

Chỉ các tùy chọn được cung cấp sẽ bị thay đổi. Lưu ý rằng --watch sẽ thay thế toàn bộ danh sách được theo dõi khi được chỉ định.

Để cập nhật các bí mật của webhook được kích hoạt bởi Job, hãy truyền --job-id cùng với --secrets. Các bí mật được liệt kê sẽ thay thế các giá trị đã lưu và tất cả các bí mật khác sẽ được giữ nguyên:

>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKEN

Bật / tắt webhook

>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123

Xóa một webhook

>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123

Sử dụng --yes để bỏ qua lời nhắc xác nhận:

>>> hf webhooks delete wh-abc123 --yes

Tất cả các lệnh đều chấp nhận --token để ghi đè xác thực. Sử dụng --help trên bất kỳ lệnh nào để xem tất cả các tùy chọn.

hf endpoints

Sử dụng hf endpoints để liệt kê, triển khai, mô tả và quản lý Inference Endpoints trực tiếp từ terminal. Alias cũ hf inference-endpoints vẫn khả dụng để đảm bảo tương thích.

# Lists endpoints in your namespace
>>> hf endpoints ls

# List the hardware you can deploy on
>>> hf endpoints hardware

# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint

# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl

# List catalog entries
>>> hf endpoints catalog ls

# Show status and metadata
>>> hf endpoints describe my-endpoint

# Pause the endpoint
>>> hf endpoints pause my-endpoint

# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yes

Thêm --namespace để nhắm đến một tổ chức, --token để ghi đè xác thực.

Tìm phần cứng để triển khai

hf endpoints deploy yêu cầu năm cờ phần cứng (--vendor, --region, --accelerator, --instance-type và --instance-size). hf endpoints hardware liệt kê các tổ hợp hợp lệ, kèm theo giá mỗi replica mỗi giờ tính bằng USD và hạn mức accelerator của namespace bạn:

>>> hf endpoints hardware --vendor aws --region eu-west-1
VENDOR REGION    ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS
------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- ---------
aws    eu-west-1 cpu         intel-spr     x1                  2.0                        0.033 0/60  available
aws    eu-west-1 cpu         intel-spr     x2                  4.0                        0.067 0/60  available
aws    eu-west-1 cpu         intel-spr     x4                  8.0                        0.134 0/60  available
aws    eu-west-1 cpu         intel-spr     x8                 16.0                        0.268 0/60  available
aws    eu-west-1 cpu         intel-spr     x16                32.0                        0.536 0/60  available
aws    eu-west-1 gpu         nvidia-a10g   x1                 30.0            24            1.0 0/16  available
aws    eu-west-1 gpu         nvidia-t4     x1                 15.0            16            0.5 1/30  available
Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo <repo> --framework <framework> --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1

Các cờ lọc chính là các cờ triển khai (--vendor, --region, --accelerator, --instance-type), do đó những gì bạn lọc chính là những gì bạn truyền cho deploy. Chỉ liệt kê phần cứng mà bạn có thể triển khai ngay bây giờ: trạng thái khả dụng và còn đủ hạn mức accelerator trong namespace của bạn cho một bản sao. Thêm --all để cũng xem những gì đã bị ngừng hỗ trợ, tạm thời không khả dụng hoặc vượt quá hạn mức. --format json thêm các thông số kỹ thuật còn lại cho mỗi bản sao (vCPUs, kiến trúc, số lượng accelerator) vào mỗi mục.

Quota được tính theo từng namespace và quyết định những dòng nào được liệt kê. Nếu bạn triển khai vào một tổ chức, hãy truyền cùng một --namespace mà bạn sẽ truyền cho deploy — nếu không, bạn đang xem quota cá nhân của mình, điều này có thể vừa che giấu phần cứng mà tổ chức có thể triển khai, vừa hiển thị phần cứng mà tổ chức không thể triển khai.

Triển khai một container tùy chỉnh

Để triển khai hình ảnh Docker của riêng bạn thay vì hình ảnh do Hugging Face quản lý, hãy truyền --framework custom cùng với --custom-image. Kho mô hình được gắn tại /repository bên trong container. Sử dụng --container-args (và tùy chọn --container-command) để truyền chuỗi khởi động có dấu nháy, --env/--secrets để chèn các biến môi trường, và --type để đặt loại truy cập (public, authenticated hoặc private):

>>> hf endpoints deploy nex-n2-pro \
      --repo nex-agi/Nex-N2-Pro \
      --framework custom \
      --accelerator gpu --vendor aws --region us-east-1 \
      --instance-type nvidia-h200 --instance-size x8 \
      --custom-image nexagi/sglang:v0.5.12 \
      --health-route /health --port 30000 \
      --container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \
      --env MODEL_ID=/repository \
      --type authenticated

--container-args và --container-command không bị giới hạn ở các image tùy chỉnh: chúng ánh xạ tới model.args và model.command trong API payload, áp dụng cho cả các image được quản lý. Trên một endpoint hiện có, cả hai cờ này thay thế giá trị hiện tại thay vì thêm vào, vì vậy hãy truyền danh sách đầy đủ bạn muốn và dùng chuỗi rỗng để xóa. Các endpoint triển khai từ catalog đã có sẵn các cờ engine được tinh chỉnh, vì vậy hãy kiểm tra hf endpoints describe trước khi ghi đè lên chúng:

>>> hf endpoints update my-endpoint \
      --container-args "--enable-auto-tool-choice --tool-call-parser lfm2"

Triển khai ảnh engine được quản lý

--custom-image đơn lẻ triển khai một container tùy ý. Thêm --engine để chạy nó như một trong các engine do API quản lý (vllm, sglang, tgi, tei, llamacpp, hf-serve, …), qua đó mở khóa các cài đặt của engine đó, bao gồm --tensor-parallel-size và --data-parallel-size. vLLM và SGLang mặc định dùng một accelerator trong khi endpoint nhận mọi accelerator của instance, nên việc để cả hai không được đặt sẽ nạp model lên một accelerator và để các accelerator còn lại nhàn rỗi trong khi vẫn báo trạng thái khỏe, đây là lý do API hiện từ chối cấu hình đó:

>>> hf endpoints deploy gpt-oss-120b-vllm \
      --repo openai/gpt-oss-120b \
      --framework custom \
      --accelerator gpu --vendor aws --region us-east-1 \
      --instance-type nvidia-h200 --instance-size x8 \
      --engine vllm --custom-image vllm/vllm-openai:v0.23.0 \
      --tensor-parallel-size 8

Điều này không giống với --container-args "... --tp 8" ở trên: --tensor-parallel-size ghi vào cấu hình model.image của engine, đây là phần mà API kiểm tra đối chiếu với số lượng bộ tăng tốc của instance, trong khi --container-args chỉ thêm một cờ vào dòng lệnh. Hãy dùng --container-args cho các cờ engine không có trường image, và cho các container tùy chỉnh đơn thuần, vốn không có các trường song song.

Để tinh chỉnh lại một endpoint đang chạy, hãy truyền các kích thước riêng lẻ. model.image được gửi nguyên khối và yêu cầu url, do đó hình ảnh hiện tại của endpoint sẽ được lấy về và cập nhật tại chỗ:

>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2

hf endpoints update cũng nhận --custom-image và --engine, đây là cách duy nhất để thay đổi image của một endpoint từ CLI. Lệnh này thay thế model.image thay vì vá (patch) nó, vì vậy hãy chạy hf endpoints describe trước và truyền lại những gì bạn muốn giữ.

hf endpoints catalog

Sử dụng hf endpoints catalog để tương tác với Model Catalog của Inference Endpoints. Triển khai các mô hình trực tiếp từ catalog với các cấu hình được tối ưu hóa.

Mỗi model trong catalog đi kèm một hoặc nhiều recipes: tổ hợp phần cứng và engine đã được kiểm tra cho model đó. hf endpoints catalog ls in ra một dòng cho mỗi recipe, do đó một model có cả recipe GPU và Neuron sẽ xuất hiện hai lần:

# List available catalog models
>>> hf endpoints catalog ls
REPO_ID                             TASK               LICENSE    ACCELERATOR ENGINE   GGUF_FILE                     RECIPE_ID
----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- -------------------------
meta-llama/Llama-3.1-8B-Instruct    text-generation    Llama 3.1  gpu         vllm                                   sizzling-biryani-g4xsi1ac
meta-llama/Llama-3.1-8B-Instruct    text-generation    Llama 3.1  neuron      vllmNeuron                             artisanal-quinoa-yz9ynamx
bartowski/QwQ-32B-Preview-GGUF      text-generation    Apache 2.0 gpu         llamacpp QwQ-32B-Preview-Q8_0.gguf     baked-orange-m863gx7d

# Narrow it down
>>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10

--accelerator, --engine, --license, --task, --search và --limit đều lọc phía máy chủ.

# Deploy the default recipe of a model
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct

# Deploy an exact recipe listed above
>>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx

# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpoint

Với --repo, công thức mặc định có thể được thu hẹp bằng --accelerator (cpu, gpu, neuron) và --gguf-file (đối với các model có một công thức cho mỗi mức lượng tử hóa). Cả hai đều bị từ chối khi dùng cùng với --recipe, vốn đã chỉ định một công thức duy nhất.