사용자 액세스 토큰

User Access Tokens이란 무엇인가요?

User Access Tokens는 Hugging Face 서비스에 애플리케이션 또는 노트북을 인증하는 권장 방법입니다. 설정에서 액세스 토큰을 관리할 수 있습니다.

액세스 토큰은 애플리케이션과 노트북이 다음에 표시된 역할의 범위로 지정된 특정 작업을 수행할 수 있도록 합니다:

• fine-grained: 이 역할의 토큰은 특정 모델이나 특정 조직의 모델과 같은 특정 리소스에 대한 세밀한 접근을 제공하기 위해 사용할 수 있습니다. 이 유형의 토큰은 모든 리소스에 대한 접근 권한을 공유하지 않고도 자체 토큰을 사용할 수 있으므로 프로덕션 환경에서 유용합니다.

• read: 이 역할을 가진 토큰은 읽을 수 있는 저장소에 대한 읽기 전용 액세스를 제공하는 데만 사용할 수 있습니다. 여기에는 사용자가 소유한 공개 및 비공개 저장소, 또는 사용자가 소속된 조직이 소유한 저장소가 포함됩니다. Hugging Face Hub에서 콘텐츠 읽기만 필요한 경우(예: 비공개 모델 다운로드 또는 추론 수행 시) 이 역할을 사용하세요.

• write: 이 역할을 가진 토큰은 쓰기 권한이 있는 저장소에 대한 쓰기 접근 권한을 추가로 부여합니다. 저장소에 콘텐츠를 생성하거나 푸시해야 하는 경우(예: 모델 학습 또는 모델 카드 수정 시) 이 토큰을 사용하세요.

조직의 읽기/쓰기/관리자(read/write/admin) 역할 멤버인 경우, 사용자 액세스 토큰(User Access Tokens)은 토큰 권한(read/write) 및 조직 멤버십(read/write/admin)에 따라 리소스를 읽기/쓰기할 수 있습니다.

User Access Tokens를 관리하는 방법

액세스 토큰을 생성하려면 설정으로 이동한 후 Access Tokens 탭을 클릭하세요. New token 버튼을 클릭하여 새로운 User Access Token을 생성합니다.

토큰의 역할과 이름을 선택하면 준비 완료!

Manage 버튼을 클릭하여 User Access Tokens를 삭제하고 새로고침할 수 있습니다.

User Access Tokens를 사용하는 방법

User Access Token을 사용하여 Hugging Face Hub에 액세스하는 방법은 다양하며, 이를 기반으로 훌륭한 앱을 구축하는 데 필요한 유연성을 제공합니다.

User Access Tokens은 다음과 같습니다:

• git 또는 기본 인증을 통해 Hugging Face Hub에 액세스할 때 비밀번호 대신 사용
• Inference Providers를 호출할 때 bearer token으로 전달됩니다.
• transformers나 datasets와 같은 Hugging Face Python 라이브러리에서 사용됩니다:

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

토큰이 유출되지 않도록 주의하세요! 토큰은 언제든 재발급할 수 있지만, 그 사이에는 누구나 사용자의 비공개 저장소를 읽거나 쓸 수 있으며 이는 💩입니다. 토큰이 노출된 경우 유출된 토큰 폐기를 참고하세요.

최적의 관행

각 앱 또는 용도별로 액세스 토큰을 하나씩 생성하는 것을 권장합니다. 예를 들어, 다음 용도별로 별도의 토큰을 사용할 수 있습니다:

• 로컬 머신
• Colab 노트북입니다.
• 훌륭한 사용자 정의 추론 서버입니다.

이렇게 하면 다른 사용에 영향을 주지 않고 하나의 토큰만 무효화할 수 있습니다.

프로덕션 환경에서는 세밀한 권한을 가진 토큰만 사용하는 것을 권장합니다. 유출 시 영향 범위가 줄어들며, 계정에 영향을 주지 않고 조직 내에서 공유할 수 있습니다.

예를 들어, 프로덕션 애플리케이션이 게이트된 모델에 대한 읽기 접근 권한이 필요한 경우, 조직의 구성원이 해당 모델에 대한 접근을 요청한 후, 그 모델에 대한 읽기 접근 권한이 있는 세밀한 토큰을 생성할 수 있습니다. 이 토큰은 프로덕션 애플리케이션에서 사용될 수 있으며, 이를 통해 모든 비공개 모델에 대한 접근 권한을 부여하지 않아도 됩니다.

CI/CD 파이프라인을 위한

CI/CD 워크플로(GitHub Actions, GitLab CI, CircleCI, …)에서만 액세스가 필요한 경우, CI 시크릿으로 액세스 토큰을 저장하는 것을 완전히 생략할 수 있습니다. 각 실행 시작 시 CI 제공자의 OpenID Connect(OIDC) ID 토큰을 짧은 유효기간의 Hub 토큰으로 교환하는 Trusted Publishers를 참조하세요. 이는 레포지토리 범위(모델, 데이터셋, Spaces 또는 커널을 게시하거나 읽기 전용으로 가져오기 위해) 또는 사용자 범위(액세스 권한이 있는 게이트드 레포지토리를 읽고 계정의 속도 제한을 받기 위해)로 설정할 수 있습니다.

Enterprise 조직을 위한

조직에서 각 사용자가 개별 토큰을 생성하지 않고도 멤버를 위해 토큰을 프로그래매틱으로 발급해야 하는 경우, OAuth Token Exchange를 참조하세요. 이 Enterprise 플랜 기능은 조직 멤버를 대신하여 Hugging Face 리소스에 접근해야 하는 내부 플랫폼, CI/CD 파이프라인 또는 커스텀 통합을 구축하는 데 이상적입니다.

누출된 토큰 폐기

사용자 소유의 토큰 중 하나가 유출된 경우, 설정의 Access Tokens 탭에서 해당 토큰을 삭제하거나 새로고침하세요.

다른 사람의 Hugging Face 액세스 토큰을 발견한 경우, POST /api/credentials/revoke 엔드포인트를 사용하여 해당 토큰을 무효화할 수 있습니다. 토큰을 소유한 계정 또는 조직에 대한 권한이 필요하지 않습니다.

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

credentials 배열에 여러 토큰 값을 한 번의 호출로 전달할 수 있으며, 이는 배치로 결과를 보고하는 시크릿 스캐닝 파이프라인에 유용합니다.

제출된 모든 토큰 중 기존 토큰과 일치하는 토큰은 즉시 무효화되어 모든 곳에서 작동이 중단됩니다. 이는 조직 수준 폐기와 달리 단일 조직에 대한 토큰의 접근만 차단하는 것과 다릅니다. 토큰 소유자는 이메일로 통지를 받으며, 접근을 복구하려면 새 토큰을 생성해야 합니다.

이 엔드포인트는 제출한 토큰이 존재했는지 여부와 관계없이 항상 202 Accepted로 응답하므로, 응답을 사용하여 토큰이 유효한지 확인하는 데 사용할 수 없습니다. 동일한 토큰을 다시 제출해도 해롭지 않습니다. 반복 호출은 아무 효과도 없으며 소유자에게는 한 번만 알림이 전송됩니다.

셸 히스토리나 로그에 토큰 값이 노출되지 않도록 환경 변수나 파일을 통해 전달하고, 원시 토큰을 명령줄에 직접 붙여 넣지 마세요.

토큰 관리 정책이 있는 조직의 토큰

Team 및 Enterprise 플랜의 조직은 해당 조직의 리소스에 액세스할 때 토큰의 작동 방식에 영향을 미치는 토큰 정책을 적용할 수 있습니다.

토큰이 승인(팀 및 엔터프라이즈 조직)을 필요로 하는 경우

관리자 승인이 필요한 조직에 범위가 지정된 세밀한 토큰을 생성하면, 해당 토큰은 자동으로 Pending 상태로 전환됩니다. 관리자가 승인하기 전까지는 해당 조직의 리소스에 접근할 수 없습니다. 토큰이 승인되거나 거부되면 이메일 알림을 받게 됩니다.

토큰 목록 페이지에서 상태를 확인할 수 있습니다. 대기 중인 토큰은 권한 배지 옆에 주황색 모래시계 아이콘이 표시되고, 거부되거나 폐기된 토큰은 빨간색 느낌표 아이콘이 표시됩니다. 토큰이 거부되거나 폐기된 경우 해당 토큰의 편집 페이지에도 빨간색 오류 배너가 표시됩니다.

조직의 관리자라면, 해당 조직 범위로 설정하여 생성한 fine-grained token은 자동으로 승인되며 검토 단계가 필요하지 않습니다.

토큰이 거부된 경우 (Team & Enterprise 조직)

토큰이 거부되면 이메일 알림을 받게 됩니다. 토큰은 계정에 유지되며 조직 외부의 리소스에 여전히 사용할 수 있습니다. 거부된 토큰은 나중에 관리자가 승인하여 새 토큰을 생성하지 않고도 액세스를 복원할 수 있습니다.

거부된 토큰을 조직 리소스에 사용하려고 하면 403 오류가 발생합니다.

토큰이 폐기된 경우(Enterprise 조직)

취소는 영구적입니다. 거부와 달리, 취소된 토큰은 복원할 수 없습니다. 토큰이 취소된 경우, 해당 토큰을 삭제하고 새 토큰을 생성해야 합니다. 조직에서 관리자 승인을 요구하는 경우, 새 토큰은 대기 상태로 시작됩니다.

취소된 토큰으로 조직 리소스에 액세스를 시도하면 “조직 관리자에 의해 토큰이 취소되었습니다. 더 이상 조직 리소스에 액세스할 수 없습니다. 자세한 내용은 관리자에게 문의하세요.”라는 메시지와 함께 403 오류가 반환됩니다.

취소는 해당 토큰을 취소한 조직에만 영향을 미칩니다. 토큰은 스코프가 설정된 모든 다른 리소스에 대해 정상적으로 계속 작동합니다.

조직이 세분화된 토큰만 허용하는 경우 (Team & Enterprise 조직)

조직에서 세밀한 권한을 가진 토큰을 요구하는 정책을 설정한 경우, 읽기/쓰기 토큰은 해당 조직의 리소스에 사용될 때 403 오류로 거부됩니다.