用途
该技能为训练侧输出目录定义标准化规则，用于统一保存模型权重（checkpoint）。当用户需要在训练脚本中实现检查点保存，或需要让加载器、部署服务、评估工具跨模型定位权重时，可使用此技能。
主要能力
- 定义标准目录布局：顶层为 {output_root}，最终步权重文件夹的全部内容直接放在 {output_root} 根目录下；每个周期性权重文件夹的全部内容放入 {output_root}/ckpt/checkpoint{step}/。
- 仅规定外层存储位置，不预设不同模型/框架产生的检查点内部结构（权重文件名、配置、统计信息等），也不重命名或修改任何检查点内部文件。
- 提供可选的加载器/路径解析参考实现（references/loader.py），用于定位 {output_root} 并选择最新检查点。
- 支持恢复训练：扫描 ckpt/ 下目录名匹配 checkpoint<N> 的检查点（也兼容旧式纯 <N> 或 steps_<N>_*.pt 扁平文件），从 N 最大的一个恢复。
使用方式
- 定义布局：
{output_root}/
├── <all contents of the final-step weight folder> # files/subfolders directly under root
└── _ckpt/ # periodic checkpoints
├── checkpoint_1000/
│ └── <all contents of that step's weight folder>
└── checkpoint_2000/
└── <all contents of that step's weight folder>
-
在训练脚本中应用规则：
- 最终步：将最终步权重文件夹下的所有文件/子文件夹直接放在 {output_root}/ 根目录下（不要创建 final_model/ 子目录）。
- 周期性检查点：将每个周期性权重文件夹下的所有文件/子文件夹放入 {output_root}/ckpt/checkpoint{step}/（step 为该检查点保存的步数）。
- 仅移动/复制内容：不要重命名或修改检查点内部文件。
- _ckpt/ 在训练开始时创建，因此布局在第一个检查点之前就已存在。
-
加载器/路径解析：
- 从权重文件向上遍历，找到包含 _ckpt/ 目录的祖先目录，该祖先即为 {output_root}。不要硬编码固定的父级深度（例如 path.parents[1]）。
- 示例路径：
- {output_root}/<final weight>（最终步内容，任意文件名）
- {output_root}/_ckpt/checkpoint_1000/<weight file>（周期性检查点）
- 参考实现见 references/loader.py。
-
恢复训练：
- 扫描 ckpt/ 下目录名匹配 checkpoint<N> 的检查点（也兼容旧式纯 <N> 或 steps_<N>_*.pt 扁平文件），从 N 最大的一个恢复。
核心命令
references/loader.py 提供以下函数（复制到 migrate_to_cloudrobo/loader.py 并扩展模型重建逻辑）：
| 函数 | 用途 |
|---|---|
| locate_output_root(weight_path) | 从权重文件向上遍历，找到包含 _ckpt/ 的祖先目录，返回 {output_root} |
| find_latest_checkpoint(ckpt_root) | 返回 _ckpt/ 下最新检查点的 (step, checkpoint_dir)，或 (None, 0) |
| load_state_dict(weight_path) | 从 .pt 或 .safetensors 文件加载原始 state dict（CPU） |
参数确认
| 参数 | 描述 |
|---|---|
| {output_root} | 标准布局的顶层输出目录；最终步权重内容位于其根目录 |
| _ckpt/ | {output_root} 下的周期性检查点目录 |
| checkpoint_{step} | 每步周期性检查点目录；step 为保存的步数 |
| <N> | 恢复时匹配的步数（checkpoint_<N> / 纯 <N> / steps_<N>_*.pt） |
适用场景
- 需要在训练脚本中实现检查点保存。
- 需要让加载器、部署服务或评估工具跨模型定位权重。
- 需要从周期性检查点恢复训练。
限制
- 该布局只定义外层存储位置，不预设检查点内部结构，也不重命名任何文件。
- 使用 load_state_dict() 加载 .pt 权重需要 torch>=1.13，因为它使用 torch.load(..., weights_only=True) 防止检查点在加载时执行代码。
- 加载器/路径解析为可选组件；若项目需要消费检查点，需将 references/loader.py 复制到项目的 migrate_to_cloudrobo/loader.py 并扩展模型重建逻辑。
- 关于 IAM 权限：references/iam-policies.md 说明无需任何权限。
参考文档
- references/loader.py — 定位 {output_root} 并选择最新检查点（复制到项目的 migrate_to_cloudrobo/loader.py）。
- references/verification-method.md — 使用示例布局验证加载器，并检查真实训练输出。
- references/iam-policies.md — IAM 权限（无需任何权限）。