bodaay/HuggingFaceModelDownloader

🤖 HuggingFace 모델 다운로더 (hfdownloader)

정의 – HuggingFace Hub에서 모델, 데이터셋, LoRA, Diffusers 파이프라인 등을 가져오기 위한 빠르고 병렬적이며 프록시를 지원하는 명령줄 도구(Go로 작성). 파일을 표준 HF 캐시에 저장하므로 기존 Python 라이브러리(transformers, diffusers, llama.cpp 바인딩 등)가 자동으로 찾을 수 있으며, 심볼릭 링크/하드 링크를 통해 사람이 읽을 수 있는 보기도 제공합니다.

중요한 이유 – 대규모 모델 파일은 수십 기가바이트에 달할 수 있습니다. hfdownloader는:

각 파일을 최대 16개의 병렬 연결로 분할하고 8개 파일을 동시에 다운로드하여 실제 소요 시간을 크게 줄입니다.
중단 후 자동으로 재개하고 LFS 파일을 SHA-256으로 검증합니다.
품질 별점, RAM 추정치, "권장" 양자화를 표시하는 대화형 GGUF 선택기를 제공하여 양자화 모델의 올바른 버전을 쉽게 선택할 수 있습니다.
완전한 HTTP/SOCKS5 프록시 지원, 인증, CIDR 우회 규칙으로 기업 방화벽 뒤에서도 작동합니다.
그래픽 인터페이스를 선호하는 사용자를 위해 웹 UI(실시간 진행 상황, 캐시 브라우저, 미러 동기화, 설정)를 제공합니다.
미러 동기화 기능을 통해 로컬 캐시를 NAS, USB 드라이브 또는 다른 머신으로 푸시/풀할 수 있습니다. 에어갭 또는 팀 환경에 유용합니다.

설치 방법

한 줄 설치(sudo 불필요): bash <(curl -sSL https://g.bodaay.io/hfd) install
Linux, macOS, Windows용 사전 빌드 바이너리는 GitHub Releases 페이지에 있습니다.
Go 1.25+로 소스에서 빌드: go build -o hfdownloader ./cmd/hfdownloader
Docker 이미지 ghcr.io/bodaay/huggingfacemodeldownloader (캐시를 유지하려면 ~/.cache/huggingface를 마운트).

일반적인 명령줄 워크플로

# 저장소 내용 확인 (대화형 GGUF 선택기)
hfdownloader analyze -i TheBloke/Mistral-7B-Instruct-v0.2-GGUF

# 특정 양자화 다운로드 (또는 여러 개)
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m
# 또는 최대 병렬로 모든 항목 다운로드
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF -c 16 --max-active 8

# 이미 캐시된 파일을 일반 디렉토리로 내보내기 (llama.cpp, Ollama 등용)
hfdownloader export TheBloke/Mistral-7B-Instruct-v0.2-GGUF ~/models/mistral

# 웹 UI 시작 (http://localhost:8080)
hfdownloader serve

주요 개념

저장 모드 1 – HF 캐시 (기본) – 파일은 ~/.cache/huggingface/hub/...(콘텐츠 주소 지정 blob) 및 ~/.cache/huggingface/models/ 아래의 사람이 읽을 수 있는 심볼릭 링크 트리에 저장됩니다. Python 도구는 그냥 작동합니다.
저장 모드 2 – 플랫 디렉토리 – --local-dir <path> 또는 레거시 -o <dir>을 사용하여 실제 파일이 있는 일반 <owner>/<repo>/ 폴더를 얻습니다. HF 캐시 레이아웃을 이해하지 못하는 도구에 유용합니다.
매니페스트 (hfd.yaml) – 모든 다운로드는 저장소, 커밋, 선택된 파일, 크기 및 사용된 정확한 명령을 설명하는 작은 YAML 파일을 작성합니다. hfdownloader list 및 hfdownloader info로 이 메타데이터를 조회할 수 있습니다.
프록시 구성 – 명령별로 전달(--proxy ...)하거나 ~/.config/hfdownloader.yaml에 저장할 수 있습니다.
미러 동기화 – 명명된 대상을 정의하고(hfdownloader mirror target add office /mnt/nas/hf-models) push, pull 또는 diff를 사용하여 캐시를 동기화합니다.

사용 대상

대규모 GGUF, GPTQ 또는 Diffusers 모델을 정기적으로 가져오는 연구원 또는 엔지니어.
강력한 프록시 처리가 필요한 기업 네트워크의 팀.
심볼릭 링크 문제를 처리하지 않고 HF 캐시의 편리함을 원하는 Windows 또는 macOS 사용자.
다운로드 모니터링 및 공유 모델 캐시 관리를 위해 웹 대시보드를 선호하는 모든 사람.

라이선스 – Apache 2.0 (개인 및 상업용 무료).

빠른 링크

bodaay/HuggingFaceModelDownloader

🤖 HuggingFace 모델 다운로더 (hfdownloader)

관련