# Downloading datasets

## 統合ライブラリ

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はネットワーク状況に応じて並列ストリームを自動的に調整する適応的並行性を持つ[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
```

リポジトリは読み取り専用でマウントされます。完全なセットアップの詳細、バックエンドのオプション、およびキャッシュについては、[ローカルファイルシステムとしてマウントする](./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` は 2 ラベルの `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]
> エンドポイントが追加・削除されるたびにファイルの内容が変更されます。コピーを固定するのではなく、ルールを構築する際に取得してください。