원격 추론

큰 정책은 GPU가 필요하며, 동기식 롤아웃에서는 정책이 다음 액션 청크를 계산할 때마다 로봇의 움직임이 멈춥니다. 원격 추론은 이 작업을 두 부분으로 나눕니다. 정책 서버는 GPU에서 체크포인트를 실행하고, 로봇 컴퓨터는 카메라, 모터, 텔레오퍼레이션 및 녹화를 계속 제어합니다. 서버가 다음 액션을 계산하는 동안 로봇은 이미 가진 액션을 계속 실행하므로, 더 이상 추론을 위해 움직임이 중단되지 않습니다.

사용 시점:

• 로봇에 연결된 컴퓨터에 GPU가 없거나 정책(policy)에 필요한 용량보다 작은 GPU만 있는 경우: 로봇 팔 옆에 노트북이나 싱글보드 컴퓨터가 있고, 실험실 건너편에 GPU 워크스테이션이 있는 환경
• inference가 각 액션 청크의 상당한 부분을 차지하며 연속적인 동작이 필요한 경우
• checkpoint에 직접 접근하지 않고 로봇이 재계획을 수행하는 빈도를 결정하려면

조율해야 하는 유일한 트레이드오프는 신선도와 연속성입니다. 새로운 계획을 더 빨리 요청하면 로봇이 현재 보고 있는 상황에 반응할 수 있고, 현재 계획을 더 많이 따르면 작업 진행 상황을 유지할 수 있습니다.

작동 방식

로봇 컴퓨터는 예정된 동작의 버퍼를 유지합니다. 버퍼의 용량이 부족해지면 새로운 관측치를 전송하고, 서버가 계산하는 동안 버퍼에서 동작을 계속 수행하며, 아직 실행되지 않은 계획의 일부에 새로운 청크를 삽입합니다.

세 가지 클라이언트 설정이 이 동작을 결정합니다. refill_seconds는 다음 계획을 얼마나 일찍 요청할지, chunk_merge는 새 계획을 기존 계획에 어떻게 결합할지, 블렌딩은 두 계획 사이의 이음을 부드럽게 만듭니다. 서버에는 체크포인트와 학습에 사용된 로봇의 설명만 필요합니다. 아래 섹션은 작동하는 설정에서 시작하여 각 설정에 대한 직관을 쌓아가도록 구성되었습니다.

Local RTC(--inference.type=rtc)는 다른 비동기 옵션입니다. 추론은 서버 없이 동일한 머신에서 rollout 프로세스의 백그라운드 스레드에서 실행됩니다. 동일한 호스트에서 원격 추론은 여전히 두 개의 프로세스와 --inference.type=remote를 사용하며, RTC가 없는 정책의 정렬 및 블렌딩을 제공합니다. RTC와 원격 추론의 관계를 참조하세요.

지원되는 정책 및 로봇

저장된 프로세서가 단일 현재 관측으로부터 액션 청크를 예측할 수 있을 때 체크포인트를 서빙할 수 있습니다. ACT의 경우 시간적 앙상블(temporal ensembling)이 비활성화되어 있어야 합니다. ACT, SmolVLA, XVLA, EVO1, LaWAM 체크포인트는 이 경로를 통해 실제 로봇에서 실행된 바 있습니다. 여러 다른 정책은 계약 수준에서 지원되지만 하드웨어에서 검증되지 않았으며, 히스토리에 의존하는 정책은 추가적인 통합이 필요합니다. 정책 지원 테이블에는 모든 정책의 상태와 제한 사항이 나열되어 있습니다.

로봇 드라이버는 클라이언트가 동작을 기다리는 동안 마지막으로 적용된 타겟을 갱신하기 때문에 위치 유지(position-hold) 지원을 선언해야 합니다. SO, OMX, Koch, HopeJr, Rebot 및 YAM 팔로우러는 이를 선언합니다. OpenArm, Reachy2 및 양팔(bimanual) 래퍼는 구성에 따라 다릅니다. Unitree G1은 SONIC 컨트롤러와 함께 사용할 때만 이를 선언하며, 이 경우 유지되는 타겟은 마지막 모션 토큰입니다. 모바일 베이스는 이를 지원하지 않습니다. 하드웨어 표를 참조하세요. 지원되지 않는 로봇 또는 정책 계약은 어떤 동작도 수행하기 전에 승인 단계에서 거부됩니다.

작동하는 rollout에서 시작

성공적으로 실행된 동기식 lerobot-rollout 명령을 참고용으로 유지하고, 해당 명령의 로봇, 카메라, 작업, FPS, 텔레오퍼레이터 및 보간 설정을 그대로 유지하세요. 체크포인트와 모델 디바이스는 서버로 이동하며, 원격 클라이언트는 가중치를 로드하지 않습니다.

아래 예시는 전면 카메라 1개가 장착된 범용 6-액추에이터 SO-101를 설명합니다. 체크포인트, 카메라 뷰, 구성 요소 순서 및 단위를 함께 조정하세요.

1. 두 컴퓨터 모두에 설치

양쪽 모두 remote 추가 항목이 필요합니다. 하드웨어 추가 항목은 클라이언트에, 선택된 정책의 추가 항목은 서버에 유지하세요:

uv sync --locked --extra remote --extra core_scripts --extra feetech
# Add the policy extra on the server when required, for example --extra pi.

지원되는 Zenoh 범위는 >=1.9.0,<1.11.0입니다. uv sync --locked은 현재 1.10.1인 lockfile 버전을 설치합니다.

2. 서버 구성 및 시작

일반 구성을 복사한 후 편집합니다:

cp examples/remote_inference/server.yaml server.yaml

model.repo_or_path와 model.device를 설정합니다. Hub 체크포인트의 경우, 검증하려는 커밋에 model.revision을 고정합니다. features, action_feature, semantics, robot_type, execution.action_fps를 현재 작업 환경에 맞게 일치시키세요. 아래 스키마 및 카메라 이름 변경 예시를 참고하세요.

uv run --no-sync lerobot-policy-server --config_path=server.yaml

서버는 체크포인트를 로드하고, 선언을 검증한 후 워밍업을 실행하며, 그런 다음 Policy server ready: deployment=<name> instance=<id>; awaiting one client을 기록합니다. 모든 YAML 필드는 중첩된 CLI 오버라이드를 지원합니다:

uv run --no-sync lerobot-policy-server --config_path=server.yaml \
  --model.device=cuda \
  --execution.idle_timeout_s=10

3. 로봇 클라이언트 시작

다른 터미널에서 하드웨어 인수를 동일한 구성에 맞게 조정합니다:

uv run --no-sync lerobot-rollout \
  --inference.type=remote \
  --inference.endpoint=tcp/127.0.0.1:7447 \
  --inference.deployment=manipulation \
  --inference.mode=chunk \
  --inference.chunk_merge=aligned \
  --inference.semantics=so101-degrees-gripper-percent-v1 \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.use_degrees=true \
  --robot.cameras='{front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}' \
  --fps=30 \
  --task="pick up the cube" \
  --interactive=true

입원 후 /start를 입력합니다. /stop은 실행을 종료하며, 로봇이 대기하거나 정지하는 동안 수행하는 작업을 참조하세요. 작동 중인 롤아웃의 텔레오퍼레이션 및 녹화 옵션을 유지합니다. 원격 클라이언트에 --policy.path, 로컬 모델-장치 오버라이드 또는 컴파일 플래그를 전달하지 마세요.

deployment은 서버를 선택하고 semantics는 검증된 동작 단위와 순서를 지정합니다. 두 값 모두 서버 구성과 일치해야 합니다. 예시에서는 몸체 관절의 자유도와 보정된 0~100 그리퍼 범위를 사용합니다.

uv run --no-sync lerobot-policy-server --config_path=server.yaml \
  --zenoh.listen_endpoints='[tcp/172.18.133.214:7447]'

움직임을 계속하는 방법을 선택합니다

새로운 chunk가 도착할 때쯤이면, 해당 chunk를 계산하는 데 사용된 관측(observation)은 이미 약간 오래된 상태이며 로봇은 이미 이동한 뒤입니다. merge mode는 이 상황에 대해 어떻게 처리할지 결정합니다: 이전 chunk 뒤에 새로운 chunk를 재생하거나, 로봇이 이미 지나간 스텝을 제거하거나, 연결 지점을 부드럽게 매끄럽게 처리하는 것입니다.

이 표의 설정은 --inference. 접두사를 사용합니다. 일반 청크는 블렌딩이 비활성화된 정렬을 기본값으로 사용합니다. 이미 보간 중인 대상은 커밋되며 대체할 수 없습니다.

Alignment은 이미 커밋된 수신 스텝을 폐기합니다. Blending은 겹치는 미래 타겟을 평균화합니다. Interpolation은 엔드포인트 사이에 중간 모터 명령을 추가합니다. RTC는 예측이 생성되는 방식을 변경합니다. 이 중 어느 것도 매끄러운 움직임이나 성공적인 그랩을 보장하지 않습니다.

--inference.chunk_merge=aligned \
--inference.blend_steps=5 \
--inference.blend_weight=0.5 \
--inference.blend_components='[shoulder_pan.pos, shoulder_lift.pos, elbow_flex.pos, wrist_flex.pos, wrist_roll.pos]'

uv run --no-sync lerobot-policy-server --config_path=server.yaml \
  --execution.supported_modes='[rtc_guided]' \
  --execution.rtc.enabled=true \
  --execution.rtc.mode=guided \
  --execution.rtc.execution_horizon=15

중요한 매개변수

아래의 Client 옵션은 별도로 명시되지 않는 한 --inference. 접두사를 사용합니다. 기본값은 시작 값일 뿐, 특정 로봇에 대한 보장은 아닙니다.

효과적인 리필은 max(refill_seconds, recent maximum turnaround + 1 / fps)입니다. 턴어라운드는 인코딩, 네트워크, 큐잉, 추론 및 디코딩을 포함합니다. 처음 수락된 요청이 초기 추정치를 제공하고, 이후 추정치는 최대 100개의 정상 상태 샘플을 사용합니다.

따라서 Refill은 고정된 요청 주기나 실행되는 동작의 보장된 수가 아닙니다. 로그에서 구성된 and effective refill을 확인하세요. 전체 실행 지평을 커버하는 임계값은 매우 빈번한 대체를 유발합니다.

대기 또는 정지 중 로봇의 동작

지원되는 대기 동안, 클라이언트는 보간, 클리핑 및 그리퍼를 포함하여 드라이버가 실제로 적용한 마지막 목표를 새로고침합니다. 첫 번째 명령 전에, 측정된 포즈가 이를 초기화합니다. 이는 궤적 진행을 중단하며, 로봇은 해당 목표 방향으로 안정화될 수 있습니다. 이는 토크를 끄거나 정지를 보장하지 않습니다. 로컬 RTC는 지원되는 로봇에서 동일한 제한된 대기를 사용하며, 다른 환경에서는 소진 시 즉시 오류를 발생시킵니다.

Starvation recovery는 오래된 in-flight 예측을 제거하고, 대기 시작 이후에 캡처된 새로운 예측을 가져옵니다. 오래된 결과로는 모션을 재개할 수 없습니다. 패킷과 사용 불가능한 결과는 grace를 갱신하지 않습니다. 빈번한 대기는 재생 또는 지연 시간 커버리지가 부족함을 나타냅니다.

서버 또는 연결 손실은 자동으로 복구되지 않습니다. 버퍼링된 유효한 작업이 소진된 후, grace 또는 다른 마감 시간이 만료될 때까지 대기합니다. 서버 존재가 손실된 것으로 관찰되면, 연결이 복구되어도 해당 세션을 재개할 수 없으며, 새 세션을 위해 롤아웃을 다시 시작해야 합니다. 텍스트 작업 중 서버 손실이 관찰되면 쿼리가 오류 상태로 전환됩니다.

정상적인 관측 수집과 액추에이터 제어 하에서, 터미널 종료 시 --return_to_initial_position=true(기본값)를 준수한 후 연결을 해제합니다. 반환 과정에서는 전체 관측을 읽기 때문에, 영구적인 카메라 장애가 반환을 방해할 수 있습니다. 실패한 액션 또는 홀드 적용은 추가적인 이동을 억제합니다. 해당 옵션을 false로 설정하면 반환은 건너뛰지만 연결 해제는 수행됩니다. 연결 해제 시 로봇 구성에 따라 토크가 해제될 수 있습니다. 터미널 실패는 클린업 후 비영 상태 코드로 종료되며, 강제 종료된 프로세스는 클린업을 보장할 수 없습니다.

작동하는 작업 하나 조정하기

동기식 참조 지점 근처에서 시작하세요. 각 예측의 상당 부분을 실행하되, 추론 지연을 가릴 수 있을 만큼 충분히 일찍 요청합니다. 그런 다음 더 빈번한 재계획이 도움이 되는지 평가해 보세요.

1. 먼저 블렌딩 없이 정렬을 사용하세요. FPS, 보간 및 설정을 고정하세요. 실행 지평선, 전체 턴어라운드 및 느린 요청을 검사하세요.
2. 여유를 두고 재충전 범위를 선택합니다. 다른 요청과 지연 시간 변동에 대비해 충분한 재생 시간을 확보하되, 계획을 지속적으로 교체하지 않습니다.
3. 해당 주기에서 짧은 블렌드를 추가하세요. 작업 완료, 그립/해제, 충돌을 각각 비교하세요. 호환되지 않는 계획의 매끄러운 평균은 물체를 놓칠 수 있습니다.
4. 혜택이 있을 때만 더 일찍 요청하세요. 리필을 늘리면 응답성이 향상될 수 있지만 유용한 진행을 방해할 수도 있습니다. 작업 성능이 저하되면 안정적인 리듬으로 되돌아가세요.
5. 한 번에 하나의 설정만 변경하세요. 타임아웃이나 grace를 늘리는 것은 누락된 작업을 제공하지 않습니다. refill을 줄이는 것이 고갈에 대한 보편적인 해결책이 아닙니다.

0.8 s 실행 지평선과 안정적 성공 정렬을 위해, 요청 간격은 대략 0.8 - effective_refill입니다:

이 값에는 시작, 홀드, 포화 및 제어 틱 효과가 제외됩니다. 0.2 s가 남아 있는 상태에서 시작되어 0.1 s가 소요되는 요청은 블렌딩에 0.1 s만 남게 되며, 이는 30 Hz에서 3단계에 해당합니다. 따라서 거의 동기화된 주기는 짧은 블렌딩만 필요할 수 있습니다.

정렬 및 RTC의 경우, 명목상 청크 길이가 아닌 트림 후 사용 가능한 재생 시간을 확인하세요. 추론에 1.67초 예측 중 1초가 소요되면 약 0.67초만 남게 됩니다. 1초짜리 추가 요청은 수용할 수 없으며, 리필 값으로 이를 해결할 수 없습니다. 턴어라운드를 줄이거나, 더 긴 지원 지평선을 사용하거나, 다른 동작 주기를 검증하세요.

Source age에는 실행이 포함됩니다. append의 경우, 대략 execution horizon + effective refill에 capture/inference 마진을 더한 값을 허용합니다. 30 Hz에서 100-step 청크는 이미 3.33초에 걸쳐집니다. 정렬은 일반적으로 age를 줄이지만, 반복적인 블렌딩은 더 오래된 기여자를 유지할 수 있습니다.

로그를 읽고 실행을 진단합니다

INFO 로그는 승인 및 유효한 설정, 텍스트 요청 결과, 대기/종료 전환, 그리고 약 5초 간격의 활동 요약을 표시합니다. 읽기 처리 시간과 대기 중인 재생을 함께 확인하세요. 자세한 내용은 서버 --log_level=DEBUG와 클라이언트 --inference.log_level=DEBUG를 사용하세요. 인터랙티브 세션에서는 ERROR보다 낮은 클라이언트 로그가 음소거됩니다. 실시간 타이밍 로그를 수집할 때는 비인터랙티브 실행을 사용하세요.

로그을 저장할 때는 2>&1 | tee -i server.log(또는 client.log)를 사용하세요. -i는 Ctrl+C가 전체 파이프라인에 도달했을 때에도 tee가 유지되도록 하여, 정상 종료 메시지도 함께 캡처합니다.

DEBUG에는 각 요청의 제출 시 재생, 관찰 나이, 커서 진행률, 그리고 결과별 잘림/사용 가능 단계 및 중복이 포함됩니다. 이는 명령된 진행률을 설명하며, 측정된 물리적 실행을 나타내지 않습니다.

구성 및 네트워킹

체크포인트, 로봇 스키마, 서버 설정을 위한 배포 YAML을 하나로 유지하고, 실험에는 중첩된 CLI 오버라이드를 사용하세요. 독립적인 실험에는 서로 다른 배포 이름을 지정하세요. 두 프로세스 모두 패키지 및 프로토콜 버전을 기록하며, 수신은 프로토콜과 실행/데이터 계약을 확인하지만 동일한 패키지 버전을 요구하지 않습니다.

features:
  - name: observation.state
    shape: [6]
    dtype: float32
    names:
      [
        shoulder_pan.pos,
        shoulder_lift.pos,
        elbow_flex.pos,
        wrist_flex.pos,
        wrist_roll.pos,
        gripper.pos,
      ]
    semantics: so101-degrees-gripper-percent-v1
  - name: observation.images.front
    shape: [480, 640, 3]
    dtype: uint8
    kind: rgb
    semantics: rgb-front-table-v1

zenohd --config examples/remote_inference/zenoh/router.json5

uv run --no-sync lerobot-policy-server --config_path=server.yaml \
  --zenoh.mode=client \
  --zenoh.listen_endpoints='[]' \
  --zenoh.connect_endpoints='[tls/localhost:7447]' \
  --zenoh.config_file=examples/remote_inference/zenoh/server.json5

--inference.endpoint=tls/localhost:7447 \
--inference.zenoh_mode=client \
--inference.zenoh_config_path=examples/remote_inference/zenoh/robot.json5

LEROBOT_ZENOHD=/absolute/path/to/zenohd \
  uv run --no-sync pytest tests/remote_inference/test_zenoh.py -q -rs

언어 및 녹음

interactive rollout를 통해 /vqa, /subtask, /autosteer를 사용하세요. 서버의 language.enabled=true는 텍스트 생성을 구현한 체크포인트에서만 활성화해야 하며, autosteering은 호환되는 goal/subtask 프롬프팅으로 서브태스크 생성을 위해 학습된 체크포인트가 추가로 필요합니다. 서버는 체크포인트가 해당 기능을 선언할 때 이러한 명령을 노출하며, 답변과 서브태스크의 유용성은 체크포인트에 따라 달라집니다.

Text work은 동작을 일시 중지하고 버퍼링된 후속 작업을 폐기합니다. VQA는 사용자의 지시를 유지하고 새로운 예측으로 재개하므로, 로봇은 성공적인 답변 이후에도 재계획 시 작업 진행 상황을 잃을 수 있습니다. 정보 제공 목적의 VQA 쿼리 동안 버퍼링된 동작을 계속 실행하는 기능은 계획되어 있으며, 향후 작업을 참조하세요.

기록은 일반적인 로컬 데이터셋 형식을 사용합니다. 작업 라벨은 분배된 액션을 따릅니다. 진단 정보는 애플리케이션 로그에 유지되며 데이터셋에 기록되거나 업로드되지 않습니다. 데이터셋을 사용하는 경우 초기 지침에 --dataset.single_task를 사용하고, 그렇지 않은 경우 --task를 사용합니다. 충돌하는 구성을 피하기 위해 둘 중 하나를 우선적으로 사용하세요.

Python에서 사용

공용 엔진과 구성은 lerobot.inference에, 원격 클라이언트, 엔진 및 서버는 lerobot.remote_inference에 있습니다. lerobot-rollout 외부의 제어 루프는 클라이언트를 연결하고 허용한 뒤 엔진으로 감싸 캡처를 게시하고, 모든 모터 틱을 CLI와 동일한 권한, 홀드 및 확인 계약을 적용하는 dispatch_tick을 통해 분배합니다:

import time

import numpy as np

from lerobot.inference import RemoteInferenceConfig, dispatch_tick
from lerobot.remote_inference import RemoteClient, RemoteInferenceEngine
from lerobot.utils.action_interpolator import ActionInterpolator

config = RemoteInferenceConfig(
    endpoint="tcp/127.0.0.1:7447",
    deployment="manipulation",
    semantics="so101-degrees-gripper-percent-v1",
)
client = RemoteClient.connect(config)
caps = client.capabilities
client.admit(
    features=caps.features,
    action_feature=caps.action_feature,
    semantics=config.semantics,
    action_interval=caps.action_interval,
    mode=config.mode,
)
engine = RemoteInferenceEngine(client, config, task="pick up the cube")
interpolator = ActionInterpolator(multiplier=1)

engine.start()
engine.resume()
try:
    while running():
        captured = time.monotonic()
        engine.submit_observation(
            {"observation.state": state_vector(), "observation.images.front": front_rgb()},
            capture_time=captured,
        )
        # send() receives a torch tensor in the deployment's action order; hold() refreshes
        # the last applied target. Returns None when the tick was held or starved.
        dispatch_tick(engine, interpolator, send=robot_send, hold=robot_hold)
finally:
    engine.stop()  # revokes motion and closes the client

Observations은 체크포인트에서 사용하는 기능 이름으로 키가 지정되며 서버 스키마와 일치해야 합니다: 선언된 구성 요소 순서로 배치된 float32 벡터, 선언된 크기의 RGB uint8 이미지. tests/remote_inference/test_library_client.py는 이 경로를 루프백 서버에 대해 실행하며 호출 순서의 기준이 됩니다. lerobot-rollout는 이 위에 드라이버 변환, 위치 유지 확인, 인터랙티브 명령 및 녹화를 추가합니다. lerobot-policy-server는 서빙 진입점이며 YAML 및 CLI 오버라이드로만 구성됩니다.

아키텍처, 실행 계약 및 계획된 확장 기능에 대해서는 엔지니어링 디자인 참고 자료를 참조하세요.