ShopTRAINING/xz训练模型保存规则.md

扁平化模型数据处理规范 (最终版)

版本: 4.0 (最终版) 核心思想: 逻辑路径被转换为文件名的一部分，实现极致扁平化的文件存储。

---

一、 文件保存规则

1.1. 核心原则

所有元数据都被编码到文件名中。一个逻辑上的层级路径（例如 product/P001_all/mlstm/v2）应该被转换为一个用下划线连接的文件名前缀（product_P001_all_mlstm_v2）。

1.2. 文件存储位置

• 最终产物: 所有最终模型、元数据文件、损失图等，统一存放在 saved_models/ 根目录下。
• 过程文件: 所有训练过程中的检查点文件，统一存放在 saved_models/checkpoints/ 目录下。

1.3. 文件名生成规则

1. 构建逻辑路径: 根据训练参数（模式、范围、类型、版本）确定逻辑路径。

   • 示例: product/P001_all/mlstm/v2

2. 生成文件名前缀: 将逻辑路径中的所有 / 替换为 _。

   • 示例: product_P001_all_mlstm_v2

3. 拼接文件后缀: 在前缀后加上描述文件类型的后缀。

   • _model.pth
   • _loss_curve.png
   • _checkpoint_best.pth
   • _checkpoint_epoch_{N}.pth

完整示例:

• 最终模型: saved_models/product_P001_all_mlstm_v2_model.pth
• 最佳检查点: saved_models/checkpoints/product_P001_all_mlstm_v2_checkpoint_best.pth
• Epoch 50 检查点: saved_models/checkpoints/product_P001_all_mlstm_v2_checkpoint_epoch_50.pth

---

二、 文件读取规则

1. 确定模型元数据: 根据需求确定要加载的模型的训练模式、范围、类型和版本。
2. 构建文件名前缀: 按照与保存时相同的逻辑，将元数据拼接成文件名前缀（例如 product_P001_all_mlstm_v2）。
3. 定位文件:
   • 要加载最终模型，查找文件: saved_models/{prefix}_model.pth。
   • 要加载最佳检查点，查找文件: saved_models/checkpoints/{prefix}_checkpoint_best.pth。

---

三、 数据库存储规则

数据库用于索引，应存储足以重构文件名前缀的关键元数据。

models 表结构建议:

字段名	类型	描述	示例
id	INTEGER	主键	1
filename_prefix	TEXT	完整文件名前缀，可作为唯一标识	product_P001_all_mlstm_v2
model_identifier	TEXT	用于版本控制的标识符 (不含版本)	product_P001_all_mlstm
version	INTEGER	版本号	2
status	TEXT	模型状态	completed, training, failed
created_at	TEXT	创建时间	2025-07-21 02:29:00
metrics_summary	TEXT	关键性能指标的JSON字符串	{"rmse": 10.5, "r2": 0.89}

保存逻辑:

• 训练完成后，向表中插入一条记录。filename_prefix 字段是查找与该次训练相关的所有文件的关键。

---

四、 版本记录规则

版本管理依赖于根目录下的 versions.json 文件，以实现原子化、线程安全的版本号递增。

• 文件名: versions.json
• 位置: saved_models/versions.json
• 结构: 一个JSON对象，key 是不包含版本号的标识符，value 是该标识符下最新的版本号（整数）。
  • Key: {prefix_core}_{model_type} (例如: product_P001_all_mlstm)
  • Value: Integer

versions.json 示例:

{
  "product_P001_all_mlstm": 2,
  "store_S001_P002_transformer": 1
}

版本管理流程:

1. 获取新版本: 开始训练前，构建 key。读取 versions.json，找到对应 key 的 value。新版本号为 value + 1 (若key不存在，则为 1)。
2. 更新版本: 训练成功后，将新的版本号写回到 versions.json。此过程必须使用文件锁以防止并发冲突。