我最近在给实验室做 robomimic 教学型复现工程卡在 Lift-PH 这个数据集上。很多人第一次跑 State BC以为把命令一敲、等训练完就结束了实际上坑最多的地方不在训练而在启动前那十分钟的配置准备与审计。Phase 3 要做的就是把官方 State BC 配置从“能打开”变成“确定能跑出可复现结果”。这篇文章面向的是正在按阶段复现 robomimic 的同学尤其是刚接触机器人模仿学习、对数据集和配置结构还不熟的人。我会按自己实际操作时的顺序把准备官方 State BC 配置、审计环境与数据、试跑验证这一整套流程讲清楚。每一步为什么要做、会出现什么现象、怎么排查我都会提到。如果你已经跑通了前面两个阶段这篇可以直接照做。1. 为什么把“配置准备与审计”单独做成一个阶段1.1 教学型复现的路线图里Phase 3 承担什么角色教学型复现和一般的调参跑实验不太一样。正常做研究时你可能会直接改 config 然后跑 50 epoch失败了再改。但教学型复现的目标是让一个完全没接触过 robomimic 的人能按阶段从零走到一个可信的结果。它需要把流程切碎让每个阶段都承担一个明确任务Phase 1安装 robomimic 仓库、创建虚拟环境、解决依赖Phase 2下载并理解 Lift-PH 数据集搞清楚数据形态Phase 3准备官方 State BC 配置并对环境、数据和配置做一致性审计Phase 4启动训练、保存基线模型、可视化结果。Phase 3 夹在数据准备和正式训练之间看起来只是“写一个 json 配置文件”的事情但它实际上是整个复现项目里风险最高的关卡。因为后续所有训练结果都建立在这个配置上如果配置里某个路径写错、某个 observation key 对不上、某个 filter 条件把数据过滤成空集后面跑出来的要么是报错要么是一个看起来正常但完全不可信的模型。单独做一个阶段就是要把这类问题在训练开始前全部暴露出来。1.2 配置审计到底在审什么审计这个词听着重其实核心就是回答三类问题环境对不对Python 版本、torch 版本、CUDA 是否可用、robomimic 是否能正常 import数据全不全Lift-PH 数据集文件是否存在、HDF5 内部结构是否完整、轨迹数量和时间步是否符合预期配置匹配不匹配官方 bc.json 里写的路径、obs modality、batch size 等参数是否和当前数据集、当前设备条件一致。我见过很多同学直接跑官方命令结果报错 FileNotFoundError或者训练完才发现模型根本没有看到图像/状态特征只是因为 config 和数据集版本不一致导致数据被静默过滤。审计阶段的作用就是用最少的时间把这三类问题全查一遍。2. 先把家底盘清楚环境、仓库与数据集资产清单2.1 虚拟环境与依赖版本核对进入 Phase 3 时假设你已经按 robomimic 的官方 README 装好了环境。但“装过”不表示“现在还能用”环境是动态的你可能中途升级过某个包也可能多装了一个会产生依赖冲突的库。我启动前会先跑一组快速检查conda activate robomimic python -c import robomimic; print(robomimic.__version__) python -c import torch; print(torch.__version__); print(torch.cuda.is_available()) python -c import h5py; print(h5py.__version__)这里有一个容易忽略的点robomimic.__version__可能不存在。robomimic 有些版本没有在__init__.py里定义版本号如果报 AttributeError不要慌直接看 pip 包信息或者 git commit 号即可pip show robomimic git -C /path/to/robomimic log --oneline -1为什么这一步值得单独拎出来因为 robomimic 的配置文件结构在不同 commit 之间有过调整有的新版本把experiment.name改成必填项有的旧版本还在用train.data_dir而新版本已经要求dataset_path。确定 commit 号后面解析配置、对齐官方示例时才有参照物。2.2 数据集目录结构与 Lift-PH 文件确认robomimic 官方的数据集下载脚本会把数据放到统一的目录结构里。Lift-PH 对应的低维状态数据路径通常是datasets/ └── lift/ └── ph/ └── low_dim.hdf5建议用绝对路径管理不要用相对路径。因为run_training.py里如果只写了../datasets它相对的是当前工作目录而很多人喜欢在仓库根目录下敲命令这时相对路径的基准目录就很容易搞混。我在实际部署时使用下面的检查方式ls -lh /workspace/datasets/lift/ph/low_dim.hdf5正常文件大小在几十 MB 量级。如果文件只有几 KB基本可以怀疑是下载失败或者git-lfs没有正确拉取内容。robomimic 某些数据集走的是download_datasets.py脚本下载中断也可能产生这种问题建议重新下载并确认文件哈希。同时检查一下high_dim.hdf5是否存在。Phase 3 虽然用的是低维状态数据但后续如果你想扩展成 Image BC 或者看演示视频高度数据还会用到。都放在那里不影响 Phase 3但能省去后面临时补下载的麻烦。2.3 用一段小脚本把数据集元信息读出来路径和大小没问题还不够。HDF5 是个容器真正内容在里面。我建议花 30 秒写一个小脚本把数据集的关键元信息打印出来import h5py demo_path /workspace/datasets/lift/ph/low_dim.hdf5 with h5py.File(demo_path, r) as f: print(root attrs:, dict(f.attrs)) print(top-level keys:, list(f.keys())) data_grp f[data] print(data attrs:, dict(data_grp.attrs)) demo_keys list(data_grp.keys()) print(num demos inside data:, len(demo_keys)) first_demo demo_keys[0] first_grp data_grp[first_demo] print(first demo keys:, list(first_grp.keys())) print(obs group keys:, list(first_grp[obs].keys())) print(actions shape:, first_grp[actions].shape) print(rewards shape:, first_grp[rewards].shape)在我的实机上打印结果类似这样data.attrs[total_timesteps]在几千到一万多之间data.attrs[num_traj]对应 Lift-PH 官方数据集的轨迹数obs下能看到object、robot0_eef_pos、robot0_eef_quat、robot0_gripper_qpos、robot0_gripper_qvel等低维 key。这段输出非常关键。因为 State BC 配置里的observation.modalities会和这里的 obs key 逐项匹配。如果数据集里根本没有某个 obs key而配置里写了它robomimic 可能会在运行时才报错如果配置里漏了某个 key训练出的模型会缺失一部分状态信息成功率会明显下降。提前打印出来相当于给后续配置审计做了一次“字典对齐”。3. 官方 State BC 配置文件逐段拆解3.1 experiment / train / algo 三段式结构官方提供的基线配置统一放在robomimic/scripts/configs/下面State BC 对应的就是bc.json。打开这个文件第一感觉是字段很多但其实核心就是三段实验信息、训练参数、算法参数。experiment段负责定义实验的名称、输出目录、数据集路径和运行设备。它决定了“本次实验去哪里读数据、往哪里写结果”。训练参数段train则控制训练流程随机种子、训练轮数、batch size、日志打印频率、Checkpoint 保存策略、数据加载线程数等。算法参数段algo才是 State BC 本身的定义策略网络结构、优化器、损失函数、是否使用 RNN 等。理解三段式结构对审计的意义在于当你需要排查一个问题时能快速定位到它是属于路径问题、训练流程问题还是网络结构问题而不是在 json 里瞎翻。官方注释里也写得很清楚建议花十分钟从头到尾读一遍很多报错就是读注释读出来的。3.2 observation.modalities为什么是 State 方案的核心State BC英文是 State-Based Behavior Cloning核心就是只使用低维状态向量不使用图像。在配置里体现为observation: { modalities: { obs: { low_dim: [ object, robot0_eef_pos, robot0_eef_quat, robot0_gripper_qpos, robot0_gripper_qvel ], image: [] } } }这个字段决定了模型从观测中读取哪些信息。low_dim列出来的 key 要和 HDF5 里obs组下的低维 key 一一对应image数组为空则表示不加载任何图像。很多第一次接触的人会觉得 State BC 和 Image BC 的区别只是“图像字段有没有值”。实际不止如此。State BC 的输入是拼接后的低维向量不需要经过图像编码器所以网络结构可以是简单的 MLPImage BC 则通常需要 CNN 编码器训练更慢、显存需求更大、对数据增强也更敏感。对于教学型复现来说选择 State BC 是合理的它更容易跑通也能更快验证数据管线、训练代码和评估流程是否正常。3.3 训练尺度epoch、batch、learning rate 怎么来的官方bc.json里默认的训练尺度是按“Lift-PH 这种规模的单任务数据集”设计的。比如训练轮数、batch size、学习率这些数值并不是拍脑袋定的它们参考了 robomimic 论文发布时的实验设置。这些参数在复现阶段不建议一上来就大改。原因很简单官方配置是经过验证的基准配置改参后如果结果变差你很难判断是改动本身造成的还是数据集/环境的问题。教学型复现的第一目标是把官方基线复现出来得到一个可信的 baseline然后再谈调优。如果机器显卡显存不够可以优先考虑减小 batch size但也要同时考虑是否需要相应调整学习率如果时间紧张可以先把 epoch 减少到 1/5 做冒烟测试不要直接砍一半就正式出结果。3.4 版本差异提醒不同分支的字段有变化robomimic 仓库在过去一段时间内更新比较频繁bc.json的字段在不同 commit 之间有差异。举个我遇到的例子旧版本里train段会有data_dir和dataset_path两个字段并用新版本可能只保留dataset_path且新增了部分用于数据集筛选和轨迹处理的字段。所以在按照网上教程配置时一定要先确认你 clone 的仓库版本。最直接的方式是打开仓库根目录的README.md里面通常标注了推荐的使用方式然后对比robomimic/scripts/configs/bc.json的注释内容和当前仓库robomimic/core里各模块的源码字段。如果直接用不是当前版本的旧配置文件很容易遇到字段不匹配或行为不一致的问题。我的建议是以自己 clone 到的官方bc.json为基准不要从网上随便复制一份。4. 配置与数据的一致性审计逐步操作4.1 路径审计五处容易写错的地方配置准备里最容易翻车的不是算法参数而是路径。我总结了五处容易写错的地方dataset_path写成了相对路径而当前工作目录不是仓库根目录output_dir指向了一个不存在的目录程序启动时报 OSError数据集文件名写错把low_dim.hdf5写成lowdim.hdf5路径里用了~而没有做 shell 展开python 不会自动把它替换成主目录在 Windows 上用了反斜杠\拼接路径导致转义符号问题。审计路径时我的做法是在启动训练前先手工用python验证一下最重要的两个路径import os from robomimic.utils.file_utils import ensure_dir dataset_path /workspace/datasets/lift/ph/low_dim.hdf5 print(dataset exists:, os.path.exists(dataset_path)) output_dir /workspace/results/lift_ph_state_bc ensure_dir(output_dir) print(output dir ready:, os.path.exists(output_dir))这样不会等到训练脚本跑到一半才炸出来。4.2 obs key 对照审计路径对了下一步就进入观察空间的一致性审计。这一步是 State BC 配置准备的核心因为模型能否学到有效的策略取决于它拿到的状态特征是否完整且有序。我把观测空间的审计拆成三步从 HDF5 里取出obs组的低维 key 列表从bc.json的observation.modalities里取出配置的低维 key 列表对比这两个列表确认配置里的 key 都真实存在于数据中并且没有遗漏关键状态。import h5py, json demo_path /workspace/datasets/lift/ph/low_dim.hdf5 config_path /workspace/robomimic/scripts/configs/bc.json with h5py.File(demo_path, r) as f: demo_key list(f[data].keys())[0] data_obs_keys list(f[data/{}/obs.format(demo_key)].keys()) data_lowdim_keys sorted([ k for k in data_obs_keys if not k.lower().endswith(image) ]) with open(config_path, r) as f: cfg json.load(f) config_lowdim_keys sorted(cfg[observation][modalities][obs][low_dim]) print(data lowdim keys: , data_lowdim_keys) print(config lowdim keys:, config_lowdim_keys) print(missing in config:, set(data_lowdim_keys) - set(config_lowdim_keys)) print(not found in data:, set(config_lowdim_keys) - set(data_lowdim_keys))注意这里我用了一个简单规则凡是 key 名字里带image的都归为图像模态。实际数据集里可能还有agentview_image、robot0_eye_in_hand_image这类 key而低维多维特征一般是object、robot0_eef_pos这些不带 image 的字段。通过这个小脚本基本能一眼看出问题。4.3 数据集切分与 filter_by_attribute官方配置里还包含一个容易被忽略的字段dataset.filter_by_attribute。它的作用是按轨迹属性过滤数据集常见用法是只保留成功轨迹。Lift-PH 这个数据集里的轨迹质量整体较高因为它是熟练操作者Proficient Human的演示。但如果你用的数据集是混合质量或者包含失败轨迹就需要考虑是否设置过滤条件。robomimic 数据集在 HDF5 的轨迹组 attr 里可能保存了属性信息例如success、edited等。如果filter_by_attribute设置为null表示不过滤使用全部轨迹如果设置成某个属性名训练时会只保留该属性为 True 的轨迹。我在教学型复现里一般先保持null这样能让第一次跑的人看到完全按照官方配置的结果。后续如果要演示“数据质量对模仿学习的影响”可以再对比过滤前后的结果这个作为扩展实验更合适。4.4 Dry-run 试跑设计配置和数据的静态检查都通过后不要直接跑完整训练。先设计一个轻量的试跑也就是“冒烟测试”。具体做法是在命令行覆盖关键超参把训练规模缩小python run_training.py \ --config /workspace/robomimic/scripts/configs/bc.json \ --dataset /workspace/datasets/lift/ph/low_dim.hdf5 \ --output_dir /workspace/results/lift_ph_state_bc_smoke \ --experiment.name lift_ph_state_bc_smoke \ --train.num_epochs 1这样只会跑 1 个 epoch。如果数据集规模不大整个试跑只要几分钟。试跑不是真的为了出结果而是为了验证整个管线能通数据能加载、模型能构建、优化器能更新、日志能写入、Checkpoint 能保存。这一步能筛掉九成以上的运行时问题。跑完后检查一下输出目录应该能看到日志文件、模型 checkpoint 和 tensorboard 文件。如果只出现了日志但没有任何 checkpoint要检查是不是 checkpoint 保存频率设得太高或者本地磁盘空间不足。5. 试跑与结果合理性检查5.1 一个 epoch 的冒烟测试要观察什么冒烟测试跑完后我会先打开输出目录里的训练日志关注几个关键指标数据加载速度是否正常首个 batch 的 loss 是否在“不奇怪”的范围训练 epoch 是否在预期时间内完成checkpoint 是否顺利保存。这些指标不需要很精确但能反映管线是否健康。比如如果首步 loss 直接是 NaN那就别继续了优先去看学习率是不是设得太大或者 obs 里是不是混入了缺失值如果一个 epoch 跑了几个小时那可能数据加载卡死要去检查num_data_workers是否设置过高导致 worker 阻塞。5.2 第一个 checkpoint 前后的 Loss 曲线长什么样State BC 做的是监督式行为克隆损失函数衡量的是模型预测动作和演示动作之间的差异。正常情况下第 1 个 epoch 的 loss 会明显下降后面下降速度放缓进入一个缓慢下降平台。在我的经验里Lift-PH 这个任务在 State BC 下loss 的绝对值不会特别小因为动作空间有多个维度而且夹爪动作是离散的。比绝对值更重要的是变化趋势。如果第一个 epoch 结束后 loss 纹丝不动说明模型可能没有有效学习常见原因是优化器参数设置错误或者输入输出张量拼接有问题。如果 loss 下降到某个点之后开始反弹常见原因则可能是学习率偏大或者 batch size 太小导致梯度噪声过大。冒烟测试结束后因为只跑了一个 epoch看不到完整的 loss 形态所以我会在此基础上补做一个短训实验比如把 epoch 设到 10 左右跑一次看看趋势再决定是否进入正式长训。5.3 用官方基准预期值兜底对照robomimic 论文和官方仓库都公布过基线结果。Lift 任务在 State BC 下通常能取得很高的任务成功率因为任务本身相对简单且 PH 演示质量高。如果你跑完短训后想马上评估一轮robomimic 提供了评估脚本或run_training.py的--evaluate相关选项。我一般在得到第一个完整 checkpoint 后先用官方评估流程跑一次 rollout把成功率记录下来。预期成功率会偏低因为训练并没有充分进行。但你不应该看到成功率等于 0 且很多 rollout 卡在同一个位置如果出现这种情况很可能是动作空间归一化出错或者是策略网络输出和机器人控制器不匹配。5.4 常见失败现象排查表试跑阶段会暴露各种问题我整理了一个排查表方便按图索骥现象可能原因检查方式FileNotFoundError: dataset_path路径写错或~未展开os.path.exists验证AttrError: no obs key配置里写了数据集中不存在的 key用 h5py 打印 obs group 的 key训练 loss 为 NaN学习率过高、输入含无穷值检查 obs 数值范围降低学习率CUDA out of memorybatch size 或模型过大减小 batch size 或换小模型训练速度极慢num_data_workers 太高或太低调整 worker 数观察 CPU 占用checkpoint 文件没生成保存频率设置为 0 或输出路径无权限检查 train.log_every_n_epochs评估成功率一直为 0动作空间/奖励函数理解有误先手工回放一条演示轨迹核对这个表只是起点真正遇到问题时要学会看完整堆栈robomimic 的报错信息通常会把出错模块和具体字段都打出来顺着源码追一遍往往比搜教程更快。6. 跑通之后的下一步记录基线、留好审计痕迹6.1 实验命名与输出目录规范正式训练开始前建议花两分钟想清楚实验命名。一个规范的名字应该让人一眼看出用了什么算法、什么数据、什么模态、什么配置。比如lift_ph_state_bc_v1输出目录可以是results/lift_ph_state_bc_v1/然后在experiment.name里保持同一个名字。这样后续做多组对比时不会因为目录名相似而混淆。教学型复现尤其需要这个习惯因为学习者要靠这些痕迹理解每一个实验对应什么用途。6.2 怎么把这一次配置固化成一个 session 报告我在 Phase 3 结束时会把这次审计结果整理成一个简单的 markdown 文件内容包括仓库 commit 号和 pip 包版本数据集路径、轨迹数、总时间步bc.json的关键字段快照冒烟测试的日志摘要试跑是否通过以及是否遇到过问题。这个报告不需要很长三十分钟内可以写完。但它对后续阶段非常有用特别是当你跑完 Phase 4 发现结果不理想回过头来排查时这份报告能帮你快速确认“配置审计阶段到底是怎么准备的”。6.3 Phase 4 可以怎么做配置审计跑通后你已经拿到了一个干净的训练管线。下一步建议直接按照官方配置跑一份完整的 State BC 基线把训练日志、checkpoint、成功率评估结果都保存下来。然后再考虑扩展改动比如改成 Image BC、换用cql.json、或者在数据集上叠加filter_by_attribute。按照我的习惯Phase 3 到 Phase 4 之间隔一天最好。隔这一天的意义不是拖时间而是让自己从“怎么让程序跑通”的思维切换到“怎么解释结果”的思维。训练脚本跑起来以后你会花更多时间在结果分析上而配置审计阶段的数据和判断正好是分析的基准。