当前位置： 首页 > news >正文

【零基础】在Ubuntu22.04上开始一个基于MotrixSim与MotrixLab的强化学习项目

news 2026/4/17 20:45:45

本教程基于MotrixSim与MotrixLab官方文档撰写

⚙️ 系统准备

在开始安装之前，需要安装 uv
uv 是必需的包管理工具。如果尚未安装，请运行以下标准安装命令：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果遇到网络问题可以尝试命令：

wget -qO- https://astral.sh/uv/install.sh | sh

安装完成后需要重启终端并验证安装

# UV版本
uv --version
# Python版本
uv python list

后续如果需要对uv进行版本升级可以执行命令

uv self update

MotrixLab 强制要求使用 Python 3.10 版本，如果没有需要使用uv进行安装：

uv python install 3.10

🛠️ 第一部分：安装 MotrixSim

由于需要确保每个项目都在其专属的、稳定的环境中运行，在每个新项目里都需要重新将 motrixsim 作为依赖添加进去，注意项目文件夹的命名不要是单纯的motrixsim。

为何每个项目都需要独立安装？
简单来说，依赖隔离可以保证项目稳定、避免版本冲突。

  • 避免版本冲突：不同项目可能依赖 motrixsim 的不同版本。如果全局共享，更新一个项目的依赖可能会无意中破坏另一个项目。通过为每个项目独立安装，就能确保每个项目都在其专属的、稳定的环境中运行。
  • 便于项目分发：当一个项目通过 pyproject.toml 等文件声明了所有依赖后，其他开发者或部署环境只需运行 uv sync 就能精确还原环境，实现“一次构建，处处运行”。
  1. 创建项目目录（以motrix_anymal_c_locomotion为例)
mkdir motrix_anymal_c_locomotion && cd motrix_anymal_c_locomotion
  1. 指定Python版本
    使用 Python 3.10 来创建环境：
uv venv --python 3.10
  1. 初始化Python项目
# 生成 pyproject.toml
uv init
  1. 安装MotrixSim
    使用uv安装MotrixSim
uv add motrixsim

uv add 与 uv pip install 的核心区别
核心区别在于是否“声明”依赖：
uv add：会修改 pyproject.toml 文件，将 motrixsim 正式声明为项目的依赖。
uv pip install：只会将包安装到当前环境，不会修改 pyproject.toml。
由此带来的工作流差异：
使用 uv add 后，你的团队成员可以通过 uv sync 一键同步所有依赖。同时，uv.lock 文件会锁定所有依赖的精确版本，确保了环境的高度可复现性。
使用 uv pip install 则需要手动维护 requirements.txt 文件，或依赖团队成员各自记住需要安装哪些包。
因此，对于正式的、需要长期维护的项目，务必使用 uv add。这会让依赖管理变得清晰、可靠，避免了“在我电脑上能运行”的尴尬情况。

  1. 验证安装完成
    安装完成后，检查包信息：
uv pip list | grep motrixsim

如果能看到类似 motrixsim 的条目，则说明安装成功。

🔍 （可选）安装示例与环境配置并验证

为了验证安装并学习 MotrixSim 的使用，可以克隆其官方示例仓库并安装额外依赖。

  1. 工具准备（开启新的终端进行操作）
    更新软件包列表：
sudo apt update

安装 Git：

sudo apt install git -y

验证安装：

git --version

配置全局用户信息，这些信息会记录在每一次的代码提交中（推荐但非必要）：

git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"

查看配置信息：

git config --list

安装 Git LFS 扩展：

Git LFS
Git LFS (Large File Storage) 是一个 Git 的扩展工具，专为解决 Git 在处理大型二进制文件（如图片、视频、数据集等）时效率低下的问题而设计。它通过“指针文件”的方式，将大文件的实际内容存储在 Git 仓库之外，从而保持仓库本身的轻量和高效。

添加 Git LFS 官方软件源（Ubuntu 默认软件源中的 Git LFS 版本可能较旧。此命令通过官方脚本，将 Git LFS 的专用软件源添加到系统中，确保能安装到最新版本）：

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash

安装 Git LFS：

sudo apt install git-lfs -y

验证安装：

git lfs version

初始化 Git LFS：
在 Git 配置中设置必要的钩子（hooks）和过滤器，让 Git 能够识别并正确处理 LFS 文件。
此命令只需在每台电脑上运行一次，它会进行全局设置，影响所有 Git 仓库。

git lfs install
  1. 克隆仓库
    转到项目目录，如：
cd motrix_anymal_c_locomotion

克隆仓库：

git clone https://github.com/Motphys/motrixsim-docs
cd motrixsim-docs
git lfs pull

为什么会需要 git lfs pull？
git lfs pull 的核心功能是将当前分支所需的大文件从远程 LFS 服务器下载到本地，并替换掉工作目录中的占位符，使文件变得可用。这是为了解决 Git 本身处理大文件（如数据集、模型、视频等）效率低下的问题。Git LFS 会用一个很小的指针文件（Pointer File）来替换原始大文件，这个指针文件只有几字节到几百字节，避免了仓库体积过大。可以将 git lfs pull 理解为：git lfs fetch (下载文件到缓存) + git lfs checkout (将文件从缓存释放到工作目录)。

  1. 安装依赖
    检查更新并安装：
uv sync --extra examples --upgrade
  1. 验证安装
    运行一个简单的示例来验证环境配置是否成功：
uv run examples/empty.py

如果能够正常打开仿真窗口，说明环境配置成功！

如果电脑使用集成显卡，终端中显示正在运行但是无法现实窗口可能是以下原因：
问题的出现与 Wayland 的兼容性有关，可以在登录界面（GDM）进行切换。1. 注销当前会话，回到用户登录界面。

  1. 在输入密码之前，找到屏幕右下角的齿轮图标（⚙️）并点击。
  2. 在弹出的菜单中，选择 "Ubuntu on Xorg" 或类似的 X11 会话选项。
  3. 输入密码登录。
  4. 登录后，可以在终端输入 echo $XDG_SESSION_TYPE 来验证，如果输出是 x11，就代表切换成功了。在输入vkcube如果看到一个旋转的彩色立方体窗口，说明 Vulkan 驱动正常工作。
  5. 完成以上步骤并登录 X11 会话后，就可以再次运行仿真程序：
# 在目标文件夹打开终端运行
uv run examples/empty.py

如果这次窗口能正常显示并保持开启，就说明问题已经解决。

关于 “Ubuntu on Xorg” 和默认的 “Ubuntu” 选项
主要区别在于它们使用的图形显示协议不同，这直接影响应用程序的渲染和窗口管理方式。
默认的 “Ubuntu” 选项：使用的是 Wayland 协议。它是新一代的显示服务器，设计更现代、更安全、更简洁，也是 Ubuntu 22.04 及更新版本的默认选择。大多数新应用（包括 GNOME 桌面本身）在 Wayland 下运行流畅，但在某些场景下可能存在兼容性问题。
“Ubuntu on Xorg” 选项：使用的是 X11（也称 X Window System）协议。这是有几十年历史的传统显示服务器，非常成熟稳定，几乎所有 Linux 图形应用最初都是为它设计的。因此，一些在 Wayland 下表现异常的程序，切换到 Xorg 后往往能恢复正常。

💡 创建第一个MotrixSim项目

本部分的操作采用已经在项目文件夹中安装示例与环境配置后的步骤。
（以motrix_anymal_c_locomotion为例)目录结构如下：

motrix_anymal_c_locomotion/
├── motrixsim-docs
│   └── examples/
│       └── assets/
│           └── boston_dynamics_spot/
│               └── scene.xml
├── hello_motrixsim.py
├── pyproject.toml
└── ...
  1. 创建第一个仿真程序
    创建一个名为 hello_motrixsim.py 的文件：
# ============================
# MotrixSim 基础仿真与渲染示例
# ============================# 1. 导入 MotrixSim 库，并使用别名 'mx' 简化调用
import motrixsim as mx# 2. 加载模型文件（场景描述文件，通常为 MJCF/XML 格式）
#    该文件定义了机器人的物理属性（质量、关节、碰撞体）以及可视化网格。
#    路径指向波士顿动力 Spot 机器人的场景文件（需确保文件存在）。
model = mx.load_model("motrixsim-docs/examples/assets/boston_dynamics_spot/scene.xml")# 3. 创建一个渲染器上下文管理器
#    RenderApp 负责打开图形窗口并渲染模型。
#    参数 "warn" 表示只输出警告级别以上的日志（减少控制台输出）。
#    使用 with 语句可以自动管理渲染器的资源（启动与关闭）。
print("1. 模型加载完成，准备创建渲染器...")
with mx.render.RenderApp("warn") as render:print("2. 渲染器已创建，准备 launch...")# 4. 将模型加载到渲染器中，创建对应的可视化实体render.launch(model)print("3. launch 完成，创建 SceneData...")# 5. 创建场景数据对象，用于存储物理仿真的状态（位置、速度等）#    该对象会在每一帧被更新，并传递给渲染器进行同步。data = mx.SceneData(model)print("4. 进入主循环...")# 6. 无限循环运行物理仿真与渲染同步while True:# 6.1 执行一步物理仿真（根据当前状态更新位置、速度等）model.step(data)# 6.2 将最新的物理数据同步到渲染器，更新显示画面render.sync(data)# 注意：
# - 程序会一直运行，直到用户关闭渲染窗口或强制终止（Ctrl+C）。
# - 如果模型文件路径错误或缺少依赖，可能会在 load_model 或 launch 阶段抛出异常。
# - 对于四足机器人（如 ANYmal C），通常需要配合控制算法（如 RL 策略）来生成动作，
#   本例仅演示基本的物理仿真与可视化，未包含主动控制逻辑。
  1. 运行第一个仿真程序
    在motrix_anymal_c_locomotion文件夹中打开终端运行：
uv run hello_motrixsim.py

若出现仿真窗口显示Spot 四足机器人在重力作用下自然站立并保持平衡，说明已经成功运行了一个MotrixSim仿真程序。

🧠 第二部分：安装 MotrixLab

MotrixLab 是配套的机器学习框架：

  1. 克隆项目仓库
    转到项目目录，如：
cd motrix_anymal_c_locomotion

从 GitHub 克隆官方仓库，并进入项目目录：

git clone https://github.com/Motphys/MotrixLab.git
cd MotrixLab
  1. 安装依赖并同步环境
    执行以下命令安装项目所需的所有依赖：
# 安装所有依赖
uv sync --all-packages --all-extras

🏃‍♂️ 运行一个MotrixLab任务

通过过演示一个简单例子 - 加载倒立摆并进行训练展示 MotrixLab 的工作流程：
在MotrixLab目录下打开终端执行以下命令

  1. 环境预览
uv run scripts/view.py --env cartpole

这将打开一个可视化窗口，显示倒立摆的物理仿真环境
2. 训练模型
开始训练倒立摆平衡任务：

uv run scripts/train.py --env cartpole

若需要在训练过程中观察模型的学习过程，可以使用可视化渲染：

uv run scripts/train.py --env cartpole --render

如果电脑没有GPU，可能无法正确可视化渲染：
原因：由于 TensorFlow 在初始化时尝试加载不兼容的 CUDA 库或动态链接失败导致的。系统没有 GPU，环境缺少 CUDA 运行时库， TensorFlow 的默认安装在某些环境下仍可能触发底层崩溃。
解决方法：替换 TensorFlow 包为 CPU 专用版。
在MotrixLab文件中打开终端，输入：

uv pip uninstall tensorflow tensorboard
uv pip install tensorflow-cpu==2.13.0

之后正常运行 uv run scripts/train.py --env cartpole --render即可

TensorFlow
TensorFlow 的主要作用是提供一个端到端的机器学习开发平台，用于构建、训练和部署深度学习模型。它支持自动微分、大规模分布式计算（CPU/GPU/TPU），并内置 Keras 高层 API 简化模型搭建。此外，TensorFlow 生态包含 TensorBoard（训练可视化）、TF Serving（模型服务）、TF Lite（移动端部署）和 TF.js（浏览器运行），覆盖从研究到生产的全流程。

使用具有GPU的电脑可能在可视化仿真出现卡住的现象：
原因：在运行 MotrixLab 训练脚本时，默认使用的是 JAX 作为训练后端（--train-backend jax）。实验的系统环境为：CUDA 版本：12.8与驱动版本：570.211.01。但是JAX 官方预编译的二进制版本最高只支持到 CUDA 12.5 或 12.6，对 CUDA 12.8 的兼容性不完整，导致在编译计算图时发生 段错误（Segmentation fault），程序崩溃。
解决方法： PyTorch 对较新 CUDA 版本的支持通常更好，因此切换到 PyTorch 后端后，训练能够正常进行。在执行训练命令时，显式指定--train-backend torch，强制使用 PyTorch 作为训练后端：

uv run scripts/train.py --env cartpole --render --train-backend torch

注：如果需要查看脚本支持的所有参数，可运行：

uv run scripts/train.py --helpfull
  1. 测试训练好的模型
uv run scripts/play.py --env cartpole

系统会自动在 runs/cartpole/ 目录(训练完成后自动生成）下寻找最新、最佳的策略文件。通常情况下，使用自动发现功能即可。

附：scripts/train.py 的参数说明表格：

参数 说明 默认值 可选值 / 类型
--env 要训练的环境 'cartpole' 字符串
--num-envs 训练时并行环境数量 2048 整数
--[no]rand-seed 是否生成随机种子 false 布尔（--rand-seed 启用）
--[no]render 是否渲染环境 false 布尔（--render 启用）
--rllib 强化学习框架 'skrl' skrl / rslrl
--seed 用于复现的随机种子 (无) 整数
--sim-backend 使用的仿真后端 自动选择 字符串（如 jax / torch? 实际由脚本决定）
--train-backend 训练后端 (无) jax / torch
http://www.jsqmd.com/news/657235/

相关文章：

  • Wand-Enhancer完全指南：免费解锁WeMod高级功能的终极解决方案
  • 算法训练营第四天|59.螺旋矩阵II
  • 亲测6款AI生成器，20分钟搞定6万字论文带数据分析 - 麟书学长
  • 2026年OpenClaw怎么搭建？3分钟腾讯云零技术安装OpenClaw及百炼Coding Plan步骤
  • 中启联信科技集团（数据要素全链路服务商｜AI训练+数据资产入表双场景适配）
  • 鲸采云SRM深度测评：如何做到降低采购风险60%、采购成本35%？
  • 源雀SCRM商业版发布AI SKILLS：专属AI驱动的开发新范式
  • 保姆级教程：用Charades数据集复现行为识别模型（附PyTorch代码与避坑指南）
  • OpenClaw 2.6.2 Windows11 一键部署：一次安装，永久使用
  • 别再手动拖拽了！用Claude Desktop + Unity MCP插件，让AI帮你自动创建游戏场景（保姆级避坑指南）
  • 【语音信号处理】从可视化到特征：时域、频域、语谱图与MFCC的实战解析与代码实现
  • tapd-ai-cli——专为 AI Agent 打造的 TAPD 命令行工具
  • 手把手教你用Matlab实现KELM回归预测：从数据归一化到结果可视化全流程
  • 20260417
  • Unity C#脚本控制平滑移动——MoveTowards()方法的进阶应用与性能优化
  • 装修公司怎么选？2026设计施工一体公司推荐与避坑指南 - 品牌策略主理人
  • 保姆级教程：用C++在PX4飞控上实现无人机航线跟踪（Cross-track Error算法详解）
  • AI应用开发必看：Token、Skill、Agent、RAG四概念辨析，手把手教你打造可测知识问答Agent！
  • 如何5分钟完成DOL游戏汉化美化：终极整合包使用指南
  • Unity物理引擎实战：用GJK+EPA算法搞定2D碰撞后的物体分离（附完整C#源码）
  • WereYouLast
  • 差分式升压逆变器MATLAB仿真模型设计——实现110V/50Hz输出电压与THD＜5%
  • OpenEMS开源能源管理系统：构建智能能源解决方案的完整指南
  • 海外短视频竞争升级跨境卖家如何提升内容吸引力
  • Windows 11 Android子系统终极指南：3种方法快速部署跨平台应用生态
  • flask》》多线程并发数据安全问题 threading.local werkzeug.local.Local
  • Android手把手编写儿童手机远程监控App之JAVA基础
  • 新建了一个微信群深圳技术交流群
  • CISSP 域6知识点 安全评估与测试策略
  • 测试深度策略