# 데이터셋 다운로드

## 통합된 라이브러리

Hub의 데이터셋이 [지원되는 라이브러리](./datasets-libraries)와 연결되어 있으면, 몇 줄의 코드로 데이터셋을 로드할 수 있습니다. 데이터셋에 액세스하는 방법에 대한 정보는 데이터셋 페이지의 "Use this dataset" 버튼을 클릭하여 확인할 수 있습니다. 예를 들어, [`samsum`](https://huggingface.co/datasets/knkarthick/samsum?library=datasets)은 아래에서 `datasets`를 사용하여 이를 수행하는 방법을 보여줍니다.

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

[`huggingface_hub`](/docs/huggingface_hub) 라이브러리를 사용하여 리포지토리를 생성, 삭제, 업데이트하고 정보를 가져올 수 있습니다. 예를 들어, 커맨드 라인에서 `HuggingFaceH4/ultrachat_200k` 데이터셋을 다운로드하려면 다음을 실행하세요

```bash
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
```

자세한 내용은 [HF CLI 다운로드 문서](https://huggingface.co/docs/huggingface_hub/en/guides/cli#download-a-dataset-a-space-or-a-kernel)를 참조하세요.

이 기능을 직접 만든 라이브러리에 통합할 수도 있습니다. 예를 들어, Pandas를 사용하면 몇 줄의 코드로 CSV 데이터셋을 빠르게 로드할 수 있습니다.
```py
from huggingface_hub import hf_hub_download
import pandas as pd

REPO_ID = "YOUR_REPO_ID"
FILENAME = "data.csv"

dataset = pd.read_csv(
    hf_hub_download(repo_id=REPO_ID, filename=FILENAME, repo_type="dataset")
)
```

## Git 사용

Hub의 모든 데이터셋은 Xet 기반 Git 저장소이므로 [git-xet를 설치](./xet/using-xet-storage#git-xet)하고 다음을 실행하여 데이터셋을 로컬에 클론할 수 있습니다:

```bash
git xet install
git lfs install
git clone git@hf.co:datasets/<dataset ID> # example: git clone git@hf.co:datasets/allenai/c4
```

특정 데이터셋 저장소에 대한 쓰기 권한이 있으면, 데이터셋에 대한 수정 사항을 커밋하고 푸시할 수도 있습니다.

변경 사항을 푸시하거나 비공개 저장소에 액세스하려면 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
```

더 빠른 전송을 위해 Hub는 네트워크 조건에 따라 병렬 스트림을 자동으로 조정하는 적응형 동시성(adaptive concurrency)을 갖춘 [Xet 스토리지 백엔드](https://huggingface.co/docs/hub/en/xet/index)를 사용합니다. `HF_XET_HIGH_PERFORMANCE=1`와 같은 튜닝 옵션에 대한 자세한 내용은 [모델의 더 빠른 다운로드](./models-downloading#faster-downloads)를 참고하세요.

## hf-mount 사용

대용량 데이터셋의 경우, 전체 저장소를 다운로드하는 대신 [hf-mount](https://github.com/huggingface/hf-mount)를 사용하여 저장소를 로컬 파일 시스템으로 마운트할 수 있습니다. 파일은 지연 방식으로 가져오며, 코드가 실제로 읽는 바이트만 네트워크를 통해 전송됩니다. Python 반복자 대신 로컬 파일 경로(예: `tarfile`, `zipfile`, `imagefolder`)를 기대하는 워크플로에 유용합니다.

```bash
brew install hf-mount
hf-mount start repo datasets/stanfordnlp/imdb /tmp/imdb
```

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

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

네트워크가 방화벽 또는 프록시를 통해 아웃바운드 트래픽을 제한하는 경우, 데이터셋을 다운로드하려면 `huggingface.co`만 허용하는 것만으로는 부족합니다. 파일 콘텐츠는 별도의 스토리지 및 CDN 호스트 이름에서 제공되며, `huggingface.co` 자체가 허용 목록에 포함되어 있더라도 이러한 호스트에 접근할 수 없으면 `load_dataset` / `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` 접미사(모든 서브도메인)를 허용 목록에 추가하세요.

### 기계 가독성 목록

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

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