2026 원격 Mac HF Hub 가중치 국경 간 풀 결정 매트릭스

대상: 원격 Mac에서 추론 프리웜, 벤치·평가 스크립트, 경량 파인튜닝, Hub 스냅샷을 아티팩트로 고정하는 파이프라인.병목에 체크: (1) huggingface.co 직접 연결 시 국경 간 RTT·TLS·메타데이터 왕복이 김; (2) 단일 파일 수 GB~100GB+인데 HF_HUB_DOWNLOAD_TIMEOUT 기본(초 단위로 짧음) 때문에 TimeoutError 반복; (3) 캐시가 대화형 사용자 홈에만 있어 CI 데몬 사용자와 경로 불일치로 매번 풀; (4) 공유 Mac에서 다중 job이 동일 캐시 디렉터리에 쓰기·심볼릭 링크·NFS 특성 충돌; (5) HF_HUB_ENABLE_HF_TRANSFER=1만 켜고 최신 스택에서 기대와 다른 경로를 탐—신규 환경은 Xet·HF_XET_HIGH_PERFORMANCE·HF_XET_NUM_CONCURRENT_RANGE_GETS를 먼저 매칭해야 합니다.

복붙 골격(zsh/bash, Python import 전에 실행):

export HF_ENDPOINT="${HF_ENDPOINT:-https://huggingface.co}"
export HF_HOME="${HF_HOME:-/usr/local/ci/hf}"
export HUGGINGFACE_HUB_CACHE="${HUGGINGFACE_HUB_CACHE:-$HF_HOME/hub}"
export HF_XET_CACHE="${HF_XET_CACHE:-$HF_HOME/xet}"
export HF_HUB_DOWNLOAD_TIMEOUT="${HF_HUB_DOWNLOAD_TIMEOUT:-600}"
export HF_HUB_ETAG_TIMEOUT="${HF_HUB_ETAG_TIMEOUT:-60}"
# 공유 Mac: 아래 두 줄은 기본 유지 또는 주석
# export HF_XET_HIGH_PERFORMANCE=1
# export HF_XET_NUM_CONCURRENT_RANGE_GETS=32
# 레거시 의존성 전용:
# export HF_HUB_ENABLE_HF_TRANSFER=1

이어받기: huggingface_hub는 캐시 레이아웃에 미완료 조각을 쓴 뒤 성공 시 원자적으로 치환합니다. 동일 리비전 스냅샷을 재실행하면 전체 재다운로드 없이 이어쓰기되는 경우가 많습니다. 단계 사이에 HUGGINGFACE_HUB_CACHE를 비우거나 HF_ENDPOINT를 바꾸면 네임스페이스가 달라져 사실상 새 풀로 봐야 합니다. 이미 선풀한 빌드만 재현하려면 HF_HUB_OFFLINE=1로 네트워크 ETag 조회를 건너뛰는 게이트를 둘 수 있습니다(로컬 스냅샷 전제).

CI 캐시 키(GitHub Actions 의미 예시): OS·락파일·모델 커밋 SHA·엔드포인트 슬러그를 한 줄에 묶습니다.

# key 개념 예시 — 경로·문법은 러너에 맞게 수정
key: hf-${{ runner.os }}-${{ hashFiles('requirements.txt','pyproject.toml') }}-${{ env.MODEL_REVISION }}-${{ env.HF_ENDPOINT_SLUG }}
path: |
  /usr/local/ci/hf/hub
  /usr/local/ci/hf/xet

MODEL_REVISION은 Hub 커밋 SHA(또는 태그가 가리키는 SHA)를 권장합니다. main 문자열만 쓰면 무효화 정책이 불명확해집니다. HF_ENDPOINT_SLUG는 official·mirror-example 같이 파이프라인이 주입하는 짧은 식별자면 충분합니다.