ManiSkill2 踩坑记录：从 pip 安装到成功回放 PickSingleYCB Demo（Vulkan/Wrapper 全流程）

在 Linux 上从零搭建 ManiSkill2（mani-skill2==0.5.3）并成功回放官方 PickSingleYCB 演示轨迹

最容易卡住的坑（Vulkan 渲染设备、环境 wrapper 兼容）一次性解决

主要的问题在于服务器显示gui需要通过x11转发，然后这里vulkan的配置有一些问题

1. 环境与依赖安装

我使用 conda 建立独立虚拟环境并安装 ManiSkill2：

https://maniskill2.github.io/

conda create -n maniskill2 python=3.10
conda activate maniskill2
pip install mani-skill2

安装完成后确认包版本：

mani-skill2==0.5.3

依赖里关键的是 sapien==2.2.2（ManiSkill2 的物理仿真/渲染底座）

安装完成后可以在环境中 import mani_skill2 通过。

2. 下载最小资产与 demo（最小可运行集）

为了尽快跑通桌面刚体抓取任务，我只下载了最基本的资产：

python -m mani_skill2.utils.download_asset ycb
python -m mani_skill2.utils.download_asset minimal_bedroom
python -m mani_skill2.utils.download_demo PickSingleYCB-v0

下载完成后，demo 轨迹文件位于类似路径：

demos/v0/rigid_body/PickSingleYCB-v0/*.h5

3. 第一个大坑：SAPIEN 报 “Cannot find a suitable rendering device”

执行回放时出现：

RuntimeError: Cannot find a suitable rendering device

这是 Vulkan 渲染链路问题，不是 ManiSkill2 本身的代码 bug。排查思路：

安装并运行 Vulkan 工具检查 Vulkan 是否可用：

sudo apt-get install -y vulkan-tools
vulkaninfo | head -n 50

我这里 vulkaninfo 提示存在 lavapipe/llvmpipe（软件 Vulkan）以及 NVIDIA GPU，但 ManiSkill2/SAPIEN 仍然无法选到合适的渲染设备。

关键发现：系统 Vulkan ICD 路径中没有 NVIDIA ICD（/usr/share/vulkan/icd.d/ 里只有 intel/lvp/radeon），但在：/etc/vulkan/icd.d/找到了 nvidia_icd.json。

解决方法：强制 Vulkan 使用 NVIDIA ICD

export VK_ICD_FILENAMES=/etc/vulkan/icd.d/nvidia_icd.json

为避免每次手动设置，我将其写入 ~/.bashrc：

echo 'export VK_ICD_FILENAMES=/etc/vulkan/icd.d/nvidia_icd.json' >> ~/.bashrc
source ~/.bashrc

之后 ManiSkill2 的渲染设备错误消失。

4. 第二个坑：找不到 demo 文件（FileNotFoundError）

如果直接在 ~ 目录运行 replay，可能会报：

FileNotFoundError: ... demos/... No such file or directory

原因是 demo 下载在项目目录（如 ~/my_code/manipulation），相对路径在 ~ 下不成立。解决方法：

cd 到 demo 所在目录再运行；或使用绝对路径。

5. 第三个坑：Gym wrapper 导致 obs_mode/control_mode 读取失败

回放继续后报错：

AttributeError: 'TimeLimit' object has no attribute 'obs_mode'

原因：gym.make() 返回的 env 被 TimeLimit wrapper 包装，obs_mode/control_mode 在底层 env 上。

修复方法：对 replay 脚本做最小补丁（unwrapped）

定位文件：

python -c "import mani_skill2.trajectory.replay_trajectory as rt, os; print(os.path.abspath(rt.file))"

在 env = gym.make(...) 后插入：

env = env.unwrapped

6. 第四个坑：RecordEpisode wrapper 没有 render_human

继续回放后出现：

AttributeError: 'RecordEpisode' object has no attribute 'render_human'

同样是 wrapper 没转发接口。最小修复：

将 replay 脚本中的：

env.render_human()

改为：

env.unwrapped.render_human()

修复后终于能正常显示回放画面，demo 成功运行。

FILE=/home/aiziqing/anaconda3/envs/maniskill2/lib/python3.10/site-packages/mani_skill2/trajectory/replay_trajectory.py
grep -n "render_human" $FILE | head -n 5
sed -i 's/env\.render_human()/env.unwrapped.render_human()/g' $FILE
grep -n "render_human" $FILE | head -n 5

7. 最终可用的回放命令

在 demo 目录下运行（示例）：

VK_ICD_FILENAMES=/etc/vulkan/icd.d/nvidia_icd.json \
python -m mani_skill2.trajectory.replay_trajectory \
  --traj-path demos/v0/rigid_body/PickSingleYCB-v0/035_power_drill.h5 \
  --vis --bg-name minimal_bedroom

如果你是纯 SSH 无 GUI 环境，--vis 可能会遇到显示问题，此时建议使用离屏渲染/保存视频模式（以 -h 参数为准）。