LeRobotDataset v3.0

LeRobotDataset v3.0, robot öğrenme verileri için standart bir biçimdir. Çok modlu zaman serisi verilerine, sensomotor sinyallere ve çoklu kamera videolarına birleşik erişim sağlar; ayrıca Hugging Face Hub üzerinde indeksleme, arama ve görselleştirme için zengin meta veriler sunar.

Bu biçimdeki bir veri setinin düzeni hakkında okumadan önce ne içerdiğini görmek için birini LeRobot Dataset Visualizer'da açın: kamera kayıtları, senkronize durum ve eylem grafikleri ve her bölüm, tarayıcıda. Explore a Dataset in the Browser'a bakın.

Bu belgeler sizi şunlara yönlendirecektir:

• v3.0 tasarımını ve dizin düzenini anlama
• Bir veri seti kaydedin ve Hub'a gönderin
• Eğitim için veri setlerini LeRobotDataset ile yükleyin
• İndirmeden StreamingLeRobotDataset kullanarak veri kümelerini akış olarak kullanın
• Eğitim sırasında veri artırma için görüntü dönüşümleri uygulayın
• Mevcut v2.1 veri setlerini v3.0 sürümüne taşıma
• Lance gibi diğer LeRobotDataset biçimleri ve uygulamalarıyla deneyler yapın

v3'te yenilikler

• Dosya tabanlı depolama: Parquet/MP4 dosyası başına birçok bölüm (v2, bölüm başına bir dosya kullanıyordu).
• İlişkisel meta veriler: Bölüm sınırları ve aramalar, dosya adları yerine meta veriler üzerinden çözümlenir.
• Hub yerel akış: StreamingLeRobotDataset ile veri setlerini doğrudan Hub'dan tüketin.
• Daha düşük dosya sistemi baskısı: Daha az, daha büyük dosyalar ⇒ daha hızlı başlatma ve ölçeklendirmede daha az sorun.
• Birleşik organizasyon: Veri ve videolar arasında tutarlı yol şablonlarına sahip temiz dizin düzeni.
• Veri seti depolama arka uçları: Veri setleri, nesne depolamadan doğrudan rastgele erişim ve indeksleme için LanceDB tabloları olarak da depolanabilir (bkz. LanceDB veri seti arka ucu).

Kurulum

LeRobotDataset v3.0, lerobot >= 0.4.0 sürümünde yer alır. Yüklemek için Yükleme Kılavuzu'nu izleyin.

Bir veri seti kaydet

SO-101 ile bir veri seti kaydetmek ve Hub'a göndermek için aşağıdaki komutu çalıştırın:

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodem585A0076841 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/tty.usbmodem58760431551 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true \
  --dataset.repo_id=${HF_USER}/record-test \
  --dataset.num_episodes=5 \
  --dataset.single_task="Grab the black cube" \
  --dataset.streaming_encoding=true \
  --dataset.encoder_threads=2
# Optional: --dataset.rgb_encoder.vcodec=auto

Daha fazla ayrıntı için kayıt kılavuzuna bakın.

Biçim tasarımı

v3'ün temel ilkelerinden biri depolamayı kullanıcı API'sinden ayırmaktır: veriler verimli bir şekilde (az sayıda büyük dosya) saklanırken, genel API sezgisel bir bölüm düzeyinde erişim sunar.

v3 üç sütuna dayanır:

1. Tablo verileri: Apache Parquet içinde saklanan düşük boyutlu, yüksek frekanslı sinyaller (durumlar, eylemler, zaman damgaları). Erişim, datasets yığını üzerinden bellek eşlemeli (memory-mapped) veya akış (streamed) olarak yapılır.
2. Görsel veriler: Kamera kareleri birleştirilip MP4 formatında kodlanır. Aynı epizottan gelen kareler gruplanır; videolar, pratik boyutlar için kamera başına parçalara ayrılır.
3. Meta veriler: Şema (özellik adları, dtypes, şekiller), kare hızları, normalizasyon istatistikleri ve epot bölümlemesi (ortak Parquet/MP4 dosyalarına yönelik başlangıç/bitiş ofsetleri) hakkında bilgi veren JSON/Parquet kayıtları.

Milyonlarca epizoda ölçeklenmek için, birden fazla epizottan gelen tablo satırları ve video kareleri birleştirilerek daha büyük dosyalara aktarılır. Epizota özgü görünümler, dosya sınırları yerine meta veriler aracılığıyla yeniden oluşturulur.

Dizin düzeni (basitleştirilmiş)

• meta/info.json: kanonik şema (özellikler, şekiller/tipler), FPS, kod tabanı sürümü ve veri/video parçalarını bulmak için yol şablonları.
• meta/stats.json: normalizasyon için kullanılan küresel özellik istatistikleri (ortalama/std/min/max); dataset.meta.stats olarak sunulur.
• meta/tasks.parquet: görev koşullu politikalar için tam sayı kimliklerine eşlenmiş doğal dil görev tanımları.
• meta/episodes/: ölçeklenebilirlik için chunked Parquet olarak saklanan bölüm başına kayıtlar (uzunluklar, görevler, ofsetler).
• data/: kare kare Parquet parçaları; her dosya genellikle çok sayıda bölüm içerir.
• videos/: kamera başına MP4 parçaları; her dosya genellikle çok sayıda bölüm içerir.

Eğitim için bir veri seti yükleyin

LeRobotDataset, PyTorch tensörlerinden oluşan Python sözlükleri döndürür ve torch.utils.data.DataLoader ile entegre çalışır. Kullanımını gösteren bir kod örneği aşağıdadır:

import torch
from lerobot.datasets import LeRobotDataset

repo_id = "yaak-ai/L2D-v3"

# 1) Load from the Hub (cached locally)
dataset = LeRobotDataset(repo_id)

# 2) Random access by index
sample = dataset[100]
print(sample)
# {
#   'observation.state': tensor([...]),
#   'action': tensor([...]),
#   'observation.images.front_left': tensor([C, H, W]),
#   'timestamp': tensor(1.234),
#   ...
# }

# 3) Temporal windows via delta_timestamps (seconds relative to t)
delta_timestamps = {
    "observation.images.front_left": [-0.2, -0.1, 0.0]  # 0.2s and 0.1s before current frame
}

dataset = LeRobotDataset(repo_id, delta_timestamps=delta_timestamps)

# Accessing an index now returns a stack for the specified key(s)
sample = dataset[100]
print(sample["observation.images.front_left"].shape)  # [T, C, H, W], where T=3

# 4) Wrap with a DataLoader for training
batch_size = 16
data_loader = torch.utils.data.DataLoader(dataset, batch_size=batch_size)

device = "cuda" if torch.cuda.is_available() else "cpu"
for batch in data_loader:
    observations = batch["observation.state"].to(device)
    actions = batch["action"].to(device)
    images = batch["observation.images.front_left"].to(device)
    # model.forward(batch)

Eğitim sırasında bir veri setini akıt

Önce veri setinin Parquet ve video dosyalarını indirmeden eğitim yapmak için --dataset.streaming=true ayarlayın. Epizodlar, sınırlı bir bellek içi havuza anlık olarak getirilir ve seçilen her kare, her epokta tam olarak bir kez ziyaret edilir:

lerobot-train \
  --dataset.repo_id=yaak-ai/L2D-v3 \
  --dataset.streaming=true \
  --policy.type=act \
  --output_dir=outputs/train/act_streaming

Aynı okuyucu, Python için, Hub veri kümeleri için ve HF Storage Bucket içinde saklanan veri kümeleri için kullanılabilir:

from lerobot.datasets import StreamingLeRobotDataset

dataset = StreamingLeRobotDataset("yaak-ai/L2D-v3")
bucket_dataset = StreamingLeRobotDataset("my-org/my-bucket", repo_type="bucket")

CLI'den --dataset.repo_type=bucket veya --dataset.root=hf://buckets/my-org/my-bucket ile bir bucket seçin.

İşçilerin ve parçaların (shard) akış eşzamanlılığına, MP4 yan dizin dosyasına (sidecar index), bellek ayarlarına, devam etme ve sorun giderme konularına nasıl eşlendiğini görmek için Eğitim Veri Seti Akışı bölümüne bakın.

Görüntü dönüşümleri

Görüntü dönüşümleri, modelin dayanıklılığını ve genelleme yeteneğini artırmak için eğitim sırasında kamera karelerine uygulanan veri artırma yöntemleridir. LeRobot; parlaklık, kontrast, doygunluk, ton ve keskinlik ayarları dahil olmak üzere çeşitli dönüşümleri destekler.

Veri seti oluşturma/kayıt sırasında dönüştürme kullanma

Şu anda dönüşümler yalnızca eğitim sırasında uygulanır, kayıt sırasında değil. Bir veri seti oluştururken veya kaydederken, ham görüntüler dönüşümler olmadan saklanır. Bu sayede, verileri yeniden kaydetmeden daha sonra farklı artırma yöntemleriyle deney yapabilirsiniz.

Mevcut veri setlerine dönüştürme ekleme (API)

Eğitim için bir veri seti yüklerken image_transforms parametresini kullanın:

from lerobot.datasets import LeRobotDataset
from lerobot.transforms import ImageTransforms, ImageTransformsConfig, ImageTransformConfig

# Option 1: Use default transform configuration (disabled by default)
transforms_config = ImageTransformsConfig(
    enable=True,  # Enable transforms
    max_num_transforms=3,  # Apply up to 3 transforms per frame
    random_order=False,  # Apply in standard order
)
transforms = ImageTransforms(transforms_config)

dataset = LeRobotDataset(
    repo_id="your-username/your-dataset",
    image_transforms=transforms
)

# Option 2: Create custom transform configuration
custom_transforms_config = ImageTransformsConfig(
    enable=True,
    max_num_transforms=2,
    random_order=True,
    tfs={
        "brightness": ImageTransformConfig(
            weight=1.0,
            type="ColorJitter",
            kwargs={"brightness": (0.7, 1.3)}  # Adjust brightness range
        ),
        "contrast": ImageTransformConfig(
            weight=2.0,  # Higher weight = more likely to be selected
            type="ColorJitter",
            kwargs={"contrast": (0.8, 1.2)}
        ),
        "sharpness": ImageTransformConfig(
            weight=0.5,  # Lower weight = less likely to be selected
            type="SharpnessJitter",
            kwargs={"sharpness": (0.3, 2.0)}
        ),
    }
)

dataset = LeRobotDataset(
    repo_id="your-username/your-dataset",
    image_transforms=ImageTransforms(custom_transforms_config)
)

# Option 3: Use pure torchvision transforms
from torchvision.transforms import v2

torchvision_transforms = v2.Compose([
    v2.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2, hue=0.1),
    v2.GaussianBlur(kernel_size=3, sigma=(0.1, 2.0)),
])

dataset = LeRobotDataset(
    repo_id="your-username/your-dataset",
    image_transforms=torchvision_transforms
)

Kullanılabilir dönüştürme türleri

Bir dönüştürmenin type'i, torchvision.transforms.v2'den herhangi bir sınıf olabilir, örneğin:

• ColorJitter: Parlaklık, kontrast, doygunluk ve tonu ayarlar
• SharpnessJitter: Görüntü keskinliğini rastgele ayarlar
• RandomAffine, RandomRotation: Geometrik jitter
• GaussianNoise, MotionBlur, JPEGCompression, GaussianPatchBrightness, RandomShadow, CoarseDropout, GammaCorrection, PlanckianJitter: Gerçek robotlarda görülen kamera ve aydınlatma efektleri
• Identity: Dönüşüm yok (test için faydalı)

Diğer herhangi bir torchvision.transforms.v2 sınıfı da bir type olarak adlandırılabilir (örneğin RandomResizedCrop veya GaussianBlur); bu dönüşüm örnekler tek tek uygulanır. Ayrıca bir torchvision dönüşümünü doğrudan image_transforms parametresine de iletebilirsiniz.

Her dönüştürme artık toplu (batched) olarak çalışır ve aynı toplu dönüştürmeler her iki arka uçta da çalıştırılır. Örnek başına sınıflar (SharpnessJitter, GaussianNoise, MotionBlur, GaussianPatchBrightness, RandomShadow, CoarseDropout, GammaCorrection, PlanckianJitter, RandomSubsetApply) ve make_transform_from_config, Batched* karşılıkları üzerinde kullanımdan kaldırılmış ön uçlar olarak içe aktarılabilir kalmaya devam eder ve kullanıldıklarında uyarı verir; bunlar gelecekteki bir sürümde kaldırılacaktır. ImageTransforms, (C, H, W) veya (T, C, H, W) tensörünü kabul eden düz bir torch.nn.Module'dür. Bir dönüştürmeyi type ile adlandıran yapılandırmalar etkilenmez.

Mevcut tarifler için davranış değişikliği. Eğitim, kareleri uint8 olarak okur ve ColorJitter, RandomAffine ile RandomRotation dışındaki LeRobot dönüşümleri, daha önce kayan noktalı olmayan girdileri değiştirmeden döndürüyordu. Bu nedenle GaussianNoise, MotionBlur, GaussianPatchBrightness, RandomShadow, CoarseDropout, GammaCorrection veya PlanckianJitter etkinleştiren tarifler, bu dönüşümler olmadan eğitim yapıyordu. Artık her iki arka uçta da uygulanıyorlar, bu nedenle böyle bir tarif, daha öncekinden farklı şekilde eğitim alıyor: istediği artırmayı alıyor. Zaten uygulanan dönüşümler, yuvarlama dışında değişmedi; çünkü toplu yol, her dönüşümden sonra değil, yalnızca sonunda bir kez yuvarlama yaparak kayan nokta aralığında hesaplama yapıyor.

Yapılandırma seçenekleri

• enable: Dönüşümleri etkinleştirme/devre dışı bırakma (varsayılan: False)
• max_num_transforms: Kare başına uygulanan maksimum dönüşüm sayısı (varsayılan: 3)
• random_order: Dönüşümleri standart sıralama yerine rastgele sırayla uygula (varsayılan: False)
• weight: Her dönüştürme için örneklemleme olasılığı (daha yüksek = daha olası, ağırlıkların toplamı 1 değilse normalize edilirler)
• kwargs: Dönüşüme özgü parametreler (ör. parlaklık aralığı)
• backend: Eğitim sırasında dönüşümlerin nerede çalıştığı, "dataloader" (varsayılan) veya "gpu"; aşağıya bakın
• gpu_compile: "gpu" arka ucunda, toplu dönüştürmeleri torch.compile ile derler (varsayılan: True)
• gpu_chunk_size: "gpu" arka ucunda, geçici belleği sınırlamak için bu kadar örnek bir anda artırılır (varsayılan: 32)

GPU üzerinde dönüştürme çalıştırma

Varsayılan olarak dönüşümler, DataLoader işçilerinde örnek başına çalışır. Birden fazla kamera kullanıldığında bu, işçilerin yaptığı en maliyetli işlem olur ve GPU veri beklemek durumunda kalır. İşçilerin yalnızca çözümleme yapmasını ve aynı dönüşümleri her partiye politika cihazında uygulamasını sağlamak için backend=gpu ayarlayın:

lerobot-train \
  --dataset.repo_id=your-username/your-dataset \
  --dataset.image_transforms.enable=true \
  --dataset.image_transforms.backend=gpu \
  --policy.type=act \
  --policy.device=cuda

Rastgeleleştirme değişmez: her örnek kendi dönüşümlerini ve parametrelerini çeker ve bir kameranın geçmişindeki kareler bunları paylaşır. Artırma yalnızca eğitim toplularına, politika ön işleyicisinden önce uygulanır; değerlendirme topluları, rollouts ve kaydedilen checkpoint'ler değiştirilmez.

Bilmeniz gerekenler:

• Hızlandırıcı gerektirir; --policy.device=cpu reddedilir. Kendi image_transforms çağrılabilirine sahip elle oluşturulan bir veri seti de reddedilir, çünkü bunlar işçilerde çalışır.
• Dataloader altyapısının desteklediği her dönüştürme türünü destekler. Toplu (batched) uygulaması olmayan türler (JPEGCompression ve ColorJitter, RandomAffine, RandomRotation ile Identity hariç torchvision sınıfları), hızlanma elde edilemediğinden, parti içinde örnek başına bir kez uygulanır; JPEGCompression ayrıca CPU üzerinden gidip gelir. Kare boyutunu değiştiren bir dönüştürme, birden fazla örnekten oluşan bir partide reddedilir.
• --seed ile yeniden üretilebilir, her işlem farklı bir tohumla başlatılır. Artırma, politikanın rastgele akışını tüketmez ve gpu_compile ile gpu_chunk_size uygulanan şeyi değiştirmez.
• Her iki arka uç da aynı toplu dönüştürmeleri float olarak çalıştırır ve yalnızca sonunda bir kez yuvarlar; bu nedenle aynı parametrelerle bir arka uçta artırılmış bir örnek, diğer arka uçta artırılmış aynı örneğe eşittir.
• gpu_compile, her görüntü şekli için bir kez 15-30 sn sürer. Zirve bellek, parti görüntülerinin yaklaşık iki float kopyası ve bir parçanın birkaç kopyası kadardır; bellek daralırsa gpu_chunk_size değerini düşürün. random_order=true, dönüştürme süresini max_num_transforms ile çarpar.

v2.1 → v3.0 sürümüne geçiş

Dönüştürücü, bölüm başına dosyaları daha büyük parçalarda birleştirir ve bölüm ofsetlerini/metaları yazar. Veri setinizi aşağıdaki talimatları kullanarak dönüştürün.

# Convert an existing v2.1 dataset hosted on the Hub:
python -m lerobot.scripts.convert_dataset_v21_to_v30 --repo-id=<HF_USER/DATASET_ID>

Neler yapar

• Parquet dosyalarını birleştirir: episode_000000.parquet, episode_000001.parquet, … → file-000.parquet, …
• mp4 dosyalarını birleştirir: episode_000000.mp4, episode_000001.mp4, … → file-000.mp4, …
• meta/episodes/* (parçalı Parquet) dosyalarını, bölüm başına uzunluklar, görevler ve bayt/kare ofsetleri ile günceller.

Sık Karşılaşılan Sorunlar

Her zaman push işleminden önce finalize() çağırın

Veri kümeleri oluştururken veya kaydederken, parquet yazarlarını doğru şekilde kapatmak için mutlaka dataset.finalize() çağrısını yapmalısınız. Daha fazla ayrıntı için PR #1903 adresine bakın.

from lerobot.datasets import LeRobotDataset

# Create dataset and record episodes
dataset = LeRobotDataset.create(...)

for episode in range(num_episodes):
    # Record frames
    for frame in episode_data:
        dataset.add_frame(frame)
    dataset.save_episode()

# Call finalize() when done recording and before push_to_hub()
dataset.finalize()  # Closes parquet writers, writes metadata footers
dataset.push_to_hub()

Bu neden gerekli?

Dataset v3.0, verimlilik için tamponlu meta verilerle artımlı parquet yazımı kullanır. finalize() yöntemi:

• Önbelleğe alınan bölüm (episode) meta verilerini diske yazar
• Parquet dosyalarının bozuk olmaması için footer metadata'sını yazmak üzere parquet yazarlarını kapatır
• Veri setinin yüklenmesi için geçerli olduğunu sağlar

finalize() çağrılmadığı takdirde parquet dosyalarınız eksik kalır ve veri seti düzgün şekilde yüklenmez.

Diğer formatlar ve uygulamalar

LanceDB veri seti arka ucu

v3 bir veri seti ayrıca LanceDB tabloları olarak da saklanabilir. LanceDB, yapay zekâ erişim desenleri için Lance biçimi üzerine inşa edilmiş çok modlu bir veri gölüdür: herhangi bir satıra ve video baytlarına hızlı rastgele erişim, aynı tablolar üzerinde skaler, vektör ve tam metin indeksleri; böylece EDA, madencilik, kürasyon ve eğitim doğrudan nesne depolamadan çalışır. Yerleşim, meta/ dizinini değiştirmez ve tabular veriler için bir frames tablosu ile MP4 dosyalarını blob olarak içeren bir videos tablosu ekler. meta/info.json içindeki "storage_format": "lance" değeri okuyucuyu seçer; LeRobotDataset API'si, öğeler ve eğitim hattı değiştirilmez.

• GPU'lar beslenirken doğrudan Hub veya HF Storage Buckets'tan eğitim yapın. Rastgele kareler yerinde okunur, yalnızca her batch'in ihtiyaç duyduğu baytlar çekilir; böylece her batch küresel bir karıştırma olur ve hiçbir şey önceden indirilmez.
• Yaklaşık bir dosya kopyalama maliyetiyle dönüştürün. Videolar yeniden kodlanmadığından, öğeler kaynakla birebir aynıdır. DROID 34 dakikada dönüştürür.
• Kopyasız özellik mühendisliği. Eğiticinin okuduğu tablolara, videoları yeniden yazmadan veya veri setini kopyalamadan puanlar, gömlemeler veya düzeltilmiş etiketler gibi sütunlar ekleyin, ardından bunları indekslerle filtreleyin ve aramada kullanın. Okuyucu, tanımadığı sütunları yok sayar.

Bunun nasıl çalıştığına, kıyaslamalara ve örneklerine dair bilgi için LanceDB LeRobot kılavuzu'na bakın.

Kamera özellikleri video tabanlı olmalıdır. Kamera karelerini görüntü olarak depolayan veri setleri okuyucu tarafından desteklenmez ve dönüştürmeden önce video olarak yeniden kodlanmalıdır.

Lance veri kümelerini okumak için lancedb ek paketi (pip install "lerobot[lancedb]") gereklidir. Biçim salt okunurdur: veri kümelerini varsayılan biçimde kaydedip düzenleyin, ardından lerobot-lancedb paketiyle dönüştürün:

pip install "lerobot-lancedb"
lerobot-lance-convert --repo-id lerobot/pusht --out ./pusht-lance  # or --root <local dataset dir>

Yükleme aynı sınıfı kullanır:

from lerobot.datasets import LeRobotDataset

# Hub dataset repo
dataset = LeRobotDataset("lance-format/pusht-lance")

# HF Storage Bucket, read in place
dataset = LeRobotDataset("my-org/pusht-lance", repo_type="bucket")

# the same bucket as a root URI (other object store URIs work the same way)
dataset = LeRobotDataset("lerobot/pusht", root="hf://buckets/my-org/pusht-lance")

HF Storage Bucket seçenekleri lerobot-train ile çalışır:

lerobot-train \
  --dataset.repo_id=my-org/pusht-lance \
  --dataset.repo_type=bucket \
  --policy.type=act

Görselleştirme her iki görüntüleyiciyle de çalışır. lerobot-dataset-viz --repo-id lance-format/pusht-lance --episode-index 0 bir bölümü normalde olduğu gibi Rerun'da açar ve --display-mode foxglove bunu Foxglove'a WebSocket üzerinden sunar. Her iki durumda da yalnızca ekrandaki kareler alınır; MCAP dışa aktarımı veya indirme yapılmaz.