# ゲート付きモデル モデルの使用方法に対する制御を強化するため、Hub ではモデル作成者がモデルに対して**アクセスリクエスト**を有効にできます。有効にすると、ユーザーはモデルファイルにアクセスするためにアクセスリクエストを提出する必要があり、モデル作成者がその収集をオプトアウトしていない限り、Hugging Face の情報（ユーザー名とメールアドレス）がモデル作成者と共有されます。モデル作成者はカスタムフィールドを追加することもできます。アクセスリクエストが有効なモデルは**ゲート付きモデル**と呼ばれます。アクセスリクエストは、組織全体ではなく、常に個人ユーザーに対して承認されます。ゲート付きモデルの一般的なユースケースは、より広範なリリース前に、初期の研究モデルへのアクセスを提供することです。 ## モデル作成者としてゲート付きモデルを管理する アクセスリクエストを有効にするには、モデルの設定ページに移動します。デフォルトでは、モデルはゲートされていません。右上隅の**Enable Access request**をクリックしてください。 デフォルトでは、モデルのアクセス要求時に、自動的にユーザーへのアクセス権限が付与されます。これは**自動承認**と呼ばれます。このモードでは、ユーザーが個人情報を共有した時点で、誰でもあなたのモデルにアクセスできます。 モデルへのアクセスを許可するユーザーを手動で承認したい場合は、**manual approval**に設定する必要があります。この場合、より多くのオプションが表示されます。 - **アクセスの追加**を使用すると、ユーザーを検索して、リクエストがなくてもアクセス権を付与できます。 - **通知頻度**では、新しいユーザーがアクセスをリクエストした際に通知を受け取るタイミングを設定できます。1日1回またはリアルタイムに設定できます。デフォルトでは、プライマリーメールアドレスにメールが送信されます。組織がホストするモデルの場合、デフォルトでは組織の最初の5人の管理者にメールが送信されます。どちらの場合（ユーザーまたは組織）でも、**通知用メールアドレス**フィールドで別のメールアドレスを設定できます。 ### アクセス要求のレビュー アクセス要求が有効になると、承認モードが手動であっても自動であっても、モデルへのアクセスを許可するかどうかを完全に管理できます。要求のレビューと管理は、UI または API を通じて行うことができます。 #### UIから **アクセス要求の確認**ボタンをクリックすることで、ゲート付きモデルの設定ページから、誰がそのモデルにアクセスできるかを確認できます。これにより、3つのユーザーリストが表示されるモーダルが開きます。 - **pending**: モデルへのアクセスを承認待ちで待機しているユーザーのリストです。このリストは、**manual approval**を選択していない限り空です。**Accept**または**Reject**でリクエストを処理できます。リクエストが拒否された場合、そのユーザーはモデルにアクセスできず、再度アクセスをリクエストすることもできません。 - **accepted**: モデルへのアクセス権を持つユーザーの完全なリストです。承認モードが手動であっても自動であっても、いつでも任意のユーザーに対してアクセスを**Reject**（拒否）できます。また、承認を**Cancel**（キャンセル）すると、そのユーザーは*pending*リストに移動します。 - **rejected**: 手動で拒否したユーザーのリストです。これらのユーザーはあなたのモデルにアクセスできません。モデルのリポジトリにアクセスすると、*このリポジトリの著者によって、このリポジトリへのアクセスリクエストが拒否されました* というメッセージが表示されます。 #### API経由 API を使用して、アクセスリクエストの承認を自動化できます。ゲート付きリポジトリへの `write` アクセス権限を持つ `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) を使用して、ユーザーにアクセス権を付与できます。 ### ダウンロードアクセスレポート ゲート付きモデルのすべてのアクセスリクエストのレポートは、**ユーザーアクセスレポートのダウンロード**ボタンからダウンロードできます。このボタンをクリックすると、ユーザーのリストを含む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)内のモデルでは、これらのオプションはコレクション側で設定されます。 ### 要求される情報のカスタマイズ By default, users landing on your gated model will be asked to share their Hugging Face information (email and username, unless you [disabled their collection](#choose-which-profile-data-hugging-face-shares-with-you)) by clicking the **Agree and send request to access repo** button. より多くのユーザー情報を収集したい場合は、追加のフィールドを設定できます。この情報は、**Settings**タブからアクセスできます。そのためには、[モデルカードのメタデータ](./model-cards#model-card-metadata)に、キー/値のペアのリストを含む`extra_gated_fields`プロパティを追加します。*key*はフィールドの名前、*value*はその型、または`type`フィールドを持つオブジェクトです。フィールドの型のリストは以下の通りです: - `text`: 1行のテキストフィールド。 - `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） [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ユーザー名およびメールアドレスを、モデルの著者と共有することに同意したことになります。モデルの著者がアクセスを許可するかどうかを判断するために、フォームの各項目をできるだけ完全に記入してください。 アクセスリクエストが送信されると、2つの可能性があります。承認メカニズムが自動の場合、すぐにモデルファイルへのアクセスが許可されます。それ以外の場合は、著者による手動の承認が必要であり、時間がかかる場合があります。 > [!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)を参照してください。 ### EUユーザーへのアクセス制限 ゲート付きモデルでは、EU（欧州連合）の国々からのユーザーを特に制限するために、追加のアクセス制御レイヤーを追加できます。これは、モデルのライセンスまたは利用規約がEUでの配布を禁止している場合に有用です。 これを有効にするには、モデルカードのメタデータに`extra_gated_eu_disallowed: true`プロパティを追加してください。 **重要:** この機能は、モデルがすでにゲート付きである場合にのみ有効になります。`gated: false` の場合、またはプロパティが設定されていない場合、この制限は適用されません。 ```yaml --- license: mit gated: true extra_gated_eu_disallowed: true --- ``` システムは、IPアドレスに基づいてユーザーの位置情報を特定します。