AI 摘要

还在为IsaacSim复杂的依赖和CUDA冲突抓狂？本文为你解锁XTrainer的高效部署秘籍！带你巧用Docker“集装箱”实现环境隔离，告别系统污染，让具身智能训练搭建从“痛苦”变“秒速”。想要快速开启IsaacLab实操？这份保姆级避坑指南请收好！

前情提要

项目Link：https://github.com/embodied-dobot/x-trainer
比赛赛题：https://github.com/embodied-dobot/x-trainer/tree/dobot-challenge

看前提示

不提供100%回复的技术支持服务，本文主要面向懂一点Linux，但对于部署环境有麻烦的用户，可以结合本文和AI助手来自行部署。

项目概述

简单地说就是IsaacSim做的仿真，项目的话用Lerobot框架做训练，项目的话推荐使用源代码+Anaconda做部署，但是实际上这样做的话会污染现有的环境（因为CUDA要对应环境，且lsaacsim装的也很痛苦），所以作者还提供了Docker这个安装方法，这里主讲这个。

这里简单说一下这个项目给出的Docker部署思路：
首先拉一个Isaaclab2.1.0的image，把项目目录用volume透传进去，随后装一下专有的包。

先期准备

硬件准备：有NvidiaGPU的电脑一台。

首先装双系统，不建议用wsl或者其他方式。系统这里装的Ubuntu24.04。
安装的过程中联网并勾选“使用第三方和专有驱动”，这样能在安装系统的时候就完成Nvidia驱动的安装。

方法一、使用Docker部署

这里让Gemini简单介绍一下Docker：您可以把 Docker 想象成软件领域的“标准化集装箱”。在普通的 Linux 系统中，直接安装不同的应用程序经常会遇到各种运行库版本不匹配的问题，稍不注意就会发生依赖冲突，把系统环境弄得乱七八糟；而 Docker 的巧妙之处在于，它能把每一个软件及其所需的所有运行环境（代码、依赖库、配置文件等）统统打包进一个轻量级、完全隔离的“容器”中。 这样一来，这些容器就可以直接在您的 Linux 机器上平稳运行且互不干扰，不仅让软件的安装、卸载和跨机器迁移变得像搬运集装箱一样简单无痛，还能完美保持您底层操作系统的干净整洁。

综上所述，Docker部署的优势在于宿主机只要安装NVIDIA驱动和NVIDIA Container Toolkit即可，CUDA都不需要配置（因为CUDA库已经包含在Docker Image中），环境隔离性好，不干扰其他项目，且移除简单方便。

安装Docker

这个不赘述，照着指令跑就行。

curl -fsSL https://get.docker.com -o install-docker.sh
sh install-docker.sh --mirror Aliyun

启用Docker-GPU支持

如果使用Docker做部署，由于IssacSim用GPU做加速，必须让Docker具备访问GPU的能力。
这个需要通过NVIDIA Container Toolkit实现，这里简单介绍安装步骤。
首先添加Nvidia签名和源：

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

然后直接apt把NVIDIA Container Toolkit装上

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

随后启用NVIDIA Container Toolkit

sudo nvidia-ctk runtime configure --runtime=docker  # 开启nvidia-ctk相关
sudo systemctl restart docker   # 重启docker

构建镜像

首先装好git，用来下载和同步代码。

apt install git

接下来直接clone仓库，记得找个合适的文件夹。

git clone https://github.com/embodied-dobot/x-trainer.git
cd x-trainer/docker

接下来开始构建镜像，镜像构建过程中自行确保网络畅通，此处不赘述。这个过程大约会消耗4G流量

docker build --network=host -t xtrainer-leisaac:v1 .

创建容器

Dobot官方提供了俩脚本方便创建/直接进入容器的shell。不过我们需要根据我们的实际情况做修改，这里主要是修改create_docker.sh，推荐使用nano对文件进行编辑。

#!/bin/bash

xhost +
docker run --name isaac-lab --entrypoint bash -it --gpus all -e "ACCEPT_EULA=Y" --network=host \
   -e "PRIVACY_CONSENT=Y" \
   -e DISPLAY \
   -v $HOME/.Xauthority:/root/.Xauthority \
   -v ~/docker/isaac-sim/cache/kit:/isaac-sim/kit/cache:rw \
   -v ~/docker/isaac-sim/cache/ov:/root/.cache/ov:rw \
   -v ~/docker/isaac-sim/cache/pip:/root/.cache/pip:rw \
   -v ~/docker/isaac-sim/cache/glcache:/root/.cache/nvidia/GLCache:rw \
   -v ~/docker/isaac-sim/cache/computecache:/root/.nv/ComputeCache:rw \
   -v ~/docker/isaac-sim/logs:/root/.nvidia-omniverse/logs:rw \
   -v ~/docker/isaac-sim/data:/root/.local/share/ov/data:rw \
   -v ~/docker/isaac-sim/documents:/root/Documents:rw \
   -v /home/xtrainer_leisaac:/workspace/xtrainer_leisaac:rw \
   xtrainer-leisaac:v1

这里重点是倒数第二行， -v /home/xtrainer_leisaac:/workspace/xtrainer_leisaac:rw
我们要把这个前面的部分，也就是 /home/xtrainer_leisaac ，修改成你项目的绝对目录，比如说我的电脑是 /home/nature/x-trainer/ ，这样在容器内就可以访问到这个了。

配置完成后，我们直接运行create_docker.sh即可，随后自动切换到容器中的shell。

进入容器

创建完容器后就不需要每次走create_docker.sh反复创建容器了，直接执行start_docker.sh就可以了。

方法二、手动安装

安装NVIDIA驱动

略，自行查教程。

安装Miniforge / Anaconda

MiniForge / Anaconda 是一个环境管理工具，可以便捷地安装各种常用的库（如CUDA）和环境（管理python虚拟环境），这里我们先安装。

首先把它下载到Ubuntu系统里面，通过这里获取连接：https://mirrors.ustc.edu.cn/github-release/conda-forge/miniforge/LatestRelease/

wget https://mirrors.ustc.edu.cn/github-release/conda-forge/miniforge/LatestRelease/Miniforge3-Linux-x86_64.sh
chmod +x ./Miniforge3-Linux-x86_64.sh
bash ./Miniforge3-Linux-x86_64.sh

按照指引完成安装即可。

创建虚拟环境

考虑到blackwell的架构变更导致isaacsim 低版本不兼容，下面会同时给出isaacsim 4.5和isaacsim 5.1的安装方式，赛程建议是使用4.5，不过本文接下来提及的指令都会有4.5和5.0两个版本，可以选择。

因为文档建议用IsaacSim 4.5，Python版本选用3.10。

conda create -n leisaac python=3.10

如果你是50系显卡，那么必须安装IsaacSim 5.0+，按照以下指令安装：

conda create -n leisaac python=3.11

指令跑完后，用 conda activate leisaac 切换到对应环境，如图所示，可以看到虚拟环境已经切换，执行python -V 可以输出正确的python版本。

然后我们需要安装CUDA，这里呢因为项目用的是IsaacSim 4.5，cuda就安装11.8。
在确保切换到leisaac环境的情况下，我们执行下面的指令安装Cuda

# 如果你是50系显卡以下，执行下面这个指令：
conda install cudatoolkit=11.8 -c nvidia/label/cuda-11.8.0
# 如果你是50系显卡，执行下面这个指令
conda install nvidia::cuda-toolkit==12.6.3

CUDA下载量比较大，需要稍作等待。

完事了再装个nvcc看看，

# 非50系
conda install -c "nvidia/label/cuda-11.8.0" cuda-nvcc
# 50系
conda install -c "nvidia/label/cuda-12.6.3" cuda-nvcc

下载项目代码

(leisaac) nature@rtx5000ada:~$ git clone -b dobot-challenge https://github.com/embodied-dobot/x-trainer.git

如果发现克隆的很慢，可以执行这一条： git clone https://ghfast.top/https://github.com/embodied-dobot/x-trainer.git

安装Torch

先把torch和torchvision装了，isaacsim版本4.5的话推荐用torch 2.5.1 

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118
# 50系：
pip install -U torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128

指令跑完，我们简单验证一下：

python -c "import torch; print(f'PyTorch: {torch.__version__} | CUDA: {torch.cuda.is_available()} | GPU: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"None\"}')"

这样我们torch就装上了，接下来安装isaacsim

安装IsaacSim

这一过程将会消耗大量流量（约10GB），请注意网络使用。

首先提前把setup-tools降级到69版本，安装isaaclab 4.5的依赖flatdict

pip install "setuptools<70.0.0" wheel
pip install flatdict==4.0.1 --no-build-isolation

如果是isaac5.1的话，没有这个bug

随后开始正式安装isaaclab

如果你在海外，可以把指令中的pypi.nvidia.cn换成pypi.nvidia.com。
pip install isaaclab[isaacsim,all]==2.1.0 --extra-index-url https://pypi.nvidia.cn
# 50系显卡执行下面的指令：
pip install "isaaclab[isaacsim,all]==2.3.2.post1" --extra-index-url https://pypi.nvidia.cn

如果指令跑完了，接下来我们来跑一个测试脚本，先执行这个指令创建脚本：

cat << 'EOF' > test_isaac.py
# ⚠️ 黄金法则：在 Isaac Lab/Sim 中，SimulationApp 必须在导入任何其他核心库之前被实例化！
from isaacsim import SimulationApp

# 启动底层 Omniverse 引擎 (Headless 模式，不弹 UI 窗口)
simulation_app = SimulationApp({"headless": True})

import torch
import isaaclab
from isaaclab.app import AppLauncher

print("\n" + "="*50)
print(f"✅ PyTorch 版本: {torch.__version__} (CUDA: {torch.cuda.is_available()})")
print(f"✅ Isaac Lab 成功挂载！")
print("✅ 底层 Omniverse 物理与渲染引擎启动顺利，无崩溃！")
print("="*50 + "\n")

# 安全关闭引擎，释放 GPU 显存
simulation_app.close()
EOF

然后直接执行脚本即可，这个脚本执行需要3-10分钟（第一次运行会下载测试用的资产文件，可能会更久），中途卡住为正常现象。

python ./test_isaac.py

出现以下提示即为成功完成安装。

拉取竞赛用usd文件（模型）

直接敲命令就行了

mkdir ~/xt_race_datasets/
hf download --repo-type dataset Dobot-robot/X-trainer --local-dir ~/xt_race_datasets/

完事了看看文件路径

(leisaac) nature@rtx5000ada:~/x-trainer$ ls ~/xt_race_datasets/assets/
docs  robots  scenes

出来了就可以准备拷贝了

(leisaac) nature@rtx5000ada:~/x-trainer$ cp -R ~/xt_race_datasets/X-trainer_dataset/x-trainer/assets/ ./

拷贝好我们走ls看一下，看看任务sence下载下来没有，如下图出现task1 / 2 / 3就成功了。

安装leisaac包

conda activate leisaac
conda install -c conda-forge evdev pynput
cd ~/x-trainer/
pip install -e source/leisaac

测试

执行键盘遥操作测试，走一个task1看看，记得在项目根目录执行，并启用leisaac环境，第一次启动需要几分钟，请耐心等待。过程中会出现一个GUI界面，但我们可以靠终端来判断是否执行完成。

python scripts/environments/teleoperation/teleop_se3_agent.py \
    --task=task1 \
    --teleop_device=bi_keyboard \
    --num_envs=1 \
    --device=cuda \
    --enable_cameras \
    --multi_view

如图所示，到这里就启动成功了。

我们切换一下顶部的视角到顶相机

然后按B就可以开始用键盘操作机械臂了。

【可选】查看模拟FPS

采集数据

见：https://github.com/embodied-dobot/x-trainer/tree/dobot-challenge

此作者没有提供个人介绍。
最后更新于 2026-04-16