Hugging Face – The AI community building the future.
The Home of Machine Learning Create, discover and collaborate on ML better. We provide paid Compute and Enterprise solutions. We are building the foundation of ML tooling with the community.
huggingface.co
1. 서론
Hugging Face Hub는 다양한 머신러닝 모델, 데이터셋, 스페이스(Spaces)를 공유하고 협업할 수 있는 플랫폼입니다.
허가된(gated) 혹은 비공개(private) 모델의 경우에는 **액세스 토큰(access token)**을 발급받아야 다운로드 또는 사용이 가능하며, 토큰을 통해 인증(authentication)과 권한(authorisation)을 처리할 수 있습니다.
이 글에서는 토큰을 어떻게 발급하고, 그리고 모델을 어떻게 사용하는지 (다운로드/로드/인퍼런스) 단계별로 살펴보겠습니다.
2. 액세스 토큰 발급 방법
2.1 계정 준비
- 위 사이트에 접속하여 계정을 생성하거나 로그인합니다.
- 이메일 인증이나 프로필 설정 등이 완료되어야 토큰 발급이 가능할 수 있습니다.
2.2 토큰 생성
- 로그인 후 우측 상단 아바타(프로필 아이콘)를 클릭 → Settings(설정) 메뉴 진입.
- 좌측 메뉴에서 Access Tokens 또는 Tokens 탭을 선택합니다.
- “New token” 또는 “+ Create new token” 버튼을 클릭하여 새 토큰을 생성합니다.
- 토큰 이름(Name)을 지정하고, 권한(scope) 또는 역할(role)을 선택합니다. (예: 읽기(read)만, 읽기+쓰기(read+write) 등)
- 생성된 토큰 값을 복사해 둡니다. 생성 후 다시는 보이지 않을 수 있으므로 안전한 장소에 저장해야 합니다.
2.3 권한 및 안전 주의사항
- 읽기(read) 전용 토큰은 모델 다운로드 또는 인퍼런스만 가능하며, 쓰기(write) 권한이 있는 토큰은 업로드(push) 및 리포지토리 수정도 가능.
- 비공개 조직(organization)이나 팀 계정 사용하는 경우에는 토큰 관리, 권한 정책 등이 추가로 존재합니다 (예: 조직 관리자가 토큰 만들기/리뷰 가능) .
- 토큰을 코드나 버전관리(GitHub 등)에 노출시키면 안 됩니다. 외부 공개 저장소에 토큰이 담기면 보안 사고로 이어질 수 있습니다.
3. 토큰을 이용한 모델 사용 방법
3.1 인증(Authentication)
모델 사용 전 인증이 필요합니다. 방법은 여러 가지가 있습니다.
- 환경 변수(environment variable)로 설정: HF_TOKEN="hf_xxx…” 등
- 코드 내에서 토큰을 전달: 예) use_auth_token=… 파라미터 등
- CLI 로그인: huggingface-cli login 명령어로 토큰을 입력하는 방식.
3.2 모델 다운로드 및 로드
예를 들어, 비공개 또는 사용 허가가 필요한 모델(예: google/gemma-2-2b-it 등) 사용할 때 다음과 같은 코드를 참고할 수 있습니다.
https://huggingface.co/google/gemma-2-2b-it
google/gemma-2-2b-it · Hugging Face
This repository is publicly accessible, but you have to accept the conditions to access its files and content. To access Gemma on Hugging Face, you’re required to review and agree to Google’s usage license. To do this, please ensure you’re logged in
huggingface.co
access to this model
3.4 게이트드(Gated) 모델 접근 주의
일부 모델은 사용 전에 라이선스 동의(usage license) 또는 액세스 요청(request access) 절차가 필요합니다. 예를 들어 google/gemma-2-2b-it 모델은 사용 전에 허가 조건을 동의해야 합니다.
이 경우 토큰만으로는 부족하고, 모델 페이지에서 “Accept license” 또는 “Request access” 버튼을 눌러야 할 수 있습니다.