# Dil sütunları ve tarifler

LeRobot veri setlerinin çoğu, bölüm başına tek bir `task` dizesiyle birlikte gelir; bu, kısa süreli ve tek talimatlı beceriler için yeterlidir ancak alanın yöneldiği daha uzun ufuklu, çok modlu robot politikaları (yüksek düzey planlama, bellek, araya girmeler, VQA, araç kullanımı) için yeterli değildir. Bu politikaları veri seti biçimini çatallamadan desteklemek için LeRobot, `LeRobotDataset`'i iki isteğe bağlı dil sütunu ve bu satırları anında sohbet tarzı eğitim örneklerine dönüştüren küçük bir tarif katmanı ile genişletir.

Tasarım, temiz bir şekilde üç katmana ayrılır:

1. **Veri setindeki veriler** — `data/chunk-*/file-*.parquet` içinde karelerin yanında saklanan dil etiketleri, iki isteğe bağlı sütun olarak (`language_persistent` ve `language_events`). Bu sütunlara sahip olmayan veri setleri mevcut davranışlarını korur.
2. **Reçete** — hangi etiketleme satırlarının bağlanacağını ve bunların sohbet turları olarak (`role`, `content`, isteğe bağlı görseller, isteğe bağlı araç çağrıları) nasıl yerleştirileceğini bildiren bir YAML dosyası. Reçeteler saf yapılandırma dosyalarıdır; yeni bir tane eklemek için Python gerekmez.
3. **Eğitim biçimi** — örnek zamanında, `RenderTrainingMessagesStep` tarifi kare başına ek açıklamalarla eşleştirir ve politika işleyicilerin tükettiği HF tarzı `messages` ile LeRobot'a özgü yan dosyaları (`message_streams`, `target_message_indices`) üretir.

Bu sayfa, her katmanı sırayla açıklar.

## Katman 1 — veri setindeki dil sütunları

İsteğe bağlı iki sütun, `data/chunk-*/file-*.parquet` içindeki kare verilerinin yanında yer alır:

- `language_persistent`: bir bölümdeki her kareye yayılan, `subtask`, `plan` ve `memory` gibi aktif kalan durum için satırlardan oluşan bir liste.
- `language_events`: bir olayın yayımlandığı tam karede yalnızca o karede bulunan satırlardan oluşan bir liste, örneğin `interjection`, `vqa` ve konuşma araç çağrıları.

Her iki sütun da aynı satır biçimini paylaşır (olay satırları, satırın oturduğu karenin zaten bunu sağladığı için `timestamp` alanını atlar):

```text
role: string
content: string | null
style: string | null
timestamp: float32        # persistent rows only
camera: string | null     # observation.images.* feature key, view-dependent rows only
tool_calls: list[Json] | null
```

`camera` alanı, `content` değeri belirli bir kamera görünümüne dayanan satırları etiketler. Görünüme bağımlı stillerin (`vqa` ve `trace`) satırları, `camera` değerini eşleşen `observation.images.*` özellik anahtarına ayarlamalıdır. Diğer tüm stillerin satırları — robot çerçevesi ilkelini eklemler / Kartezyen terimlerle tanımlayan `motion` dahil — `camera` değerini `null` olarak bırakmalıdır. Pipeline yazarları ve doğrulayıcı, bunu `validate_camera_field(style, camera)` aracılığıyla uygular.

`meta/tasks.parquet` görev için kanonik kaynak olmaya devam eder. Özel `${task}` recipe bağlaması her zaman o görev dizgesini okur ve dil anotasyonlarına bağlı değildir.

### Mimari

Dil yığını kendisi, 1. katmanı destekleyen üç iç modüle sahiptir:

1. `lerobot.datasets.language`, şema, stil kayıt defteri ve `column_for_style` öğesini tanımlar.
2. `lerobot.datasets.language_render` satırları çözümler ve mesajları oluşturur.
3. `RenderTrainingMessagesStep`, veri seti örneklerini `messages`, `message_streams` ve `target_message_indices` olarak dönüştürür.

`LeRobotDataset` tariften bağımsızdır. `language_persistent` ve `language_events` alanları mevcut olduğunda bunları olduğu gibi iletir ve etiketlenmemiş veri setleri mevcut davranışlarını korur.

## Katman 2 — tarif anatomisi

Recipes, `lerobot.datasets.recipe` içindeki `TrainingRecipe` ve `MessageTurn` tarafından desteklenen YAML dosyalarıdır. Hangi etiketleme satırlarının çekileceğini (`bindings` aracılığıyla) ve bunların sohbet turlarına (`messages`) nasıl birleştirileceğini bildirirler.

```yaml
messages:
  - { role: user, content: "${task}", stream: high_level }
  - { role: assistant, content: "${subtask}", stream: low_level, target: true }
```

Bir tarif, alt tariflerin ağırlıklı bir **karışımına** da dallanabilir. Örnek alma sırasında, örnek dizisinden deterministik olarak tam olarak bir dal seçilir; böylece farklı kareler farklı hedefleri (ör. bellek güncellemeleri, düşük seviyeli yürütme, VQA) herhangi bir Python bağlantısı olmadan eğitir.

### Zamansal anlambilim

Kalıcı stiller, değiştirilene kadar yayımlandıktan sonra etkin kalır:

- `active_at(t, style=subtask)`
- `nth_prev(style=memory, offset=1)`
- `nth_next(style=subtask, offset=1)`

Olay stilleri yalnızca tam zaman damgalarında var olur:

- `emitted_at(t, style=interjection)`
- `emitted_at(t, style=vqa, role=user, camera=observation.images.top)`
- `emitted_at(t, role=assistant, tool_name=say)`

Tam olay eşleştirmesinde tolerans penceresi yoktur, bu nedenle yazarlar olay satırlarını parquet verisinden gelen kare zaman damgalarıyla işaretlemelidir.

### Görüşe bağlı çözünürlük

Görüşe bağlı stiller (`vqa` ve `trace`) için çözümleyici, `role=` ve `tool_name=` ile paralel olarak `camera=` filtresi kazanır. Birden fazla kameraya sahip veri setleri genellikle aynı zaman damgasında kameraya birer (`vqa`, `user`) + (`vqa`, `assistant`) çifti yayar; `camera=` olmadan bu çözümleyiciler iki eşleşme görür ve belirsizlik hatası fırlatır. Tarifler, her kamerayı kendi bağlaması ve eşleşen bir görüntü bloğu aracılığıyla tüketir, örn.

```yaml
ask_vqa_top:
  route: vqa
  bindings:
    vqa_query: "emitted_at(t, style=vqa, role=user, camera=observation.images.top)"
    vqa: "emitted_at(t, style=vqa, role=assistant, camera=observation.images.top)"
  messages:
    - role: user
      stream: high_level
      if_present: vqa_query
      content:
        - { type: image, feature: observation.images.top }
        - { type: text, text: "${vqa_query}" }
    - {
        role: assistant,
        content: "${vqa}",
        stream: high_level,
        target: true,
        if_present: vqa,
      }
```

Veri setinin kaydettiği her kamera için birer alt tarif ekleyin. Açık `route: vqa` işareti, eşleşen seyrek VQA anotasyonunun normal ağırlıklı karışım seçimine öncelik kazanmasını sağlar; bileşen adları tamamen tanımlayıcıdır.

## Katman 3 — eğitim biçimi

Render edilen örnekler, HF tarzı sohbet mesajları ve LeRobot yan araçlarını kullanır:

```python
sample["messages"]
sample["message_streams"]
sample["target_message_indices"]
```

Render, bir tokenizer sohbet şablonu uygulamaz. Politika işleyicileri, mesajların omurgaları için nasıl serileştirileceğine karar verir; bu sayede aynı veri seti, OpenAI tarzı sohbet mesajları bekleyen SmolVLA, Pi0.5 ve gelecekteki herhangi bir VLM arasında kullanılabilir kalır.

## Karışımlar

Blend tarifleri, örnek indeksinden ağırlıklı bir alt tarifi deterministik olarak seçer. `recipes/subtask_mem.yaml`, kompakt çekirdek blend'ini eğitir: yüksek düzeyde alt görev tahmini, düşük düzeyde yürütme ve bellek. `recipes/subtask_mem_vqa_speech.yaml`, VQA ve sözlü araya girme yanıtlarını da ekleyen daha kapsamlı varyanttır.

`recipes/subtask_joint.yaml`, ağırlıklı bir karışım yerine ortak dizilim eğitimini gösterir. Aynı örnek için, asistan alt görevi `low_level` akışında metin çapraz entropisi ile denetlenirken eylem tahmini aktif kalmaya devam eder; bu da π0.5 makalesindeki ortak kurulumla uyumludur. Şimdilik yalnızca eğitim amaçlıdır: çalışma zamanı, çıkarım sırasında bu ortak öneki henüz yeniden oluşturmaz.

## Zarif yokluk

Her iki dil sütunu da eksikse, `None` ise veya boşsa, `RenderTrainingMessagesStep` uygun olduğunda görev dizgisini düşük düzeyde denetim olarak kullanır, aksi halde örneği değiştirmez. İşaretlenmiş bir örnekte, hiçbir tarif dalı uygulanmıyorsa ve görev yedeği yoksa, işleme `None` döndürür ve bir yükleyicinin başka bir örneği yeniden denemesine izin verir.