稳妥的起点是克隆项目、建立独立 Python 环境、安装与 CUDA 匹配的 JAX，确认 JAX 返回 GPU 后端，再运行小型 Cartpole PPO。MuJoCo Playground 官方仓库提供 PyPI 包，但建议从源码安装以获得较新的功能和修复，并要求 Python 3.10 以上。
第一次运行的目标不是得到高性能机器人策略，而是验证环境加载、GPU、训练、评估和保存能否完整走通。不能只看命令正常退出，还要检查指标变化并重新加载检查点。
安装前先记录硬件和版本边界
当前源码流程以 uv、Python 3.12 环境和 CUDA 12 JAX 为例。最低 Python 要求为 3.10，但不同发布版与主分支的依赖可能变化。使用项目专用环境可以避免覆盖其他机器人软件。
先记录操作系统、GPU、驱动、Python 和代码提交。组合不匹配时可能退回 CPU，或在初始化时缺少库。完整记录也便于团队复现成功配置。
| 准备项 | 核查标准 |
|---|---|
| Python | 3.10 以上的独立环境 |
| GPU | 受支持的 NVIDIA 设备与正常驱动 |
| JAX | 匹配 CUDA 并返回 gpu |
| 代码版本 | 发布标签或准确提交 |
把安装拆成可以验证的步骤
依次完成仓库克隆、uv 环境创建、CUDA JAX 安装和项目依赖同步。不要把所有命令压成一条，这样才能区分 Python、CUDA、依赖解析和 Playground 本身的错误。
安装时重新查看官方项目文档。先确认 JAX 默认后端输出 gpu，再测试导入 mujoco_playground。首次加载运动或操作环境可能下载 Menagerie 资源，网络限制也可能造成失败。
| 步骤 | 成功信号 |
|---|---|
| 虚拟环境 | 解释器位于项目环境 |
| JAX | 默认后端为 gpu |
| 依赖同步 | 无未解决冲突 |
| 模块导入 | 同一环境中导入成功 |
用 CartpoleBalance 快速验证训练链路
README 的基础命令是 `train-jax-ppo –env_name CartpoleBalance`。它避开复杂机器人资源，却能覆盖环境创建、并行步进、PPO 更新、日志和评估。
测试 Warp 时，应先核查当前支持状态，再增加实现选项。正常运行会持续更新步数与奖励。仅有 GPU 占用不代表成功，奖励不变或出现 NaN 都需要排查。
固定版本与精度才能比较结果
官方发布页面记录功能和依赖变化。主分支会继续更新，因此每次结果都应保存提交。复现实验时还要对齐训练入口和参数。
仓库提示部分 Ampere GPU 上的 JAX 默认 TF32 可能影响复现。需要时可提高矩阵运算精度，并用多个随机种子比较分布，而不是期待完全相同的每一步。
扩大任务前先证明检查点可以恢复
把环境名、随机种子、设置、提交、训练和评估日志、检查点放在同一记录中。启动新进程加载检查点，并用不同评估种子运行，才能确认文件真正可用。
转向 G1 行走、Panda 操作或视觉环境时，依次测试加载、随机动作、短训练和长训练。接触、观测和控制周期增加后，不要一次改变所有变量。
| 保存内容 | 作用 |
|---|---|
| 提交与依赖 | 重建相同软件状态 |
| 环境、种子、设置 | 解释实验差异 |
| 训练与评估日志 | 发现发散和过拟合 |
| 检查点 | 恢复训练和策略评估 |
GPU 训练成功不等于实机成功
工具选择可参考机器人模拟器对比，概念可参考Sim-to-Real 现实迁移，常见问题可参考Sim-to-Real 失败原因。
官方技术报告提供框架和实验背景。仓库明确说明该项目不是 Google 官方支持产品。上实机前仍需限制、急停、延迟、传感器噪声和安全审查。
常见问题
应该从 PyPI 还是源码安装？
PyPI 包可用，但官方仓库建议源码安装以获取较新功能和修复。重视复现时应固定发布版或提交。
没有 GPU 可以运行吗？
部分小测试可能在其他后端运行，但框架的主要价值是 GPU 并行学习。应先确认 JAX 真实返回 gpu。
模拟训练成功后能直接上机器人吗？
不能。动力学、延迟、传感器、接触和执行器差异需要单独的迁移与安全验证。
已核验的官方资料
- Google DeepMind MuJoCo Playground 官方仓库
- MuJoCo Playground 官方文档
- MuJoCo Playground 官方发布
- MuJoCo Playground 技术报告
2026-08-07