Hugging Face에서 모델을 내려받다가 막히는 이유는 대부분 토큰입니다. 게이트 모델은 토큰 없이 받을 수 없고, 토큰을 넘기지 않으면 요청 한도도 비로그인 기준으로 계산됩니다. 아래에서 토큰 종류, 발급, 429 오류, 유출 시 조치를 정리했습니다.
Hugging Face에서 모델을 내려받다가 막히는 이유는 대부분 토큰입니다. 게이트 모델은 토큰 없이 받을 수 없고, 토큰을 넘기지 않으면 요청 한도도 비로그인 기준으로 계산됩니다. 아래에서 토큰 종류, 발급, 429 오류, 유출 시 조치를 정리했습니다.
Hugging Face 토큰 종류
Hugging Face 액세스 토큰은 세 종류입니다. read 는 내가 읽을 수 있는 저장소를 읽기만 하고, write 는 쓰기 권한이 있는 저장소에 올리기까지 합니다. fine-grained 는 특정 모델이나 특정 조직의 모델처럼 범위를 좁혀 권한을 줄 수 있어, 공식 문서는 실제 서비스에는 이 종류만 쓰라고 권합니다.
Hugging Face 토큰 발급 순서
토큰은 설정 화면에서 만듭니다.
| 구분 | 내용 |
|---|---|
| 1단계 | 설정 > Access Tokens 탭 |
| 2단계 | New token 클릭 |
| 3단계 | 역할(read·write·fine-grained)과 이름 지정 |
| 관리 | Manage 에서 삭제·갱신 |
| 터미널 로그인 | hf auth login |
| git 인증 | 비밀번호 대신 토큰 입력 |
Hugging Face 429 오류 해결
429 Too Many Requests 는 5분 동안 허용된 요청 수를 넘었다는 뜻입니다. 공식 문서가 꼽는 1순위 원인은 HF_TOKEN 을 넘기지 않은 것입니다. 토큰이 없으면 비로그인 IP 기준(파일 받기 5분에 3,000회)으로 계산됩니다. 토큰을 넘겨도 막히면 요청을 시간에 나눠 보내거나, API 호출 대신 파일 받기 경로를 쓰거나, 요금제를 올립니다.
Hugging Face 토큰 유출 시 조치
토큰이 노출되면 설정 > Access Tokens 에서 바로 삭제하거나 갱신합니다. 갱신하기 전까지는 누구나 그 토큰으로 비공개 저장소를 읽고 쓸 수 있습니다. 남의 토큰을 발견했다면 /api/credentials/revoke 주소로 보내 무효화할 수 있고, 계정 권한이 없어도 됩니다. 토큰 주인에게는 메일이 갑니다.
Hugging Face 에서 게이트 모델을 받으려면 로그인한 뒤 브라우저에서 접근 요청에 동의해야 하고, 거절되면 다시 요청할 수 없습니다. 승인된 뒤 스크립트로 받을 때는 hf auth login 으로 토큰 로그인을 해야 합니다. 요청은 5분 단위로 세며 무료 계정은 파일 받기 5,000회, 비로그인은 3,000회이고, 429 오류의 1순위 원인은 HF_TOKEN 을 넘기지 않은 것입니다. 무료 계정의 비공개 저장은 100GB, 파일 하나는 최대 500GB, 한 폴더에는 1만 개까지입니다. Spaces는 정적 앱만 무료로 만들 수 있고 Gradio·Docker는 유료 요금제가 필요하며, 무료 계정은 ZeroGPU Gradio Spaces를 2개까지 둡니다. PRO는 월 9달러, 신용카드 전용이고 모든 구독이 매월 1일에 갱신됩니다.
