使用者訪問令牌

什麼是使用者訪問令牌？

使用者訪問令牌是驗證應用程式或筆記本連線到 Hugging Face 服務時的首選方式。您可以在您的設定中管理您的訪問令牌。

訪問令牌允許應用程式和筆記本執行由以下角色範圍所指定的特定操作：

• fine-grained（細粒度）：具有此角色的令牌可用於提供對特定資源（例如特定組織中的一個或多個模型）的細粒度訪問。這種型別的令牌在生產環境中非常有用，因為您可以使用自己的令牌而無需共享所有資源的訪問許可權。

• read（讀取）：具有此角色的令牌只能用於提供對您可以讀取的倉庫的讀取許可權。這包括您或您所屬組織擁有的公開和私有倉庫。如果您只需要從 Hugging Face Hub 讀取內容（例如下載私有模型或進行推理），請使用此角色。

• write（寫入）：具有此角色的令牌還會授予對您具有寫入許可權的倉庫的寫入許可權。如果您需要建立內容或將其推送至倉庫（例如訓練模型或修改模型卡片），請使用此令牌。

如果您是具有讀取/寫入/管理員角色的組織成員，那麼根據令牌許可權（讀取/寫入）和組織成員身份（讀取/寫入/管理員），您的使用者訪問令牌將能夠讀取/寫入相應資源。

如何管理使用者訪問令牌？

要建立訪問令牌，請轉到您的設定，然後點選訪問令牌選項卡 (Access Tokens)。點選 **New token** 按鈕以建立一個新的使用者訪問令牌。

為您的令牌選擇一個角色和名稱，大功告成——您可以開始了！

您可以透過點選 **Manage** 按鈕來刪除和重新整理使用者訪問令牌。

如何使用使用者訪問令牌？

有多種方式可以使用使用者訪問令牌來訪問 Hugging Face Hub，這為您在其上構建出色的應用程式提供了所需的靈活性。

使用者訪問令牌可以：

• 替代密碼，透過 git 或基礎認證 (basic authentication) 訪問 Hugging Face Hub。
• 在呼叫推理提供商 (Inference Providers)時作為 持有者令牌 (bearer token) 傳遞。
• 用於 Hugging Face 的 Python 庫中，例如 transformers 或 datasets。

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

儘量不要洩露您的令牌！雖然您隨時可以輪換它，但在此期間任何人都可以讀取或寫入您的私有倉庫，這太糟糕了 💩

最佳實踐

我們建議您為每個應用或每種用途建立一個訪問令牌。例如，您可以為以下用途分別建立令牌：

• 一臺本地機器。
• 一個 Colab 筆記本。
• 一個出色的自定義推理伺服器。

這樣，您就可以在不影響其他用途的情況下使其中一個令牌失效。

我們還建議在生產環境中僅使用細粒度令牌。這樣即使發生洩露，影響也會降到最低，並且可以在不影響您個人賬戶的情況下在組織內共享。

例如，如果您的生產應用程式需要對受限模型的讀取許可權，您所屬組織的成員可以申請該模型的訪問許可權，然後建立一個具有該模型讀取許可權的細粒度令牌。此令牌隨後可用於您的生產應用程式，而無需授予其對您所有私有模型的訪問許可權。

針對企業版組織

如果您的組織需要以程式設計方式為成員頒發令牌，而無需每位使用者建立自己的令牌，請參閱 OAuth 令牌交換。這項企業版方案功能非常適合構建內部平臺、CI/CD 流水線或需要代表組織成員訪問 Hugging Face 資源的自定義整合。

具有令牌管理政策的組織中的令牌

團隊版和企業版方案的組織可以強制執行令牌政策，這些政策會影響您在訪問該組織資源時的令牌運作方式。

當您的令牌需要審批時（團隊版和企業版組織）

當您建立了一個範圍限定於需要管理員審批的組織的細粒度令牌時，該令牌會自動進入 **Pending**（待處理）狀態。在管理員批准之前，它無法訪問該組織的資源。當您的令牌獲得批准或被拒絕時，您將收到一封電子郵件通知。

您可以從令牌列表頁面檢視狀態，待處理的令牌在其許可權徽章旁邊會顯示一個橙色的沙漏圖示，而被拒絕或吊銷的令牌則顯示一個紅色的感嘆號圖示。如果您的令牌被拒絕或吊銷，令牌編輯頁面上還會出現一個紅色的錯誤橫幅。

如果您是該組織的管理員，則您建立的範圍限定於該組織的細粒度令牌會自動獲得批准——無需稽核步驟。

當您的令牌被拒絕時（團隊版和企業版組織）

如果您的令牌被拒絕，您將收到一封電子郵件通知。該令牌仍保留在您的賬戶中，並仍可用於訪問組織以外的資源。被拒絕的令牌稍後可由管理員批准，從而恢復訪問許可權，而無需您建立新令牌。

嘗試對組織資源使用被拒絕的令牌時，您將收到 403 錯誤。

當您的令牌被吊銷時（企業版組織）

吊銷是永久性的。與拒絕不同，被吊銷的令牌無法恢復。如果您的令牌已被吊銷，您必須將其刪除並建立新令牌。如果組織需要管理員審批，新令牌將以待處理狀態開始。

嘗試對組織資源使用被吊銷的令牌時，您將收到 403 錯誤，並顯示以下訊息：*“您的令牌已被組織管理員吊銷，您無法再訪問組織資源。請聯絡他們以獲取更多資訊。”*

吊銷僅影響執行吊銷操作的組織。該令牌對於其範圍內涵蓋的所有其他資源繼續正常工作。

當您的組織僅允許細粒度令牌時（團隊版和企業版組織）

如果您的組織設定了要求使用細粒度令牌的政策，那麼在對該組織資源使用讀取/寫入 (read/write) 令牌時，將會被拒絕並返回 403 錯誤。