README_CN.md

🧬 GeneLab

面向 RL 与机器人研究的 Isaac Lab 风格 API —— 由 Genesis 提供仿真后端。

熟悉的注册机器人 / 环境 / 任务、manager-based MDP 配置与 Typer CLI， 以 Genesis 作为轻量仿真后端 —— 无 USD/Kit，无厂商锁定。

English · 文档 · 示例

---

✨ 特性

• Isaac Lab 风格 API —— 注册机器人 / 环境 / 任务，配合 manager-based 的 actions、observations、rewards、events、terminations。
• Genesis 后端 —— 快、轻量；无 USD/Kit，无 NVIDIA 锁定。
• 三个 RL 后端 —— rsl_rl、skrl、stable_baselines3，按 agent 配置类型自动分派。
• 开箱即用的 CLI —— train / play / eval / export / benchmark，支持多 seed、多 GPU。
• Asset zoo —— Franka、Unitree G1 / Go1 / H1、ANYmal-C、UR10e、cartpole …… 按需下载。
• 可扩展 —— 下游项目通过干净的扩展 API 注册自己的机器人、环境与任务。

🚀 快速开始

uv sync --extra torch-cu128          # 按你的 CUDA 选 torch extra（见下）
source .venv/bin/activate            # Windows：.venv\Scripts\activate
genelab cache                        # 创建本地 仿真 / 绘图 缓存目录
genelab list tasks                   # 看看注册了哪些任务
genelab train GeneLab-Inverted-Pendulum-v0 --max_iterations 150
genelab play  GeneLab-Inverted-Pendulum-v0 --vis

uv sync 创建项目 venv 并安装 GeneLab + uv.lock 锁定的依赖。文档统一使用裸 genelab （以及裸 python），而不是 uv run genelab。uv run 会在每次执行前重新同步环境，而 torch-* extra 之间互斥、且不在默认同步集合中，于是每次 uv run 都会卸载并重装 torch、并改写 你选定的 extra。请先激活 .venv（如上），或者——若不想激活——给一次性命令加上 uv run --no-sync 前缀来跳过这次重新同步。

📦 安装

环境要求：Python ≥ 3.12 与 uv。

只能选一个 torch-* extra —— 它们互斥：

Extra	硬件目标
torch-cpu	纯 CPU 或非 NVIDIA 开发机
torch-cu126	NVIDIA，CUDA 12.6 驱动
torch-cu128	NVIDIA，CUDA 12.8 驱动
torch-cu130	NVIDIA，CUDA 13.0 驱动

uv sync --extra torch-cpu        # 上面四选一

需要 PyTorch ≥ 2.8。 旧版本 torch 会在 import 时报 'torch<2.8.0' is not supported， 且可能破坏 Genesis 运行假设。所有 torch-* extra 都 pin 了 torch>=2.8.0，uv sync 会自动拉 兼容的 wheel。PyTorch 只在 cpu / cu126 / cu128 / cu130 这几个 index 发布 2.8+ wheel （更旧的 cu118 / cu121 / cu124 有意不作为 extra 提供）。环境里已有旧 torch 时用 uv sync --reinstall-package torch --extra torch-cuXXX 刷新。

🖥️ CLI

genelab --help
genelab list robots          # 已注册的机器人
genelab list envs            # 已注册的环境
genelab list tasks           # 已注册的任务
genelab info  <task>         # 任务详情 + 可覆盖的配置路径
genelab train <task> …       # 训练（后端由任务的 agent 配置决定）
genelab play  <task> …       # rollout：--agent zero | random | trained
genelab eval  <task> <ckpt>  # 确定性评估 → eval.json
genelab export <task> <ckpt> # 导出策略 → TorchScript / ONNX

🧩 核心 API

• genelab.registry —— 注册表、注册辅助函数与扩展加载。
• genelab.configs —— 可复用的 dataclass 配置，包括 ManagerBasedEnvCfg 与 TaskCfg。
• genelab.lab —— 注册表与 manager-based 环境原语的公开 API 门面。
• genelab.envs、genelab.robots、genelab.tasks —— 注册表辅助的轻量核心命名空间。
• genelab.actuator、genelab.entity、genelab.scene、genelab.sensor、genelab.terrains、 genelab.rl —— 机器人研究代码的扩展命名空间。
• genelab.asset_zoo —— 自带示例机器人（g1、go1、anymal-c、franka、cartpole ……）。 通过 ROBOTS 注册表取用（ROBOTS.get("g1")()），或直接 import （from genelab.asset_zoo import UnitreeG1Cfg）。

下游项目放在各自的 Python 包里，通过 GeneLab 的注册表与扩展钩子注册机器人、环境和任务。 生成一个新脚手架：

genelab project new my_robot_project

最小模板见 examples/external_project/。

✅ 验证

python -c "import genelab, genesis; print(genelab.__version__, genesis.__version__)"
python -c "from genelab.lab import ManagerBasedEnvCfg; print(ManagerBasedEnvCfg.__name__)"
pytest
ruff check && ruff format --check
pyright

同步某个 torch-* extra 后，验证选中的 PyTorch 构建：

python -c "import torch; print(torch.__version__, torch.version.cuda)"

🛠️ 故障排查

GPU 空转 / 训练异常慢

SimulationCfg.gpu 默认是 False（CPU 后端）。CPU 后端下物理在 CPU 上步进、而 policy/张量 在 GPU 上 —— GPU 几乎空转，训练可能慢 ~50–100×（接触多的任务如 Unitree G1 受影响最大）。 请在任务的 SimulationCfg 里设 gpu=True。若训练时 nvidia-smi 看到 GPU 占用接近 0%，基本就是 这个原因。更多见 docs/best-practices/reference-runs。

Hopper GPU（H100 / H200，SM 90）

Genesis 自带的 Quadrants 预编译 fatbin 在 graph_do_while 分派路径上不含 SM 90，所以任何任务在 H100 / H200 上构建场景时会报：

RuntimeError: Failed to load graph_do_while condition kernel fatbin (CUDA error 200).
This SM (90) may not be included in the fatbin

关闭 graph 分派：

export QD_GRAPH=0                     # 整个会话
QD_GRAPH=0 genelab train …     # 或只针对单条命令

注意：QD_GRAPH=0 会关掉 CUDA-graph 批处理，明显拖慢接触多的仿真 —— 重的 locomotion 训练建议用非 Hopper 卡（Ada / Ampere）。

Wayland 下 viewer 无法渲染（--vis）：makeCurrent() failed / eglError: 3000

在 Wayland 会话下，Genesis viewer 的 Qt QOpenGLWidget 可能无法在合成器上激活其 EGL 上下文，于是 --vis 打开的窗口不渲染，并在终端刷屏：

QWaylandGLContext::makeCurrent: eglError: 3000
QOpenGLWidget: Failed to make context current
qt.qpa.backingstore: composeAndFlush: makeCurrent() failed

（eglError: 3000 实际是 EGL_SUCCESS —— EGL 没报具体错误码，只是上下文激活失败；这是 Qt OpenGL 在 Wayland 上的经典上下文共享问题。）强制 Qt 走 XWayland（X11 后端），其 GLX/EGL 行为更稳定：

export QT_QPA_PLATFORM=xcb                          # 整个会话
QT_QPA_PLATFORM=xcb genelab play <task> --vis       # 或只针对单条命令

若仍失败，再关掉 Qt 自动缩放（QT_AUTO_SCREEN_SCALE_FACTOR=0），或在混合显卡笔记本上锁定独显 （__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia）。同时出现的 QFont::fromString 和 dubious mass 行无害，可忽略。

---

_{文档 · 示例 · 基于 Genesis}