Inferência Remota

Políticas grandes exigem uma GPU, e com um rollout síncrono o robô para de se mover toda vez que a política calcula seu próximo conjunto de ações. A inferência remota divide a tarefa em duas: um servidor de política executa o checkpoint em uma GPU, e o computador do robô mantém o controle das câmeras, motores, teleoperação e gravação. O robô continua executando as ações que já possui enquanto o servidor calcula as próximas, de modo que o movimento não mais pausa para a inferência.

Use-o quando:

• o computador conectado ao robô não possui GPU, ou possui uma GPU pequena demais para a política: um notebook ou computador de placa única ao lado do braço e uma estação de trabalho com GPU do outro lado do laboratório;
• a inferência consome uma fração perceptível de cada bloco de ações e você deseja movimento contínuo;
• você deseja decidir com que frequência o robô replaneja sem tocar no checkpoint.

O único compromisso que você ajusta é frescor versus continuidade. Pedir um novo plano mais cedo permite que o robô reaja ao que ele vê; seguir mais do plano atual preserva o progresso da tarefa.

Como funciona

O computador do robô mantém um buffer de ações futuras. Quando o buffer fica baixo, ele envia uma nova observação, continua se movendo a partir do buffer enquanto o servidor calcula e insere o novo trecho na parte do plano que ainda não foi executada.

Três configurações do cliente definem esse comportamento. refill_seconds determina com antecedência solicitar o próximo plano, chunk_merge determina como o novo plano é integrado ao antigo, e o blending suaviza a transição entre eles. O servidor precisa apenas do checkpoint e de uma descrição do robô para o qual foi treinado. As seções abaixo partem de uma configuração funcional e, em seguida, constroem a intuição para cada configuração.

RTC local (--inference.type=rtc) é a outra opção assíncrona: a inferência é executada em uma thread em segundo plano do processo de rollout, na mesma máquina, sem um servidor. A inferência remota no mesmo host ainda usa dois processos e --inference.type=remote, e oferece alinhamento e blending para políticas sem RTC. Veja como o RTC se relaciona com a inferência remota.

Políticas e robôs suportados

Um checkpoint pode ser servido quando seus processadores salvos preveem um chunk de ações a partir de uma única observação atual; o ACT precisa do ensembling temporal desabilitado. Checkpoints de ACT, SmolVLA, XVLA, EVO1 e LaWAM já foram executados em robôs reais por meio deste caminho. Vários outros policies são suportados no nível do contrato, mas não foram validados em hardware, e policies dependentes de histórico precisam de integração adicional. A tabela de suporte de policies lista o status e as restrições de cada policy.

O driver do robô deve declarar suporte à manutenção de posição, pois o cliente atualiza o último alvo aplicado enquanto aguarda as ações. SO, OMX, Koch, HopeJr, Rebot e os seguidores YAM o declaram; OpenArm, Reachy2 e os wrappers bimanuais dependem de sua configuração; o Unitree G1 o declara apenas com o controlador SONIC, cujo alvo retido é o último token de movimento; as bases móveis não declaram. Consulte a tabela de hardware. Contratos de robô ou de política não suportados são rejeitados na admissão, antes de qualquer movimento.

Comece com um rollout funcional

Mantenha um comando lerobot-rollout síncrono bem-sucedido como referência e preserve suas configurações de robô, câmeras, tarefa, FPS, teleoperador e interpolação. O checkpoint e o dispositivo do modelo são movidos para o servidor; o cliente remoto não carrega os pesos.

Os exemplos abaixo descrevem um SO-101 genérico com seis atuadores e uma câmera frontal. Adapte o checkpoint, as visões da câmera, a ordem dos componentes e as unidades de forma consistente.

1. Instale nos dois computadores

Ambos os lados precisam do extra remote. Mantenha os extras de hardware no cliente e o extra da política selecionada no servidor:

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

O intervalo de versões do Zenoh suportado é >=1.9.0,<1.11.0; uv sync --locked instala a versão do lockfile, atualmente 1.10.1.

2. Configure e inicie o servidor

Copie a configuração genérica e, em seguida, edite-a:

cp examples/remote_inference/server.yaml server.yaml

Defina model.repo_or_path e model.device. Para um checkpoint do Hub, fixe model.revision no commit que você pretende validar. Alinhe features, action_feature, semantics, robot_type e execution.action_fps ao seu ambiente de trabalho; veja os exemplos de esquema e renomeação de câmeras abaixo.

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

O servidor carrega o checkpoint, valida suas declarações, executa o warmup e, em seguida, registra Policy server ready: deployment=<name> instance=<id>; awaiting one client. Cada campo YAML aceita uma substituição aninhada via CLI:

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

3. Inicie o cliente do robô

Em outro terminal, adapte os argumentos de hardware para a mesma configuração:

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

Após a admissão, digite /start. /stop encerra a execução; consulte o que o robô faz enquanto espera ou para. Mantenha as opções de teleoperação e gravação do seu rollout de trabalho. Não passe --policy.path, substituições locais de modelo-dispositivo ou flags de compilação para o cliente remoto.

deployment seleciona o servidor e semantics nomeia as unidades de ação validadas e a ordem; ambos devem corresponder à configuração do servidor. O exemplo usa graus das articulações do corpo e uma faixa calibrada de pinça de 0 a 100.

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

Escolha como continuar o movimento

Quando um novo chunk chega, a observação a partir da qual ele foi calculado já está um pouco desatualizada, e o robô já se moveu. O modo de mesclagem decide o que fazer a respeito disso: reproduzir o novo chunk após o antigo, descartar os passos que o robô já percorreu, ou suavizar a junção.

As configurações desta tabela usam o prefixo --inference.. Chunks simples têm alinhamento como padrão, com blending desativado. Um alvo que já está sendo interpolado é confirmado e não pode ser substituído.

Alignment descarta os passos recebidos que já foram confirmados. Blending calcula a média dos alvos futuros sobrepostos. Interpolation adiciona comandos motores intermediários entre os pontos finais. RTC altera a forma como a previsão é gerada. Nenhum deles garante movimento suave ou uma pegada bem-sucedida.

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

Parâmetros que importam

As opções de cliente abaixo usam o prefixo --inference., a menos que indicado o contrário. Os valores padrão são valores iniciais, não garantias para um robô específico.

O refill efetivo é max(refill_seconds, recent maximum turnaround + 1 / fps). O turnaround inclui codificação, rede, fila, inferência e decodificação. A primeira solicitação aceita fornece uma estimativa inicial; as estimativas posteriores usam até 100 amostras em estado estacionário.

Refill, portanto, não é um período de solicitação fixo nem um número garantido de ações executadas. Inspecione o refill configurado e efetivo nos logs. Um limiar que cubra todo o horizonte de execução causa substituições muito frequentes.

O que o robô faz enquanto espera ou para

Durante uma espera suportada, o cliente atualiza o último alvo efetivamente aplicado pelo driver, incluindo interpolação, clipping e o garra. Antes do primeiro comando, uma pose medida o inicializa. Isso interrompe o avanço da trajetória; o robô ainda pode se estabilizar em direção a esse alvo. Isso não desliga o torque nem garante imobilidade. O RTC local usa a mesma espera limitada em robôs suportados e falha imediatamente em outros casos.

A recuperação de inanição descarta uma previsão antiga em andamento e obtém uma previsão nova a partir de uma captura realizada após o início da espera. Resultados antigos não podem reiniciar o movimento. Pacotes e resultados inutilizáveis não renovam a tolerância. Esperas frequentes indicam cobertura insuficiente de reprodução ou latência.

A perda do servidor ou da conexão não é recuperada automaticamente. Ações em buffer válidas podem ser esgotadas, seguidas de espera até que o prazo de tolerância ou outro prazo limite expire. Uma vez que a presença do servidor seja observada como perdida, aquela sessão não pode ser retomada quando a conectividade retornar; reinicie o rollout para uma nova sessão. Durante o trabalho com texto, a perda do servidor observada falha a consulta.

Com a aquisição de observações e o controle dos atuadores funcionando corretamente, o encerramento do terminal respeita --return_to_initial_position=true (o padrão) e, em seguida, desconecta. O retorno lê uma observação completa, portanto, uma falha persistente na câmera pode impedi-lo. Uma ação falha ou a aplicação de um bloqueio suprimem movimentos adicionais. Definir a opção como false ignora o retorno, mas não a desconexão. A desconexão pode liberar o torque de acordo com a configuração do robô. Falhas no terminal encerram com um status não nulo após a limpeza; um processo encerrado à força não pode garantir a limpeza.

Ajuste uma tarefa funcional

Comece perto da referência síncrona: execute uma parte substancial de cada previsão, mas solicite com antecedência suficiente para ocultar a latência de inferência. Em seguida, avalie se um replanejamento mais frequente ajuda.

1. Use alinhamento sem blending primeiro. Mantenha FPS, interpolação e configuração fixos. Inspecione o horizonte de execução, o tempo total de processamento e as solicitações lentas.
2. Escolha a cobertura de reposição com margem. Deixe reprodução suficiente para outra solicitação e variação de latência, sem substituir continuamente o plano.
3. Adicione um blend curto nessa cadência. Compare a conclusão da tarefa, a pegada/soltura e os choques separadamente. Uma média suave de planos incompatíveis pode perder o objeto.
4. Solicite antecipadamente apenas por benefício. Aumentar a reposição pode melhorar a responsividade, mas interromper o progresso útil. Retorne ao ritmo estável se o desempenho da tarefa piorar.
5. Altere uma configuração por vez. Aumentar timeouts ou grace não fornece as ações ausentes. Reduzir refill não é uma cura universal para o esgotamento.

Para um horizonte de execução de 0.8 s e alinhamento bem-sucedido constante, o espaçamento entre solicitações é aproximadamente 0.8 - effective_refill:

Isso exclui os efeitos de inicialização, retenção, saturação e tique de controle. Uma solicitação que começa com 0.2 s restantes e leva 0.1 s deixa apenas 0.1 s para a mistura, três passos a 30 Hz. Portanto, uma cadência quase síncrona pode exigir apenas uma mistura curta.

Para alinhamento e RTC, verifique o tempo de reprodução utilizável após o corte, e não o comprimento nominal do chunk. Se a inferência leva 1 segundo de uma previsão de 1,67 segundos, restam apenas cerca de 0,67 segundos. Uma solicitação de mais 1 segundo não cabe; nenhum valor de refill resolve isso. Reduza o tempo de resposta, use um horizonte suportado mais longo ou valide uma frequência de ação diferente.

A idade da fonte inclui a execução. Para append, permita aproximadamente execution horizon + effective refill mais uma margem de captura/inferência. Um bloco de 100 passos a 30 Hz já abrange 3,33 segundos. O alinhamento geralmente reduz a idade, mas o blending repetido pode reter contribuidores mais antigos.

Leia os logs e diagnostique uma execução

Os logs de INFO exibem as configurações de admissão e efetivas, os resultados das solicitações de texto, as transições de espera/desligamento e um resumo de atividade a cada cinco segundos. Leia o tempo de resposta e a reprodução enfileirada juntos. Para detalhes, use o servidor com --log_level=DEBUG e o cliente com --inference.log_level=DEBUG. Sessões interativas silenciam os logs do cliente abaixo de ERROR; use uma execução não interativa ao coletar logs de tempo em tempo real.

Ao salvar os logs, use 2>&1 | tee -i server.log (ou client.log). O -i mantém o tee ativo quando o Ctrl+C atinge todo o pipeline, de modo que ele também capture as mensagens de encerramento gracioso.

DEBUG inclui a reprodução de cada solicitação no momento do envio, a idade da observação e o progresso do cursor, além das etapas aparadas/usáveis e a sobreposição por resultado. Esses dados descrevem o progresso comandado, não a execução física medida.

Configuração e rede

Mantenha um único YAML de deployment para checkpoint, esquema do robô e configurações do servidor; use sobrescritas aninhadas da CLI para experimentos. Dê nomes de deployment diferentes para experimentos independentes. Ambos os processos registram suas versões de pacote e de protocolo; a admissão verifica o protocolo e os contratos de execução/dados, sem exigir versões de pacote idênticas.

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

Idioma e gravação

Use /vqa, /subtask e /autosteer por meio de interactive rollout. Ative language.enabled=true no servidor apenas em um checkpoint que implemente geração de texto; o autosteering exige, adicionalmente, um checkpoint treinado para geração de subtasks com prompting compatível de goal/subtask. O servidor expõe esses comandos quando o checkpoint declara a capacidade; se as respostas e subtasks são úteis depende do checkpoint.

O trabalho de texto pausa o movimento e descarta a continuação em buffer. O VQA mantém sua instrução e retoma com uma nova previsão, de modo que o robô pode perder o progresso da tarefa ao replanejar, mesmo após uma resposta bem-sucedida. Manter o movimento em buffer em execução durante uma consulta VQA informativa está planejado; veja trabalhos futuros.

A gravação usa o formato local padrão de dataset. Os rótulos de tarefa seguem a ação despachada. Os diagnósticos permanecem nos logs da aplicação; eles não são gravados no dataset nem enviados. Com um dataset, use --dataset.single_task para a instrução inicial; caso contrário, use --task. Prefira um para evitar configurações conflitantes.

Use-o a partir do Python

Os motores e a configuração compartilhados estão em lerobot.inference; o cliente remoto, o motor e o servidor estão em lerobot.remote_inference. Um loop de controle fora do lerobot-rollout conecta e aceita um cliente, o envolve em um motor, publica as capturas e despacha cada tick do motor através de dispatch_tick, que aplica o mesmo contrato de permissão, retenção e confirmação que a CLI:

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

As observações são indexadas pelos nomes de recursos voltados para o checkpoint e devem corresponder ao esquema do servidor: vetores float32 na ordem dos componentes declarada, imagens RGB uint8 do tamanho declarado. tests/remote_inference/test_library_client.py executa esse caminho contra um servidor loopback e é a referência para a sequência de chamadas. lerobot-rollout adiciona conversão do driver, verificações de posição fixa, comandos interativos e gravação por cima disso; lerobot-policy-server é o ponto de entrada de serviço e é configurado apenas por meio de suas substituições YAML e CLI.

Para a arquitetura, os contratos de execução e as extensões planejadas, consulte a referência de design de engenharia.