모델 다운로드

통합된 라이브러리

Hub의 모델이 지원되는 라이브러리와 연결되어 있으면, 몇 줄의 코드로 모델을 로드할 수 있습니다. 모델에 접근하는 방법에 대한 정보는 모델 페이지의 “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 사용

Model Hub의 모든 모델은 Xet 기반 Git 저장소이므로 git-xet를 설치하고 다음을 실행하여 모델을 로컬로 클론할 수 있습니다:

git xet install
git lfs install
git clone git@hf.co:<MODEL ID> # example: git clone git@hf.co:bigscience/bloom

특정 모델 저장소에 대한 쓰기 권한이 있는 경우, 모델에 대한 리비전을 커밋하고 푸시할 수도 있습니다.

변경 사항을 푸시하거나 비공개 저장소에 액세스하려면 SSH 공개 키를 사용자 설정에 추가하세요.

더 빠른 다운로드

다운로드 속도 테스트

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

터미널에서 hf-speedtest CLI 확장을 사용하여 다운로드 속도를 직접 측정할 수도 있습니다:

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

hf_xet의 적응형 동시성

hf_xet는 Xet 스토리지 백엔드를 활용하여 청크 기반 중복 제거를 통해 파일 전송을 최적화하는 Rust 기반 패키지입니다. 기본적으로 hf_xet는 적응형 동시성을 사용합니다. 이는 실시간 네트워크 조건에 따라 병렬 전송 스트림의 수를 자동으로 조정하며, 보수적으로 시작하여(1개 스트림) 대역폭이 허용하는 한 64개의 동시 스트림까지 확장합니다.

대부분의 머신 — 데이터 센터 환경을 포함하여 — 기본 설정으로도 사용 가능한 네트워크 대역폭을 이미 포화 상태로 만듭니다. 높은 대역폭과 빠른 디스크를 갖춘 머신을 사용하는 고급 사용자의 경우, HF_XET_HIGH_PERFORMANCE=1은 동시성 한도를 높이고 메모리 버퍼 크기를 증가시켜, 여러 개의 큰 파일을 병렬로 다운로드할 때 도움이 될 수 있습니다.

HF_XET_HIGH_PERFORMANCE=1 hf download ...

hf_xet 1.7.0부터 다운로드 버퍼 크기는 hf_xet에 사용 가능한 메모리, 컨테이너 메모리 한도를 포함하여 HF_XET_HIGH_PERFORMANCE=1 사용 여부와 관계없이 결정됩니다. 이전 버전에서는 RAM이 최소 64 GB 이상인 머신에서만 HF_XET_HIGH_PERFORMANCE=1을 사용하세요. 사용된 값은 다운로드 버퍼를 참조하세요.

hf-mount 사용

대형 모델의 경우, 전체 저장소를 다운로드하는 대신 hf-mount를 사용하여 저장소를 로컬 파일 시스템으로 마운트할 수 있습니다. 파일은 지연 방식으로 가져오며, 코드가 실제로 읽는 바이트만 네트워크를 통해 전송됩니다.

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

Repos는 읽기 전용으로 마운트됩니다. 전체 설정 세부 사항, 백엔드 옵션 및 캐싱에 대해서는 로컬 파일시스템으로 마운트를 참조하세요.

프록시 또는 방화벽 뒤에서 다운로드

네트워크가 방화벽 또는 프록시를 통해 아웃바운드 트래픽을 제한하는 경우, 모델과 데이터셋을 다운로드하려면 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 접미사(모든 서브도메인)를 허용 목록에 추가하세요.

기계 가독성 목록

위 호스트네임은 https://huggingface.co/.well-known/meta.json에서도 JSON으로 게시되므로, 표를 수동으로 복사하는 대신 이를 기반으로 프록시 또는 방화벽 규칙을 생성할 수 있습니다.

엔드포인트가 추가되고 제거됨에 따라 파일이 변경됩니다. 복사본을 고정하는 대신 규칙을 빌드할 때 가져오세요.