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

내려받은 바이트가 머무는 곳

기본 캐시 위치는 macOS와 Linux에서 ~/.cache/huggingface/hub, Windows에서 %USERPROFILE%\.cache\huggingface\hub야. 토큰과 Hub·Datasets 캐시를 한꺼번에 옮기려면 HF_HOME, Hub 캐시만 바꾸려면 HF_HUB_CACHE를 써.

각 저장소 디렉터리 안에는 해시로 주소를 매긴 blobs, 브랜치와 태그를 가리키는 refs, 특정 커밋을 심볼릭 링크로 조립한 snapshots가 있어. 여러 커밋을 받아도 동일한 대형 가중치가 디스크에 중복되지 않는 이유가 이 구조야.

프로덕션에서는 커밋 SHA를 고정해

from_pretrained, snapshot_download, load_dataset은 모두 revision=을 받아. 생략하면 기본 브랜치의 최신 상태를 따라가므로, 제작자가 tokenizer를 바꾸는 순간 오류 없이 출력이 달라질 수 있어. 브랜치와 태그는 움직일 수 있지만 커밋 SHA는 내용에 고정돼. 재현성이 필요하면 SHA를 써.

캐시를 미리 데우면 오프라인에서도 돌아가

HF_HUB_OFFLINE=1은 Hub로 향하는 HTTP 요청을 막아. 필요한 blob을 캐시에 미리 넣어 두면 외부 통신이 없는 환경에서도 같은 파일을 불러올 수 있어. 반대로 캐시에 파일이 빠져 있다면 네트워크로 보충하지 않고 즉시 실패해.

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 같은 작은 공개 모델을 미리 받아. huggingface-cli scan-cache로 캐시 구조를 확인한 뒤 HF_HUB_OFFLINE=1을 켜고 from_pretrained로 다시 불러와. 성공을 확인한 다음 snapshot 디렉터리 하나를 지우고 오프라인에서 재실행해 실패 조건도 관찰해.