快速入門

Hugging Face Hub 是分享機器學習模型、展示（demos）、資料集與指標的首選平台。huggingface_hub 程式庫能協助您在不離開開發環境的情況下與 Hub 互動。您可以輕鬆建立並管理儲存庫、下載與上傳檔案，並從 Hub 取得實用的模型與資料集詮釋資料（metadata）。

安裝

若要開始使用，請安裝 huggingface_hub 程式庫

pip install --upgrade huggingface_hub

更多詳細資訊，請參閱安裝指南。

huggingface_hub 同時也隨附一個 hf CLI，讓您能直接從終端機與 Hub 互動。如果您正在使用 AI 代理（如 Claude Code、Codex、Cursor 等），請安裝相關技能（Skill）以讓您的代理使用此 CLI。

已複製

# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude

請查看 Hugging Face AI 代理 CLI 指南以取得更多詳細資訊。

下載檔案

Hub 上的儲存庫皆使用 git 版本控制，使用者可以下載單一檔案或整個儲存庫。您可以使用 hf_hub_download() 函式來下載檔案。此函式會將檔案下載並快取至您的本機磁碟。下次您需要該檔案時，系統將會直接從快取載入，因此無需重新下載。

您需要提供儲存庫 ID 與您想下載的檔案名稱。例如，若要下載 Pegasus 模型設定檔

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

若要下載特定版本的檔案，請使用 revision 參數來指定分支名稱、標籤（tag）或提交雜湊值（commit hash）。如果您選擇使用提交雜湊值，必須使用完整長度的雜湊值，而非縮短後的 7 字元雜湊值。

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

關於更多詳細資訊與選項，請參閱 hf_hub_download() 的 API 參考文件。

身份驗證

在許多情況下，您必須通過 Hugging Face 帳號驗證才能與 Hub 互動，例如：下載私人儲存庫、上傳檔案、建立 PR（合併請求）等。如果您還沒有帳號，請建立帳號，然後登入並從您的設定頁面取得使用者存取權杖（User Access Token）。使用者存取權杖用於向 Hub 驗證您的身分。

權杖可以擁有 read（讀取）或 write（寫入）權限。如果您想要建立或編輯儲存庫，請確保擁有 write 存取權杖。否則，建議產生 read 權杖，以降低萬一權杖不慎外洩時的風險。

登入指令

最簡單的驗證方式是將權杖儲存在您的機器上。您可以使用終端機透過 login() 指令來完成。

hf auth login

如果您已經登入，該指令會立即返回。若要強制重新登入，請使用 hf auth login --force。如果您尚未登入，系統會提示您輸入權杖。權杖隨後會經過驗證並儲存在您的 HF_HOME 目錄中（預設路徑為 ~/.cache/huggingface/token）。任何與 Hub 互動的指令碼或程式庫在發送請求時都會使用此權杖。

或者，您也可以在筆記本或指令碼中透過 login() 進行程式化登入。

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

您一次只能登入一個帳號。登入新帳號會自動登出先前的帳號。若要確定您當前使用中的帳號，只需執行 hf auth whoami 指令即可。

一旦登入，所有對 Hub 發出的請求（即使是那些不一定需要驗證的方法）預設都會使用您的存取權杖。若要停用隱含的權杖使用，請將 HF_HUB_DISABLE_IMPLICIT_TOKEN=1 設定為環境變數（請參閱參考文件）。

在本機管理多個權杖

您只需使用 login() 指令分別登入各個權杖，即可在機器上儲存多個權杖。如果您需要在本機切換這些權杖，可以使用 auth switch 指令。

hf auth switch

此指令會提示您從已儲存的權杖清單中選擇一個名稱。選定後，該權杖將成為「使用中」（active）權杖，並用於所有與 Hub 的互動。

您可以使用 hf auth list 列出機器上所有可用的存取權杖。

環境變數

環境變數 HF_TOKEN 也可用於驗證。這在 Space 中特別有用，您可以將 HF_TOKEN 設定為 Space secret。

最新消息：Google Colaboratory 允許您為筆記本定義 私密金鑰 (private keys)。定義一個 HF_TOKEN 秘密資訊，即可自動完成驗證！

透過環境變數或 secret 進行的驗證，優先順序高於儲存在您機器上的權杖。

方法參數

最後，也可以透過將您的權杖傳遞給任何接受 token 作為參數的方法來進行驗證。

from huggingface_hub import whoami

user = whoami(token=...)

除非是在不想永久儲存權杖的環境中，或需要同時處理多個權杖的情況，否則通常不建議這樣做。

將權杖作為參數傳遞時請務必小心。最佳做法是從安全金庫（vault）載入權杖，而非將其硬編碼（hardcode）在程式碼庫或筆記本中。若不慎分享了程式碼，硬編碼的權杖會造成重大的洩漏風險。

建立儲存庫

註冊並登入後，使用 create_repo() 函式建立一個儲存庫。

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

如果您想要將儲存庫設為私人，則

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

私人儲存庫除了您自己以外，其他人皆無法查看。

若要建立儲存庫或將內容推送到 Hub，您必須提供具有 write 權限的使用者存取權杖。您可以在設定頁面建立權杖時選擇此權限。

上傳檔案

使用 upload_file() 函式將檔案加入您剛建立的儲存庫。您需要指定：

1. 要上傳的檔案路徑。
2. 儲存庫中檔案的路徑。
3. 您想加入檔案的儲存庫 ID。

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

若要一次上傳多個檔案，請查看上傳指南，其中會介紹幾種上傳檔案的方法（包含使用 git 與不使用 git 的方式）。

後續步驟

huggingface_hub 程式庫為使用者提供了透過 Python 與 Hub 互動的簡易方式。若要進一步了解如何管理 Hub 上的檔案與儲存庫，建議閱讀我們的操作指南 (how-to guides)，以：

• 管理您的儲存庫.
• 從 Hub 下載檔案。
• 向 Hub 上傳檔案。
• 搜尋 Hub 以找到您想要的模型或資料集。
• 針對託管在 Hugging Face Hub 上的模型，透過多種服務執行推論 (Inference)。