# Hugging Face データセットアップロード判断ガイド

> [!TIP]
> このガイドは主にLLM向けに設計されており、ユーザーがHugging Face Hubに最も互換性のある形式でデータセットをアップロードするのを支援します。ユーザーは、このガイドを参照してアップロードのプロセスやベストプラクティスについて理解することもできます。

> Hugging Face Hubへのデータセットアップロードに関する判断ガイド。Dataset Viewerとの互換性およびHugging Faceエコシステムとの統合を最適化しています。

> [!TIP]
> このガイドに従って操作している LLM またはエージェントの方は、アップロードコマンドを実行する前に、正確なフラグを確認するために `hf --help` および `hf <command> --help`（例: `hf upload --help`、`hf auth --help`）を参照してください。CLI はインストールされている `huggingface_hub` のバージョンに一致するため、記憶から想起したフラグよりも、その出力を優先してください。

## 概要

あなたの目標は、ユーザーがHugging Face Hubにデータセットをアップロードするのを支援することです。理想的には、データセットはDataset Viewer（したがって`load_dataset`関数）と互換性があり、簡単なアクセスと使いやすさを確保できる状態であるべきです。以下の基準を満たすことを目指してください。

| **基準**                       | 説明                                                                                                                                                                                                                                                                                                                                                                  | 優先度                                          |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **リポジトリの制限を遵守する**      | データセットが Hugging Face のファイルサイズ、リポジトリサイズ、ファイル数に関するストレージ制限に準拠していることを確認してください。具体的な制限については、以下の Critical Constraints セクションを参照してください。                                                                                                                                                                                               | 必須                                          |
| **Hub互換形式を使用する**     | 可能な限り Parquet 形式を使用してください（圧縮率が高く、豊富な型情報を持ち、大規模なデータセットに対応しています）。小規模なデータセット（数 GB 未満）の場合、JSON/JSONL または CSV が許容されます。小規模なデータセットにおける画像や音声には、リポジトリの制限を遵守しつつ、生ファイルが有効です。大規模なメディアコレクションには WebDataset（.tar）を使用してください。変換が現実的でない場合は、ドメイン固有の形式を使用できます。 | 望ましい                                           |
| **Dataset Viewerとの互換性**   | 自動 Dataset Viewer で動作するようにデータを構造化し、プレビューと簡単な探索を可能にします。通常、これはサポートされている形式の使用と適切なファイル構成を意味します。検証手順は、このガイドの後半で説明します。                                                                                                                                               | 望ましい                                           |
| **データを適切に整理する**         | Hubの慣例（train/testの分割など）に合致した論理的なフォルダ構造を使用してください。Configは、データセットの異なる設定を定義するために使用できます。これにより、人間による理解とデータの自動読み込みの両方が容易になります。                                                                                                                                             | 望ましい                                           |
| **適切なFeaturesを使用する**       | datasetsライブラリを使用する際は、適切なデータ処理とビューア機能を保証するために、正しいフィーチャータイプ（例: Image()、Audio()、ClassLabel()）を指定してください。これにより、タイプ固有の最適化とプレビューが有効になります。                                                                                                                                                        | 必要（datasetsライブラリを使用する場合）            |
| **非標準データセットのドキュメント化** | ハブ互換形式への変換が不可能で、カスタム形式の使用が必須となる場合は、リポジトリの制限を厳守し、データのダウンロードと読み込み方法について明確なドキュメントを提供してください。使用例や特別な要件も記載してください。                                                                                                          | datasets ライブラリが互換性がない場合、必須 |

## ファイルアクセスなしで動作する

ユーザーのファイルに直接アクセスできない場合（Webインターフェースなど）には、ユーザーにこれらのコマンドを実行してもらい、データセットを理解してもらいます。

**データセットの構造**:

```bash
# Show directory tree (install with: pip install tree or brew install tree)
tree -L 3 --filelimit 20

# Alternative without tree:
find . -type f -name "*.csv" -o -name "*.json" -o -name "*.parquet" | head -20
```

**ファイルサイズを確認する**:

```bash
# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/
```

**データ形式を確認する**:

```bash
# First few lines of CSV/JSON
head -n 5 data/train.csv

# Check image folder structure
ls -la images/ | head -10
```

**ファイル数のクイックカウント**:

```bash
# Count files by type
find . -name "*.jpg" | wc -l
```

## 重要な制約

**ストレージの制限**：

これらが[storage-limits](https://huggingface.co/docs/hub/storage-limits#repository-limitations-and-recommendations)と異なる場合、storage-limitsが優先されます。

```yaml
# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 500 # absolute hard stop per file
  recommended_file_size_gb: 200 # split larger files into chunks below this
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # recommended maximum; keep well below
  viewer_row_size_mb: 2 # approximate per-row viewer limit
  # No per-repo size limit: repo size counts against the account's storage quota
```

**人間が読める要約**:

- ファイルごと: 最大500GB、推奨200GB未満
- フォルダごと: <10k ファイル
- リポジトリごと: <100k ファイルを推奨
- アカウントのストレージ（パブリックおよびプライベート）はプランによって異なります。[ストレージプラン](https://huggingface.co/docs/hub/storage-limits#storage-plans)を参照してください。

現在のストレージプランとリポジトリの推奨事項については、https://huggingface.co/docs/hub/storage-limits を参照してください。

## データタイプ別のクイックリファレンス

| あなたのデータ                           | 推奨アプローチ                                                                                         | クイックコマンド                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| **CSV/JSONファイル**                  | 組み込みのローダーを使用（メモリマッピングにより任意のサイズに対応）                                                   | `load_dataset("csv", data_files="data.csv").push_to_hub("username/dataset")`                     |
| **フォルダ内の画像**               | 自動クラス検出には[imagefolder](https://huggingface.co/docs/datasets/en/image_load)を使用します          | `load_dataset("imagefolder", data_dir="./images").push_to_hub("username/dataset")`               |
| **オーディオファイル**                     | 自動的な整理に[audiofolder](https://huggingface.co/docs/datasets/en/audio_load)を使用します             | `load_dataset("audiofolder", data_dir="./audio").push_to_hub("username/dataset")`                |
| **動画ファイル**                     | 自動整理には[videofolder](https://huggingface.co/docs/datasets/en/video_load#videofolder)を使用します | `load_dataset("videofolder", data_dir="./videos").push_to_hub("username/dataset")`               |
| **PDFドキュメント**                   | テキスト抽出には[pdffolder](https://huggingface.co/docs/datasets/en/document_dataset#pdffolder)を使用します      | `load_dataset("pdffolder", data_dir="./pdfs").push_to_hub("username/dataset")`                   |
| **非常に大規模なデータセット（100GB以上）**    | `max_shard_size` を使用してメモリ使用量を制御します                                                                 | `dataset.push_to_hub("username/dataset", max_shard_size="5GB")`                                  |
| **多数のファイル / ディレクトリ (>10k)** | `upload_folder`/`hf upload` を使用します（大量のファイルや大容量ファイルのアップロードに対応）                                                             | `hf upload username/dataset ./data --repo-type=dataset` |
| **大規模メディアのストリーミング**           | 効率的なストリーミングのためのWebDataset形式                                                                    | Create .tar shards, then `hf upload`                                                 |
| **科学データ (HDF5、NetCDF)**  | Array機能付きでParquetに変換する                                                                       | [Scientific Data](#scientific-data)セクションを参照してください                                                  |
| **カスタム/プロプライエタリ形式**      | 変換が不可能な場合は、詳細にドキュメント化してください                                                                 | 包括的なREADME付きの`hf upload`                                                |

## アップロードワークフロー

0. ✓ 必要に応じて、**データセットの情報を収集**します:

   - データの種類は何ですか？（画像、テキスト、音声、CSV など）
   - どのように構成されていますか？（フォルダ構造、単一ファイル、複数ファイル）
   - おおよそのサイズはどのくらいですか？
   - ファイルの形式は何ですか？
   - 特別な要件はありますか？（例：ストリーミング、プライベートアクセス）
   - データセットを説明する既存のREADMEやドキュメントファイルを確認します

1. ✓ **認証**:
   - CLI: `hf auth login`
   - または、トークンを使用します: `HfApi(token="hf_...")` または `HF_TOKEN` 環境変数を設定します
2. ✓ **データ型を特定する**: 上記の[クイックリファレンス](#quick-reference-by-data-type)テーブルを確認してください
3. ✓ **アップロード方法を選択**:

   - **ハブ互換形式の小さなファイル（<1GB）**: [Hub UI](https://huggingface.co/new-dataset)を使用して、素早くアップロードできます
   - **組み込みローダーが利用可能**: ローダー + `push_to_hub()` を使用します（クイックリファレンステーブルを参照）
   - **大規模なデータセットまたは多数のファイル**: 大規模なアップロードに対応する`upload_folder` / `hf upload`（自動マルチコミット、再開可能）を使用します。
   - **カスタム形式**: 可能な場合はハブ互換形式に変換し、そうでない場合は詳細にドキュメント化します

4. ✓ **ローカルでテスト**（組み込みローダーを使用する場合）：

   ```python
   # Validate your dataset loads correctly before uploading
   dataset = load_dataset("loader_name", data_dir="./your_data")
   print(dataset)
   ```

5. ✓ **Hubにアップロード**:

   ```python
   # Basic upload
   dataset.push_to_hub("username/dataset-name")

   # With options for large datasets
   dataset.push_to_hub(
       "username/dataset-name",
       max_shard_size="5GB",  # Control memory usage
       private=True  # For private datasets
   )
   ```

6. ✓ **アップロードの確認**:
   - Dataset Viewerを確認してください: `https://huggingface.co/datasets/username/dataset-name`
   - 読み込みのテスト: `load_dataset("username/dataset-name")`
   - ビューワーでエラーが表示される場合は、[トラブルシューティング](#common-issues--solutions)セクションを確認してください。

## 一般的な変換パターン

組み込みのローダーがデータ構造に合わない場合は、datasetsライブラリを互換性レイヤーとして使用します。データをDatasetオブジェクトに変換し、`push_to_hub()`を使用することで、最大限の柔軟性とDataset Viewerとの互換性を確保できます。

### DataFrameから

pandas、polars、その他のデータフレームライブラリでデータを処理している場合は、直接変換できます:

```python
# From pandas DataFrame
import pandas as pd
from datasets import Dataset

df = pd.read_csv("your_data.csv")
dataset = Dataset.from_pandas(df)
dataset.push_to_hub("username/dataset-name")

# From polars DataFrame (direct method)
import polars as pl
from datasets import Dataset

df = pl.read_csv("your_data.csv")
dataset = Dataset.from_polars(df)  # Direct conversion
dataset.push_to_hub("username/dataset-name")

# From PyArrow Table (useful for scientific data)
import pyarrow as pa
from datasets import Dataset

# If you have a PyArrow table
table = pa.table({'data': [1, 2, 3], 'labels': ['a', 'b', 'c']})
dataset = Dataset(table)
dataset.push_to_hub("username/dataset-name")

# For Spark/Dask dataframes, see https://huggingface.co/docs/hub/datasets-libraries
```

## カスタム形式変換

組み込みのローダーがデータ形式に合わない場合は、以下の原則に従って Dataset オブジェクトに変換します。

### 設計原則

**1. 結合よりもワイド/フラットな構造を優先する**

- リレーショナルデータを単一の行にデノーマライズして、使いやすさを向上させます
- 各例にすべての関連情報を記載してください
- より大きく、かつ実用的なデータに比重を置く - Hugging Faceのインフラストラクチャは、高度な重複排除（XetHub）とParquetの最適化を使用して、冗長性を効率的に処理します

**2. 論理的なデータセットのバリエーションに設定ファイルを使用する**

- train/test/val の分割に加えて、データの異なるサブセットやビューに対して設定を使用します
- 各設定は、異なる機能やデータ構成を持つことができます
- 例: 言語固有の設定、タスク固有のビュー、データモダリティ

### 変換方法

**小規模なデータセット（メモリに収まるもの）- `Dataset.from_dict()`を使用します**：

```python
# Parse your custom format into a dictionary
data_dict = {
    "text": ["example1", "example2"],
    "label": ["positive", "negative"],
    "score": [0.9, 0.2]
}

# Create dataset with appropriate features
from datasets import Dataset, Features, Value, ClassLabel
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['negative', 'positive']),
    'score': Value('float32')
})

dataset = Dataset.from_dict(data_dict, features=features)
dataset.push_to_hub("username/dataset")
```

**大規模なデータセット（メモリ効率に優れた方法）- `Dataset.from_generator()`を使用する**：

```python
def data_generator():
    # Parse your custom format progressively
    for item in parse_large_file("data.custom"):
        yield {
            "text": item["content"],
            "label": item["category"],
            "embedding": item["vector"]
        }

# Specify features for Dataset Viewer compatibility
from datasets import Features, Value, ClassLabel, List
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['cat1', 'cat2', 'cat3']),
    'embedding': List(feature=Value('float32'), length=768)
})

dataset = Dataset.from_generator(data_generator, features=features)
dataset.push_to_hub("username/dataset", max_shard_size="1GB")
```

**ヒント**: 大規模なデータセットでは、ジェネレーターに limit を追加するか、作成後に `.select(range(100))` を使用して、まずサブセットでテストしてください。

### Using Configs for Dataset Variations

```python
# Push different configurations of your dataset
dataset_en = Dataset.from_dict(english_data, features=features)
dataset_en.push_to_hub("username/multilingual-dataset", config_name="english")

dataset_fr = Dataset.from_dict(french_data, features=features)
dataset_fr.push_to_hub("username/multilingual-dataset", config_name="french")

# Users can then load specific configs
dataset = load_dataset("username/multilingual-dataset", "english")
```

### マルチモーダル例

**テキスト + 音声（音声認識）**：

```python
def speech_generator():
    for audio_file in Path("audio/").glob("*.wav"):
        transcript_file = audio_file.with_suffix(".txt")
        yield {
            "audio": str(audio_file),
            "text": transcript_file.read_text().strip(),
            "speaker_id": audio_file.stem.split("_")[0]
        }

features = Features({
    'audio': Audio(sampling_rate=16000),
    'text': Value('string'),
    'speaker_id': Value('string')
})

dataset = Dataset.from_generator(speech_generator, features=features)
dataset.push_to_hub("username/speech-dataset")
```

**1つの例に複数の画像**:

```python
# Before/after images, medical imaging, etc.
data = {
    "image_before": ["img1_before.jpg", "img2_before.jpg"],
    "image_after": ["img1_after.jpg", "img2_after.jpg"],
    "treatment": ["method_A", "method_B"]
}

features = Features({
    'image_before': Image(),
    'image_after': Image(),
    'treatment': ClassLabel(names=['method_A', 'method_B'])
})

dataset = Dataset.from_dict(data, features=features)
dataset.push_to_hub("username/before-after-images")
```

**注**: テキストと画像の組み合わせでは、これを自動的に処理する metadata.csv を使用した ImageFolder の利用を検討してください。

## 必須機能

Featuresは、データセットの各カラムのスキーマとデータ型を定義します。正しいFeaturesを指定することで、以下が保証されます。

- 適切なデータ処理と型変換
- Dataset Viewerの機能（画像/音声プレビューなど）
- 効率的な保存と読み込み
- データ構造の明確なドキュメント

完全な機能のドキュメントについては、[Dataset Features](https://huggingface.co/docs/datasets/about_dataset_features)を参照してください。

### 機能タイプの概要

**基本型**:

- `Value`: スカラー値 - `string`、`int64`、`float32`、`bool`、`binary`、およびその他の数値型
- `ClassLabel`: 名前付きクラスを持つカテゴリデータ
- `Sequence`: 任意の機能型のリスト
- `LargeList`: 非常に大きなリスト用

**メディアタイプ**（Dataset Viewerのプレビューを有効にする）：

- `Image()`: さまざまな画像形式を処理し、PIL Imageオブジェクトを返します
- `Audio(sampling_rate=16000)`: 配列データと任意のサンプリングレートを持つ Audio
- `Video()`: 動画ファイル
- `Pdf()`: テキスト抽出付きのPDFドキュメント

**配列型**（テンソル/科学データ用）：

- `Array2D`、`Array3D`、`Array4D`、`Array5D`: 固定長または可変長の配列
- 例: `Array2D(shape=(224, 224), dtype='float32')`
- 最初の次元は、可変長の場合に`None`にできます

**翻訳の種類**:

- `Translation`: 固定された言語の翻訳ペア向け
- `TranslationVariableLanguages`: 言語ペアが異なる翻訳に

**注記**: 定期的に新しい機能タイプが追加されます。最新の情報については、ドキュメントをご確認ください。

## アップロード方法

**Datasetオブジェクト（push_to_hubを使用）**: datasetsライブラリを使用してデータをロード/変換した場合に使用します

```python
dataset.push_to_hub("username/dataset", max_shard_size="5GB")
```

**既存のファイル（`upload_folder` / `hf upload`を使用）**：Hub互換のファイル（Parquetファイルなど）がすでに準備・整理されている場合に使用します。

```python
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(folder_path="./data", repo_id="username/dataset", repo_type="dataset")
```

```bash
# Or from the CLI:
hf upload username/dataset ./data --repo-type=dataset
```

**重要**: アップロード前に、ファイルがリポジトリの制限を満たしていることを確認してください:

- ファイルアクセスがある場合は、フォルダ構造を確認してください。1つのフォルダに1万を超えるファイルが含まれていないことを確認します。
- ユーザーに確認を求めます:「ファイルはハブ互換形式（Parquet/CSV/JSON）で、適切に整理されていますか？」
- 非標準形式の場合、互換性を確保するために、まず Dataset オブジェクトへの変換を検討してください。

## 検証

**小さなフォーマット変更を検討する**: データが組み込みローダーの形式に近い場合は、軽微な変更を提案します:

- 列の名前を変更します（例: ImageFolder の場合、'filename' → 'file_name'）
- フォルダを再構成する（例：画像をクラス別のサブフォルダに移動する）
- 期待されるパターンに合わせてファイル名を変更します（例: 'data.csv' → 'train.csv'）

**アップロード前**:

- ローカルでテスト: `load_dataset("imagefolder", data_dir="./data")`
- 機能が正しく動作することを確認します:

  ```python
  # Test first example
  print(dataset[0])

  # For images: verify they load
  if 'image' in dataset.features:
      dataset[0]['image']  # Should return PIL Image

  # Check dataset size before upload
  print(f"Size: {len(dataset)} examples")
  ```

- metadata.csvにfile_name列があることを確認します
- 相対パスを検証し、先頭にスラッシュがないことを確認します
- フォルダ内のファイル数が10,000件を超えていないことを確認します

**アップロード後**:

- ビューワーを確認: `https://huggingface.co/datasets/username/dataset`
- 読み込みのテスト: `load_dataset("username/dataset")`
- 保持された特徴を確認します: `print(dataset.features)`

## 一般的な問題 → 解決策

| 問題                      | 解決策                             |
| -------------------------- | ------------------------------------ |
| "リポジトリが見つかりません"     | `hf auth login`を実行します          |
| メモリエラー              | `max_shard_size="500MB"` を使用します         |
| Dataset viewer が動作しません | 5〜10分待ってから、README.mdの設定を確認してください |
| 200GBを超えるファイル               | 小さなファイルに分割する             |
| "ファイルが見つかりません"           | メタデータに相対パスを使用する       |

## Dataset Viewerの設定

**注**: このセクションは、主に Hub に直接アップロードされたデータセット（UI、`upload_folder` または `hf upload` を通じて）を対象としています。`push_to_hub()` でアップロードされたデータセットでは、ビューアが通常自動的に設定されます。

### 自動検出が機能する場合

Dataset Viewerは標準的な構造を自動的に検出します:

- ファイル名: `train.csv`、`test.json`、`validation.parquet`
- `train/`、`test/`、`validation/` という名前のディレクトリ
- 区切り文字で名前を分割します: `test-data.csv` ✓ (`testdata.csv` ✗ は不可)

### 手動設定

カスタム構造の場合、README.md に YAML を追加します:

```yaml
---
configs:
  - config_name: default # Required even for single config!
    data_files:
      - split: train
        path: "data/train/*.parquet"
      - split: test
        path: "data/test/*.parquet"
---
```

複数の設定の例:

```yaml
---
configs:
  - config_name: english
    data_files: "en/*.parquet"
  - config_name: french
    data_files: "fr/*.parquet"
---
```

### 一般的なビューワーの問題

- **アップロード後にビューアが表示されない**: 処理に5〜10分かかる場合があります
- **「設定名エラー」**: `config_name`フィールドを追加（必須！）
- **ファイルが検出されませんでした**: 命名パターンを確認してください（区切り文字が必要です）
- **ビューアーが無効化されています**: README の YAML から `viewer: false` を削除してください

## クイックテンプレート

```python
# ImageFolder with metadata
dataset = load_dataset("imagefolder", data_dir="./images")
dataset.push_to_hub("username/dataset")

# Memory-efficient upload
dataset.push_to_hub("username/dataset", max_shard_size="500MB")

# Multiple CSV files
dataset = load_dataset('csv', data_files={'train': 'train.csv', 'test': 'test.csv'})
dataset.push_to_hub("username/dataset")
```

## ドキュメント

**コアドキュメント**: [データセットの追加](https://huggingface.co/docs/hub/datasets-adding) | [データセットビューア](https://huggingface.co/docs/hub/datasets-viewer) | [ストレージ制限](https://huggingface.co/docs/hub/storage-limits) | [アップロードガイド](https://huggingface.co/docs/datasets/upload_dataset)

## Dataset Cards

ユーザーに、以下の内容を含むデータセットカード（README.md）を追加するよう促してください：

- Dataset description and usage
- ライセンス情報
- 引用の詳細

詳細については、[Dataset Cards ガイド](https://huggingface.co/docs/hub/datasets-cards)を参照してください。

---

## 付録: 特殊ケース

### WebDatasetの構造

大規模なメディアデータセットのストリーミング処理には:

- 1〜5GBのtarシャードを作成します
- 一貫した内部構造
- `hf upload`でアップロード

### Scientific Data

- HDF5/NetCDF → Array機能を使用してParquetに変換
- 時系列 → Array2D(shape=(None, n))
- 複雑なメタデータ → JSON文字列として保存

### コミュニティリソース

非常に特殊な形式や、カスタム形式の場合:

- Hubで類似のデータセットを検索します: `https://huggingface.co/datasets`
- [Hugging Face Forums](https://discuss.huggingface.co/c/datasets/10)でアドバイスをご相談ください
- リアルタイムのサポートを受けるには、[Hugging Face Discord](https://hf.co/join/discord)に参加してください。
- 多くのドメイン固有の形式には、すでにHubにサンプルが存在します