# Gated 模型

为了更精细地控制模型的使用方式，Hub 允许模型作者为其模型启用**访问请求**。启用后，用户必须提交访问请求才能获取模型文件，该请求会将用户的 Hugging Face 信息（用户名和电子邮件地址）共享给模型作者，除非作者选择放弃收集这些信息。模型作者还可以添加自定义字段。启用了访问请求的模型被称为**门控模型**。访问请求始终授予个人用户，而非整个组织。门控模型的一个常见用例是在正式发布前，为早期研究模型提供访问权限。

## 以模型作者身份管理受控模型

 
 

要启用访问请求，请前往模型设置页面。默认情况下，模型未设置访问限制。点击右上角的 **启用访问请求**。

    
    

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

    
    

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

    
    

### 审查访问请求

启用访问请求后，无论审批模式是手动还是自动，您都可以完全控制谁可以访问您的模型。您可以通过 UI 或 API 来审核和管理请求。

#### 从 UI

您可以在模型的设置页面中，通过点击 **Review access requests** 按钮来查看谁有权访问您的受限模型。这将打开一个包含三个用户列表的模态框：
- **pending**：等待批准以访问您模型的用户列表。除非您选择了**manual approval**，否则此列表为空。您可以选择**Accept**或**Reject**该请求。如果请求被拒绝，该用户将无法访问您的模型，也无法再次申请访问权限。
- **accepted**：拥有您模型访问权限的完整用户列表。无论审批模式是手动还是自动，您都可以随时为任何用户选择 **Reject** 访问权限。您还可以 **Cancel** 审批，这将把该用户移至 *pending* 列表。
- **rejected**：您手动拒绝的用户列表。这些用户无法访问您的模型。如果他们访问您的模型仓库，将会看到一条消息：*您对访问此仓库的请求已被仓库作者拒绝*。

    
    

#### 通过 API

您可以使用 API 自动批准访问请求。您必须传递一个具有对受限制仓库`write`访问权限的`token`。要生成 token，请前往[您的用户设置](https://huggingface.co/settings/tokens)。

| 方法 | URI | 描述 | 请求头 | 请求体
| ------ | --- | ----------- | -------  | -------  |
| `GET` | [`/api/models/{repo_id}/user-access-request/{status}`](https://huggingface.co/spaces/huggingface/openapi#tag/models/GET/api/models/{namespace}/{repo}/user-access-request/{status}) | 列出具有指定 `status` 的请求：`pending`、`accepted`、`rejected` 或 `reset`。每个请求都有一个 `requestId`，如果收集了用户名，则还有一个 `user`。 | `{"authorization": "Bearer $token"}` | |
| `POST` | [`/api/models/{repo_id}/user-access-request/handle`](https://huggingface.co/spaces/huggingface/openapi#tag/models/POST/api/models/{namespace}/{repo}/user-access-request/handle) | 将指定访问请求的状态更改为 `status`。 | `{"authorization": "Bearer $token"}` | `{"status": "accepted"/"rejected"/"pending"/"reset", "user": "username" (or "requestId": "request id"), "rejectionReason": "Optional rejection reason that will be visible to the user (max 200 characters).", "resetReason": "Optional reset reason that will be included in the email sent to the user (max 200 characters)."}` |
| `POST` | [`/api/models/{repo_id}/user-access-request/grant`](https://huggingface.co/spaces/huggingface/openapi#tag/models/POST/api/models/{namespace}/{repo}/user-access-request/grant) | 允许特定用户访问您的仓库。 | `{"authorization":  "Bearer $token"}` | `{"user": "username"} ` |

上述 HTTP 端点的基础 URL 为 `https://huggingface.co`。

将请求设置为 `reset` 会撤销先前的决定并要求用户重新开始：他们将失去对模型的访问权限，收到一封通知其请求已被重置的电子邮件（其中包含可选的 `resetReason`），并在下次访问模型页面时被提示同意门控条款并提交新请求。这与 `pending` 不同，后者保持现有请求不变，只是将其重新放回审核队列；也与 `rejected` 不同，后者会阻止用户再次申请访问权限。

**新功能！**这些端点现已在我们的 Python 客户端 `huggingface_hub` 中正式获得支持。您可以使用 [`list_pending_access_requests`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.list_pending_access_requests)、[`list_accepted_access_requests`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.list_accepted_access_requests) 和 [`list_rejected_access_requests`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.list_rejected_access_requests) 来列出针对您模型的访问请求。此外，您还可以使用 [`accept_access_request`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.accept_access_request)、[`cancel_access_request`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.cancel_access_request) 和 [`reject_access_request`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.reject_access_request) 来接受、取消或拒绝访问请求。最后，您可以使用 [`grant_access`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.grant_access) 授予用户访问权限。

### 下载访问报告

您可以使用 **download user access report** 按钮下载受限模型的所有访问请求报告。点击该按钮即可下载一个包含用户列表的 json 文件。每个条目包含：
- **requestId**：请求的 ID。
- **user**：用户 ID。示例：*julien-c*。
- **fullname**：用户在 Hub 上的名称。示例：*Julien Chaumond*。
- **status**：请求的状态。可以是 `"pending"`、`"accepted"`、`"rejected"` 或 `"reset"`。
- **email**：用户的电子邮件地址。
- **time**：用户最初发出请求的时间。
- **reviewedAt**：请求被接受或拒绝的时间。对于待处理请求，此字段未设置。

> [!TIP]
> `user`、`fullname` 和 `email` 仅在发起请求时选择 [收集这些信息](#choose-which-profile-data-hugging-face-shares-with-you) 的情况下才会存在。所有请求始终可以通过其 `requestId` 进行识别。

### 选择 Hugging Face 与您共享哪些个人资料数据

默认情况下，Hugging Face 会将请求者的用户名和主要电子邮件地址共享给您。您有责任处理任何个人身份信息（PII），并根据适用法律披露您的处理方式（例如，通过链接到您自己的隐私政策）。您可以在模型设置页面的访问控制选项中更改此设置：

- **收集用户名**：取消勾选后，你将不会收到请求者的 Hugging Face 用户名、全名和头像。请求将以请求 ID 的形式列出，并且可以像其他请求一样被接受或拒绝。
- **收集电子邮件**：收集请求者的 Hugging Face 个人资料电子邮件。需要 **收集用户名**。

您仍然会收到[自定义表单字段](#customize-requested-information)的答案，因此您可以在其中索取所需的任何联系方式。这些设置仅适用于新请求：现有请求将保留其创建时生效的设置。

对于 [Gating Group Collection](./enterprise-gating-group-collections) 中的模型，这些选项将在集合上进行配置。

 

### 自定义请求的信息

默认情况下，访问您的受保护模型的用户在点击 **同意并发送访问仓库请求** 按钮时，会被要求共享其 Hugging Face 信息（邮箱和用户名，除非您已 [禁用其收集](#choose-which-profile-data-hugging-face-shares-with-you)）。

    
    

如果您希望收集更多用户信息，可以配置额外的字段。此信息可在 **设置** 选项卡中访问。为此，请在您的 [模型卡片元数据](./model-cards#model-card-metadata) 中添加一个 `extra_gated_fields` 属性，其中包含一个键值对列表。*键* 是字段的名称，*值* 是其类型或一个包含 `type` 字段的对象。字段类型列表如下：

- `text`：单行文本字段。
- `checkbox`：复选框字段。
- `date_picker`：日期选择器字段。
- `country`：国家下拉菜单。国家列表基于 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 标准。
- `select`：一个包含选项列表的下拉菜单。选项列表在 `options` 字段中定义。示例：`options: ["option 1", "option 2", {label: "option3", value: "opt3"}]`。

最后，你还可以使用 `extra_gated_prompt` 额外字段来个性化显示给用户的消息。

以下是一个自定义请求表单的示例，其中要求用户提供其公司名称和所在国家，并确认该模型仅限非商业用途。

```yaml
---
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`：

```yaml
---
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](https://huggingface.co/meta-llama/Llama-2-7b-chat-hf) 初始发布，当时用户需要在 Meta 网站上申请访问权限。
    - 您可以在访问流程中要求用户提供其 HF 用户名，然后使用脚本根据您设定的条件在 Hub 上以编程方式接受用户请求。
- 如果您想根据是否完成支付流程（请注意，实际的支付流程发生在 Hub 之外）来控制对模型的访问权限。
    - 这是来自 TrelisResearch 的一个[示例仓库](https://huggingface.co/Trelis/openchat_3.5-function-calling-v3)，它使用了该用例。
   - [@RonanMcGovern](https://huggingface.co/RonanMcGovern) 发布了一段[关于该流程的视频](https://www.youtube.com/watch?v=2OT2SI5auQU)，并分享了实施技巧。

### 为组织成员设置访问权限

对于托管在组织下的门控模型，您还可以要求该组织的**成员**提交访问请求。在模型设置页面中，在门控选项下，启用**同时为 `{org}` 的成员门控访问**。

启用此选项后，组织成员必须像其他用户一样申请模型访问权限。以下角色可绕过申请流程并保留直接访问权限：

- 组织管理员
- 创建该仓库的用户
- 当模型属于资源组时，[资源组](./security-resource-groups)管理员

所有其他成员都必须通过访问请求流程。这包括具有 read、contributor 或 write 组织角色的成员，以及不具有 admin 角色的资源组成员。

## 以组织身份管理受控模型（团队版和企业版）

[Team & Enterprise](https://huggingface.co/docs/hub/en/enterprise) 订阅用户可以创建一个 Gating Group Collection，以一次性授予（或拒绝）对集合中所有模型和数据集的访问权限。

有关 Gating Group Collections 的更多信息，请参阅[我们的专用文档](https://huggingface.co/docs/hub/en/enterprise-gating-group-collections)。

## 以用户身份访问受限制模型

作为用户，如果您想使用一个受控模型，您需要申请访问权限。这意味着您必须已登录 Hugging Face 用户账户。

申请访问权限只能通过浏览器完成。前往 Hub 上的该模型，系统会提示您共享您的信息：

    
    

点击 **同意** 即表示您同意将您在请求表单中填写的信息（如适用）与模型作者共享，同时，如果作者选择收集，您的 Hugging Face 用户名和电子邮件地址也将被共享。为了帮助模型作者决定是否授予您访问权限，请尽可能完整地填写表单中的各项内容。

访问请求发送后，会出现两种情况。如果审批机制是自动的，您将立即获得模型文件的访问权限。否则，请求需要由作者手动批准，这可能需要更长的时间。

> [!WARNING]
> 模型作者对模型访问权限拥有完全的控制权。具体而言，无论采用何种审批机制，也无论您的请求是否已获批准，他们都可以随时在不提前通知的情况下阻止您访问该模型。

### 下载文件

要从受限制模型下载文件，需要进行身份验证。在浏览器中，只要您已登录账户，此过程会自动完成。如果您使用脚本，则需要提供一个[用户令牌](./security-tokens)。在 Hugging Face Python 生态系统（`transformers`、`diffusers`、`datasets` 等）中，您可以使用 [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/index) 库登录您的机器，并在终端中运行：

```bash
hf auth login
```

或者，您可以在笔记本或脚本中通过编程方式使用 `login()` 进行登录：

```python
>>> from huggingface_hub import login
>>> login()
```

您还可以在大多数库的加载方法（`from_pretrained`、`hf_hub_download`、`load_dataset` 等）中直接提供 `token` 参数，从您的脚本中直接调用。

有关登录的更多详细信息，请参阅[登录指南](https://huggingface.co/docs/huggingface_hub/quick-start#login)。

### 限制欧盟用户的访问

对于门控模型，您可以添加一层额外的访问控制，专门限制来自欧盟国家的用户。如果您的模型许可证或条款禁止在欧盟分发，这将非常有用。

要启用此功能，请在您的模型卡元数据中添加 `extra_gated_eu_disallowed: true` 属性。

**重要：**此功能仅在你的模型已设置为受限时才会生效。如果 `gated: false` 或未设置该属性，则此限制不适用。

```yaml
---
license: mit
gated: true
extra_gated_eu_disallowed: true
---
```

系统根据用户的 IP 地址识别其位置。