# 모델 다운로드

## 통합된 라이브러리

Hub의 모델이 [지원되는 라이브러리](./models-libraries)와 연결되어 있으면, 몇 줄의 코드로 모델을 로드할 수 있습니다. 모델에 접근하는 방법에 대한 정보는 모델 페이지의 "Use in _Library_" 버튼을 클릭하여 확인할 수 있습니다. 예를 들어, `distilbert/distilgpt2`는 아래에서 🤗 Transformers를 사용하여 이를 수행하는 방법을 보여줍니다.

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

[`huggingface_hub`](https://github.com/huggingface/huggingface_hub) 라이브러리를 사용하여 리포지토리를 생성, 삭제, 업데이트하고 정보를 가져올 수 있습니다. 예를 들어, 커맨드 라인에서 `HuggingFaceH4/zephyr-7b-beta` 모델을 다운로드하려면 다음을 실행하세요
```bash
hf download HuggingFaceH4/zephyr-7b-beta
```
자세한 내용은 [CLI 다운로드 문서](https://huggingface.co/docs/huggingface_hub/en/guides/cli#download-an-entire-repository)를 참조하세요.

이 기능을 자체 라이브러리에 통합할 수도 있습니다. 예를 들어, 몇 줄의 코드로 Scikit-learn 모델을 빠르게 로드할 수 있습니다.
```py
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를 설치](./xet/using-xet-storage#git-xet)하고 다음을 실행하여 모델을 로컬로 클론할 수 있습니다:

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

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

변경 사항을 푸시하거나 비공개 저장소에 액세스하려면 SSH 공개 키를 [사용자 설정](https://huggingface.co/settings/keys)에 추가하세요.

## 더 빠른 다운로드

### 다운로드 속도 테스트

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

터미널에서 [`hf-speedtest`](https://github.com/julien-c/hf-speedtest) CLI 확장을 사용하여 다운로드 속도를 직접 측정할 수도 있습니다:

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

### hf_xet의 적응형 동시성

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

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

```bash
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`을 사용하세요. 사용된 값은 [다운로드 버퍼](./xet/using-xet-storage#download-buffers)를 참조하세요.

## hf-mount 사용

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

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

Repos는 읽기 전용으로 마운트됩니다. 전체 설정 세부 사항, 백엔드 옵션 및 캐싱에 대해서는 [로컬 파일시스템으로 마운트](./storage-buckets-access#mount-as-a-local-filesystem)를 참조하세요.

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

네트워크가 방화벽 또는 프록시를 통해 아웃바운드 트래픽을 제한하는 경우, 모델과 데이터셋을 다운로드하려면 `huggingface.co`만으로는 부족합니다. 파일 콘텐츠는 별도의 스토리지 및 CDN 호스트네임에서 제공되며, `huggingface.co` 자체가 허용 목록에 포함되어 있더라도 이러한 호스트에 접근할 수 없으면 `from_pretrained` / `hf download`가 실패합니다.

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

| 호스트 이름                     | 목적                                     |
|------------------------------|---------------------------------------------|
| `huggingface.co`             | Hub API, 메타데이터 및 다운로드 리디렉션   |
| `cas-server.xethub.hf.co`    | Xet 프로토콜 API, 다운로드 및 업로드(미국) |
| `cas-server.xethub-eu.hf.co` | Xet 프로토콜 API, 다운로드 및 업로드(EU) |
| `transfer.xethub.hf.co`      | Xet 스토리지 다운로드 API(미국)              |
| `transfer.xethub-eu.hf.co`   | Xet 스토리지 다운로드 API (EU)              |
| `us.aws.cdn.hf.co`           | CDN 엣지(미국)                               |
| `us.gcp.cdn.hf.co`           | CDN 엣지(미국)                               |
| `cdn-lfs-us-1.hf.co`         | LFS CDN(미국)                                |
| `cdn-lfs-eu-1.hf.co`         | LFS CDN (EU)                                |

> [!TIP]
> 다운로드는 `huggingface.co`에서 이러한 호스트 이름으로 HTTP 리다이렉트를 따르므로, `huggingface.co`만 허용 목록에 추가하는 것만으로는 충분하지 않습니다. 다운로드 도중 `ReadTimeoutError`(연결 오류가 아닌)가 발생하면 초기 연결은 성공했지만 스토리지 또는 CDN 호스트가 차단되었음을 의미하는 경우가 많습니다.

> [!TIP]
> 와일드카드 동작은 프록시가 도메인을 매칭하는 방식에 따라 달라집니다. 많은 엔터프라이즈 프록시는 허용 목록 항목을 모든 깊이의 하위 도메인을 포함하는 접미사 매칭으로 취급합니다. 프록시가 이 방식을 사용하는 경우, 가장 간단한 방법은 `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`를 포함하지 않는다는 점에 유의하십시오.

> [!WARNING]
> 저장소 및 CDN 인프라가 발전함에 따라 이러한 호스트네임은 변경될 수 있습니다. 보안 정책이 허용하는 경우, 특정 엔드포인트가 변경되어 규칙이 깨지지 않도록 `hf.co` 및 `huggingface.co` 접미사(모든 서브도메인)를 허용 목록에 추가하세요.

> [!NOTE]
> `hf_xet` 1.8.0 이상으로 업로드하는 경우, `hf.co` 또는 `huggingface.co` 도메인이 아닌 Amazon S3 호스트 이름으로 직접 업로드할 수도 있습니다. [프록시 또는 방화벽 뒤에서 업로드하기](./xet/using-xet-storage#uploading-behind-a-proxy-or-firewall)를 참조하세요.

### 기계 가독성 목록

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

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