企业官网建设流程全解析

如果你准备复现 robomimic 实验，最容易被卡住的地方往往不是某个模型定义，而是“怎么把数据跑起来”这一整条链路。robomimic 是机器人操作领域常用的模仿学习（Imitation Learning）与离线强化学习（Offline RL）实验框架，我最早接触它的时候，光是下载数据集、改配置、生成 rollout 视频这三个环节就折腾了很久。这篇文章直接把完整流程串一遍：从环境搭建、数据下载、配置文件理解，到模型训练、视频生成，再到常见问题排错，争取你照着走一遍就能跑通。

这套流程适合两类人：一类是刚接触机器人操作方向、想做 baseline 对比的在校同学；另一类是在工业场景里想验证自己的数据能不能训出可用策略的工程师。不管你是用 GPU 服务器还是只有一台普通电脑，只要能把数据下载下来、训练脚本能启动，后面的事情基本都是水到渠成。

1. 复现 robomimic 之前，先搞清楚这四件事

1.1 robomimic 是什么、能做什么

robomimic 不是一个单一算法包，而是一整套“机器人从示范中学习”的实验框架。它自带多个仿真任务，比如 lift、can、square、tool_hang、transport，每个任务都有由真人遥操作采集的专家示范数据。框架里统一封装了数据接口、训练接口、评估接口和可视化接口，所以你可以非常方便地对比不同算法在同一个数据集上的表现。

这套框架覆盖的算法类型也比较全。行为克隆方向有最基础的 BC、带时序建模的 BC-RNN、BC-Transformer；离线强化学习方向有 CQL、TD3-BC、IQL 等。对于很多论文来说，robomimic 几乎成了一个默认的 benchmark 环境，大家汇报结果时经常直接报这几个任务上的成功率。

1.2 一条完整的复现链路长什么样

如果你跟我一样喜欢先把全貌看清楚再动手，那可以把全部流程拆成下面几步：

1. 搭建 Python 环境，安装 robomimic 和配套的仿真依赖。
2. 下载官方数据集，确认 HDF5 文件结构。
3. 选择算法对应的配置文件，做必要的参数修改。
4. 启动训练，观察 loss、验证指标和 rollout 成功率。
5. 用训练好的 checkpoint 做评估，生成 rollout 视频。
6. 根据视频判断策略行为是否合理，再决定调参方向。

后面所有内容都是按这条线展开的。你会发现，真正影响实验结果的往往不是训练那一行命令，而是前面的数据版本和配置细节。

1.3 硬件和软件环境怎么选

硬件方面，复现 low_dim 数据集上的 BC 实验其实不需要太强的显卡。我一开始在只有 CPU 的机器上也跑通过 lift 任务，只是速度慢一些。但如果要跑 image 数据集，或者用 CQL、IQL 这类离线强化学习算法，最好准备一张显存 8GB 以上的 NVIDIA 显卡，否则 Batch Size 和图像输入尺寸都受限。

软件环境上，官方一直以来比较稳的是 Python 3.8。你可以用 conda 建一个干净的虚拟环境，避免和系统自带 Python 或其他项目相互污染。操作系统方面，Ubuntu 20.04、22.04 都是常见选择；Windows 下也能装，但建议优先用 WSL2 或直接在一台 Linux 服务器上操作，遇到渲染相关的问题会更少。

1.4 版本锁定是复现的第一原则

robomimic 迭代速度不算慢，配置文件格式、脚本参数名、数据集文件名都可能在不同版本里发生变化。我见过很多“照着某个老教程敲代码，结果报错”的情况，原因基本都是版本不匹配。所以动手之前，建议先确定自己用的 commit 或 release 版本，并把环境里的 robomimic、robosuite、torch 版本都记录下来。

一个比较稳妥的做法是：先把官方仓库 clone 到本地，进入目录后看一下git log，再基于这个版本的 README 来装依赖。不要随意pip install robomimic之后又从 GitHub 拉最新代码混着用。

2. 环境搭建：Conda、代码、仿真后端一次搞定

2.1 创建 Python 环境并安装基础依赖

先把 robomimic 代码拿下来。打开终端执行：

git clone https://github.com/ARISE-Initiative/robomimic.git cd robomimic

然后创建一个干净的 conda 环境：

conda create -n robomimic python=3.8 -y conda activate robomimic

接下来安装 robomimic 本体。官方仓库推荐用可编辑模式安装，这样你改代码后不用重新安装就能生效：

pip install -e .

这个命令会把 h5py、numpy、imageio、tqdm 等基础依赖一起装上，但不一定会自动装好合适版本的 PyTorch。建议根据你的 CUDA 版本单独安装 PyTorch，例如：

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

没有 GPU 的话就去 PyTorch 官网选 CPU 版本。这一步建议先做，避免后面跑训练时才发现 torch 版本不对。

2.2 安装和验证仿真后端

robomimic 训练时并不一定需要仿真环境，但你想做 rollout 或者生成视频，就必须要能启动仿真任务。这个能力依赖 robosuite，而 robosuite 又依赖 MuJoCo。

安装方式比较简单：

pip install robosuite

不过 robomimic 对 robosuite 的版本有一定要求，如果你用的 robomimic 是较新版本，robosuite 也要选配套的 release。装好后可以这样验证：

python -c "import robomimic; print('robomimic ok')" python -c "import robosuite; print('robosuite ok')" python -c "import mujoco; print('mujoco ok')"

如果 robosuite 导入时报错，先检查 GL 相关系统库是否齐全。常见的提示是libGL.so.1找不到，这时候在 Ubuntu 上装libgl1-mesa-dev或者libgl1一般就能解决。容器环境里没有显卡渲染条件时，可以先安装xvfb，以后用xvfb-run包裹训练或评估命令。

2.3 第一次环境验证：跑一个最小示例

为了确认环境真的没问题，可以先跑一个非常小的 rollout，而不是直接上完整训练。robomimic 的 scripts 目录下提供了不少工具脚本，你可以先看下有哪些：

ls robomimic/scripts/

如果里面有run_trained_agent.py，说明这套代码是完整的。没有训练好的模型也没关系，后面我们训练完一个模型后，还要回到这个脚本生成视频。

3. 数据集下载：别再手动复制网页链接了

3.1 官方数据集的类型与目录结构

robomimic 官方把每个任务的数据分成了 low_dim 和 image 两种类型。low_dim 数据集保存的是低维状态，比如机械臂末端位置、姿态、夹爪宽度、物体位置等；image 数据集则额外保存了相机图像，通常通过多个视角拍摄。

两种数据集在训练时的感受完全不同。low_dim 数据收敛快、占用空间小、适合快速验证代码流程；image 数据更接近真实视觉操作场景，但训练时间、显存占用和调参难度都会上升。所以我的建议是：第一次复现默认使用 low_dim 数据集，至少在环境、训练、视频生成整条链路顺利跑通之前，先不要去碰 image。

下载完后，目录结构大致是这样：

datasets/ lift/ low_dim_v141.hdf5 image_v141.hdf5 can/ low_dim_v141.hdf5 image_v141.hdf5

具体文件名里的v141可能随版本变化，不用死记，知道 HDF5 文件名里通常会带数据集版本号就行。

3.2 使用 download_datasets.py 批量拉取

robomimic 官方提供了数据集下载脚本，比自己在网页里一个个点要方便得多。进入仓库根目录后，先查看脚本支持的参数：

python robomimic/scripts/download_datasets.py --help

常见的用法是同时指定任务和数据集类型：

python robomimic/scripts/download_datasets.py \ --tasks lift \ --dataset_types low_dim

想一次性跑完所有任务，可以多列几个：

python robomimic/scripts/download_datasets.py \ --tasks lift can square tool_hang transport \ --dataset_types low_dim image

如果你不想把数据放在默认目录，可以看下脚本是否有--download_dir这类参数，有的话就指定一个自己的路径。每个版本的参数名可能略有差异，所以最保险的办法是先--help，再执行。

3.3 大文件下载的三个细节

第一，文件不算小，尤其 image 数据集。下载之前留出足够磁盘空间，建议至少 20GB 以上；只下 low_dim 的话会小很多，但也不要只看单文件大小，任务数量多时总量会快速增加。

第二，网络中断会导致 HDF5 文件损坏。如果官方脚本不支持断点续传，你可以先用wget -c把文件拉下来，再放到脚本期望的目录里。wget -c的好处是断了能接着下，不用从头再来：

wget -c <数据集文件的直链>

第三，下载完成后不要急着训练，先检查文件是否能被 h5py 正常打开。这一步能帮你把“下载损坏”和“程序 bug”这两类问题明确分开。

3.4 用 h5py 检查数据集内部长什么样

robomimic 的数据集是 HDF5 格式，HDF5 可以理解为一种“带结构的大文件”，里面有分组、数据集和属性。用 Python 查看非常方便：

python

import h5py f = h5py.File("datasets/lift/low_dim_v141.hdf5", "r") # 顶层一般有 data 等字段 print(list(f.keys())) # 每个演示是一个 demo_ demos = list(f["data"].keys()) print(demos[:5]) # 看一个演示内部结构 demo = f["data/demo_0"] print(list(demo.keys())) print(demo["actions"].shape) print(list(demo["obs"].keys()))

输出里你会看到actions、rewards、dones、states和obs这些字段。obs下面通常有机械臂末端位置、末端姿态、夹爪状态等观测项，image 数据集里还会有相机图像。把这一步做扎实，后面配置 obs_keys 就不会靠猜。

4. 训练前必须做的配置改动

4.1 配置文件里的三个关键区域

robomimic 使用 JSON 配置文件控制训练流程，配置文件在robomimic/configs/目录下，比如bc.json、bc_rnn.json、cql.json。我第一次打开这些文件时觉得字段太多，其实只需要关注几个核心区域。

experiment区域控制实验本身，例如 rollout 是否开启、多久做一次 rollout、保存 checkpoint 的频率。data区域控制数据集路径、训练验证文件、obs 键等。train区域控制训练轮数、Batch Size、学习率、输出目录等。

用表格整理一下就是：

不同版本的字段不完全一样，但思路一致：先用默认配置跑通，再根据结果调整关键字段。

4.2 按任务选择算法

不同算法适用的场景不太一样。如果你只是想快速验证流程，BC 是最稳的起点。它实现简单、收敛快，在 low_dim 的 lift、can 任务上通常能取得不错的表现。BC-RNN 引入了循环结构，适合处理带时序信息的数据，尤其是 image 数据集，因为单帧图像无法完整表达速度等信息。BC-Transformer 在更长的时序依赖上可能更强，但训练也更重。

离线强化学习方法里，CQL、IQL、TD3-BC 都是常见选择。它们比 BC 更容易受 reward 设计和数据质量影响，调参空间更大。我的建议是：不要一上来就跑 offline RL，先把 BC 作为基线跑通，再逐步切换到更复杂的算法。

4.3 用 Data 和 Obs 键对齐数据集

JSON 配置里对数据和观测的描述必须和实际 HDF5 文件匹配。如果你用的官方数据集和官方默认配置，通常不需要大改，因为默认配置就是为这些数据集写的。但如果你换了任务、换了数据版本，或者以后用自己采集的数据，就必须检查 obs 键。

怎么检查？回到上一步的 h5py 输出，把demo["obs"].keys()里看到的字段和配置文件里的 obs 键对照一遍。比如 low_dim 数据里常见的是robot0_eef_pos、robot0_eef_quat、robot0_gripper_qpos等；image 数据里则是agentview_image、eye_in_hand_image这类图像键。

配置不匹配最常见的报错就是 KeyError。此时不要盲目改代码，先用 h5py 确认数据集里实际有哪些字段，再改配置。

4.4 训练命令与日志解读

配置确认后，训练命令其实很简洁。以官方的bc.json为例：

python robomimic/scripts/train.py \ --config robomimic/configs/bc.json \ --dataset datasets/lift/low_dim_v141.hdf5 \ --output_dir ./exp/lift_bc

看到标准输出开始打日志，说明训练已经启动。训练日志里一般会显示 epoch、训练 loss、验证指标和 rollout 成功率。不要只盯着 loss，因为模仿学习的 loss 下降不一定代表任务成功率高。真正值得关注的是 rollout 阶段的Success_Rate。

5. 开始训练：一个 lift 任务的完整例子

5.1 从零训练 BC 策略的命令

假设你已经把数据下载到了datasets/lift/low_dim_v141.hdf5，代码在robomimic目录下，conda 环境也已经激活。那么完整命令如下：

conda activate robomimic cd robomimic python robomimic/scripts/train.py \ --config robomimic/configs/bc.json \ --dataset ../datasets/lift/low_dim_v141.hdf5 \ --output_dir ../exp/lift_bc

这里我把输出目录放到了代码目录外面，避免把训练产物和源码混在一起。train.py会把运行时的配置复制到输出目录里，后续评估模型时直接使用这份config.json，就能保证训练和评估配置一致。

5.2 训练过程中需要盯的指标

BC 训练刚开始的时候，loss 会快速下降，这是正常的。如果数据集比较简单，比如 lift 的 low_dim 数据，可能几十个 epoch 后 rollout 成功率就有明显上升。如果过了很多 epoch 还是 0，先别急着换算法，按这个顺序排查：

• rollout 是否真的开启？如果experiment.rollout.enabled为 false，日志里不会出现 rollout 指标。
• rollout 的评估次数是否太少？如果每轮只试 1 次，成功率波动会很大。
• 任务 horizon 是否够长？有些任务需要足够大的时间步才能完成，截断太早会导致失败。
• 数据集路径和配置中的 obs 键是否匹配？

我通常会在训练时开一个终端盯着日志，看 loss 和Success_Rate的变化趋势。如果 loss 正常下降但成功率始终为 0，那大概率不是梯度问题，而是数据或评估设置问题。

5.3 中途保存与恢复训练

robomimic 默认会在训练过程中保存模型 checkpoint，保存频率由experiment.save.every_n_epochs控制。checkpoint 文件一般放在输出目录下的models文件夹里，例如model_epoch_100.pth或者带best字样的模型文件。

如果你想把训练过程停下来，后面再接着跑，建议先确认当前版本是否支持恢复训练。不同版本的train.py支持情况不太一样，最简单的方式是直接用现有 checkpoint 做评估，而不是纠结于“无缝续训”。从实验复现的角度看，通常更关心的是最终策略表现，而不是训练中断在哪里。

5.4 训练完成后 output 目录里有什么

训练结束后，你的输出目录里一般会包含：

exp/lift_bc/ config.json logs/ models/ plots/

config.json是完整展开后的配置，非常重要；logs里是训练日志；models里是保存的模型权重；plots里是训练过程曲线。下一步生成视频时，最需要的就是config.json和models下的 checkpoint。

6. 生成训练视频：把你的策略变成可见的 rollout

6.1 用 run_trained_agent.py 生成视频

训练完成后，最常见的需求是“看一段策略实际操作的视频”。robomimic 专门提供了评估脚本，通常叫run_trained_agent.py。用法大致是这样：

python robomimic/scripts/run_trained_agent.py \ --agent exp/lift_bc/models/model_best.pth \ --config exp/lift_bc/config.json \ --video_path exp/lift_bc/rollout.mp4

如果脚本提示参数名不对，先执行--help查一下。不同版本可能用--checkpoint、--policy等不同名字，但核心思路是一样的：把训练好的模型放进去，指定配置，脚本会启动仿真环境，让策略自己跑若干回合，然后把画面保存成视频文件。

6.2 批量 rollout 与成功率统计

生成单个视频可能带有偶然性，你不能只看一个回合就说策略好或不好。更科学的做法是批量 rollout，比如让策略跑 50 个回合，统计成功率。很多场景下，你甚至不需要保存视频，只需要把成功次数和平均回报打印出来。

如果你用的是run_trained_agent.py，留意脚本是否支持--n或--num_rollouts这类参数。批量 rollout 拿到的成功率，才是你写实验报告、和论文基线对比时真正该用的数字。单条视频更多是用来“看行为”，而不是“下定论”。

6.3 训练期间自动保存的视频片段

robomimic 在 rollout 开启时，可能会在训练过程中直接保存视频。具体是否保存、保存频率如何，取决于配置里和 rollout 相关的参数。如果你不想训练完再单独评估，可以在训练阶段就把视频片段功能打开，这样每个 rollout 周期结束后就能看到当时的策略表现。

我个人的习惯是：训练初期不频繁保存视频，否则磁盘消耗太快；等到成功率有明显上升趋势后，再把 rollout 频率调高，以便选出一个行为最稳定的 checkpoint 去生成最终视频。

6.4 视频参数和渲染设置的微调建议

生成视频时，有几个参数会直接影响观看体验。第一个是相机视角，robosuite 环境通常有多个相机视角，默认视角可能看不到关键操作区域。如果你发现视频里机械臂动作被遮挡，优先调整视角相关参数，或者使用官方配置里推荐的 camera 名称。

第二个是帧率。默认帧率太低会显得动作卡顿，太高文件又太大。一般 20 到 30 fps 比较合适。如果你有更多需求，比如把多个视角拼在一起，可以先把每帧渲染成图片，再用 FFmpeg 合成视频：

ffmpeg -framerate 20 -i frame_%06d.png -c:v libx264 rollout.mp4

这种方式更灵活，适合做汇报材料和论文补充视频。

7. 常见问题与排查技巧实录

7.1 快速排查表

这张表只是一个起点。很多时候问题不是单一原因，而是多个配置叠加导致的，所以排查时要一次只改一个变量。

7.2 我踩过的几个典型坑

第一个坑是“数据集版本看错”。robomimic 数据集文件名里带版本号，如果你下载的是旧版数据，但代码用的是新版的 obs 键或任务定义，训练时会出现莫名其妙的维度不匹配。我建议每个实验都写一个 notebook，把数据集路径、文件版本、配置 hash 统一记下来。

第二个坑是“在容器里跑渲染”。容器环境通常没有显示设备，直接跑 rollout 有时会崩。解决方案不是把渲染代码删掉，而是用 xvfb 模拟显示。类似xvfb-run -a python ...，或者把渲染后端切到 EGL，都能解决问题。

第三个坑是“输出目录写进了代码目录”。训练生成的大量 checkpoint 和视频如果和代码混在一起，后续git pull或版本切换会非常痛苦。最好从一开始就把实验输出放在独立目录，比如exp/lift_bc，并且让程序路径里不出现空格和中文。

7.3 结果偏低时的排查思路

如果你发现自己的成功率和论文里差异很大，先不要怀疑论文造假。先检查这几个因素。

第一，数据是否完整。官方数据集有很多个 demo，如果你只拿前几个 demo 训练，表现通常会差很多。第二，训练轮数是否足够。BC 虽然简单，但训练不足照样欠拟合。第三，随机种子。robomimic 的 rollout 本身带有随机性，不同种子可能差几个百分点。做实验对比时，最好固定种子并报告多次运行的平均值。

最后还有一个容易被忽视的因素：训练和评估时使用的数据版本必须一致。任务定义、奖励设置、重置逻辑只要有一点点偏差，成功率都会受影响。

8. 这套流程能复用到哪些场景

8.1 换算法做对比实验

robomimic 最大的价值在于“公平对比”。你已经把 BC 跑通了，接下来如果想跑 BC-RNN，只需要换一个配置文件：

python robomimic/scripts/train.py \ --config robomimic/configs/bc_rnn.json \ --dataset datasets/lift/low_dim_v141.hdf5 \ --output_dir ./exp/lift_bc_rnn

数据、评估方式、视频生成流程都保持不变，你就能比较不同算法在同一数据集上的差异。这也是很多研究组拿 robomimic 做实验底座的原因。

8.2 跑自己的数据

如果你有自己的机器人采集数据，也可以套用这套流程。核心是把数据转换成 robomimic 认识的 HDF5 格式，保证有obs、actions、rewards、dones这些关键字段。转换时注意观测命名要和配置一致，动作空间要和环境定义一致。

这一步没有官方魔法，更多是数据工程。建议先拿一个小 demo 集跑通整个流程，再逐步扩大数据量。数据量越大，格式错误定位越困难。

8.3 这套流程的扩展方向

从 robomimic 出发，你可以继续研究很多方向：多任务模仿学习、跨任务泛化、视觉策略、离线强化学习中的保守值估计、数据增强对策略的影响等。它面向的是机器人操作实验，但背后的“数据集规范、训练接口统一、评估指标可复现”这套思想，也可以迁移到其他机器人学习项目里。

如果你后续要做真实机器人部署，robomimic 的模型训练部分仍然可以复用，只是需要把 sim 里的 obs 和 action 映射到真实机器人上。这时候前期准备的数据检查、配置管理、评估流程会帮你省掉大量重复工作。

我个人的体会是：第一次复现这类实验，千万不要跳过“读数据”这步。很多人一上来就训练，报错了才回头看 HDF5，反而浪费更多时间。先把数据看清，把默认配置跑通，再一步步加复杂度，整个过程会顺很多。最后再提醒一句：生成视频不是可选项，而是验证策略行为最直观的方式。很多指标上看着不错的策略，一看视频就会发现它在某个位置反复抖动或卡住，这时候你才真正知道下一步该改哪里。