# Superspider RL 六足蜘蛛机器人强化学习项目,18 个主动关节。最终路线:**PPO 平地预训练 → 盲走台阶微调 → 高度图教师 → 本体感知学生蒸馏**。 ## 文件 | 内容 | 位置 | | --- | --- | | 最终 URDF、STL | `models/superspider/` | | RL 用 MJCF、网格 | `models/superspider_mjlab/` | | 环境、奖励、蒸馏配置 | `src/tasks/velocity/config/custom_dog/dogs/superspider.py` | | 键盘控制 | `scripts/superspider_teleop.py` | | 策略回放 | `scripts/play.py` | | 训练入口 | `scripts/train_stage.py` | | 训练方法 | [TRAINING.md](TRAINING.md) | | 权重及 SHA-256 | `checkpoints/` | ## 安装 Linux、Python 3.12 + venv;训练使用 NVIDIA CUDA GPU,图形窗口需要桌面环境。MuJoCo 与 mujoco-warp 固定为 3.5.0,完整依赖在 requirements.txt。 ```bash git clone https://gitea.robotquan.com/liyang/superspider-rl.git cd superspider-rl python3.12 -m venv .venv source .venv/bin/activate python -m pip install . ``` 普通安装已包含运行脚本、URDF/MJCF、网格、五份权重与校验清单;无需保持源码目录作为当前目录。开发时可改用 `python -m pip install -e .`。 也可构建 wheel 后交付安装: ```bash python -m pip wheel --no-deps -w dist . python -m pip install dist/superspider_rl-0.1.1-py3-none-any.whl ``` 安装后提供 `superspider-teleop`、`superspider-play`、`superspider-train`、`superspider-evaluate`、`superspider-verify`。以下控制台命令可在任意可写目录执行;日志和评测输出写入当前目录。原 `python -m scripts.*` 入口仍兼容。 ## 控制与回放 默认控制最终学生策略: ```bash superspider-teleop ``` W/S 或上下键增减前进速度,A/D 或左右键转向,Q/E 横移,C 清除转向和横移,X/空格将速度指令归零,L 切换转向保持。学生训练范围为前进 0.05–0.40 m/s、横移 ±0.05 m/s、转向 ±0.30 rad/s;另提供零速指令,零速稳定性不由训练范围保证。 平地策略支持前后移动: ```bash superspider-teleop --task Custom-Superspider-Flat --checkpoint-file flat_5999.pt ``` 自动回放最终学生(无桌面可加 `--viewer viser`): ```bash superspider-play Custom-Superspider-Stairs-Distill --checkpoint-file student_5999.pt --num-envs 1 ``` ## 权重 | 文件 | 用途 | | --- | --- | | flat_5999.pt | 平地 PPO | | blind_10000.pt | 盲走台阶 PPO,教师初始化来源 | | teacher_3800.pt | 318 维高度图教师,蒸馏来源 | | student_1600.pt | 历史单级台阶评测使用的学生快照 | | student_5999.pt | 最后保存的学生权重,默认回放版本 | 学生输入 65 维本体状态、输出 18 维关节位置动作。最后保存不等于评测最优;历史 9 cm 单级台阶结果对应 1600 快照,不能直接归给 5999 快照或连续楼梯。 ## 模型与适用范围 URDF 保留最终建模文件。训练通过 MJCF 与任务后处理设置 100 mm 站高、HTD-45H 参数、4.41 N·m 力矩限幅和站姿中心 ±40° 的 coxa 限位。有效训练参数以任务配置为准,不能只读 URDF 替代训练配置。舵机质量仍沿用 CAD 值,待实物核验。 控制脚本运行 MuJoCo 仿真,不包含串口舵机驱动或已验证的真机部署。零速度指令不是硬件急停。 模型与策略检查: ```bash MUJOCO_GL=egl superspider-verify ``` 来源与许可见 [NOTICE.md](NOTICE.md)。 验证状态:普通 wheel 已在独立 venv 安装,并从源码目录之外完成 URDF/MJCF 编译、网格引用、5 份权重哈希与严格加载、每份策略 8 个 CPU 仿真步;运行入口与评测判据测试通过。本轮复用已有匹配版本的大型依赖,未声明全新机器从零安装通过。详情见 [validation/DELIVERY.md](validation/DELIVERY.md)。本轮验收范围为安装和运行,不包含完整台阶能力评测。