Annotasyon Hattı

lerobot-annotate, her bölümün videosunu bir görme-dil modeli (VLM) ile izler ve doğal dilde açıklamaları veri setinize geri yazar. Language Columns and Recipes sayfasındaki iki dil sütununu — language_persistent ve language_events — doğrudan data/chunk-*/file-*.parquet dosyalarına doldurur.

Kısaca: bir LeRobot veri setine yönlendirin; politika üzerinde eğitim yapılabilecek alt görevler, planlar, bellek, ara sözler, konuşma ve görsel S&S ekler.

Bileşenlerin nasıl bir araya geldiği

  your dataset                  lerobot-annotate
  (LeRobotDataset v3.0)
        │
        ▼
  ┌─────────────────────────────────────────────────────┐
  │                    read episodes                     │
  └──────────────────────────┬──────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                     ▼
  ┌──────────┐      ┌───────────────┐        ┌──────────┐       one shared Qwen-VL
  │   plan   │      │ interjections │        │   vqa    │  ◀──   server (vLLM, OpenAI
  └────┬─────┘      └───────┬───────┘        └────┬─────┘        API) drives all three
       └────────────────────┼─────────────────────┘
                            │   each module stages raw JSONL
                            ▼   into .annotate_staging/
                  ┌─────────────────┐
                  │    validator    │  ◀──  checks everything
                  └────────┬────────┘
                           ▼
                  ┌─────────────────┐
                  │     writer      │
                  └────────┬────────┘
                           ▼
              data/chunk-*/file-*.parquet
              (+ meta/info.json tools)

Üç modül (plan, interjections, vqa) hepsi tek paylaşılan VLM ile iletişim kurar. Her modül çıktısını diske yazar, bir doğrulayıcı bunu kontrol eder ve tek bir yazar, veri seti parçalarını yerinde yeniden yazar.

Hattın ürettiği

Her modül, iki dil sütunundan birine yönlendirilen birkaç türde anotasyon (“stil”) üretir:

Alt görevlerin nasıl oluşturulduğu

plan modülü, VLM'den alt görevleri tek seferde istemez. Bunun yerine iki aşamalı bir describe → segment akışı kullanır:

1. Açıkla — VLM, seçilen kamerada gerçekten gördüklerini anlatır (görev hakkında tahmin yürütmez).
2. Segment — bu açıklama geri beslenir ve VLM, bölümü ardışık atomik alt görevlere böler.

Her iki geçiş de bölümü zaman damgalı temas tabloları olarak görür — frames_per_second (varsayılan olarak 0,5 sn) aralıklarla örneklenen kareler, her karenin köşesine zamanı işlenmiş JPEG ızgaralarına paketlenir; böylece VLM tam sınır zamanlarını doğrudan alıntılar. Bu, kare başına bir görsel kullanmaktan çok daha az görme jetonu gerektirdiğinden örneklemeyi yoğun tutmak mümkündür; max_frames_per_prompt değerini aşan bölümler aynı yoğunlukta pencerelere bölünür ve birleştirilir. Her iki istem de kesimlerin nereye yerleştiğini netleştirmek için nedensel bir olay sınırı tanımı taşır (bir nesne tutulduğunda / bırakıldığında / yeni bir konuma ulaştığında / bir kapak durumu değiştirdiğinde / içerikler hareket ettiğinde yeni bir olay başlar).

İsteğe bağlı olarak, üçüncü bir seeded-relabel geçişi (--plan.subtask_seeded_relabel) her span'i önceki/geçerli/sonraki segment temas tablolarıyla birlikte yeniden ziyaret eder ve etiketi minimal düzeyde düzeltir; ilk etiketi bir öncül olarak kullanır — sınırları sabit tutar ve yalnızca ifadeyi netleştirir, bunun bedeli ise alt görev başına bir ek çağrıdır.

Oluşan aralıklar, ardından boşluksuz, tam bölüm kapsamasına birleştirilir; böylece her karede tam olarak bir etkin alt görev bulunur. Üretim ayarları (tek kamera, zaman damgalı temas tabloları, otomatik pencereli alt görev üretimi) için Hugging Face Jobs üzerinde çalıştırma bölümüne bakın.

Araçlar

Yazar, parquet dosyasına tools sütunu eklemez. Araç kataloğu bunun yerine meta/info.json["tools"] içinde bulunur (bkz. Araçlar). Her çalıştırma sonrasında, pipeline, bu listede kanonik say şemasının bulunduğundan emin olur ve önceden bildirdiğiniz araçları korur.

Kendi aracınızı eklemek istiyorsanız meta/info.json["tools"] dosyasını doğrudan düzenleyin — pipeline zaten orada olan her şeyi korur. Bu, aracı sohbet şablonu için görünür kılar ve modelin çağrıyı oluşturmayı öğrenmesini sağlar. Oluşturulan bir çağrıyı fiilen çalıştıran çalışma zamanı katmanı (src/lerobot/tools/ altındaki Tool protokolü / TOOL_REGISTRY) henüz uygulanmadı — Tools belgesi bu parçaları henüz uygulanmamış olarak işaretler.

Hugging Face İşlerinde Çalıştırma

Gerçek bir veri setini etiketlemek, VLM'yi sunabilecek kadar büyük bir GPU gerektirdiğinden lerobot-annotate, lerobot-train ile aynı şekilde kendini Hugging Face Jobs platformuna yönlendirebilir. Yerel olarak çalıştıracağınız komuta --job.target=<flavor> parametresini ekleyin; komut bu donanımda çalıştırılır:

hf auth login   # once

uv run lerobot-annotate \
    --repo_id=user/my_dataset \
    --new_repo_id=user/my_dataset_annotated \
    --push_to_hub=true \
    --vlm.model_id=Qwen/Qwen3.6-27B \
    --vlm.num_gpus=1 \
    --vlm.serve_command="vllm serve Qwen/Qwen3.6-27B --tensor-parallel-size 1 \
        --max-model-len 32768 --gpu-memory-utilization 0.8 \
        --uvicorn-log-level warning --port {port}" \
    --vlm.serve_ready_timeout_s=1800 \
    --vlm.chat_template_kwargs='{"enable_thinking": false}' \
    --job.target=h200

Bu, tek GPU'lu bir h200 işi gönderir:

1. vllm/vllm-openai görüntüsünden başlar ve üzerine lerobot kurar,
2. her GPU için bir vLLM sunucusu başlatır ve OpenAI ile uyumlu API üzerinden yönetir,
3. Veri setinde plan / interjections / vqa modüllerini çalıştırır,
4. --push_to_hub=true ile sonuç, --new_repo_id (veya --repo_id ayarını boş bırakırsanız orijinal --repo_id deposuna) yüklenir.

Komut, işin günlüklerini akış olarak iletir; Ctrl-C ile iptal etmeden bağlantıyı kesersiniz. Kullanılabilir donanım türlerini ve fiyatlarını hf jobs hardware komutuyla listeleyebilirsiniz.

Qwen3.6, düşünme özelliği etkin olarak gelir; bu da anotasyoncunun JSON yanıtı için ihtiyaç duyduğu token bütçesini tüketir — --vlm.chat_template_kwargs='{"enable_thinking": false}' bu özelliği kapatır. --push_to_hub=true olmadan, anotasyonlu veri seti pod çıktığında atılır.

İş seçenekleri

Daha büyük bir veri seti için ölçeklemeyi h200x4 olarak ayarlayın, --vlm.parallel_servers / --vlm.num_gpus değerlerini buna göre artırın ve örneğin --job.timeout=8h ile işe daha fazla pay bırakın.

Uzak çalıştırmalar --repo_id gerektirir (pod, veri setini Hub'dan çeker; --root yalnızca sizin makinenizde bulunan bir dizini belirtir). Yalnızca yerel önbelleğinizde bulunan bir veri seti, önce özel bir depoya itilir.

Önemli seçenekler

En sık başvuracağınız bayraklar bunlardır. Diğer her şey için lerobot-annotate --help komutunu çalıştırın; varsayılanlar kısa manipülasyon bölümleri için ayarlanmıştır.

Veri seti girişi / çıkışı

Hangi modüller çalışır

Her modül varsayılan olarak açıktır ve bağımsız olarak değiştirilebilir (örneğin, modüllerden birinde tek tek çalışmak için atlaması için false olarak ayarlayın):

VLM ( --vlm.* )

Alt görevler / plan / bellek ( --plan.* )

Ünlemler + VQA

Yeni modüller katkıda bulunma

Pipeline büyümek üzere tasarlanmıştır ve katkılar çok memnuniyetle karşılanır — tamamen yeni bir modül (örneğin yörünge izleri veya affordances), yeni bir prompt şablonu, daha akıllı bir grounding akışı veya mevcut plan / interjections / vqa modüllerine yönelik kalite düzeltmeleri.

Her modül src/lerobot/annotations/steerable_pipeline/modules/ altında bulunur, VLM istemcisi ve anahtar kare önbelleğini paylaşır, ham çıktısını geçici ağaca yazar ve yürütücüye kendi fazı olarak bağlanır. Bir fikriniz mi var? deponun üzerinde bir sorun veya PR açın.

Tariflerin çıktının nasıl kullanıldığı

Annotasyonlar, tarifler tarafından okunmak üzere tasarlanmıştır (bkz. Dil Sütunları ve Tarifler). Tipik olarak:

• low-level / high-level / memory-update dalları language_persistent içinden subtask / plan / memory okur.
• bir araya-yanıt dalı, interjection olaylarını, eşleştirilmiş konuşma atomunu (tool_calls_from ile tek bir asistan turuna birleştirilir) ve aynı zaman damgasındaki eşleşen plan yenilemesini okur.
• Bir VQA dalı, language_events içindeki (vqa, user) ve (vqa, assistant) çiftlerini okur.

Durum ve olayların neden ayrı tutulduğu

Tasarımı şekillendiren iki fikir:

1. Persistent state vs. exact events. Persistent rows (subtask, plan, memory) apply to the whole episode and answer “what’s true right now?“. Event rows (interjection, vqa, speech) appear only on the one frame whose timestamp matches. Timestamps are copied straight from the source parquet — never recomputed in floating point.
2. Tek VLM geçişi. Üç modül de tek bir VLM istemcisini paylaşır (işin vLLM sunucusuyla konuşan OpenAI uyumlu istemci), bu nedenle veri seti başına üç model yüklemesi yerine bir model yüklemesi için ödeme yaparsınız.

Tek bir modülü yeniden çalıştırma

Her modül, ham çıktısını <root>/.annotate_staging/episode_{N:06d}/<module>.jsonl konumuna yazar. Bu, prompt yinelemesini ucuz hale getirir: bir modülü yeniden çalıştırmak yalnızca kendi JSONL dosyasını üzerine yazar, ardından yazar nihai parquet dosyasını yeniden oluşturur. Bir modülü tek başına test etmek için istemediğiniz modülleri --plan.enabled=false (ve benzer şekilde --interjections.enabled / --vqa.enabled) ile devre dışı bırakın.

Doğrulayıcının neyi kontrol ettiği

Yazar çalışmadan önce, StagingValidator şunları doğrular:

• her olay satırı tam olarak gerçek bir kare zaman damgasına denk gelir;
• hiçbir konuşma / ünlem çifti yetim kalmamış;
• plan, her araya girme zaman damgasında yenilenir;
• memory satırları alt görev sınırlarına denk gelir (bir hata değil, bir uyarı);
• her VQA asistanı content alanı, bbox / keypoint / count / attribute / spatial biçimlerinden birinde geçerli JSON'dur;
• her satır, column_for_style(style) tarafından seçilen sütuna gider.

Herhangi bir hata yazarı sonlandırır. Hata ayıklama sırasında geçersiz kılmak için --skip_validation=true parametresini iletin.

Her modülün fikirlerinin kaynağı

• plan — alt görevler. Hi Robot (Shi 2025) atom granülerliği için (“bir parça marul al”, “kaseyi kutuya yerleştir”); Pi0.7 (Physical Intelligence 2025) “nasıl, ne değil” detayı için.
• plan — bellek. MEM (Torne 2026): yalnızca asgari düzeyde ilgili bilgiyi koruyun — sonuçları muhafaza edin, belirli nitelikleri atın.
• interjections. Hi Robot senaryo taksonomisi: negatif görev, bağlamsal düzeltme, spesifik kısıt, tercih. Konuşma, yalnızca araç çağrısı olan bir atomdur (tool_calls=[{type:function, function:{name:"say", arguments:{text:...}}}]).
• vqa. Yerelleştirilmiş özellikler için (sınır kutuları [x_min, y_min, x_max, y_max] ve anahtar noktalar, [0, 1] görüntü oranları olarak saklanır) ECoT (Zawalski 2024) ve çok soyutlama düzeyinde yerelleştirme için Steerable VLA Policies (Zhao 2025) kullanılır. Pi0.7 de yanıtları soyutlama düzeyleri arasında yerelleştirir.

Bir modülü iyileştirirken, sıfırdan yeniden yazmak yerine src/lerobot/annotations/steerable_pipeline/prompts/ içindeki prompt şablonunu ayarlayın.

Yaklaşık maliyeti

Her bölümde, boru hattı yaklaşık plan_max_steps plan çağrısı, max_interjections_per_episode araya girme çağrısı ve vqa_emission_hz × episode_seconds VQA çağrısı yapar. Varsayılan ayarlarla (8 alt görev, 3 araya girme, 1 Hz × 3 çift) 30 saniyelik bir bölümde bu, ~50 VLM çağrısına karşılık gelir.

Depolama küçük kalır: language_persistent her epizot için en fazla onlarca KB'dır (parquet, kareler arasında tekrarlanan tek girdiyi sözlük kodlamasıyla sıkıştırır) ve language_events çoğu karede boştur — boyutu, num_frames × num_emissions ile değil, yayınlama sayısı ile orantılı olarak artar.