게이티드(Gated) 모델

모델 사용 방식을 더 통제하기 위해 Hub는 모델 작성자가 모델에 접근 요청을 켤 수 있게 해요. 켜면 모델 파일에 접근하려면 사용자가 자신의 연락처 정보(사용자 이름과 이메일 주소)를 모델 작성자와 공유하는 데 동의해야 해요. 모델 작성자는 이 요청을 추가 필드로 구성할 수 있어요. 접근 요청이 켜진 모델을 게이티드 모델이라고 해요. 접근 요청은 항상 조직 전체가 아니라 개별 사용자에게 부여돼요. 게이티드 모델의 일반적인 사용 사례는 광범위한 릴리스 전에 초기 연구 모델에 접근을 제공하는 거예요.

출처: 문서

본문

모델 작성자로서 게이티드 모델 관리하기

접근 요청을 켜려면 모델 설정 페이지로 가세요. 기본적으로 모델은 게이티드가 아니에요. 오른쪽 위의 Enable Access request를 클릭하세요.

기본적으로 요청 시 모델 접근이 사용자에게 자동으로 부여돼요. 이를 자동 승인(automatic approval) 이라고 해요. 이 모드에서는 어떤 사용자든 개인 정보를 공유하기만 하면 모델에 접근할 수 있어요.

어떤 사용자가 모델에 접근할 수 있는지 수동으로 승인하려면 수동 승인(manual approval) 으로 설정해야 해요. 이 경우 더 많은 옵션이 보여요:

Add access - 사용자를 검색해 요청하지 않았어도 접근을 부여할 수 있어요.
Notification frequency - 새 사용자가 접근을 요청할 때 언제 알림받을지 구성해요. 하루 한 번 또는 실시간으로 설정할 수 있어요. 기본적으로 기본 이메일 주소로 이메일이 발송돼요. 조직 아래 호스팅되는 모델은 기본적으로 조직의 첫 5명 관리자에게 발송돼요. 두 경우(사용자·조직) 모두 Notifications email 필드에 다른 이메일 주소를 설정할 수 있어요.

접근 요청 검토

접근 요청이 켜지면 승인 모드가 수동이든 자동이든 누가 모델에 접근할 수 있는지 완전히 제어할 수 있어요. UI나 API에서 요청을 검토·관리할 수 있어요.

UI에서

게이티드 모델 설정 페이지의 Review access requests 버튼을 클릭해 접근 권한이 있는 사람을 검토할 수 있어요. 3개 사용자 목록이 있는 모달이 열려요:

pending: 모델 접근 승인을 기다리는 사용자 목록. manual approval을 선택하지 않으면 이 목록은 비어 있어요. 요청을 Accept하거나 Reject할 수 있어요. 거부되면 사용자는 모델에 접근할 수 없고 다시 요청할 수도 없어요.
accepted: 모델에 접근 권한이 있는 완전한 목록. 승인 모드가 수동이든 자동이든 언제든 어떤 사용자에게도 Reject 접근을 선택할 수 있어요. Cancel 승인할 수도 있는데, 그러면 사용자가 pending 목록으로 이동해요.
rejected: 수동으로 거부한 사용자 목록. 이 사용자들은 모델에 접근할 수 없어요. 모델 저장소로 가면 Your request to access this repo has been rejected by the repo's authors 메시지를 볼 거예요.

API로

API로 접근 요청 승인을 자동화할 수 있어요. 게이티드 저장소에 write 접근이 있는 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"}`
`GET`	`/api/models/{repo_id}/user-access-request/reset`	리셋된 요청 목록 가져오기.	`{"authorization": "Bearer $token"}`
`POST`	`/api/models/{repo_id}/user-access-request/handle`	주어진 접근 요청의 상태를 `status`로 변경.	`{"authorization": "Bearer $token"}`	`{"status": "accepted"/"rejected"/"pending"/"reset", "user": "username", "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`	특정 사용자가 저장소에 접근하게 허용.	`{"authorization": "Bearer $token"}`	`{"user": "username"}`

위 HTTP 엔드포인트의 기본 URL은 https://huggingface.co예요.

요청을 reset으로 설정하면 이전 결정을 취소하고 사용자가 처음부터 다시 시작하도록 요구해요: 모델 접근을 잃고, 요청이 리셋됐다는 이메일(선택 resetReason 포함)을 받고, 다음에 모델 페이지를 방문할 때 게이팅 약관에 동의하고 새 요청을 제출하라는 안내를 받아요. 이는 기존 요청을 그대로 두고 검토 큐에 다시 넣는 pending, 그리고 사용자가 다시 요청하지 못하게 막는 rejected와 다르다.

NEW! 이 엔드포인트들은 이제 파이썬 클라이언트 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로 사용자에게 접근을 부여할 수 있어요.

접근 리포트 다운로드

download user access report 버튼으로 게이티드 모델의 모든 접근 요청 리포트를 다운로드할 수 있어요. 클릭하면 사용자 목록이 담긴 json 파일이 다운로드돼요. 각 항목마다:

user: 사용자 id. 예: julien-c.
fullname: Hub의 사용자 이름. 예: Julien Chaumond.
status: 요청 상태. "pending", "accepted", "rejected", "reset" 중 하나.
email: 사용자 이메일.
time: 사용자가 처음 요청한 시각.
reviewedAt: 요청이 승인·거부된 시각. pending 요청에는 설정되지 않음.

요청 정보 커스터마이즈

기본적으로 게이티드 모델에 도착한 사용자는 Agree and send request to access repo 버튼을 클릭해 연락처 정보(이메일과 사용자 이름)를 공유하라는 안내를 받아요.

더 많은 사용자 정보를 수집하려면 추가 필드를 구성할 수 있어요. 이 정보는 Settings 탭에서 접근할 수 있어요. 모델 카드 메타데이터에 키/값 쌍 목록을 담은 extra_gated_fields 속성을 추가하면 돼요. key는 필드 이름이고 value는 그 타입 또는 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이 흐름과 구현 팁에 관한 영상을 올렸어요.

조직 멤버 접근 게이팅

조직 아래 호스팅되는 게이티드 모델의 경우 조직 자체 멤버도 접근 요청을 제출하도록 요구할 수 있어요. 모델 설정 페이지의 게이팅 옵션 아래에서 Also gate access for members of {org} 를 켜면 돼요.

이 옵션을 켜면 조직 멤버도 다른 사용자처럼 모델 접근을 요청해야 해요. 다음 역할은 요청을 건너뛰고 직접 접근을 유지해요:

조직 관리자
저장소를 만든 사용자
모델이 Resource Group에 속할 때 Resource Group 관리자

다른 모든 멤버는 접근 요청 흐름을 거쳐야 해요. 여기에는 read, contributor, write 조직 역할의 멤버와 admin 역할이 아닌 Resource Group 멤버가 포함돼요.

조직으로서 게이티드 모델 관리하기 (Team & Enterprise)

Team & Enterprise 구독자는 Gating Group Collection을 만들어 컬렉션의 모든 모델과 데이터셋에 대한 접근을 한 번에 부여(또는 거부)할 수 있어요.

Gating Group Collections에 대한 자세한 내용은 전용 문서에서 확인할 수 있어요.

사용자로서 게이티드 모델에 접근하기

사용자로서 게이티드 모델을 사용하려면 접근을 요청해야 해요. 즉 Hugging Face 사용자 계정에 로그인되어 있어야 해요.

접근 요청은 브라우저에서만 할 수 있어요. Hub의 모델로 가면 정보를 공유하라는 안내가 나와요.

Agree를 클릭하면 사용자 이름과 이메일 주소를 모델 작성자와 공유하는 데 동의하는 거예요. 경우에 따라 추가 필드가 요청될 수 있어요. 작성자가 접근을 부여할지 결정하는 데 도움이 되도록 폼을 최대한 완전하게 채우세요.

접근 요청이 전송되면 두 가지 가능성이 있어요. 승인 메커니즘이 자동이면 즉시 모델 파일에 접근할 수 있어요. 그렇지 않으면 작성자가 수동으로 승인해야 하므로 더 걸릴 수 있어요.

[!WARNING] 모델 작성자는 모델 접근을 완전히 통제해요. 특히 승인 메커니즘이나 요청이 이미 승인되었는지와 무관하게, 언제든 사전 통지 없이 모델 접근을 차단할 수 있어요.

파일 다운로드

게이티드 모델에서 파일을 다운로드하려면 인증이 필요해요. 브라우저에서는 계정으로 로그인되어 있으면 자동이에요. 스크립트를 쓴다면 사용자 토큰을 제공해야 해요. Hugging Face Python 생태계(transformers, diffusers, datasets 등)에서는 huggingface_hub 라이브러리로 터미널에서 로그인할 수 있어요:

hf auth login

또는 노트북이나 스크립트에서 login()으로 프로그래밍 방식으로 로그인할 수 있어요:

>>> from huggingface_hub import login
>>> login()

대부분 로딩 메서드(from_pretrained, hf_hub_download, load_dataset 등)에 token 파라미터를 직접 제공할 수도 있어요.

로그인 방법에 대한 자세한 내용은 로그인 가이드를 참고하세요.

EU 사용자 접근 제한

게이티드 모델의 경우 유럽 연합 국가 사용자를 특별히 제한하는 추가 접근 제어 계층을 추가할 수 있어요. 모델의 라이선스나 이용 약관이 EU 배포를 금지할 때 유용해요.

이를 켜려면 모델 카드 메타데이터에 extra_gated_eu_disallowed: true 속성을 추가하세요.

중요: 이 기능은 모델이 이미 게이티드일 때만 활성화돼요. gated: false이거나 속성이 설정되지 않으면 이 제한은 적용되지 않아요.

---
license: mit
gated: true
extra_gated_eu_disallowed: true
---

시스템은 사용자 IP 주소로 사용자 위치를 식별해요.

더 알아보기 (Learn more)

모델 카드에서 게이팅 메타데이터 구성을 익혀 보세요.
접근 토큰으로 게이티드 모델 파일을 인증해 다운로드해 보세요.