Streaming Dataset Pelatihan

Streaming dataset saat pelatihan memungkinkan lerobot-train mengonsumsi LeRobotDataset v3 tanpa terlebih dahulu mengunduh seluruh payload Parquet dan videonya. Aktifkan melalui saklar publik yang sudah ada:

lerobot-train \
  --dataset.repo_id=OWNER/DATASET \
  --dataset.streaming=true \
  --policy.type=act \
  --output_dir=outputs/train/act_streaming

Fitur ini independen dari --dataset.streaming_encoding=true. streaming_encoding mengontrol bagaimana video ditulis saat perekaman; dataset.streaming mengontrol bagaimana dataset yang sudah ada dibaca selama pelatihan. Encoder perekaman dan rollout tidak digunakan oleh jalur pelatihan ini.

Cara sebuah epoch dibaca

Setiap rank distribusi memiliki kumpulan episode lengkap yang deterministik dan seimbang per frame. Satu pool cakupan-eksak per worker DataLoader mencampur bagian worker dari episode-episode tersebut sambil mengunjungi setiap frame yang dipilih sekali per epoch cakupan. Kolom Parquet dan rentang byte MP4 terkompresi diprefetch dari frontier penerimaan yang sama yang sadar byte. Jendela riwayat temporal dan masa depan diselesaikan di dalam episode lengkap, termasuk mask padding batas yang sama seperti pemuatan gaya peta.

Perilaku LeRobotDataset bergaya peta secara default tidak berubah ketika --dataset.streaming=false.

Worker, shard, dan konkurensi

Setiap rank memiliki shard yang seimbang frame dari episode lengkap. Di dalam sebuah rank, --num_workers mengatur jumlah proses worker DataLoader, sama seperti pada dataset bergaya map. Setiap worker memiliki bagian yang tidak tumpang tindih dan seimbang frame dari episode rank tersebut, dengan pool cakupan persis miliknya sendiri, bagiannya sendiri dari anggaran byte, dan pool thread miliknya sendiri:

Mengapa beberapa worker. Perakitan sampel dan penyerahan batch menjalankan kode Python, dan satu proses hanya menjalankan kode Python di satu thread pada satu waktu (GIL). Dengan satu worker, thread decode dari sebuah rank saling menunggu, sehingga rank tersebut hanya menggunakan sekitar 2 core CPU. Setiap worker adalah proses terpisah, sehingga N worker merakit dan mendekode sampel secara paralel.

Ukuran pool dan keragaman batch. streaming_episode_pool_size mengatur pool untuk setiap worker. Jika Anda tidak mengaturnya, rank akan mencampur 32 episode dan masing-masing dari N worker akan menerima 32/N dari episode tersebut. Setiap worker juga melakukan prefetch streaming_prefetch_episodes episode dan merupakan proses Python yang terpisah, sehingga semakin banyak worker, semakin banyak memori yang digunakan: pada satu dataset dengan 3 kamera, 4 worker menggunakan sekitar 8 GB secara total, dibandingkan sekitar 3 GB dengan satu worker. DataLoader mengambil setiap batch dari satu worker, sehingga satu batch mencampur episode dari pool satu worker. Pool yang lebih besar akan mencampur lebih banyak episode dalam setiap batch, tetapi menggunakan lebih banyak memori dan mengambil lebih banyak data sebelum sampel pertama.

Batasan. Anggaran byte (streaming_byte_budget_gb) dan video_decoder_cache_size yang eksplisit tetap per rank: setiap worker menerima 1/N dari keduanya. Karena satu worker membutuhkan setidaknya satu episode, lerobot-train menggunakan jumlah worker yang tidak melebihi jumlah episode pada rank tersebut. --num_workers=0 menjaga dataset tetap berada di proses pelatihan. Di sana, thread pelatihan menerapkan transformasi gambar, sehingga --seed yang sama menghasilkan transformasi yang sama.

Sidecar MP4 dan eksekusi pertama

Streaming video menggunakan sidecar indeks MP4. Inisialisasi dataset pertama-tama memeriksa cache lokal yang berdasar revisi, kemudian mencari sidecar terbitan yang valid. Jika keduanya tidak tersedia, LeRobot membangun sidecar secara lokal sambil memegang kunci proses dan memasangnya secara atomik. Bangunan yang gagal atau terputus tidak menggantikan file valid sebelumnya. Proses lain yang membutuhkan sidecar yang sama menunggu kunci hingga --dataset.streaming_sidecar_lock_timeout_s (30 menit secara default). Naikkan nilai ini untuk dataset besar yang membutuhkan waktu lebih lama untuk diindeks.

Pembacaan payload Hub dikunci ke commit snapshot metadata. Indeks Bucket diperiksa terhadap daftar objek terbaru, termasuk hash konten, sehingga penggantian video di path yang sama akan membatalkan sidecar-nya meskipun ukuran file tidak berubah. Daftar ini menambah pekerjaan saat startup, tetapi tidak mengunduh payload video. Pertahankan metadata dan payload tetap tidak berubah selama eksekusi. Filesystem remote generik tanpa identitas objek yang stabil akan membangun ulang indeksnya setiap kali dibuka. Sidecar Bucket yang ada tanpa sidik jari objek akan dibangun ulang secara lokal sekali; penerbitan sidecar yang diperbarui tetap merupakan tindakan eksplisit oleh maintainer.

Pelatihan bersifat hanya-baca: tidak pernah mengunggah sidecar atau memodifikasi repositori dataset. Pada klaster dengan cache lokal per node, pekerjaan pertama mungkin membangun sekali per node. Cache LeRobot bersama menghindari duplikasi tersebut.

Konstruksi sidecar menulis setiap indeks sumber yang selesai ke dalam arsip sementara. Proses ini mempertahankan hasil parsing sebanyak jumlah yang dikonfigurasi. Memori array bergantung pada sumber konkuren terbesar; metadata arsip tetap bertambah seiring jumlah sumber. Gunakan --workers untuk mengatur konkurensi parsing saat Anda menjalankan lerobot-build-mp4-sidecar. Jika build gagal, sidecar sebelumnya tetap dipertahankan.

Arsip NPZ skema-3 yang diterbitkan mempertahankan array integer int64 kanonik. Pembukaan pertama mengonversi arsip menjadi indeks memory-mapped hanya-baca di bawah $HF_LEROBOT_HOME/streaming-indexes. Indeks turunan menggunakan tipe integer eksak terkecil. Ia menyimpan durasi konstan, offset komposisi, ukuran, atau offset byte sekali. Tampilan array hanya-baca mempertahankan jumlah sampel logis. Timestamp presentasi mempertahankan nilai float64 eksak. Array sampel sinkron mempertahankan penyimpanan padat.

Indeks turunan menggunakan generasi cache yang terpisah. Pembaca versi lama mempertahankan format cache yang ada. Pembukaan pertama dengan pembaca baru dapat mengonversi arsip sekali; pembukaan berikutnya akan menggunakannya kembali. Konversi menggunakan kunci proses dan penggantian atomik. Rank yang berbagi cache menggunakan halaman berbasis file yang sama. Setiap rank hanya membangun rekaman untuk file sumber yang digunakan oleh episodenya. Generasi cache lama dan baru dapat memerlukan ruang disk tambahan. Penggantian sidecar membuat generasi immutable baru tanpa membatalkan pembaca yang aktif.

Hal ini tidak membuat semua metadata berukuran konstan: metadata episode dan tabel span masih bertambah seiring dengan dataset, dan shard rank yang diacak dapat menyentuh file sumber yang tumpang tindih. Halaman yang dipetakan dan berada di memori OS juga dihitung ke dalam RSS; gunakan proportional set size (PSS) saat mengukur memori yang dibagikan oleh rank. Pembaca Parquet memangkas grup baris menggunakan statistik episode dan kemudian memfilter ke episode yang lengkap. Grup tanpa statistik tetap menjadi kandidat, sehingga file tanpa batas yang berguna masih dapat memerlukan pembacaan proyeksi seluruh file.

Pemelihara dataset dapat membangun sidecar sebelumnya:

lerobot-build-mp4-sidecar \
  --repo-id=OWNER/DATASET \
  --revision=COMMIT_SHA \
  --data-root=hf://datasets/OWNER/DATASET@COMMIT_SHA \
  --output=/tmp/dataset-mp4-sidecar.npz

Publikasi selalu bersifat eksplisit. Tambahkan --push hanya setelah memvalidasi sidecar dataset lengkap. Sidecar subset tidak dapat dipublikasikan.

Untuk repositori dataset, --push membuat atau memperbarui cabang khusus lerobot-sidecars. Cabang/tag dataset sumber tidak berubah. Pelatihan mencari indeks yang dikunci ke commit sumber video yang di-pin di sana dan memvalidasinya sebelum digunakan. Tag dan commit yang di-resolve-nya berbagi indeks publikasi yang sama; cache lokal yang sudah ada dan berdasar revisi tetap dapat digunakan kembali. Bucket masih mempublikasikan langsung di bawah meta/mp4-sidecars/. Publikasi memerlukan akses tulis ke repositori atau bucket; pelatihan hanya memerlukan akses baca dan tidak pernah membuat cabang atau mengunggah file.

Skema sidecar v3 mempertahankan waktu komposisi MP4 dan pengeditan delay encoder, termasuk video B-frame. Sidecar yang lebih lama dibangun ulang secara otomatis ke entri cache terpisah yang berdasar kunci revisi; sidecar tersebut juga harus dibangun ulang sebelum publikasi eksplisit. Video yang diurutkan ulang mencakup akhir GOP terakhir di setiap span yang diambil sehingga indeks frame yang didekode tetap berurutan. Garis waktu pengeditan MP4 yang berulang atau non-unit-rate ditolak, bukan dikembalikan secara diam-diam dengan frame yang tidak selaras.

Konfigurasi

Nilai bawaan produksi adalah:

Semua opsi kecuali max_num_shards adalah flag --dataset.*. max_num_shards adalah argumen StreamingLeRobotDataset; lerobot-train menyetelnya dari --num_workers (minimal 1).

Untuk pencampuran episode yang lebih merata, gunakan --dataset.streaming_sampling_strategy=round_robin. Setiap putaran mengacak episode yang saat ini berada di memori dan mengambil satu frame acak dari masing-masing episode; episode yang diterima selama satu putaran akan bergabung ke putaran berikutnya. Kedua strategi mempertahankan cakupan epoch yang tepat sekali dan batas sumber daya yang sama. Tidak ada yang merupakan permutasi seragam global: round-robin lebih memihak episode yang lebih pendek pada prefix terbatas dan dapat meningkatkan pergantian decoder serta mengurangi throughput. Urutan berasal dari --seed (default 1000), bersama dengan inisialisasi kebijakan dan generator acak berseed lainnya. Seed yang berbeda menghasilkan urutan episode dan anchor yang berbeda, dan seed yang sama mengulang urutan tersebut. --seed=null menggunakan seed streaming tetap 42. Pertahankan strategi, --seed, dan pengaturan pool yang sama saat melanjutkan checkpoint. Checkpoint menyimpan seed, sehingga --resume biasa akan mempertahankan urutan tersebut. Checkpoint dari run yang dimulai sebelum --seed mencapai dataset streaming menggunakan seed 42 untuk urutannya: berikan --seed=42 saat Anda melanjutkannya untuk mempertahankan urutan tersebut.

Himpunan episode aktif dibatasi oleh jumlah episode dan ukuran mini-MP4 sintetis yang tepat, yang dihitung dari sidecar. Episode yang lebih besar dari anggaran rank lengkap akan gagal sebelum pelatihan mengambil payload-nya. Reservasi mencakup pengambil yang tertunda, prefetch yang selesai, dan episode yang masih dalam proses dekoding. Pada anggaran penuh, prefetch spekulatif dijeda dan penerimaan penggantian menunggu hingga dekoding terakhir melepaskan byte-nya. EpisodeByteCache.reserved_bytes melaporkan reservasi ini; resident_bytes melaporkan semua payload yang selesai, bahkan sebelum sampel pertamanya diminta.

Ini adalah anggaran payload terkompresi, bukan batas RSS proses: buffer scratch untuk range-fetch/sintesis, status decoder, tabel Parquet, dan tensor yang didekodekan memerlukan memori tambahan. LRU decoder dan antrean sampel terdekode memiliki batas terpisah. Mulai dengan pool atau anggaran yang lebih kecil pada host dengan keterbatasan memori:

lerobot-train \
  --dataset.repo_id=OWNER/DATASET \
  --dataset.streaming=true \
  --dataset.streaming_episode_pool_size=16 \
  --dataset.streaming_prefetch_episodes=4 \
  --dataset.streaming_byte_budget_gb=4 \
  --dataset.streaming_decode_threads=2 \
  --dataset.streaming_decoded_queue_size=8 \
  --num_workers=4 \
  --policy.type=act \
  --output_dir=outputs/train/act_streaming

Untuk dataset lengkap yang disimpan dalam HF Storage Bucket, gunakan pengidentifikasi bucket dan tipe repositori, atau lewati URI bucket sebagai --dataset.root=hf://buckets/OWNER/BUCKET. Metadata (meta/), file Parquet, dan file video harus semuanya ada di root bucket tersebut:

lerobot-train \
  --dataset.repo_id=OWNER/BUCKET \
  --dataset.repo_type=bucket \
  --dataset.streaming=true \
  --policy.type=act \
  --output_dir=outputs/train/act_bucket_streaming

Dataset hub menggunakan repo_type=dataset secara default. Untuk dataset lokal yang lengkap, atur --dataset.root ke direktorinya. Pelatihan menyelesaikan metadata dan payload dari sumber yang sama; tidak diperlukan flag lokasi payload streaming yang terpisah.

Resume and shuffle migration

Streaming reader sebelumnya menggunakan buffer shuffle baris yang terbatas. Episode reader memiliki urutan cakupan eksak yang deterministik, yang diturunkan dari seed dan epoch. Pemulihan checkpoint memulihkan offset sampel per-rank menggunakan ukuran batch checkpoint. Dengan beberapa worker, setiap worker menurunkan offsetnya sendiri dari offset tersebut, karena DataLoader mengambil batch dari worker-nya secara bergiliran. Mengubah ukuran dunia terdistribusi, ukuran batch, atau --num_workers akan mengubah kepemilikan atau batas batch. Untuk perbandingan yang eksak per sampel, pulihkan dengan ukuran dunia, ukuran batch, dan jumlah worker yang sama. Pertahankan konkurensi fetch internal yang sama saat membandingkan kinerja.

Metadata checkpoint tidak mengidentifikasi sampler multi-worker sebelumnya. Checkpoint-nya tidak dapat dibedakan secara andal melalui pemeriksaan world-size dan batch-size, dan tidak boleh digunakan untuk resume streaming yang presisi per sampel. Mulai run baru dari bobot kebijakan yang tersimpan alih-alih. Jaminan resume berkaitan dengan urutan anchor, bukan replay bitwise dari transformasi gambar stokastik. Transformasi gambar acak dijalankan pada thread decode, secara paralel dengan decoding, sehingga seed yang tetap tidak mereproduksi augmentasi yang sama dari satu run ke run berikutnya.

Pemecahan Masalah