Huy-Quang-Dao/instantTrack

项目介绍

InstantTrack 是一个面向仿真 Unitree G1 人形机器人的全身运动跟踪训练代码库。它沿用 SuperMimic 的思路——用一个可微世界模型，在想象 rollout 中反向传播来训练策略——再叠加 InstantMimic 的训练循环工程优化和若干算法改动。每一项改动都以命令行开关形式提供，因此基线和每个增量共享同一套仿真器、MDP、奖励、终止条件、域随机化和评估器。

主配置 v1.2 用单个策略覆盖全部 40 段 LAFAN1 动作，在单张 RTX 5090 上、5 个随机种子的平均训练时间为 0.12 h，即可达到评估目标（归一化回报 ≥ 0.82 且 0/40 失败片段，连续 3 个检查点保持）；对照的是作者自己复现的 SuperMimic + EMA，为 0.55 h README 数据。文中 4.7× 的比较基准是这个同机复现版本，而不是 SuperMimic 论文在 H100 上的数字。

适用对象是想训练、做消融或复现人形机器人跟踪策略的机器人强化学习研究者和工程师。它不是部署栈：范围内没有 sim-to-real 实验，也没有更大规模的动作库。

快速开始

环境要求为 Linux x86_64、带 CUDA 12.8 驱动的 NVIDIA GPU（测试用 RTX 5090）、uv、git、curl；ffmpeg 只在渲染视频时需要。环境与数据约占 10 GB 磁盘，每次 0.75 h 训练另需约 2 GB 检查点空间。

git clone https://github.com/Huy-Quang-Dao/instantTrack.git
cd instantTrack
uv sync                          # mjlab、MuJoCo Warp、Warp、torch 2.9.0（CUDA 12.8）
tools/download_data.sh           # LAFAN1 G1 重定向动作（40 段）+ G1 描述 -> data/
uv run python tools/test_env.py  # 自检：FK 与仿真器一致、状态往返、参考播放

数据脚本从 Hugging Face 数据集下载 G1 重定向后的 LAFAN1 动作和机器人描述，并把 URDF 转换为 MJCF；动作数据不在仓库内分发 说明。

随后用主预设训练并评估检查点：

scripts/train.sh instanttrack it_s0 --seed 0 --max_hours 0.75

该脚本以 v1.2 开关运行 python -m instanttrack.train，然后调用 tools/eval_batch.py。单次运行写入 logs/it_s0/：train_log.csv、每 3 分钟与每 2000 次迭代的检查点、args.json 和 stdout.log。要复现对比表格，scripts/reproduce_main.sh 以 3 个种子、每个 0.75 h 运行 SuperMimic + EMA 和 InstantTrack（约 5 h），再由 tools/make_report.py 从 results/runs/ 重建表格和图 复现步骤。

也可以绕过脚本直接训练：

uv run python -m instanttrack.train --log_dir logs/my_run --seed 0 --max_hours 0.75 \
  --pi_ema 0.995 --no_sync --fused_adam --fused_rot --compile_more --lr 4e-4 --wm_batches 5 \
  --wm_hidden 1024,1024,1024 --fail_reset 0.3 --contact_reward 0.25 --ref_residual 1.0 \
  --muon --cuda_graph --batch_goal_enc --enc_hidden 1024,512,256 --dec_hidden 1024,512,256

--cuda_graph 需要同时给出 --no_sync --fused_adam，并且需要 CUDA GPU；它会在仅训练世界模型的预热迭代后捕获两个更新阶段，捕获的几秒计入训练时间 训练说明。

使用约束

• 硬件与平台：训练时间是在独占一张 RTX 5090、4096 个并行环境的条件下测得的；同一张 GPU 上再跑一个进程会让循环慢 1.5–2×。仅支持 Linux x86_64。
• 计时可复现性：检查点每 3 分钟保存一次，因此报告的时间以 0.05 h 为粒度；GPU 运行不是逐位可复现的，同一随机种子重跑曾让某配置从 0.30 h 变为 0.34 h。
• 基准范围：只覆盖仿真中的 Unitree G1 和 40 段 LAFAN1 动作，评估不做域随机化、不加推力，没有 sim-to-real 验证。
• 已知短板：全局根漂移仍高于 SuperMimic + EMA 基线（v1.2 在 1.5 h 为 52 cm，基线为 49–54 cm）；较难的片段在首次达标后可能回退（v1.2 种子 4 的 jumps1_subject2）；接触奖励以约 0.03 h 的达标时间和约 0.007 的回报为代价，换取更好的接触指标。
• CUDA graph 下的 Muon：Muon 的学习率是 Python 浮点数，在图捕获时固定，不跟随余弦调度；在 v1.2 各次运行中最多高于调度值 8%。
• 许可：代码采用 MIT。LAFAN1 动作为 CC BY-NC-ND 4.0，仓库不再分发；由其派生的 GIF、视频和检查点仅限非商业研究与展示，不在 MIT 许可范围内 署名与许可。

HotRepo 点评

HotRepo 数据中没有这个仓库的日榜名次，也没有相关讨论；它只出现在 2026-11-03 的 Python 新项目记录中，约五小时内新增 13 个 Star，总数从 100 升到 113。这个时间窗太短，只能说明早期有关注，不足以判断趋势。更值得注意的是文档本身：README 公布了逐种子达标时间、消融阶梯、无效改动的清单和每次运行的日志，并明确说明基线是作者自己复现的 SuperMimic，且早期提速很大一部分来自 EMA 而不是 InstantTrack 本身。对评估速度声明的读者来说，这种交代比 Star 数更有参考价值。