토큰, 접근 권한, CLI 로그인

토큰은 scope 가 있어 — 만능 아님

HF user access token 은 세 가지 scope: read, write, fine-grained. read 는 공개 모델 다운로드, gated license 동의, Inference API 호출에 충분. write 는 레포 생성, push, 삭제 추가. fine-grained 토큰 (서비스 계정의 모던 디폴트) 은 특정 org / 특정 레포 whitelist 가능 — 어떤 non-trivial CI 셋업이든 이거 써야 해.

토큰이 사는 곳

huggingface-cli login 후 토큰은 ~/.cache/huggingface/token 에 저장돼 (HF_HOME 으로 override). 모든 클라이언트 (transformers, datasets, huggingface_hub, accelerate) 가 거기서 읽어. HF_TOKEN 환경 변수로 프로세스 단위 override 가능 — Docker 이미지랑 CI 의 표준 패턴.

토큰 회전 — 지루한 룰

모든 토큰이 created-at 와 last-used 타임스탬프 가져 — huggingface.co/settings/tokens 에서 보여. CI 러너에 90 일 넘게 있던 토큰이면, 회전. read scope 토큰이 어쩌다 공개 레포 들어가면 blast radius 는 “이미 다운로드 가능한 거 다운로드 가능” — 근데 write 토큰이면 그건 진짜 incident. 회전, push 감사, GitHub 의 secret scanning push protection 고려.

Code

# Interactive — 가장 흔함
huggingface-cli login

# Non-interactive (CI)
echo "${HF_TOKEN}" | huggingface-cli login --token "${HF_TOKEN}" --add-to-git-credential

# whoami 로 확인
huggingface-cli whoami

# 토큰 파일 위치 (디폴트)
ls -l ~/.cache/huggingface/token

토큰 override priority·python

import os
from huggingface_hub import HfApi

# 우선순위: explicit token 인자 > HF_TOKEN env > ~/.cache/huggingface/token

# Explicit (가장 높음 — token kwarg 받는 라이브러리에서 씀)
api = HfApi(token=os.environ.get("HF_PROD_TOKEN"))
print(api.whoami())

# Implicit (env 또는 cache)
api2 = HfApi()
print(api2.whoami())

Exercise

공개 레포 read-only 로 scope 된 fine-grained 토큰 하나 만들고, 새로 만든 단일 테스트 레포 ({your-username}/scratch-{date}) 에 write scope 한 거 또 만들어. whoami 로 둘 다 검증. .env 에 저장. write 토큰으로 테스트 레포에 README.md push, read 토큰으로 push 시도 — 실패 관찰.