이 글의 목차
모델 페이지는 열리는데 대용량 파일 다운로드가 시작되면 계속 재시도하는 경우가 있습니다. 시간 제한을 늘리거나 캐시를 지워도 해결되지 않을 수 있습니다. 작은 파일과 가중치는 다운로드 방식이 다를 수 있으므로 계정 권한, 프록시 경로, 디스크 공간도 따로 확인하세요. 완료된 파일을 보존하고 실제 사용 도구에 맞게 점검하면 처음부터 다시 받는 일을 줄일 수 있습니다.
Hub의 작은 파일, Xet 청크와 기존 Git LFS 다운로드는 어떻게 다를까요?
모델 카드나 config.json으로 일반 Hub 요청을 확인하세요. 대용량 가중치는 보통 Xet 청크로 다운로드하며 이는 큰 파일을 작은 조각으로 나누어 전송하는 방식입니다. 아래 표에서 사용 중인 도구를 확인하세요. 기존 Git LFS에는 별도의 호환 방식이 있습니다. 점검 중에도 완료된 캐시는 보존하고 작은 파일로 계정과 네트워크를 확인합니다.
현재 다운로드 방식
| 방식 | 실제 대용량 파일 백엔드 | 적합한 상황 |
|---|---|---|
| huggingface_hub / hf CLI | huggingface_hub 0.32+는 hf_xet를 자동 설치하고 Xet 청크 다운로드를 사용 | 모델과 데이터 세트 다운로드에 우선 사용 |
| git clone + git-xet | Xet, Git 워크플로도 유지 | 전체 저장소와 커밋 기록이 필요한 경우 |
| 기존 Git LFS 클라이언트 | 호환 브리지를 통해 계속 작동 | 이전 워크플로이며 현재 성능 기준의 우선 선택은 아님 |
| 브라우저 단일 파일 | Hub에서 생성한 다운로드 주소 | 소형 파일 확인 또는 임시 다운로드 |
Hugging Face 공식 문서에 따르면 Hub는 Xet를 채택했습니다. Git LFS도 계속 호환되지만 hf_transfer는 더 이상 사용되지 않으므로 hf_xet로 전환해야 합니다. Git LFS만 설치하고 HF_HUB_ENABLE_HF_TRANSFER를 켜라고 하는 이전 가이드는 2026년 기본 방식으로 적합하지 않습니다.
config.json 다운로드 여부로 사용 허가 문제와 기본 연결 장애 구분하기
python -m pip install -U huggingface_hub
hf auth login
hf download gpt2 config.json
# 查看版本
python -c "import huggingface_hub; print(huggingface_hub.__version__)"공개 모델의 소형 파일 다운로드에 성공하면 Hub 메타데이터, 기본 HTTPS와 로컬 캐시 디렉터리를 사용할 수 있다는 뜻입니다. 제한 모델에서 401/403이 반환되면 브라우저에서 같은 계정으로 사용 조건에 동의하고 token의 read 권한을 확인하세요. 노드를 바꾼다고 계정이 자동 승인되지는 않습니다.
token은 hf auth login으로 저장하고 Clash YAML, Notebook 셀 또는 공개 스크립트에는 기록하지 않습니다. 팀 서버에서는 자체 secrets 관리를 사용하고 개인 token을 복사하지 마세요.
환경 변수는 huggingface_hub를 가져오기 전에 설정해야 함
아래 예제에서는 HF_HOME을 변경합니다. 앞 절에서 로그인한 뒤에도 같은 token 출처를 사용하는지 확인하세요. 인증에는 HF_TOKEN 값이 우선 사용되며, HF_TOKEN_PATH로 다른 파일 위치를 지정할 수 있습니다. 기본 token 파일 위치는 HF_HOME을 따릅니다.
제한된 모델을 다운로드하기 전에 프록시와 캐시 디렉터리를 정하세요. 디렉터리를 바꾼 뒤 hf auth whoami로 현재 계정을 확인하고 필요하면 해당 환경에서 다시 로그인하세요. 공개 모델 예시는 로그인이 필요 없으며 성공해도 제한된 모델의 접근 허가가 유효하다는 뜻은 아닙니다.
CLASH_PORT=7890
export HTTPS_PROXY="http://127.0.0.1:$CLASH_PORT"
export HTTP_PROXY="http://127.0.0.1:$CLASH_PORT"
export HF_HOME="$HOME/hf-cache"
export HF_HUB_DOWNLOAD_TIMEOUT=30
mkdir -p "$HF_HOME"
hf download openai-community/gpt2 --include '*.json'
hf download openai-community/gpt2 --cache-dir "$HF_HOME/hub"공식 문서에 따르면 huggingface_hub는 import 시 환경 변수를 읽습니다. Notebook에서 라이브러리를 이미 가져온 뒤 변수를 바꾸면 현재 커널이 기존 값을 계속 사용할 수 있습니다. kernel을 재시작하거나 시작 전에 설정하세요. HF_HUB_DOWNLOAD_TIMEOUT 기본값은 10초이며 연결은 이미 되었지만 읽기가 느릴 때만 늘리는 것이 적합합니다.
HF_HOME은 token과 캐시 루트 디렉터리에 함께 영향을 줍니다. 저장소 캐시만 옮기려면 HF_HUB_CACHE 또는 명령의 --cache-dir을 사용할 수 있습니다. 현재 사용자에게 디렉터리 쓰기 권한이 있어야 하며 임시 청크, 모델 revision과 압축 해제에 필요한 공간도 남겨 두세요.
웹페이지는 열리지만 모델 청크에서 시간 초과가 나면 연결 페이지에서 Xet 요청 확인
모델 카드와 README는 짧은 요청으로 가져오지만 Xet 대용량 파일 다운로드는 파일 내용을 기준으로 데이터를 찾는 주소와 임시 접근 권한이 포함된 저장소 주소에도 접근합니다. 웹페이지가 열리는 것은 huggingface.co에 접속할 수 있다는 뜻일 뿐입니다. 분할 다운로드가 시작된 뒤 재시도가 반복되면 노드를 고정하고 실패한 도메인, 상태 코드, 캐시 쓰기 오류를 확인하세요.
관련 Hub/Xet 요청을 같은 고정 노드에서 비교해 경로별 연결 차이를 확인하고 다운로드 후 자동 선택을 복원하세요. 경로 변경만으로 사전 서명 URL이 무효화됐다고 볼 수 없으므로 상태 코드와 권한 정보도 확인해야 합니다. 임시 저장소 도메인을 넓은 DOMAIN-KEYWORD 규칙으로 영구 처리하지 마세요.
401 / 403
저장소 접근 권한과 token을 확인하고 시간 제한은 늘리지 마세요.
httpx.TimeoutException / Read timed out
노드를 고정하고 실패 요청의 경로를 확인하세요. Hub 파일 읽기가 느리면 HF_HUB_DOWNLOAD_TIMEOUT을 조정할 수 있지만 Xet 청크 오류는 hf_xet 로그로 별도 확인해야 합니다. 하나의 변수가 모든 다운로드를 제어한다고 가정하지 마세요.
No space left on device
완료된 캐시는 유지한 채 HF_HOME/HF_HUB_CACHE를 옮기고 노드는 바꾸지 않습니다.
캐시 쓰기 중 Permission denied
디렉터리 소유자와 마운트 권한을 바로잡고 root로 전체 모델을 다시 내려받지 않습니다.
몇 KB짜리 포인터 파일만 받아짐
Git 절차에 git-xet/git-lfs가 없거나 대용량 파일 체크아웃이 완료되지 않았습니다.
완료된 Hub 파일 재사용하기: 청크 캐시 변수는 효과 없음
기본 Hub 캐시는 ~/.cache/huggingface/hub에 있고 Xet 관련 디렉터리는 ~/.cache/huggingface/xet입니다. HF_HOME을 바꾸면 이후 사용하는 경로가 바뀌지만 기존 파일이 자동으로 이동하지는 않습니다. 원래 디렉터리의 완료된 파일을 보존한 뒤 어느 캐시를 옮기거나 계속 사용할지 정하세요.
Hub의 refs, blobs, snapshots는 이미 완료된 파일을 재사용합니다. 다운로드가 중단되면 같은 repo_id, revision, 사용자, 캐시 디렉터리로 다시 실행하세요.
현재 공식 문서에 따르면 HF_XET_CHUNK_CACHE_SIZE_BYTES는 효과가 없습니다. hf_xet는 다운로드용 로컬 청크 캐시를 더 이상 사용하지 않으며 이 변수로 켤 수도 없습니다. 완료된 Hub 파일을 재사용하고 실제 요청과 저장 공간을 확인하세요. “청크 캐시를 켜려고” blobs를 지우거나 모델 전체를 다시 받지 마세요.
from pathlib import Path
from huggingface_hub import snapshot_download
cache_dir = Path.home() / "hf-cache" / "hub"
path = snapshot_download(
repo_id="openai-community/gpt2",
revision="main",
cache_dir=cache_dir,
)
print(path)Git을 반드시 사용해야 한다면 git-xet를 설치하고 LFS 호환성 유지
프로젝트가 Git 기록이나 브랜치 작업에 실제로 의존할 때만 이 경로가 필요합니다. 일반 모델 다운로드에는 hf download를 우선 사용하면 이어받기와 캐시 상태를 더 쉽게 확인할 수 있습니다.
git xet 명령이 없다면 해당 플랫폼의 공식 안내에 따라 git-xet을 설치하세요. macOS는 Homebrew를 사용할 수 있고 Windows 공식 문서에는 winget 설치 방법이 있습니다. 이전 클라이언트도 LFS bridge를 통해 다운로드할 수 있지만 속도나 대용량 파일 문제가 생기면 Hugging Face의 관련 다운로드 도구부터 업데이트하세요.
HF_REPO='OWNER/MODEL'
# 例如 HF_REPO='openai-community/gpt2'
git lfs install
git xet install
git clone "https://huggingface.co/$HF_REPO"
cd "${HF_REPO##*/}"
git xet --version
git lfs version
git statusGit은 git config와 환경 변수를 사용하며 Python SDK와는 별개의 설정입니다. hf CLI는 정상인데 git clone이 멈춘다면 Git/Xet/LFS와 Git 프록시만 확인하고 HF_HOME은 다시 변경하지 마세요.
오프라인 모드를 켜고 모델 가중치와 tokenizer가 로컬에서 로드되는지 확인하기
다운로드 결과와 오프라인 사용 확인하기
같은 다운로드 명령 다시 실행
모든 조각을 다시 전송하지 않고 같은 snapshot을 빠르게 찾아야 합니다.
모델 한 번 불러오기
실제 transformers 또는 프로젝트 코드로 가중치와 tokenizer를 읽습니다.
오프라인 모드 테스트 활성화
캐시된 콘텐츠를 사용할 수 있다면 HF_HUB_OFFLINE=1을 설정하거나 local_files_only를 사용했을 때 더 이상 Hub에 접속하지 않아야 합니다.
자격 증명과 공간 확인
Notebook, 로그, Git 기록에 token이 남아 있지 않고 캐시 디스크에 업그레이드 여유 공간이 있는지 확인합니다.
revision과 snapshot 경로 기록
다음 모델 업데이트 때 새 버전 다운로드와 기존 캐시 손상을 구분할 수 있습니다.