安装 Lambda Sim

Lambda Sim 以预装依赖的容器镜像提供运行环境。完成宿主机检查、启动容器、挂载资产和运行验证后，即可使用 Lambda Sim 导入 USD 场景并进行渲染。直接使用该镜像时，不要再次安装 Lambda Sim 或覆盖镜像内的 Python 依赖。

前提条件

宿主机环境

准备以下基础环境：

项目	要求	说明
MUSA Linux Driver	5.2.0	必须与容器内的 MUSA Compute Lib 主版本一致。
MUSA Compute Lib	5.2.0	容器使用 /usr/local/musa 中的运行时库。
MUSA Container Toolkit	2.2.0 或更高版本	支持 Docker 和 mthreads-container-runtime。
Python	3.10	容器默认使用 python3。
操作系统	Ubuntu 22.04 LTS，x86_64	这是当前主要验证环境。

还需要准备：

• 可用的 MTT GPU 和设备节点。
• Docker，或可用的 mthreads-container-runtime。
• 容器镜像仓库访问权限。
• USD、贴图、机器人模型和渲染输出所在的共享目录或本地目录。

驱动和容器内的 libmusa 主版本必须一致。如果宿主机驱动为 4.3.x，而容器使用 MUSA 5.2.0，加载 torch_musa 时可能出现 undefined symbol: muThreadExchangeStreamCaptureMode。

操作系统与 CPU

主分支运行环境为 Ubuntu 22.04 LTS（x86_64）。已列入兼容范围的宿主系统包括：

• Ubuntu 20.04、22.04 和 24.04 LTS。
• CentOS 8、Rocky Linux 8。
• openEuler 20.03、22.03。
• 中标麒麟 V7、V10。

Lambda Sim 在容器内运行。宿主机主要负责提供 MUSA 驱动、设备节点和容器运行时。只有在重新编译 MUSA native 扩展时，才需要额外确认 CPU 和编译器适配；直接运行预装镜像不需要配置 TORCH_MUSA_ARCH_LIST。

安装流程概览

按以下顺序完成安装：

步骤	操作	结果
1	检查宿主机	确认驱动、运行时版本和 GPU 设备节点。
2	获取预装镜像	准备包含 Lambda Sim、渲染器和运行时依赖的镜像。
3	启动容器	透传 GPU 能力，挂载资产和工作目录。
4	检查容器环境	确认 MUSA、Python 包、Lambda Sim 和命令行入口可用。
5	准备资产	将 USD、贴图和机器人模型放到容器可访问的目录。
6	运行示例	运行命令行入口或 example 脚本验证渲染链路。

步骤 1：检查宿主机

启动容器前，在宿主机执行：

mthreads-gmi
ls /dev/mtgpu.*
cat /usr/local/musa/version.json

检查以下结果：

• mthreads-gmi 能识别 MTT GPU，并显示驱动和运行时版本。
• /dev/mtgpu.* 至少包含可用设备节点。
• /usr/local/musa/version.json 显示的运行时主版本为 5.2.0。

步骤 2：获取预装镜像

使用以下镜像：

harbor.mthreads.com/mt-studio-embodied-ai/roboevolve:roboevolve_5.2.0_torch2.9.1post_axinfra-ektro_202600909_release_v2

镜像已经包含：

• Torch 2.9.1 和 Torch-MUSA 2.9.1。
• MUSA Compute Lib 5.2.0。
• Lambda Sim 0.3.0。
• alphacore-ektro、ektro、mujoco-ektro、mujoco-warp、path-tracer 和 warp。
• Lambda Sim 的 example 脚本和测试资产。

容器内的主要 Python 包版本如下：

包	版本或路径
alphacore-ektro	0.1.0，/workspace/alphacore-ektro
ektro	0.1.0
lambdasim	0.3.0，/workspace/LambdaSim
mujoco	3.5.0
mujoco-ektro	0.2.0，/workspace/mujoco-ektro
mujoco-warp	3.6.0，/workspace/mujoco_warp_musa
usd-core	26.8
warp	1.12.1.dev2608，/workspace/axInfrastructure
path-tracer	/workspace/path_tracer_musa/python，通过 sys.path 提供

步骤 3：启动容器

设置需要使用的 GPU：

export MTHREADS_VISIBLE_DEVICES=0

使用 Docker

docker pull harbor.mthreads.com/mt-studio-embodied-ai/roboevolve:roboevolve_5.2.0_torch2.9.1post_axinfra-ektro_202600909_release_v2

docker run -dit \
  --env MTHREADS_VISIBLE_DEVICES="${MTHREADS_VISIBLE_DEVICES}" \
  --env MTHREADS_DRIVER_CAPABILITIES=all \
  --net host \
  --pid=host \
  --pids-limit=65536 \
  --shm-size 500g \
  -v /mnt/shared/assets:/workspace/assets \
  -v /mnt/shared/workspace:/workspace \
  --name lambdasim-dev \
  harbor.mthreads.com/mt-studio-embodied-ai/roboevolve:roboevolve_5.2.0_torch2.9.1post_axinfra-ektro_202600909_release_v2 \
  bash

参数作用如下：

参数	作用
MTHREADS_VISIBLE_DEVICES	指定容器内可见的 GPU。
MTHREADS_DRIVER_CAPABILITIES=all	透传 GPU 所需的 MUSA 能力。
--net host	使用宿主机网络，便于访问服务和共享资源。
--pid=host、--pids-limit=65536	为仿真子进程提供足够的进程资源。
--shm-size 500g	为多进程渲染和 mujoco-warp 提供共享内存。
-v /mnt/shared/assets:/workspace/assets	挂载 USD、贴图和机器人资产。
-v /mnt/shared/workspace:/workspace	挂载工作区，使源码和输出可持久化。

不需要单独为每张 GPU 添加 /dev/mtgpu.* 设备参数；MTHREADS_VISIBLE_DEVICES 和 MTHREADS_DRIVER_CAPABILITIES=all 负责设备透传。

使用 MUSA Container Toolkit

不使用 Docker daemon 时，可以使用容器工具直接启动：

mthreads-container-runtime run -dit \
  --env MTHREADS_VISIBLE_DEVICES="${MTHREADS_VISIBLE_DEVICES}" \
  --env MTHREADS_DRIVER_CAPABILITIES=all \
  -v /mnt/shared/assets:/workspace/assets \
  -v /mnt/shared/workspace:/workspace \
  --name lambdasim-dev \
  harbor.mthreads.com/mt-studio-embodied-ai/roboevolve:roboevolve_5.2.0_torch2.9.1post_axinfra-ektro_202600909_release_v2 \
  bash

进入容器

docker exec -it lambdasim-dev bash

如果使用 mthreads-container-runtime 启动，请使用该工具对应的进入命令，确保进入同一个容器实例。

步骤 4：检查容器环境

进入容器后，先检查设备和核心依赖：

musaInfo
python3 -c "import torch, torch_musa; print(torch.musa.is_available(), torch.musa.device_count())"
python3 -c "import lambdasim; from lambdasim.scene.scene import Scene; print('lambdasim ok')"
python3 -c "from path_tracer.lambda_renderer import LambdaRenderer; from path_tracer.config import RenderConfig; print('path_tracer ok')"
python3 -c "import warp, mujoco_warp, ektro, alphacore_ektro, mujoco_ektro; print('deps ok')"
lambdasim --help

预期结果包括：

• musaInfo 能列出容器可见的 MTT GPU。
• torch.musa.is_available() 为 True，并显示可用设备数量。
• Lambda Sim、path_tracer 和其他运行依赖均能导入。
• lambdasim --help 输出命令行帮助。

镜像已经以 editable 模式安装 Lambda Sim 和相关依赖。不要执行 python3 -m pip install lambdasim，否则可能重新拉取不可访问的依赖仓库或覆盖镜像内版本。

步骤 5：准备项目和资产

容器内的主要目录如下：

/workspace
├── LambdaSim/             # Lambda Sim 源码和 Python 包
│   ├── src/lambdasim
│   ├── scripts
│   ├── tests
│   └── pyproject.toml
├── path_tracer_musa/      # path-tracer 及其 native 扩展
├── mujoco_warp_musa/      # mujoco-warp MUSA 版本
├── mujoco-ektro/          # MuJoCo ektro 后端
├── alphacore-ektro/       # 物理求解器库
├── axInfrastructure/      # warp 运行库
├── models/                # 按需挂载的模型权重
└── assets/                # USD、贴图和机器人模型

Lambda Sim 的内置测试资产位于 /workspace/LambdaSim/tests/assets/。正式场景放在 /workspace/assets/ 下，并确保 USD 引用的网格、贴图和机器人模型都能访问：

ls /workspace/assets

单节点调试可以使用本地目录。多节点运行时，所有节点应挂载同一个资产目录，并将输出写入共享路径。

共享存储适用于跨节点共享场景、模型权重和渲染输出。单节点 example 或一次性离线渲染不需要强制使用共享存储。

步骤 6：运行 Lambda Sim

进入 Lambda Sim 项目目录：

cd /workspace/LambdaSim

运行命令行帮助和单帧渲染：

lambdasim --help

MTHREADS_VISIBLE_DEVICES=0 \
lambdasim \
  --device musa:0 \
  --output-dir /workspace/assets/render_out \
  /workspace/assets/usd/<scene>.usda

也可以运行镜像中的 example：

python3 scripts/example_franka_mujoco_musa.py

如果使用多机多卡环境，请确保每台机器使用正确的 MTHREADS_VISIBLE_DEVICES，并将输出目录设置为共享存储路径。

步骤 7：验证安装结果

在容器中运行以下检查：

set -e
musaInfo | head -5
python3 -c "import torch, torch_musa; print(torch.musa.is_available(), torch.musa.device_count())"
lambdasim --help | head -1
python3 - <<'PY'
import alphacore_ektro
import ektro
import lambdasim
import mujoco_ektro
import mujoco_warp
import path_tracer
import warp
from lambdasim.scene.scene import Scene
from path_tracer.config import RenderConfig
from path_tracer.lambda_renderer import LambdaRenderer
print("imports OK")
PY
python3 - <<'PY'
import mujoco_warp
import warp
print("warp", warp.__version__, "mujoco_warp", mujoco_warp.__version__)
PY

预期结果包括：

True <设备数>
usage: lambdasim [-h] ...
imports OK
warp 1.12.1.dev2608 mujoco_warp 3.6.0

常见错误

错误或现象	处理方法
undefined symbol: muThreadExchangeStreamCaptureMode	检查宿主机驱动和容器内 MUSA Compute Lib 是否都是 5.2.0。
musaInfo 看不到设备	检查 MTHREADS_VISIBLE_DEVICES、MTHREADS_DRIVER_CAPABILITIES=all 和容器启动参数。
torch.musa.is_available() 返回 False	检查 MUSA 驱动、设备透传和 /usr/local/musa/lib。
import path_tracer 失败	确认 /workspace/path_tracer_musa/python 仍在 Python 搜索路径中，并保留工作区挂载。
运行 lambdasim_demo 失败	使用 lambdasim 和 scripts/example_*.py；不要使用无效的 lambdasim_demo 入口。
pip install 重新拉取依赖失败	镜像已预装依赖，不要重新安装 Lambda Sim 或覆盖 Torch、torchvision 和 torchcodec。
torch.cuda.is_available() 返回 True	检查是否误装 CUDA 版 PyTorch；当前镜像应使用带 MUSA 后缀的 PyTorch。

后续步骤

安装验证通过后，按照 Lambda Sim 快速开始运行场景导入、运行时对象创建和图像生成。需要查看模块、函数和参数时，请打开 API 参考。需要接入上层任务、数据生成、策略训练或评测流程时，请继续阅读上层平台集成。