快速入門

The Hugging Face Hub 是分享機器學習模型、演示、資料集和指標的首選場所。huggingface_hub 庫可幫助您在不離開開發環境的情況下與 Hub 進行互動。您可以輕鬆地建立和管理倉庫，下載和上傳檔案，並從 Hub 獲取有用的模型和資料集元資料。

安裝

要開始，請安裝 huggingface_hub 庫

pip install --upgrade huggingface_hub

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

下載檔案

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 引數指定分支名稱、標籤或提交雜湊。如果您選擇使用提交雜湊，則必須使用完整雜湊，而不是較短的 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 等。如果您還沒有帳戶，請 建立帳戶，然後登入以從您的 設定頁面 獲取您的 使用者訪問令牌。使用者訪問令牌用於向 Hub 驗證您的身份。

令牌具有 read 或 write 許可權。如果您想建立或編輯倉庫，請確保擁有 write 訪問令牌。否則，最好生成一個 read 令牌，以減少令牌意外洩露時的風險。

登入命令

最簡單的身份驗證方法是將令牌儲存在本地。您可以使用終端中的 login() 命令執行此操作

hf auth login

該命令會告知您是否已登入，並提示您輸入令牌。然後，令牌會被驗證並儲存在您的 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

此命令將提示您從已儲存令牌的列表中選擇一個令牌（按名稱）。選擇後，所選令牌將成為活動令牌，並將用於與 Hub 的所有互動。

您可以使用 hf auth list 命令列出本地所有可用的訪問令牌。

環境變數

環境變數 HF_TOKEN 也可用於進行身份驗證。這在使用 Space 時特別有用，因為您可以將 HF_TOKEN 設定為 Space 秘密。

新功能： Google Colaboratory 允許您為筆記本定義 私鑰。定義 HF_TOKEN 秘密即可自動進行身份驗證！

透過環境變數或秘密進行身份驗證的優先順序高於本地儲存的令牌。

方法引數

最後，您還可以透過將令牌傳遞給接受 token 引數的任何方法來進行身份驗證。

from huggingface_hub import whoami

user = whoami(token=...)

這通常不被推薦，除非在您不想永久儲存令牌的環境中，或者您需要處理多個令牌。

請小心處理令牌引數。將令牌硬編碼到程式碼庫或筆記本中存在重大的洩露風險，建議始終從安全庫載入令牌。如果您不小心共享了程式碼，硬編碼的令牌會帶來很大的風險。

建立倉庫

註冊並登入後，使用 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）。

後續步驟

huggingface_hub 庫為使用者提供了一種方便的方式，可以透過 Python 與 Hub 進行互動。要了解有關如何管理 Hub 上的檔案和倉庫的更多資訊，我們建議閱讀我們的 操作指南 以

• 管理您的倉庫.
• 從 Hub 下載 檔案。
• 將檔案上傳 到 Hub。
• 搜尋 Hub 以查詢您想要的模型或資料集。
• 執行推理，跨多個服務對 Hugging Face Hub 上託管的模型進行推理。