데이터셋 다운로드하기
데이터셋 다운로드하기
Hub의 데이터셋은 코드 몇 줄이면 불러올 수 있어요. 큰 데이터셋은 hf-mount로 로컬 파일시스템처럼 마운트해서 필요한 만큼만 네트워크로 가져올 수도 있죠.
다운로드 속도를 이렇게 저렇게 최적화하는 방법까지 함께 살펴볼게요.
출처: 문서
본문
통합된 라이브러리
Hub의 데이터셋이 지원되는 라이브러리에 연결되어 있다면, 데이터셋을 불러오는 건 몇 줄이면 돼요. 데이터셋 접근 방법을 보려면 데이터셋 페이지의 "Use this dataset" 버튼을 클릭하면 돼요. 예를 들어 samsum은 아래처럼 datasets로 사용하는 방법을 보여줘요.
Hugging Face 클라이언트 라이브러리 사용하기
huggingface_hub 라이브러리로 리포지토리를 생성, 삭제, 업데이트하고 정보를 가져올 수 있어요. 예를 들어 HuggingFaceH4/ultrachat_200k 데이터셋을 명령줄에서 다운로드하려면 이렇게 실행해요:
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
자세한 내용은 HF CLI 다운로드 문서를 참고해요.
이걸 자신의 라이브러리에 통합할 수도 있어요! 예를 들어 Pandas로 CSV 데이터셋을 몇 줄이면 빠르게 불러올 수 있어요.
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을 설치하고 아래 명령을 실행하면 데이터셋을 로컬로 클론할 수 있어요:
git xet install
git lfs install
git clone [email protected]:datasets/<dataset ID> # example: git clone [email protected]:datasets/allenai/c4
해당 데이터셋 리포지토리에 쓰기 접근 권한이 있다면 이 데이터셋에 리비전을 커밋하고 푸시할 수도 있어요.
변경사항을 푸시하거나 비공개 리포지토리에 접근하려면 SSH 공개 키를 내 설정에 추가해요.
더 빠른 다운로드
Hugging Face CDN에서 다운로드 속도를 fast.hf.co에서 테스트할 수 있어요. 이는 가장 가까운 HF 엣지 서버에 대해 빠른 대역폭 테스트를 실행해 기준 처리량을 파악하게 도와줘요. hf-speedtest CLI 확장으로 터미널에서도 다운로드 속도를 측정할 수 있어요:
hf extensions install julien-c/hf-speedtest
hf speedtest
더 빠른 전송을 위해 Hub는 네트워크 상태에 따라 병렬 스트림을 자동 조정하는 적응형 동시성을 가진 Xet 스토리지 백엔드를 사용해요. HF_XET_HIGH_PERFORMANCE=1 같은 조정 옵션은 모델 더 빠른 다운로드를 참고해요.
hf-mount 사용하기
큰 데이터셋은 전체를 다운로드하는 대신 hf-mount로 리포지토리를 로컬 파일시스템으로 마운트할 수 있어요. 파일은 지연(lazy) 방식으로 가져와져서 — 코드가 읽는 바이트만 네트워크를 타요. Python 이터레이터보다 로컬 파일 경로(tarfile, zipfile, imagefolder)를 기대하는 워크플로에 유용해요.
brew install hf-mount
hf-mount start repo datasets/stanfordnlp/imdb /tmp/imdb
리포지토리는 읽기 전용으로 마운트돼요. 전체 설정, 백엔드 옵션, 캐싱은 로컬 파일시스템으로 마운트를 참고해요.
프록시나 방화벽 뒤에서 다운로드하기
네트워크가 방화벽이나 프록시로 나가는 트래픽을 제한한다면, 데이터셋 다운로드에는 huggingface.co 말고도 더 필요한 게 있어요. 파일 내용은 별도의 스토리지와 CDN 호스트에서 서빙되므로 huggingface.co 자체가 허용 목록에 있어도 이 호스트들에 닿을 수 없으면 load_dataset / hf download가 실패해요.
다음 호스트들을 허용 목록에 추가해요 (모두 HTTPS / 포트 443):
| 호스트네임 | 용도 |
|---|---|
huggingface.co |
Hub API, 메타데이터, 다운로드 리다이렉트 |
cas-server.xethub.hf.co |
Xet 프로토콜 API, 다운로드·업로드 (US) |
cas-server.xethub-eu.hf.co |
Xet 프로토콜 API, 다운로드·업로드 (EU) |
transfer.xethub.hf.co |
Xet 스토리지 다운로드 API (US) |
transfer.xethub-eu.hf.co |
Xet 스토리지 다운로드 API (EU) |
us.aws.cdn.hf.co |
CDN 엣지 (US) |
us.gcp.cdn.hf.co |
CDN 엣지 (US) |
cdn-lfs-us-1.hf.co |
LFS CDN (US) |
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에 JSON으로도 공개돼 있어요. 표를 손으로 복사하는 대신 여기서 프록시·방화벽 규칙을 생성할 수 있어요.
[!WARNING] 엔드포인트가 추가·제거되면서 파일은 바뀌어요. 사본을 고정(pin)하지 말고 규칙을 만들 때마다 다시 가져와요.