262 lines
15 KiB
Markdown
262 lines
15 KiB
Markdown
# 训练前端 Windows 兼容性与「暂停」审计（结论 + 修复方案）
|
||
|
||
> 审计对象：`src/mcm26b/training_ui/`、`src/mcm26b/process_control.py`、
|
||
> `scripts/train_hrl_high.py`。
|
||
> 触发问题：「无法暂停」「频繁出现 os 无 killpg 等」。
|
||
> 结论一句话：**这两个现象同源——训练前端的停止/暂停路径是纯 POSIX 设计；
|
||
> Windows 上 `os.killpg` 根本不存在，异常又没被兜住，所以点了停止等于没点。**
|
||
|
||
---
|
||
|
||
## 0. 结论摘要
|
||
|
||
| # | 现象 | 根因 | 严重度 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | 点「停止训练」返回 500 / 无效果，训练照跑，于是「无法暂停」 | `TrainingJob.stop()` 直接调用 `os.killpg(os.getpgid(...))`；这两个符号**只存在于 POSIX**，Windows 上抛 `AttributeError`，而旧 `except` 只接 `ProcessLookupError/PermissionError` | 阻断 |
|
||
| 2 | 控制台/日志反复出现 `module 'os' has no attribute 'killpg'` | 同上：错误最终落到 `_UIHandler.do_POST` 的兜底 `except Exception`，返回 500 并带出 `AttributeError` 文本；每点一次复现一次 | 阻断 |
|
||
| 3 | 即使把 killpg 换成 `terminate()`，停止后模型/元数据仍然丢失（Windows 上） | Windows 的 `os.kill(pid, SIGTERM)` 语义是 `TerminateProcess` **硬杀**，训练脚本里"收到信号后在 step 边界保存"的处理器不会执行 | 高 |
|
||
| 4 | 界面根本没有「暂停」能力（POSIX 也没有） | 原设计只有 start/stop；且 `SIGSTOP/SIGCONT` 在 Windows 上不存在，**原生暂停在 Windows 上无法实现**，必须改成协作式 | 高 |
|
||
| 5 | 子进程进程组隔离在 Windows 上失效 | `Popen(start_new_session=True)` 在 Windows 被**静默忽略**（CPython 的 Windows `_execute_child` 形参名就是 `unused_start_new_session`） | 中 |
|
||
| 6 | subproc worker 在 Windows 下可能抢在主进程收尾前退出 | worker 只忽略 `SIGTERM/SIGINT`，没处理 Windows 的 `SIGBREAK`（`CTRL_BREAK_EVENT` 的落点） | 中 |
|
||
|
||
**修复原则**：把"暂停/继续/停止"从**信号语义**改成**控制文件语义**。
|
||
控制文件在 POSIX 与 Windows 上都只是普通文件 IO，行为完全一致；信号与强杀退居
|
||
兜底。这样 Windows 上暂停、继续、优雅停止、落盘保证全部成立。
|
||
|
||
---
|
||
|
||
## 1. 失败链复现（旧代码）
|
||
|
||
```
|
||
用户点「停止训练」
|
||
└─ POST /api/train/stop
|
||
└─ TrainingUI.stop() → TrainingJob.stop()
|
||
└─ os.killpg(os.getpgid(process.pid), signal.SIGTERM)
|
||
├─ POSIX ：成功，进程组收到 SIGTERM，脚本优雅收尾
|
||
└─ Windows：AttributeError: module 'os' has no attribute 'killpg'
|
||
↑ 只 except (ProcessLookupError, PermissionError)，接不住
|
||
└─ _UIHandler.do_POST 兜底 except Exception → HTTP 500
|
||
└─ 训练子进程完全没收到任何指令，继续跑 → 「无法暂停 / 停止没反应」
|
||
```
|
||
|
||
关键代码（修复前，`src/mcm26b/training_ui/server.py`）：
|
||
|
||
```python
|
||
def stop(self) -> bool:
|
||
with self._lock:
|
||
process = self.process
|
||
if process is None or process.poll() is not None:
|
||
return False
|
||
try:
|
||
os.killpg(os.getpgid(process.pid), signal.SIGTERM)
|
||
except (ProcessLookupError, PermissionError):
|
||
process.terminate()
|
||
self.status = "stopping"
|
||
return True
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 根因逐条（含证据）
|
||
|
||
### 2.1 `os.killpg` / `os.getpgid` 是 POSIX-only
|
||
|
||
CPython 只在 `posix` 构建里注册这两个函数；Windows 的 `os` 模块没有它们。
|
||
访问会得到 `AttributeError`（不是 `OSError` 子类），所以旧 `except` 接不住。
|
||
|
||
### 2.2 `start_new_session=True` 在 Windows 被静默忽略
|
||
|
||
`subprocess.Popen` 接受该参数，但 Windows 的 `_execute_child` 形参名是
|
||
`unused_start_new_session`，也就是**根本不读**。要隔离进程组，Windows 必须传
|
||
`creationflags=CREATE_NEW_PROCESS_GROUP`。
|
||
|
||
### 2.3 Windows 的 `SIGTERM` 是硬杀
|
||
|
||
`os.kill(pid, sig)` 在 Windows 上只有 `CTRL_C_EVENT` / `CTRL_BREAK_EVENT` 是
|
||
"软"信号；**任何其它值**（含 `SIGTERM`）都会走 `TerminateProcess`。因此
|
||
`scripts/train_hrl_high.py` 里的：
|
||
|
||
```python
|
||
for _signum in (signal.SIGTERM, signal.SIGINT): # 旧代码
|
||
signal.signal(_signum, _on_stop_signal)
|
||
```
|
||
|
||
在 Windows 上形同虚设——处理器注册了，但没人会用它。这也解释了为什么"停止后
|
||
模型没保存"。
|
||
|
||
### 2.4 Windows 没有 `SIGSTOP`，暂停无法用信号实现
|
||
|
||
暂停（挂起/继续）在 POSIX 上可以用 `SIGSTOP/SIGCONT`，但 Windows 既无这两个
|
||
信号，也无等价的"无侵入挂起"用户态 API（真正的挂起要 `SuspendThread`/调试 API）。
|
||
所以**任何跨平台暂停都必须是协作式的**：由训练进程自己在 step 边界检查标志并
|
||
让出执行。本项目原先没有这条通道，界面也没有暂停按钮。
|
||
|
||
### 2.5 `SIGBREAK` 未处理
|
||
|
||
Windows 的 `CTRL_BREAK_EVENT`（发给进程组的软信号）在 Python 里落到
|
||
`signal.SIGBREAK`。旧的 handler 安装与 worker 屏蔽列表都只含
|
||
`SIGTERM/SIGINT`，Windows 下等于裸奔。
|
||
|
||
### 2.6 异常类型没兜住
|
||
|
||
`except (ProcessLookupError, PermissionError)` 漏掉 `AttributeError`、以及
|
||
更一般的 `OSError`；`_hard_kill` 里 `signal.SIGKILL` 在 Windows 上也不存在
|
||
（`getattr(signal, "SIGKILL", None) is None`），同样会 `AttributeError`。
|
||
|
||
---
|
||
|
||
## 3. 修复方案（已实施）
|
||
|
||
### 3.1 新增 `src/mcm26b/process_control.py`（零第三方依赖）
|
||
|
||
| 能力 | 实现 | 作用 |
|
||
| --- | --- | --- |
|
||
| 子进程隔离 | `spawn_kwargs()`：POSIX `start_new_session=True`；Windows `creationflags=CREATE_NEW_PROCESS_GROUP` | 前端 Ctrl+C 不误伤训练；Windows 也能组杀进程树 |
|
||
| 控制协议读写 | `write_control()` / `read_control()`：JSON + 同目录临时文件 + `os.replace` 原子替换；损坏/缺失一律视为"无指令" | 两端统一的暂停/停止通道 |
|
||
| 强杀兜底 | `terminate_process_tree(process, grace_s)`：先等宽限期；超时后 POSIX 走 `killpg(SIGKILL)`、Windows 走 `taskkill /F /T /PID`；所有 POSIX 符号用 `getattr` 探测 | 彻底移除 `os.killpg` 无条件调用；返回"是否动用了强杀" |
|
||
|
||
`IS_WINDOWS` 是运行期常量而非导入期分支，便于测试直接 monkeypatch 模拟 Windows。
|
||
|
||
### 3.2 控制文件协议
|
||
|
||
路径由前端生成并随命令下发：`--control-file <abs>`（默认落在
|
||
`output/hrl/ui/control/<job_id>.control.json`，`output/` 已 gitignore）。
|
||
|
||
```json
|
||
{"paused": false, "stop": false, "seq": 1712345678901234567, "ts": 1712345678.9}
|
||
```
|
||
|
||
- 前端**只写**：`pause()` → `paused=true`；`resume()` → `paused=false`；
|
||
`stop()` → `stop=true`（同时清零 paused，保证阻塞中的暂停循环能被唤醒）。
|
||
- 训练脚本**只读**：`_ControlPoll` 每 32 个 step 抽样读一次盘（避免每 step 一次
|
||
文件 IO）；暂停时在 `_on_step` 内阻塞轮询（`poll_s=0.2`），进程存活、显存仍占用，
|
||
但不消耗算力。
|
||
- 墙钟上限 `--max-wall-s` **扣除累计暂停时长**，避免"挂起一小时回来直接判超时"。
|
||
|
||
### 3.3 训练脚本 `scripts/train_hrl_high.py`
|
||
|
||
- 新增 `--control-file`；`_ControlPoll`（纯标准库、可单测）+ 薄薄的
|
||
`_ControlChannel(BaseCallback)` 接到 SB3 回调链**最前面**。
|
||
- 收尾信号集合扩为 `_stop_signals()`：POSIX `SIGTERM/SIGINT`；Windows 追加
|
||
`SIGBREAK`。worker 屏蔽同一集合，保证主进程 `vec_env.close()` 之前 worker 不先退。
|
||
- 落盘保证不变：停止后仍写最终模型 + 元数据，`stopped_by_signal=true`，
|
||
`stop_signal` 记 `control_file` 或信号名；异常仍落 `*_emergency.zip`。
|
||
|
||
### 3.4 训练前端 `server.py` / `static/`
|
||
|
||
- 新增 `POST /api/train/pause`、`POST /api/train/resume`；`stop` 语义改为
|
||
"写控制文件 → 宽限期内自行退出；超时强杀"，强杀在**独立看门狗线程**里做，
|
||
HTTP 请求不会被 15s 等待卡住。
|
||
- 状态机新增 `paused`；`_sync_control_events()` 用训练脚本回显的
|
||
`paused/resumed/stop_requested` 事件校正状态。
|
||
- 快照新增 `forced_kill`，前端横幅区分"优雅停止"与"超时强杀"。
|
||
- 前端新增「暂停训练 / 继续训练」按钮、暂停横幅；停止确认文案更新。
|
||
|
||
### 3.5 停止/暂停时序
|
||
|
||
```
|
||
pause: UI 写 {paused:true} ──► 脚本 _on_step 读到 ──► 回显 paused，阻塞轮询
|
||
resume: UI 写 {paused:false} ─► 暂停循环退出 ────────► 回显 resumed，继续训练
|
||
stop: UI 写 {stop:true} ────► 脚本 step 边界收尾落盘 ──► 退出码 0
|
||
│
|
||
└─(宽限 15s 未退)─► terminate_process_tree 强杀；forced_kill=true
|
||
```
|
||
|
||
### 3.6 急停（强杀）也必须可恢复
|
||
|
||
宽限期一到就强杀，训练脚本**没有任何 Python 收尾机会**——不写最终模型、不写
|
||
元数据、不写 `training_failure.json`。如果磁盘上只有 `--checkpoint-every` 的稀疏
|
||
历史 checkpoint，急停就可能丢掉上万步，或者在"保存途中被杀"时留下一个打不开的
|
||
半截 zip。为此加了四条保证：
|
||
|
||
| 保证 | 实现 | 效果 |
|
||
| --- | --- | --- |
|
||
| 起步基线 | `recovery_every > 0` 时，`learn()` 之前先写一份 `<stem>_latest.zip` | 训练刚起就急停，也有可加载、可 `--resume` 的产物 |
|
||
| 滚动恢复点 | 每 `--recovery-every`（默认 2000）环境步覆盖写同一份 `<stem>_latest.zip` | 急停最多丢 `recovery_every` 步，而不是 `checkpoint-every` 步 |
|
||
| 原子落盘 | 模型 zip / 旁挂 json / `resume.json` 一律「同目录 `.tmp-` + `os.replace`」 | 保存途中被强杀，目标路径仍是上一份**完整**快照；不会出现半截文件 |
|
||
| 权威恢复指针 | 每次落盘刷新 `<run_dir>/resume.json`（model / timesteps / 增量语义 / 生效 PPO 超参）；前端 `/api/train/state` 暴露为 `recovery` | 无论怎么停，都有一份明确的"从哪继续"；界面一键「用最近检查点续训」 |
|
||
|
||
前端在强杀后还会补写 `<run_dir>/forced_stop.json`（`job_id`、`pid`、`reason`、
|
||
`recovery.model`），因为此时训练脚本已经无法记录任何事情。
|
||
|
||
---
|
||
|
||
## 4. 平台兼容性矩阵（修复后）
|
||
|
||
| 能力 | POSIX | Windows |
|
||
| --- | --- | --- |
|
||
| 启动子进程并隔离 | `start_new_session=True`（setsid） | `CREATE_NEW_PROCESS_GROUP` |
|
||
| 暂停 / 继续 | 控制文件（协作式） | 控制文件（协作式） |
|
||
| 优雅停止 + 落盘 | 控制文件；`SIGTERM` 亦可 | 控制文件；`CTRL_BREAK_EVENT`→`SIGBREAK` 亦可 |
|
||
| 超时强杀进程树 | `killpg(SIGKILL)` | `taskkill /F /T /PID` |
|
||
| `os.killpg` 依赖 | 有 | **无（不再调用）** |
|
||
| 暂停期间是否算墙钟 | 否（扣除） | 否（扣除） |
|
||
|
||
---
|
||
|
||
## 5. 验证
|
||
|
||
- 新增/更新回归测试：
|
||
- `tests/test_training_ui.py`：控制文件协议往返与损坏容错、`spawn_kwargs`
|
||
平台分支、Windows 强杀走 `taskkill`、**无 `killpg` 环境下强杀不抛异常**
|
||
（直接复现旧 bug）、暂停/继续/停止全链路、控制文件被忽略时强杀并写
|
||
`forced_stop.json` 恢复指引、`discover_recovery` 的
|
||
`resume.json`/扫描/悬空指针三分支、HTTP `pause/resume` 端到端。
|
||
- `tests/test_hrl_checkpoint.py`：控制文件状态机单测；原子保存失败不破坏上一份
|
||
快照；JSON 原子替换；历史清理不误删滚动恢复点；起步基线可加载；
|
||
**强杀急停后 `resume.json` + 滚动恢复点仍可 `--resume`**；控制文件停止后
|
||
模型/元数据落盘（`stop_signal=control_file`）与暂停→继续；POSIX 信号路径
|
||
单列并加平台跳过。以上集成用例都用**真实训练脚本**跑 subproc。
|
||
- 手工验证：`--recovery-every 32` 短程实跑后强杀，`resume.json` 指向
|
||
`q3_ckpt_latest.zip`；以它为 `--resume` 目标再跑 32 步，元数据
|
||
`actual_timesteps` 从 64 变 96、`timesteps_semantics=additional`。
|
||
- 全量测试：`pytest tests referee/tests` 全绿。
|
||
- 全仓库 `pylint src scripts project tests referee main.py` 达到 10.00/10
|
||
（口径见 §7）。
|
||
|
||
---
|
||
|
||
## 6. 残余风险与后续建议
|
||
|
||
1. **暂停粒度** = `poll_every` 个 env step（默认 32，约 0.1–3s 量级），不是即时；
|
||
若要更快可调小 `_ControlChannel(poll_every=...)`，代价是更频繁的文件 stat。
|
||
2. **宽限期固定 15s**（`server.STOP_GRACE_S`）。大模型保存可能更久；但因为落盘是
|
||
原子的，即使宽限期到点被强杀，也只是"新的最终模型没写成"，**上一份滚动恢复点
|
||
与历史 checkpoint 完好**，不会出现半截文件。需要更长可调大该常量。
|
||
3. **急停的损失上界 = `--recovery-every`**（默认 2000 环境步）。要更小就调小它；
|
||
调到 0 表示放弃滚动恢复点（此时只剩 `--checkpoint-every` 的稀疏历史
|
||
checkpoint 与起步基线）。
|
||
4. **Windows 强杀依赖 `taskkill`**（系统自带）。若被安全策略禁用，会退回
|
||
`Popen.kill()`（只杀主进程，spawn 的 worker 可能残留）。
|
||
5. 更严格的 Windows 方案是 **Job Object**（子进程随 job 句柄一起销毁），但需要
|
||
`ctypes`/`pywin32`，本仓库基础依赖刻意保持轻量，未引入。
|
||
6. **前端进程重启后**，内存中的任务对象没了，「用最近检查点续训」按钮不会自动
|
||
出现；但恢复信息都落在磁盘上（`<run_dir>/resume.json`、`forced_stop.json`、
|
||
`checkpoints/<stem>_latest.zip`），在表单里填同一个模型输出路径并勾选
|
||
`--resume` 即可继续。
|
||
7. 界面 `--device mps` 选项在 Windows 上无意义；`auto` 会回退 cuda/cpu，属既有
|
||
行为，未改。
|
||
8. `_ControlPoll` 的暂停循环会占用一个 Python 线程的调度（每 0.2s 一次读盘），
|
||
长暂停期间 CPU 占用可忽略。
|
||
|
||
---
|
||
|
||
## 7. pylint 口径说明
|
||
|
||
配置写在 `pyproject.toml` 的 `[tool.pylint.*]`，目标是
|
||
`pylint src scripts project tests referee main.py` = 10.00/10。
|
||
|
||
**改代码修掉的真实问题**（不是 disable）：未使用的 import/变量/参数、重复字典键
|
||
（`reward_version`）、`value != value` 判 NaN、`__dataclass_fields__` 私有访问、
|
||
`raise` 非异常类型、`pytest.importorskip` 之外的赋值不确定、过长行、无谓括号、
|
||
`len(x)` 判空、循环闭包变量、`subprocess.run` 未显式 `check`、`os.path` 循环导入等。
|
||
|
||
**有意 disable 的类别**（每条在 pyproject 里写了理由）：项目刻意的懒加载
|
||
（`import-outside-toplevel`）、防御式宽异常（`broad-exception-caught`）、测试访问
|
||
内部状态（`protected-access`）、pytest fixture 同名（`redefined-outer-name`）、
|
||
无头环境不实现 `gym.Env.render`（`abstract-method`）、以及静态分析的已知误报
|
||
（`possibly-used-before-assignment`）。
|
||
|
||
**注意**：`good-names` 不覆盖 `redefined-builtin`，stdlib 回调签名里的
|
||
`log_message(self, format, ...)` 只能在对应 `def` 上行内 disable。
|