企业官网建设流程全解析

写这篇文章的时候，刚好是lerobot系列教程的第六篇。前五篇已经搞定了环境搭建、数据采集、数据集格式整理这些准备工作，都是些听起来琐碎但实际绕不过去的活。这篇把所有准备工作的终点打通：把采集到的轨迹数据真正喂给模型去训练，再把训练好的模型部署回真实环境里做测试。目标很明确，就是让你跟着操作记录走一遍，能顺利拿到一个可以动起来的策略模型。

先交代一下这篇内容适合谁看。如果你已经按lerobot官方流程跑通过数据采集，手上有一批自己的演示数据；或者你只是想用官方推的pusht、aloha这类公开数据集，快速体验一下“从零训练一个机器人操作策略”的完整闭环，那这篇文章就是给你准备的。我这边全程用的是真实环境采集的数据，不是仿真数据，训练和测试都踩过不少坑，所以实操层面的东西会写得比较细。

1. 先把训练思路理清楚：数据、策略、硬件三件事

开始跑命令之前，我建议你先花十几分钟把这三件事想明白，比直接复制粘贴训练命令重要得多。lerobot这个框架的定位其实很清晰：它把“从数据到策略”这一条流水线给你搭好了，但每一个环节里面的选择，仍然需要你自己根据实际情况做决策。

1.1 数据格式更新：从hdf5到mcap，到底改了什么

先聊数据格式。你可能在lerobot的issue区或者社区里见过这两种后缀名：hdf5和mcap。早期版本的lerobot统一用hdf5存储数据集，一个文件里塞了全部的图像、动作状态和元信息。hdf5格式本身没什么不好，数据读取、切片都很方便，但它有个硬伤：不方便做流式读取。如果你采集的数据量一大，比如我这边用两个摄像头各采了2万多个步长，光是把hdf5文件完整加载进内存就要吃掉不少资源，而且每次训练都要重复这个过程，很浪费。

所以lerobot在v0.3.0版本之后，数据集的官方推荐格式改成了mcap。这里面有个很关键的原因：mcap是机器人行业里为“流式数据”设计的容器格式，它天然支持按topic分通道存储，可以把摄像头图像、关节角度、时间戳这些数据分开写入，读取的时候只需要按需订阅对应通道，并不需要把整个文件都读进内存。实际体验下来，训练时数据加载速度明显比hdf5版本顺滑，尤其是在长时间采集、多摄像头场景下，差距非常明显。

我是直接用的新版本lerobot，数据采集时就已经是mcap格式了，所以训练前不需要做额外转换。但如果你跟我情况相反，手上是hdf5旧数据集，建议你先跑一下lerobot仓库里自带的转换脚本，把数据升级成新版本格式再继续。需要提醒一句：转换完之后一定要重新检查一遍数据集里的图像分辨率和状态维度，别转换完闷头训练，跑到一半发现数据维度对不上。

1.2 策略模型怎么选：ACT、Diffusion Policy和TDMPC的差异

lerobot框架里内置了多种策略模型，同一个数据集，你可以用ACT训练，也可以用Diffusion Policy训练，甚至在部分版本里还能跑TDMPC。不少新手上来就挑最复杂的模型，这是误区。我强烈建议你先根据自己的任务类型来选，而不是根据模型热度来选。

先说说ACT。ACT（Action Chunking with Transformers）的核心思想是让模型一次性预测未来一段时间内的动作序列，而不是一个时间点一个时间点地预测。这种“动作分块”的机制天然适合那些需要连续、平滑操作的任务，比如用机械臂夹东西、倒水、叠衣服。ACT在lerobot里也是文档最全、社区讨论最多的模型，遇到问题最容易搜到解决方案。

再说Diffusion Policy。这个名字听着很玄乎，本质上是把动作生成当成一个去噪过程：模型在一个随机噪声动作序列上迭代去噪，逐步收敛到目标动作。它的优势是表达能力强，能拟合非常复杂的多模态动作分布，比如同一个物体可以从不同角度去抓，它都能学到。代价就是训练和推理速度都比ACT慢，你需要评估自己硬件是否扛得住。

TDMPC这一类模型融合了模型预测控制的思想，它不仅要学策略，还要学一个世界模型来预测未来状态。听起来很厉害，但落地复杂度也高，不太适合作为第一个跑通的模型。

我这边最终选的是ACT，原因很直接：我的任务是真实机械臂的搬运动作演示，动作轨迹相对稳定，没有特别复杂的多模态需求，而且ACT的收敛速度更快，真机部署时推理延迟也更低。如果你第一次接触lerobot，想快速看到训练效果，ACT通常是最稳的选择。

1.3 显卡资源有限，训练配置如何取舍

聊一下硬件。lerobot训练并不像大语言模型那样动辄几十张卡，但也不至于一张老显卡就能轻松跑完。以我的实际经验来看，单张显存12GB以上的NVIDIA显卡是起步线。太小的显存倒也不是完全不能跑，只是要把batch size压得非常小，训练时间会拉得很长，而且容易出现显存溢出的问题。

我手头是单张RTX 4060 Ti 16GB，训练ACT模型，图像分辨率从原来的640x480做了缩放，batch size设置在32左右，显存占用已经接近上限。如果你的显存只有8GB，建议把batch size调成8到16，同时将图像分辨率进一步缩小到224x224或更低，牺牲一点精度换训练可行性。

还有一点要注意：lerobot训练默认会使用CUDA，但不同的PyTorch版本对CUDA版本有要求。我记得第一次配置环境时，因为PyTorch的CUDA版本和显卡驱动不匹配，训练脚本一开始就报“CUDA unavailable”，这个排查过程非常折磨。建议动手之前先确认一下自己GPU的CUDA compute capability和PyTorch官方要求的CUDA版本是否匹配。

2. 模型训练实操记录

思路理顺了，可以开始跑训练了。这一部分我把自己的完整操作流程和遇到的细节记录在这里，包括命令行参数怎么填、checkpoint怎么存、训练过程中应该盯哪些指标。建议你尽量照着做一遍，出问题的时候再回头看第4部分的排查列表。

2.1 启动训练之前的环境检查

别急着运行train.py，先花两分钟做一次环境体检。我每次训练前都会跑这几个检查，确认环境没问题再动手：

python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"

这一步能看到PyTorch版本、CUDA是否可用、显卡型号。如果CUDA显示False，多半是PyTorch的CUDA版本和驱动不匹配，或者安装的是CPU版PyTorch，这个必须先解决。

接下来检查lerobot装的是不是最新版本，最好同步一下。我这次用的是v0.3.x的代码库，如果你从pip直接装的话，版本号可能对不上，功能和命令行参数会有细微差别：

pip show lerobot

再确认一下数据集路径。lerobot的数据集有固定的目录结构，包括metadata、videos、episodes这些子目录。如果你是自己采的数据，建议先跑一下lerobot自带的脚本做可视化回放，确认每条episode的数据都完整，没有明显跳帧或者传感器异常。

最后检查一下数据集配置文件里的图像分辨率、状态维度跟模型配置是否一致。这一步非常关键，我的经验是很多训练中途崩溃，都是因为数据维度和模型输入维度对不上导致的。

2.2 训练命令与关键参数说明

lerobot的训练入口是一个train.py脚本，通过命令行传入各种配置参数。我把自己的训练命令简化一下，加上注释说明：

python lerobot/scripts/train.py \ --policy.type=act \ --dataset.repo_id=my_robot_dataset \ --dataset.root=./data \ --output_dir=./outputs/train/act_test \ --train.batch_size=32 \ --train.num_steps=50000 \ --train.log_freq=100 \ --train.save_freq=5000 \ --train.eval_freq=2000 \ --policy.backbone=resnet18 \ --policy.dim_model=512 \ --policy.n_heads=8 \ --policy.n_enc_layers=4 \ --policy.n_dec_layers=1 \ --policy.chunk_size=100

逐一解释一下我这些参数是怎么定的。--policy.type=act指定了用ACT模型，--dataset.repo_id是你数据集在Hugging Face上的仓库名，如果没有上传到HF，也可以用本地路径加--dataset.root来指定。这里新手最容易困惑的是repo_id和root的区别，简单说repo_id是给远程数据集用的标识，root是本地数据集所在根目录。

训练步数我设的是5万步。这个数值不是拍脑袋定的，而是根据我的数据量粗略估算的：2万步长的数据，配合batch size 32，一个epoch大约需要600多次迭代，5万步大约是80个epoch。这不是严格意义上的标准公式，但实际操作中够用了。如果你的数据量大，可以适当减少步数，数据量小就增加，避免过早过拟合。

--train.save_freq=5000表示每5000步保存一次checkpoint。这个频率不是越高越好，因为每个checkpoint都包含完整的模型权重和优化器状态，占用空间不小。我踩过一次坑：把save_freq设成1000，结果训练到一半，磁盘空间直接爆掉，所有数据作废重头再跑。建议至少留出20GB以上的硬盘余量，再开始训练。

2.3 checkpoint机制：训练中到底存了什么

训练过程中，output_dir下会不断生成checkpoint目录，例如checkpoint-005000、checkpoint-010000这种命名方式。每个checkpoint目录里通常包含这几个文件：model.safetensors是模型权重，optimizer.safetensors是优化器状态，config.json是训练配置，training_state.json记录了当前训练步数和各项指标，还有一个scaler文件用来保存混合精度缩放状态。

这些文件各有用处，其中model.safetensors是测试时必须要加载的权重文件，optimizer.safetensors则是用来恢复训练断点的。如果你想中断训练再接着跑，用--resume=true就能从最近的checkpoint继续，但如果只保留了model权重而丢了optimizer状态，恢复训练就会有问题。

我建议训练期间不要把checkpoint的保留间隔设得太密。lerobot默认只会保留最近几个checkpoint，这个设计很合理，因为早期checkpoint的模型权重基本没有使用价值。想让模型效果真实变好，关键看loss曲线的收敛情况，而不是checkpoint的数量。

2.4 怎么判断训练收敛了

训练过程中在终端里能看到实时打印的loss值，同时训练完成之后，还可以从output_dir下的日志文件里读取完整的指标变化。我比较建议直接看TensorBoard曲线，启动方式很简单：

tensorboard --logdir=./outputs/train/act_test

然后浏览器打开TensorBoard地址，重点看三个曲线：total_loss、action_loss和grad_norm。total_loss是整体损失，这个值应该随着训练步数增加稳步下降，然后趋于平缓。action_loss是动作预测的损失，这个值对最终策略质量的影响最大。grad_norm是梯度范数，如果这个值出现了异常大的波动，说明训练状态可能不稳定，需要适当调小learning rate。

还有一个细节，训练过程中保存的eval指标也很值得关注。lerobot在eval频率处会对验证集数据做一次推理评估，计算模型在未见过的数据上的动作误差。这个误差比训练集上的loss更有参考价值，因为模型有可能在训练数据上过拟合，loss很低，但实际测试一塌糊涂。

我这次训练到3万步左右，total_loss就已经趋于平稳，曲线斜率明显变缓。到5万步结束，动作误差降到相对可接受的范围。如果你训练到后期发现loss还在明显下降，不妨再多跑一段时间，不要机械地按预设步数停止。

3. 模型测试与效果评估

训练完成，challenge checkpoint已经有了，接下来就是把模型测试跑起来，看它在真实环境里到底能不能完成任务。这一步的坑比训练更多，因为训练数据是静止的，测试环境是动态的，各种意外情况都会冒出来。

3.1 离线评估与在线测试的区别

先讲清楚两个概念：离线评估和在线测试。离线评估指的是用验证集数据来做推理，看模型在相同输入条件下预测的动作和真实动作之间的误差。这个过程不涉及机械臂运动，纯粹是算法层面的评估，速度快，方便排查模型本身的问题。

在线测试则是把模型加载到真实机器人上，输入实时摄像头画面，模型输出动作指令，机械臂实际执行。这个过程中会有传感器噪声、执行延迟、物理碰撞一系列问题，离线评估的误差指标在这里只能作为参考。

我建议你两条路径都走一遍。先用离线评估快速筛掉明显有问题的checkpoint，避免频繁把有问题的模型搬到机械臂上调试。等离线误差降到合理范围，再上真机测试。

3.2 加载checkpoint做rollout测试

要加载模型测试，第一个问题是我怎么知道训练集上最好的checkpoint是哪一个。我会看训练日志里eval指标的变化，而不是盲目加载最后一个checkpoint。有时候模型在训练后期虽然loss不高，但因为过拟合，验证集误差反而会反弹。如果遇到这种情况，我建议回到验证误差最低的那个checkpoint，往往效果更好。

测试时，lerobot提供了一套评估脚本，可以直接加载训练好的checkpoint，在数据集上做评估，并且在仿真环境里做rollout测试。如果你是像我一样的真实机器人场景，那这一步会更接近部署，通常是自己写一个推理脚本，把模型加载起来，订阅相机话题，输出动作到机械臂控制器。

我自己测试时用的大致逻辑是这样：

python eval_checkpoint.py \ --checkpoint=./outputs/train/act_test/checkpoint-050000 \ --dataset.repo_id=my_robot_dataset \ --dataset.root=./data

这里的核心是确认checkpoint路径正确。如果加载报错，很大概率是config.json里的配置和当前代码版本不一致，比如backbone类型、图像尺寸、动作维度这些信息对不上。

真机测试之前，我还习惯先做一步“数据回放测试”，检查机械臂能否按数据里的动作轨迹运行。这能提前暴露执行层面的问题，比如关节限位、速度设置不合理等，避免直接加载模型时把机械臂跑出问题。

3.3 效果不好时的排查思路

如果你的模型测试效果不理想，不要急着调超参数，先按下面这个顺序排查，效率最高。

第一步检查输入数据质量。训练时用的演示数据和测试时相机画面亮度、角度是否一致。如果测试画面稍微偏暗或者摄像头位置变了，模型性能可能立刻下降，这就是典型的训练数据与测试数据分布不一致问题。与其调模型，不如采集一批更贴近真实环境的演示数据，通过数据增强处理色彩、亮度的变化，效果会更明显。

第二步看动作平滑性。如果机械臂执行动作时抖动严重，多半是动作预测噪声太大。ACT模型输出的是动作序列，如果相邻时间步的动作预测不稳定，执行起来就会抖动。可以适当调大chunk_size，让模型预测更长的动作序列，并且考虑在推理时做动作平滑，比如取前后几个预测的平均值。

第三步调整推理频率。机器人控制频率和模型推理频率不匹配，也容易导致动作不连贯。机械臂的控制频率一般是几十赫兹，但模型单次推理可能只有十几赫兹，这种频率差会在执行时放大误差。解决思路是把模型推理放到单独的线程里，动作指令通过队列传递给控制循环，保证控制频率稳定。

4. 常见问题与避坑心得

最后一部分，把我在训练和测试过程中踩过的坑集中整理一下。这些问题不亲身经历一遍很难意识到，列出来帮你省点时间。

4.1 训练中容易翻车的几个坑

第一个坑是显存溢出。训练刚开始几秒钟就报CUDA out of memory。这个问题多半是batch size或图像分辨率设置过大，可以逐步调小batch size，也可以修改数据集的图像预处理参数，把分辨率降到合适范围。

第二个坑是数据集读取速度慢。训练时每个step都要从磁盘读一批数据，如果数据加载成为瓶颈，GPU利用率会非常低，训练速度不升反降。mcap格式本身已经优化了读取性能，但如果你把数据集放在机械硬盘上，IO依然是瓶颈。建议把数据集放到SSD上，有条件的话放到内存盘里，训练速度提升非常明显。

第三个坑是精度太低。这也算是我比较常用的一种手段。在lerobot训练脚本里设置混合精度训练，能够减少显存占用，同时加快训练速度，而且大部分情况下精度损失可以忽略。实际操作里，用bf16还是fp16也很有讲究，NVIDIA Ampere架构以上的显卡用bf16更稳，遇到loss突然变成nan的概率更小。

第四个坑是torch的版本冲突。lerobot依赖的PyTorch版本如果过新或过旧，部分内置模块可能无法正常工作。我之前遇到过深度学习框架版本和某个依赖包冲突，导致模型初始化报错，折腾了半天，最后把PyTorch回退到官方建议版本解决。建议严格按照lerobot官方文档的依赖列表来安装，别自己随便升版本。

4.2 别把lerobot训练和llama factory微调搞混

这段时间社区里经常有人问，lerobot训练和llama factory这种大模型微调工具是不是可以互相替代。这里直接说明白：两者完全是两个赛道，不存在谁替代谁的问题。

llama factory是一站式大语言模型微调平台，处理的是文本、token，训练的是语言模型，目标是让模型更好地生成文本、回答问题。而lerobot是机器人策略学习框架，处理的是图像、状态、动作序列，训练的是策略模型，目标是让机器人学会执行物理动作。两者的数据格式、模型架构、训练目标完全不同，千万不要把llama factory的Lora配置套到lerobot上，也不要用lerobot的数据处理流程去做语言模型微调。

不过这两个工具倒确实有个共同点：都追求开箱即用，把复杂的训练流程封装成简单的命令行操作。这个思路对新人很友好，但也就意味着你依然需要理解背后的数据流和训练逻辑，否则遇到问题根本无从下手。

4.3 新手最容易忽略的细节

最后说几个新手最容易忽略的小细节，都是我自己用代价换来的经验。

第一，训练数据不要全用同一个场景、同一个角度采集。数据多样性直接决定了模型在新场景下的泛化能力。我一开始偷懒，采集的演示数据都是固定角度、固定光照，结果模型一换位置就失灵，重新采集加上适当的数据增强才好一些。

第二，别忽略训练过程中的梯度范数。很多新手只看loss，不关心grad_norm。实际上grad_norm异常是训练崩溃的前兆。当grad_norm突然跳到正常值的数十倍甚至上百倍时，训练很大概率马上要出nan了，建议提前中断调低学习率。

第三，真机测试前一定要做好安全措施。模型在测试初期是完全不可控的，可能出现大幅度关节动作、夹爪突然闭合这些状况。我建议设置好机械臂的关节速度上限和力矩限制，同时准备好急停开关，别让模型在无保护状态下直接运行。

第四，如果checkpoint莫名加载失败，优先检查配置文件里是否包含了当前模型结构不支持的字段。比如你训练时用了某个版本的lerobot，测试时换了另一个版本，config.json里的模型参数可能发生了变化，加载就会失败。保证训练和测试环境版本一致，这是基础原则。

根据我个人经验，lerobot从数据采集到模型训练再到真机部署，整个流程里最容易出问题的并不是训练本身，而是训练前后那一圈环境准备和数据校验工作。模型训练是一个相对线性的过程，只要数据、配置、环境都对了，加速迭代、调参看曲线，整个流程就会顺畅很多。建议第一次操作时把每一步都记录下来，尤其是checkpoint路径、数据集配置这些，测试阶段会反复用到。如果你用的是自己的机器人，平台差异较大，前期多花点时间做好数据质量校验，后面训练和测试都会省心很多。