개발 및 AI · Clash 기술 블로그

Hugging Face 모델 다운로드가 느리거나 중단될 때 해결 방법: Clash, Git LFS 및 캐시 구성 가이드

웹페이지가 열린다고 해서 모델 파일 다운로드 경로도 정상인 것은 아닙니다. Hub 메타데이터, Xet 또는 Git LFS 대용량 파일 및 로컬 캐시를 먼저 구분한 뒤 시간 초과, 중단 및 디스크 공간 문제를 처리하세요.

본문 읽기블로그로 돌아가기
  • Hugging Face
  • 모델 다운로드
  • Git LFS
  • 캐시
이 글의 목차
게시일
업데이트 날짜
예상 읽기 시간
약 9분

느린 구간이 Hub 페이지, Xet 청크 또는 기존 Git LFS 다운로드인지 먼저 확인

Hugging Face 모델 다운로드가 느리거나 끊길 때 캐시부터 지우지 마세요. 모델 카드와 config.json은 일반 Hub 요청이고 대용량 가중치는 대개 Xet 청크로 다운로드하며 이전 저장소는 계속 Git LFS를 사용할 수도 있습니다. 세 경로는 도구, 로그와 복구 방식이 다릅니다. 소형 파일로 계정과 네트워크부터 확인한 뒤 Clash 프록시, 시간 초과와 캐시 디렉터리를 설정하세요.

현재 다운로드 방식

방식실제 대용량 파일 백엔드적합한 상황
huggingface_hub / hf CLIhuggingface_hub 0.32+는 hf_xet를 자동 설치하고 Xet 청크 다운로드를 사용모델과 데이터 세트 다운로드에 우선 사용
git clone + git-xetXet, 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를 가져오기 전에 설정해야 함

macOS / Linux 현재 터미널 예시, CLASH_PORT는 실제 mixed-port에 맞게 수정
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에 접근할 수 있다는 뜻일 뿐입니다. 청크 시작 후 재시도가 반복되면 노드 하나를 고정하고 실패 도메인, 상태 코드와 캐시 쓰기 오류를 확인하세요.

자동 정책이 다운로드 도중 출구를 바꾸면 사전 서명된 URL과 동시 연결이 함께 무효화될 수 있습니다. 관련 Hub/Xet 요청을 하나의 고정 정책 그룹에 넣고 전체 다운로드가 끝난 뒤 자동 선택을 복원하세요. 임시 저장소 도메인을 지나치게 넓은 DOMAIN-KEYWORD 규칙으로 영구 등록하지 마세요.

401 / 403

시간 제한을 늘리기 전에 저장소 권한과 token을 확인합니다.

httpx.TimeoutException / Read timed out

노드를 고정하고 Xet 요청이 규칙에 맞는지 확인한 뒤 HF_HUB_DOWNLOAD_TIMEOUT을 적절히 늘립니다.

No space left on device

완료된 캐시는 유지한 채 HF_HOME/HF_HUB_CACHE를 옮기고 노드는 바꾸지 않습니다.

캐시 쓰기 중 Permission denied

디렉터리 소유자와 마운트 권한을 바로잡고 root로 전체 모델을 다시 내려받지 않습니다.

몇 KB짜리 포인터 파일만 받아짐

Git 절차에 git-xet/git-lfs가 없거나 대용량 파일 체크아웃이 완료되지 않았습니다.

같은 revision을 다시 실행해 Hub 캐시부터 재사용한 뒤 Xet 청크 캐시 활성화 여부 결정

기본 Hub 캐시는 ~/.cache/huggingface/hub에 있으며 Xet 관련 파일은 ~/.cache/huggingface/xet에 있습니다. HF_HOME을 설정하면 두 위치가 함께 이동합니다.

Hub의 refs, blobs, snapshots는 이미 완료된 파일을 재사용합니다. 다운로드가 중단되면 같은 repo_id, revision, 사용자, 캐시 디렉터리로 다시 실행하세요.

현재 공식 문서에 따르면 Xet chunk cache의 기본 크기는 0으로, 기본적으로 비활성화되어 있습니다. 같은 콘텐츠 범위를 자주 다운로드하고 디스크 공간도 충분할 때만 HF_XET_CHUNK_CACHE_SIZE_BYTES 설정을 고려하세요. 단일 다운로드가 느리다면 먼저 노드를 고정하고 다운로드 시간 제한을 늘리며, 캐시를 시험한다는 이유로 완료된 blobs를 삭제하지 마세요.

Python에서 revision 고정, CACHE_DIR은 쓰기 가능한 자체 디렉터리로 변경 가능
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를 우선 사용하면 이어받기와 캐시 상태를 더 쉽게 확인할 수 있습니다.

Hugging Face 공식 Git 절차에 따라 먼저 HF_REPO를 교체합니다
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 status

git xet 명령이 없다면 먼저 공식 플랫폼 안내에 따라 git-xet를 설치하세요. macOS에서는 Homebrew를 사용할 수 있고 Windows 공식 문서에는 winget 설치 방법이 안내되어 있습니다. 구형 클라이언트도 LFS bridge를 통해 다운로드할 수 있지만 속도나 대용량 파일 문제가 생기면 Hugging Face 도구 체인을 우선 업그레이드해야 합니다.

Git은 git config와 환경 변수를 사용하며 Python SDK와는 별개의 설정입니다. hf CLI는 정상인데 git clone이 멈춘다면 Git/Xet/LFS와 Git 프록시만 확인하고 HF_HOME은 다시 변경하지 마세요.

다운로드 완료 후 네트워크를 끊고 모델이 실제로 로컬에 있는지 확인

진행률 표시가 끝난 뒤에도 프로젝트가 tokenizer, 설정 또는 사용자 지정 코드를 불러오면서 Hub에 접속할 수 있습니다. 마지막에는 실제 프로젝트로 오프라인 테스트를 수행해 필요한 모든 파일이 로컬 캐시에 들어왔는지 확인하세요.

전달 전 검증

  1. 같은 다운로드 명령 다시 실행

    모든 조각을 다시 전송하지 않고 같은 snapshot을 빠르게 찾아야 합니다.

  2. 모델 한 번 불러오기

    실제 transformers 또는 프로젝트 코드로 가중치와 tokenizer를 읽습니다.

  3. 오프라인 모드 테스트 활성화

    캐시된 콘텐츠를 사용할 수 있다면 HF_HUB_OFFLINE=1을 설정하거나 local_files_only를 사용했을 때 더 이상 Hub에 접속하지 않아야 합니다.

  4. 자격 증명과 공간 확인

    Notebook, 로그, Git 기록에 token이 남아 있지 않고 캐시 디스크에 업그레이드 여유 공간이 있는지 확인합니다.

  5. revision과 snapshot 경로 기록

    다음 모델 업데이트 때 새 버전 다운로드와 기존 캐시 손상을 구분할 수 있습니다.

참고 자료