# 大規模なデータセットの処理

すべてのJobには、[ハードウェアフレーバー](./jobs-pricing#pricing)（`hf jobs hardware`でも表示される**Ephemeral Storage**列）によって設定された固定量のローカルディスクが用意されています。そのディスクにデータセット全体を収める必要はありません。データセットと[Storage Buckets](./storage-buckets)は、Hubからストリーミング、クエリ、マウントのいずれかの方法で直接読み取れるため、1つのJobでディスク容量をはるかに超えるデータを処理できます。このページでは、各オプションと、それぞれをいつ使うべきかについて説明します。

## どちらのアプローチにしますか？

- **ディスクに収まる** → 通常の`load_dataset(...)`がそのまま動作します（または、最大 1 TB の一時ディスクまで、より大きなバリエーションを選択するだけです）。
- **行を反復処理して処理や学習を行う** → [stream](#stream-the-dataset) する。
- **Filtered or column-pruned scans** → query it [directly over `hf://`](#read-and-filter-over-hf) with Polars or DuckDB.
- **ローカルファイルパスを期待するツール** → リポジトリを[mount](#mount-a-dataset-model-or-bucket)し、遅延読み込みで読み取ります。
- **結果の永続化** → Job が終了しても残るように、[Storage Bucket](#save-results) に書き出します。

## データセットをストリーミングする

Streamingは、コードがサンプルを消費するにつれてHubからサンプルを読み込みます。ダウンロードもローカルコピーも不要で、数TB規模のデータセットにも対応できます。最近のリリースにより、[最大100倍の効率化](https://huggingface.co/blog/streaming-datasets)が実現され、多数のワーカーでトレーニングを行う場合、ローカルSSDと同等の性能に達します:

```python
from datasets import load_dataset

ds = load_dataset("HuggingFaceFW/fineweb-edu", "sample-10BT", split="train", streaming=True)
for example in ds.take(1000):
    ...  # streams in as you iterate, nothing hits disk
```

ストリームされたデータセットは、遅延評価の`.filter()`、`.map()`、`.shuffle(buffer_size=...)`、および`.batch()`をサポートする`IterableDataset`であり、ディスク容量を超えるデータでの学習のために、そのままPyTorchの`DataLoader`や`Trainer`に渡すことができます。完全なAPIについては[Streamガイド](/docs/datasets/stream)を、単一ノードまたは分散環境でのエンドツーエンドの学習手順については[Examples & Tutorials](./jobs-examples)を参照してください。

Spark を使用した分散環境でも、ストリーミングは機能します。

```python
import pyspark_huggingface

df = spark.read.format("huggingface").option("config", "sample-10BT").load("HuggingFaceFW/fineweb-edu")
```

生成される Spark データフレームは分散型です。各ワーカーは、自分自身のファイルのサブセットからストリーミングします。行と列の読み取り、書き込み、および効率的なフィルタリングの例については、[Spark のドキュメント](./datasets-spark)を参照してください。

## `hf://` からの読み取りとフィルタリング

多くのデータライブラリは、`hf://` パス経由で Hub のデータセットを直接読み取ります。**Polars**、**DuckDB**、**pandas** はすべて Hub の Parquet をネイティブでスキャンし、フィルタリングやカラム選択をスキャン処理にプッシュダウンすることで、1 つの Job がメモリやディスクに収まる量をはるかに超えるデータを処理できます。このクエリは、デフォルトの CPU フレーバーで約 28 GB の Parquet を約 4 分で集約します。

```python
import polars as pl

agg = (
    pl.scan_parquet("hf://datasets/HuggingFaceFW/fineweb-edu/sample/10BT/*.parquet")
    .filter(pl.col("int_score") >= 4)
    .group_by("int_score")
    .agg(pl.len().alias("docs"), pl.col("token_count").sum().alias("tokens"))
    .sort("int_score")
    .collect()
)
print(agg)
```

このようなスキャンはメモリ制約ではなくネットワーク制約であり、エンジンによってリモート読み取りを並列化する度合いが異なるため、タイミングはライブラリによって異なります。実用上の含意は2つあります。長時間のスキャンでは、`--timeout`をデフォルトの30分より大きく設定すること、そして高速化のために作業を複数のJobに分割して並列実行することです。ライブラリごとの例については、[Polars](./datasets-polars)、[DuckDB](./datasets-duckdb)、[pandas](./datasets-pandas)を、`hf://`経由で**buckets**を読み込む方法については、[Python data tools](./storage-buckets-access#python-data-tools)を参照してください（[`HfFileSystem`](/docs/huggingface_hub/guides/hf_file_system)を経由します）。

## データセット、モデル、またはバケットのマウント

`-v` / `--volume` を使用して、リポジトリまたはバケットを Job にローカルパスとしてマウントします。ファイルはコードが読み込む際にネットワーク経由で遅延取得されるため、ローカルファイルを読み込むツールはすべてそのまま動作します。

```bash
hf jobs uv run --flavor cpu-upgrade \
  -v hf://datasets/HuggingFaceFW/fineweb-edu:/mnt/data \
  process.py
```

```python
# /// script
# dependencies = ["polars"]
# ///
# process.py — the mounted repo is just a directory of files
from pathlib import Path

import polars as pl

for path in Path("/mnt/data/sample/10BT").glob("*.parquet"):
    shard = pl.read_parquet(path)
    ...  # process one shard at a time, write results out
```

ファイル全体が消費される場合（モデルの重み、音声や画像ファイル、アーカイブなど）、またはツールがファイルパスのみを受け入れる場合に、マウントは自然な選択です。大規模な複数ファイルのParquetスキャンでは、[`hf://` を直接クエリする](#read-and-filter-over-hf)方が、マウント経由でスキャンするよりも通常数倍速くなります。

Datasets とモデルは読み取り専用でマウントされます。一方、バケットは読み書き可能であり、[結果を保存する](#save-results)のに適した場所です。`-v` の完全な構文については [設定](./jobs-configuration#volumes) を、詳細については [バケットのアクセスパターン](./storage-buckets-access#volume-mounts-in-jobs-and-spaces) を参照してください。

> [!TIP]
> マウント経由で読み取られたファイルは、Job のエフェメラルディスクにキャッシュされるため、遅延読み込み（1 つずつ読み込む）にするとフットプリントを小さく保つことができます。`hf jobs uv run` でローカルスクリプトを実行する場合、スクリプトディレクトリは `/data` にマウントされるため、データは別の場所（例: `/mnt/data`）にマウントしてください。

## 結果を保存

Ephemeral diskはJobの終了とともに失われるため、保持したいデータは読み書き可能な[Storage Bucket](./storage-buckets)に書き込むか、Hubにデータセットとしてプッシュしてください。DuckDBは`hf://`経由でソースをフィルタリングし、一致したデータをマウントされたバケットに直接書き込むことを1つのアウトオブコアクエリで実行できるため、結果をメモリに収める必要はありません:

```bash
hf jobs uv run --flavor cpu-upgrade --timeout 1h \
  -v hf://buckets/username/my-output:/mnt/out \
  filter.py
```

```python
# /// script
# dependencies = ["duckdb"]
# ///
# filter.py — scan ~28 GB of Parquet, keep only the matching rows
import duckdb

duckdb.sql(
    """
    COPY (
        SELECT text, url, token_count
        FROM 'hf://datasets/HuggingFaceFW/fineweb-edu/sample/10BT/*.parquet'
        WHERE int_score >= 4 AND token_count >= 4000
    ) TO '/mnt/out/result.parquet' (FORMAT parquet)
    """
)
```

バケットのマウントパス配下に書き込まれたファイルは、Jobが終了した後も保持されます。処理済みデータセットを公開する場合は、代わりに[`Dataset.push_to_hub`](/docs/datasets/upload_dataset)を使用してください。

## 実例: Common Crawl をダウンロードせずにクエリする

Common Crawl は、そのアーカイブをバケット [`commoncrawl/commoncrawl`](https://huggingface.co/buckets/commoncrawl/commoncrawl) にミラーリングしています。容量は数百 TB に達します。`hf://` から WET（プレーンテキスト）シャードを 1 つストリーミングし、パースして DuckDB でクエリを実行できます。gzip がシーケンシャルに読み取られ、早期に停止されるため、転送されるのは数 MB だけです。

```python
# /// script
# requires-python = ">=3.11"
# dependencies = ["huggingface_hub>=1.9", "fastwarc>=0.15", "duckdb>=1.0"]
# ///
import duckdb
from fastwarc.warc import ArchiveIterator, WarcRecordType
from huggingface_hub import hffs

WET = (
    "buckets/commoncrawl/commoncrawl/crawl-data/CC-MAIN-2026-17/"
    "segments/1775805908305.14/wet/"
    "CC-MAIN-20260410081153-20260410111153-00000.warc.wet.gz"
)

rows = []
with hffs.open(WET, "rb") as f:
    for rec in ArchiveIterator(f, record_types=WarcRecordType.conversion):
        lang = (rec.headers.get("WARC-Identified-Content-Language", "") or "und").split(",")[0]
        rows.append((rec.headers.get("WARC-Target-URI", ""), lang, len(rec.reader.read())))
        if len(rows) >= 5000:
            break

con = duckdb.connect()
con.execute("CREATE TABLE wet(url VARCHAR, lang VARCHAR, n_chars BIGINT)")
con.executemany("INSERT INTO wet VALUES (?,?,?)", rows)
con.sql("SELECT lang, count(*) AS docs FROM wet GROUP BY lang ORDER BY docs DESC LIMIT 10").show()
```

`hf jobs uv run cc_wet.py` で実行します。デフォルトのCPUフレーバーでは約1分で完了し、以下を出力します。

```
┌─────────┬───────┐
│  lang   │ docs  │
│ varchar │ int64 │
├─────────┼───────┤
│ eng     │  1974 │
│ zho     │   586 │
│ rus     │   434 │
│ jpn     │   244 │
│ …       │    …  │
└─────────┴───────┘
```

## 関連項目

- [Stream](/docs/datasets/stream) · [ストリーミングデータセット: 100倍の効率化](https://huggingface.co/blog/streaming-datasets)
- [料金とハードウェア](./jobs-pricing#pricing) — フレーバーごとのエフェメラルディスク · [設定](./jobs-configuration#volumes) — ボリューム
- [ストレージバケット](./storage-buckets) · [アクセスパターン](./storage-buckets-access) · [統合](./storage-buckets-integrations)