Grave Seu Primeiro Dataset LeRobot Com um SO-100

Um SO-100 seguidor, um braço líder do mesmo design e duas câmeras USB podem ajustar uma política em uma tarde. A mesma bancada pode facilmente produzir sessenta episódios que parecem saudáveis em um navegador de arquivos e desperdiçar uma execução de GPU de seis horas. A diferença raramente é o modelo; é o que aconteceu entre os servos e o arquivo parquet.

Aqui está a rota manual, depois a mais curta. Cada comando é do lerobot 0.6.1, lançado em 3 de agosto de 2026 e atual no PyPI. Ele mudou para pontos de entrada de console, então tutoriais que executam python lerobot/scripts/control_robot.py descrevem um arquivo que não existe mais.

O que uma sessão de gravação captura

Um conjunto de dados LeRobot não é uma pasta de vídeos, mas uma tabela indexada por tempo com vídeo anexado: cada ciclo de controle escreve uma linha contendo a ação comandada, o estado que o seguidor alcançou, um quadro por câmera, um carimbo de data/hora e índices. A política vê apenas essas colunas. O esquema de lerobot/svla_so100_pickplace, lido de seu meta/info.json.

As juntas são main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll e main_gripper: os seis graus de liberdade do SO-100. A ação e o estado compartilham uma forma porque a teleoperação líder-seguidor registra um alvo e a posição alcançada um passo depois. Essa lacuna é informação: onde o braço lutou contra a gravidade ou um objeto preso. Essas strings são desse conjunto de dados. Uma sessão gravada com 0.6.1 hoje escreve shoulder_pan.pos até gripper.pos, IDs 1 a 6 no barramento: as mesmas seis juntas, chaves diferentes, o que importa no momento em que uma configuração aborda uma característica pelo nome.

O que você precisa na bancada

Se o braço ainda não foi construído, isso é uma tarefa para outra noite: comece em Introdução ao SO-100 e o guia completo de configuração do SO-100. Se você ainda não comprou nada, leia a comparação SO-100 vs SO-101 primeiro: o SO-101 é a revisão mais recente com fiação aprimorada e sem a etapa de remoção de engrenagens, e o fluxo de trabalho de gravação é idêntico.

Instalar lerobot 0.6.1

conda create -y -n lerobot python=3.12
conda activate lerobot

# TorchCodec is the default video decoder and needs ffmpeg
conda install ffmpeg -c conda-forge

# core_scripts = dataset + hardware + viz extras (record, replay, calibrate)
# feetech     = SDK for the STS3215 bus servos in the SO-100
pip install 'lerobot[core_scripts,feetech]'

lerobot-info

Os extras são o que mais confunde as pessoas. pip install lerobot instala apenas as dependências principais de ML, nada que se comunique com um robô. Os braços Koch precisam de dynamixel em vez de feetech. Se o seu shell nunca ouviu falar de lerobot-record, é por isso.

Portas, IDs de motor e calibração

Três etapas únicas separam as peças de um loop de teleoperação funcional. permite que uma política treinada no seu braço funcione no braço de outra pessoa, mapeando contagens brutas do encoder para uma convenção de junta compartilhada.

1. 1
   Encontre a porta USB de cada braço

   Execute-o com ambos os braços conectados, desconecte o que você está identificando quando solicitado e anote qual porta desaparece. No Linux, pode ser necessário sudo chmod 666 /dev/ttyACM0.

   bash

   lerobot-find-port
   # Finding all available ports for the MotorsBus.
   # Ports before disconnecting: ['/dev/ttyACM0', '/dev/ttyACM1']
   # Remove the USB cable from your MotorsBus and press Enter when done.
   # The port of this MotorsBus is '/dev/ttyACM1'
   # Reconnect the USB cable.

2. 2
   Grave os IDs e baudrates dos motores

   Os IDs são gravados um motor por vez, e a documentação é rigorosa sobre como: conecte exatamente um motor à placa controladora, ainda não em cadeia com nenhum outro. O script percorre a cadeia de trás para frente, solicitando primeiro a garra e atribuindo-lhe o ID 6, depois o wrist_roll como 5, até o shoulder_pan como 1. Faça isso antes da montagem.

   bash

   lerobot-setup-motors \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0
   
   lerobot-setup-motors \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1

3. 3
   Calibre ambos os braços

   Mova cada junta para o meio de seu alcance, pressione Enter e, em seguida, mova cada uma por todo o seu alcance. O id se torna o nome do arquivo de perfil.

   bash

   lerobot-calibrate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower
   
   lerobot-calibrate \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader

4. 4
   Teleopere antes de gravar qualquer coisa

   O teste de aceitação para tudo o que foi descrito acima. Se a teleoperação for irregular, espelhada ou uma junta não seguir, a gravação preserva isso em 50 episódios.

   bash

   lerobot-teleoperate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader \
       --display_data=true

Câmeras decidem o que a política vê

lerobot-find-cameras opencv   # or: lerobot-find-cameras realsense

# --- Detected Cameras ---
# Camera #0:
#   Name: OpenCV Camera @ 0
#   Type: OpenCV
#   Id: 0
#   Backend api: AVFOUNDATION
#   Default stream profile:
#     Format: 16.0
#     Width: 1920
#     Height: 1080
#     Fps: 15.0

Duas vistas, e onde elas estão posicionadas importa: uma câmera de cena fixa cobrindo o espaço de trabalho e uma câmera de pulso perto do efetor final mostrando o que a garra está prestes a tocar. A lista de verificação de conjuntos de dados da comunidade LeRobot pede preferencialmente duas vistas em 480x640 / 720p ou melhor, um fundo estático, iluminação neutra e estável, e o braço líder e os membros humanos fora do quadro. O guia de gravação adiciona a regra prática: você deve ser capaz de realizar a tarefa apenas olhando as imagens da câmera.

O comando de gravação e cada flag

HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_so100_follower \
    --robot.cameras="{ top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}}" \
    --teleop.type=so100_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_so100_leader \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/so100_pick_cube \
    --dataset.single_task="Pick the red cube and drop it in the box" \
    --dataset.num_episodes=50 \
    --dataset.fps=30 \
    --dataset.episode_time_s=25 \
    --dataset.reset_time_s=10 \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2

Os valores padrão abaixo vêm de src/lerobot/configs/dataset.py no branch principal, não de um tutorial. Vários não são o que as pessoas assumem.

Controle de teclado durante uma sessão

• Seta para a direita ou n: encerra o episódio ou reinicia a fase mais cedo. É a tecla que você mais usa, pois uma pegada limpa raramente precisa de 25 segundos.
• Seta para a esquerda ou r: descarta o episódio e o refaz. Uma tentativa ruim não custa nada agora e muito depois.
• Escape ou q: para a sessão, finaliza a codificação, faz o upload.
• Isso funciona em X11, Wayland e SSH headless: sem um backend de chave global, lerobot-record lê as mesmas chaves do terminal de controle. As letras sobrevivem a links SSH lentos, onde as sequências de setas se dividem.
• A teleoperação por teclado é diferente e precisa de um backend global: X11, Windows ou macOS com Acessibilidade.

Quantos episódios, e como é um bom episódio

O guia de gravação sugere pelo menos 50 episódios para uma primeira tarefa, cerca de 10 por localização de objeto. As páginas de política listam um mínimo por modelo, abaixo do qual uma execução não vale o tempo de GPU.

A melhor pergunta é quantos de quê. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) coletaram mais de 40.000 demonstrações e executaram mais de 15.000 rollouts no mundo real. A generalização seguiu uma relação aproximadamente de lei de potência com o número de ambientes e objetos, e, após um certo limite por ambiente ou objeto, demonstrações adicionais tiveram efeito mínimo. Em um banco de testes: mova o objeto, mude a iluminação, troque o cubo, em vez de repetir uma única tomada.

Um bom episódio é entediante: pose inicial repetível, uma coisa feita, encerrado assim que o objeto está na lixeira, string de tarefa com 25 a 50 caracteres conforme recomendado pela lista de verificação. Pegue o cubo vermelho e coloque-o na caixa é uma string de tarefa; task1 é o antipadrão que a lista de verificação nomeia explicitamente. Anotações vagas encabeçam sua lista de problemas, e elas são mais importantes para modelos de visão-linguagem-ação, onde a string é uma entrada do modelo, não um nome de arquivo.

Defeitos que silenciosamente arruínam um conjunto de dados

Nenhum lança uma exceção. Todos sobrevivem ao treinamento, surgindo como uma curva de perda que parece boa e um robô que não faz nada. Verifique enquanto a cena está configurada.

Uma ressalva: a tabela do guia de streaming-encoding lista o padrão como True, enquanto a dataclass no main lê streaming_encoding: bool = False. Documentação e código discordam, então defina-o explicitamente; o lerobot registra uma dica recomendando-o sempre que inicia com a flag desativada.

Verifique o conjunto de dados antes de alugar uma GPU

O teste de aceitação da documentação: compare a duração do vídeo com a duração do episódio relatada pela CLI e confirme que a contagem de linhas é igual a fps vezes a duração. Por episódio, não no total.

from lerobot.datasets import LeRobotDataset

ds = LeRobotDataset("your-user/so100_pick_cube_20260823_141530")
print("fps:", ds.fps, "frames:", ds.num_frames)

# In v3.0 the per-episode records live in meta/episodes/ as chunked parquet:
# lengths, tasks and offsets into the shared parquet and mp4 shards.
# They load through the datasets stack, so this is a datasets.Dataset --
# use .column_names and integer indexing, not pandas .columns / .head().
eps = ds.meta.episodes
print(eps.column_names)
print(eps[0])

# Global feature statistics, including per-joint min and max.
# A joint whose min equals its max never moved. A joint sitting at a
# hard limit for most of the run is the one that will stall the policy.
print(ds.meta.stats["observation.state"])

Em seguida, observe-o. lerobot-dataset-viz reproduz um episódio quadro a quadro com rastros de articulações ao lado das visualizações da câmera, no Rerun ou Foxglove. Câmeras trocadas e quadros congelados aparecem em dez segundos. As pessoas pulam esta etapa.

# Replay one episode with camera views and joint traces
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0

# Foxglove instead, for a seekable, scrubbable timeline
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0 \
    --display-mode foxglove

# Drop the episodes that did not survive review
lerobot-edit-dataset \
    --repo_id your-user/so100_pick_cube_20260823_141530 \
    --new_repo_id your-user/so100_pick_cube_clean \
    --operation.type delete_episodes \
    --operation.episode_indices "[3, 17, 41]"

v2.1 ou v3.0: decida antes de gravar

v2.1 gravava um parquet e um MP4 por episódio. v3.0 concatena muitos episódios em shards compartilhados e reconstrói os limites a partir dos metadados, então info.json contém modelos de caminho como data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet em vez de um número de episódio. A justificativa a montante é ter menos arquivos e maiores: inicialização mais rápida e menos pressão no sistema de arquivos em escala.

# Upgrade an older v2.1 dataset to v3.0
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube

# By default it pushes the converted dataset back to the hub and tags it v3.0.
# To convert a local copy and keep it off the hub:
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube \
    --root=/path/to/dataset/directory \
    --push-to-hub=false

Duas rotas para o mesmo conjunto de dados

Do conjunto de dados à política

Cinquenta episódios limpos alimentam cada executada aqui. treina do zero apenas na sua tarefa, com cerca de 80 M parâmetros a aproximadamente 20 ms por passo de ação, sendo o único dos cinco confortável com movimento rápido. tem cerca de 450 M parâmetros em uma placa de 24 GB. é um modelo de base de aproximadamente 3 B parâmetros onde afeta cerca de 40 M parâmetros, precisa de uma A100 ou H100, e requer o conjunto de dados v2.1.

Em seguida, o guia para sua combinação: , ou ; para uma primeira execução, é mais curto. Quando a política funciona na bancada, mas colapsa no momento em que você move a mesa, isso é um problema de dados: e aprofundam-se na diversidade.