ライブラリ

Datasets Hubは、オープンソースエコシステム内の複数のライブラリをサポートしています。 huggingface_hub Pythonライブラリのおかげで、Hubでのデータセットの共有を簡単に有効にできます。 機械学習を前進させる一連のオープンソースライブラリを、Hubに迎え入れることを嬉しく思います。

ライブラリ一覧

以下の表は、サポートされているライブラリとその統合レベルをまとめます。

* 最適化された Parquet ファイルを書き込むには、追加の引数を渡す必要があります

データ処理ライブラリ

ストリーミング

Dataset streamingは、Hugging Faceのデータを完全にダウンロードせずに、段階的に反復処理することを可能にします。 データがディスクに保存されないため、ローカルディスクの容量を節約できます。一度に使用されるのはデータセットのほんの一部であるため、メモリも節約できます。また、CPUやGPUの処理前にデータをダウンロードする必要がないため、時間の節約にもなります。

Hugging Faceからのストリーミングに加えて、多くのライブラリはHugging Faceへのストリーミングもサポートしています。 そのため、エンドツーエンドのストリーミングパイプラインを実行できます。ソースからストリーミングし、Hugging Faceへ段階的に書き込むことで、ダウンロード、アップロード、処理のステップをオーバーラップさせることがよくあります。

ストリーミングの具体的な方法については、ストリーミングをサポートするライブラリのドキュメント（上記の表を参照）を確認するか、Hugging Faceから独自にデータセットをストリーミングしたい場合は、ストリーミングデータセットのドキュメントを参照してください。

最適化された Parquet ファイル

Hugging Face上のParquetファイルは、ストレージ効率の向上、ダウンロードおよびアップロードの高速化、そして効率的なデータセットのストリーミングと編集を可能にするよう最適化されています。

最適化された Parquet ファイルは、追加の機能を持つ Parquet ファイルです:

• Parquet Content Defined Chunking は、Hugging Face のストレージバックエンドである Xet 向けに Parquet を最適化します。チャンクベースの重複排除によりアップロードとダウンロードが高速化され、効率的なファイル編集が可能になります。
• ページインデックスはストリーミング時のフィルタリングを高速化し、Dataset Viewer での効率的なランダムアクセスを可能にします。

PandasやPyArrowなどの一部のライブラリでは、Optimized Parquetファイルを書き出すために追加の引数が必要です:

• use_content_defined_chunking=True を設定して、重複排除および編集のために Parquet Content Defined Chunking を有効にします。
• write_page_index=True を設定すると、ストリーミングおよびランダムアクセスのために Parquet メタデータにページインデックスが含まれます。

トレーニングライブラリ

Hubのデータセットと統合し、モデルの学習を行うための学習ライブラリです。以下の表は、それらのストリーミング機能、すなわちデータセットを事前にダウンロードせずに学習できる能力を示しています。

* SFTTrainerとDPOTrainerはストリーミングをサポートしています。GRPOTrainerは現在、ストリーミング入力をサポートしていません。

Hubからのストリーミング

Streamingは、まずダウンロードせずに大規模なデータセットでトレーニングすることを可能にします。これは、次のような場合に価値があります：

• データセットが大きすぎてディスクに収まりません
• すぐにトレーニングを開始したい
• HF Jobsでは、同一場所に配置された計算リソースにより、より高速なストリーミングが実現されます。

最近の改善により、起動の高速化、プリフェッチ、および多数のワーカーへのスケーリングの向上により、ストリーミングが最大100倍効率的になりました。

注: ストリーミングでは、データセットの長さが不明であるため、トレーニング引数にmax_stepsが必要です。また、バッファベースのシャッフルを使用します。詳細はストリーミングデータセットを参照してください。

Hubへのログ記録

一部のツールは、トレーニング中にトレーニングデータをHubにストリーミングで送信できます:

• Trackio: 学習メトリクスをリアルタイムで Hub のデータセットにストリーミングします

Hubへのデータライブラリおよびツールの統合

このガイドは、Hugging Face Hub との統合を希望するデータライブラリやツールの開発者およびメンテナー向けに設計されています。データ処理ライブラリ、分析ツール、またはデータセットとの相互作用が必要なソフトウェアを構築している場合、このドキュメントが Hub 統合の実装に役立ちます。

このガイドでは、以下の内容について説明します。

• Hubからlibrary/toolにデータを読み込むための考えられるアプローチ
• ライブラリ/ツールからHubにデータをアップロードするための考えられるアプローチ

Hubからのデータ読み込み

データ処理用のライブラリをお持ちの場合は、ユーザーがHubからデータをロードできるようにすると便利です。

一般的には、独自の理由がない限り、datasets、pandas、polars などの既存のライブラリに依存することをお勧めします。読み込みプロセスに対してより細かな制御が必要な場合は、huggingface_hub ライブラリを使用できます。これにより、リポジトリから特定のファイルのサブセットをダウンロードするなど、より柔軟な操作が可能になります。

Hubからのデータ読み込みに関する詳細は、こちらをご覧ください。

Dataset ViewerおよびParquetファイルによる統合

HubのデータセットビューアとParquet変換システムは、元の形式に関係なく、データセットを統合するための標準的な方法を提供します。このインフラストラクチャは、Hubと外部ライブラリ間の信頼できる統合レイヤーです。

データセットがすでに Parquet 形式でない場合、Hub はデータセットビューワーを動作させ、一貫したアクセスパターンを提供するために、すべてのデータセットの最初の 5GB を自動的に Parquet 形式に変換します。この標準化により、ライブラリ統合においていくつかの利点があります。

• 元の形式に関係なく一貫したデータアクセスパターン
• Hubのデータセットビューアによる、組み込みのデータセットプレビューと探索。データセットビューアはiframeとしてアプリケーションに埋め込むこともでき、豊富なデータセットプレビューを簡単に提供できます。ビューアの埋め込みに関する詳細は、データセットビューアの埋め込みドキュメントを参照してください。
• クエリに最適化された効率的なカラムナーストレージです。例えば、DuckDBのようなツールを使用して、特定のデータサブセットをクエリしたりフィルタリングしたりできます。
• Parquetは、機械学習やデータサイエンスのエコシステム全体で広くサポートされています。

Dataset Viewer APIの使用方法の詳細については、Dataset Viewer APIのドキュメントを参照してください。

Hubへのデータのアップロード

このセクションでは、ライブラリにHubへのデータアップロード機能を追加するためのアプローチについて説明します。具体的には、push_to_hubメソッドを実装する方法です。

このガイドでは、Hubにデータをアップロードする主な3つの方法について説明します。

• datasets ライブラリとpush_to_hub メソッドを使用して
• pandasを使用してHubに書き込む
• huggingface_hub ライブラリとupload_folderメソッドを使用して

datasetsライブラリを使用します

Hubにデータをプッシュする最もシンプルなアプローチは、datasetsライブラリの既存のpush_to_hubメソッドに依存することです。push_to_hubメソッドは、以下を自動的に処理します:

• リポジトリの作成
• Parquetへのデータセットの変換
• データセットを適切な部分に分割すること
• データのアップロード

例えば、辞書のリストを返す合成データ生成ライブラリがある場合、次のようにすれば十分です。

from datasets import Dataset

data = [{"prompt": "Write a cake recipe", "response": "Measure 1 cup ..."}]
ds = Dataset.from_list(data)
ds.push_to_hub("USERNAME_OR_ORG/repo_ID")

この種の統合の例:

• Distilabel

Hubとの既存のライブラリ統合に依存する

Polars、Pandas、Dask、Spark、DuckDB、DaftはすべてHugging Face Hubのリポジトリに書き込むことができます。詳細は上記のライブラリ一覧表を参照してください。

これらのライブラリのいずれかをコードで既に使用している場合、Hubにプッシュする機能を追加するのは簡単です。例えば、PandasのDataFrameを返すことのできる合成データ生成ライブラリを持っている場合、Hubに書き込むために必要なコードは以下の通りです。

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi()

# Create a repository (if it doesn't exist)
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset", exist_ok=True)

# Convert your data to a DataFrame and save directly to the Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

huggingface_hub Pythonライブラリを使用する

huggingface_hub Python ライブラリは、Hub へのデータアップロードにおいてより柔軟なアプローチを提供します。このライブラリを使用すると、リポジトリに特定のファイルまたはファイルのサブセットをアップロードできます。これは、Parquet 形式に変換したくない大規模なデータセットを持っている場合、特定のファイルのサブセットをアップロードしたい場合、またはリポジトリの構造をより細かく制御したい場合に便利です。

ユースケースに応じて、コード内の特定の時点でファイルやフォルダをアップロードできます。つまり、ユーザーが「push to Hub」をクリックしたときに、ツールからアノテーションをHubにエクスポートする、といったことができます。例えば、

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/my-cool-library/data-folder",
    repo_id="username/my-dataset",
    repo_type="dataset",
    commit_message="Push annotations to Hub",
    allow_patterns="*.jsonl",
)

Hubにデータをアップロードする方法に関する詳細は、こちらをご覧ください。

また、バックグラウンドでデータをアップロードしたい状況もあります。例えば、10分ごとに生成される合成データなどが挙げられます。この場合、huggingface_hubライブラリのCommitSchedulerクラスを使用できます。詳細については、スケジュールアップロードのドキュメントを参照してください。

このアプローチを使用してデータをHubにアップロードする例を、

• fastdataライブラリ
• このmagpieデモスペース

追加のサポート

統合に関する技術的なご質問は、datasets@huggingface.coまでdatasetsチームへお気軽にお問い合わせください。