MuJoCo介绍

MuJoCo 全称 Multi-Joint dynamics with Contact，是一个物理仿真引擎，主要用于机器人、生物力学和强化学习研究。它的特点是计算快、接触力学模拟准确，适合需要大量仿真的场景，比如训练控制策略。

MuJoCo 仿真可视化镜像预置 MuJoCo Studio、MuJoCo Web Viewer 和 mjlab Cartpole 示例。用户可以通过百舸开发机入口，在浏览器中快速查看仿真画面、编辑并保存 XML 场景，也可以在终端启动 Web Viewer、训练和评估示例。

本文介绍如何创建开发机、打开 MuJoCo Studio、管理显示模式、编辑保存场景，以及运行镜像内置的 Web Viewer 和 Cartpole 示例。

部署环境要求

使用须知

• GPU 模式下自动检测同时检查 Vulkan/NVIDIA 渲染和 NVENC 硬件编码。
• 原生 Studio 和 Web Viewer 使用 MuJoCo 版本与mjlab 训练环境使用 MuJoCo / MuJoCo Warp版本相互独立。

1. 通过快速开始创建开发机

1.1 创建开发机

1. 在百舸控制台，快速开始下找到该卡片【通过网页方式可视化连接 MuJoCo】
2. 在卡片中，点击【通过开发机打开】
3. 根据您的需求选择开发机配置，MuJoCo Studio 可以通过 CPU 进行渲染，因此不强制依赖显卡，但流畅度会受到影响
4. 在开发机状态为运行中后，点击登录进入开发机

2. 进入 MuJoCo 可视化界面

2.1 启动 MuJoCo Studio

新开发机或新容器首次启动时，镜像会自动检测 GPU 渲染和硬件编码能力，并启动 Studio。打开 MuJoCo Studio 卡片即可进入页面。

如果用户在同一开发机中手动停止了 Studio，之后重启 Jupyter 不会再次自动拉起；如果页面提示 Studio 尚未启动，请在 JupyterLab Terminal 中执行：

1sim-studio start --auto

启动完成后，页面会自动显示原生 MuJoCo Studio 编辑器。关闭浏览器标签页或 Terminal 不会停止 Studio。
请注意：如果您挂载了显卡，请确认页面左上角渲染模式为【GPU】，如果显示为【CPU】，请参考 2.3 命令与配置在终端中尝试重启或参考 2.5 常见问题咨询客服。

2.2 页面功能

原生 Studio 保存的是模型定义。运行时的位置、速度、仿真时间和编辑器撤销记录不会写入 XML。关闭页面前请先进行保存。

2.3 命令与配置

Studio 启动和模式管理

模式偏好会持久化。后续执行不带模式参数的 sim-studio start 时，会沿用上次选择；需要恢复自动检测时，明确使用 --auto。

--saved 只表示用户已经完成保存确认，不会自动保存场景，也不会检查编辑器是否存在未保存修改。

Studio 已运行时，start 不会替换当前实例。重启或切换模式会关闭当前 Studio，执行前先在原生 Studio 中选择 File → Save XML。

切换模式或加载其他场景时，使用 restart：

1sim-studio restart --auto --saved \
2  --model /root/workspace/my-scene/scene.xml

Web Viewer 和 Cartpole 示例

Web Viewer 和 Cartpole 命令需要保持对应的 Terminal 运行；按 Ctrl+C 结束本次 Viewer 或回放。Viewer 可以与 Studio 同时运行。

Web Viewer 默认加载 humanoid 示例并处于暂停状态，页面提供 Run、Pause 和 Reset 操作。该模型没有控制策略，运行后倒下属于预期行为。保存 XML 后，Web Viewer 会监视文件并自动重新加载；如果进程已结束，再重新执行启动命令。

Cartpole 示例使用 mjlab 官方任务，训练、回放和评估都要求 CUDA 训练环境。未指定 checkpoint 时，play 和 evaluate 使用镜像预置的示例 checkpoint；训练完成后请使用命令输出的实际 checkpoint 路径。Studio 选择 CPU 模式不会把 Cartpole 训练切换为 CPU。修改 Cartpole 模型时，请使用自包含 XML；该示例不接受 include 或外部资产，并且新模型仍需要匹配任务的观测、动作和奖励定义。

2.5 常见问题

Q1：页面显示 Studio 没有启动？

在 JupyterLab Terminal 中执行：

1sim-studio start --auto

然后返回 MuJoCo Studio 页面等待连接。首次启动可能需要等待初始化完成。

Q2：有 GPU，但 Auto 进入了 CPU 模式？

Auto 要求 Vulkan/NVIDIA 渲染和 NVENC 硬件编码同时通过。显卡可见或 CUDA 可用，不代表 NVENC 可用。继续使用 CPU 模式时无需再次启动；如果要切换模式，请先在 Studio 中保存 XML，再执行：

1sim-studio restart --gpu --saved \
2  --model /root/workspace/my-scene/scene.xml

如果只是明确切换到 CPU，可将 --gpu 替换为 --cpu。GPU 模式仍要求图形渲染和 NVENC 检测同时通过。如果必须使用 GPU 模式，请联系平台管理员检查实例的图形驱动、容器图形能力和 NVENC 支持。

Q3：执行 sim-studio start --gpu 提示检测未通过？

这表示 GPU 渲染或硬件编码至少有一项未通过。GPU 强制模式会拒绝启动，不会自动回退到 CPU。确认实例环境后，可临时使用 --auto 或 --cpu。

Q4：修改场景后重新打开，修改没有保留？

在 Editor 中修改后，先执行 Compile and Reload，再执行 File → Save XML。sim-studio stop --saved 和 sim-studio restart --saved 都不会代替保存操作。

Q5：需要加载自己的 XML，应该如何上传？

将 XML 及其纹理、网格和 include 文件一起上传到 /root/workspace 下，并保持相对路径。然后在 Studio 中通过 File → Open Model File 打开，或执行：

1sim-studio restart --auto --saved \
2  --model /root/workspace/my-scene/scene.xml

Q6：Web Viewer 页面没有打开或模型没有更新？

确认 Terminal 中的 sim-example web 进程仍在运行，并打开该命令输出的最新链接。Web Viewer 会监视已保存的 XML，保存后通常会自动重新加载；如果进程已经结束或页面仍未更新，再按 Ctrl+C 结束旧 Viewer，并重新执行命令。

Q7：Cartpole 训练无法启动？

Cartpole 训练、回放和评估都使用 CUDA，并要求使用示例规定的自包含 XML 和任务结构。请确认当前开发机有可用 NVIDIA CUDA 资源；Studio 的 CPU/GPU 显示模式不改变训练设备。评估指定策略时，可以追加 --checkpoint /实际输出目录/model_499.pt。

Q8：窗口被最小化后看不到编辑器？

点击页面中的【恢复窗口】，或在 Terminal 中执行：

1sim-studio restore

该操作只恢复窗口，不会重启 Studio 或改变当前场景。