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

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

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

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

概要

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

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

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

データセットの構造:

# 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

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

# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/

データ形式を確認する:

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

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

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

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

重要な制約

ストレージの制限：

これらがstorage-limitsと異なる場合、storage-limitsが優先されます。

# 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 を参照してください。

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

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

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

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

1. ✓ 認証:

   • CLI: hf auth login
   • または、トークンを使用します: HfApi(token="hf_...") または HF_TOKEN 環境変数を設定します

2. ✓ データ型を特定する: 上記のクイックリファレンステーブルを確認してください

3. ✓ アップロード方法を選択:

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

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

   コピーしました

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

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

   コピーしました

   # 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")
   • ビューワーでエラーが表示される場合は、トラブルシューティングセクションを確認してください。

一般的な変換パターン

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

DataFrameから

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

# 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()を使用します：

# 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()を使用する：

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

# 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")

マルチモーダル例

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

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つの例に複数の画像:

# 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を参照してください。

機能タイプの概要

基本型:

• 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ライブラリを使用してデータをロード/変換した場合に使用します

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

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

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

# 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")

• 機能が正しく動作することを確認します:

  コピーしました

  # 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)

一般的な問題 → 解決策

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 を追加します:

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

複数の設定の例:

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

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

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

クイックテンプレート

# 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")

ドキュメント

コアドキュメント: データセットの追加 | データセットビューア | ストレージ制限 | アップロードガイド

Dataset Cards

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

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

詳細については、Dataset 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でアドバイスをご相談ください
• リアルタイムのサポートを受けるには、Hugging Face Discordに参加してください。
• 多くのドメイン固有の形式には、すでにHubにサンプルが存在します