Hub Python 庫文件
命令列介面 (CLI)
並獲得增強的文件體驗
開始使用
命令列介面 (CLI)
huggingface_hub Python 包自帶一個名為 hf 的 CLI。此工具允許您直接從終端與 Hugging Face Hub 互動。例如，您可以登入您的帳戶、建立倉庫、上傳和下載檔案等。它還附帶了用於配置您的機器或管理快取的便捷功能。在本指南中，我們將介紹 CLI 的主要功能以及如何使用它們。
開始使用
首先，讓我們安裝 CLI
>>> pip install -U "huggingface_hub[cli]"在上面的程式碼片段中，我們還安裝了 [cli] 額外依賴項，以改善使用者體驗，尤其是在使用 cache delete 命令時。
安裝完成後，您可以檢查 CLI 是否正確設定
>>> hf --help
usage: hf <command> [<args>]
positional arguments:
{auth,cache,download,repo,repo-files,upload,upload-large-folder,env,version,lfs-enable-largefiles,lfs-multipart-upload}
hf command helpers
auth Manage authentication (login, logout, etc.).
cache Manage local cache directory.
download Download files from the Hub
repo Manage repos on the Hub.
repo-files Manage files in a repo on the Hub.
upload Upload a file or a folder to the Hub. Recommended for single-commit uploads.
upload-large-folder
Upload a large folder to the Hub. Recommended for resumable uploads.
env Print information about the environment.
version Print information about the hf version.
options:
-h, --help show this help message and exit如果 CLI 正確安裝，您應該會看到 CLI 中所有可用選項的列表。如果您收到錯誤訊息，例如 command not found: hf，請參閱安裝指南。
--help 選項非常方便，可以獲取有關命令的更多詳細資訊。您可以隨時使用它來列出所有可用選項及其詳細資訊。例如，hf upload --help 提供了有關如何使用 CLI 上傳檔案的更多資訊。
替代安裝
使用 pkgx
Pkgx 是一個超快的跨平臺包管理器，可以執行任何東西。您可以使用 pkgx 安裝 huggingface-cli，如下所示：
>>> pkgx install huggingface-cli
或者您可以直接執行 huggingface-cli
>>> pkgx huggingface-cli --help檢視 pkgx huggingface 頁面此處獲取更多詳細資訊。
使用 Homebrew
您還可以使用Homebrew安裝 CLI
>>> brew install huggingface-cli
檢視 Homebrew huggingface 頁面此處獲取更多詳細資訊。
hf auth login
在許多情況下，您必須登入 Hugging Face 帳戶才能與 Hub 互動（下載私有倉庫、上傳檔案、建立 PR 等）。為此，您需要從設定頁面獲取使用者訪問令牌。使用者訪問令牌用於向 Hub 驗證您的身份。如果您想上傳或修改內容，請確保設定具有寫入許可權的令牌。
獲得令牌後，在終端中執行以下命令
>>> hf auth login
此命令將提示您輸入令牌。複製貼上您的令牌並按 Enter。然後，系統會詢問您是否應將令牌儲存為 git 憑據。如果您打算在本地使用 git，請再次按 Enter（預設為是）。最後，它將呼叫 Hub 來檢查您的令牌是否有效並將其儲存到本地。
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_|
_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_|
To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Enter your token (input will not be visible):
Add token as git credential? (Y/n)
Token is valid (permission: write).
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或者，如果您想在不被提示的情況下登入，您可以直接從命令列傳遞令牌。為了更安全，我們建議將您的令牌作為環境變數傳遞，以避免將其貼上到您的命令歷史記錄中。
# 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`有關身份驗證的更多詳細資訊，請檢視此部分。
hf auth whoami
如果您想知道是否已登入，可以使用 hf auth whoami。此命令沒有任何選項，只打印您的使用者名稱和您所屬的 Hub 組織
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster如果您未登入，將列印錯誤訊息。
hf auth logout
此命令會登出您。實際上，它將刪除您機器上儲存的所有令牌。如果您想刪除特定令牌，可以將其名稱指定為引數。
如果您使用 HF_TOKEN 環境變數登入（請參閱參考），此命令不會登出您。在這種情況下，您必須在機器配置中取消設定該環境變數。
hf download
使用 hf download 命令直接從 Hub 下載檔案。在內部，它使用hf_hub_download() 和snapshot_download() 輔助函式，這些函式在下載指南中描述，並列印返回的路徑到終端。在下面的示例中，我們將介紹最常見的用例。有關可用選項的完整列表，您可以執行
hf download --help下載單個檔案
要從倉庫下載單個檔案，只需提供倉庫 ID 和檔名，如下所示
>>> 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
命令將始終在最後一行列印檔案在您本地機器上的路徑。
要下載位於倉庫子目錄中的檔案，您應該按 POSIX 格式提供檔案在倉庫中的路徑，如下所示
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors
下載整個倉庫
在某些情況下，您只想下載倉庫中的所有檔案。這可以透過僅指定倉庫 ID 來完成
>>> hf download HuggingFaceH4/zephyr-7b-beta Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s] ... ... /home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720
下載多個檔案
您還可以透過單個命令下載倉庫中的部分檔案。這可以透過兩種方式完成。如果您已經有一個要下載的精確檔案列表，您可以簡單地按順序提供它們
>>> hf download gpt2 config.json model.safetensors Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s] downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o (…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s] Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
另一種方法是提供模式以使用 --include 和 --exclude 過濾要下載的檔案。例如，如果您想從 stabilityai/stable-diffusion-xl-base-1.0 下載所有 safetensors 檔案，但 FP16 精度檔案除外
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b下載資料集或空間
上面的示例展示瞭如何從模型倉庫下載。要下載資料集或空間，請使用 --repo-type 選項
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space
...下載特定修訂版
上面的示例展示瞭如何從主分支的最新提交下載。要從特定修訂版（提交雜湊、分支名稱或標籤）下載，請使用 --revision 選項
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1 ...
下載到本地資料夾
從 Hub 下載檔案的推薦（也是預設）方式是使用快取系統。但是，在某些情況下，您希望下載檔案並將其移動到特定資料夾。這對於使工作流更接近 git 命令所提供的功能非常有用。您可以使用 --local-dir 選項來完成此操作。
在本地目錄的根目錄中建立了一個 .cache/huggingface/ 資料夾，其中包含有關已下載檔案的元資料。這可以防止在檔案已是最新狀態時重新下載檔案。如果元資料已更改，則下載新檔案版本。這使得 local-dir 針對僅拉取最新更改進行了最佳化。
有關下載到本地檔案如何工作的更多詳細資訊，請檢視下載指南。
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu ... fuyu/model-00001-of-00002.safetensors
指定快取目錄
如果不使用 --local-dir，所有檔案預設將下載到 HF_HOME 環境變數定義的快取目錄。您可以使用 --cache-dir 指定自定義快取
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache ... ./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745
指定令牌
要訪問私有或受限倉庫，您必須使用令牌。預設情況下，將使用本地儲存的令牌（使用 hf auth login）。如果您想顯式進行身份驗證，請使用 --token 選項
>>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
靜默模式
預設情況下，hf download 命令將非常詳細。它將列印警告訊息、有關下載檔案的資訊和進度條等詳細資訊。如果您想靜默所有這些，請使用 --quiet 選項。只打印最後一行（即下載檔案的路徑）。如果您想在指令碼中將輸出傳遞給另一個命令，這可能會很有用。
>>> hf download gpt2 --quiet /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
下載超時
在連線速度較慢的機器上，您可能會遇到超時問題，例如以下情況
`requests.exceptions.ReadTimeout: (ReadTimeoutError("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`為了緩解此問題，您可以將 HF_HUB_DOWNLOAD_TIMEOUT 環境變數設定為更高的值（預設為 10）
export HF_HUB_DOWNLOAD_TIMEOUT=30有關更多詳細資訊，請檢視環境變數參考。並重新執行您的下載命令。
hf upload
使用 hf upload 命令直接將檔案上傳到 Hub。在內部，它使用upload_file() 和upload_folder() 輔助函式，這些函式在上傳指南中描述。在下面的示例中，我們將介紹最常見的用例。有關可用選項的完整列表，您可以執行
>>> hf upload --help上傳整個資料夾
此命令的預設用法是
# Usage: hf upload [repo_id] [local_path] [path_in_repo]要將當前目錄上傳到倉庫的根目錄，請使用
>>> hf upload my-cool-model . . https://huggingface.co/Wauplin/my-cool-model/tree/main/
如果倉庫尚不存在，它將自動建立。
您還可以上傳特定資料夾
>>> hf upload my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main/
最後，您可以將資料夾上傳到倉庫中的特定目的地
>>> hf upload my-cool-model ./path/to/curated/data /data/train https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train
上傳單個檔案
您還可以透過將 local_path 指向您機器上的檔案來上傳單個檔案。在這種情況下，path_in_repo 是可選的，並且將預設為您的本地檔名
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors
如果您想將單個檔案上傳到特定目錄，請相應地設定 path_in_repo
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors
上傳多個檔案
要一次性上傳資料夾中的多個檔案而不上傳整個資料夾，請使用 --include 和 --exclude 模式。它還可以與 --delete 選項結合使用，以在上傳新檔案的同時刪除倉庫中的檔案。在下面的示例中，我們透過刪除遠端檔案並上傳除 /logs 中的所有檔案來同步本地空間。
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...上傳到資料集或空間
要上傳到資料集或空間，請使用 --repo-type 選項
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset ...
上傳到組織
要將內容上傳到組織擁有的倉庫而不是個人倉庫，您必須在 repo_id 中明確指定
>>> hf upload MyCoolOrganization/my-cool-model . . https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/
上傳到特定版本
預設情況下，檔案上傳到 main 分支。如果您想將檔案上傳到其他分支或引用，請使用 --revision 選項
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...注意：如果 revision 不存在且未設定 --create-pr，則將自動從 main 分支建立分支。
上傳並建立 PR
如果您沒有許可權推送到倉庫，您必須開啟一個 PR 並告知作者您要進行的更改。這可以透過設定 --create-pr 選項來完成
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/定期上傳
在某些情況下，您可能希望定期更新倉庫。例如，如果您正在訓練模型並希望每 10 分鐘上傳一次日誌資料夾，這會很有用。您可以使用 --every 選項來執行此操作。
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10指定提交訊息
使用 --commit-message 和 --commit-description 設定自定義的提交訊息和描述，而不是預設的
>>> 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指定令牌
要上傳檔案，您必須使用令牌。預設情況下，將使用本地儲存的令牌（使用 hf auth login）。如果您想顯式進行身份驗證，請使用 --token 選項
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_**** ... https://huggingface.co/Wauplin/my-cool-model/tree/main
靜默模式
預設情況下，hf upload 命令將非常詳細。它將列印警告訊息、有關上傳檔案的資訊和進度條。如果您想靜默所有這些，請使用 --quiet 選項。只打印最後一行（即上傳檔案的 URL）。如果您想在指令碼中將輸出傳遞給另一個命令，這可能會很有用。
>>> hf upload Wauplin/my-cool-model ./models . --quiet https://huggingface.co/Wauplin/my-cool-model/tree/main
hf repo-files
如果您想從 Hugging Face 倉庫中刪除檔案，請使用 hf repo-files 命令。
刪除檔案
hf repo-files delete <repo_id> 子命令允許您從倉庫中刪除檔案。以下是一些用法示例。
刪除資料夾
>>> hf repo-files delete Wauplin/my-cool-model folder/ Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
刪除多個檔案
>>> hf repo-files delete Wauplin/my-cool-model file.txt folder/pytorch_model.bin Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
使用 Unix 風格的萬用字元刪除檔案集
>>> hf repo-files delete Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...指定令牌
要從倉庫中刪除檔案，您必須經過身份驗證和授權。預設情況下，將使用本地儲存的令牌（使用 hf auth login）。如果您想顯式進行身份驗證，請使用 --token 選項
>>> hf repo-files delete --token=hf_**** Wauplin/my-cool-model file.txt
hf cache scan
如果您想知道您下載了哪些倉庫以及它們在磁碟上佔用了多少空間，掃描快取目錄會很有用。您可以透過執行 hf cache scan 來完成此操作
>>> hf cache scan
REPO ID REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH
--------------------------- --------- ------------ -------- ------------- ------------- ------------------- -------------------------------------------------------------------------
glue dataset 116.3K 15 4 days ago 4 days ago 2.4.0, main, 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue
google/fleurs dataset 64.9M 6 1 week ago 1 week ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs
Jean-Baptiste/camembert-ner model 441.0M 7 2 weeks ago 16 hours ago main /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner
bert-base-cased model 1.9G 13 1 week ago 2 years ago /home/wauplin/.cache/huggingface/hub/models--bert-base-cased
t5-base model 10.1K 3 3 months ago 3 months ago main /home/wauplin/.cache/huggingface/hub/models--t5-base
t5-small model 970.7M 11 3 days ago 3 days ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/models--t5-small
Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.有關如何掃描快取目錄的更多詳細資訊，請參閱管理快取指南。
hf cache delete
hf cache delete 是一種工具，可幫助您刪除不再使用的快取部分。這對於節省和釋放磁碟空間非常有用。要了解有關使用此命令的更多資訊，請參閱管理快取指南。
hf repo tag create
hf repo tag create 命令允許您為倉庫新增標籤、取消標籤和列出標籤。
為模型新增標籤
要為倉庫新增標籤，您需要提供 repo_id 和 tag 名稱
>>> hf repo 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
在特定修訂版本上為模型新增標籤
如果要為特定修訂版本新增標籤，可以使用 --revision 選項。預設情況下，標籤將建立在 main 分支上
>>> hf repo 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
為資料集或空間新增標籤
如果要為資料集或空間新增標籤，則必須指定 --repo-type 選項
>>> hf repo 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
列出標籤
要列出倉庫的所有標籤，請使用 -l 或 --list 選項
>>> hf repo tag create Wauplin/gradio-space-ci -l --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刪除標籤
要刪除標籤，請使用 -d 或 --delete 選項
>>> hf repo tag create -d 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
您還可以傳遞 -y 來跳過確認步驟。
hf env
hf env 命令列印有關您的機器設定的詳細資訊。當您在 GitHub 上提交問題時，這有助於維護人員調查您的問題。
>>> hf env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 0.19.0.dev0
- Platform: Linux-6.2.0-36-generic-x86_64-with-glibc2.35
- Python version: 3.10.12
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- FastAI: N/A
- Tensorflow: 2.11.0
- Torch: 1.12.1
- Jinja2: 3.1.2
- Graphviz: 0.20.1
- Pydot: 1.4.2
- Pillow: 9.2.0
- hf_transfer: 0.1.3
- gradio: 4.0.2
- tensorboard: 2.6
- numpy: 1.23.2
- pydantic: 2.4.2
- aiohttp: 3.8.4
- 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_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_ENABLE_HF_TRANSFER: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10hf jobs
使用熟悉的 Docker 類似介面在 Hugging Face 基礎設施上執行計算作業。
hf jobs 是一個命令列工具，它允許您透過簡單的命令在 Hugging Face 的基礎設施（包括 GPU 和 TPU！）上執行任何東西。可以將其視為 docker run，但用於在 A100 上執行程式碼。
# Directly run Python code
>>> hf jobs run 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 my_script.py✨ 主要功能
- 🐳 類似 Docker 的 CLI：熟悉的命令（
run、ps、logs、inspect）來執行和管理作業 - 🔥 任何硬體：從 CPU 到 A100 GPU 和 TPU pod - 使用簡單的標誌即可切換
- 📦 執行任何內容：使用 Docker 映象、HF Spaces 或您的自定義容器
- 🔐 簡單身份驗證：只需使用您的 HF 令牌
- 📊 即時監控：即時流式傳輸日誌，就像在本地執行一樣
- 💰 按使用付費：只按使用秒數付費
快速入門
1. 執行您的第一個作業
# Run a simple Python script
>>> hf jobs run python:3.12 python -c "print('Hello from HF compute!')"此命令執行作業並顯示日誌。您可以傳遞 --detach 在後臺執行作業並僅列印作業 ID。
2. 檢查作業狀態
# List your running jobs
>>> hf jobs ps
# Inspect the status of a job
>>> hf jobs inspect <job_id>
# View logs from a job
>>> hf jobs logs <job_id>
# Cancel a job
>>> hf jobs cancel <job_id>3. 在 GPU 上執行
您還可以使用 --flavor 選項在 GPU 或 TPU 上執行作業。例如，要在 A10G GPU 上執行 PyTorch 作業
# 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()}")"執行此命令將顯示以下輸出！
This code ran with the following GPU: NVIDIA A10G
就這樣！您現在正在 Hugging Face 的基礎設施上執行程式碼。
常見用例
- 模型訓練：在 GPU（T4、A10G、A100）上微調或訓練模型，無需管理基礎設施
- 合成數據生成：使用強大的硬體上的 LLM 生成大規模資料集
- 資料處理：使用高 CPU 配置處理海量資料集以進行並行工作負載
- 批次推理：使用最佳化的 GPU 設定對數千個樣本進行離線推理
- 實驗與基準測試：在一致的硬體上執行 ML 實驗以獲得可重現的結果
- 開發與除錯：無需本地 CUDA 設定即可測試 GPU 程式碼
傳遞環境變數和金鑰
您可以使用以下方式將環境變數傳遞給您的作業
# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c "import os; print(os.environ['FOO'], os.environ['BAR'])"# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c "import os; print(os.environ['FOO'], os.environ['BAR'])"# Pass secrets - they will be encrypted server side
>>> hf jobs run -s MY_SECRET=psswrd python:3.12 python -c "import os; print(os.environ['MY_SECRET'])"# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c "import os; print(os.environ['MY_SECRET'])"使用 --secrets HF_TOKEN 隱式傳遞您的本地 Hugging Face 令牌。使用此語法，將從環境變數中檢索金鑰。對於 HF_TOKEN，如果未設定環境變數，它可能會讀取位於 Hugging Face 主資料夾中的令牌檔案。
硬體
可用的 --flavor 選項
- 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
（於 2025 年 7 月從 Hugging Face suggested_hardware docs 更新）
UV 指令碼（實驗性）
在 HF 基礎設施上執行 UV 指令碼（帶內聯依賴項的 Python 指令碼）
# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py
# Run with persistent repo
>>> hf jobs uv run my_script.py --repo my-uv-scripts
# Run with GPU
>>> hf jobs uv run ml_training.py --flavor gpu-t4-small
# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet --repo data-scripts
# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.pyUV 指令碼是 Python 指令碼，它使用特殊的註釋語法直接將依賴項包含在檔案中。這使得它們非常適合不需要複雜專案設定的自包含任務。在 UV 文件中瞭解有關 UV 指令碼的更多資訊。
< > 在 GitHub 上更新