快速入門

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() 函式將檔案新增到您新建立的倉庫。您需要指定

要上傳檔案的路徑。
檔案在倉庫中的路徑。
要新增檔案的倉庫 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 上的模型，透過多種服務執行推理。

< > 在 GitHub 上更新

Hub Python 庫