# 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. > [!TIP] > 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 đủ về tất cả các lệnh và tùy chọn, hãy xem [tham chiếu CLI](../package_reference/cli). > [!TIP] > Đ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](https://huggingface.co/docs/hub/agents-cli). > ```bash > # 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: ```bash >>> curl -LsSf https://hf.co/cli/install.sh | bash ``` Trên Windows: ```powershell >>> 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`](https://huggingface.co/docs/hub/agents-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ó: ```bash >>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill ``` ```powershell >>> 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: ```bash >>> 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](../installation). > [!TIP] > 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`](https://docs.astral.sh/uv/concepts/tools/). 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](https://docs.astral.sh/uv/getting-started/installation/) để biết các bước thực hiện. Sau đó, sử dụng CLI trực tiếp: ```bash >>> uvx hf auth login >>> uvx hf download >>> uvx hf ... ``` > [!TIP] > `uvx hf` sử dụng gói PyPI [`hf`](https://pypi.org/project/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: ```bash >>> pip install -U "huggingface_hub" ``` ### Sử dụng Homebrew Bạn cũng có thể cài đặt CLI bằng [Homebrew](https://brew.sh/): ```bash >>> brew install hf ``` Xem trang Homebrew huggingface [tại đây](https://formulae.brew.sh/formula/hf) để 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: ```bash >>> 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: | Cờ | Tương đương | Mô tả | | ---- | ---------- | ----------- | | `--format ` | — | Chọn định dạng đầu ra một cách rõ ràng. Các giá trị được chấp nhận: `auto` (mặc định), `human`, `agent`, `json`, `quiet`. | | `--json` | `--format json` | In JSON có cấu trúc. Hữu ích để truyền vào `jq` hoặc các script khác. | | `-q`, `--quiet` | `--format quiet` | Chỉ in các ID (mỗi dòng một ID). Hữu ích để chuyển các ID sang các lệnh khác. | | `--no-truncate` | — | Hiển thị đầy đủ các giá trị trong bảng dạng người dùng thay vì rút ngắn các giá trị dài bằng `...`. Bảng có thể vượt quá chiều rộng của terminal. Sử dụng `--format json` để có đầu ra có cấu trúc cho các cột list/dict. | `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 kết hợp hai cờ chế độ đầu ra (ví dụ `--json` cùng với `--format table`) 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. ```bash # 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 ``` > [!TIP] ## 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: ```bash >>> 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`: ```bash >>> 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](https://huggingface.co/docs/hub/security-tokens) được tạo từ [Settings page](https://huggingface.co/settings/tokens) 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. ```bash # 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: ```bash >>> 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](../quick-start#authentication). ## 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: ```bash 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](../package_reference/environment_variables#hftoken)). 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download) và [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download) được mô tả trong hướng dẫn [Tải xuống](./download) 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: ```bash 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: ```bash >>> 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: ```bash >>> 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: ```bash >>> hf download HuggingFaceH4/zephyr-7b-beta Fetching 23 files: 0%| | 0/23 [00:00>> hf download gpt2 config.json model.safetensors Fetching 2 files: 0%| | 0/2 [00:00>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"* Fetching 8 files: 0%| | 0/8 [00:00>> 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`: ```bash >>> 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://[/][@][/]` (xem [tham chiếu HF URIs](../package_reference/hf_uris) để biết cú pháp đầy đủ): ```bash # 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. > [!TIP] > Để 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](./download#download-files-to-a-local-folder). ```bash >>> 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. ```sh >>> 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](./download#dry-run-mode). ### 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](../package_reference/environment_variables#hfhome) `HF_HOME`. Bạn có thể chỉ định một thư mục cache tùy chỉnh bằng `--cache-dir`: ```bash >>> 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`: ```bash >>> 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. ```bash >>> 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: ```bash `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): ```bash 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](../package_reference/environment_variables#hfhubdownloadtimeout). 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_file) và [upload_folder()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) giống như đã mô tả trong hướng dẫn [Upload](./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: ```bash >>> 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à: ```bash # 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: ```bash >>> hf upload my-cool-model . . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` > [!TIP] > 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ể: ```bash >>> 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: ```bash >>> 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: ```bash >>> 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: ```bash >>> 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`: ```bash # 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`: ```bash >>> 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`: ```bash >>> 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`: ```bash # 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://[/][@][/]` (xem [tham chiếu HF URIs](../package_reference/hf_uris) để biết cú pháp đầy đủ). Loại kho, phiên bản và `path_in_repo` đều được đọc từ URI: ```bash # 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. Bạn có thể làm điều này bằng cách đặt tùy chọn `--create-pr`: ```bash # 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`: ```bash # 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 ```bash >>> 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`: ```bash >>> 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. ```bash >>> 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](./buckets). ### 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: ```bash >>> 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`: ```bash >>> 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ể: ```bash >>> 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`: ```bash >>> 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`: ```bash # 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`: ```bash >>> 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 đó: ```bash >>> 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`: ```bash >>> 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ố: ```bash >>> 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ì: ```bash >>> 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: ```bash >>> 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: ```bash # 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: ```bash >>> 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). > [!TIP] > `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): ```bash # 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ộ): ```bash # 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 `-`: ```bash # 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): ```bash # 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): ```bash # 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ữ](https://huggingface.co/docs/hub/storage-regions). ### Đồ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: ```bash >>> 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ộ: ```bash >>> 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: ```bash >>> 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`: ```bash >>> 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`: ```bash >>> 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ó: ```bash # 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: ```bash >>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq . ``` > [!TIP] > `hf sync` là một alias cấp cao tiện lợi cho `hf buckets sync`. Xem [hướng dẫn Buckets](./buckets#sync-directories) để 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 ```bash # 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 đó: ```bash # 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 ```bash >>> 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. ```bash # 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 ```bash # 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 đó: ```bash # 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. ```bash >>> 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 ```bash >>> 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. ```bash # 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](https://huggingface.co/docs/dataset-viewer/parquet) để biết thêm chi tiết. ```bash >>> 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, hãy 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(...)`. ```bash >>> 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: ```bash # 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 ```bash # 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 đó: ```bash # 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 ```bash >>> 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. ```bash # 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 ``` > [!TIP] > 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`. ```bash >>> 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. ```bash >>> 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. ```bash >>> 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ả. ```bash >>> 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](https://huggingface.co/docs/hub/spaces-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. ```bash >>> 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](https://huggingface.co/settings/billing?add-credits=true) 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. ```bash >>> 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](https://huggingface.co/docs/hub/spaces-gpus#sleep-time)). - `--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 đè. ```bash >>> 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 ``` > [!NOTE] > 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`. ```bash >>> 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](https://huggingface.co/settings/keys). Xem [tài liệu Dev Mode](https://huggingface.co/docs/hub/spaces-dev-mode) để biết thêm chi tiết. ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Get structured metadata for a paper (returns JSON) >>> hf papers info 2601.15621 ``` ### Đọc bài báo dưới dạng markdown ```bash # 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](./community). ### 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`): ```bash >>> 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ả: ```bash >>> 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ố): ```bash >>> 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: ```bash >>> 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`: ```bash >>> 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`: ```bash >>> 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 -`: ```bash >>> 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`: ```bash >>> 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 `#`: ```bash >>> 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: ```bash >>> 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`: ```bash >>> hf discussions reopen username/my-model 5 --yes ``` Để hợp nhất một pull request, hãy sử dụng `hf discussions merge`: ```bash >>> 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: ```bash >>> 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`: ```bash >>> 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: ```bash # 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: ```bash # 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: ```bash >>> hf repos ls --limit 0 --format json | jq '.[].id' >>> hf repos ls -q ``` ### Tạo một kho ```bash >>> 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ư: ```bash >>> 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ể: ```bash >>> 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: ```bash >>> 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 ```bash >>> hf repos delete Wauplin/my-cool-model ``` Bộ dữ liệu và Spaces: ```bash >>> hf repos delete my-cool-dataset --repo-type dataset >>> hf repos delete my-gradio-space --repo-type space ``` ### Chuyển một kho ```bash >>> hf repos move old-namespace/my-model new-namespace/my-model ``` ### Cập nhật cài đặt kho ```bash >>> 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 ` 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: ```bash >>> 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: ```bash >>> 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](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Việc khớp mẫu dựa trên [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). > [!WARNING] > 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. ```bash >>> 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`: ```bash >>> 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. ```bash # 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 ``` > [!TIP] > 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. ```bash # 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ữ: ```bash >>> 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: ```bash >>> 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](./manage-cache) để 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`: ```bash >>> 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: ```bash >>> 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ợ: ```bash >>> 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ó: ```bash >>> 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: ```bash >>> 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: ```bash >>> 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](./manage-cache) để 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ụ: ```bash # 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: ```bash >>> 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: ```text ✅ 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. ```bash # 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`: ```bash >>> 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`: ```bash >>> 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`: ```bash >>> 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`): ```bash >>> 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`: ```bash >>> 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](https://github.com/huggingface/huggingface_hub) để giúp các nhà bảo trì điều tra vấn đề của bạn. ```bash >>> 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](https://huggingface.co/docs/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](./jobs). ```bash # 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 ``` > [!TIP] > **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](https://huggingface.co/settings/billing). ### Bắt đầu nhanh #### 1. Chạy công việc đầu tiên ```bash # 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: ```bash >>> 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 ```bash # List your running jobs >>> hf jobs ls # List all jobs >>> hf jobs ls -a # Inspect the status of a job >>> hf jobs inspect # View logs from a job >>> hf jobs logs # 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 # Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully) >>> hf jobs wait [...] # 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 `&&`: ```bash >>> 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: ```bash # 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! ```bash This code ran with the following GPU: NVIDIA A10G ``` Sử dụng `--` để phân 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 `--`. ```bash >>> 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 ```bash # 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"])' ``` ```bash # 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"])' ``` ```bash # 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"])' ``` ```bash # 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"])' ``` ```bash # 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ị sẽ xuất hiện trong lịch sử shell và trong danh sách tiến trình (`/proc//cmdline` trên Linux), do đó CLI sẽ in cảnh báo ra stderr khi bạn sử dụng dạng này; 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 `: 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. > [!TIP] > 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: | Biến | Mô tả | | ------------- | ------------------------------------------------------------------------------------------------------- | | `JOB_ID` | Định danh duy nhất của tác vụ hiện tại. Sử dụng định danh này để tham chiếu tác vụ một cách lập trình. | | `ACCELERATOR` | Loại bộ tăng tốc khả dụng (ví dụ: `t4-medium`, `a10g-small`, `a100x4`). Để trống nếu không có bộ tăng tốc. | | `CPU_CORES` | Số lượng lõi CPU có sẵn cho tác vụ (ví dụ: `2`, `4`, `8`). | | `MEMORY` | Lượng bộ nhớ khả dụng cho công việc (ví dụ: `16Gi`, `32Gi`). | ```bash # 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`: ```bash # 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: ```bash # 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 ``` > [!WARNING] > 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: ```bash >>> hf jobs run --attempts 3 --detach python:3.12 python train.py >>> hf jobs rerun ``` 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](https://huggingface.co/docs/hub/en/spaces-config-reference) 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](/docs/hub/storage-buckets) 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ộ: ```bash # 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](/docs/hub/storage-buckets) `jobs-artifacts` của bạn và thư mục bucket kết quả sẽ được gắn vào Job: ```bash >>> 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): ```bash >>> 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`): ```bash >>> 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 không đổi. Bạn cũng có thể đổi tên một Job hiện có: ```bash >>> hf jobs run --name training-v2 python:3.12 python train.py >>> hf jobs labels --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: ```bash # 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ả: ```bash # 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. ```bash # 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 8000 --public 9000 # Close all exposed ports >>> hf jobs expose --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`: ```bash # 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 # Print the SSH command instead of running it >>> hf jobs ssh --dry-run # Use a specific identity file >>> hf jobs ssh -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 ` 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}` sẽ phân giải thành các thành viên đã khai báo alias bằng `--network-alias `: ```bash # 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. ```bash # 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](https://docs.astral.sh/uv/guides/scripts/). 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: ```bash >>> 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ó: ```python # /// 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: ```bash # 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 đó. Các Job được lên lịch không có nhóm mạng 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à `` để 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ì: ```bash >>> 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. ``` > [!TIP] > Đ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). ```bash # 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 ```bash # 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 # Suspend (pause) a scheduled job >>> hf jobs scheduled suspend # Resume a scheduled job >>> hf jobs scheduled resume # Change future run times (Mondays at 9:00) >>> hf jobs scheduled reschedule "0 9 * * 1" # Trigger a scheduled job to run right now (does not change the schedule) >>> hf jobs scheduled trigger # Delete a scheduled job >>> hf jobs scheduled delete ``` ## 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](./sandbox) cho API Python và [hướng dẫn khái niệm](../concepts/sandbox) để tìm hiểu cách nó hoạt động bên trong. > [!NOTE] > 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. ```bash # 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 ` (xem [hướng dẫn về Sandboxes](./sandbox#from-the-cli)). ### 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: | channel | flags | sandbox chuyên dụng | sandbox được gom nhóm (`--pool`) | | ----------- | ------------------------------------ | -------------------------- | ----------------------------------------------------------------- | | môi trường | `-e` / `--env`, `--env-file` | được lưu trữ trong metadata của job | được chuyển đến host khi tạo, không được lưu trong metadata của job | | secrets | `-s` / `--secrets`, `--secrets-file` | được mã hóa phía máy chủ | **không khả dụng** — sử dụng `--env` | ```bash # 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, do đó 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 -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 ```bash >>> 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: ```bash >>> hf webhooks ls --format json >>> hf webhooks ls -q ``` ### Lấy thông tin webhook ```bash >>> 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: ```bash >>> 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ế: ```bash >>> 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: ```bash >>> 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 ```bash >>> 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: ```bash >>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKEN ``` ### Bật / tắt webhook ```bash >>> hf webhooks enable wh-abc123 >>> hf webhooks disable wh-abc123 ``` ### Xóa một webhook ```bash >>> 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: ```bash >>> hf webhooks delete wh-abc123 --yes ``` > [!TIP] > 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. ```bash # 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 ``` > [!TIP] > 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: ```bash >>> 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 --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. > [!TIP] > 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`): ```bash >>> 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: ```bash >>> 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 đó: ```bash >>> 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ỗ: ```bash >>> 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: ```bash # 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ủ. ```bash # 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.