Gated 데이터셋

Gated 데이터셋 (Gated datasets)

데이터셋 사용 방식을 더 제어하기 위해 Hub는 데이터셋 작성자가 데이터셋에 접근 요청(access requests) 을 켤 수 있게 합니다. 활성화되면 사용자는 데이터셋 파일에 접근하려면 작성자와 연락처 정보(사용자명과 이메일)를 공유하는 데 동의해야 해요.

출처: 문서

본문

데이터셋이 어떻게 사용되는지 더 제어하려면 Hub가 데이터셋 작성자가 데이터셋에 대해 접근 요청을 활성화할 수 있게 합니다. 활성화되면 사용자는 데이터셋 파일에 접근하려면 데이터셋 작성자에게 연락처 정보(사용자명과 이메일 주소)를 공유하는 데 동의해야 합니다. 데이터셋 작성자는 이 요청에 추가 필드를 구성할 수 있어요. 접근 요청이 활성화된 데이터셋을 gated dataset이라고 합니다. 접근 요청은 전체 조직이 아니라 항상 개별 사용자에게 부여됩니다. gated 데이터셋의 일반적인 사용 사례는 광범위한 공개 전에 초기 연구 데이터셋에 대한 접근을 제공하는 것입니다.

데이터셋 작성자로서 gated 데이터셋 관리하기 (Manage gated datasets as a dataset author)

접근 요청을 활성화하려면 데이터셋 설정 페이지로 가세요. 기본적으로 데이터셋은 gated가 아닙니다. 오른쪽 위의 Enable Access request를 클릭하세요.

기본적으로 데이터셋에 대한 접근은 요청 시 사용자에게 자동으로 부여됩니다. 이를 자동 승인(automatic approval) 이라고 합니다. 이 모드에서는 어떤 사용자든 개인 정보를 공유하기만 하면 데이터셋에 접근할 수 있어요.

데이터셋에 접근할 사용자를 수동으로 승인하려면 수동 승인(manual approval) 으로 설정해야 합니다. 이 경우 더 많은 옵션이 표시됩니다:

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

접근 요청 검토하기 (Review access requests)

접근 요청이 활성화되면 승인 모드가 수동이든 자동이든 데이터셋에 접근할 수 있는 사람을 완전히 제어할 수 있어요. 요청은 UI 또는 API로 검토·관리할 수 있습니다.

UI에서 (From the UI)

설정 페이지에서 Review access requests 버튼을 클릭해 gated 데이터셋에 접근 권한이 있는 사람을 검토할 수 있습니다. 그러면 3개의 사용자 목록이 있는 모달이 열립니다:

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

API로 (Via the API)

API로 접근 요청 승인을 자동화할 수 있어요. gated 리포지토리에 write 접근이 있는 token을 전달해야 합니다. 토큰 생성은 사용자 설정에서 할 수 있습니다.

Method	URI	Description	Headers	Payload
`GET`	`/api/datasets/{repo_id}/user-access-request/pending`	대기 중인 요청 목록 조회	`{"authorization": "Bearer $token"}`
`GET`	`/api/datasets/{repo_id}/user-access-request/accepted`	수락된 요청 목록 조회	`{"authorization": "Bearer $token"}`
`GET`	`/api/datasets/{repo_id}/user-access-request/rejected`	거부된 요청 목록 조회	`{"authorization": "Bearer $token"}`
`GET`	`/api/datasets/{repo_id}/user-access-request/reset`	초기화된 요청 목록 조회	`{"authorization": "Bearer $token"}`
`POST`	`/api/datasets/{repo_id}/user-access-request/handle`	주어진 접근 요청의 상태를 `status`로 변경	`{"authorization": "Bearer $token"}`	`{"status": "accepted"/"rejected"/"pending"/"reset", "user": "username", "rejectionReason": "사용자에게 보일 선택적 거부 사유(최대 200자)", "resetReason": "사용자에게 보내는 이메일에 포함될 선택적 초기화 사유(최대 200자)"}}`
`POST`	`/api/datasets/{repo_id}/user-access-request/grant`	특정 사용자의 리포지토리 접근 허용	`{"authorization": "Bearer $token"}`	`{"user": "username"}`

위 HTTP 엔드포인트의 base URL은 https://huggingface.co입니다.

요청을 reset으로 설정하면 이전 결정을 취소하고 사용자가 처음부터 다시 시작하도록 합니다: 데이터셋 접근을 잃고, 요청이 초기화되었다는 이메일(선택적 resetReason 포함)을 받고, 다음에 데이터셋 페이지를 방문할 때 gating 약관에 동의하고 새 요청을 제출하라는 프롬프트가 표시됩니다. 이는 기존 요청을 그대로 유지하고 검토 큐에 다시 넣는 pending, 그리고 사용자가 다시 요청하지 못하게 막는 rejected와 다릅니다.

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

접근 보고서 다운로드 (Download access report)

download user access report 버튼으로 gated 데이터셋의 모든 접근 요청 보고서를 다운로드할 수 있어요. 클릭하면 사용자 목록이 담긴 json 파일을 다운로드합니다. 각 항목에 대해:

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

요청 정보 커스터마이즈 (Customize requested information)

기본적으로 gated 데이터셋에 방문한 사용자는 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 dataset 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 dataset for:
    type: select
    options: 
      - Research
      - Education
      - label: Other
        value: other
  I agree to use this dataset for non-commercial use ONLY: checkbox
---

경우에 따라 gate 제목, 설명, 버튼의 기본 텍스트를 수정하고 싶을 수도 있어요. 이 경우 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"
---

조직 멤버에 대한 접근 게이트 (Gate access for organization members)

조직 아래에 호스팅된 gated 데이터셋의 경우 조직의 자체 멤버도 접근 요청을 제출하도록 요구할 수 있어요. 데이터셋 설정 페이지의 gating 옵션 아래에서 Also gate access for members of {org} 를 활성화하세요.

이 옵션을 켜면 조직 멤버도 다른 사용자처럼 데이터셋 접근을 요청해야 합니다. 다음 역할은 요청을 우회하고 직접 접근을 유지합니다:

조직 admin
리포지토리를 만든 사용자
데이터셋이 Resource Group에 속한 경우 Resource Group admin

다른 모든 멤버는 접근 요청 흐름을 거쳐야 합니다. 여기에는 read, contributor, write 조직 역할을 가진 멤버와 admin 역할이 없는 Resource Group 멤버가 포함됩니다.

조직으로서 gated 데이터셋 관리하기 (Manage gated datasets as an organization, Team & Enterprise)

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

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

사용자로서 gated 데이터셋 접근하기 (Access gated datasets as a user)

사용자로서 gated 데이터셋을 사용하려면 접근을 요청해야 합니다. 즉 Hugging Face 사용자 계정에 로그인해야 합니다.

접근 요청은 브라우저에서만 할 수 있어요. Hub의 데이터셋으로 가면 정보 공유를 요청받습니다:

Agree를 클릭하면 사용자명과 이메일 주소를 데이터셋 작성자와 공유하는 데 동의하게 됩니다. 경우에 따라 추가 필드가 요청될 수 있어요. 작성자가 접근을 부여할지 결정하는 데 도움이 되도록 양식을 최대한 완전하게 채워 보세요.

접근 요청을 보내고 나면 두 가지 가능성: 승인 메커니즘이 자동이면 즉시 데이터셋 파일에 접근할 수 있어요. 그렇지 않으면 작성자가 수동으로 승인해야 하며 시간이 더 걸릴 수 있습니다.

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

파일 다운로드 (Download files)

gated 데이터셋에서 파일을 다운로드하려면 인증이 필요합니다. 브라우저에서는 계정으로 로그인하기만 하면 자동입니다. 스크립트를 사용한다면 user token을 제공해야 합니다. 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 파라미터를 제공할 수도 있어요.

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

EU 사용자 접근 제한 (Restricting Access for EU Users)

gated 데이터셋에 대해 유럽연합(EU) 국가의 사용자를 특별히 제한하는 추가 접근 제어 계층을 추가할 수 있어요. 데이터셋의 라이선스나 이용 약관이 EU 내 배포를 금지하는 경우 유용합니다.

이를 활성화하려면 데이터셋 카드 메타데이터에 extra_gated_eu_disallowed: true 속성을 추가하세요.

중요: 이 기능은 데이터셋이 이미 gated일 때만 활성화됩니다. gated: false이거나 속성이 설정되지 않았다면 이 제한은 적용되지 않아요.

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

시스템은 사용자의 IP 주소를 기반으로 위치를 식별합니다.

더 알아보기 (Learn more)

gated 데이터셋은 자동/수동 승인 모드로 접근 요청을 관리하고, extra_gated_fields로 요청 양식을 커스터마이즈할 수 있어요. 작성자는 UI 또는 /api/datasets/{repo_id}/user-access-request/* API(및 huggingface_hub 헬퍼)로 승인을 관리하고, 사용자는 로그인 후 요청을 제출하면 됩니다. 조직(Team & Enterprise)은 Gating Group Collection으로 일괄 제어할 수 있어요.