企业官网建设流程全解析

1. 为什么SO-ARM100值得折腾：从开箱到跑通ACT的完整路径

SO-ARM100这台桌面级六轴机械臂，最近在开源机器人圈子里热度不低。它最大的卖点就是便宜、结构简单、完全开源，配合LeRobot这套框架，能把模仿学习（Imitation Learning）的整套流程跑通。我前后花了大概两周时间，从零开始把环境搭起来，中间踩了不少坑，也积累了一些调参经验，这篇文章就把整个过程完整记录下来。

如果你手上正好有一台SO-ARM100，或者正在考虑入手，又或者你只是想了解ACT（Action Chunking Transformer）这类模仿学习模型在真实硬件上怎么落地，那这篇内容应该能帮你省下不少时间。我会从硬件组装、软件环境、数据采集、模型训练到调参，一步步拆开讲，重点放在那些官方文档里不会写、但实际一定会遇到的问题上。

先说结论：SO-ARM100加LeRobot这套组合，门槛不算高，但坑比较分散。环境依赖、串口权限、相机标定、数据格式、训练超参，每个环节都有让人卡住的地方。下面我按实际操作的顺序来展开。

2. 硬件准备与组装：别小看那几个螺丝

2.1 物料清单与采购建议

SO-ARM100的物料清单在官方仓库里有详细说明，我这里只强调几个容易出问题的点。舵机用的是Feetech STS3215系列，这个舵机支持串口通信，可以读取位置反馈，这是后面做数据采集的基础。买的时候注意区分电压版本，7.4V和12V的扭矩不一样，12V版本在负载稍大的场景下更稳。

3D打印件建议用PETG或者ABS，PLA在舵机发热后容易变形，尤其是底座和关节连接处。我第一版用PLA打的，跑了半小时后关节就有轻微松动，后来换成PETG才稳定下来。打印填充率至少30%，关键受力件可以到50%。

螺丝和轴承这些标准件，建议多买一套备用。M3螺丝在反复拆装后容易滑丝，尤其是拧进打印件的时候，力矩控制不好就会把螺纹搞坏。

2.2 组装顺序与关键细节

组装顺序官方有步骤图，我按自己的经验调整了一下，建议先装底座和第一关节，再往上逐级装。每装一个关节，先手动转动确认没有卡涩，再通电测试舵机。

舵机ID的配置是第一个大坑。每个舵机出厂默认ID都是1，你需要用Feetech的调试工具或者LeRobot自带的脚本逐个改ID。改ID的时候只能单独连接一个舵机，否则总线上的ID冲突会导致通信失败。我一开始不知道，六个舵机全接上，结果一个都认不到，排查了半天才发现是ID冲突。

注意：改舵机ID之前，先把所有舵机的中位校准好。中位没校准，后面组装完机械臂的零位就是歪的，数据采集出来的轨迹全是偏的。

2.3 串口权限与通信测试

在Ubuntu下，串口设备默认权限是root，普通用户访问不了。你需要把当前用户加到dialout组：

sudo usermod -aG dialout $USER

改完要重新登录才生效。然后确认设备节点：

ls /dev/ttyACM*

正常情况下会看到/dev/ttyACM0。如果没有，检查USB线是不是只供电不传数据的那种，换一根质量好点的线。

通信测试可以用LeRobot自带的脚本：

python -m lerobot.scripts.setup_motors --port /dev/ttyACM0

这个脚本会扫描总线上的舵机，读取当前位置和ID。如果报超时，先降波特率试试，默认是1000000，有些舵机固件版本对高波特率支持不好，降到500000就稳了。

3. 软件环境搭建：Python依赖是重灾区

3.1 系统选择与基础环境

我用的Ubuntu 22.04，Python 3.10。LeRobot对Python版本有要求，3.8到3.11都行，但3.10是最稳的。不建议用Windows，串口和相机这块在Linux下省心太多。

先装基础依赖：

sudo apt update sudo apt install -y python3-pip python3-venv git cmake build-essential

然后创建虚拟环境：

python3 -m venv lerobot_env source lerobot_env/bin/activate

虚拟环境这一步别省，LeRobot的依赖和系统Python容易冲突，尤其是torch和numpy的版本。

3.2 LeRobot安装与依赖处理

官方推荐从源码装：

git clone https://github.com/huggingface/lerobot.git cd lerobot pip install -e .

这里有个坑：pip install -e .会装一堆依赖，其中torch的版本取决于你的CUDA。如果你有NVIDIA显卡，建议先单独装好对应CUDA版本的torch，再装LeRobot，否则pip会自动拉一个CPU版本的torch，训练的时候慢到怀疑人生。

我用的RTX 3060，CUDA 11.8，torch安装命令：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

装完验证一下：

import torch print(torch.cuda.is_available())

返回True才算对。

3.3 相机配置与标定

SO-ARM100的数据采集通常需要至少一个相机，一般是腕部相机加一个全局相机。我用的是两个USB相机，一个固定在机械臂末端，一个放在侧面拍全局。

相机在Linux下走V4L2，先确认设备：

ls /dev/video*

然后测试帧率：

v4l2-ctl --device=/dev/video0 --list-formats-ext

有些相机默认输出MJPG格式，OpenCV读取的时候需要指定：

cap = cv2.VideoCapture(0, cv2.CAP_V4L2) cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc('M','J','P','G'))

不指定的话，OpenCV可能会用YUYV格式，帧率上不去，采集的时候掉帧严重。

提示：两个相机同时采集的时候，USB带宽可能不够。建议把相机插在不同的USB控制器上，或者降低分辨率到640x480。我一开始用1280x720，两个相机一起跑就卡顿，降到640x480后流畅了。

4. 数据采集：质量决定模型上限

4.1 遥操作方案选择

LeRobot支持几种遥操作方式，我用的是主从臂方案，就是再拿一台SO-ARM100作为主臂，手动拖动主臂，从臂跟随。这种方式采集的数据最自然，但需要两台机械臂。

如果没有主臂，也可以用键盘或者手柄遥操作，但采集效率低，轨迹也不够平滑。我试过键盘控制，采了50条数据，训练出来的模型抖动很明显，后来换主从臂才解决。

主从臂的配置在LeRobot里有现成的脚本：

python -m lerobot.scripts.teleoperate \ --robot.type=so100 \ --robot.port=/dev/ttyACM0 \ --teleop.type=so100_leader \ --teleop.port=/dev/ttyACM1

主臂和从臂的串口别搞混，接反了会出问题。

4.2 采集流程与注意事项

采集的时候有几个细节直接影响数据质量：

第一，每个任务至少采50条轨迹，少了模型学不会，多了训练时间线性增长。我一般采50到100条，看任务复杂度。

第二，采集前先复位到同一个初始位置。每次采集的起始位姿不一致，模型会学到很多无关的变异，训练loss降不下去。

第三，动作要平滑，不要突然加速或者急停。ACT模型对轨迹的连续性比较敏感，抖动大的数据训练出来的策略也会抖。

第四，相机画面里要包含任务相关的所有物体，但背景尽量干净。背景太乱，模型容易过拟合到背景纹理上。

采集脚本：

python -m lerobot.scripts.record \ --robot.type=so100 \ --robot.port=/dev/ttyACM0 \ --robot.cameras="{ front: {type: opencv, index: 0, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index: 1, width: 640, height: 480, fps: 30}}" \ --dataset.repo_id=your_name/so100_task \ --dataset.num_episodes=50 \ --dataset.episode_time_s=30

episode_time_s是每条轨迹的时长，根据任务调整。抓取放置类任务一般20到30秒够用。

4.3 数据格式与回放验证

LeRobot的数据集格式是HuggingFace Datasets，底层是Parquet加视频。采集完可以用回放脚本检查：

python -m lerobot.scripts.replay \ --dataset.repo_id=your_name/so100_task \ --robot.type=so100 \ --robot.port=/dev/ttyACM0

回放的时候重点看动作是否连贯，相机画面和动作是否对齐。如果发现动作和画面对不上，可能是采集的时候时间戳没同步好，需要重新采。

注意：数据集路径里不要有中文和空格，HuggingFace Datasets对路径比较敏感，中文路径会报编码错误。

5. ACT模型训练与调参实战

5.1 ACT模型结构简析

ACT的全称是Action Chunking Transformer，核心思想是一次预测未来一段时间的动作序列，而不是单步预测。这样做的好处是减少累积误差，动作更平滑。

模型结构上，输入是当前观测（图像加关节位置），输出是未来K步的动作。K就是chunk size，默认是100。Transformer的encoder处理图像特征，decoder生成动作序列。训练的时候用L1损失加KL散度，KL项用来约束隐变量的分布。

为什么用Transformer而不是LSTM？因为Transformer对长序列的建模能力更强，而且可以并行训练，速度快。ACT在多个模仿学习基准上都超过了之前的方案，这也是LeRobot选它作为默认模型的原因。

5.2 训练配置与参数选择

训练脚本：

python -m lerobot.scripts.train \ --dataset.repo_id=your_name/so100_task \ --policy.type=act \ --policy.chunk_size=100 \ --policy.n_action_steps=100 \ --training.batch_size=8 \ --training.num_epochs=2000 \ --training.lr=1e-5

几个关键参数：

chunk_size是预测的动作序列长度，100是默认值。任务周期长的可以加到200，但显存占用会增加。

n_action_steps是实际执行的动作步数，一般等于chunk_size。如果设小了，模型预测了100步但只执行10步就重新预测，会浪费计算。

batch_size取决于显存。8GB显存用8，12GB用16，24GB可以上32。batch size太小训练不稳定，太大收敛慢。

lr学习率，1e-5是安全值。我试过3e-5，loss震荡得厉害，后来降到1e-5才稳。

num_epochs一般2000到5000。看loss曲线，如果2000轮后loss还在降，可以继续训。

5.3 调参经验与loss曲线解读

训练过程中重点看两个指标：L1 loss和KL loss。L1 loss反映动作预测的准确度，KL loss反映隐变量的分布是否正常。

正常情况下，L1 loss在前500轮快速下降，然后缓慢收敛。如果L1 loss降到某个值就不动了，可能是模型容量不够，可以加宽Transformer的hidden dim，或者增加层数。

KL loss如果一直很高，说明隐变量分布偏离先验太远，可以调大KL的权重系数。LeRobot里对应的参数是policy.kl_weight，默认是10，可以试到20。

如果训练loss很低但实际执行效果差，大概率是过拟合。解决办法是增加数据量，或者加数据增强。LeRobot支持图像随机裁剪和颜色抖动，在配置里打开就行。

提示：训练的时候用TensorBoard看曲线，命令是tensorboard --logdir=outputs。不要只看最终loss，要看曲线的形状，震荡下降和单调下降对应的模型质量差别很大。

5.4 模型评估与部署

训练完的模型存在outputs/train/下面，评估脚本：

python -m lerobot.scripts.eval \ --policy.path=outputs/train/act_so100/checkpoints/last/pretrained_model \ --robot.type=so100 \ --robot.port=/dev/ttyACM0 \ --eval.n_episodes=10

评估的时候看成功率，10次里成功几次。如果成功率低于50%，先别急着调模型，检查一下评估环境和训练环境是否一致。相机位置、光照、物体摆放，任何一项变了都会影响效果。

部署的时候可以把模型导出成ONNX，推理速度会快一些。但SO-ARM100本身对实时性要求不高，直接用PyTorch推理也够用。

6. 常见问题与排查速查

6.1 环境类问题

6.2 训练类问题

6.3 独家避坑技巧

第一个技巧：采集数据前，先用回放脚本跑一遍空轨迹，确认机械臂能完整执行任务空间内的所有动作。有些关节限位没设好，采集的时候会撞到限位，数据就废了。

第二个技巧：训练的时候先跑一个小数据集，比如10条轨迹，训500轮，看看流程能不能跑通。跑通了再上全量数据，避免浪费时间。

第三个技巧：模型效果不好的时候，先别调模型参数，先检查数据。我遇到的大部分问题都是数据问题，不是模型问题。数据质量上去了，默认参数就能出不错的效果。

第四个技巧：机械臂的零位会漂移，尤其是跑了一段时间后。每次采集和评估前都重新校准一次零位，能显著提升一致性。

7. 一些个人体会

这套流程跑下来，最大的感受是：模仿学习的门槛不在模型，在数据。ACT模型本身很成熟，LeRobot的封装也做得不错，真正花时间的是硬件调试和数据采集。我前前后后采了大概300条轨迹，废掉的有一半，要么是轨迹不平滑，要么是相机没对准，要么是零位漂了。

另一个体会是，调参不要贪多。一次只改一个参数，改完看效果，有效再继续。我一开始同时改学习率和batch size，结果loss曲线乱七八糟，根本不知道是哪个参数的问题。后来改成单变量调参，效率反而高了。

最后分享一个小技巧：如果你只有一台机械臂，没有主臂，可以用手机录屏的方式做遥操作。把手机固定在支架上，通过蓝牙手柄控制，虽然不如主从臂自然，但成本低很多。采集的时候慢一点，动作平滑一点，效果也能接受。

这个方向后续还可以扩展，比如加力反馈、加多任务数据集、试试Diffusion Policy。SO-ARM100的硬件平台够开放，想怎么折腾都行。