다운로드, 캐싱, 핀 (Pinning)

바이트 어디로 가

디폴트 캐시 root: macOS/Linux 는 ~/.cache/huggingface/hub, Windows 는 %USERPROFILE%\.cache\huggingface\hub. HF_HOME (추천 — 토큰, hub 캐시, datasets 캐시 한 번에 cover) 또는 HF_HUB_CACHE (모델/Space 캐시만) 으로 override.

안에는 각 레포가 models--{org}--{name} 디렉토리 가져 — blobs (해시로 content-address), refs (브랜치/태그 포인터), snapshots (특정 커밋의 symlinked checkout). 70B 모델이 디스크에 한 카피만 있는 이유 — 다른 커밋 셋 checkout 해도 symlink 라서.

핀 안 하면 나중에 비용

모든 로더 (from_pretrained, snapshot_download, load_dataset) 가 revision= 인자 받아: 브랜치, 태그, 또는 커밋 SHA. 안 박으면 디폴트 브랜치가 뭐든 그거 받게 되고, 그게 조용히 너 밑에서 움직여. 모델 작가가 tokenizer 픽스를 force-push 하는 그 첫 순간, 파이프라인 출력 character 가 바뀌어 — 에러 없이, 로그 라인 없이. 프로덕션엔 SHA 핀. 태그는 편한데 mutable 이야.

Air-gapped / 오프라인

HF_HUB_OFFLINE=1 은 어떤 HTTP 콜이든 hard-fail. pre-warmed 캐시랑 합치면, outbound internet 없는 환경에 ship 하는 방법이 이거야. content-addressed 캐시의 핵심이 — blob 만 있으면 air-gap 모드가 그냥 동작.

Code

핀 박은 snapshot download·python

from huggingface_hub import snapshot_download

# SHA 핀 (immutable). 태그면 revision="v1.0".
local_path = snapshot_download(
    repo_id="meta-llama/Llama-3.1-8B-Instruct",
    revision="0e9e39f249a16976918f6564b8830bc894c89659",  # 예시 SHA
    allow_patterns=["*.safetensors", "*.json", "tokenizer*"],
    ignore_patterns=["*.bin"],  # .safetensors 있으면 .bin skip
)
print("downloaded to:", local_path)

캐시 레이아웃 + 오프라인 모드·bash

# 캐시 들여다보기
huggingface-cli scan-cache

# 다운로드 전에 캐시 root 옮기기
export HF_HOME=/big-disk/hf-home

# Air-gapped 실행
export HF_HUB_OFFLINE=1
python my_pipeline.py  # 어떤 HTTP 콜이든 hard-fail

Exercise

HF_HOME=/tmp/hf-test 셋하고 작은 오픈 모델 (예: prajjwal1/bert-tiny) pre-download. huggingface-cli scan-cache 돌려서 레이아웃 봐. 그다음 HF_HUB_OFFLINE=1 셋하고 from_pretrained 로 다시 로드 — 성공해야 함. snapshot 디렉토리 하나 지우고 오프라인 재실행 — 실패 봐.