如果你跟我一样，正在以“教学型复现”的方式重跑 robomimic 的 Lift-PH 任务，大概率你已经体会过这种感觉：环境装好了、数据集也下载完了，一切看起来风平浪静，结果到了准备 State BC 训练配置这一步，反而卡了整整两天。我这次在“阶段 3：官方 State BC 配置准备与审计”上踩的坑，说多不多，说少不少，但每一处都足够让人怀疑人生。这篇文章就把我完整的操作流程、审计思路、踩坑记录全部整理出来，给正准备跑到这一阶段的你当一份参考。
复现 robomimic 的教学项目，最难的不是算法本身，而是“中间状态”的管理。阶段 3 夹在数据准备和正式训练之间，既不产生最终结果，又不直接暴露错误，很多人草草填一个 config 就去开训练了，结果后面报错连起来，根本分不清是数据的问题、环境的问题，还是配置的问题。所以这一阶段的核心就两个字：审计。审计数据、审计环境、审计配置，把每一步都验证到“可解释”的程度，再进入下一阶段。本文会从环境核对、数据集属性检查、官方 State BC 配置逐段拆解、实操启动验证、常见问题排查五个方面，完整还原我这次阶段 3 的全部操作。
1. 为什么阶段 3 值得单独拿出来写
1.1 robomimic、Lift-PH 与 State BC 到底是什么关系
robomimic 是一个基于 MuJoCo 的模仿学习研究与基准测试框架，由斯坦福等机构的研究者维护，核心用途是让机器人通过人类演示数据学习完成任务。它提供了统一的训练接口、评测环境、数据集格式和多个基准算法，最典型的就是行为克隆（BC，Behavioral Cloning）系列。
Lift-PH 是 robomimic 官方数据集里最基础、最常被拿来入门的任务之一。Lift 要求机械臂把一个物体从桌面抓起来，PH 指的是 Proficient Human，即由熟练人类操作者采集的演示数据。相比 MH（Multiple Humans，多人混合数据）或 MG（Machine Generated，机器生成数据），PH 数据质量高、动作一致性强，作为 State BC 的基线数据集非常合适。Robomimic 官方的数据集既有 low-dim 版本（只包含机械臂关节、末端位置、物体位姿等低维状态），也有 image 版本（包含摄像头图像）。State BC 这个说法里的 State，指的就是只使用 low-dim 状态作为观测输入，不碰图像。
换句话说，Lift-PH + State BC 组合，是 robomimic 教学复现里最“轻量”但最完整的闭环：数据量适中、输入维度低、算法实现成熟、训练速度快，非常适合先跑通全流程，再逐步升级到 RNN、Transformer 或 Image BC。
1.2 “配置准备”在教学复现流程里的位置
如果把一次完整的 robomimic 教学型复现拆成阶段，大致是这样的：
- 阶段 1：环境搭建。装 Python、PyTorch、MuJoCo、robomimic 本体，能跑通示例脚本。
- 阶段 2：数据准备。下载或生成 Lift-PH 数据集，确认文件路径、格式、可用性。
- 阶段 3：配置准备与审计。确定用哪个算法、哪份数据、哪些超参，并把配置写到可复现的文件里。
- 阶段 4：正式训练与评测。启动 train.py，跑出模型，用 rollout 评估效果。
阶段 3 最容易被低估。很多初学者会觉得，配置不就是抄一个官方bc.json吗？真正操作起来才发现，官方配置里的路径要改、观测维度要对齐、训练卡要指定、日志目录要决定，甚至 PyTorch 版本和数据集版本之间还有一些隐性的不兼容，这些问题如果不在阶段 3 提前暴露，就会全部堆到阶段 4 第一次启动训练时一起爆发。
所以我在这套教学复现流程里，坚持把阶段 3 单独作为一个里程碑来管理。配置准备不是“随便写几行参数”，而是把环境、数据、算法三者之间的接口关系全部核对一遍，确保下一步训练启动时，程序只做“计算”这一件事，而不是同时兼职“排错”。
1.3 官方 State BC 配置和“自己随手改”的配置之间差多少
这次复现我刻意采用了一个原则：尽可能以官方配置为基准，不自由发挥。原因很简单，教学型复现的第一目标不是刷指标，而是构建一个可靠基线。官方提供的配置，比如 robomimic 仓库里的bc.json，是经过数据集验证的默认组合，至少在 Lift-PH 这类标准数据上，它就是“已知能跑”的配置。基于它修改，出问题时可以快速定位是自己改坏了，还是环境问题；而完全从零手写，出了 bug 连排查方向都没有。
官方配置和我第一版随手写的配置，差距主要体现在四类：一是experiment区块里的环境名、数据集路径、日志目录，这些属于必改项；二是observation区块的观测模态和维度，必须与 HDF5 文件里的真实数据对齐；三是train区块的output_dir、num_epochs、eval_freq等训练流程参数，需要结合自己的机器和实验目的调整；四是algo.bc区块里的优化器、学习率、网络结构参数，这些通常保持官方默认即可。
“审计”这个词听起来很重，落实到操作上其实就几件事：逐个字段确认含义、确认配置里的路径指向真实存在的文件、确认观测维度与数据集统计结果一致、用最短命令跑通一次完整链路。这几点做完，阶段 3 就算过关了。
2. 动手前先做环境审计
2.1 robomimic 与 Python、PyTorch 的版本匹配核对
开始碰配置之前，我先花了十几分钟把环境重新审计了一遍。别小看这一步，我见过不少人在阶段 3 折腾半天，最后发现是 torch 版本和 robomimic 不兼容，导致模型加载时各种玄学报错。
打开终端，进入你创建好的 conda 环境，执行：
python --version conda list | grep -E "robomimic|torch|numpy|h5py|mujoco"我这次本机的核心版本是这样的：
- Python：3.8
- PyTorch：1.11.0
- robomimic：0.2.0
- h5py：3.6.0
- numpy：1.21.5
robomimic 官方在 README 里给出的建议比较宽泛，但实际跑下来，我发现 Python 3.8 加 PyTorch 1.x 的组合最稳。如果你用了 Python 3.10 以上，同时 PyTorch 版本也比较新，robomimic 里某些依赖的 API 调用方式可能会变；如果 torch 版本太老，GPU 驱动和 CUDA 这边又会出问题。所以阶段 3 的第一个审计动作，就是确认版本组合在你自己的机器上是“已知组合”，而不是“感觉没问题”。
如果发现版本不对，优先创建干净的 conda 环境重装，而不是在现有环境里强行降级。robomimic 的依赖链不算复杂，但 torch 这种底层库升来降去，很容易产生一些难排查的动态库冲突。
2.2 数据集文件和属性审计
配置里的数据集路径指的是一个 HDF5 文件。robomimic 的 Lift-PH low-dim 数据下载解压后，典型的路径结构类似：
datasets/ lift/ ph/ low_dim.hdf5这个low_dim.hdf5就是 State BC 要用的训练数据。我见过很多人在这里把路径指到 image 版本的 hdf5 上，导致后面观测维度全对不上。所以阶段 3 一定要打开文件看一眼，不要只看文件名。
用一段简单的 Python 脚本审计：
import h5py path = "datasets/lift/ph/low_dim.hdf5" with h5py.File(path, "r") as f: print("顶层 keys:", list(f.keys())) print("数据集 attrs:", dict(f.attrs)) demo_keys = list(f["data"].keys()) print("演示数量:", len(demo_keys)) demo0 = f["data/demo_0"] print("单个演示内部 keys:", list(demo0.keys())) print("obs 字段:", list(demo0["obs"].keys())) if "actions" in demo0: print("actions shape:", demo0["actions"].shape) for obs_key in demo0["obs"].keys(): print("obs 字段:", obs_key, demo0["obs"][obs_key].shape)这一步会把数据集的真实结构暴露出来。以 Lift-PH low-dim 为例，你通常会看到obs下面有robot0_eef_pos、robot0_eef_quat、robot0_gripper_qpos、robot0_gripper_qvel、object这些字段。actions通常是 4 维，因为 Lift 任务需要控制末端 XYZ 三个方向加一个夹爪开合。
这里有一个很容易踩的细节：很多教学型复现项目里，数据集的 attrs 里会有num_samples，但单个 demo 的长度并不完全一致。也就是说，不能假设每个 demo 都是固定步数。robomimic 的数据loader 会自己处理长度变化，但你自己算 obs 维度时，得用单个样本的 shape 去对齐，而不是用 demo 数量。
2.3 GPU、CUDA 与并行参数的确认
State BC 在 Lift-PH 上其实不算重，CPU 也能跑，但既然要复现完整流程，我还是建议用 GPU。启动训练前，先确认 PyTorch 能正常看到 CUDA：
import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果输出False，不要急着去调 config，先检查 torch 版本和 CUDA 驱动是否匹配。常见情况是nvidia-smi显示驱动版本很高，但 PyTorch 是 CPU 版，或者 CUDA 版本不对，这时你需要重新安装对应 CUDA 版本的 PyTorch。
robomimic 的train区块里有一个device参数，通常写成cuda，它会自动选择可用 GPU。如果你的机器有多张卡，还可以在启动命令里用CUDA_VISIBLE_DEVICES=0指定用哪张，避免 OOM。我习惯在阶段 3 就把卡号固定下来，因为多卡机器上 robomimic 默认不一定选到 0 号卡，后面看 nvidia-smi 时容易找不到进程。
并行参数也要顺手看一下。robomimic 的数据加载支持num_workers，在train区块的data子项里配置。设得太高会导致 dataloader 反复报错，我一般先设 4，稳定后再考虑调大。
3. 官方 State BC 配置逐项拆解
3.1 一个 BC 配置文件的整体骨架
robomimic 的配置支持两种写法：JSON 和 Python。官方仓库里两种都有示例，教学复现我建议直接用 JSON，因为它可读性高、易于版本管理，而且 robomimic 的train.py原生支持--config传入 JSON 文件。
一个典型的官方 State BC 配置可以分成四个大块：experiment、algo、observation、train。以 robomimic 仓库中experiments/bc.json为基准，结构大致是：
{ "experiment": { "name": "bc", "group": "bc", "env": "lift", "dataset": "/path/to/datasets/lift/ph/low_dim.hdf5" }, "algo": { "bc": { "fit": {...}, "rnn": {...} } }, "observation": { "modalities": { "obs": ["robot0_eef_pos", "robot0_eef_quat", "robot0_gripper_qpos", "robot0_gripper_qvel", "object"] } }, "train": { "output_dir": "../training", "num_epochs": 50, "eval_freq": 10 } }四个大块各司其职：experiment告诉程序“在什么环境上、用哪份数据、这次实验叫什么”；algo告诉程序“用哪个算法、算法内部怎么训练”；observation告诉程序“从数据里取哪些字段作为输入”；train告诉程序“训练多少轮、模型存哪、多久评估一次”。
阶段 3 的审计，本质上就是把这四个大块逐个对着你的实际环境和数据过一遍。哪个字段对不上，后续就会在哪个环节爆炸。
3.2 State BC 的关键参数到底在控制什么
algo区块里的bc子项，是 State BC 的核心。官方配置里，最值得关注的是fit和rnn两组参数。
fit这个子项里通常包含optimizer、learning_rate、epochs之类的参数。这里要特别说明一个细节：robomimic 的行为克隆在训练时，实际上分成两层概念——外层是整个训练流程的train.num_epochs，内层是每个 epoch 内对 BC 模型做多次梯度更新的配置。很多第一次接触的人会把这两个epochs搞混。官方默认外层的train.num_epochs是 50，但里面fit.epochs往往是 1 或者更小。教学复现时，这个值保持默认就行，不要为了“多训一会儿”去乱改内层循环，很容易导致显存爆掉或者单轮时间过长。
rnn子项是给 RNN 版 BC 用的，如果你只是跑普通的 State BC，这里保持默认即可。我见过有人看到rnn就以为 BC 一定需要序列模型，实际上普通的bc.json用的是 MLP 网络，rnn参数只有在你切换到bc_rnn配置时才会生效。
optimizer部分，官方默认用的是 Adam，学习率在 1e-3 附近。这个组合在 Lift-PH 这种规模的数据上表现非常稳定，不建议一上来就换 AdamW 或者调学习率。教学型复现的目标是先拿到一条平滑的 loss 下降曲线，不是刷精度上限。
3.3 数据集统计信息回填到配置的技巧
配置审计中最重要的一步，是把第 2.2 节里看到的数据集真实维度，与observation区块里的字段列表对齐。robomimic 的 dataloader 会按照observation.modalities.obs列表去数据集的obs组里取字段，如果列表里写了一个数据集里不存在的字段名，训练启动时就会报 KeyError。
一个实用技巧是：把第 2.2 节打印出来的obs字段列表直接复制到配置里，不要手打。我自己的流程是先用脚本生成一份当前数据集字段清单，然后对比官方配置。比如官方bc.json里 Lift 的 obs 列表写的是["robot0_eef_pos", "robot0_eef_quat", "robot0_gripper_qpos", "robot0_gripper_qvel", "object"]，那我在审计时就会一行一行确认这五个字段在 HDF5 里都存在，并且它们的维度相加，就是网络输入层的维度。
还有一个容易被忽略的点：actions字段虽然不在observation里配置，但它的维度决定了动作头的输出维度。如果哪个版本的 Lift 数据 action 是 4 维，而配置里隐式地假设了 3 维，训练能跑，但 rollout 阶段机械臂会乱动。所以审计时也要把actions.shape[1]记下来。
3.4 训练流程与日志输出的准备工作
train区块是阶段 3 改动最多的部分，也是最因人而异的部分。核心字段有这些：
output_dir：模型 checkpoint 和日志的根目录，建议用一个独立的、带日期的目录。num_epochs：总训练轮数，教学复现可以先设小一点，比如 10，跑通后再改回 50。eval_freq：每隔多少轮做一次评估。如果只想验证流程，可以设成 9999，跳过评估。save_freq：每隔多少轮存一次 checkpoint，默认值通常没问题。
robomimic 在训练时会在output_dir下生成以experiment.name和启动时间为名的子目录，里面保存模型权重、训练日志、评估结果 CSV。阶段 3 就要把这个目录结构确认清楚，否则训练完你会发现模型不知道被存到了哪里。
我习惯把配置里的output_dir写成绝对路径，避免后续换终端、换目录启动时出现相对路径错乱。这一步看似小事，实际上很多“找不到模型”的报错都是相对路径导致的。
4. 逐步实操：把官方配置准备到位并审计通过
4.1 三种准备配置的方式，我推荐第一种
在我复现的过程中，准备配置文件的途径基本上有三种。
第一种，直接修改 robomimic 官方仓库里的示例配置。如果你是从源码安装的 robomimic，那么在仓库的robomimic/experiments/目录下就能找到bc.json。把它复制到你的项目目录，改成自己的路径参数，这是最稳妥、最适合教学型复现的方式。
第二种，用 robomimic 自带的config_gen.py脚本生成配置。这个脚本会按照你指定的算法和环境，生成一个基础配置模板。好处是字段自动完整，坏处是生成出来的模板比较“素”，很多字段需要你理解后再填。对于刚接触 robomimic 的人来说，反而不如直接改官方示例好上手。
第三种，从零手写 JSON。我个人不建议，除非你想通过这种方式学习配置结构。手写最大的风险是漏字段，robomimic 的配置校验机制虽然会报错，但错误信息对新手并不友好，排查成本很高。
确定方式后，我建议在项目根目录建一个configs/文件夹，把用到的配置统一放进去，比如configs/bc_lift_ph_state.json。文件名里带上任务、算法、数据模态、版本信息，后面做对比实验时，一眼就能看出这是哪份配置。
4.2 训练前的配置审计命令集
配置准备好之后，先别急着跑完整训练。我总结了一套“最小审计命令集”，在阶段 3 全部执行一遍，通过后再进入阶段 4。
第一组命令是确认环境能看到 GPU：
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"第二组命令是确认数据集文件能被正常打开，并且 obs/action 维度符合预期：
python scripts/audit_dataset.py这个脚本就是第 2.2 节里那个打印数据集结构的脚本。我把它独立成文件，方便反复审计。
第三组命令是检查配置文件本身是否合法，robomimic 在加载配置时会做字段校验，你可以先跑一下训练入口的加载逻辑，也就是用--help或者直接启动一个极短训练任务来验证：
python robomimic/scripts/train.py --config configs/bc_lift_ph_state.json --dataset /path/to/datasets/lift/ph/low_dim.hdf5注意，这里先不要改num_epochs，等验证通过再改。第一次启动时，robomimic 会打印出完整的配置摘要，包括数据集的 demo 数量、观测维度、训练设备，以及 “Using ... demos for training” 之类的提示。这段摘要就是你审计通过的证据，建议截图或者复制到实验记录里保存。
4.3 用一轮 epoch 快速验证完整训练链路
如果你不想一上来就跑 50 轮，可以在配置里临时把train.num_epochs改成 1，同时把train.eval_freq设成 1，然后启动训练。这样做的目的不是获得任何有效模型，而是验证从数据加载、模型构建、前向传播、反向传播、checkpoint 保存到日志写入的完整链路是否通畅。
我在这个快速验证阶段遇到过一个非常典型的坑：数据能加载、模型能构建，但训练一开始就报错，说某个 tensor 的维度不匹配。排查到最后，发现是配置里的 obs 字段列表顺序和数据集里实际读取顺序不一致，导致网络输入维度算错了。这类问题只有真正跑起来才会暴露，所以阶段 3 一定不能省略“跑 1 epoch”这个动作。
快速验证时，建议盯着终端输出看三样东西：loss 是否在下降、是否有Saved model之类的提示、output_dir下是否生成了 CSV 日志。三样都正常，说明链路已经通了。
验证通过后，把num_epochs改回正常值，并确认输出目录是新的、独立的，不要和快速验证时的输出混在一起。
4.4 把临时改动收敛成最终配置
快速验证阶段，你可能会在配置里做各种临时改动，比如调小 epoch、关闭评估、换输出目录。验证完成后，一定要把配置收敛回“正式版”，我把这步叫“配置复核”。
复核清单包括：
dataset指向真实存在的 low_dim.hdf5，而不是测试时的临时目录；output_dir是一个新目录，且不包含快速验证时的垃圾输出；num_epochs是正式训练值；observation.modalities.obs与数据集字段完全一致；train.device是cuda，num_workers合理。
做完全部检查后，把这份配置提交到自己的实验管理目录，最好带一个简单的 README 记录改动点。这一步看似繁琐，但当你跑到阶段 4 发现模型不收敛时，这份记录就是救命稻草。
5. 我在 Stage 3 踩过的坑与排查速查表
5.1 数据集路径和 dataloader 报错
这类报错最经典的表现是FileNotFoundError或者KeyError。前者是路径写错了，后者是 obs 字段名和数据不一致。排查思路很简单：先确认文件存在，再确认字段名。
我在实际操作中遇到过一个问题：数据集文件明明在，但 robomimic 报错说找不到。最后发现是我在配置里用了相对路径，而训练脚本是在另一个目录下启动的。从那以后，我在所有配置文件里都改成绝对路径，这个坑就再也没出现过。
5.2 版本类报错
robomimic 的版本兼容问题主要体现在 PyTorch API 变化和 MuJoCo 版本上。比如某些旧版 robomimic 调用了 torch 里后来改名或移除的接口，新版本 torch 就会直接报AttributeError。
这类问题没有银弹，最快的解决方式就是按照官方 README 推荐的版本组合建档，然后严格“复制粘贴”那个组合。我自己的建议是：如果你跑的是教学复现，不要追求最新 torch，优先选官方验证过的稳定版本。MuJoCo 的安装则要留意环境变量，尤其是在无头服务器上跑的时候，可能需要设置渲染后端相关的环境变量。这里我不展开具体变量名，因为 robomimic 版本不同，变量名也不同，建议直接看官方 install 文档对应你版本的说明。
5.3 GPU 显存和并行设置问题
Stage BC 本身显存占用不大，但如果你之前跑过 image 版本，或者系统里其他进程占着显存，就会出现CUDA out of memory。我的习惯是在启动命令前加CUDA_VISIBLE_DEVICES=0指定单卡，同时在配置里把num_workers调低，先保证训练能跑起来，再去优化加载速度。
num_workers过高时，有时会出现 dataloader 进程卡死或者反复报错。这不是算法问题，纯属并行数超过了系统限制。阶段 3 验证时，我建议num_workers设 0 或 2，跑通后再逐步调高。
5.4 配置审计不通过时的降级方案
如果你沿着上面的流程走，配置依然审计不通过，我最后的建议是：删掉你所有的“自定义”，回到官方示例配置，只改dataset和output_dir两个字段，先跑通。跑通之后，再一点点把你要改的参数加回去。这个方法虽然笨，但非常有效，能保证系统的任何一部分出错都能被及时定位。
如果你能拿到 robomimic 仓库里tests/目录下的测试脚本，也可以跑一遍来确认安装本身没问题。阶段 3 的审计，本质上是把“环境问题”“数据问题”“配置问题”这三类问题在开工前逐一排除。
我在这次阶段 3 的操作过程中，最深的体会是：robomimic 教学型复现的难点从来不是“理解算法”，而是“管理确定性”。官方配置就是你能找到的最强确定性，照着它审计你的环境与数据，每一步都验证通过后再前进，后面的训练阶段会轻松得多。最后再分享一个小技巧：在跑正式训练之前，把output_dir那个目录里已经生成的日志删干净，不然实验记录里多出一堆半途而废的 checkpoint，后面做对比分析时很容易分不清哪份模型是哪个阶段训出来的。配置审计这件事，慢就是快，磨刀不误砍柴工。
