# Eğitim Veri Seti Akışı Eğitim zamanı veri seti akışı, `lerobot-train`'in bir LeRobotDataset v3'ü, tam Parquet ve video yüklemesini önceden indirmeden tüketmesini sağlar. Bunu mevcut genel anahtar üzerinden etkinleştirin: ```bash lerobot-train \ --dataset.repo_id=OWNER/DATASET \ --dataset.streaming=true \ --policy.type=act \ --output_dir=outputs/train/act_streaming ``` Bu özellik, `--dataset.streaming_encoding=true` parametresinden bağımsızdır. `streaming_encoding`, kayıt sırasında videoların nasıl yazılacağını kontrol eder; `dataset.streaming` ise eğitim sırasında mevcut bir veri setinin nasıl okunacağını kontrol eder. Kayıt ve rollout kodlayıcıları, bu eğitim yolu tarafından kullanılmaz. ## Bir epoch'un nasıl okunduğu Her dağıtık rank, deterministik ve kare dengeli, tam bölümlerden oluşan bir kümeye sahiptir. Her DataLoader işçisi için bir tam kapsama havuzu, o işçinin bu bölümlerdeki payını, her kapsama döneminde seçilen her kareyi bir kez ziyaret ederek karıştırır. Parquet sütunları ve sıkıştırılmış MP4 bayt aralıkları, aynı bayt-farkındalıklı kabul sınırından önceden getirilir. Zaman geçmişi ve gelecek pencereleri, harita tarzı yüklemedeki aynı sınır dolgu maskeleri dahil olmak üzere, tam bölümün içinde çözümlenir. `--dataset.streaming=false` olduğunda varsayılan harita tarzı `LeRobotDataset` davranışı değişmez. ## Workers, shard'lar ve eşzamanlılık Her rank, tam bölümlerin kare dengeli bir dilimine sahiptir. Bir rank içinde, `--num_workers`, map-style veri kümeleri için olduğu gibi, DataLoader işçi süreçlerinin sayısını belirler. Her işçi, rank'ın bölümlerinin ayrık, kare dengeli bir kısmına sahiptir; kendi tam kapsama havuzu, kendi bayt bütçesi payı ve kendi iş parçacığı havuzları vardır: | Aşama | Eşzamanlılık | Ayar | | -------------------------- | ---------------------------------------------- | ------------------------------------------ | | Rank bölme | Her rank için bir adet ayrık tüm-epizot shard | Dağıtık dünya boyutu | | DataLoader işçileri | Her işçi için sıralama diliminin bir ayrık parçası | `--num_workers` | | Bölüm alma | Parquet satırları ve MP4 bayt aralıkları, paralel olarak | `max_num_shards`, `--num_workers` parametresinden ayarlanır | | Örnek derleme ve çözümleme | Zaman pencereleri ve video kareleri, paralel olarak | `--dataset.streaming_decode_threads` | | Sıralı örnek tamponu | Planlayıcı sırasına göre önde tutulan çözümlenmiş örnekler | `--dataset.streaming_decoded_queue_size` | **Neden birden fazla işçi?** Örnek derleme ve parti devri Python kodu çalıştırır ve bir süreç, Python kodunu aynı anda yalnızca bir iş parçacığında çalıştırır (GIL). Tek bir işçiyle, bir sıranın çözüm iş parçacıkları birbirini bekler, bu da sıranın yalnızca yaklaşık 2 CPU çekirdeğini kullanmasına neden olur. Her işçi ayrı bir süreç olduğundan, N işçi örnekleri paralel olarak derler ve çözer. **Havuz boyutu ve parti çeşitliliği.** `streaming_episode_pool_size`, her işçinin havuzunu belirler. Bu değeri ayarlamazsanız, rank 32 bölümü karıştırır ve N işçinin her biri bunların 32/N'ini alır. Her işçi ayrıca `streaming_prefetch_episodes` bölümünü önceden yükler ve ayrı bir Python sürecidir; bu nedenle daha fazla işçi daha fazla bellek kullanır: 3 kameraya sahip tek bir veri setinde, 4 işçi toplamda yaklaşık 8 GB kullanırken, tek işçi yaklaşık 3 GB kullanmıştır. DataLoader her partiyi tek bir işçiden alır, bu nedenle bir parti, tek bir işçinin havuzundaki bölümleri karıştırır. Daha büyük bir havuz, her partide daha fazla bölüm karıştırır ancak daha fazla bellek kullanır ve ilk örnekten önce daha fazla veri getirir. **Sınırlar.** Bayt bütçesi (`streaming_byte_budget_gb`) ve açıkça belirtilen `video_decoder_cache_size` rank başına kalır: her işçi bunların 1/N'ini alır. Bir işçinin en az bir epizoda ihtiyacı vardır, bu nedenle `lerobot-train`, rankın sahip olduğu epizot sayısını aşmayacak kadar işçi kullanır. `--num_workers=0`, veri setini eğitim sürecinde tutar. Burada eğitim iş parçacığı görüntü dönüşümlerini uygular, bu da aynı `--seed` değerinin aynı dönüşümleri vermesini sağlar. ## MP4 yan dosyaları ve ilk çalıştırma Video akışı, bir MP4 dizin yan dosyası (sidecar) kullanır. Veri seti başlatma işlemi önce revizyon anahtarlı yerel önbelleği kontrol eder, ardından geçerli bir yayımlanmış yan dosyası arar. İkisi de kullanılamıyorsa LeRobot, bir süreç kilidini tutarak yan dosyayı yerel olarak oluşturur ve onu atomik olarak kurar. Başarısız veya yarıda kesilen bir oluşturma işlemi, önceki geçerli dosyanın yerini almaz. Aynı yan dosyaya ihtiyaç duyan diğer süreçler, `--dataset.streaming_sidecar_lock_timeout_s` (varsayılan olarak 30 dakika) kadar kilit için bekler. Dizinlenmesi daha uzun süren büyük veri setleri için bu değeri artırın. Hub yük okumaları, meta veri anlık görüntüsünün commit'ine sabitlenir. Varlık kovası (Bucket) dizinleri, içerik özetleri dahil olmak üzere taze bir nesne listesiyle karşılaştırılır; bu nedenle aynı yoldaki bir video değiştirildiğinde, dosya boyutu değişmemiş olsa bile yan dosyası (sidecar) geçersiz kılınır. Bu liste başlangıç iş yükünü artırır, ancak video yüklerini indirmez. Bir çalıştırma sırasında meta verileri ve yükleri değiştirmeden bırakın. Kararlı nesne kimliklerine sahip olmayan genel uzak dosya sistemleri, her açılışta dizinlerini yeniden oluşturur. Nesne parmak izi içermeyen mevcut Bucket yan dosyaları yerel olarak bir kez yeniden oluşturulur; güncellenmiş yan dosyanın yayımlanması, açık bir bakım sorumlusu eylemi olarak kalır. Eğitim salt okunurdur: yan dosya (sidecar) yüklenmez veya veri seti deposu değiştirilmez. Düğüme yerel önbelleklere sahip bir kümede, ilk iş her düğümde bir kez oluşturulabilir. Paylaşılan LeRobot önbelleği bu yinelenmeyi önler. Sidecar yapımı, her tamamlanan kaynak dizinini geçici bir arşive yazar. Yapılandırılan sayıda ayrıştırma sonucunu tutar. Dizi belleği, en büyük eşzamanlı kaynaklara bağlıdır; arşiv meta verileri hâlâ kaynak sayısıyla birlikte büyür. `lerobot-build-mp4-sidecar` çalıştırırken ayrıştırma eşzamanlılığını ayarlamak için `--workers` kullanın. Başarısız bir derleme, önceki sidecar'ı korur. Yayınlanan schema-3 NPZ arşivleri, kanonik `int64` tamsayı dizilerini korur. İlk açma işlemi, arşivi `$HF_LEROBOT_HOME/streaming-indexes` altında salt okunur, bellek eşlemeli bir indekse dönüştürür. Türetilen indeks, en küçük kesin tamsayı türlerini kullanır. Sabit bir süre, kompozisyon ofseti, boyut veya bayt ofsetini yalnızca bir kez saklar. Salt okunur dizi görünümleri, mantıksal örnek sayısını korur. Sunum zaman damgaları, kesin `float64` değerlerini korur. Senkron örnek dizileri, yoğun depolamayı korur. Türetilmiş indeks ayrı bir önbellek nesli kullanır. Eski okuyucular mevcut önbellek biçimlerini korur. Yeni okuyucuyla yapılan ilk açılış, arşivi bir kez dönüştürebilir; sonraki açılışlar bunu yeniden kullanır. Dönüştürme işlemi bir süreç kilidi ve atomik bir değiştirme kullanır. Önbelleği paylaşan sıralar, aynı dosya destekli sayfaları yeniden kullanır. Her sıra, yalnızca bölümlerinde kullanılan kaynak dosyalar için kayıtlar oluşturur. Eski ve yeni önbellek nesilleri ek disk alanı gerektirebilir. Yan dosyanın değiştirilmesi, etkin okuyucuları geçersiz kılmadan yeni bir değiştirilemez nesil oluşturur. Bu, tüm meta verilerin sabit boyutlu olmasını sağlamaz: bölüm meta verileri ve aralık tabloları veri setiyle birlikte büyümeye devam eder ve karıştırılmış sıra parçaları (shards) üst üste binen kaynak dosyalara erişebilir. İşletim sisteminde yerleşik haritalı sayfalar da RSS'e dahil edilir; sıralar tarafından paylaşılan belleği ölçerken oransal küme boyutunu (PSS) kullanın. Parquet okumaları, satır gruplarını bölüm istatistiklerini kullanarak budar ve ardından tam bölgeye (complete episode) filtreler. İstatistiği olmayan gruplar aday olarak kalır, bu nedenle faydalı sınırları olmayan dosyalar hâlâ tüm dosyanın tahmini okunmasını gerektirebilir. Veri seti yöneticileri, yan dosyayı (sidecar) önceden oluşturabilir: ```bash 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 ``` Yayın işlemi her zaman açıkça yapılır. Tam veri seti yan dosyasını doğruladıktan sonra yalnızca `--push` ekleyin. Alt küme yan dosyaları yayınlanamaz. Veri seti depoları için `--push`, özel `lerobot-sidecars` dalını oluşturur veya günceller. Kaynak veri seti dalı/etiketi değiştirilmez. Eğitim, sabitlenmiş video-kaynağı commit'ine bağlı bir anahtarla orada bir indeks arar ve kullanmadan önce doğrular. Bir etiket ve çözümlenmiş commit'i aynı yayımlanmış indeksi paylaşır; mevcut revizyon-anahtarlı yerel önbellekler yeniden kullanılabilir kalır. Kovalar hâlâ doğrudan `meta/mp4-sidecars/` altında yayımlanır. Yayımlama, depo veya kova yazma erişimi gerektirir; eğitim yalnızca okuma erişimi gerektirir ve asla dal oluşturmaz veya dosya yüklemez. Sidecar şeması v3, B-kareli videolar dahil olmak üzere MP4 kompozisyon zamanlamasını ve kodlayıcı gecikmesi düzenlemelerini korur. Eski sidecar'lar otomatik olarak ayrı bir revizyon anahtarlı önbellek girdisine yeniden oluşturulur; ayrıca açık bir yayınlama işleminden önce de yeniden oluşturulmaları gerekir. Yeniden sıralanan videolar, her alınan aralıkta son GOP'un sonunu içerir, böylece çözümlenmiş kare dizinleri ardışık kalır. Tekrarlanan veya birim hızı olmayan MP4 düzenleme zaman çizelgeleri, sessizce yanlış hizalı kareler döndürmek yerine reddedilir. ## Yapılandırma Üretim varsayılanları şunlardır: | Seçenek | Varsayılan | Anlam | | ----------------------------------- | -------------: | --------------------------------------------------- | | `streaming_episode_pool_size` | 32 / N her biri | Her işçi tarafından karıştırılan en fazla tamamlanmış bölüm sayısı | | `streaming_sampling_strategy` | `remaining` | Kalan kare ağırlıklandırması veya karıştırılmış `round_robin` | | `streaming_prefetch_episodes` | 8 | Her işçinin havuzundan önce getirilen bölümler | | `streaming_byte_budget_gb` | 8 | Rank başına sentezlenen maksimum MP4 bayt sayısı | | `streaming_decode_threads` | 2 | Paralel örnek derleme ve video çözme işçileri | | `streaming_decoded_queue_size` | 8 | Planlayıcı sırasına göre önceden tamponlanan çözümlenmiş örnekler | | `video_decoder_cache_size` | pool × kameralar | Açık video çözücü LRU sınırı işçi başına | | `streaming_native_http_connections` | kaldırıldı | Rank başına yerel HTTP bağlantı sınırı | | `streaming_native_http_subranges` | 1 | Yerel HTTP aralığı okuma başına eşzamanlı alt aralıklar | | `streaming_sidecar_lock_timeout_s` | 1800 | Diğer bir sidecar derlemesi için beklenmesi gereken saniye | | `max_num_shards` (`--num_workers`) | 16 | İşçi başına eşzamanlı olarak alınan bölümler | `max_num_shards` hariç tüm seçenekler `--dataset.*` bayraklarıdır. `max_num_shards`, `StreamingLeRobotDataset` argümanıdır; `lerobot-train`, bunu `--num_workers` değerinden ayarlar (en az 1). Daha dengeli bölüm karışımı için `--dataset.streaming_sampling_strategy=round_robin` seçeneğini kullanın. Her turda, o anda mevcut olan bölümler karıştırılır ve her birinden karıştırılmış tek bir çerçeve örneklenir; bir tur sırasında kabul edilen bölümler bir sonraki tura katılır. Her iki strateji de tam olarak bir kez epoch kapsamını ve aynı kaynak sınırlarını korur. Hiçbiri küresel bir düzgün permütasyon değildir: round-robin, sonlu öneklerde daha kısa bölümlere öncelik verir ve bu da çözücü değişimlerini artırıp verimliliği düşürebilir. Sıra, `--seed` (varsayılan 1000) ile politika başlatması ve diğer tohumlu rastgele üreteçlerden gelir. Farklı tohumlar farklı bölüm ve çapa sıraları verir, aynı tohum ise sırayı tekrarlar. `--seed=null`, sabit 42 akış tohumunu kullanır. Bir kontrol noktasından devam ederken aynı stratejiyi, `--seed` ve havuz ayarlarını koruyun. Kontrol noktası tohumu sakladığı için düz bir `--resume` sırayı korur. `--seed` akış veri setine ulaşmadan önce başlayan bir çalışmadan gelen bir kontrol noktası, sırası için 42 tohumunu kullanmıştır: bu kontrol noktasından devam ederken o sırayı korumak için `--seed=42` parametresini iletin. Aktif bölüm kümesi, hem bölüm sayısı hem de yan dosyadan (sidecar) hesaplanan tam sentezlenmiş mini-MP4 boyutlarıyla sınırlandırılır. Tam sıralama bütçesinden büyük bir bölüm, eğitim yükünü (payload) getirmeden önce başarısız olur. Rezervasyonlar, bekleyen getirme işlemlerini, tamamlanan ön getirmeleri ve hâlâ çözümlenen bölümleri kapsar. Bütçe dolduğunda, spekülatif ön getirme duraklatılır ve yer değiştirme kabulü, son çözümlemenin baytlarını serbest bırakmasını bekler. `EpisodeByteCache.reserved_bytes` bu rezervasyonları raporlar; `resident_bytes` ise ilk örnek istenmeden önce bile tüm tamamlanmış yükleri raporlar. Bu, sıkıştırılmış yük bütçesidir, süreç RSS sınırı değildir: aralık-alma/sentez geçici tamponları, çözücü durumu, Parquet tabloları ve çözülmüş tensörler ek bellek gerektirir. Çözücü LRU'su ve çözülmüş örnek kuyruğu ayrı sınırlara sahiptir. Belleği kısıtlı konaklarda daha küçük bir havuz veya bütçeyle başlayın: ```bash 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 ``` HF Storage Bucket'ta saklanan tam bir veri seti için, bucket'ın tanımlayıcısını ve depo türünü kullanın veya bucket URI'sini `--dataset.root=hf://buckets/OWNER/BUCKET` olarak iletin. Meta veriler (`meta/`), Parquet ve video dosyalarının tümü, o bucket'ın kökünde bulunmalıdır: ```bash lerobot-train \ --dataset.repo_id=OWNER/BUCKET \ --dataset.repo_type=bucket \ --dataset.streaming=true \ --policy.type=act \ --output_dir=outputs/train/act_bucket_streaming ``` Hub veri kümeleri varsayılan olarak `repo_type=dataset` kullanır. Tam yerel bir veri kümesi için `--dataset.root` parametresini ilgili dizinine ayarlayın. Eğitim, hem meta verileri hem de yükleri aynı kaynaktan çözümler; ayrı bir akış yük konumu bayrağına gerek yoktur. ## Devam et ve karıştırma göçü Daha önceki akış okuyucu, sınırlı bir satır karıştırma tamponu kullanıyordu. Bölüm okuyucu ise, tohum ve çağdan türetilen, deterministik ve tam kapsama sıralamasına sahiptir. Kontrol noktasından devam etme, kontrol noktası parti boyutunu kullanarak sıralama başına örnek ofsetini geri yükler. Birden fazla işçi kullanıldığında, DataLoader işçilerinden partileri sırayla aldığı için her işçi kendi ofsetini bu değerden türetir. Dağıtık dünya boyutunun, parti boyutunun veya `--num_workers` parametresinin değiştirilmesi, sahiplik veya parti sınırlarını değiştirir. Örnek düzeyinde tam karşılaştırmalar için, aynı dünya boyutu, parti boyutu ve işçi sayısı ile devam edin. Performans karşılaştırması yaparken aynı iç alma eşzamanlılığını koruyun. Kontrol noktası (checkpoint) meta verileri, önceki çok işçili örnekleyiciyi (multi-worker sampler) tanımlamaz. Kontrol noktaları, dünya boyutu (world-size) ve parti boyutu (batch-size) kontrolleriyle güvenilir bir şekilde ayırt edilemez ve örnek-kesin (sample-exact) akışlı devam (streaming resume) için kullanılmamalıdır. Bunun yerine, kaydedilmiş politika ağırlıklarından (policy weights) yeni bir çalıştırma başlatın. Devam garantisi, çapraz (anchor) sırasıyla ilgilidir; stokastik görüntü dönüşümlerinin bit düzeyinde yeniden oynatılmasıyla değil. Rastgele görüntü dönüşümleri, çözümleme (decoding) iş parçacıklarında, çözümlemeyle paralel olarak çalıştığından, sabit bir tohum (seed) bir çalıştırmadan diğerine aynı artırmaları (augmentations) yeniden üretmez. ## Sorun Giderme | Belirti | Ne yapılmalı | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | İlk parti uzun bir süre alır | Bir sidecar derlemesi için günlükleri kontrol edin. Ortak bir önbelleği yeniden kullanın veya doğrulanmış, eksiksiz bir sidecar'ı açıkça yayınlayın. | | A sidecar kilidi zaman aşımına uğrar | Başka bir süreç aynı revizyonu indekslemeye devam ediyor olabilir. Bayat bir kilidi kaldırmadan önce sağlıklı olduğundan emin olun. | | Bir rank hiçbir veriye sahip değildir | Her rank'in en az bir seçili episode'a sahip olması için rank sayısını azaltın. | | Bayt bütçesi aşıldı | Bölüm havuzunu düşürün, sıralama başına bayt bütçesini artırın veya daha küçük bölüm aralıklarına sahip bir yük düzeni kullanın. | | Uzak okumalar kimlik doğrulaması yapamaz | Hugging Face belirtecinin veya fsspec kimlik bilgilerin her işçiye (worker) erişilebilir olmasını sağlayın. Yardımcılar (sidecar) asla kimlik bilgilerini gömmez. | | Yenileme istasyonları yüksek | p95/p99 parti bekleme süresini karşılaştırın, ağ rekabetini azaltın, ön yükleme değerini kademeli olarak artırın, yan aracın revizyonla eşleştiğini kontrol edin. |