# 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](./language_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, araya girenler, konuşma ve görsel S&S ekler.

## Bileşenlerin nasıl bir araya geldiği

```text
  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** ortak 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:

| Stil / atom                                | Sütun                | Modül          |
| ------------------------------------------- | --------------------- | --------------- |
| `subtask` (Pi0.7 tarzı "nasıl, ne değil")     | `language_persistent` | `plan`          |
| `plan` (başlangıç + kesinti durumunda yenileme)  | `language_persistent` | `plan`          |
| `memory` (MEM tarzı sıkıştırma)            | `language_persistent` | `plan`          |
| `task_aug` (görevin yeniden ifade edilmeleri)        | `language_persistent` | `plan`          |
| `interjection`                              | `language_events`     | `interjections` |
| konuşma araç çağrısı atomu (`style=null`, `say`) | `language_events`     | `interjections` |
| `vqa` (kullanıcı / asistan çifti)               | `language_events`     | `vqa`           |

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

`plan` modülü, VLM'den alt görevleri tek seferde istemez. Bunun yerine iki adımlı 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 aralığı önceki/geçerli/sonraki segment temas tablolarıyla yeniden ziyaret eder ve ilk etiketi bir öncül olarak kullanarak etiketi minimal düzeyde düzeltir — 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.

Elde edilen 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](#running-on-hugging-face-jobs) 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](./tools)). Her çalıştırma sonrasında, pipeline, bu listede standart `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ı aslında _çalıştıran_ çalışma zamanı katmanı (`src/lerobot/tools/` altındaki `Tool` protokolü / `TOOL_REGISTRY`) henüz uygulanmadı — [Tools](./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](https://huggingface.co/docs/hub/en/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:

```bash
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

| Bayrak                | Varsayılan                   | Ne işe yarar                                                                    |
| ------------------- | ------------------------- | ------------------------------------------------------------------------------- |
| `--job.target`      | `local`                   | Çalıştırılacak HF Jobs türü (ör. `h200`, `h200x4`). Atlanan/`local` çalıştırmalar burada yapılır.    |
| `--job.image`       | `vllm/vllm-openai:latest` | Pod için çalışma zamanı görüntüsü.                                                      |
| `--job.timeout`     | `2h`                      | Gerçek zaman sınırı. Büyük veri kümeleri için bunu artırın.                                    |
| `--job.detach`      | `false`                   | Günlük akışını yayınlamak yerine gönder ve çık.                                      |
| `--job.lerobot_ref` | `main`                    | Pod üzerinde kurulu lerobot'un Git ref'i — değişiklikleri test etmek için bir branch'e yönlendirin. |
| `--job.tags`        | `[]`                      | İş ve ittiği herhangi bir veri setindeki ek etiketler (`lerobot` her zaman eklenir). |

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

Bunlar, en sık başvuracağınız bayraklardı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ışı

| Bayrak              | Varsayılan | Ne işe yarar                                                            |
| ----------------- | ------- | ----------------------------------------------------------------------- |
| `--repo_id`       | —       | İşaretlenecek Hub veri seti (`--root` ayarlanmamışsa indirilir).                 |
| `--root`          | —       | Bunun yerine yerel bir veri seti dizinini etiketleyin.                             |
| `--new_repo_id`   | —       | Sonucu yeni bir depoya gönderin (kaynak depo olduğu gibi kalır).       |
| `--push_to_hub`   | `false` | İşaretleme yaptıktan sonra yükleyin (`--new_repo_id`'ye, aksi halde `--repo_id`'ye geri). |
| `--only_episodes` | tümü     | Sadece bu bölüm indekslerini etiketleyin (test çalıştırması için kullanışlıdır).             |
| `--seed`          | `1729`  | Kesinti zaman damgalarını ve VQA soru türlerini seçen RNG'leri tohumlar.  |

### 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):

| Bayrak                      | Varsayılan | Kapatır                           |
| ------------------------- | ------- | ----------------------------------- |
| `--plan.enabled`          | `true`  | alt_görevler + plan + bellek + task_aug |
| `--interjections.enabled` | `true`  | interjections + konuşma atomları        |
| `--vqa.enabled`           | `true`  | VQA çiftleri                       |

### VLM (`--vlm.*`)

| Bayrak                       | Varsayılan            | Ne işe yarar                                                                         |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------ |
| `--vlm.model_id`           | `Qwen/Qwen3.6-27B` | Sunulacak model ve istem.                                                       |
| `--vlm.camera_key`         | ilk `images.*`   | Her istemin dayandığı kamera.                                            |
| `--vlm.serve_command`      | auto               | Tam olarak `vllm serve …` komutu (TP boyutunu, GPU belleğini ve `--max-model-len` değerini burada ayarlayın).  |
| `--vlm.parallel_servers`   | `1`                | Yuvarlak-robin yönlendirme için bağımsız sunucular (GPU başına bir adet).                           |
| `--vlm.num_gpus`           | `0`                | Sunucu başına GPU (`0` = her birinde bir tane).                                                    |
| `--vlm.client_concurrency` | `16`               | Tüm sunuculardaki uçuştaki istekler.                                               |
| `--vlm.max_new_tokens`     | `512`              | Her çağrı için üretim sınırı.                                                             |
| `--vlm.temperature`        | `0.2`              | Örnekleme sıcaklığı.                                                                |
| `--vlm.reasoning_effort`   | `null`             | OpenAI uyumlu sunuculara iletilen düşünme bütçesi ipucu (`low`/`medium`/`high`). |

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

| Bayrak                            | Varsayılan    | Ne işe yarar                                                                                                                 |
| ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--plan.frames_per_second`      | `2.0`      | İletişim tabloları için kare örnek alma hızı (`2.0` = 0,5 saniyede bir kare).                                                   |
| `--plan.max_frames_per_prompt`  | `60`       | Her VLM çağrısı için kare bütçesi. Örnekleme bu değeri aşan epizotlar, aynı yoğunlukta otomatik olarak pencereye alınır ve ardından birleştirilir.        |
| `--plan.contact_sheet_columns`  | `5`        | İletişim sayfası ızgarası başına sütunlar (`contact_sheet_frames_per_sheet` karolar, zaman satır öncelikli).                                     |
| `--plan.plan_max_steps`         | `8`        | Bölüm başına alt görevlerin üst sınırı.                                                                                         |
| `--plan.subtask_describe_first` | `true`     | describe→segment yerelleştirme geçişini çalıştırın (en iyi alt görev kalitesi; +1 çağrı/epizot).                                             |
| `--plan.subtask_seeded_relabel` | `false`    | İkinci geçiş: her alt görevi, ilk etiketle tohumlanmış önceki/geçerli/sonraki temas sayfalarından yeniden etiketleyin (+1 çağrı/alt görev). |
| `--plan.subtask_relabel_frames` | `5`        | Yeniden etiketleme geçişinde segment başına sayfa içinde eşit aralıklarla örneklenen kareler (yalnızca `subtask_seeded_relabel=true` olduğunda kullanılır).               |
| `--plan.emit_plan`              | `true`     | Numaralı `plan` satırlarını yayınla (`false` = yalnızca alt görevler + bellek).                                                            |
| `--plan.emit_memory`            | `true`     | `memory` satırlarını yayınla (`false` = yalnızca alt görevler + plan); `emit_plan` ile simetrik.                                           |
| `--plan.n_task_rephrasings`     | `10`       | Kaç adet `task_aug` yeniden ifadelendirmesi üretilecek (`0` devre dışı bırakır).                                                                      |
| `--plan.derive_task_from_video` | `if_short` | Veri seti görevini olduğu gibi kullanın (`off`), yalnızca eksik/kısa olduğunda (`if_short`) veya her zaman videoyu yeniden türetin (`always`).    |

### Ünlemler + VQA

| Bayrak                                            | Varsayılan | Ne işe yarar                                               |
| ----------------------------------------------- | ------- | ---------------------------------------------------------- |
| `--interjections.max_interjections_per_episode` | `3`     | Bölüm başına araya giren konuşma/tekrar çiftleri için üst sınır.              |
| `--vqa.vqa_emission_hz`                         | `1.0`   | VQA çiftlerinin ne sıklıkla yayınlandığı.                           |
| `--vqa.restrict_to_default_camera`              | `false` | VQA'yı yalnızca `--vlm.camera_key` üzerine oturtun (aksi halde tüm kameralar). |
| `--vqa.coordinate_scale`                        | `1000`  | VLM bbox/keypoint ızgarası, [0, 1] aralığında saklanır (`none` = px).    |
| `--executor.episode_parallelism`                | `16`    | Her aşama içinde eşzamanlı olarak işlenen bölümler.         |

## Yeni modüller katkıda bulunma

Pipeline büyümek üzere tasarlanmıştır ve **katkılar çok memnuniyetle karşılanır** — yepyeni 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](https://github.com/huggingface/lerobot) ü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](./language_and_recipes)). 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.** Atom granülerliği için ("bir parça marul al", "kaseyi kutuya yerleştir") [Shi 2025](https://arxiv.org/abs/2502.19417) tarafından önerilen Hi Robot; "ne değil, nasıl" detayı için [Physical Intelligence 2025](https://pi.website/pi07) tarafından önerilen Pi0.7.
- **`plan` — bellek.** MEM ([Torne 2026](https://arxiv.org/abs/2603.03596)): yalnızca asgari düzeyde ilgili bilgiyi koruyun — sonuçları muhafaza edin, belirli nitelikleri atın.
- **`interjections`.** Hi Robot senaryo taksonomisi: olumsuz 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 (sınır kutuları `[x_min, y_min, x_max, y_max]` ve anahtar noktalar, [0, 1] görüntü oranları olarak saklanır) için ECoT ([Zawalski 2024](https://arxiv.org/abs/2407.08693)) ve çok soyutlama düzeyinde yerelleştirme için Steerable VLA Policies ([Zhao 2025](https://arxiv.org/abs/2509.07626)). Pi0.7, yanıtları soyutlama düzeyleri arasında da 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` bölüm başına 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.

