# Пакетная обработка в реальном времени (RTC)

Real-Time Chunking (RTC) позволяет крупным робототехническим политикам на основе flow-matching, таким как [Pi0](./pi0), [Pi0.5](./pi05) и [SmolVLA](./smolvla), генерировать плавное, непрерывное и реактивное движение, несмотря на высокую задержку вывода. LeRobot предоставляет исходный режим направленного вывода во время инференса, а для совместимых контрольных точек Pi05 — условное формирование действий во время обучения с дешёвым выводом жёсткого префикса.

Эти политики генерируют блоки будущих действий (например, по 50 шагов за раз), а не отдельные действия. Поскольку модели большие, генерация каждого блока занимает больше времени, чем требуется роботу на его выполнение. Наивное выполнение блоков приводит к проблемам, таким как паузы, рывки при переходах или резкие изменения стратегии, когда следующий блок приходит с опозданием или противоречит ранее выполненным действиям.

RTC решает эту проблему, асинхронно генерируя следующий фрагмент, пока робот продолжает выполнять текущий, и направляя новый фрагмент так, чтобы он плавно совпадал с уже выполненной частью предыдущего фрагмента.

## Как работает RTC (упрощённо)

RTC позволяет роботу планировать действия наперёд, пока он ещё движется. Пока робот выполняет один фрагмент действий, RTC начинает формировать следующий фрагмент заранее. Однако к моменту, когда новый фрагмент готов, робот уже немного сместился, поэтому RTC должен обеспечить плавное согласование нового фрагмента с текущими действиями робота.

Для этого RTC рассматривает начало нового фрагмента как задачу inpainting или «заполнения пробелов»: он плавно корректирует первую часть нового фрагмента, чтобы она естественно вписалась в текущее движение робота. В результате отсутствуют паузы и резкие скачки.

С технической точки зрения, RTC добавляет в процесс денуазинга flow-matching член, направляющий перекрывающиеся временные шаги нового фрагмента оставаться близкими к выполненной части предыдущего фрагмента, как правило, используя маску мягкого перехода.

## Быстрый старт

### Установка

RTC встроен в LeRobot. Просто установите зависимости политики, которые вам нужны:

```bash
# For Pi0 or Pi0.5
pip install -e ".[pi]"

# For SmolVLA
pip install -e ".[smolvla]"
```

### Использование RTC с Pi0

Для развертывания RTC на реальных роботах можно использовать `lerobot-rollout --strategy.type=base --inference.type=rtc`. Ниже приведен упрощенный псевдопример того, как RTC работает с Pi0 в вашем конвейере:

```python
from lerobot.policies.pi0 import PI0Policy, PI0Config
from lerobot.configs import RTCAttentionSchedule
from lerobot.policies.rtc import RTCConfig, ActionQueue

# Load the Pi0 config so RTC can be enabled before the policy is built
policy_cfg = PI0Config.from_pretrained("lerobot/pi0_base")

# Enable RTC
policy_cfg.rtc_config = RTCConfig(
    enabled=True,
    execution_horizon=10,  # How many steps to blend with previous chunk
    max_guidance_weight=10.0,  # How strongly to enforce consistency
    prefix_attention_schedule=RTCAttentionSchedule.EXP,  # Exponential blend
)

# Load the policy
policy = PI0Policy.from_pretrained("lerobot/pi0_base", config=policy_cfg).to("cuda")

# Now use predict_action_chunk with RTC parameters
inference_delay = 4  # How many steps of inference latency, this value should be calculated based on the inference latency of the policy

# Initialize the action queue
action_queue = ActionQueue(policy_cfg.rtc_config)

# Start in a separate thread with the following function
def get_actions():
  while True:
    if should_get_actions:

      prev_actions = action_queue.get_left_over()
      obs = get_robot_observations(robot)

      # Generate actions WITH RTC
      actions = policy.predict_action_chunk(
          obs,
          inference_delay=inference_delay,
          prev_chunk_left_over=prev_actions,
      )

      action_queue.merge(
          actions, actions, inference_delay
      )

for step in range(num_steps):
    action = action_queue.get()

    # Execute the first N actions
    execute_actions(action)
```

## Ключевые параметры

`RTCConfig` имеет следующие параметры для настройки:

**`mode`** выбирает метод условного кодирования префикса действия:

- `guided` (по умолчанию) применяет исходное направление Якобиана на этапе денойзинга и работает с обычными чекпоинтами flow-matching.
- `trained` выполняет жёсткое инпейнтинг префикса предыдущего чанка с использованием шагов потока для каждого действия. В настоящее время требуется чекпоинт Pi05, обученный с параметром `policy.rtc_training_max_delay > 0`, и пропускает обратный проход для guidance.

Локальный rollout и сервер политики применяют одно и то же консервативное правило допуска в режиме обучения: `rtc_training_max_delay <= execution_horizon <= prediction_steps - rtc_training_max_delay`. Для Pi05 `prediction_steps` соответствует `chunk_size` контрольной точки. Это сохраняет существующее локальное ограничение: настроенный префикс покрывает максимальную обученную задержку и оставляет за его пределами не менее этого количества предсказанных шагов. Локальный rollout дополнительно требует, чтобы `inference.queue_threshold >= rtc_training_max_delay` перед подключением робота; тайминг удалённых запросов использует собственные настройки пополнения.

Здесь `execution_horizon` — это предоставленная ёмкость префикса, а не объём воспроизведения между запросами. Pi05 жёстко обусловливает только префикс `inference_delay`. Правило допуска не является гарантией задержки или утверждением о том, что более крупные ёмкости должны приводить к сбою во время выполнения; фактическое перекрытие, оставшиеся действия и проверки актуальности по-прежнему определяют, может ли возвращённый фрагмент быть выполнен. Обычные фрагменты и управляемый RTC не затрагиваются этим правилом, применимым только к обученным моделям.

**`execution_horizon`**: количество шагов времени от предыдущего фрагмента, с которым нужно поддерживать согласованность. Большие значения обеспечивают более плавные переходы, но могут снижать отзывчивость.

Типичные значения: 8–12 шагов

```python
RTCConfig(execution_horizon=10)
```

**`max_guidance_weight`**: Насколько строго обеспечивать согласованность с предыдущим фрагментом. Это гиперпараметр, который можно настроить для баланса между плавностью переходов и реактивностью политики. Для flow matching на 10 шагов (SmolVLA, Pi0, Pi0.5) оптимальным значением является 10.0.

**`prefix_attention_schedule`**: способ взвешивания согласованности в области перекрытия.

- `LINEAR`: линейное затухание от inference_delay до execution_horizon
- `EXP`: экспоненциальное затухание (рекомендуется для начала работы)
- `ONES`: полный вес на протяжении всего execution_horizon
- `ZEROS`: бинарный (полный вес до inference_delay, затем ноль)

**`inference_delay`**: количество шагов инференса, составляющих задержку вашей системы. Этот параметр передаётся в `predict_action_chunk()`, а не в конфигурацию, поскольку он может меняться во время выполнения.

## Тестирование RTC в автономном режиме

Перед запуском на реальном роботе протестируйте RTC на образцах из набора данных, чтобы визуализировать принцип его работы:

```bash
python examples/rtc/eval_dataset.py \
    --policy.path=lerobot/pi0_libero_finetuned \
    --dataset.repo_id=HuggingFaceVLA/libero \
    --rtc.execution_horizon=10 \
    --rtc.max_guidance_weight=10.0 \
    --device=cuda
```

Добавьте `--rtc.mode=trained` при оценке совместимого контрольного пункта обучения RTC Pi05. Неподдерживаемые политики отклоняют режим trained, а не переключаются на guided RTC.

Скрипт генерирует визуализацию процесса удаления шума, сравнивая стандартную генерацию (слева) с RTC (справа). На графиках RTC видно, как первые несколько шагов (синие/фиолетовые линии) направляются так, чтобы соответствовать красной траектории эталонных данных (хвост предыдущего чанка), что обеспечивает плавный переход между чанками.

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/flow_matching.png"
    alt="Denoising steps with and without RTC"
    width="100%"
  />

## Тестирование RTC на реальном роботе

```bash
lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USERNAME}/policy_repo_id \
    --inference.type=rtc \
    --inference.rtc.mode=guided \
    --inference.rtc.execution_horizon=10 \
    --inference.rtc.max_guidance_weight=10.0 \
    --robot.type=so100_follower \
    --robot.port=/dev/tty.usbmodem58FA0834591 \
    --robot.cameras="{ gripper: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --task="Move green small object into the purple platform" \
    --duration=120 \
    --device=cuda
```

Для контрольной точки RTC Pi05, предназначенной для обучения, измените режим на `trained`. Контрольная точка фиксирует максимальную поддерживаемую задержку, а rollout проверяет измеренную задержку на соответствие этому значению:

```bash
lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USERNAME}/pi05_training_rtc \
    --inference.type=rtc \
    --inference.rtc.mode=trained \
    --inference.rtc.execution_horizon=10 \
    --robot.type=so100_follower \
    --robot.port=/dev/tty.usbmodem58FA0834591 \
    --task="Move green small object into the purple platform" \
    --duration=120 \
    --device=cuda
```

## Как RTC связан с удалённым выводом

`--inference.type=rtc` — это локальный RTC: инференс выполняется в фоновом потоке процесса rollout и не использует транспорт. Запуск policy-сервера и клиентского процесса робота как отдельных процессов на одной машине использует удалённый бэкенд.

Оба асинхронных бэкенда используют одинаковое [поведение ограниченного ожидания и завершения работы](./remote_inference#what-the-robot-does-while-waiting-or-stopping) на поддерживаемых роботах. См. [бюджеты локального RTC](./inference#inference-backends) для значений таймаутов по умолчанию. Ожидание не ослабляет проверки префикса, задержки или свежести в RTC.

Оба подхода — RTC и [удалённый вывод](./remote_inference) — улучшают управление роботами в реальном времени, но решают разные задачи.

| Аспект           | Удалённый вывод                                              | RTC                                                   |
| ---------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
| **Назначение**      | Запуск вывода в другом процессе или на другом компьютере       | Условные предсказания на оставшейся траектории     |
| **Выполнение**    | Локальное воспроизведение с буферизацией, необязательное выравнивание и смешивание      | Руководимое или обученное продолжение для поддерживаемых политик |
| **Связь** | Может обслуживать обычные фрагменты или RTC                                 | Можно выполнять локально или через удалённый бэкенд     |
| **Ограничения**       | Задержка, актуальность и покрытие буфера по-прежнему ограничивают движение | Требуется объявленный в политике контракт RTC           |

Удалённый вывод может использовать RTC, если контрольная точка поддерживает согласованный режим RTC. Обычные фрагменты также поддерживают необязательное выравнивание курсора и смешивание; см. [руководство по удалённому выводу](./remote_inference) для информации о режимах, совместимости и настройке.

## Дополнительно: отслеживание отладки

RTC включает встроенное отслеживание отладки, чтобы помочь вам понять, что происходит во время инференса:

```python
# Enable debug tracking
policy_cfg.rtc_config.debug = True
policy_cfg.rtc_config.debug_maxlen = 100
policy.init_rtc_processor()  # re-create the RTC processor so the new debug settings take effect

# After inference, access debug data
debug_data = policy.rtc_processor.get_all_debug_steps()

# Visualize denoising steps, corrections, etc.
from lerobot.policies.rtc.debug_visualizer import RTCDebugVisualizer
visualizer = RTCDebugVisualizer()
# ... create plots
```

См. `examples/rtc/eval_dataset.py` для полного примера офлайн-визуализации RTC.

## Ссылки

- [Плавные, как масло, политики роботов](https://alexander-soare.github.io/robotics/2025/08/05/smooth-as-butter-robot-policies.html) — Отличное техническое объяснение с результатами на реальном роботе
- [Physical Intelligence - Real-Time Chunking](https://www.physicalintelligence.company/research/real_time_chunking) — исходная статья и исследования
- [Реализация Kinetix RTC](https://github.com/Physical-Intelligence/real-time-chunking-kinetix) — эталонная реализация от Physical Intelligence
- [Условие на действие во время обучения](https://arxiv.org/abs/2512.05964) — Эффективный RTC с чистым префиксным условием во время обучения
- [RLDX-1](https://github.com/RLWRLD/RLDX-1) — эталонная реализация на PyTorch, используемая для интеграции RTC на этапе обучения