# リアルタイムチャンキング（RTC）

リアルタイムチャンキング（RTC）により、[Pi0](./pi0)、[Pi0.5](./pi05)、[SmolVLA](./smolvla) などの大規模なフローマッチングベースのロボティクスポリシーは、推論レイテンシが高いにもかかわらず、滑らかで連続的かつ反応性の高い動作を生成できます。LeRobot は、元の推論時のガイドモードを提供するとともに、互換性のある Pi05 チェックポイントに対して、安価なハードプレフィックス推論を用いた学習時のアクション条件付けをサポートしています。

これらのポリシーは、単一のアクションではなく、将来のアクションのチャンク（例えば、50ステップずつ）を生成します。モデルが大きいことから、各チャンクの生成には、ロボットがそれを実行する時間よりも長い時間がかかります。チャンクを単純に実行すると、次のチャンクが遅れて到着した場合や、以前に実行されたアクションと一致しない場合、停止、ぎこちない遷移、戦略の急激な変更などの問題が発生します。

RTCは、ロボットが現在のチャンクの実行を継続している間に次のチャンクを非同期で生成し、かつ新しいチャンクを前回のチャンクで既に実行済みの部分と滑らかに整合するよう誘導することで、この問題を解決します。

## RTCの仕組み（簡略化版）

RTCは、ロボットがまだ動作している間に先読みして考えさせます。ロボットがアクションの1チャンクを実行している間、RTCは次のチャンクの生成を早期に開始します。ただし、新しいチャンクが準備できた時点でロボットはすでに少し移動しているため、RTCは新しいチャンクがロボットが現在実行している動作と滑らかに整合するよう保証する必要があります。

これを実現するために、RTCは新しいチャンクの先頭をインペインティング（「隙間を埋める」）問題として扱います。新しいチャンクの最初の部分を穏やかに調整し、ロボットの進行中の動作と自然に調和するようにします。その結果、停止も急なジャンプも発生しません。

技術的な観点から言えば、RTCはフローマッチングのノイズ除去プロセスにガイダンス項を追加し、新しいチャンクの重複するタイムステップが、直前のチャンクの実行済み部分に近くなるように強制します。通常、ソフトトランジションマスクが使用されます。

## クイックスタート

### インストール

RTCはLeRobotに組み込まれています。必要なポリシーの依存関係をインストールするだけです:

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

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

### Pi0でのRTCの使用

実際のロボットでのRTCデプロイには、`lerobot-rollout --strategy.type=base --inference.type=rtc`を使用できます。以下は、パイプライン内でPi0がRTCとして動作する様子の簡略化された疑似例です。

```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`（デフォルト）は、デノイジング中に元のJacobianガイダンスを適用し、通常のflow-matchingチェックポイントと互換性があります。
- `trained`は、アクションごとのフロータイムステップを用いて、直前のチャンクのプレフィックスをハードインペイントします。現在、`policy.rtc_training_max_delay > 0`で学習されたPi05チェックポイントが必要であり、ガイダンスのバックワードパスを回避します。

ローカルロールアウトとポリシーサーバーは、同じ保守的な学習モードの受け入れルールを適用します: `rtc_training_max_delay <= execution_horizon <= prediction_steps - rtc_training_max_delay`。Pi05 については、`prediction_steps` はチェックポイントの `chunk_size` です。これにより、既存のローカル制限が維持されます。設定されたプレフィックスは最大学習遅延をカバーし、その外側に少なくともその数の予測ステップを残します。ローカルロールアウトは、ロボットを接続する前に `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`**: 前のチャンクとの整合性をどの程度強く強制するかを示します。これは、遷移の滑らかさとポリシーの反応性のバランスを調整するためにチューニングできるハイパーパラメータです。10ステップのフローマッチング（SmolVLA、Pi0、Pi0.5）の場合、10.0が最適な値です。

**`prefix_attention_schedule`**: オーバーラップ領域における整合性をどのように重み付けするか。

- `LINEAR`: 推論遅延から実行地平線までの線形減衰
- `EXP`: 指数減衰（入門に推奨）
- `ONES`: 実行ホライズン全体にわたるフルウェイト
- `ZEROS`: バイナリ（推論遅延までの全重み、その後ゼロ）

**`inference_delay`**: システムの推論レイテンシのタイムステップ数です。実行時に値が変わる可能性があるため、設定ではなく`predict_action_chunk()`に渡します。

## RTCのオフラインでのテスト

実際のロボットで実行する前に、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 の Pi05 チェックポイントを評価する場合は、`--rtc.mode=trained` を追加してください。サポートされていないポリシーは、guided RTC にフォールバックするのではなく、trained モードを拒否します。

このスクリプトは、標準的な生成（左）と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`に変更します。チェックポイントはサポートされる最大遅延を記録しており、ロールアウトは測定されたレイテンシをそれに対して検証します:

```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 です。推論はロールアウトプロセス内のバックグラウンドスレッドで実行され、トランスポートは使用されません。同じマシン上でポリシーサーバーとロボットクライアントを別々のプロセスとして実行する場合は、リモートバックエンドが使用されます。

非同期バックエンドの両方は、対応するロボット上で同じ[有界待機とシャットダウンの動作](./remote_inference#what-the-robot-does-while-waiting-or-stopping)を使用します。タイムアウトのデフォルト値については、[ローカル RTC の予算](./inference#inference-backends)を参照してください。待機は、RTC のプレフィックス、遅延、鮮度チェックを緩和しません。

RTCと[リモート推論](./remote_inference)はどちらもリアルタイムのロボット制御を改善しますが、解決する問題は異なります。

| アスペクト           | リモート推論                                              | RTC                                                   |
| ---------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
| **目的**      | 別のプロセスまたは別のコンピューターで推論を実行する       | 残りの軌道について条件付き予測を行う     |
| **実行**    | ローカルバッファード再生、任意の整列およびブレンド      | サポートされているポリシー向けのガイド付きまたは学習済み継続 |
| **関係** | プレーンチャンクまたはRTCを提供できます                                 | ローカルで、またはリモートバックエンドを介して実行できます     |
| **制限事項**       | レイテンシ、鮮度、バッファカバレッジが依然としてモーションを制約しています | ポリシーが宣言したRTC契約が必要です           |

Remote inference は、チェックポイントが交渉された RTC モードをサポートしている場合に RTC を使用できます。プレーンチャンクも、オプションのカーソルアライメントとブレンドをサポートしています。モード、互換性、チューニングについては、[remote inference ガイド](./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
```

オフライン RTC 可視化の完全な例については、`examples/rtc/eval_dataset.py`を参照してください。

## 参考文献

- [なめらかで安定したロボットポリシー](https://alexander-soare.github.io/robotics/2025/08/05/smooth-as-butter-robot-policies.html) - 実際のロボットでの結果を伴う優れた技術的解説
- [Physical Intelligence - リアルタイムチャンキング](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) - 学習時のRTC統合に使用されるPyTorchの参照実装

