Introdução aos braços robóticos SO-ARM100 e SO-ARM101 no LeRobot

SO-ARM10x × LeRobot

Da montagem e calibração à coleta de datasets, treinamento e implantação em robôs reais

Este wiki orienta você por todo o fluxo de trabalho do SO-ARM100 / SO-ARM101 no LeRobot: configuração de hardware, configuração de servos, calibração do braço, teleoperação, integração de câmeras, gravação de datasets, visualização, reprodução, treinamento de políticas, avaliação e dicas de implantação.

Ver trilha de aprendizado Instalar LeRobot Gravar um dataset

Trilha de leitura recomendadaNovos usuários: comece com especificações, regras de alimentação e configuração de servos.Usuários de braços pré-montados: vá direto para calibração do braço completo e teleoperação.Usuários já familiarizados com LeRobot: vá direto para câmeras, gravação de datasets, treinamento ou FAQ.

⚠️

Aviso de segurança: limpe a área de trabalho do braço robótico antes de executar programas de movimento

Antes de executar qualquer programa que possa mover o braço robótico, remova itens de valor, objetos frágeis, ferramentas, cabos e objetos não relacionados em um raio de 1 metro da área de trabalho. Durante a depuração e operação, mantenha as pessoas afastadas da faixa de movimento do braço.

Não toque em juntas, motores, elos, garra ou ferramentas de extremidade após o braço ser energizado.
Antes da configuração dos servos, calibração, teleoperação, gravação de datasets, reprodução ou avaliação de políticas, certifique-se de que o braço esteja firmemente fixado.
Mantenha pelo menos 1 metro de distância de segurança e certifique-se de que as pessoas próximas entendam que o braço pode se mover de forma repentina.
Se ocorrer movimento anormal, ruído, trepidação, cabos soltos, mau contato de alimentação ou perda de comunicação, pare o programa imediatamente e desligue a alimentação antes da inspeção.
Desligue a alimentação antes de conectar ou desconectar cabos de servo, cabos USB, conectores de alimentação ou cabos da placa de controle do motor.

Trilha de aprendizado recomendada

Visão geral das etapas

Siga o fluxo de trabalho real de depuração passo a passo

Para uma configuração inicial do SO-ARM10x, conclua a preparação de hardware, configuração de ambiente e calibração antes de avançar para teleoperação, câmeras, datasets, treinamento e avaliação.

Entenda o kit

Confirme sua versão SO-ARM100 / SO-ARM101, tipo de motor, tensão e BOM.

Preparar

Instale o LeRobot

Configure Miniforge, o repositório verificado Seeed LeRobot, ffmpeg, PyTorch e dependências de câmera.

Ambiente

Configure os motores e faça a montagem

Defina IDs e baud rates dos servos e depois monte os braços líder e seguidor.

Hardware

Calibre e teleopere

Calibre ambos os braços e verifique se a cadeia de controle de líder para seguidor está estável.

Controle

Adicione câmeras e grave dados

Conecte câmeras OpenCV, RealSense ou Orbbec e grave episódios limpos e repetíveis.

Dados

Treine e avalie políticas

Comece com ACT e depois explore SmolVLA, Pi0, Pi0.5, GR00T, PEFT e inferência assíncrona.

Visão geral

Introdução ao projeto

SO-ARM10x combina um braço robótico de baixo custo e código aberto com o ecossistema LeRobot para coleta de dados, aprendizado por imitação e implantação em robôs reais.

dica

Este tutorial foi atualizado para a versão mais recente do LeRobot.

Adquira agora 🖱️

cuidado

A Seeed Studio é responsável pela qualidade de hardware do kit. O tutorial de software segue a documentação oficial do LeRobot o mais fielmente possível. Se você encontrar problemas de software ou dependências que não consiga resolver, verifique o FAQ no final desta página e relate problemas no repositório LeRobot no GitHub ou no canal LeRobot no Discord.

Guia de impressão 3D

Impressão 3D

Guia de impressão 3D

Escolha os arquivos STL e as configurações de impressão corretos antes de montar uma versão em kit do braço.

Ver parâmetros de impressão 3D

cuidado

Após a atualização oficial do SO101, o SO100 não terá mais suporte e os arquivos-fonte serão excluídos conforme o oficial, mas os arquivos-fonte ainda podem ser encontrados em nosso Makerworld. No entanto, para usuários que já compraram o SO100, os tutoriais e métodos de instalação continuam compatíveis. A impressão do SO101 é totalmente compatível com a instalação do kit de motor do SO100.

Passo 1: Escolha uma impressora

Os arquivos STL fornecidos estão prontos para impressão em muitas impressoras FDM. Abaixo estão as configurações testadas e sugeridas, embora outras também possam funcionar.

Material: PLA+
Diâmetro do bico e precisão: bico de 0,4 mm com altura de camada de 0,2 mm ou bico de 0,6 mm com altura de camada de 0,4 mm.
Densidade de preenchimento: 15%

Passo 2: Configure a impressora

Certifique-se de que a impressora esteja calibrada e que o nivelamento da mesa esteja corretamente ajustado usando as instruções específicas da impressora.
Limpe a mesa de impressão, certificando-se de que esteja livre de poeira ou gordura. Se limpar a mesa com água ou outro líquido, seque-a.
Se a sua impressora recomendar, use um bastão de cola padrão e aplique uma camada fina e uniforme de cola em toda a área de impressão da mesa. Evite acúmulos ou aplicação irregular.
Carregue o filamento da impressora usando as instruções específicas da impressora.
Certifique-se de que as configurações da impressora correspondam às sugeridas acima (a maioria das impressoras possui múltiplas configurações, então escolha as que mais se aproximam).
Configure para suportes em todos os lugares, mas ignore inclinações maiores que 45 graus em relação à horizontal.
Não deve haver suportes nos furos de parafuso com eixos horizontais.

Passo 3: Imprima as peças

Todas as peças para o líder ou seguidor já estão contidas em um único arquivo, prontas para impressão 3D fácil, corretamente orientadas com o eixo z para cima para minimizar suportes.

Para tamanhos de mesa de impressão de 220mm x 220mm (como a Ender), imprima estes arquivos:
- Follower
- Leader
Para tamanhos de mesa de impressão de 205mm x 250mm (como a Prusa/Up):
- Follower
- Leader

Passo 4: Imprima o Soft Gripper e o inserto do suporte de montagem da câmera (opcional)

Se você quiser que o braço robótico consiga agarrar objetos macios, frágeis ou de formato irregular, pode imprimir um soft gripper para substituir a garra rígida padrão. Você também pode imprimir o inserto do suporte de montagem da câmera se precisar montar uma câmera. Os arquivos de impressão estão disponíveis no repositório soarm_soft_gripper.

Instruções sobre material de impressão:

Dois dedos da garra: imprimir com material TPU
Outras partes: imprima com material PLA

⚡ No-code · Sem configuração de ambiente

Pule a configuração — execute o reBot Arm e o LeRobot a partir de um único aplicativo

SenseCraft Robotics é a plataforma no-code da Seeed para o SO-ARM101, reBot Arm 102 + B601-RS e B601-DM. Conecte os braços, calibre, colete demonstrações, treine e execute inferência a partir de uma interface guiada — sem ambiente Python, sem terminal.

✅ Fluxo de trabalho guiado em 6 etapas
✅ Treinamento em nuvem — sem GPU local
✅ Cliente para Windows / macOS
✅ SO-ARM101 · B601-RS · B601-DM

Ir para SenseCraft Robotics ↗Guia de software

Ambiente inicial do sistema

Ambiente

Ambiente inicial do sistema

Confirme os requisitos de Ubuntu, Jetson, CUDA, Python, PyTorch e Torchvision antes da instalação.

Para Ubuntu x86:

Ubuntu 22.04
CUDA 12+
Python 3.12
Torch 2.6+

Para Jetson Orin:

Jetson JetPack 6.0 e 6.1, JetPack 6.2 ainda não é suportado
Python 3.12
Torch 2.3+

Instalar LeRobot

Passo 1

Instalar LeRobot

Instale o Miniforge, o repositório verificado Seeed LeRobot, ffmpeg, PyTorch e dependências específicas de hardware.

Ambientes como pytorch e torchvision precisam ser instalados com base na sua versão do CUDA.

Jetson
X86 Ubuntu 22.04

Instale o Miniforge:

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh
chmod +x Miniforge3-Linux-aarch64.sh
./Miniforge3-Linux-aarch64.sh
# Follow the prompts by entering 'yes' or pressing Enter. Once the installation is complete:
source ~/.bashrc

Crie e ative um novo ambiente conda para o lerobot

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

Clone o Lerobot:

git clone https://github.com/Seeed-Projects/lerobot.git ~/lerobot

Ao usar o miniforge, instale o ffmpeg no seu ambiente:

conda install ffmpeg -c conda-forge

dica

Isso geralmente instala o ffmpeg 7.X para a sua plataforma, compilado com o codificador libsvtav1. Se o libsvtav1 não for suportado (verifique os codificadores suportados com ffmpeg -encoders), você pode:

[Em qualquer plataforma] Instalar explicitamente o ffmpeg 7.X usando:

conda install ffmpeg=7.1.1 -c conda-forge

[Somente no Linux] Instalar as dependências de compilação do ffmpeg e compilar o ffmpeg a partir do código-fonte com libsvtav1, e certificar-se de usar o binário ffmpeg correspondente à sua instalação com which ffmpeg.

Se você encontrar um erro como este, também pode usar este comando.

Instale o LeRobot com dependências para os motores feetech:

cd ~/lerobot && pip install -e ".[feetech]"

Para dispositivos Jetson Jetpack 6.0+ (certifique-se de instalar Pytorch-gpu e Torchvision a partir do passo 5 antes de executar este passo):

conda install -y -c conda-forge "opencv>=4.10.0.84"  # Install OpenCV and other dependencies through conda, this step is only for Jetson Jetpack 6.0+
conda remove opencv   # Uninstall OpenCV
pip3 install opencv-python==4.10.0.84  # Then install opencv-python via pip3
conda install -y -c conda-forge ffmpeg
conda uninstall numpy
pip3 install numpy==1.26.0  # This should match torchvision

Verifique o Pytorch e o Torchvision

Como instalar o ambiente do lerobot via pip desinstalará o Pytorch e o Torchvision originais e instalará as versões de CPU do Pytorch e do Torchvision, você precisa realizar uma verificação em Python.

python   # Command to start Python in the terminal
import torch
print(torch.cuda.is_available())
exit()   # Exit Python

Se o resultado impresso for False, o ambiente atual está usando a versão de CPU do PyTorch. Se você precisar de PyTorch e Torchvision com suporte a GPU no Jetson, instale-os de acordo com este tutorial. Para ambientes que precisam de treinamento ou inferência em GPU, o resultado final da verificação deve ser True.

Instale o Miniforge:

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
chmod +x Miniforge3-Linux-x86_64.sh
./Miniforge3-Linux-x86_64.sh
# Once the installation is complete:
source ~/.bashrc
# Initialize all shells
conda init --all

Crie e ative um novo ambiente conda para o lerobot

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

Clone o Lerobot:

git clone https://github.com/Seeed-Projects/lerobot.git ~/lerobot

Ao usar o miniforge, instale o ffmpeg no seu ambiente:

conda install ffmpeg -c conda-forge

dica

[Em qualquer plataforma] Instalar explicitamente o ffmpeg 7.X usando:

conda install ffmpeg=7.1.1 -c conda-forge

[Somente no Linux] Instalar as dependências de compilação do ffmpeg e compilar o ffmpeg a partir do código-fonte com libsvtav1, e certificar-se de usar o binário ffmpeg correspondente à sua instalação com which ffmpeg.

Se você encontrar um erro como este, também pode usar este comando.

Instale o LeRobot com dependências para os motores feetech:

dica

Em uma VM Ubuntu 22.04 recém-configurada, especialmente em uma instalação mínima, gcc e outras ferramentas de compilação C podem não estar instaladas por padrão. Nesse caso, a instalação do LeRobot com dependências feetech pode falhar porque o pacote Python evdev não pode ser compilado.

Instale primeiro as ferramentas de compilação básicas:

sudo apt update
sudo apt install build-essential

Após a instalação, execute novamente o comando de instalação do LeRobot.

cd ~/lerobot && pip install -e ".[feetech]"

Verifique o Pytorch e o Torchvision

python   # Command to start Python in the terminal
import torch
print(torch.cuda.is_available())
exit()   # Exit Python

Se o resultado impresso for False, o ambiente atual está usando a versão de CPU do PyTorch. Se você precisar de treinamento ou inferência em GPU, instale as versões do Pytorch e do Torchvision que correspondam à sua versão do CUDA de acordo com o guia oficial do PyTorch. Para ambientes com uma GPU NVIDIA que precisam de aceleração por GPU, o resultado final da verificação deve ser True.

dica

Observação: GPUs NVIDIA RTX série 50 exigem a versão de prévia do CUDA 12.8 ou superior.

O comando de download é o seguinte:

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128

Configurar motores e montar o braço

Passo 2

Configurar motores e montar o braço

Defina os IDs dos servos e as taxas de baud, verifique a fiação e a alimentação e, em seguida, monte os braços líder e seguidor.

⚠️

Verificação de segurança antes de executar

Afaste itens de valor e pessoas não relacionadas em um raio de 1 metro da área de trabalho do braço robótico. Certifique-se de que o braço esteja firmemente fixado e que a alimentação e os cabos estejam conectados corretamente antes de executar esta seção.

dica

Se você comprou um braço robótico pré-montado, pule para a seção de Calibração.

Para a versão em kit, siga as etapas abaixo

O processo de calibração e inicialização do servo para o SO-ARM101 é o mesmo do SO-ARM100, tanto em termos de método quanto de código. No entanto, observe que as relações de engrenagem dos três primeiros eixos do braço líder SO-ARM101 são diferentes das do SO-ARM100, portanto é importante distingui-las e calibrá-las com cuidado.

Para configurar os motores, designe um adaptador de servo de barramento e 6 motores para o braço líder e, da mesma forma, o outro adaptador de servo de barramento e 6 motores para o braço seguidor. É conveniente rotulá-los e escrever em cada motor se ele é para o seguidor F ou para o líder L e seu ID de 1 a 6. Usamos F1–F6 para representar as juntas 1 a 6 do Braço Seguidor, e L1–L6 para representar as juntas 1 a 6 do Braço Líder. O modelo de servo correspondente, a atribuição das juntas e os detalhes da relação de engrenagem são os seguintes:

Modelo de Servo	Relação de Engrenagem	Juntas Correspondentes
ST-3215-C044(7.4V)	1:191	L1
ST-3215-C001(7.4V)	1:345	L2
ST-3215-C044(7.4V)	1:191	L3
ST-3215-C046(7.4V)	1:147	L4–L6
ST-3215-C001(7.4V) / C018(12V) / C047(12V)	1:345	F1–F6

perigo

Agora você deve conectar a fonte de alimentação de 5V ou 12V ao barramento dos motores. 5V para os motores STS3215 7,4V e 12V para os motores STS3215 12V. Observe que o braço líder sempre usa motores de 7,4V, portanto, certifique-se de conectar a fonte de alimentação correta se você tiver motores de 12V e 7,4V, caso contrário, você pode queimar seus motores! Agora, conecte o barramento dos motores ao seu computador via USB. Observe que o USB não fornece nenhuma alimentação, e tanto a fonte de alimentação quanto o USB precisam estar conectados.

A seguir estão as etapas de calibração por código, por favor calibre com o servo de referência de fiação na imagem acima

Encontre as portas USB associadas aos seus braços Para encontrar as portas corretas para cada braço, execute o script utilitário duas vezes:

lerobot-find-port

Exemplo de saída:

Finding all available ports for the MotorBus.
['/dev/ttyACM0', '/dev/ttyACM1']
Remove the usb cable from your MotorsBus and press Enter when done.

[...Disconnect corresponding leader or follower arm and press Enter...]

The port of this MotorsBus is /dev/ttyACM1
Reconnect the USB cable.

dica

Lembre-se de remover o USB, caso contrário a interface não será detectada.

Exemplo de saída ao identificar a porta do braço seguidor (por exemplo, /dev/tty.usbmodem575E0031751 no Mac, ou possivelmente /dev/ttyACM0 no Linux):

Exemplo de saída ao identificar a porta do braço líder (por exemplo, /dev/tty.usbmodem575E0032081, ou possivelmente /dev/ttyACM1 no Linux):

Você pode precisar conceder acesso às portas USB executando:

sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1

dica

Ao conectar os braços, o primeiro dispositivo conectado será atribuído a ttyACM0 (braço Escravo/Seguidor), e o segundo dispositivo conectado será atribuído a ttyACM1 (braço Mestre/Líder).

Configure seus motores

Imagens de referência para calibração dos servos do líder

Calibração da Junta 6 do Braço Líder	Calibração da Junta 5 do Braço Líder	Calibração da Junta 4 do Braço Líder	Calibração da Junta 3 do Braço Líder	Calibração da Junta 2 do Braço Líder	Calibração da Junta 1 do Braço Líder

Imagens de referência para calibração dos servos do seguidor

Calibração da Junta 6 do Braço Seguidor	Calibração da Junta 5 do Braço Seguidor	Calibração da Junta 4 do Braço Seguidor	Calibração da Junta 3 do Braço Seguidor	Calibração da Junta 2 do Braço Seguidor	Calibração da Junta 1 do Braço Seguidor

dica

Novamente, certifique-se de que os IDs das juntas dos servos e as relações de engrenagem correspondam estritamente às do SO-ARM101.

Calibrar Servos do Braço Seguidor

Conecte o cabo USB do seu computador e a fonte de alimentação à placa controladora do braço seguidor. Em seguida, execute o seguinte comando.

lerobot-setup-motors \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0  # <- paste here the port found at previous step

Você deverá ver a seguinte instrução.

Connect the controller board to the 'gripper' motor only and press enter.

Conforme instruído, conecte o motor da garra. Certifique-se de que ele seja o único motor conectado à placa e que o próprio motor ainda não esteja em cadeia (daisy-chain) com nenhum outro motor. Ao pressionar [Enter], o script definirá automaticamente o id e o baudrate para esse motor.

Você deverá então ver a seguinte mensagem:

'gripper' motor id set to 6

Seguido pela próxima instrução:

Connect the controller board to the 'wrist_roll' motor only and press enter.

Você pode desconectar o cabo de 3 pinos da placa controladora, mas pode deixá-lo conectado ao motor da garra na outra extremidade, pois ele já estará no lugar certo. Agora, conecte outro cabo de 3 pinos ao motor de rotação do punho (wrist roll) e conecte-o à placa controladora. Como no motor anterior, certifique-se de que ele seja o único motor conectado à placa e que o próprio motor não esteja conectado a nenhum outro.

cuidado

Repita a operação para cada motor conforme instruído.

dica

Verifique sua fiação em cada etapa antes de pressionar Enter. Por exemplo, o cabo da fonte de alimentação pode se desconectar enquanto você manipula a placa.

Quando terminar, o script simplesmente será concluído, momento em que os motores estarão prontos para uso. Agora você pode conectar o cabo de 3 pinos de cada motor ao próximo, e o cabo do primeiro motor (o ‘shoulder pan’ com id=1) à placa controladora, que agora pode ser fixada à base do braço.

Calibrar Servos do Braço Líder

Repita os mesmos passos para o braço líder.

lerobot-setup-motors \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM0  # <- paste here the port found at previous step

Montagem

dica

O processo de montagem de braço duplo do SO-ARM101 é o mesmo do SO-ARM100. As únicas diferenças são a adição de presilhas de cabo no SO-ARM101 e as diferentes relações de engrenagem dos servos das juntas no Braço Líder. Portanto, tanto o SO100 quanto o SO101 podem ser instalados consultando o conteúdo a seguir
Antes da montagem, verifique novamente o modelo do seu motor, a relação de engrenagem e a tensão da fonte de alimentação. Se você comprou o SO101, consulte a tabela de modelo de servo e mapeamento de juntas acima para distinguir F1 a F6 e L1 a L6.

Montar o Braço Líder

Passo 1	Passo 2	Passo 3	Passo 4	Passo 5	Passo 6

Passo 7	Passo 8	Passo 9	Passo 10	Passo 11	Passo 12

Passo 13	Passo 14	Passo 15	Passo 16	Passo 17	Passo 18

Passo 19	Passo 20

Montar o Braço Seguidor

dica

As etapas para montar o Braço Seguidor são, em geral, as mesmas do Braço Líder. A única diferença está no método de instalação do efetuador final (garra e alça) após a Etapa 12.

Etapa 1	Etapa 2	Etapa 3	Etapa 4	Etapa 5	Etapa 6

Etapa 7	Etapa 8	Etapa 9	Etapa 10	Etapa 11	Etapa 12

Etapa 13	Etapa 14	Etapa 15	Etapa 16	Etapa 17

Calibrar o Braço Robótico

Etapa 3

Calibrar o Braço Robótico

Calibre os braços seguidor e líder para que suas posições físicas correspondam ao estado no software.

⚠️

Verificação de segurança antes de executar

Remova itens de valor e pessoas não relacionadas em um raio de 1 metro da área de trabalho do braço robótico. Certifique-se de que o braço esteja firmemente fixado e que a alimentação e os cabos estejam conectados corretamente antes de executar esta seção.

dica

Os códigos do SO100 e SO101 são compatíveis. Usuários do SO100 podem utilizar diretamente os parâmetros e o código do SO101 para operação.

perigo

Se você comprou o SO101 Arm Kit Standard Edition, todas as fontes de alimentação são de 5V. Se você comprou o SO101 Arm Kit Pro Edition, o Braço Líder deve ser calibrado e operado em cada etapa usando uma fonte de alimentação de 5V, enquanto o Braço Seguidor deve ser calibrado e operado em cada etapa usando uma fonte de alimentação de 12V.

Em seguida, você precisa conectar a fonte de alimentação e o cabo de dados ao seu robô SO-10x para calibração, a fim de garantir que os braços líder e seguidor tenham os mesmos valores de posição quando estiverem na mesma posição física. Essa calibração é essencial porque permite que uma rede neural treinada em um robô SO-10x funcione em outro.

Recalibrar o braço robótico

Ver opções de recalibração

Se você precisar recalibrar os braços robóticos, há duas opções disponíveis:

Opção 1: Excluir arquivos de calibração locais

Exclua completamente os arquivos em ~/.cache/huggingface/lerobot/calibration/robots ou ~/.cache/huggingface/lerobot/calibration/teleoperators antes de recalibrar. Caso contrário, o sistema pode disparar uma mensagem de erro porque os dados de calibração anteriores são armazenados em arquivos JSON nesses diretórios.

Opção 2: Escolher recalibração no comando de calibração

Execute o comando de calibração diretamente no terminal. Se o braço já tiver sido calibrado antes, o seguinte aviso aparecerá:

Press ENTER to use provided calibration file associated with the id my_awesome_leader_arm, or type 'c' and press ENTER to run calibration:

Digite c e pressione Enter para iniciar a recalibração. Pressione Enter diretamente para manter e usar os dados de calibração existentes.

Conecte os 6 servos do robô pelas interfaces de 3 pinos e conecte o servo do chassi à placa controladora de servos. Em seguida, execute o seguinte comando ou exemplo de API para calibrar o braço:

dica

Em PCs (Linux) e dispositivos Jetson, o primeiro dispositivo USB que você conecta normalmente é mapeado para ttyACM0, e o segundo é mapeado para ttyACM1. Verifique cuidadosamente qual porta está mapeada para o líder e para o seguidor antes de executar os comandos.

Calibração manual do braço seguidor

Conecte as interfaces dos 6 servos do robô por meio de um cabo de 3 pinos e conecte o servo do chassi à placa controladora de servos, depois execute o seguinte comando ou exemplo de API para calibrar o braço robótico:

Primeiro, conceda as permissões da interface

sudo chmod 666 /dev/ttyACM*

Depois, calibre o braço seguidor

lerobot-calibrate \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 # <- The port of your robot
  --robot.id=my_awesome_follower_arm  # <- Give the robot a unique name

O vídeo abaixo mostra como realizar a calibração. Primeiro você precisa mover o robô para a posição em que todas as juntas estejam no meio de seus intervalos. Em seguida, após pressionar Enter, você deve mover cada junta por toda a sua amplitude de movimento.

dica

Devido à atualização do repositório lerobot, é normal que o terminal não receba um sinal do servo 5 ao realizar a calibração do braço mestre-escravo. Você pode continuar com a operação.

Calibração manual do braço líder

Siga os mesmos passos para calibrar o braço líder, executando o seguinte comando ou exemplo de API:

lerobot-calibrate \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 # <- The port of your robot
  --teleop.id=my_awesome_leader_arm  # <- Give the robot a unique name

dica

Se você encontrar o erro “Could not connect on port '/dev/ttyACM0'. Make sure you are using the correct port., Try running lerobot-find-port” ao calibrar os braços Líder ou Seguidor, você precisa conceder as permissões necessárias executando: sudo chmod 666 /dev/ttyACM*

(Opcional) Calibração de posição central com a ferramenta rápida Seeed Studio SoARM

Ao calibrar ou executar o robô, se você vir erros como:

Magnitude 30841 exceeds 2047 (max for sign_bit_index=11)

Isso geralmente significa que a posição atual / deslocamento de zero de um servo está anormal, fazendo com que o ângulo lido exceda o intervalo esperado. Nesse caso, você pode usar a ferramenta SoARM da Seeed Studio para fazer uma calibração de posição central (gravar a posição atual como o valor central 2048) e, em seguida, refazer a calibração de todo o braço.

1) Clonar a ferramenta do GitHub e instalar dependências

git clone https://github.com/Seeed-Projects/Seeed_RoboController.git
cd Seeed_RoboController
pip install -r requirements.txt

2) Calibração de posição central e verificação

Localização dos scripts:

src/tools/servo_middle_calibration.py: calibração de posição central (grava a posição atual como 2048)
src/tools/servo_disable.py: desativar o torque do servo (facilita girar as juntas manualmente)
src/tools/servo_center_test.py: mover para 2048 para verificar o resultado da calibração

Execute na seguinte ordem (os comandos solicitarão interativamente que você selecione uma porta):

(Opcional) Desativar o torque para ajustar as juntas manualmente:

python -m src.tools.servo_disable

Fazer a calibração de posição central (definir a posição atual como 2048):

python -m src.tools.servo_middle_calibration

Verificar: mover o servo para 2048 e checar se ele retorna à posição central esperada:

python -m src.tools.servo_center_test

Após a calibração de posição central, volte para as etapas do lerobot-calibrate acima e refaça a calibração de todo o braço.

Se você encontrar os erros acima, pode usar a Ferramenta de Depuração de Engrenagem de Direção para depuração. Ela é compatível com Windows, Ubuntu e Mac.

▶ Abrir Tutorial da Ferramenta de Depuração de Engrenagem de Direção

Teleoperação

Etapa 4

Teleoperação

Execute um teste de teleoperação de líder para seguidor antes de adicionar câmeras ou coletar dados.

⚠️

Verificação de segurança antes de executar

Remova itens de valor e pessoas não relacionadas em um raio de 1 metro da área de trabalho do braço robótico. Certifique-se de que o braço esteja firmemente montado e que a alimentação e os cabos estejam conectados corretamente antes de executar esta seção.

Teleop simples Então você está pronto para teleoperar seu robô! Execute este script simples (ele não irá conectar e exibir as câmeras):

Observe que o id associado a um robô é usado para armazenar o arquivo de calibração. É importante usar o mesmo id ao teleoperar, gravar e avaliar quando estiver usando a mesma configuração.

sudo chmod 666 /dev/ttyACM*

lerobot-teleoperate \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=my_awesome_leader_arm

O comando de teleoperação irá automaticamente:

Identificar quaisquer calibrações ausentes e iniciar o procedimento de calibração.
Conectar o robô e o dispositivo de teleoperação e iniciar a teleoperação.

Adicionar câmeras

Passo 5

Adicionar câmeras

Adicione câmeras OpenCV, RealSense ou Orbbec e verifique os fluxos de imagem antes de gravar conjuntos de dados.

Se estiver usando câmeras RealSense D435i/D405

As câmeras de profundidade RealSense podem fornecer percepção RGB-D para o LeRobot e são adequadas para tarefas como reconhecimento de objetos, reconstrução de nuvens de pontos e manipulação em mesa. Os modelos recomendados aqui são RealSense D405 e RealSense D435i.

RealSense D405

A RealSense D405 é uma câmera estéreo de profundidade de curto alcance projetada para tarefas de alta precisão em curta distância, como manipulação robótica em mesa, com uma faixa de trabalho típica de 7 cm a 50 cm.

RealSense D435i

A RealSense D435i combina detecção de profundidade, imagem RGB e um IMU, tornando-a adequada para aplicações de médio a curto alcance, como reconstrução 3D, SLAM e percepção do ambiente robótico.

1. Mudar para o branch da câmera

O suporte atual a câmeras está disponível no branch DepthCameraSupport:

git checkout DepthCameraSupport
git pull origin DepthCameraSupport

Confirme o branch atual:

git branch --show-current

Saída esperada:

DepthCameraSupport

2. Instalar RealSense em modo editável

Se você usar apenas RealSense:

pip install -e ".[realsense]"

3. Conceder permissões à câmera

chmod a+rw /dev/bus/usb/*/*

4. Detectar câmeras

lerobot-find-cameras realsense

Esta etapa irá exibir:

Modelo da câmera
Número de série
Informações USB
Configuração de fluxo padrão

Insira o Serial number obtido no parâmetro serial_number_or_name do comando da câmera abaixo.

5. Exemplo com RealSense

Teste com duas RealSense:

lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_awesome_follower_arm \
--robot.cameras='{
  d435i_color: {
    type: realsense_d435i_color,
    serial_number_or_name: "419522072950",
    width: 640,
    height: 480,
    fps: 30,
    color_mode: rgb,
    color_stream_format: rgb8,
    rotation: 0,
    warmup_s: 1
  },
  d435i_depth: {
    type: realsense_d435i_depth,
    serial_number_or_name: "419522072950",
    width: 640,
    height: 480,
    fps: 30,
    max_depth_m: 2.0,
    depth_alpha: 0.2,
    rotation: 0,
    warmup_s: 5
  },
  d405_color: {
    type: realsense_d405_color,
    serial_number_or_name: "409122273421",
    width: 640,
    height: 480,
    fps: 30,
    color_mode: rgb,
    color_stream_format: rgb8,
    rotation: 0,
    warmup_s: 1
  },
  d405_depth: {
    type: realsense_d405_depth,
    serial_number_or_name: "409122273421",
    width: 640,
    height: 480,
    fps: 30,
    depth_alpha: 0.03,
    rotation: 0,
    warmup_s: 5
  }
}' \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_awesome_leader_arm \
--display_data=true

6. Observações sobre parâmetros

depth_alpha controla o fator de escala da imagem de profundidade e pode ser ajustado com base no resultado da exibição e na faixa de distância alvo.
Se você conectar três ou mais câmeras de profundidade, é recomendável reduzir fps para 15 para melhorar a estabilidade geral.
Recomenda-se manter a resolução em 640x480 para um melhor equilíbrio entre estabilidade e desempenho em tempo real.

Se estiver usando câmeras Orbbec Gemini2/Gemini336

Adquira agora 🖱️

A Orbbec Gemini 2 é uma câmera RGB-D de alto desempenho para aplicações em robótica, fornecendo fluxos sincronizados de RGB e profundidade com alinhamento preciso de profundidade para cor. Combinada com detecção de profundidade estéreo e um IMU de 6 eixos integrado, ela é bem adequada para tarefas robóticas como detecção de objetos, percepção 3D, mapeamento e navegação. Seu design compacto e o suporte completo ao Orbbec SDK a tornam adequada tanto para pesquisa quanto para implantação em cenários reais.

A Gemini 336 é um novo membro da série Gemini 330. Ela herda o forte desempenho de profundidade da Gemini 335 e melhora ainda mais a qualidade de imagem de profundidade em áreas internas reflexivas, regiões escuras em cenas de alta dinâmica e ambientes externos claros. Para aplicações em robótica, ela pode fornecer dados de profundidade mais estáveis e de alta qualidade para tarefas como percepção, localização e manipulação.

1. Mudar para o branch da câmera

O suporte atual a câmeras está disponível no branch DepthCameraSupport:

git checkout DepthCameraSupport
git pull origin DepthCameraSupport

Confirme o branch atual:

git branch --show-current

Saída esperada:

DepthCameraSupport

2. Instalar LeRobot em modo editável

Se você usar apenas Orbbec:

pip install -e ".[orbbec]"

3. Conceder permissões à câmera

chmod a+rw /dev/bus/usb/*/*

4. Configuração do tamanho do cache USBFS

Por padrão, o tamanho do cache USBFS é 16 MB. Esse valor é insuficiente para imagens de alta resolução, múltiplos fluxos de dados e cenários com vários dispositivos. Os usuários podem aumentar o tamanho do cache até 128 MB.

Verificar o tamanho do cache USBFS

cat /sys/module/usbcore/parameters/usbfs_memory_mb

Aumentar temporariamente o tamanho do cache USBFS

sudo sh -c 'echo 128> /sys/module/usbcore/parameters/usbfs_memory_mb'

dica

Se você ainda encontrar o timeout error TimeoutError: Timed out waiting for frame from <lerobot.cameras.orbbec.camera_orbbec.OrbbecDepthCamera object at 0x7ba4ba130910.........>, simplesmente reconecte a câmera.

5. Detectar câmeras

lerobot-find-cameras orbbec

Esta etapa irá exibir:

Modelo da câmera（Name）
Número de série（Serial number）
Informações USB
Configuração de fluxo padrão

Insira o Serial Number obtido no parâmetro serial_number_or_name do comando da câmera mostrado abaixo.

6. Exemplo com Orbbec

Teste com uma única Orbbec:

lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_awesome_follower_arm \
--robot.cameras='{
  orbbec_color: {
    type: orbbec_color,
    serial_number_or_name: "CP9JA530003A",
    width: 640,
    height: 480,
    fps: 30,
    color_mode: rgb,
    rotation: 0,
    warmup_s: 1
  },
  orbbec_depth: {
    type: orbbec_depth,
    serial_number_or_name: "CP9JA530003A",
    width: 640,
    height: 400,
    fps: 30,
    depth_alpha: 0.2,
    rotation: 0,
    warmup_s: 5
  }
}' \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_awesome_leader_arm \
--display_data=true

Teste com uma única câmera Orbbec + teste com câmera padrão:

  lerobot-teleoperate \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras='{
    orbbec_color: {
      type: orbbec_color,
      serial_number_or_name: "CP9JA530003A",
      width: 640,
      height: 480,
      fps: 30,
      color_mode: rgb,
      rotation: 0,
      warmup_s: 1
    },
    orbbec_depth: {
      type: orbbec_depth,
      serial_number_or_name: "CP9JA530003A",
      width: 640,
      height: 400,
      fps: 30,
      depth_alpha: 0.2,
      rotation: 0,
      warmup_s: 5
    },
    side: {
    type: opencv,
    index_or_path: 8,
    width: 640,
    height: 480,
    fps: 30,
    fourcc: "MJPG"}
  }' \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true

dica

Ao usar uma única câmera Orbbec junto com uma câmera padrão, é recomendado conectar primeiro a câmera Orbbec e, em seguida, a câmera padrão.

Ao executar o comando lerobot-find-cameras opencv para detectar IDs de câmera, você verá que a câmera Orbbec ocupa 3 números de câmera consecutivos. Portanto, é aconselhável conectar a câmera padrão por último, para que seu número seja atribuído ao final.

7. Observações sobre parâmetros

depth_alpha controla o fator de escala da imagem de profundidade. Um bom ponto de partida é 0.2, depois você pode ajustá-lo com base no resultado exibido.
Se você conectar três ou mais câmeras de profundidade, é recomendado reduzir fps para 15 para obter melhor estabilidade.
Recomenda-se manter a resolução em 640x480 para uma exibição e transferência de dados mais estáveis.

Para erros relacionados à câmera, consulte a seção de FAQ no final desta página.

If using a regular camera

dica

Os códigos SO100 e SO101 são compatíveis. Usuários do SO100 podem utilizar diretamente os parâmetros e o código do SO101 para operação.

Para instanciar uma câmera, você precisa de um identificador de câmera. Esse identificador pode mudar se você reiniciar o computador ou reconectar a câmera, um comportamento que depende principalmente do seu sistema operacional.

Para encontrar os índices das câmeras conectadas ao seu sistema, execute o seguinte script:

lerobot-find-cameras opencv # or realsense for Intel Realsense cameras

O terminal exibirá as seguintes informações.

--- 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
--------------------
(more cameras ...)

Você pode encontrar as imagens capturadas por cada câmera no diretório outputs/captured_images.

atenção

Ao usar câmeras Intel RealSense em , você pode receber este erro: , isso pode ser resolvido executando o mesmo comando com permissões. Observe que o uso de câmeras RealSense em é instável.macOSError finding RealSense cameras: failed to set power statesudomacOS.

Em seguida, você poderá exibir as câmeras no seu computador enquanto faz a teleoperação executando o código a seguir. Isso é útil para preparar sua configuração antes de gravar seu primeiro conjunto de dados.

lerobot-teleoperate \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true

Se você tiver mais câmeras, poderá alterar --robot.cameras para adicioná-las. Você deve observar o formato de index_or_path, que é determinado pelo último dígito do ID da câmera exibido por python -m lerobot.find_cameras opencv.

dica

Imagens no formato fourcc: "MJPG" são compactadas. Você pode tentar resoluções mais altas e também pode experimentar o formato YUYV. No entanto, este último reduzirá a resolução e o FPS da imagem, causando atraso na operação do braço robótico. Atualmente, no formato MJPG, é possível suportar 3 câmeras com resolução de 1920*1080 mantendo 30FPS. Dito isso, ainda não é recomendado conectar 2 câmeras a um computador por meio do mesmo HUB USB.

Por exemplo, você quer adicionar uma câmera lateral:

lerobot-teleoperate \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true

dica

Se você encontrar um bug como este.

Você pode fazer downgrade da versão do rerun para resolver o problema.

pip3 install rerun-sdk==0.23

Instalação e uso do suporte da câmera

Instalação do suporte da câmera

Fixe a posição da câmera para uma coleta de dados limpa. Suporta ajuste livre de múltiplos ângulos, incluindo vistas de cima + pulso e de cima + lateral. Compatível com câmeras USB comuns e câmeras de profundidade como D435i, D405 e Gemini 2. Suporta braços robóticos SO-ARM101 e reBot. Pode ser usado com a caixa de experimentos de coleta de dados e reutilizar conjuntos de dados e modelos baixados prontos para uso.

Compre agora 🖱️

Gravar conjunto de dados

Passo 6

Gravar conjunto de dados

Grave conjuntos de dados locais ou envie-os para o Hugging Face Hub, mantendo o conjunto de dados limpo e consistente.

⚠️

Verificação de segurança antes de executar

Se você quiser salvar o conjunto de dados localmente, pode executá-lo diretamente:

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true \
  --dataset.repo_id=seeedstudio123/test \
  --dataset.num_episodes=5 \
  --dataset.single_task="Grab the black cube" \
  --dataset.push_to_hub=false \
  --dataset.episode_time_s=30 \
  --dataset.reset_time_s=30

Entre eles, repo_id pode ser modificado de forma personalizada, e push_to_hub=false. Por fim, o conjunto de dados será salvo no diretório ~/.cache/huggingface/lerobot na pasta home, onde a pasta seeedstudio123/test mencionada acima será criada.

Se você quiser usar os recursos do Hugging Face hub para enviar seu conjunto de dados e ainda não tiver feito isso antes, certifique-se de ter feito login usando um token com permissão de escrita, que pode ser gerado em Hugging Face settings:

huggingface-cli login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential

Armazene o nome do seu repositório Hugging Face em uma variável para executar estes comandos:

HF_USER=$(huggingface-cli whoami | head -n 1)
echo $HF_USER

Grave 5 episódios e envie seu conjunto de dados para o hub:

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true \
  --dataset.repo_id=${HF_USER}/record-test \
  --dataset.num_episodes=5 \
  --dataset.single_task="Grab the black cube" \
  --dataset.push_to_hub=true \
  --dataset.episode_time_s=30 \
  --dataset.reset_time_s=30

Você verá muitas linhas aparecendo como esta:

INFO 2024-08-10 15:02:58 ol_robot.py:219 dt:33.34 (30.0hz) dtRlead: 5.06 (197.5hz) dtWfoll: 0.25 (3963.7hz) dtRfoll: 6.22 (160.7hz) dtRlaptop: 32.57 (30.7hz) dtRphone: 33.84 (29.5hz)

Função de gravação

A função record fornece um conjunto de ferramentas para capturar e gerenciar dados durante a operação do robô.

1. Armazenamento de dados

Os dados são armazenados usando o formato LeRobotDataset e são gravados em disco durante a gravação.
Por padrão, o conjunto de dados é enviado para a sua página do Hugging Face após a gravação.
Para desativar o envio, use: --dataset.push_to_hub=False

2. Checkpoint e retomada

Checkpoints são criados automaticamente durante a gravação.
Para retomar após uma interrupção, execute novamente o mesmo comando com: --resume=true

⚠️ Nota crítica: Ao retomar, defina --dataset.num_episodes para o número de episódios adicionais a serem gravados (não o número total de episódios desejado no dataset).

Para começar a gravação do zero, exclua manualmente o diretório do dataset.

3. Parâmetros de Gravação

Defina o fluxo de gravação de dados usando argumentos de linha de comando:

Parâmetro	Descrição	Padrão
--dataset.episode_time_s	Duração por episódio de dados (segundos)	60
--dataset.reset_time_s	Tempo de reset do ambiente após cada episódio (segundos)	60
--dataset.num_episodes	Total de episódios a serem gravados	50

4. Controles de Teclado Durante a Gravação

Controle o fluxo de gravação de dados usando atalhos de teclado:

Tecla	Ação
→ (Seta para a direita)	Encerrar antecipadamente o episódio atual/resetar; ir para o próximo.
← (Seta para a esquerda)	Cancelar o episódio atual; regravá-lo.
ESC	Parar a sessão imediatamente, codificar os vídeos e enviar o dataset.

dica

Se o teclado não funcionar, talvez seja necessário instalar outra versão do pynput.

pip install pynput==1.6.8

Dicas para Coletar Dados

Sugestão de tarefa: Agarrar objetos em diferentes locais e colocá-los em uma caixa.
Escala: Grave ≥50 episódios (10 episódios por local).
Consistência:
- Mantenha as câmeras fixas.
- Mantenha o mesmo comportamento de preensão.
- Garanta que os objetos manipulados estejam visíveis nas imagens das câmeras.
Progressão:
- Comece com preensões confiáveis antes de adicionar variações (novos locais, técnicas, ajustes de câmera).
- Evite aumentar a complexidade rapidamente para prevenir falhas.

💡 Regra geral: Você deve ser capaz de executar a tarefa apenas olhando para as imagens da câmera.

Se quiser se aprofundar nesse tópico importante, você pode conferir o post no blog que escrevemos sobre o que torna um dataset bom.

Para problemas com atalhos de teclado durante a gravação, consulte a seção de FAQ no final desta página.

Visualizar Dataset

Dataset

Visualizar Dataset

Inspecione imagens, ações e episódios gravados antes do treinamento.

dica

Os códigos SO100 e SO101 são compatíveis. Usuários do SO100 podem utilizar diretamente os parâmetros e o código do SO101 para operação.

Se você enviou seu dataset para o hub com --control.push_to_hub=true, pode visualizar seu dataset online copiando e colando o seu repo id obtido por:

echo ${HF_USER}/so101_test

Se você não enviou com --dataset.push_to_hub=false, também pode visualizá-lo localmente com:

lerobot-dataset-viz \
--repo-id ${HF_USER}/so101_test \

Se você enviar com --dataset.push_to_hub=false, também pode visualizá-lo localmente com:

lerobot-dataset-viz \
--repo-id seeed_123/so101_test \

Aqui, seeed_123 é o nome personalizado de repo_id definido ao coletar os dados.

Reproduzir Dataset

Dataset

Reproduzir Dataset

Reproduza um episódio gravado no braço real para verificar a consistência das ações.

⚠️

Verificação de segurança antes de executar

dica

Os códigos SO100 e SO101 são compatíveis. Usuários do SO100 podem utilizar diretamente os parâmetros e o código do SO101 para operação.

Um recurso útil é a função replay, que permite reproduzir qualquer episódio que você tenha gravado ou episódios de qualquer dataset disponível. Essa função ajuda a testar a repetibilidade das ações do seu robô e avaliar a transferibilidade entre robôs do mesmo modelo.

Você pode reproduzir o primeiro episódio no seu robô com o comando abaixo ou com o exemplo de API:

lerobot-replay \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_awesome_follower_arm \
  --dataset.repo_id=seeedstudio123 \
  --dataset.root=~/.cache/huggingface/lerobot/seeedstudio123 \
  --dataset.episode=0 \

Seu robô deve reproduzir movimentos semelhantes aos que você gravou.

Neste comando, dataset.root especifica o caminho físico para o dataset, e dataset.repo_id é o nome personalizado definido durante a coleta de dados.

Treinar e Avaliar

Passo 7

Treinar e Avaliar

Treine e avalie políticas como ACT, SmolVLA, Pi0, Pi0.5, GR00T, PEFT e inferência assíncrona.

⚠️

Verificação de segurança antes de executar

ACT

Consulte ACT

Para treinar uma política para controlar seu robô, use o script lerobot-train.

Treinar

lerobot-train \
--dataset.repo_id=${HF_USER}/so101_test \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--wandb.enable=false \
--steps=300000

Se você quiser treinar em um dataset local, certifique-se de que o repo_id corresponda ao usado durante a coleta de dados e adicione --policy.push_to_hub=False.

lerobot-train \
--dataset.repo_id=seeedstudio123/test \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--wandb.enable=false \
--policy.push_to_hub=false\
--steps=300000

dica

Se você estiver usando uma GPU da série RTX 50, deve adicionar --dataset.video_backend=pyav ao comando de treinamento. Isso contorna APIs ausentes na versão de prévia do torchvision. O comando completo de treinamento deve ficar assim:

lerobot-train \
--dataset.repo_id=seeedstudio123/test \
--dataset.video_backend=pyav \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--policy.device=cuda \
--wandb.enable=false \
--policy.push_to_hub=false \
--steps=300000 \

Vamos explicar:

Especificação do dataset: Fornecemos o dataset por meio do parâmetro --dataset.repo_id=\${HF_USER}/so101_test.
Passos de treinamento: Modificamos o número de passos de treinamento usando --steps=300000. O algoritmo usa por padrão 800000 passos, e você pode ajustá-lo com base na dificuldade da sua tarefa e observando o loss durante o treinamento.
Tipo de política: Fornecemos a política com policy.type=act. Da mesma forma, você pode alternar entre políticas como [act, diffusion, pi0, pi0fast, pi0fast, sac, smolvla]., o que carregará a configuração de configuration_act.py. Importante: essa política se adaptará automaticamente aos estados dos motores, ações dos motores e ao número de câmeras do seu robô (por exemplo, laptop e phone), pois essas informações já estão armazenadas no seu dataset.
Seleção de dispositivo: Fornecemos policy.device=cuda porque estamos treinando em uma GPU Nvidia, mas você pode usar policy.device=mps para treinar em Apple Silicon.
Ferramenta de visualização: Fornecemos wandb.enable=true para visualizar gráficos de treinamento usando o Weights and Biases. Isso é opcional, mas, se você usar, certifique-se de ter feito login executando wandb login.

Avaliar

dica

Os códigos SO100 e SO101 são compatíveis. Usuários do SO100 podem utilizar diretamente os parâmetros e o código do SO101 para operação.

Você pode usar a função record de lerobot/record.py, mas com um checkpoint de política como entrada. Por exemplo, execute este comando para gravar 10 episódios de avaliação:

lerobot-record \
--robot.type=so100_follower \
--robot.port=/dev/ttyACM0 \
--robot.cameras="{ up: {type: opencv, index_or_path: /dev/video10, width: 640, height: 480, fps: 30, fourcc: "MJPG"}, side: {type: intelrealsense, serial_number_or_name: 233522074606, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--robot.id=my_awesome_follower_arm \
--display_data=false \
--dataset.repo_id=${HF_USER}/eval_so100 \
--dataset.single_task="Put lego brick into the transparent box" \
--policy.path=${HF_USER}/my_policy

como:

lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"},   side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--robot.id=my_awesome_follower_arm \
--display_data=false \
--dataset.repo_id=seeed/eval_test123 \
--dataset.single_task="Put lego brick into the transparent box" \
--policy.path=outputs/train/act_so101_test/checkpoints/last/pretrained_model

O parâmetro --policy.path indica o caminho para o arquivo de pesos dos resultados do treinamento da sua política (por exemplo, outputs/train/act_so101_test/checkpoints/last/pretrained_model). Se você enviar o arquivo de pesos do resultado do treinamento do modelo para o Hub, também poderá usar o repositório do modelo (por exemplo, \${HF_USER}/act_so100_test).
O nome do dataset dataset.repo_id começa com eval_. Essa operação irá gravar separadamente vídeos e dados durante a avaliação, que serão salvos na pasta que começa com eval_, como seeed/eval_test123.
Se você encontrar File exists: 'home/xxxx/.cache/huggingface/lerobot/xxxxx/seeed/eval_xxxx' durante a fase de avaliação, exclua primeiro a pasta que começa com eval_ e depois execute o programa novamente.
Ao encontrar mean is infinity. You should either initialize with stats as an argument or use a pretrained model, observe que palavras-chave como front e side no parâmetro --robot.cameras devem ser estritamente consistentes com as usadas ao coletar o dataset.

SmolVLA

SmolVLA é o modelo base leve para robótica da Hugging Face. Projetado para fácil fine-tuning em datasets do LeRobot, ele ajuda a acelerar o seu desenvolvimento!

Configure seu ambiente

Instale as dependências do SmolVLA executando:

pip install -e ".[smolvla]"

Faça o fine-tuning do SmolVLA com seus dados

Use smolvla_base, nosso modelo pré-treinado de 450M, e faça o fine-tuning com seus dados. Treinar o modelo por 20k steps levará aproximadamente ~4 horas em uma única GPU A100. Você deve ajustar o número de steps com base no desempenho e no seu caso de uso.

Se você não tiver um dispositivo com GPU, pode treinar usando nosso notebook no Google Colab.

Passe seu dataset para o script de treinamento usando --dataset.repo_id. Se quiser testar sua instalação, execute o seguinte comando em que usamos um dos datasets que coletamos para o artigo do SmolVLA.

lerobot-train \
--policy.path=lerobot/smolvla_base \
--dataset.repo_id=${HF_USER}/mydataset \
--batch_size=64 \
--steps=20000 \
--output_dir=outputs/train/my_smolvla \
--job_name=my_smolvla_training \
--policy.device=cuda \
--wandb.enable=true

dica

Você pode começar com um batch size pequeno e aumentá-lo gradualmente, se a GPU permitir, desde que os tempos de carregamento permaneçam curtos.

O fine-tuning é uma arte. Para uma visão completa das opções de fine-tuning, execute

lerobot-train --help

Avalie o modelo com fine-tuning e execute-o em tempo real

Da mesma forma que ao gravar um episódio, é recomendado que você esteja conectado ao HuggingFace Hub. Você pode seguir as etapas correspondentes: Gravar um dataset. Depois de fazer login, você pode executar a inferência na sua configuração fazendo:

lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/act_policy \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.cameras=="{ front: {type: opencv, index_or_path: 8, width: 640, height: 480, fps: 30, fourcc: "MJPG"}}" \
--display_data=true \
--task="Your task description" \ # can be skipped for ACT
--duration=60

Dependendo da sua configuração de avaliação, você pode configurar a duração e o número de episódios a serem gravados para sua suíte de avaliação.

LIBERO

LIBERO é um benchmark projetado para estudar o aprendizado contínuo de robôs. A ideia é que os robôs não serão apenas pré-treinados uma vez em uma fábrica, eles precisarão continuar aprendendo e se adaptando com seus usuários humanos ao longo do tempo. Essa adaptação contínua é chamada de aprendizado contínuo em tomada de decisão (LLDM), e é um passo fundamental para construir robôs que se tornem ajudantes verdadeiramente personalizados.

📄 Artigo do LIBERO
💻 Repositório original do LIBERO

Avaliando com LIBERO

No LeRobot, portamos o LIBERO para o nosso framework e o usamos principalmente para avaliar o SmolVLA, nosso modelo leve de Visão-Linguagem-Ação.

LIBERO agora faz parte da nossa simulação com suporte a multi-eval, o que significa que você pode avaliar suas políticas em uma única suíte de tarefas ou em múltiplas suítes de uma vez com apenas uma flag.

Para instalar o LIBERO, depois de seguir as instruções oficiais do LeRobot, basta fazer: pip install -e ".[libero]"

Avaliação de uma única suíte

Avalie uma política em uma suíte LIBERO:

lerobot-eval \
--policy.path="your-policy-id" \
--env.type=libero \
--env.task=libero_object \
--eval.batch_size=2 \
--eval.n_episodes=3

--env.task escolhe a suíte (libero_object, libero_spatial, etc.).
--eval.batch_size controla quantos ambientes são executados em paralelo.
--eval.n_episodes define quantos episódios serão executados no total.

Avaliação de múltiplas suítes

Avalie uma política em várias suítes de uma só vez:

lerobot-eval \
--policy.path="your-policy-id" \
--env.type=libero \
--env.task=libero_object,libero_spatial \
--eval.batch_size=1 \
--eval.n_episodes=2

Passe uma lista separada por vírgulas para --env.task para avaliação de múltiplas suítes.

Exemplo de comando de treinamento

lerobot-train \
--policy.type=smolvla \
--policy.repo_id=${HF_USER}/libero-test \
--dataset.repo_id=HuggingFaceVLA/libero \
--env.type=libero \
--env.task=libero_10 \
--output_dir=./outputs/ \
--steps=100000 \
--batch_size=4 \
--eval.batch_size=1 \
--eval.n_episodes=1 \
--eval_freq=1000 \

Observação sobre renderização

LeRobot usa MuJoCo para simulação. Você precisa definir o backend de renderização antes do treinamento ou da avaliação:

export MUJOCO_GL=egl → para servidores headless (por exemplo, HPC, nuvem)

Pi0

Consulte Pi0

pip install -e ".[pi]"

Treinar

lerobot-train \
  --dataset.repo_id=your_dataset \
  --policy.type=pi0 \
  --output_dir=./outputs/pi0_training \
  --job_name=pi0_training \
  --policy.pretrained_path=lerobot/pi0_base \
  --policy.repo_id=your_repo_id \
  --policy.compile_model=true \
  --policy.gradient_checkpointing=true \
  --policy.dtype=bfloat16 \
  --policy.freeze_vision_encoder=false \
  --policy.train_expert_only=false \
  --steps=3000 \
  --policy.device=cuda \
  --batch_size=32

Avaliar

lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"},   side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30,fourcc: "MJPG"}}" \
--robot.id=my_awesome_follower_arm \
--display_data=false \
--dataset.repo_id=seeed/eval_test123 \
--dataset.single_task="Put lego brick into the transparent box" \
--policy.path=outputs/pi0_training/checkpoints/last/pretrained_model

Pi0.5

Consulte Pi0.5

pip install -e ".[pi]"

Treinar

lerobot-train \
  --dataset.repo_id=seeed/eval_test123 \
  --policy.type=pi05 \
  --output_dir=./outputs/pi05_training \
  --job_name=pi05_training \
  --policy.repo_id=your_repo_id \
  --policy.pretrained_path=lerobot/pi05_base \
  --policy.compile_model=true \
  --policy.gradient_checkpointing=true \
  --wandb.enable=true \
  --policy.dtype=bfloat16 \
  --policy.freeze_vision_encoder=false \
  --policy.train_expert_only=false \
  --steps=3000 \
  --policy.device=cuda \
  --batch_size=32

Avaliar

lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"},   side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30,fourcc: "MJPG"}}" \
--robot.id=my_awesome_follower_arm \
--display_data=false \
--dataset.repo_id=seeed/eval_test123 \
--dataset.single_task="Put lego brick into the transparent box" \
--policy.path=outputs/pi05_training/checkpoints/last/pretrained_model

GR00T N1.5

Consulte a documentação oficial: GR00T N1.5.

GR00T N1.5 é um modelo base aberto da NVIDIA para raciocínio robótico mais geral e aprendizado de habilidades. É um modelo cross-embodiment: ele pode receber entradas multimodais como linguagem e imagens, e executar tarefas de manipulação em diferentes ambientes.

No LeRobot, o ponto-chave é definir o tipo de política como --policy.type=groot. Observe que o GR00T N1.5 tem requisitos de ambiente mais altos (ele depende de FlashAttention e requer uma GPU CUDA). Recomenda-se primeiro colocar ACT / Pi0 para rodar de ponta a ponta e, depois, testar o GR00T.

Instalação (importante)

De acordo com a documentação oficial atual, o GR00T N1.5 requer flash-attn e só pode ser usado em hardware compatível com CUDA.

Ordem recomendada:

Prepare primeiro o seu ambiente base (Python, CUDA, drivers, etc.). Não instale lerobot ainda.
Instale o PyTorch para a sua versão de CUDA (diferentes versões de CUDA podem exigir um --index-url diferente; siga a página de instalação do PyTorch).

pip install "torch>=2.2.1,<2.8.0" "torchvision>=0.21.0,<0.23.0"

dica

Se você estiver usando uma GPU RTX 50 Series, os seguintes requisitos devem ser atendidos: Python=3.10, CUDA=12.8, Torch=2.7.1

O comando de download é o seguinte:

pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128

Instale as dependências de build para flash-attn e, em seguida, instale o próprio flash-attn.

pip install ninja "packaging>=24.2,<26.0"
pip install "flash-attn>=2.5.9,<3.0.0" --no-build-isolation
python -c "import flash_attn; print(f'Flash Attention {flash_attn.__version__} imported successfully')"

dica

Se você estiver usando uma GPU RTX 50 Series, o seguinte requisito deve ser atendido: flash_attn=2.8.0

O comando de download é o seguinte:

pip install flash_attn==2.8.0.post2 torch==2.7.1 --no-build-isolation

Instale o LeRobot com as dependências opcionais de groot (lerobot[groot]).

pip install "lerobot[groot]"

dica

Se a instalação de flash-attn falhar, geralmente é devido a (1) incompatibilidade entre PyTorch/CUDA, (2) dependências de build ausentes ou (3) um ambiente muito novo/muito antigo. Verifique primeiro a documentação oficial do GR00T e as instruções de instalação do PyTorch.

Treinamento (fine-tuning)

A documentação oficial fornece um exemplo multi-GPU com accelerate launch --multi_gpu .... Se você tiver apenas uma única GPU, ainda pode começar fazendo um run de processo único funcionar primeiro (o suporte/argumentos exatos dependem da documentação oficial).

accelerate launch \
--multi_gpu \
--num_processes=$NUM_GPUS \
$(which lerobot-train) \
--output_dir=$OUTPUT_DIR \
--save_checkpoint=true \
--batch_size=$BATCH_SIZE \
--steps=$NUM_STEPS \
--save_freq=$SAVE_FREQ \
--log_freq=$LOG_FREQ \
--policy.push_to_hub=true \
--policy.type=groot \
--policy.repo_id=$REPO_ID \
--policy.tune_diffusion_model=false \
--dataset.repo_id=$DATASET_ID \
--wandb.enable=true \
--wandb.disable_artifact=true \
--job_name=$JOB_NAME

Validação no robô (avaliação)

Após o treinamento, você pode avaliar e gravar replays com lerobot-record como em outras políticas. A documentação oficial inclui um exemplo bimanual; usuários de braço único SO101 não precisam de argumentos do tipo left_arm_port/right_arm_port.

lerobot-record \
--robot.type=bi_so_follower \
--robot.left_arm_port=/dev/ttyACM1 \
--robot.right_arm_port=/dev/ttyACM0 \
--robot.id=bimanual_follower \
--robot.cameras='{ right: {"type": "opencv", "index_or_path": 0, "width": 640, "height": 480, "fps": 30}, left: {"type": "opencv", "index_or_path": 2, "width": 640, "height": 480, "fps": 30}, top: {"type": "opencv", "index_or_path": 4, "width": 640, "height": 480, "fps": 30} }' \
--display_data=true \
--dataset.repo_id=${HF_USER}/eval_groot_bimanual \
--dataset.num_episodes=10 \
--dataset.single_task="Grab and handover the red cube to the other arm" \
--policy.path=${HF_USER}/groot-bimanual \
--dataset.episode_time_s=30 \
--dataset.reset_time_s=10

Licença: Apache 2.0 (mesma do repositório original do GR00T).

(Opcional) Fine-tuning Eficiente em Parâmetros (PEFT)

PEFT (Parameter-Efficient Fine-Tuning) é uma família de métodos e ferramentas que ajuda um grande modelo pré-treinado a se adaptar a novas tarefas sem atualizar todos os parâmetros. Para políticas LeRobot pré-treinadas (por exemplo, SmolVLA, Pi0), você geralmente pode treinar apenas um pequeno conjunto de parâmetros “adaptadores” (por exemplo, LoRA) para reduzir o uso de VRAM e o custo de treinamento, ainda assim alcançando desempenho próximo ao do fine-tuning completo.

Instalação

Após instalar o LeRobot com as dependências opcionais de peft, você pode usar argumentos relacionados a PEFT no treinamento.

pip install -e ".[peft]"

pip install "lerobot[peft]"

Mais conceitos e métodos: 🤗 documentação do PEFT.

Exemplo: fazer fine-tuning do SmolVLA com LoRA (subtarefa LIBERO libero_spatial)

Este exemplo faz fine-tuning de lerobot/smolvla_base com LoRA no dataset HuggingFaceVLA/libero. Os nomes dos argumentos dependem da versão do LeRobot; recomenda-se também verificar lerobot-train --help.

lerobot-train \
--policy.path=lerobot/smolvla_base \
--policy.repo_id=${HF_USER}/my_libero_smolvla_peft \
--dataset.repo_id=HuggingFaceVLA/libero \
--env.type=libero \
--env.task=libero_spatial \
--output_dir=outputs/train/my_libero_smolvla_peft \
--job_name=my_libero_smolvla_peft \
--policy.device=cuda \
--steps=10000 \
--batch_size=32 \
--optimizer.lr=1e-3 \
--peft.method_type=LORA \
--peft.r=64

Principais argumentos de PEFT

--peft.method_type: Seleciona o método PEFT. LoRA (Low-Rank Adapter) é uma das opções mais comuns.
--peft.r: Rank do LoRA. Um rank mais alto geralmente aumenta a capacidade, mas também aumenta a contagem de parâmetros e o uso de VRAM.

Escolher em quais camadas/módulos injetar LoRA (opcional)

Por padrão, o PEFT geralmente injeta LoRA nas camadas de projeção mais importantes (por exemplo, atenção q_proj, v_proj), e também pode cobrir projeções de estado/ação. Se você quiser personalizar, use --peft.target_modules.

Padrões comuns:

Fornecer uma lista de sufixos de nomes de módulos (exemplo):

--peft.target_modules="['q_proj', 'v_proj']"

Fornecer uma regex (exemplo; ajuste aos nomes reais dos módulos no modelo):

--peft.target_modules='(model\\.vlm_with_expert\\.lm_expert\\..*\\.(down|gate|up)_proj|.*\\.(state_proj|action_in_proj|action_out_proj|action_time_mlp_in|action_time_mlp_out))'

Treinar completamente alguns módulos (opcional)

Se você quiser que alguns módulos sejam totalmente treinados (em vez de apenas injetar LoRA), use --peft.full_training_modules. Por exemplo, treinar completamente apenas state_proj:

--peft.full_training_modules="['state_proj']"

Sugestão de taxa de aprendizado (regra prática)

Taxas de aprendizado para LoRA costumam ser ~10× maiores do que no fine-tuning completo. Por exemplo, se o fine-tuning completo normalmente usa 1e-4, o LoRA pode começar em 1e-3. Se você usar um scheduler de taxa de aprendizado, a taxa final costuma ficar em torno de 1e-4 como referência.

(Opcional) Treinamento multi-GPU com Accelerate

Etapas de treinamento

Método 1: usar flags de CLI.

Instale accelerate no seu ambiente lerobot.

pip install accelerate

Inicie o treinamento multi-GPU com accelerate launch e as flags --multi_gpu e --num_processes.

accelerate launch \

--multi_gpu \

--num_processes=2 \

$(which lerobot-train) \

--dataset.repo_id=${HF_USER}/my_dataset \

--policy.type=act \

--policy.repo_id=${HF_USER}/my_trained_policy \

--output_dir=outputs/train/act_multi_gpu \

--job_name=act_multi_gpu \

--wandb.enable=true

Principais flags do accelerate:

--multi_gpu: Habilita o treinamento multi-GPU.
--num_processes: Número de GPUs a serem usadas (geralmente igual ao número de GPUs disponíveis na máquina).
--mixed_precision=fp16: Usa precisão mista fp16 (se o seu hardware suportar, você também pode usar bf16).

Observe: bf16 requer suporte de hardware e não está disponível em todas as GPUs.

Precisão	Suporte de hardware
fp16	Suportado por quase todas as GPUs NVIDIA
bf16	Suportado apenas por algumas GPUs mais novas (Ampere e posteriores)

Se a sua GPU não suportar bf16, escolha fp16 na configuração do Accelerate ou especifique fp16 explicitamente.

Método 2: usar um arquivo de configuração do accelerate (opcional).

Se você treina em múltiplas GPUs com frequência, pode salvar a configuração para evitar digitar repetidamente as mesmas flags.

accelerate config salva a configuração do seu hardware (número de GPUs, precisão mista, etc.) em um arquivo de configuração, para que você não precise reinserir essas opções ao executar accelerate launch depois. Isso não altera a lógica de treinamento do LeRobot; apenas reduz entradas repetidas na CLI.

Se você só usa multi-GPU ocasionalmente (ou se esta é a sua primeira vez), pular isso é totalmente aceitável.

Na configuração interativa, para o cenário comum de “máquina única + múltiplas GPUs”, as escolhas típicas são:

Ambiente de computação: Esta máquina
Número de máquinas: 1
Número de processos: Número de GPUs que você deseja usar
IDs de GPU a usar: pressione Enter (usar todas as GPUs)
Precisão mista: prefira fp16; escolha bf16 apenas se você souber que sua GPU o suporta

accelerate config

accelerate launch $(which lerobot-train) \

--dataset.repo_id=${HF_USER}/my_dataset \

--policy.type=act \

--policy.repo_id=${HF_USER}/my_trained_policy \

--output_dir=outputs/train/act_multi_gpu \

--job_name=act_multi_gpu \

--wandb.enable=true

Como o uso de múltiplas GPUs afeta os hiperparâmetros (e como ajustá-los)

LeRobot não ajusta automaticamente a taxa de aprendizado nem os passos de treinamento com base no número de GPUs, para evitar alterar silenciosamente o comportamento do treinamento. Isso é diferente de alguns outros frameworks de treinamento distribuído.

Se você quiser ajustar os hiperparâmetros para múltiplas GPUs, uma abordagem comum é:

Passos: o batch size efetivo aumenta (batch_size × num_gpus), então você pode reduzir o número de passos aproximadamente proporcional a 1 / num_gpus para manter um número total semelhante de amostras vistas.

accelerate launch --num_processes=2 $(which lerobot-train) \

--batch_size=8 \

--steps=50000 \

--dataset.repo_id=lerobot/pusht \

--policy=act

Taxa de aprendizado: como cada passo usa mais amostras, você geralmente pode escalar a taxa de aprendizado linearmente com o número de GPUs: new_lr = single_gpu_lr × num_gpus

accelerate launch --num_processes=2 $(which lerobot-train) \

--optimizer.lr=2e-4 \

--dataset.repo_id=lerobot/pusht \

--policy=act

Essas não são regras rígidas; são heurísticas comuns. Se você não tiver certeza, também pode manter a taxa de aprendizado e o número de passos inalterados, desde que o treinamento permaneça estável.

Para configurações avançadas e solução de problemas, consulte a documentação do Accelerate: Accelerate.

(Opcional) Inferência assíncrona

Quando a inferência assíncrona não está habilitada, o fluxo de controle do LeRobot pode ser entendido como inferência sequencial / síncrona convencional: a policy primeiro prevê um segmento de ações, depois executa esse segmento e, somente depois disso, espera pela próxima previsão.

Para modelos maiores, isso pode fazer com que o robô faça uma pausa perceptível enquanto espera pelo próximo bloco de ações.

O objetivo da inferência assíncrona é permitir que o robô execute o bloco de ações atual enquanto calcula o próximo com antecedência, reduzindo assim o tempo ocioso e melhorando a capacidade de resposta.

A inferência assíncrona é aplicável às policies suportadas pelo LeRobot, incluindo policies de ação baseadas em blocos (chunk-based) como ACT, OpenVLA, Pi0 e SmolVLA.

Como a inferência é desacoplada do controle real, a inferência assíncrona também ajuda a aproveitar máquinas com recursos de computação mais fortes para realizar a inferência para o robô.

Você pode ler mais sobre inferência assíncrona no blog da Hugging Face

Primeiro, vamos apresentar alguns conceitos básicos:

Cliente: conecta-se ao braço robótico e às câmeras, coleta dados de observação (como imagens e poses do robô), envia essas observações para o servidor e recebe os blocos de ações retornados pelo servidor, executando-os em ordem.
Servidor: o dispositivo que fornece recursos de computação. Ele recebe dados da câmera e do braço robótico, realiza a inferência (isto é, o cálculo) para produzir blocos de ações e os envia de volta ao cliente. Pode ser o mesmo dispositivo conectado ao braço robótico e às câmeras, outro computador na mesma rede local ou um servidor em nuvem alugado na Internet.
Bloco de ações (action chunk): uma sequência de comandos de ação do braço robótico obtida por inferência da policy no lado do servidor.

Três cenários de implantação para inferência assíncrona

Implantação em máquina única

O robô, as câmeras, o cliente e o servidor estão todos no mesmo dispositivo.

Este é o caso mais simples: o servidor pode escutar em 127.0.0.1, e o cliente também pode se conectar a 127.0.0.1:port. O exemplo de comando na documentação oficial é para este cenário.

Implantação em LAN

O robô e as câmeras estão conectados a um dispositivo leve, enquanto o servidor de policy é executado em outra máquina com alta capacidade de computação na mesma rede local.

Nesse caso, o servidor deve escutar em um endereço acessível por outras máquinas, e o cliente também deve se conectar ao IP da LAN do servidor, em vez de 127.0.0.1.

Implantação entre redes / em nuvem

O servidor de policy é executado em um host de nuvem publicamente acessível, e o cliente se conecta a ele pela Internet pública.

Essa abordagem pode usar a GPU mais potente do host em nuvem. Quando as condições de rede são boas, o tempo de ida e volta da rede (latência de rede) às vezes pode ser relativamente pequeno em comparação com o tempo de inferência, mas isso depende do seu ambiente de rede real.

Nota de segurança: o pipeline de inferência assíncrona do LeRobot tem um risco relacionado a gRPC sem autenticação + desserialização com pickle. Se houver informações ou serviços importantes no servidor, não é recomendado expor o serviço diretamente à Internet em uma implantação pública. Uma abordagem mais segura é usar VPN ou tunelamento SSH ou, pelo menos, restringir ao máximo os IPs de origem permitidos no grupo de segurança ao IP público do seu próprio cliente.

Introdução à implantação de inferência assíncrona

Etapa 1: Configuração do ambiente

Primeiro, use pip para instalar as dependências adicionais necessárias para a inferência assíncrona. Tanto o cliente quanto o servidor precisam ter o lerobot instalado junto com as dependências extras:

pip install -e ".[async]"

Etapa 2: Configuração e verificações de rede

Problemas de proxy

Se o seu terminal atual estiver configurado para usar um proxy e a conexão se comportar de forma anormal, você pode desativar temporariamente as variáveis de ambiente de proxy:

unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY

Observação: o comando acima afeta apenas a sessão de terminal atual. Se você abrir outra janela de terminal, precisará executá-lo novamente.

Abrir a porta no firewall / grupo de segurança

Implantação em máquina única: isso geralmente pode ser ignorado.

Implantação em LAN: você precisa abrir a porta de escuta no lado do servidor.

Exemplo de abertura da porta de escuta em uma configuração de LAN (executar no lado do servidor):

sudo ufw allow 8080/tcp

Implantação em nuvem: você precisa abrir essa porta no grupo de segurança do servidor em nuvem, e é recomendável restringir o máximo possível os IPs de origem.

Se você estiver executando em um servidor em nuvem:

Abra a porta 8080 no grupo de segurança do console de gerenciamento do servidor ou use outra porta que já esteja aberta. Diferentes plataformas de serviços em nuvem lidam com isso de maneiras diferentes; consulte a documentação do seu provedor de nuvem.

Confirmar o endereço IP

Esta etapa pode ser ignorada para implantação em máquina única (o endereço IP para uma única máquina é sempre 127.0.0.1).

Se for uma implantação em LAN:

Você precisa confirmar e memorizar o endereço IP da LAN do lado do servidor. Quando o cliente se conectar, o que deve ser preenchido é o IP da LAN da máquina que está executando o policy_server, não o IP do próprio cliente.

Linux / Jetson / Raspberry Pi:

hostname -I

Se vários endereços forem exibidos, geralmente escolha o que corresponde à interface de rede da LAN atual, por exemplo 192.168.x.x.

Você também pode usar:

ip addr

para visualizar o campo inet sob a interface de rede atualmente conectada.

Windows:

ipconfig

Encontre um campo como IPv4 Address . . . . . . . . . . . : 192.168.14.140; esse é o endereço IP da LAN dessa máquina.

macOS:

ifconfig

Encontre o campo inet correspondente à interface de rede atualmente conectada; esse é o endereço IP da LAN.

Precisamos memorizar o endereço IP da LAN do lado do servidor. Usaremos <LAN IP address> para nos referir a ele.

Se for uma implantação em servidor em nuvem:

Procure o IP público no painel de controle do servidor. Geralmente ele é chamado de uma das seguintes formas:

Public IPv4

External IP

Public IP address

EIP

Public IP

Precisamos memorizar o endereço IP público. Usaremos <server public IP> para nos referir a ele.

Teste de conexão

Implantação em máquina única: esta etapa pode ser ignorada

Implantação em LAN / nuvem: é recomendável testar, a partir do lado do cliente, se a porta do servidor é alcançável. Exemplos de testes são os seguintes:

Exemplo em LAN: executar no lado do cliente

nc -vz <LAN IP address> 8080

Exemplo em nuvem: executar no lado do cliente

nc -vz <server public IP> 8080

Etapa 3: Iniciar o serviço

Cenário A: Implantação em máquina única

Inicie o serviço local em um terminal:

python -m lerobot.async_inference.policy_server \
--host=127.0.0.1 \
--port=8080

Depois que ele iniciar com sucesso, você precisa manter esse terminal aberto. Será necessário abrir um novo terminal para executar outros comandos.

Cenário B: Implantação em LAN

Executar no lado do servidor:

python -m lerobot.async_inference.policy_server \
--host=0.0.0.0 \
--port=8080

Nesse caso, quando o cliente se conectar, o --server_address deve ser o endereço IP da LAN do lado do servidor, como <LAN IP address>:8080.

Cenário C: Implantação em servidor em nuvem

Executar no lado do servidor:

python -m lerobot.async_inference.policy_server \
--host=0.0.0.0 \
--port=8080

Nesse caso, quando o cliente se conectar, o --server_address deve ser o endereço IP público do servidor, como <server public IP>:8080.

Etapa 4: Escolher parâmetros de inferência

Executar no lado do cliente:

python -m lerobot.async_inference.robot_client \
--server_address=<ip address>:8080 \
--robot.type=so100_follower \
--robot.port=/dev/tty.usbmodem585A0076841 \
--robot.id=follower_so100 \
--robot.cameras="{ laptop: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}, phone: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
--task="dummy" \
--policy_type=your_policy_type \
--pretrained_name_or_path=user/model \
--policy_device=cuda \
--actions_per_chunk=50 \
--chunk_size_threshold=0.5 \
--aggregate_fn_name=weighted_average \
--debug_visualize_queue_size=True

Explicações dos parâmetros:

--server_address

Especifica o endereço e a porta do servidor de políticas. <ip address> deve ser substituído por 127.0.0.1 (máquina local), <LAN IP address> (LAN) ou <server public IP> (servidor em nuvem).

--robot.type, --robot.port, --robot.id, --robot.cameras

Parâmetros do dispositivo de hardware. Eles devem ser mantidos consistentes com os parâmetros usados durante a coleta do conjunto de dados.

--task

A descrição da tarefa. Políticas visão-linguagem como SmolVLA podem determinar o alvo da ação com base no texto da tarefa.

--policy_type

Substitua isto pelo nome específico da política, por exemplo:

smolvla
act
--pretrained_name_or_path

Este valor deve ser substituído pelo caminho do modelo no lado do servidor ou por um caminho de modelo no Hugging Face.

--policy_device

Especifica o dispositivo de inferência usado no lado do servidor.

Pode ser cuda, mps ou cpu.

--actions_per_chunk=50

Especifica quantas ações são geradas em cada inferência.

Quanto maior esse valor:

Vantagem: o buffer de ações é mais abundante, tornando menos provável que ele se esgote Desvantagem: o horizonte de predição é maior, então o erro de controle pode se acumular de forma mais perceptível

--chunk_size_threshold=0.5

Especifica quando solicitar o próximo bloco de ações ao servidor.

Este é um limiar, geralmente no intervalo de 0 a 1.

Pode ser entendido como: quando a proporção restante da fila de ações atual cai abaixo desse limiar, o cliente enviará uma nova observação com antecedência e solicitará o próximo bloco de ações.

Definir como 0,5 aqui significa:

quando o bloco de ações atual estiver aproximadamente pela metade consumido

o cliente começa a solicitar o próximo bloco de ações

Quanto maior esse valor, mais frequentemente as requisições são enviadas e mais responsivo o sistema se torna, mas a carga no servidor também aumenta.

Quanto menor esse valor, mais o comportamento se aproxima da inferência síncrona.

--aggregate_fn_name=weighted_average

Especifica o método de agregação para intervalos de ações sobrepostos.

Na inferência assíncrona, quando o bloco de ações antigo ainda não foi totalmente executado, o novo bloco de ações já pode ter chegado.

Nesse caso, os dois blocos se sobrepõem em parte do intervalo de tempo, e é necessária uma função de agregação para combiná-los na ação final executada.

O significado de weighted_average é:

usar uma média ponderada para fundir a parte sobreposta.

Isso geralmente torna a troca de ações mais suave e reduz mudanças bruscas.

--debug_visualize_queue_size=True

Define se o tamanho da fila de ações será visualizado em tempo de execução.

Quando ativado, permite ver mais diretamente se a fila atinge o fundo com frequência, o que ajuda a ajustar actions_per_chunk e chunk_size_threshold.

Etapa 5: Ajuste os parâmetros com base no comportamento do robô

Na inferência assíncrona, há dois parâmetros adicionais que precisam de ajuste e que não existem na inferência síncrona:

Parâmetro Valor inicial sugerido Descrição

actions_per_chunk 50 Quantas ações a política gera de uma vez. Valores típicos: 10–50.

chunk_size_threshold 0.5 Quando a proporção restante da fila de ações é ≤ chunk_size_threshold, o cliente envia uma nova requisição de bloco de ações. O intervalo de valores é [0, 1].

Quando --debug_visualize_queue_size=True, a variação do tamanho da fila de ações será plotada em tempo de execução.

O que a inferência assíncrona precisa equilibrar é: a velocidade com que o servidor gera blocos de ações deve ser maior ou igual à velocidade com que o cliente consome blocos de ações. Caso contrário, a fila de ações ficará vazia e o robô começará a travar novamente (isso pode ser visto como a curva batendo no fundo na visualização da fila).

A velocidade com que o servidor gera blocos de ações é afetada por fatores como tamanho do modelo, tipo de dispositivo, VRAM / memória e poder de computação da GPU.

A velocidade com que o cliente consome blocos de ações é afetada pelo fps de execução configurado.

Se a fila frequentemente ficar vazia, você precisa aumentar actions_per_chunk, aumentar chunk_size_threshold ou reduzir o fps.

Se a curva da fila oscilar com frequência, mas as ações restantes na fila forem sempre suficientes, você pode diminuir chunk_size_threshold de forma apropriada.

Em geral:

o intervalo empírico para actions_per_chunk é 10–50

o intervalo empírico para chunk_size_threshold é 0,5–0,7; ao ajustar, é recomendável começar em 0,5 e aumentá-lo gradualmente

Se você encontrar o seguinte erro:

TypeError: stack(): argument 'tensors' (position 1) must be tuple of Tensors, not Column

Tente executar o seguinte comando para resolvê-lo:

pip install datasets==2.19

O treinamento deve levar várias horas. Você encontrará checkpoints em outputs/train/act_so100_test/checkpoints.

Para retomar o treinamento a partir de um checkpoint, abaixo está um comando de exemplo para retomar do checkpoint last da política act_so101_test:

lerobot-train \
--config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true

Fazer upload dos checkpoints da política

Quando o treinamento terminar, faça upload do checkpoint mais recente com:

huggingface-cli upload ${HF_USER}/act_so101_test \
outputs/train/act_so101_test/checkpoints/last/pretrained_model

Você também pode fazer upload de checkpoints intermediários com:

CKPT=010000
huggingface-cli upload ${HF_USER}/act_so101_test${CKPT} \
outputs/train/act_so101_test/checkpoints/${CKPT}/pretrained_model

FAQ

Centralização da solução de problemas para portas, IDs de servos, ffmpeg, câmeras, conjuntos de dados, avaliação e treinamento.

Qual repositório LeRobot devo usar?

Use o repositório recomendado neste wiki:

git clone https://github.com/Seeed-Projects/lerobot.git ~/lerobot

Esta versão foi verificada com o SO-ARM10x. O repositório LeRobot upstream muda rapidamente, portanto argumentos de comando, formatos de conjunto de dados e dependências podem ser diferentes deste tutorial.

Motor 'gripper' was not found durante a configuração do ID do servo

Se você vir o seguinte erro:

Motor 'gripper' was not found, Make sure it is connected

verifique se o cabo de comunicação está conectado corretamente e se o barramento do servo está alimentado com a tensão correta.

Could not connect on port "/dev/ttyACM0"

Se /dev/ttyACM0 existir, mas o LeRobot não conseguir se conectar a ele, geralmente faltam permissões da porta serial. Execute:

sudo chmod 666 /dev/ttyACM*

Também verifique novamente se os braços líder e seguidor estão mapeados para as portas esperadas.

No valid stream found in input file

Se você vir:

No valid stream found in input file. Is -1 of the desired media type?

instale o ffmpeg 7.1.1:

conda install ffmpeg=7.1.1 -c conda-forge

Present_Position sync read failed

Se você vir:

ConnectionError: Failed to sync read 'Present_Position' on ids=[1,2,3,4,5,6] after 1 tries. [TxRxResult] There is no status packet!

verifique se o braço correspondente está ligado e se os cabos de dados do barramento do servo estão soltos ou desconectados. Se o LED de um servo estiver apagado, o cabo antes desse servo pode estar solto.

Magnitude 30841 exceeds 2047 durante a calibração

Se você vir:

Magnitude 30841 exceeds 2047 (max for sign_bit_index=11)

desligue e reinicie o braço e, em seguida, calibre novamente. Se o problema persistir, use a ferramenta de calibração rápida Seeed Studio SoARM para realizar a calibração de posição central e verificação de ID dos servos e, depois, refaça a calibração de todo o braço.

Como recalibrar após reparo ou substituição de peças?

Exclua os arquivos de calibração antigos e calibre novamente:

rm -rf ~/.cache/huggingface/lerobot/calibration/robots
rm -rf ~/.cache/huggingface/lerobot/calibration/teleoperators

As informações de calibração são armazenadas como arquivos JSON nesses diretórios. Se o hardware mudar, mas os arquivos de calibração antigos permanecerem, o LeRobot pode reutilizar offsets desatualizados.

Atalhos de teclado não funcionam durante a gravação

Se a tecla de seta para a direita, seta para a esquerda ou ESC não responder durante a gravação do conjunto de dados, primeiro verifique se a variável de ambiente $DISPLAY está definida. Você também pode tentar fazer downgrade do pynput:

pip install pynput==1.6.8

Como devo lidar com episódios com falha durante a gravação?

Se o objeto cair, o gripper errar ou a qualidade do episódio for ruim, mova o braço de volta para uma pose de descanso segura e pressione a tecla de seta para a esquerda para descartar e regravar o episódio. Se a tarefa terminar cedo e o robô já tiver retornado ao descanso, pressione a tecla de seta para a direita para ir para o próximo episódio sem esperar por todo o tempo restante.

Com o que devo tomar cuidado durante a coleta do conjunto de dados?

Mantenha estáveis a posição da câmera, o ângulo da câmera e a iluminação ambiente. Evite fundos instáveis ou pedestres no campo de visão da câmera, pois grandes diferenças entre o ambiente de gravação e o de implantação podem fazer com que a política falhe.

Defina --dataset.num_episodes alto o suficiente antes de começar. Não pare a gravação manualmente no meio, a menos que seja necessário, porque estatísticas do conjunto de dados, como média e variância, são calculadas após o término da coleta e são necessárias para o treinamento.

Como excluir ou modificar conjuntos de dados gravados?

Para excluir ou editar conjuntos de dados gravados, consulte o tutorial da ferramenta de conjunto de dados:

Dataset Tool

Dados de imagem da câmera USB não podem ser lidos

Evite conectar a câmera USB por meio de um hub USB. Conecte-a diretamente ao dispositivo, de preferência por uma porta USB 3.0, para garantir largura de banda suficiente para transmissão de imagem.

Tempo limite ou incompatibilidade de número de série da câmera Orbbec

Se você vir um tempo limite ao aguardar quadros, desconecte e reconecte a câmera. Se você vir:

No Orbbec camera found for 'XXXX'

execute o comando de detecção da câmera e atualize serial_number_or_name com o número de série real:

lerobot-find-cameras orbbec

File exists durante a avaliação

Se a avaliação informar que um diretório eval_ já existe, exclua primeiro a pasta de avaliação existente e execute o programa novamente.

File exists: 'home/xxxx/.cache/huggingface/lerobot/xxxxx/seeed/eval_xxxx'

mean is infinity durante a avaliação

Se você vir:

mean is infinity. You should either initialize with stats as an argument or use a pretrained model

certifique-se de que as chaves da câmera em --robot.cameras, como front e side, correspondam exatamente às chaves usadas durante a gravação do conjunto de dados.

TypeError: stack(): argument 'tensors' must be tuple of Tensors

Se você vir:

TypeError: stack(): argument 'tensors' (position 1) must be tuple of Tensors, not Column

tente instalar a versão compatível do datasets:

pip install datasets==2.19

rerun não tem o atributo scalar

Se você vir:

AttributeError: module 'rerun' has no attribute 'scalar'. Did you mean: 'scalars'?

faça o downgrade do SDK do rerun:

pip3 install rerun-sdk==0.23

Quanto tempo o treinamento ACT geralmente leva?

Como referência aproximada, treinar ACT em 50 episódios leva cerca de 6 horas em um laptop com RTX 3060 8GB, e cerca de 2–3 horas em uma RTX 4090 ou A100. O tempo real depende do tamanho do conjunto de dados, resolução da imagem, tamanho do lote e hardware.

dica

Se você encontrar problemas de software ou dependências não resolvidos após verificar este FAQ, relate-os no repositório LeRobot no GitHub ou no canal LeRobot no Discord.

Citação

Referências

Citação

Documentação, projetos, artigos e recursos externos relacionados.

Chinese Document

Projeto TheRobotStudio: SO-ARM10x

Projeto Huggingface: Lerobot

Dnsty: Jetson Containers

Suporte Técnico e Discussão de Produtos

Suporte

Suporte Técnico e Discussão de Produtos

Entre em contato com a Seeed Studio e participe de discussões na comunidade sobre dúvidas de produtos.

Obrigado por escolher nossos produtos! Estamos aqui para oferecer diferentes formas de suporte para garantir que sua experiência com nossos produtos seja a mais tranquila possível. Oferecemos vários canais de comunicação para atender a diferentes preferências e necessidades.

ForumFaça perguntas sobre produtos e questões técnicas no fórum da Seeed.Email SupportEntre em contato diretamente com o suporte da Seeed Studio.DiscordJunte-se à comunidade Seeed no Discord.GitHub DiscussionDiscuta conteúdo da wiki e problemas de documentação.

Da montagem e calibração à coleta de datasets, treinamento e implantação em robôs reais

Trilha de aprendizado recomendada​

Siga o fluxo de trabalho real de depuração passo a passo

Visão geral​

Introdução ao projeto

Guia de impressão 3D​

Guia de impressão 3D

Ambiente inicial do sistema​

Ambiente inicial do sistema

Instalar LeRobot​

Instalar LeRobot

Configurar motores e montar o braço​

Configurar motores e montar o braço

Calibrar o Braço Robótico​

Calibrar o Braço Robótico

Recalibrar o braço robótico​

(Opcional) Calibração de posição central com a ferramenta rápida Seeed Studio SoARM​

1) Clonar a ferramenta do GitHub e instalar dependências​

2) Calibração de posição central e verificação​

Teleoperação​

Teleoperação

Adicionar câmeras​

Adicionar câmeras

Gravar conjunto de dados​

Gravar conjunto de dados

Visualizar Dataset​

Visualizar Dataset

Reproduzir Dataset​

Reproduzir Dataset

Treinar e Avaliar​

Treinar e Avaliar

FAQ​

FAQ

Citação​

Citação

Suporte Técnico e Discussão de Produtos​

Suporte Técnico e Discussão de Produtos

Trilha de aprendizado recomendada

Visão geral

Guia de impressão 3D

Ambiente inicial do sistema

Instalar LeRobot

Configurar motores e montar o braço

Calibrar o Braço Robótico

Recalibrar o braço robótico

(Opcional) Calibração de posição central com a ferramenta rápida Seeed Studio SoARM

1) Clonar a ferramenta do GitHub e instalar dependências

2) Calibração de posição central e verificação

Teleoperação

Adicionar câmeras

Gravar conjunto de dados

Visualizar Dataset

Reproduzir Dataset

Treinar e Avaliar

FAQ

Citação

Suporte Técnico e Discussão de Produtos