모델 다운로드 (Downloading Models)

모델 다운로드 (Downloading Models)

통합 라이브러리

허브의 모델이 지원 라이브러리에 연결되어 있다면 몇 줄만으로 모델을 로드할 수 있어요. 모델에 접근하는 방법은 모델 페이지의 "Use in Library" 버튼을 클릭해 확인할 수 있어요. 예를 들어 distilbert/distilgpt2는 🤗 Transformers로 어떻게 하는지 보여줘요.

Hugging Face 클라이언트 라이브러리 사용

huggingface_hub 라이브러리로 저장소를 생성·삭제·업데이트하고 정보를 조회할 수 있어요. 예를 들어 HuggingFaceH4/zephyr-7b-beta 모델을 명령줄에서 다운로드하려면 다음을 실행해요.

hf download HuggingFaceH4/zephyr-7b-beta

자세한 내용은 CLI 다운로드 문서를 참고하세요.

이것을 내 라이브러리에 통합할 수도 있어요. 예를 들어 Scikit-learn 모델을 몇 줄로 빠르게 로드할 수 있어요.

from huggingface_hub import hf_hub_download
import joblib

REPO_ID = "YOUR_REPO_ID"
FILENAME = "sklearn_model.joblib"

model = joblib.load(
    hf_hub_download(repo_id=REPO_ID, filename=FILENAME)
)

Git 사용

모델 허브의 모든 모델은 Xet 기반 Git 저장소이므로, git-xet 설치 후 다음을 실행해 로컬에 복제할 수 있어요.

git xet install
git lfs install
git clone [email protected]:<MODEL ID> # example: git clone [email protected]:bigscience/bloom

특정 모델 저장소에 쓰기 권한이 있다면, 모델에 리비전을 커밋하고 푸시할 수도 있어요.

푸시하거나 비공개 저장소에 접근하려면 사용자 설정에 SSH 공개 키를 추가하세요.

더 빠른 다운로드

다운로드 속도 테스트

fast.hf.co에서 Hugging Face CDN의 다운로드 속도를 테스트할 수 있어요. 가장 가까운 HF 엣지 서버에 대한 빠른 대역폭 테스트를 실행해, 설정을 조정하기 전에 기준 처리량을 파악하는 데 도움을 줘요.

터미널에서 직접 hf-speedtest CLI 확장을 써서 다운로드 속도를 측정할 수도 있어요.

hf extensions install julien-c/hf-speedtest
hf speedtest

hf_xet의 적응형 동시성

hf_xet는 Xet 저장 백엔드를 활용해 청크 기반 중복 제거로 파일 전송을 최적화하는 Rust 기반 패키지예요. 기본적으로 hf_xet는 적응형 동시성을 사용해요. 실시간 네트워크 상태에 따라 병렬 전송 스트림 수를 자동으로 조정하죠. 보수적으로 1개 스트림에서 시작해 대역폭이 허용하는 대로 최대 64개 동시 스트림까지 늘려요.

데이터 센터 환경을 포함한 대부분의 머신에서 기본 설정이 이미 가용 네트워크 대역폭을 충분히 활용해요. 높은 대역폭 그리고 최소 64GB RAM을 가진 머신의 고급 사용자에게는 HF_XET_HIGH_PERFORMANCE=1이 동시성 상한을 높이고 메모리 버퍼 크기를 크게 늘려줘요. 많은 대용량 파일을 병렬로 다운로드할 때 도움이 될 수 있어요.

HF_XET_HIGH_PERFORMANCE=1 hf download ...

hf-mount 사용

대형 모델의 경우 전체 저장소를 다운로드하는 대신 hf-mount로 저장소를 로컬 파일시스템으로 마운트할 수 있어요. 파일은 지연(lazy) 방식으로 가져와져서, 코드가 읽는 바이트만 네트워크에 닿아요.

brew install hf-mount
hf-mount start repo openai-community/gpt2 /tmp/gpt2

저장소는 읽기 전용으로 마운트돼요. 전체 설정 방법, 백엔드 옵션, 캐싱은 로컬 파일시스템으로 마운트를 참고하세요.

프록시나 방화벽 뒤에서의 다운로드

네트워크가 방화벽이나 프록시로 나가는 트래픽을 제한한다면, 모델·데이터셋 다운로드는 huggingface.co만으로는 부족해요. 파일 내용은 별도의 스토리지와 CDN 호스트네임에서 제공되므로, huggingface.co 자체가 허용 목록에 있어도 이 호스트네임에 도달할 수 없으면 from_pretrained/hf download가 실패해요.

다음 호스트네임을 허용 목록에 추가하세요(모두 HTTPS/포트 443).

다운로드는 huggingface.co에서 이 호스트네임들로 HTTP 리다이렉트를 따르므로, huggingface.co만 허용 목록에 넣는 것으로는 부족해요. 다운로드 중간에 (연결 오류가 아니라) ReadTimeoutError가 난다면 보통 초기 연결은 성공했지만 스토리지나 CDN 호스트가 차단된 경우예요.

와일드카드 동작은 프록시가 도메인을 매칭하는 방식에 따라 달라요. 많은 엔터프라이즈 프록시는 허용 목록 항목을 어느 깊이든 서브도메인을 덮는 접미사 매칭으로 취급해요. 그렇다면 가장 간단한 방법은 접미사 hf.co와 huggingface.co를 허용 목록에 넣는 것 — 이게 현재와 미래의 모든 스토리지·CDN 엔드포인트를 덮어요.

프록시가 단일 라벨 와일드카드만 지원한다면(*.hf.co가 cdn-lfs-us-1.hf.co는 매칭하지만 더 깊은 us.aws.cdn.hf.co나 cas-server.xethub.hf.co는 매칭 안 함), 위 표의 명시적 호스트네임을 허용 목록에 넣으세요. *.xethub.hf.co는 xethub-eu.hf.co 아래 EU 호스트를 덮지 않고, *.cdn.hf.co는 두 라벨인 us.aws.cdn.hf.co/us.gcp.cdn.hf.co를 덮지 않아요.

이 호스트네임은 스토리지·CDN 인프라가 진화하면서 바뀔 수 있어요. 보안 정책이 허용한다면 hf.co와 huggingface.co 접미사(모든 서브도메인)를 허용 목록에 넣어, 특정 엔드포인트가 바뀌어도 규칙이 깨지지 않게 하세요.