cyy/RoboGauge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fe35afea22acbe8d2da8bd0c8b1f8edc91f169a0
RoboGauge/README_zh.md
wty-yy fe35afea22 v1.1.4; Add ZMP margin metric
2026-03-23 11:24:00 +08:00

12 KiB
Raw Blame History

RoboGauge

🌎 English | 🇨🇳 中文

本仓库提供一系列强化学习训练的运动控制模型指标, 目标是衡量模型的以下信息, 从而能一定程度预测模型Sim2Real的结果, 避免损坏真机:

  • 鲁棒性: 随机变化地形, 地面类型(环境摩擦、弹性系数), 模型是否能继续稳定控制
  • 稳定性: 电机出力是否合理, 长时间运行是否导致电机过热, 是否出现极端关节位置
  • 控制稳定性及准确性: 对于速度追踪指令, 能否准确追踪; 对于目标点指令, 到达误差大小

能间接地衡量模型部署在真机上的效果, 该流程使用Mujoco进行自动化指标评测, 全部代码基于Python实现.

评估过程展示，四种地形及两种难度展示:

Wave Slope
Stairs Obstacles

支持机器人

机器人型号 机器人类型 速度追踪指令
Unitree go2 四足 ✅

安装

推荐安装python=3.8, 参考PyTorch官网安装2.0以上任意版本, 安装本仓库

git clone https://github.com/wty-yy/RoboGauge.git
cd RoboGauge
pip install -e .

使用方法

直接评测指标

包含Single Pipeline, Multi Pipeline, Level Pipeline, Stress Pipeline四种评测方式, 计算量逐个提升, 可并行加快评估速度, 参考CMD.md中的使用示例

训练异步评估

启动评估客户端，

python robogauge/scripts/server.py

包含如下参数：

  • --port: 服务端口号, 默认9973
  • --num-processes: 评估总进程数, 默认30

客户端robogauge/scripts/client.py会向服务端发送评测请求, 并返回评测结果, 参考下方使用示例

from robogauge.scripts.client import RoboGaugeClient

# Create client and submit a test task
client = RoboGaugeClient(f"http://127.0.0.1:9973")
task_id = client.submit_task(
    model_path=test_payload["model_path"],
    step=test_payload["step"],
    task_name=test_payload["task_name"],
    experiment_name=test_payload["experiment_name"],
    wait_for_server=True
)

# Monitor task status and get results
while True:
    client.monitor_tasks()
    for task_id, resp in client.response_data.items():
        scores = resp['results']['scores']
        print("[RoboGaugeClient]📊 Scores:")
        print(json.dumps(scores, indent=2, ensure_ascii=False))
    client.response_data.clear()
    time.sleep(5)

使用例子：在go2_rl_gym - on_policy_runner.py中的update_robogauge函数

可通过python legged_gym/scripts/train.py --task=xxx --robogauge启动带有评估的训练，会等待客户端启动，结果会在logs/{experiment_name}目录下保存，并绘制tensorboard

环境参数/指标/目标

指标的计算方法是通过在环境中发送固定指令及持续时长, 通过Mujoco获取所需参数并计算.

环境参数

域随机化

所有的评测指标都会先配置相应的域随机化参数, 在随机参数下进行评测, 以下为常用的域随机化参数

参数名称 变量名 范围
电机动作执行随机延迟 action delay <= RL控制间隔
base负重 base mass -1, 0, 1, 2, 3 kg
地面摩擦力 friction 0.2 ~ 1.0 (step 0.1)

地形

  1. 支持legged_gym中的部分地形, 包括: wave, slope, stairs up, stairs down, obstacles, flat, 除flat地形外其他地形可进行难度系数提升
  2. 地面类型 (影响接触摩擦系数, 弹性摩擦系数), 包括: 橡胶地, 木地板, 瓷砖地

地形生成代码：windigal - mujoco_terrains

指标

目前在每个env.step后可度量的指标, 所有指标均要求越大越好, 目前支持:

# 指标名称 Metrics 描述 包含的超参数 归一化系数 变化
1 dof_limits 关节超出软关节范围的大小 软关节范围阈值 总关节变化范围 1-x
2 lin_vel_err 线速度L2误差 NA 总线速度指令范围 1-x
3 ang_vel_err 角速度L2误差 NA 总角速度指令范围 1-x
4 dof_power 电机耗能 缩放系数 100 1-x
5 orientation_stability 机身姿态稳定性 (Roll) NA NA 1-x
6 torque_smoothness 力矩平滑度 缩放系数 30 1-x
7 zmp_margin ZMP裕度 NA 默认状态下对角足端间距 1-x

速度追踪目标

针对在虚实迁移中发现的问题, 整理指标 (metrics) 内容如下:

# 描述 标准化范围 对应真机问题 地形
1 关节出现极端值的比例 关节范围 移动时发生危险的高抬腿行为 Any
2 线速度与指令速度的L2误差 最大线速度指令 移动时可能无法达到指定速度 Any
3 角速度与指令速度的L2误差 最大角速度指令 移动时可能无法达到指定速度 Any
4 高速移动/速度对角突变base高度变化 固定高度 高速移动时机身存在趴低问题, 速度发生对角突变时无法平衡 平地
5 高速移动急停稳定性 固定用时 楼梯上静止时, 关节不稳定 Any

总结速度最总目标 (goals) 如下:

# 目标名称 Goals 描述 reset条件 最大reset次数
1 max_velocity 单一维度的最大线/角速度 每次执行一个方向的指令, 再急停 6
2 diagonal_velocity 对角线速度变化 每次执行一对对角指令 8
3 target_pos_velocity 比例差分控制到达目标位置 到达目标位置或超时 1

创建新任务

评测任务注册在tasks/__init__.py中完成, 包含四个部分:

  • BasePipline: 标准Pipline一般无需修改
  • MujocoConfig: 仿真器配置文件, 一般无需修改
  • BaseGaugeConfig: 指标配置文件, 参考下文创建新指标
  • RobotConfig: 机器人配置文件, 参考下文创建新机器人

新指标

在robogauge/tasks/gauge下创建新的场景、评估指标

新机器人

在robogauge/tasks/robots下创建新机器人、配置控制模型, 参考go2配置

  • go2.py控制模型, 包含观测构建和动作输出两个函数, 继承BaseRobot
  • go2_config.py配置文件, 包含机器人模型xml路径, 控制模型路径, 观测构建参数, 关节映射顺序, 各类缩放系数, 控制频率等

注意事项

导入新机器人/控制模型

  1. 在Robot中创建新的机器人xml文件时, 需包含力矩控制actuator, 传感器sensor - jointpos, jointvel, imu (framequat, gyro, accelerometer), 参考go2.xml, 注意: actuator的顺序需要和joint顺序一致, 该顺序称为mujoco关节顺序
  2. 控制模型相关位置位于RobotConfig.control中, 不同仿真中关节顺序可能不同, 需保证mj2model_dof_indices从mujoco映射到模型训练的关节次序配置正确 (IsaacGym次序和Mujoco相同), 其他模型配置需保持一致

代码架构

目录结构

  • robogauge/：核心 Python 包

    • robogauge/scripts/：可执行入口脚本（运行评测 / 启动服务端）
    • robogauge/tasks/：任务系统（仿真配置 + 指标/场景 + 机器人 + 调度执行）
      • robogauge/tasks/pipeline/：调度与执行层（生命周期、域随机化、多 seed 并行、结果聚合）
      • robogauge/tasks/gauge/：指标层（指令生成、指标计算、结果汇总）
      • robogauge/tasks/robots/：机器人适配层（观测/动作、关节映射、模型加载、控制频率）
      • robogauge/tasks/simulator/：仿真器封装 / 环境接口（MuJoCo 集成、step、状态读取等）
      • robogauge/tasks/custom/：项目自定义扩展与自定义任务
    • robogauge/utils/：工具库（日志、配置/文件处理、统计、数学工具）

  • resources/：仿真静态资源

    • resources/robots/：机器人资源（XML / mesh / 纹理等），按机器人型号组织
    • resources/terrains/：地形资源（如 flat.xml、slope/stairs/wave/obstacle 等）
    • resources/models/：策略/模型资源

  • assets/：文档资源

  • scripts/：实验运行的辅助 shell 脚本

RoboGauge评估框架

说明 框架图
RoboGauge评估框架如右图中三部分组成：
Part A: BasePipeline负责单一评估环境，包含地形、机器人、域随机化、原始指标计算功能
Part B: MultiPipeline通过多进程启动多个BasePipeline，进行多seed评估，LevelPipeline负责调用MultiPipeline寻找最高难度地形
Part C: StressPipeline负责全地形下测试，给出整体RoboGauge评分		 robogauge framework

BasePipeline用于管理仿真sim, 度量器(控制指令, 指标计算)gauge, 机器人运控模型robot三者的调度, 并包含异常处理, 域随机化, 观测噪声的添加.

robogauge_basepipeline

MultiPipeline用于多进程启动不同seed, 域随机化参数下的BasePipeline, 并合并结果文件.

LevelPipeline对于当前的环境配置, 找到环境地形下模型能稳定通过(三个seed均通过)的最高地形难度.

robogauge_levelpipeline

可能的报错

Mujoco OpenGL Context Error

mujoco.FatalError: an OpenGL platform library has not been loaded into this process, this most likely means that a valid OpenGL context has not been created before mjr_makeContext was called 问题原因: Mujoco在无头模式下无法创建OpenGL上下文 解决方案: 在robogauge/scripts/run.py和robogauge/scripts/server.py中, 将os.environ['MUJOCO_GL']设置为egl(GPU)或osmesa(CPU, 慢)

测试

在AMD EPYC 7763 64-Core Processor (3.09 GHz)进行StressPipeline测试64进程，评估63个任务总用时2'46"，指令为CMD - stress pipeline + --num-processes 64

https://github.com/user-attachments/assets/7e19d831-1fc9-49db-99e0-c83cddddfb0b

致谢

感谢@windigal地形生成及视频剪辑

引用

如果觉得我们的工作有帮助，请引用：

@article{wu2026robogauge,
      title={Toward Reliable Sim-to-Real Predictability for MoE-based Robust Quadrupedal Locomotion}, 
      author={Tianyang Wu and Hanwei Guo and Yuhang Wang and Junshu Yang and Xinyang Sui and Jiayi Xie and Xingyu Chen and Zeyang Liu and Xuguang Lan},
      year={2026},
      journal={arXiv preprint arXiv:2602.00678},
      url={https://arxiv.org/abs/2602.00678}, 
}
Reference in New Issue View Git Blame Copy Permalink