# v4训练检查点精简：保留每模型最佳权重

用户授权：“v4的last.pt仅保存每个模型的最佳权重用于后训练，其余权重释放”。
本次只精简 `outputs/pallet_pose_benchmark_v4/{trials,refit}/` 的训练权重，
不更改正式数据、人工历史、旧选模结果、评测、源代码快照、完整部署目录或交付ZIP。

## 最佳权重的定义

- 使用原有 `selection_frozen.json` 中 **原train交叉验证** 的分数，在每模型/单位分支内选配方；分数越低越好。
- 完全相同的分数沿用冻结记录原顺序，不因更晚的配方名字而换模型，不用val/test再选模。
- 保留对应全train重拟合的 **CV所定epoch权重**，而不是直接保留 `last.pt` 或refit末轮 `selected.pt`。
  后者不一定是CV推荐的重拟合轮次。
- 八模型各有 `metric` 与 `native_unknown` 两个单位分支，分开保留，共16份；未知单位不混入米制。
- 每份最佳权重与冻结profile、完整部署包的文件哈希和epoch一致；用CPU `weights_only=True` 加载，检查state_dict有限性。
  这是序列化/内容完整性检查，不是新一轮训练、GPU推理或精度验证。

| 模型 | metric配方 / epoch | native_unknown配方 / epoch |
|---|---|---|
| Utonia | base / 1 | base / 1 |
| LitePT | base / 7 | base / 1 |
| Concerto | base / 3 | base / 1 |
| Sonata | base / 6 | base / 1 |
| PTv3 | long_b32 / 20 | long_b64_steps / 12 |
| PointNeXt | long_b32 / 180 | base / 1 |
| Point-MAE | base / 2 | base / 1 |
| DGCNN | base / 65 | base / 1 |

保留原始路径和原始文件字节，不重新序列化、不将末轮文件改名冒充best。
下游v5研究读取的 `refit/pointnext/metric/long_b32/epochs/180.pt` 也在保留集合中。

## 清理范围和代价

计划移除：

| 类型 | 文件数 | 约占用 |
|---|---:|---:|
| 含优化器/RNG的 `last.pt` | 178 | 30.51 GiB |
| 折内或refit末轮的 `selected.pt` | 178 | 10.17 GiB |
| 非最佳配方的refit epoch副本 | 12 | 0.89 GiB |
| 合计 | 368 | 41.57 GiB |

16份保留的训练权重约0.316 GiB。
已发布 `deployment/` 保持完整的28个原实验profile及5份官方预训练编码器，
其完整校验配置仍可使用；两份模型/标签交付ZIP和HTML报告ZIP也保留原样。
这里的“训练目录只留16份”不表示改写不可变交付包去删除其历史配方。

**明确失去的能力：**

- 被删除的last.pt含AdamW动量、随机状态、末轮参数；模型交付ZIP只有模型权重，不能恢复这些状态。
- 不能再从原epoch80或其它删除端点做到逐步一致的旧实验续训。
- 原 `scripts/verify_pose_benchmark_v4.py` 的完整trial检查会因last/selected已删除而失败；
  本次不会改写旧验收记录来伪造“全部检查点仍存在”。旧验收保留为清理前的历史记录，新清理审计另存。
- 后续可从保留最佳模型 **重新微调**，但应新建输出目录和优化器，不能称为原优化器/RNG断点续训。

## 计划与执行

入口：`scripts/compact_pose_v4_checkpoints.py`；独立审计目录：
`outputs/pallet_pose_v4_checkpoint_cleanup_v1/`。

```bash
PYTHONDONTWRITEBYTECODE=1 OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
  .venv/bin/python scripts/compact_pose_v4_checkpoints.py plan

# 完整计划核对后使用其精确哈希；不支持无清单通配删除
PYTHONDONTWRITEBYTECODE=1 OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
  .venv/bin/python scripts/compact_pose_v4_checkpoints.py apply \
  --plan-sha256 <plan.json的SHA-256>
```

计划对每个删除项校验原始SHA-256与completed/profile历史绑定；只删明确白名单路径，
未知新权重、未完成训练、符号链接、硬链接、打开文件或变化文件均阻断。
检查并独占原pipeline锁，避免与正常管线同时运行，不启动任何训练。

保留的v4全部文件（包括完整部署、数据、报告、ZIP）在清理前后逐字节哈希核对；
全部配置和三个人工库逻辑指纹也必须不变。
正式数据检查覆盖72,667份文件的路径/stat身份，不是新一轮全量内容字节审计。
删除动作只对清单内文件逐项unlink，清单与删除journal均保留。

`plan.json` 是计划，不是已删除成功的证明；实际完成状态和净释放空间以 `result.json` 为准。
本次已审阅冻结计划SHA-256为 `68c80dc3c897c2a419604c1b2bce0450fc461bbbe3e8d7dbb02d390a8e571218`。

独立的只读核对记录 `outputs/pallet_pose_v4_best_weight_audit_v1.json` 已将16份最佳refit权重
分别与原交付ZIP内对应成员逐字节比对通过，并核对v5依赖的PointNeXt原路径在保留集合中。
该检查没有启动训练或重新评测准确率。清理工具、删除后核验、旧复核清理保护与v4 CPU回归联合测试56项通过，
1项GPU断点等价测试按显式开关跳过；不能据此声称清理后仍有旧优化器/RNG状态。

删除任务完成后，再运行不导入清理器的 `scripts/verify_pose_v4_checkpoint_compaction.py`，
将缺失项/journal、16份冻结最佳选择、全部保留v4内容哈希、人工库/配置/正式文件保护和三个服务健康状态
写入独立的 `post_cleanup_verification.json`。它不能重新读取已删文件，因此明确不将后验检查当作删除字节的独立重读证明。

## 如何找到保留权重用于后续训练

`outputs/pallet_pose_v4_checkpoint_cleanup_v1/best_weights_index.json` 列出16个来源路径、哈希、
单位分支、配方、CV分数、epoch、训练域及冻结编码器标记。
此索引不改变当前部署入口，也不自动授权或启动新的训练任务。

五个冻结编码器模型的checkpoint只含位姿头及其归一化buffer，必须同时保留并使用匹配的
`deployment/weights/` 官方编码器和 `deployment/upstream/` 架构代码；只拷贝小的head文件不是完整模型。
其余模型保留完整端到端state_dict。模型状态均可在CPU只读加载，不含可恢复的优化器状态。

未来微调应先核对索引哈希、架构、输入单位/域/特征和标签资格，再在新版本中建立训练协议及新优化器。
不要把val/test回流训练，不根据已看的test重新选模，不把人工选面/多边形/标尺/目标ID当作位姿输入。
新任务若需要额外GPU，优先两块非3090卡，并在启动前按UUID重新核实设备和空闲资源。

## 实际完成结果

2026-10-26完成，`result.json` 与 `post_cleanup_verification.json` 均为 `passed`：

- 删除368个训练检查点：178份last、178份selected、12份非最佳epoch副本。
- 移除文件占用41.5677 GiB，删除阶段实测净释放41.5676 GiB；最终可用空间约55.98 GiB。
- v4目录由约46.73 GiB降至5.16 GiB；`trials/` 无剩余PT，`refit/` 恰好保留16份最佳PT。
- 原部署目录、交付ZIP及其它保留v4文件共9,849份重新校验内容哈希通过；
  三个人工库逻辑指纹、全部配置和72,667份正式文件路径/stat身份保持一致。
- 16份保留权重再次通过CPU安全加载；v5依赖路径保留；位姿、图库、结构服务均返回HTTP 200。
- 没有启动训练、重测精度、改写人工标注或活动配置。

删除的优化器/RNG状态没有备份；这是按用户授权释放空间，不宣称可从模型交付ZIP恢复原断点状态。
