# openduck_train

**Repository Path**: huahuaze/openduck_train

## Basic Information

- **Project Name**: openduck_train
- **Description**: openduck-playgournd
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Open Duck Playground 安装、训练与测试说明

本文档基于当前项目的 [requirements.txt](file:///root/Desktop/Open_Duck_Playground-main/requirements.txt) 和 [README.md](file:///root/Desktop/Open_Duck_Playground-main/README.md) 整理，完整说明如何使用 `pip` 完成环境安装、训练、继续训练、测试与可视化。

本文档不使用 `uv`，全部采用 `pip` 安装方式。

## 1. 环境说明

- 操作系统：Linux
- Python 版本：`3.11.15`
- 建议 Python 大版本：`3.11.x`
- 项目根目录：`Open_Duck_Playground-main`

当前验证通过的关键依赖版本包括：

- `jax==0.5.1`
- `jaxlib==0.5.1`
- `jax-cuda12-plugin==0.5.1`
- `jax-cuda12-pjrt==0.5.1`
- `mujoco==3.2.7`
- `mujoco-mjx==3.2.7`
- `brax==0.12.1`
- `flax==0.10.4`
- `tensorflow==2.21.0`
- `onnxruntime==1.27.0`
- `isaaclab==2.3.2.post1`
- `isaacsim==5.1.0.0`

所有 Python 包版本都已经固定在 `requirements.txt` 中。

## 2. 获取项目代码

如果你拿到的是打包好的压缩包：

```bash
tar -xzf Open_Duck_Playground-main.tar.gz
cd Open_Duck_Playground-main
```

如果你已经有源码目录，直接进入项目根目录即可：

```bash
cd /path/to/Open_Duck_Playground-main
```

## 3. 准备 `mujoco_menagerie`

### 3.1 为什么要单独说明

`mujoco_menagerie` 在某些机器上直接拉取最新版本时可能会报错，因此建议使用固定版本。

注意，这里优先以当前 `pip` 安装的 `mujoco_playground` 自带的 `external_deps/mujoco_menagerie` 为准，而不是项目根目录里单独放一个 `mujoco_menagerie` 目录。

当前验证通过的 `mujoco_menagerie` 提交号是：

```text
14ceccf557cc47240202f2354d684eca58ff8de4
```

### 3.2 正确处理方式

如果你使用的是当前这套 `pip` 环境，`mujoco_menagerie` 一般位于 `mujoco_playground` 的安装目录下面：

```text
/opt/conda/envs/isaaclab/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
```

你给出的实际可用版本就是在这个目录下切换得到的：

```bash
cd /opt/conda/envs/isaaclab/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
git checkout 14ceccf557cc47240202f2354d684eca58ff8de4
```

### 3.3 要改哪个位置

这里要修改的是 `pip` 安装目录中的：

```text
/opt/conda/envs/isaaclab/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
```

不是优先修改项目根目录下的：

```text
Open_Duck_Playground-main/mujoco_menagerie
```

也就是说，对当前环境来说，真正生效的位置应当是：

```text
<python环境>/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
```

在你当前环境下，具体就是：

```text
/opt/conda/envs/isaaclab/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
```

### 3.4 如何确认是否切对版本

执行：

```bash
cd /opt/conda/envs/isaaclab/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
git rev-parse HEAD
```

如果输出是：

```text
14ceccf557cc47240202f2354d684eca58ff8de4
```

说明版本正确。

## 4. 创建 Python 虚拟环境

建议使用 Python `3.11` 创建独立虚拟环境：

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python --version
```

然后先升级 `pip`：

```bash
pip install --upgrade pip
```

## 5. 安装固定版本依赖

在项目根目录执行：

```bash
pip install -r requirements.txt
```

说明：

- `requirements.txt` 中已经固定了所有包的版本号。
- 文件中包含 `-e .`，因此当前项目本身也会以 editable 模式安装。
- 目标机器需要具备与这些包兼容的系统环境，尤其是：
  - Linux
  - Python `3.11`
  - NVIDIA 驱动
  - CUDA 12 兼容环境
  - Isaac Sim 运行所需环境

## 6. 验证安装是否成功

先验证关键包是否可以正常导入：

```bash
python -c "import jax, mujoco, brax, onnxruntime; print(jax.__version__, mujoco.__version__, brax.__version__, onnxruntime.__version__)"
```

再验证项目模块是否可以正常导入：

```bash
python -c "import playground; print('playground import ok')"
```

## 7. 参考运动数据 `polynomial_coefficients.pkl`

对于基于 imitation reward 的 walking 任务，项目需要下面这个文件：

```text
playground/open_duck_mini_v2/data/polynomial_coefficients.pkl
```

如果你需要重新生成，原始 README 里给出的参考工程是：

- <https://github.com/apirrone/Open_Duck_reference_motion_generator>

生成完之后，请把文件拷贝到这里：

```text
Open_Duck_Playground-main/playground/open_duck_mini_v2/data/polynomial_coefficients.pkl
```

也就是说，最终这个文件必须位于：

```text
playground/open_duck_mini_v2/data/
```

另外，walking 任务当前依赖 `joystick.py` 中启用 imitation reward。

相关位置在：

```text
playground/open_duck_mini_v2/joystick.py
```

## 8. 开始训练

### 8.1 基础训练命令

在项目根目录执行：

```bash
python -m playground.open_duck_mini_v2.runner \
  --task flat_terrain_backlash \
  --num_timesteps 300000000 \
  --output_dir checkpoints_test
```

说明：

- 默认环境是 `joystick`，它对应 walking policy。
- 当前项目里已经跑通的任务是 `flat_terrain_backlash`。
- 训练输出会写入 `--output_dir` 指定目录。

### 8.2 训练输出内容

训练完成后，通常会生成以下内容：

- Orbax checkpoint 目录
- ONNX 模型文件
- TensorBoard 事件文件

典型目录结构如下：

```text
checkpoints_test/
  2026_07_20_205503_300482560/
  2026_07_20_205503_300482560.onnx
  events.out.tfevents...
```

## 9. 从 checkpoint 继续训练

如果已经有一个保存好的 checkpoint 目录，可以继续训练：

```bash
python -m playground.open_duck_mini_v2.runner \
  --task flat_terrain_backlash \
  --num_timesteps 300000000 \
  --output_dir checkpoints_test \
  --restore_checkpoint_path /path/to/checkpoints_test/<checkpoint_dir>
```

示例：

```bash
python -m playground.open_duck_mini_v2.runner \
  --task flat_terrain_backlash \
  --num_timesteps 300000000 \
  --output_dir checkpoints_test \
  --restore_checkpoint_path /root/Desktop/Open_Duck_Playground-main/checkpoints_test/2026_07_20_205503_300482560
```

## 10. 查看 TensorBoard

如果想查看训练曲线：

```bash
tensorboard --logdir checkpoints_test
```

启动后在浏览器中打开 TensorBoard 提示的本地地址即可。

## 11. 测试与可视化

### 11.1 测试 walking ONNX 模型

训练结束后，可以使用导出的 `.onnx` 模型在 MuJoCo 中做可视化测试：

```bash
python -m playground.open_duck_mini_v2.mujoco_infer \
  -o /path/to/model.onnx \
  --model_path /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/xmls/scene_flat_terrain_backlash.xml \
  --reference_data /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/data/polynomial_coefficients.pkl
```

当前已经验证通过的 walking 模型示例：

```bash
python -m playground.open_duck_mini_v2.mujoco_infer \
  -o /root/Desktop/Open_Duck_Playground-main/checkpoints_test/2026_07_20_205503_300482560.onnx \
  --model_path /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/xmls/scene_flat_terrain_backlash.xml \
  --reference_data /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/data/polynomial_coefficients.pkl
```

### 11.2 为什么测试还需要这些参数

这几个参数的作用分别是：

- `-o`
  - 指向导出的 ONNX 策略网络
- `--model_path`
  - 指向测试时使用的 MuJoCo 场景与机器人定义
- `--reference_data`
  - 指向 walking policy 所使用的参考运动系数文件

也就是说，`.onnx` 只保存了策略网络本身，不包含完整的 MuJoCo 场景和参考运动数据，因此测试时仍然需要额外指定这些运行上下文。

### 11.3 Viewer 支持的控制键

当前测试脚本支持：

- 方向键
- `W / S / A / D`
- `Z / E` 转向
- `H` 切换头部控制模式

### 11.4 测试 standing 模型

如果你训练的是 standing policy，那么测试时需要显式加上 `--standing`：

```bash
python -m playground.open_duck_mini_v2.mujoco_infer \
  -o /path/to/standing_model.onnx \
  --model_path /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/xmls/scene_flat_terrain_backlash.xml \
  --standing
```

注意：

- walking 模型不要加 `--standing`
- standing 模型才使用 `--standing`

## 12. ONNX 推理速度测试

如果你只是想测 ONNX 推理是否正常，可以运行：

```bash
python -m playground.common.onnx_infer -o /path/to/model.onnx
```

## 13. 观测数据可视化

如果推理脚本保存了 `mujoco_saved_obs.pkl`，可以使用下面的命令画图查看：

```bash
python -m playground.common.plot_saved_obs -d mujoco_saved_obs.pkl
```

## 14. 常用流程总结

### 14.1 安装

```bash
cd /path/to/Open_Duck_Playground-main
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```

### 14.2 训练

```bash
python -m playground.open_duck_mini_v2.runner \
  --task flat_terrain_backlash \
  --num_timesteps 300000000 \
  --output_dir checkpoints_test
```

### 14.3 可视化测试

```bash
python -m playground.open_duck_mini_v2.mujoco_infer \
  -o /root/Desktop/Open_Duck_Playground-main/checkpoints_test/2026_07_20_205503_300482560.onnx \
  --model_path /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/xmls/scene_flat_terrain_backlash.xml \
  --reference_data /root/Desktop/Open_Duck_Playground-main/playground/open_duck_mini_v2/data/polynomial_coefficients.pkl
```

## 15. 常见问题

### 15.1 JAX CUDA 插件版本不匹配

如果出现 JAX backend 或 PJRT plugin 版本不匹配错误，请重点检查下面四个版本是否严格一致：

- `jax`
- `jaxlib`
- `jax-cuda12-plugin`
- `jax-cuda12-pjrt`

当前验证通过的版本是：

```text
jax==0.5.1
jaxlib==0.5.1
jax-cuda12-plugin==0.5.1
jax-cuda12-pjrt==0.5.1
```

### 15.2 MuJoCo 窗口能打开，但模型不动

请检查以下几项：

- 当前测试的 ONNX 模型是否是 walking 模型
- 是否错误地给 walking 模型加了 `--standing`
- `--model_path` 是否与训练任务匹配
- `--reference_data` 是否指向正确的 `polynomial_coefficients.pkl`

### 15.3 `mujoco_menagerie` 拉取失败

不要直接使用最新版，建议固定到下面这个提交：

```text
14ceccf557cc47240202f2354d684eca58ff8de4
```

对于当前这套 `pip` 环境，建议直接在 `mujoco_playground` 的安装目录里切换：

```bash
cd /opt/conda/envs/isaaclab/lib/python3.11/site-packages/mujoco_playground/external_deps/mujoco_menagerie
git checkout 14ceccf557cc47240202f2354d684eca58ff8de4
```

然后执行：

```bash
git rev-parse HEAD
```

确认输出为：

```text
14ceccf557cc47240202f2354d684eca58ff8de4
```

### 15.4 环境复刻建议

为了尽可能复刻当前环境，建议：

- 使用 Python `3.11`
- 使用当前固定版本的 `requirements.txt`
- 在 Linux 环境下运行
- 保持 NVIDIA 驱动、CUDA 与 Isaac Sim 环境兼容
- 始终在项目根目录使用 `pip install -r requirements.txt`