Hub 文档
门控模型
并获得增强的文档体验
开始使用
门控模型
为了更好地控制模型的使用方式,Hub 允许模型作者为其模型启用**访问请求**。启用此功能后,用户必须同意与模型作者共享其联系信息(用户名和电子邮件地址)才能访问模型文件。模型作者可以为此请求配置额外的字段。启用访问请求的模型称为**门控模型**。访问请求始终授予个人用户,而非整个组织。门控模型的一个常见用例是在广泛发布之前提供对早期研究模型的访问。
作为模型作者管理门控模型
要启用访问请求,请转到模型设置页面。默认情况下,模型未被门控。单击右上角的**启用访问请求**。


默认情况下,当用户请求访问模型时,系统会自动授予他们访问权限。这称为**自动批准**。在此模式下,任何用户一旦与您共享其个人信息,即可访问您的模型。


如果您希望手动批准哪些用户可以访问您的模型,则必须将其设置为**手动批准**。在这种情况下,您会看到更多选项。
- **添加访问权限**允许您搜索用户并授予其访问权限,即使他们未提出请求。
- **通知频率**允许您配置何时在新用户请求访问时收到通知。可以设置为每天一次或实时。默认情况下,电子邮件会发送到您的主要电子邮件地址。对于组织托管的模型,电子邮件默认发送给组织的前5位管理员。在这两种情况下(用户或组织),您都可以在**通知电子邮件**字段中设置不同的电子邮件地址。


审查访问请求
启用访问请求后,无论批准模式是手动还是自动,您都可以完全控制谁可以访问您的模型。您可以通过 UI 或 API 审查和管理请求。
通过 UI
您可以通过单击**审查访问请求**按钮,从其设置页面审查谁可以访问您的门控模型。这将打开一个包含3个用户列表的模式窗口:
- **待处理**:等待批准以访问您的模型的用户列表。除非您选择了**手动批准**,否则此列表为空。您可以**接受**或**拒绝**该请求。如果请求被拒绝,则用户无法访问您的模型,也无法再次请求访问。
- **已接受**:拥有您模型访问权限的完整用户列表。您可以随时**拒绝**任何用户的访问权限,无论批准模式是手动还是自动。您也可以**取消**批准,这将把用户移到*待处理*列表。
- **已拒绝**:您手动拒绝的用户列表。这些用户无法访问您的模型。如果他们进入您的模型仓库,他们将看到一条消息:*您访问此仓库的请求已被仓库作者拒绝*。


通过 API
您可以通过 API 自动化批准访问请求。您必须传递一个具有门控仓库**写入**权限的`token`。要生成令牌,请转到您的用户设置。
方法 | URI | 描述 | 标头 | 有效负载 |
---|---|---|---|---|
GET | /api/models/{repo_id}/user-access-request/pending | 检索待处理请求列表。 | {"authorization": "Bearer $token"} | |
GET | /api/models/{repo_id}/user-access-request/accepted | 检索已接受请求列表。 | {"authorization": "Bearer $token"} | |
GET | /api/models/{repo_id}/user-access-request/rejected | 检索已拒绝请求列表。 | {"authorization": "Bearer $token"} | |
POST | /api/models/{repo_id}/user-access-request/handle | 将给定访问请求的状态更改为`status`。 | {"authorization": "Bearer $token"} | {"status": "accepted"/"rejected"/"pending", "user": "username", "rejectionReason": "将向用户显示的可选拒绝理由(最多200个字符)。"} |
POST | /api/models/{repo_id}/user-access-request/grant | 允许特定用户访问您的仓库。 | {"authorization": "Bearer $token"} | {"user": "username"} |
上述 HTTP 端点的基本 URL 是 `https://huggingface.co`。
**新功能!** 这些端点现已在我们的 Python 客户端 `huggingface_hub` 中正式支持。使用 `list_pending_access_requests`、`list_accepted_access_requests` 和 `list_rejected_access_requests` 列出您的模型的访问请求。您还可以使用 `accept_access_request`、`cancel_access_request` 和 `reject_access_request` 接受、取消和拒绝访问请求。最后,您可以使用 `grant_access` 授予用户访问权限。
下载访问报告
您可以使用**下载用户访问报告**按钮下载门控模型的所有访问请求报告。单击该按钮可下载一个 JSON 文件,其中包含用户列表。每个条目包含:
- **用户**:用户 ID。示例:*julien-c*。
- **全名**:Hub 上的用户名称。示例:*Julien Chaumond*。
- **状态**:请求的状态。可以是`"pending"`、`"accepted"`或`"rejected"`。
- **电子邮件**:用户的电子邮件地址。
- **时间**:用户最初提出请求的日期时间。
自定义请求信息
默认情况下,用户访问您的门控模型时,系统会要求他们通过单击**同意并发送请求以访问仓库**按钮来共享其联系信息(电子邮件和用户名)。


如果您想收集更多用户信息,可以配置其他字段。此信息将可在**设置**选项卡中访问。为此,请向您的模型卡元数据添加一个 `extra_gated_fields` 属性,其中包含一个键/值对列表。*键*是字段的名称,*值*是其类型或包含 `type` 字段的对象。字段类型列表如下:
- `text`:单行文本字段。
- `checkbox`:复选框字段。
- `date_picker`:日期选择器字段。
- `country`:国家/地区下拉列表。国家/地区列表基于ISO 3166-1 alpha-2 标准。
- `select`:带有选项列表的下拉菜单。选项列表在 `options` 字段中定义。示例:`options: ["option 1", "option 2", {label: "option3", value: "opt3"}]`。
最后,您还可以使用 `extra_gated_prompt` 附加字段来个性化向用户显示的消息。
这是一个自定义请求表单的示例,其中要求用户提供公司名称和国家/地区,并确认该模型仅供非商业用途。
---
extra_gated_prompt: "You agree to not use the model to conduct experiments that cause harm to human subjects."
extra_gated_fields:
Company: text
Country: country
Specific date: date_picker
I want to use this model for:
type: select
options:
- Research
- Education
- label: Other
value: other
I agree to use this model for non-commercial use ONLY: checkbox
---
在某些情况下,您可能还希望修改门控标题、描述和按钮中的默认文本。对于这些用例,您可以像这样修改 `extra_gated_heading`、`extra_gated_description` 和 `extra_gated_button_content`:
---
extra_gated_heading: "Acknowledge license to accept the repository"
extra_gated_description: "Our team may take 2-3 days to process your request"
extra_gated_button_content: "Acknowledge license"
---
程序化管理访问请求的示例用例
以下是一些程序化管理门控仓库访问请求的有趣用例,这些用例是社区中自然出现的。提醒一下,模型仓库需要设置为手动批准,否则用户将自动获得访问权限。
程序化管理的可能用例包括:
- 如果您有高级用户请求筛选要求(例如高级合规要求),或者您希望在 Hub 之外处理用户请求。
- 例如 Meta 的 Llama 2 初次发布,用户必须在 Meta 网站上请求访问权限。
- 您可以在您的访问流程中向用户询问他们的 HF 用户名,然后使用脚本根据您的条件程序化地接受 Hub 上的用户请求。
- 如果您希望根据完成支付流程来限制模型访问(请注意,实际的支付流程发生在 Hub 之外)。
- 这是一个来自 TrelisResearch 的示例仓库,它使用了此用例。
- @RonanMcGovern 发布了一个关于流程的视频和如何实现它的技巧。
作为组织管理门控模型(企业中心)
企业中心订阅者可以创建一个门控组集合,一次性授予(或拒绝)对集合中所有模型和数据集的访问权限。
有关门控组集合的更多信息,请参阅我们的专用文档。
作为用户访问门控模型
作为用户,如果您想使用门控模型,则需要请求访问权限。这意味着您必须登录 Hugging Face 用户帐户。
请求访问只能通过您的浏览器完成。转到 Hub 上的模型,系统将提示您共享您的信息


点击**同意**,即表示您同意与模型作者分享您的用户名和电子邮件地址。在某些情况下,可能会请求额外字段。为了帮助模型作者决定是否授予您访问权限,请尽量完整填写表格。
访问请求发送后,有两种可能性。如果审批机制是自动的,您将立即获得模型文件访问权限。否则,请求必须由作者手动批准,这可能需要更多时间。
模型作者对模型访问具有完全控制权。特别是,无论审批机制如何,或者您的请求是否已获批准,他们都可以随时决定阻止您访问模型,恕不另行通知。
下载文件
要从门控模型下载文件,您需要进行身份验证。在浏览器中,只要您已登录帐户,这将是自动的。如果您正在使用脚本,则需要提供用户令牌。在 Hugging Face Python 生态系统(`transformers`、`diffusers`、`datasets` 等)中,您可以使用`huggingface_hub`库并在您的终端中运行来登录您的机器
hf auth login
或者,您可以在笔记本或脚本中使用 `login()` 程序化登录
>>> from huggingface_hub import login
>>> login()
您还可以将 `token` 参数直接从脚本提供给库中的大多数加载方法(`from_pretrained`、`hf_hub_download`、`load_dataset` 等)。
有关如何登录的更多详细信息,请查看登录指南。
< > 在 GitHub 上更新