用户访问令牌

什么是用户访问令牌？

用户访问令牌是应用程序或笔记本向 Hugging Face 服务进行身份验证的首选方式。您可以在您的 设置 中管理访问令牌。

访问令牌允许应用程序和笔记本执行以下角色范围中指定的特定操作：

• fine-grained：具有此角色的令牌可用于为特定资源（例如特定模型或特定组织中的模型）提供细粒度访问权限。这种类型的令牌在生产环境中非常有用，因为您可以使用自己的令牌，而无需共享对所有资源的访问权限。

• read：具有此角色的令牌只能用于提供对您有权读取的仓库的读取访问权限。这包括您或您所属组织拥有的公共和私有仓库。如果您只需要从 Hugging Face Hub 读取内容（例如下载私有模型或执行推理），请使用此角色。

• write：具有此角色的令牌还会授予对您拥有写入权限的仓库的写入访问权限。如果您需要创建或推送内容到仓库（例如，在训练模型或修改模型卡片时），请使用此令牌。

如果您是拥有读取/写入/管理员角色的组织成员，那么您的用户访问令牌将根据令牌权限（读取/写入）和组织成员身份（读取/写入/管理员）来读取/写入资源。

如何管理用户访问令牌？

要创建访问令牌，请前往您的设置，然后单击 访问令牌选项卡。单击 新建令牌 按钮以创建新的用户访问令牌。

选择令牌的角色和名称，然后大功告成——一切就绪！

您可以点击 Manage 按钮来删除和刷新用户访问令牌。

如何使用用户访问令牌？

使用用户访问令牌访问 Hugging Face Hub 的方式多种多样，为您提供构建出色应用所需的灵活性。

用户访问令牌可以是：

• 使用 代替密码 通过 git 或基本身份验证访问 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 笔记本。
• 一个出色的自定义推理服务器。

这样，您可以使一个令牌失效，而不会影响其他使用场景。

我们还建议在生产环境中仅使用细粒度令牌。如果发生泄露，其影响范围将更小，并且可以在您的组织内共享，而不会影响您的账户。

例如，如果您的生产环境应用需要访问某个受限模型，您所在组织的成员可以先申请该模型的访问权限，然后创建一个仅具有该模型读取权限的细粒度令牌。随后，您可以在生产环境应用中使用此令牌，而无需授予其访问所有私有模型的权限。

用于 CI/CD 流水线

如果您只需要在 CI/CD 工作流（GitHub Actions、GitLab CI、CircleCI 等）中访问，可以完全避免将访问令牌存储为 CI 机密。请参阅 Trusted Publishers，它会在每次运行开始时，用您的 CI 提供商的 OpenID Connect (OIDC) 身份令牌换取一个短生命周期的 Hub 令牌——可以是仓库范围的（用于发布模型、数据集、Spaces 或内核，或以只读方式拉取它们），也可以是用户范围的（用于读取您有权访问的受限仓库并获取您账户的速率限制）。

面向企业组织

如果您的组织需要以编程方式为成员颁发令牌，而无需每位用户自行创建令牌，请参阅 OAuth Token Exchange。此企业版功能非常适合构建内部平台、CI/CD 流水线或需要代表组织成员访问 Hugging Face 资源的自定义集成。

撤销泄露的令牌

如果您的某个令牌已泄露，请从设置中的 访问令牌选项卡 中删除或刷新它。

如果您发现了他人的 Hugging Face 访问令牌，可以通过 POST /api/credentials/revoke 端点将其作废。您无需拥有该令牌所属账户或组织的任何权限。

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

您可以在单次调用中通过 credentials 数组传入多个令牌值，这对于以批量方式报告扫描结果的密钥扫描流水线非常方便。

每个与现有令牌匹配的已提交令牌都会立即失效，并在所有位置停止工作——这与组织级别的吊销不同，后者仅切断令牌对单个组织的访问权限。令牌的所有者会收到电子邮件通知，并需要创建新令牌以恢复访问权限。

该端点始终返回 202 Accepted，无论您提交的令牌是否存在，因此无法通过其响应来探测令牌是否有效。重复提交同一令牌是无害的：重复调用不会产生任何影响，且所有者只会收到一次通知。

为避免在 shell 历史记录或日志中泄露令牌值，请通过环境变量或文件传递令牌，并避免将原始令牌直接粘贴到命令行中。

具有令牌管理策略的组织中的令牌

使用团队版和企业版计划的组织可以强制执行令牌策略，这些策略会影响您在访问该组织资源时令牌的工作方式。

当您的令牌需要审批时（团队和企业组织）

当创建一个细粒度令牌并将其限定到需要管理员审批的组织时，该令牌会自动进入待处理状态。在管理员批准之前，它无法访问该组织的资源。当您的令牌被批准或拒绝时，您将收到电子邮件通知。

您可以从令牌列表页面查看状态：待处理的令牌在其权限徽章旁显示一个橙色沙漏图标，而被拒绝或已吊销的令牌则显示一个红色感叹号图标。如果您的令牌被拒绝或已吊销，其编辑页面也会显示一条红色错误横幅。

如果您是组织的管理员，您创建的限定于该组织范围的细粒度令牌会自动获得批准——无需审核步骤。

当您的令牌被拒绝时（Team & Enterprise 组织）

如果您的令牌被拒绝，您将收到一封电子邮件通知。该令牌仍保留在您的账户中，并且可以继续用于组织外部的资源。被拒绝的令牌之后可以由管理员批准，从而恢复访问权限，而您无需创建新的令牌。

尝试使用被拒绝的令牌访问组织资源时，您将收到 403 错误。

当您的令牌被撤销时（企业组织）

吊销是永久性的。与拒绝不同，被吊销的令牌无法恢复。如果您的令牌已被吊销，您必须将其删除并创建一个新的令牌。如果组织要求管理员审批，新令牌将处于待处理状态。

尝试使用已吊销的令牌访问组织资源时，您将收到 403 错误，并显示以下消息：“您的令牌已被组织管理员吊销，您无法再访问组织资源。请联系他们以获取更多信息。”

撤销操作仅影响执行撤销的组织。该令牌在其作用范围内的所有其他资源上仍可正常工作。

当您的组织仅允许使用细粒度令牌（团队和企业组织）时

如果您的组织已设置要求使用细粒度令牌的政策，则在使用读写令牌访问该组织的资源时，将被拒绝并返回 403 错误。