Work: SAC/MuJoCo 单卡 collector CPU 利用率仅 ~48%——BatchEnvPool 默认 2×CPU 线程超订 + 串行 host 相占 1/3 墙钟

[TATP-233]

Work type: benchmark / perf　Area: mujoco　规模预估: Small（选项 A：1–2 文件，≤50 行手写）

1. 一句话问题

单卡 sac + g1_motion_tracking + mujoco、algo.num_envs=4096 稳态训练时整机 CPU 占用只有 ~48%：MuJoCo BatchEnvPool 默认起 2×cpu_count 个 worker（本机 64 线程 / 16 物理核），物理相在 ~16–20 核即被内存带宽饱和，同时每个 collector cycle 约 1/3 墙钟花在只用 1–4 核的串行 host 相（update_state / reset_done / replay 写入 / 等 learner 动作），两者叠加把平均利用率结构性拉到 50% 以下。

2. 为什么现在做（实测证据）

机器：Xeon w5-3435X（16 物理 / 32 逻辑核）+ RTX 6000 Ada；commit f734cabe（基线分支 dev/issue-1304-motion-numba-body-state）。
复现：uv run train --algo sac --task g1_motion_tracking --sim mujoco algo.num_envs=4096（诊断时加 training.trace_enabled=true）。

稳态训练（400 iter，cycle 77.2ms，26540 steps/s）：

证据	数值
/proc/stat 整机 CPU	47.5–49.2%
collector 进程	~14.3 核（102 线程）
learner 进程	~0.5 核；每 iter 等 collector 数据 43.2ms，自身更新 38.0ms（与 collector env step 重叠）
collector cycle 构成	env_step 72.7ms（94%）+ 等 learner 动作 7.7ms + replay 写入 2.0ms

env.step 分相归因（独立进程，4096 envs，随机动作 → reset 偏重，150 步均值；绝对值与真实训练不同，看比例与核数）：

配置	backend_step	update_state	reset_done	整步
默认 64 线程	78.5ms @ 20.6 核	20.7ms @ 1.8 核	11.8ms @ 4.1 核	113.2ms @ 15.0 核
32 线程（cpu_ids=0–31）	59.5ms @ 27.2 核	12.3ms @ 1.9 核	9.1ms @ 3.7 核	82.2ms @ 20.4 核，steps/s +38%

pool 裸测（G1 scene_flat.xml，4096 envs × 3 substeps，无 env 语义）：

nthread	64 默认不绑定	32 不绑定	32 pinned	24 pinned	16 pinned	8 pinned
ms/step	77.6	69.9	69.7	72.9	73.2	141.7
实占核	25.1	29.9	30.3	23.6	15.8	8.0

结论：

• 收益来自线程数而非绑定（32 不绑定 ≈ 32 pinned）；64 线程比 32 慢 11%，超订纯亏。
• 物理吞吐在 ~16 物理核饱和（16→32 线程仅 +5% wall）：CPU% 上不去首先是内存带宽瓶颈，其次是串行 host 相摊薄。追“100% CPU”不是本 issue 目标。
• 代码事实：src/unilab/base/backend/mujoco/backend.py:355 默认 nthread = min(num_envs, 2*cpu_count)（沿用早期 rollout 惯例；曾经的 UNILAB_MUJOCO_STEP_THREADS 旋钮在 ab9614fa 被移除，未见调优依据）；EnvCfg.cpu_ids 仅由多卡 DP 路径注入（src/unilab/ipc/dp_launcher.py:128 单卡返回 None），单卡用户没有配置入口。

诊断脚本（可复现以上各表）：见评论区链接的分支 scripts/benchmark/env/ 下两个新脚本。

3. 最小交付结果

把单卡（cpu_ids=None）默认 pool 线程数从 2×cpu_count 收敛到有效 CPU 数（建议 len(os.sched_getaffinity(0))，尊重 taskset/cgroup），本机该 task 物理相预期提速 ~10%（独立 env 基准整步 +38%，真实训练受串行 host 相稀释会更低）。两个真实候选：

• A（推荐）：改默认 sizing 一行 + 更新受影响单测。规模 Small，长期维护成本为零。
• B：扩展 chunk_tuner 做 (nthread, chunk_size) 联合 autotune（沿用 adaptive_chunk_size 的 cache 机制），逐机自适应；但要动 tuner，规模升 Standard，留作后续。

4. In scope

• src/unilab/base/backend/mujoco/backend.py 默认 _n_threads sizing 规则（仅 cpu_ids is None 路径）。
• 受影响既有单测更新 + 一条 sizing 规则单测。
• 用复现命令在同机验证稳态 steps/s 与 CPU 占用前后对比。

5. Non-goals

• update_state / reset_done 的并行化或 Numba 化（归 roadmap: motion tracking Numba 热点与统一 body-state copy 收敛 #1304 / 评估：Manager-based API 下用 Numba 加速 collector 后处理与 reset 的可行性（基于 #932 复盘） #1292 路线）。
• collector↔learner 流水线重构；mjwarp / motrix / drake 后端 sizing。
• 多卡 DP 路径（已有 cpu_ids 分区，不动）；新增 Hydra 配置旋钮。

6. Owner 与预计改动

• Owner layer：src/unilab/base/backend/mujoco（backend 适配层）。
• 预计 1–2 文件、≤50 行手写（选项 A），1 个 PR；执行 owner 待 maintainer 指派。

7. Acceptance criteria

• 单卡默认 nthread == min(num_envs, 有效 CPU 数)；显式 cpu_ids 时仍为 len(cpu_ids)。
• make check 与受影响单测通过；chunk tuner 因 cache key 含 nthread 自动重调，无脏 cache。
• 同机复现命令稳态 steps/s 提升（预期 ≥5%），issue/PR 中记录前后对比数据。

8. Stop conditions

• maintainer 说明 2× 规则在某些机型是刻意调优 → 退回并记录。
• 修完真实训练吞吐无改善（说明瓶颈不在线程数）→ 关闭，转入 roadmap: motion tracking Numba 热点与统一 body-state copy 收敛 #1304 / 评估：Manager-based API 下用 Numba 加速 collector 后处理与 reset 的可行性（基于 #932 复盘） #1292 路线。
• 发现需要新增配置旋钮或跨后端统一 sizing → 超出本 issue，回 maintainer 决策。

[TATP-233]

诊断脚本已推送至分支 perf/issue-1328-mujoco-pool-thread-sizing（仅新增 2 个 benchmark 脚本，不改动已有代码）：

• scripts/benchmark/env/benchmark_mujoco_pool_thread_scaling.py —— 复现正文 pool 裸测表（nthread × pinned/unpinned 的 wall 与实占核数）
• scripts/benchmark/env/benchmark_env_step_phase_cpu.py —— 复现 env.step 分相归因表（--cpu-ids 0-31 为 pinned A/B）

运行方式见各脚本 docstring。按治理约定，本 issue 的实施（选项 A/B 取舍）与后续 PR 均待 maintainer 确认。

[TATP-233]

在另一台机器上按评论区分支 perf/issue-1328-mujoco-pool-thread-sizing 的两个脚本 + 正文复现命令做了完整复现，三个证据方向与正文结论完全一致，定量差异可由机型差异解释。

复现环境

• 机器：AMD Ryzen 9 9950X3D（16 物理 / 32 逻辑核）+ RTX 4090 48GB（注意：与正文的 Xeon w5-3435X + RTX 6000 Ada 不同机型，逻辑核数同为 32）
• 代码：dev/issue-1304-motion-numba-body-state @ f734cabe，与正文基线同 commit；诊断脚本从上述分支原样检出
• 命令与正文/评论区 docstring 完全一致

1. pool 裸测（benchmark_mujoco_pool_thread_scaling.py，G1 scene_flat.xml，4096 envs × 3 substeps，chunk_size=6）

nthread	ms/step	实占核
64 默认不绑定	41.94	22.9
32 不绑定	36.04	29.5
32 pinned	36.30	29.9
24 pinned	37.46	23.5
16 pinned	39.32	15.8
8 pinned	75.64	8.0

• 64 线程比 32 慢 16.4%（正文机上 11%），超订纯亏 ✓
• 32 不绑定 ≈ 32 pinned（36.04 vs 36.30），收益来自线程数而非绑定 ✓
• 16→32 线程仅 +9% wall，物理相在 ~16 物理核附近饱和 ✓

2. env.step 分相归因（benchmark_env_step_phase_cpu.py，4096 envs，随机动作，150 步均值）

配置	backend_step	update_state	reset_done	整步	steps/s
默认 64 线程	39.72ms @ 21.4 核	5.70ms @ 2.1 核	3.92ms @ 3.9 核	50.20ms @ 17.5 核	81587
32 线程（cpu_ids=0–31）	34.37ms @ 26.2 核	5.83ms @ 2.0 核	5.39ms @ 2.7 核	46.51ms @ 19.9 核	88073（+8.0%）

方向与正文一致（32 线程全面不慢、物理相明显更快、host 串行相只占 1–4 核），但整步收益 +8.0% 小于正文的 +38%。原因可见于绝对值：本机 update_state 5.7ms / reset_done 3.9ms，远低于正文机的 20.7ms / 11.8ms——9950X3D 单核与内存性能更强，串行 host 相绝对耗时大幅下降，超订惩罚占比相应缩小（物理相收益 +13.5%，与正文 78.5→59.5ms 的 +24% 同向同量级）。

3. 真实训练稳态（uv run train --algo sac --task g1_motion_tracking --sim mujoco algo.num_envs=4096 training.trace_enabled=true）

• 整机 CPU（/proc/stat 2s 采样，剔除启动后取稳态窗口）：mean 53.2% / median 53.3%，max 55.4% —— 与正文 47.5–49.2% 同属"结构性 ~50%"量级 ✓
• 稳态吞吐（tfevents perf/steps_per_sec 后半程）：median 91034 steps/s（本机绝对值无直接可比性）
• collector env_step 分相（tfevents timing/collector_env_step_*，后半程均值）：45.2ms = backend 36.0ms + update_state 5.7ms + reset_done 2.5ms，串行 host 相占比 ~18%，与正文"约 1/3 墙钟"同结构性问题、占比因机型缩小 ✓

结论

在本机（同为 16C/32T，但单核/内存代际更新）上，issue 的三组核心证据全部复现，方向无一反例；选项 A（单卡默认 nthread = min(num_envs, 有效 CPU 数)）在本机的预期收益：物理相 ~+13%，真实训练稳态吞吐受串行 host 相稀释后预计为高个位数百分比，符合正文"≥5%"的预期下限。

备注（与本 issue 无关的观察）

该训练运行在 iter ~20200/25000 处以 exit code 247 退出（model_20000.pt 已保存，控制台无 traceback，stdout 因块缓冲丢失），未跑满 25000；不影响以上稳态测量窗口。如需可另行排查。

[TATP-233]

在第三台机器（macOS / Apple Silicon，与前两台 Linux x86 不同平台）上做了完整复测，结论：结构性问题（物理相饱和点、host 串行相低并行、整机 CPU% 结构性偏低）复现；但 2× 超订惩罚在本机不复现；模拟选项 A 的真实训练仍 +4~5% 且无回退。

复现环境

• 机器：MacBook Pro（Mac17,6），Apple M5 Max，18 核（sysctl：6 "Super" + 12 "Performance"，无 SMT，18 线程 = 18 物理核），128GB，macOS 25.5.0
• 栈：torch 2.7.0（无 CUDA，learner 自动回落 MPS）、mujoco 3.10.0、Python 3.13.12
• 代码：dev/issue-1304-motion-numba-body-state @ 07e6fe64（含 benchmark(env): add MuJoCo pool thread-scaling and env-step phase-CPU probes (#1328) #1329 诊断脚本、fix(base): cpu_runtime 在非 Linux 主机上的类型检查与测试修复 #1330 Darwin cpu_runtime 修复；backend.py:356 仍为 2×cpu_count，即选项 A 未实施状态）
• 与正文的方法差异（均为 Darwin 平台限制所致）：
  • mujoco_uni cpu_ids pinning 仅支持 Linux（macOS 直接 ValueError）→ 无 pinned 行；18 线程行通过在 import 前 patch multiprocessing.cpu_count（→9，使 min(num_envs, 2×9)=18）注入。仓库内仅 mujoco/drake backend 消费该符号，torch 线程预算 / Numba / chunk_tuner cache key 均走 os.cpu_count 不受影响，是单变量 A/B。
  • 整机 CPU% 用 iostat -w 2（us+sy）替代 /proc/stat。
  • 训练命令按正文，另加 algo.max_iterations=600 training.no_play=true（task YAML 默认 25000；稳态取 iter 300–600 后半程）。

1. pool 裸测（benchmark_mujoco_pool_thread_scaling.py，scene_flat.xml，4096 envs × 3 substeps，chunk_size=6）

nthread	ms/step	实占核
36（本机默认 2×18，不绑定）	44.44	17.4
24 不绑定	45.03	17.3
18 不绑定	45.04	17.4
12 不绑定	62.88	11.9
9 不绑定	80.75	8.9
6 不绑定	114.89	6.0

• 饱和点恰在 18 = 有效线程数（无 SMT 机型），18→36 零收益、18 以下近似线性掉 —— "物理相在有效核数饱和" ✓
• 但 2× 超订无惩罚：36t 不慢于 18t（−1.3%，噪声内），与两台 Linux 机（64t 比 32t 慢 11% / 16.4%）结论相反 —— macOS 调度器对超订 pool 不敏感。

2. env.step 分相归因（benchmark_env_step_phase_cpu.py，4096 envs，随机动作，150 步均值；adaptive chunk 各自调优：36t→chunk 11，18t→chunk 22）

配置	backend_step	update_state	reset_done	整步	steps/s
默认 36t	44.19ms @ 16.8 核	6.55ms @ 2.1 核	5.33ms @ 4.2 核	57.12ms @ 13.6 核	71,714
18t	50.50ms @ 15.9 核	7.99ms @ 2.0 核	5.52ms @ 3.6 核	65.23ms @ 12.9 核	62,791（−12.5%）

• host 串行相只占 ~2–4 核、backend_step 占墙钟 77% ✓ 与正文结构性一致。
• 但整步方向反转：18t 更慢 12.5%；chunk tuner 微基准同向（36t≈25.2ms vs 18t≈26.8ms，−6%），与 pool 裸测（持平）结合看，本机隔离基准中 2× 不亏、1× 不赚。

3. 真实训练稳态（正文命令，600 iter，后半程 median；两 run 目录：logs/fast_sac/G1MotionTrackingSAC/2026-08-27_14-50-00_mujoco（36t）/ _14-52-21_mujoco（18t））

指标（tfevents tag）	36t 基线	18t（模拟选项 A）
perf/steps_per_sec	24,660	25,896（+5.0%）
perf/iter_ms	166.1	158.2（−4.8%）
timing/learner_train_ms	163.3	155.4（−4.8%）
timing/learner_collector_wait_ms	0.12	0.12
timing/collector_env_step_ms	46.8	45.1
├ backend / update_state / reset_done	31.0 / 8.8 / 6.5	30.4 / 7.7 / 6.0
timing/collector_learner_action_wait_ms	120.2（cycle 的 71%）	113.0
perf/collector_active_steps_per_sec	83,552	86,012（+2.9%）
整机 CPU%（iostat us+sy，稳态 median）	28%	~29%

• 本机 regime 与两台 Linux+CUDA 机不同：learner-bound（MPS learner 每 iter ~163ms，远超 collector 实际工作量 ~50ms；collector cycle 的 71% 在等 learner 动作）。整机 CPU% 因此只有 ~28%，比正文 ~48% 更低 —— "CPU% 结构性上不去"在本机以更极端的形式成立 ✓
• 18t 的 +5% 不来自物理相（backend 基本持平），而来自 learner 侧：少 18 个 pool worker 后 learner 的 host 线程（torch compile/MPS 提交路径）争用减小，learner_train_ms −4.8%。单跑对照、run 内噪声 ±4%，但 iter_ms 与 learner_train_ms 两个 tag 同向 −4.8%，方向可信。
• 注意隔离基准与真实训练符号相反（前者 18t 慢 12.5%，后者 18t 快 5%）：本机上 nthread 的净效应由进程间争用决定，隔离 env 基准不能代理真实训练方向 —— 验收标准里"用复现命令验证稳态 steps/s"这条在本机是必要的。

结论

1. issue 的结构性诊断在本机复现：物理相饱和于有效核数、host 串行相 1–4 核、整机 CPU% 结构性偏低（本机 ~28%，learner-bound 使然）。
2. "2× 超订纯亏"在本机不成立（无 SMT + macOS 调度）：pool 裸测持平、隔离 env.step 18t 反而慢 12.5%。
3. 尽管如此，模拟选项 A（nthread=18）的真实训练稳态 steps/s +4~5% 且无任何相变慢，CPU% 不变 —— 收益机制从 Linux 的"消除超订惩罚"变为"减少对 learner/host 相的争用"。对本机而言选项 A 仍为正改进，但预期收益（高个位数以内）低于 Linux 机型。
4. 两个 Darwin 平台事实，与选项 A 实施直接相关：
   • os.sched_getaffinity 在 macOS 不存在，min(num_envs, 有效 CPU 数) 需要 os.cpu_count() fallback（fix(base): cpu_runtime 在非 Linux 主机上的类型检查与测试修复 #1330 后 cpu_runtime.py 已有同款 getattr 模式可循）。
   • mujoco_uni cpu_ids Linux-only（macOS 硬报错）→ 单卡 macOS 用户目前没有任何收缩 pool 线程的入口，选项 A 是该平台唯一杠杆。

[TATP-233]

关闭说明：本 issue 的超订问题已解决，acceptance criteria 全部达成。

• 修复：PR perf(mujoco): 单卡默认 pool 线程数收敛到有效 CPU 数，消除 2× 超订 (#1328) #1333（df9def36），单卡默认 nthread = min(num_envs, 有效 CPU 数)（sched_getaffinity，尊重 taskset/cgroup），显式 cpu_ids 时仍为 len(cpu_ids)；同机稳态 86,162 → 96,262 steps/s（+11.7%，见 commit message），受影响单测已更新并新增 sizing 规则测试。
• 修复后复测（M5 Max，commit 59d82518，collector-only 基准）：nthread=18 生效；benchmark_env_step_phase_cpu.py 1500 步均值 69,720 steps/s，物理相 16.4/18 核；benchmark_offpolicy_collector_active.py Collector/s = 74,298；整机 iostat 稳态 busy 78.4%。超订惩罚消除。
• 剩余"CPU 利用率仍然低"是 collector 自身结构性问题，与超订无关、与 learner 无关：78% 墙钟的物理相已被内存带宽饱和（加线程零收益），22% 墙钟的串行 host 相（update_state 11.5% + reset_done 8.3%）只用 1–4 核。update_state 归 roadmap: motion tracking Numba 热点与统一 body-state copy 收敛 #1304 路线，reset 路径无 owner。

后续跟踪转入 #1340。