Hugging Face's logo

LeRobot documentation

データセット

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

データセット

LeRobotDatasetは、すべてのLeRobotスクリプトが読み書きする形式です。エピソードを認識し、動画の観測データをオンザフライでデコードし、Hugging Face Hubとの往復も可能です。

形式と一般的な操作についてはLeRobotDatasetの使用、移行については大規模データセットの移植、CLIについてはツールを参照してください。

LeRobotDataset

class lerobot.datasets.LeRobotDataset

< >

( repo_id: strroot: str | pathlib.Path | None = Noneepisodes: list[int] | None = Noneepisode_filter: collections.abc.Callable[[dict], bool] | None = Noneimage_transforms: collections.abc.Callable | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsedownload_videos: bool = Truevideo_backend: str | None = Nonereturn_uint8: bool = Falsedepth_output_unit: str = 'mm'batch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Noneencoder_threads: int | None = Nonestreaming_encoding: bool = Falseencoder_queue_maxsize: int = 30repo_type: str = 'dataset'token: str | bool | None = Nonevideo_decoder_cache_size: int | None = None )

add_frame

< >

( frame: dict )

パラメータ

  • frame — このフレームの機能名とその値をマッピングする辞書。 'task' キーを含める必要があります。Torch テンソルは numpy に変換されます。

例外

RuntimeError

  • RuntimeError — データセットが読み取り専用（writer が存在しない）の場合。

現在のエピソードバッファに1フレームを追加します。

DatasetWriter.add_frame に委譲します。データセットは書き込みモードである必要があります（create または resume によって作成されたもの）。

clear_episode_buffer

< >

( delete_images: bool = True )

パラメータ

  • delete_images — Trueの場合、現在のエピソード用にディスクに書き込まれた一時画像ファイルも削除します。

例外

RuntimeError

  • RuntimeError — データセットが読み取り専用（writer が存在しない）の場合。

…

DatasetWriter.clear_episode_bufferに委譲します。失敗または中断された録画エピソードを破棄する場合に便利です。

clear_image_transforms

< >

( )

視覚観察に適用されたtransformを削除します。

create

< >

( repo_id: strfps: intfeatures: dictroot: str | pathlib.Path | None = Nonerobot_type: str | None = Noneuse_videos: bool = Truetolerance_s: float = 0.0001image_writer_processes: int = 0image_writer_threads: int = 0video_backend: str | None = Nonebatch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Nonemetadata_buffer_size: int = 10streaming_encoding: bool = Falseencoder_queue_maxsize: int = 30encoder_threads: int | None = Nonevideo_files_size_in_mb: int | None = Nonedata_files_size_in_mb: int | None = None )

パラメータ

  • repo_id — リポジトリの識別子。通常は'{hf_user}/{dataset_name}'の形式です。
  • fps — データ収集時に使用される秒あたりのフレーム数。
  • features — 特徴量名をその型/形状メタデータにマッピングする、特徴量仕様辞書。
  • root — データセットの保存に使用するローカルディレクトリ。デフォルトは $HF_LEROBOT_HOME/{repo_id} です。
  • robot_type — メタデータに保存される任意のロボットタイプ文字列。
  • use_videos — Trueの場合、視覚モダリティはMP4動画として保存されます。 Falseの場合、画像として保存されます。
  • tolerance_s — タイムスタンプ同期の許容誤差（秒）。
  • image_writer_processes — 非同期の画像書き込み用のサブプロセス数。0 はスレッドのみを使用することを意味します。
  • image_writer_threads — 非同期画像書き込み用のスレッド数。
  • video_backend — 動画デコードのバックエンド（読み戻し時に使用されます）。
  • batch_encoding_size — 動画をバッチエンコードする前に蓄積するエピソード数。1 は即座にエンコードすることを意味します。
  • rgb_encoder — カメラ用のビデオエンコーダー設定（コーデック、品質など）。 Noneの場合、rgb_encoder_defaults()が使用されます。
  • depth_encoder — 深度カメラ用のビデオエンコーダー設定（コーデック、品質など）。 Noneの場合、depth_encoder_defaults()が使用されます。
  • encoder_threads — エンコーダーのスレッド数（グローバル）。None の場合、コーデックが決定します。
  • metadata_buffer_size — parquet にフラッシュする前にバッファリングするエピソードメタデータレコードの数
  • streaming_encoding — Trueの場合、画像を先に書き出すのではなく、キャプチャ中にリアルタイムで動画フレームをエンコードします。
  • encoder_queue_maxsize — ストリーミングエンコーディングを使用する場合の、カメラごとのバッファリングされるフレームの最大数。

データの記録用に、LeRobotDatasetをゼロから新規作成します。

アクティブなDatasetWriterを備えた書き込みモードのデータセットを返します。add_frame / save_episodeを使用してデータを格納し、完了したらfinalizeを呼び出します。

finalize

< >

( )

保留中のすべての作業をフラッシュし、ライターを閉じます。

データ収集/変換の後に呼び出す必要があります。そうしないと、フッターのメタデータがparquetファイルに書き込まれず、データセットが無効になります。

冪等性 — 複数回呼び出しても安全です。 DatasetWriter.del は、明示的に呼び出されない場合の安全策として機能します。

get_raw_item

< >

( idx )

画像変換を適用せずに生フレームを取得します。

__getitem__とは異なり、このメソッドは指定されたインデックスの生のHFデータセット行を、デルタタイムスタンプの展開、動画のデコード、画像変換なしで返します。

has_pending_frames

< >

( )

エピソードバッファに未保存のフレームがあるかどうかを確認します。

push_to_hub

< >

( branch: str | None = Nonetags: list | None = Nonelicense: str | None = 'apache-2.0'tag_version: bool = Truepush_videos: bool = Trueprivate: bool | None = Noneallow_patterns: list[str] | str | None = Noneupload_large_folder: bool = False**card_kwargs )

パラメータ

  • branch — 対象のブランチ（任意）。存在しない場合は、現在のリビジョンから作成されます。
  • tags — データセットカード用のタグの任意のリスト。
  • license — データセットカードのライセンス識別子。
  • tag_version — Trueの場合、現在のコードベースのバージョンに対してGitタグを作成します。
  • push_videos — Falseの場合、videos/ディレクトリのアップロードをスキップします。
  • private — Trueの場合、プライベートリポジトリを作成します。None（デフォルト）の場合、Hub上の組織のデフォルトに従います（組織にのみ影響します）。
  • allow_patterns — アップロードするファイルを制限する Glob パターン。
  • upload_large_folder — 後方互換性のために残されていますが、無視されます。 upload_folder がすべてのサイズのデータセットを処理します。
  • **card_kwargs — データセットカードの作成に転送される追加のキーワード引数。

データセットを Hugging Face Hub にアップロードします。

リポジトリが存在しない場合は作成し、すべてのデータセットファイルをアップロードします（オプションで動画を除外可能）。その後、データセットカードを生成し、リビジョンに現在のコードベースのバージョンをタグ付けします。

再開

< >

( repo_id: strroot: str | pathlib.Path | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsevideo_backend: str | None = Nonebatch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Noneencoder_threads: int | None = Noneimage_writer_processes: int = 0image_writer_threads: int = 0streaming_encoding: bool = Falseencoder_queue_maxsize: int = 30token: str | bool | None = None )

パラメータ

  • repo_id — 既存のデータセットのリポジトリ識別子。
  • root — データセットのローカルディレクトリ。指定された場合、Hubからのダウンロードは直接このディレクトリに展開されます。省略された場合、Hubからのダウンロードは$HF_LEROBOT_HOME/hub配下のリビジョン安全なスナップショットキャッシュを使用します。
  • tolerance_s — タイムスタンプ同期の許容誤差（秒）。
  • revision — Git のリビジョン（ブランチ、タグ、またはコミットハッシュ）。デフォルトでは、現在のコードベースのバージョンタグが使用されます。
  • force_cache_sync — Trueの場合、ローカルキャッシュが存在していても、Hubからメタデータを再ダウンロードします。
  • video_backend — データの読み戻しに使用する動画デコードバックエンド。
  • batch_encoding_size — 動画をバッチエンコードする前に蓄積するエピソード数。
  • rgb_encoder — カメラ用のビデオエンコーダー設定（コーデック、品質など）。 Noneの場合、rgb_encoder_defaults()が使用されます。
  • depth_encoder — 深度カメラ用のビデオエンコーダー設定（コーデック、品質など）。 Noneの場合、depth_encoder_defaults()が使用されます。
  • encoder_threads — エンコーダーのスレッド数（グローバル）。None の場合、コーデックが決定します。
  • image_writer_processes — 非同期の画像書き込み用のサブプロセス。
  • image_writer_threads — 非同期の画像書き込み用のスレッド数。
  • streaming_encoding — Trueの場合、キャプチャ中にリアルタイムで動画をエンコードします。
  • encoder_queue_maxsize — ストリーミングにおけるカメラごとのバッファリングされるフレームの最大数。
  • token — メタデータを Hub からダウンロードする必要がある場合に使用される認証トークン。このトークンはデータセットインスタンスに保持されません。

既存のデータセットで記録を再開します。

既存のデータセット（ローカルまたはHub）からメタデータを読み込み、新しいエピソードを追加するためのDatasetWriterを作成します。基盤となるHFデータセットは、finalizeが呼び出されてからデータが読み込まれるまで、読み込まれません。

save_episode

< >

( episode_data: dict | None = Noneparallel_encoding: bool = True )

パラメータ

  • episode_data — 任意の事前構築済みエピソード辞書。None の場合、add_frame によって埋められた内部エピソードバッファを使用します。
  • parallel_encoding — Trueの場合、複数のカメラが存在するときは、プロセスプールを使用して動画を並列でエンコードします。

例外

RuntimeError

  • RuntimeError — データセットが読み取り専用（writer が存在しない）の場合。

現在のエピソードバッファをディスクに保存します。

DatasetWriter.save_episode に委譲します。動画をエンコードし、parquet データを書き込み、メタデータを更新します。その後、エピソードバッファはリセットされます。

select_columns

< >

( column_names: str | list[str] )

ベースとなるデータセットから特定の列を選択します。

リプレイ中のアクションシーケンスを抽出する際に有用です。すべての特徴を読み込む必要がありません。 要求されたカラムのみを含むdatasets.Datasetを返します。

set_image_transforms

< >

( image_transforms: collections.abc.Callable | None )

視覚観察に適用されるtransformを置き換えます。

LeRobotDatasetMetadata

class lerobot.datasets.LeRobotDatasetMetadata

< >

( repo_id: strroot: str | pathlib.Path | None = Nonerevision: str | None = Noneforce_cache_sync: bool = Falsemetadata_buffer_size: int = 10repo_type: typing.Literal['dataset', 'bucket'] = 'dataset'token: str | bool | None = None )

LeRobotデータセットのメタデータコンテナ。

データセットの構造、内容、統計情報を記述するinfo.json、stats.json、tasks.parquet、およびepisodes/のparquetファイルを管理します。

create

< >

( repo_id: strfps: intfeatures: dictrobot_type: str | None = Noneroot: str | pathlib.Path | None = Noneuse_videos: bool = Truemetadata_buffer_size: int = 10chunks_size: int | None = Nonedata_files_size_in_mb: int | None = Nonevideo_files_size_in_mb: int | None = None )

パラメータ

  • repo_id — リポジトリの識別子（例: 'user/my_dataset'）。
  • fps — データ収集時に使用される秒あたりのフレーム数。
  • features — 特徴量名をその型/形状メタデータにマッピングする、特徴量仕様辞書。
  • robot_type — メタデータに保存される任意のロボットタイプ文字列。
  • root — データセット用のローカルディレクトリ。デフォルトは $HF_LEROBOT_HOME/{repo_id} です。既存のディレクトリであってはなりません。
  • use_videos — Trueの場合、視覚モダリティはMP4動画としてエンコードされます。
  • metadata_buffer_size — parquet にフラッシュする前にバッファリングするエピソードメタデータレコードの数
  • chunks_size — チャンクディレクトリあたりのファイル数の上限。None を指定すると、デフォルト値が使用されます。
  • data_files_size_in_mb — parquet ファイルの最大サイズ（MB）。None の場合はデフォルト値が使用されます。
  • video_files_size_in_mb — 動画ファイルの最大サイズ（MB）。None の場合はデフォルト値が使用されます。

ゼロから新しいLeRobotデータセットのメタデータを作成します。

提供された機能スキーマとデータセット設定に基づいて、ディスク上のinfo.jsonファイルを初期化します。エピソードデータはまだ書き込まれません。

ensure_readable

< >

( )

読み取り操作のためにメタデータが完全に読み込まれていることを保証します。

冪等性 — メタデータがすでにメモリ内にある場合、これは単なるis Noneチェックです。同じインスタンスで書き込みモードから読み取りモードに移行する前に、これを呼び出してください。

filter_episodes

< >

( predicate: Callablecandidates: list[int] | None = None )

パラメータ

  • predicate — エピソードの選択に使用する、エピソードごとのメタデータ行に対する述語。
  • candidates — 評価を特定のエピソードに限定するための、エピソードのインデックスの任意のリスト。

与えられた述語を満たすメタデータを持つエピソードをフィルタリングします。

finalize

< >

( )

メタデータバッファをフラッシュし、parquetライターを閉じます。

冪等性 — 複数回呼び出しても安全です。

get_chunk_settings

< >

( )

現在のチャンクとファイルサイズの設定を取得します。

get_data_file_path

< >

( ep_index: int )

パラメータ

  • ep_index — 0 始まりのエピソードインデックス。

例外

IndexError

  • IndexError — ep_index が範囲外の場合。

指定されたエピソードインデックスの相対的なparquetファイルパスを返します。

get_task_index

< >

( task: str )

自然言語で与えられたタスクについて、そのタスクがデータセットに既に存在する場合はそのtask_indexを返し、存在しない場合はNoneを返します。

get_video_file_path

< >

( ep_index: intvid_key: str )

パラメータ

  • ep_index — 0 始まりのエピソードインデックス。
  • vid_key — 動画ストリームを識別する特徴量キー（例: 'observation.images.laptop'）。

例外

IndexError または ValueError

  • IndexError — ep_index が範囲外の場合。
  • ValueError — データセットに動画が保存されていない場合（video_path テンプレートがない場合）。

指定されたエピソードとビデオキーの相対ビデオファイルパスを返します。

rescale_depth_stats

< >

( output_unit: str )

output_unit に、記録された単位から深度特徴量統計をインプレースで再スケーリングします。

Depth statsは、フレームが記録された単位(features[key]["info"]["depth_unit"])で保存されますが、読み取り時にはoutput_unitでフレームが返されます。これにより、単位を持つ統計エントリが変換され、統計値が消費者が見るフレームと一致するようになります。

save_episode

< >

( episode_index: intepisode_length: intepisode_tasks: listepisode_stats: dictepisode_metadata: dict )

パラメータ

  • episode_index — 保存対象のエピソードのゼロ始まりのインデックス。
  • episode_length — このエピソードのフレーム数。
  • episode_tasks — このエピソードのタスク説明のリスト。
  • episode_stats — このエピソードの機能ごとの統計情報。
  • episode_metadata — 追加のメタデータ（チャンク/ファイルのインデックス、フレーム範囲、動画のタイムスタンプなど）。

エピソードのメタデータを永続化し、データセット情報を更新して、統計情報を集計します。

エピソードのメタデータをバッファリングされた parquet writer に書き込み、info.json 内のエピソード/フレームの合計カウンターをインクリメントし、エピソードの統計情報を実行中のデータセット統計にマージします。

save_episode_tasks

< >

( tasks: list )

パラメータ

  • tasks — 自然言語で記述された固有のタスクの説明のリスト。

例外

ValueError

  • ValueError — tasks に重複が含まれている場合。

現在のエピソードのタスクを登録し、ディスクに永続化します。

データセットにまだ存在しない新しいタスクには、連続するタスクインデックスが割り当てられ、タスクのparquetファイルに追加されます。

update_chunk_settings

< >

( chunks_size: int | None = Nonedata_files_size_in_mb: int | None = Nonevideo_files_size_in_mb: int | None = None )

パラメータ

  • chunks_size — チャンクディレクトリあたりのファイル数の上限。None の場合は、現在の値を維持します。
  • data_files_size_in_mb — データのparquetファイルの最大サイズ（MB単位）。Noneの場合、現在の値を維持します。
  • video_files_size_in_mb — 動画ファイルの最大サイズ（MB）。None の場合は現在の値を維持します。

Update chunk and file size settings after dataset creation.

これにより、ユーザーはコンストラクタを変更せずにストレージの構成をカスタマイズできます。 これらの設定は、エピソードがどのようにチャンク化されるか、および新しいファイルが作成される前にファイルがどの程度大きくなってもよいかを制御します。

update_video_info

< >

( video_key: str | None = Nonevideo_encoder: lerobot.configs.video.VideoEncoderConfig | None = Nonepreserve_keys: collections.abc.Iterable[str] | None = None )

パラメータ

  • video_key — 指定された場合、この video key のみを更新します。指定されなかった場合は、データセット内のすべての video key を更新します。
  • video_encoder — 動画の生成に使用されるエンコーダーの設定です。指定された場合、そのフィールドは、ストリームから派生したvideo.*エントリ（get_video_infoを参照）と並んで、video.<field>エントリとして記録されます。
  • preserve_keys — 再計算せず、既存の値を保持するキー。None（デフォルト）の場合、すべてのキーが再計算されます。

info.json内の機能ごとの動画情報を設定または更新します。

警告: この関数は最初のエピソードの動画から情報を書き込み、すべての動画が同じ方法でエンコードされていることを暗黙に前提としています。また、最初のエピソードが存在することを前提としています。

preserve_keys に列挙されたキー（is_depth_map や深度量子化パラメータなどのデータ固有のエントリなど）は再計算されず、既存の値が保持されます。それ以外のキーについては、常に動画を再プローブし、再計算されたキーの既存情報を上書きします。

MultiLeRobotDataset

class lerobot.datasets.MultiLeRobotDataset

< >

( repo_ids: listroot: str | pathlib.Path | None = Noneepisodes: dict | None = Noneimage_transforms: collections.abc.Callable | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerances_s: dict | None = Nonedownload_videos: bool = Truevideo_backend: str | None = Nonetoken: str | bool | None = None )

複数のLeRobotDatasetで構成されるデータセット。

基盤となるLeRobotDatasetは実質的に連結されており、このクラスはLeRobotDatasetのAPI構造の多くを踏襲しています。

clear_image_transforms

< >

( )

このデータセットとその子からtransformを削除します。

set_image_transforms

< >

( image_transforms: collections.abc.Callable | None )

このデータセットとその子要素のtransformを置き換えます。

StreamingLeRobotDataset

クラス lerobot.datasets.StreamingLeRobotDataset

< >

( repo_id: strroot: str | pathlib.Path | None = Noneepisodes: list[int] | None = Noneimage_transforms: collections.abc.Callable[[torch.Tensor], torch.Tensor] | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsestreaming: bool | None = Nonebuffer_size: int = 1000max_num_shards: int = 16seed: int = 42rng: numpy.random._generator.Generator | None = Noneshuffle: bool = Truereturn_uint8: bool = Falsedepth_output_unit: str = 'mm'video_backend: str | None = Nonedata_root: str | pathlib.Path | None = Noneepisode_pool_size: int | None = Noneprefetch_episodes: int = 8byte_budget_gb: float = 8.0repeat: bool = Falserepo_type: typing.Literal['dataset', 'bucket'] = 'dataset'token: str | bool | None = Nonedecode_threads: int = 2decoded_queue_size: int = 8video_decoder_cache_size: int | None = Nonenative_http_connections: int | None = Nonenative_http_subranges: int = 1sidecar_lock_timeout_s: float = 1800sampling_strategy: lerobot.streaming.episode_pool.StreamingSamplingStrategy | str = <StreamingSamplingStrategy.REMAINING: 'remaining'> )

LeRobotデータセット用のエピソードスコープのストリーミングリーダー。

メタデータはローカルにキャッシュされ、各ランクは自分が担当する完全なエピソードに必要なParquetの行とMP4のバイト範囲のみを読み取ります。N個のDataLoaderワーカーがある場合、各ワーカーはランクのエピソードのうち、フレーム数がバランスの取れた互いに重複しない部分を担当し、独自のエピソードプールとバイト予算の1/Nを保持します。各プロセスは独自のPython GILを持つため、N個のワーカーが並行してサンプルのデコードと組み立てを行います。エピソードの所有権は互いに重複せず、選択された各フレームはイテレーションごとに正確に1回のみ生成されます。MP4のサイドカーは自動的に解決され、存在しない場合はリビジョンをキーとするローカルキャッシュに構築されます。

例:

基本的な使用方法:

from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset

# Create a streaming dataset with delta timestamps
delta_timestamps = {
    "observation.image": [-1.0, -0.5, 0.0],  # 1 sec ago, 0.5 sec ago, current
    "action": [0.0, 0.1, 0.2],  # current, 0.1 sec future, 0.2 sec future
}

dataset = StreamingLeRobotDataset(
    repo_id="your-dataset-repo-id",
    delta_timestamps=delta_timestamps,
)

# Iterate over the dataset
for i, item in enumerate(dataset):
    print(f"Sample {i}: Episode {item['episode_index']} Frame {item['frame_index']}")
    # item will contain stacked frames according to delta_timestamps
    if i >= 10:
        break

load_state_dict

< >

( state: dict )

パラメータ

  • state (dict[str, int]) — Rankローカルなエポック、サンプルオフセット、バッチサイズ。欠落しているキーはデフォルトでそれぞれ 0、0、1 になります。

例外

ValueError

  • ValueError — エポックまたはオフセットが負の場合、またはバッチサイズが正でない場合に発生します。

スキップされたサンプルを取得せずに、次のイテレーターのアンカー位置を復元します。

Note: アンカー順序の再現には、同じデータセット、シード、サンプラー、プール設定、分散トポロジー、およびDataLoaderワーカー数が必要です。複数のワーカーを使用する場合、オフセットはbatch_sizeのバッチ単位でのランクのオフセットです。DataLoaderがワーカーから順番にバッチを取得するため、各ワーカーは自分の部分を独自に導出します。ランダムな画像変換はこの方法では復元されません。

num_episodes_for_rank

< >

( rank: intworld_size: int )

1つのトレーニングランクが所有するエピソードの整数個数を返します。

num_frames_for_rank

< >

( rank: intworld_size: intnum_workers: int )

バランスの取れたエピソード全体シャーディングの下で、1つのトレーニングランクが所有するフレームを返します。

set_data_parallel_shard

< >

( rank: intworld_size: int )

torch.distributedおよび環境の処理に先立ち、データ並列ランクとワールドサイズを固定します。

spawnされたDataLoaderワーカーには初期化されたtorch.distributedが存在せず、値はpicklingによって渡されます。

set_epoch

< >

( epoch: int )

パラメータ

  • epoch (int) — シャッフルが有効な場合、次のサンプル計画のシードとして使用されるカバレッジエポック。

例外

ValueError

  • ValueError — epoch が負の値の場合。

非負のepochを選択し、ランクローカルの再開オフセットをリセットします。

state_dict

< >

( ) → dict[str, int]

戻り値

dict[str, int]

エポック、生成サンプルのオフセット、および再開時のバッチサイズ。

イテレータの現在のランクローカル位置を返します。

Note: DataLoaderのプリフェッチを使用すると、生成されたサンプルがまだトレーニングによって消費されていない可能性があります。 トレーニングパイプラインは、完了したステップからその位置を復元します。複数の DataLoaderワーカーを使用する場合、各ワーカープロセスは自身の位置のみを保持します。

Update on GitHub

←モーター ポリシー→