ShopTRAINING/docs/MODEL_MANAGEMENT_RULES.md

药店销售预测系统 - 模型管理规则

📋 统一模型命名规范

文件名格式

1. 产品训练模式 (Product Mode)

{model_type}_product_{product_id}_{version}.pth

示例：

• tcn_product_P001_v1.pth
• mlstm_product_P002_v2.pth
• kan_product_P001_v1.pth
• transformer_product_P001_v1.pth

2. 店铺训练模式 (Store Mode)

{model_type}_store_{store_id}_{product_id}_{version}.pth

示例：

• tcn_store_S001_P001_v1.pth
• mlstm_store_S002_P001_v1.pth
• kan_store_S001_P002_v2.pth

3. 全局训练模式 (Global Mode)

{model_type}_global_{product_id}_{aggregation_method}_{version}.pth

示例：

• tcn_global_P001_sum_v1.pth
• mlstm_global_P001_mean_v1.pth
• transformer_global_P002_weighted_v1.pth

模型类型标识符

模型类型	标识符	说明
TCN	tcn	时间卷积网络
mLSTM	mlstm	多层长短期记忆网络
KAN	kan	Kolmogorov-Arnold网络
优化KAN	optimized_kan	优化版KAN网络
Transformer	transformer	注意力机制模型

聚合方法标识符

聚合方法	标识符	说明
求和	sum	所有店铺销量求和
平均	mean	所有店铺销量平均值
加权平均	weighted	基于店铺规模的加权平均
最大值	max	取各店铺最大销量

📁 目录结构

项目根目录/
├── saved_models/                    # 统一模型存储目录
│   ├── tcn_product_P001_v1.pth     # 产品模式模型
│   ├── tcn_store_S001_P001_v1.pth  # 店铺模式模型
│   ├── tcn_global_P001_sum_v1.pth  # 全局模式模型
│   └── ...                         # 其他模型文件
├── server/
│   └── utils/
│       └── model_manager.py        # 统一模型管理器
└── ...

📦 模型文件内容结构

每个模型文件包含以下标准化内容：

{
    # 模型状态
    'model_state_dict': {...},          # PyTorch模型参数
    
    # 数据预处理器
    'scaler_X': MinMaxScaler(...),      # 特征缩放器
    'scaler_y': MinMaxScaler(...),      # 目标变量缩放器
    
    # 模型配置
    'config': {
        'model_type': 'tcn',             # 模型类型
        'input_dim': 8,                  # 输入特征维度
        'output_dim': 7,                 # 输出维度
        'sequence_length': 30,           # 输入序列长度
        'forecast_horizon': 7,           # 预测时间窗口
        'hidden_size': 64,               # 隐藏层大小
        # ... 其他模型特定参数
    },
    
    # 评估指标
    'metrics': {
        'mse': 150.0,                    # 均方误差
        'rmse': 12.25,                   # 均方根误差
        'mae': 9.5,                      # 平均绝对误差
        'r2': 0.85,                      # 决定系数
        'mape': 15.2,                    # 平均绝对百分比误差
        'training_time': 45.6            # 训练时间(秒)
    },
    
    # 训练历史
    'loss_history': {
        'train': [0.8, 0.6, 0.4, ...],  # 训练损失历史
        'test': [0.9, 0.7, 0.5, ...],   # 测试损失历史
        'epochs': [1, 2, 3, ...]         # 轮次
    },
    
    # 管理信息
    'model_manager_info': {
        'product_id': 'P001',            # 产品ID
        'product_name': '感冒灵颗粒',     # 产品名称
        'model_type': 'tcn',             # 模型类型
        'version': 'v1',                 # 版本号
        'store_id': 'S001',              # 店铺ID (可选)
        'training_mode': 'product',      # 训练模式
        'aggregation_method': 'sum',     # 聚合方法 (可选)
        'created_at': '2025-06-21T22:03:23.357844',  # 创建时间
        'filename': 'tcn_product_P001_v1.pth'        # 文件名
    },
    
    # 其他信息
    'loss_curve_path': 'saved_models/TCN_product_感冒灵颗粒_loss_curve.png'  # 损失曲线图路径
}

🔧 模型管理器API

主要方法

1. 保存模型

model_path = model_manager.save_model(
    model_data=model_data,
    product_id='P001',
    model_type='tcn',
    version='v1',
    store_id='S001',                    # 可选，店铺模式需要
    training_mode='product',            # 'product', 'store', 'global'
    aggregation_method='sum',           # 可选，全局模式需要
    product_name='感冒灵颗粒'
)

2. 列出模型

# 列出所有模型
models = model_manager.list_models()

# 按条件过滤
models = model_manager.list_models(
    product_id='P001',                  # 按产品过滤
    model_type='tcn',                   # 按模型类型过滤
    store_id='S001',                    # 按店铺过滤
    training_mode='product'             # 按训练模式过滤
)

3. 解析文件名

info = model_manager.parse_model_filename('tcn_product_P001_v1.pth')
# 返回：
# {
#     'model_type': 'tcn',
#     'product_id': 'P001',
#     'version': 'v1',
#     'training_mode': 'product',
#     'store_id': None,
#     'aggregation_method': None
# }

4. 获取特定模型

model = model_manager.get_model_by_id('tcn_product_P001_v1')

🚀 版本管理策略

版本号规则

• v1: 初始版本
• v2, v3, ...: 后续优化版本
• 自动递增: 同一配置下重新训练自动生成新版本

版本冲突处理

• 相同产品、模型类型、训练模式的模型会自动生成新版本号
• 避免意外覆盖之前训练的模型
• 支持模型版本对比和回滚

📊 兼容性支持

支持的旧格式

系统可以解析和处理以下旧格式文件名：

• transformer_model_product_P001_v1.pth
• P001_mlstm_v1_global_model.pt
• kan_optimized_model_product_P001.pth

迁移策略

• 旧格式模型可以正常读取和使用
• 重新训练时会使用新的标准化命名
• 提供迁移工具将旧格式转换为新格式

🛠️ 使用示例

1. 训练并保存模型

from core.predictor import PharmacyPredictor

predictor = PharmacyPredictor()

# 产品模式训练
metrics = predictor.train_model(
    product_id='P001',
    model_type='tcn',
    epochs=50,
    training_mode='product'
)

# 店铺模式训练
metrics = predictor.train_model(
    product_id='P001',
    model_type='mlstm',
    epochs=50,
    training_mode='store',
    store_id='S001'
)

# 全局模式训练
metrics = predictor.train_model(
    product_id='P001',
    model_type='transformer',
    epochs=50,
    training_mode='global',
    aggregation_method='sum'
)

2. 加载和预测

from predictors.model_predictor import load_model_and_predict

# 使用特定模型进行预测
predictions = load_model_and_predict(
    product_id='P001',
    model_type='tcn',
    training_mode='product',
    store_id=None
)

📈 性能和监控

存储效率

• 统一目录避免文件分散
• 标准化命名便于查找和管理
• 支持大量模型文件的高效检索

元数据管理

• 每个模型包含完整的训练信息
• 支持模型性能对比和分析
• 便于模型版本管理和回滚

🔄 更新日志

v2.1.0 (2025-06-21)

• ✅ 实现统一模型命名规范
• ✅ 创建标准化模型管理器
• ✅ 支持三种训练模式的文件名格式
• ✅ 添加完整的元数据管理
• ✅ 实现版本自动管理
• ✅ 提供向后兼容性支持

---

注意事项：

1. 所有新训练的模型都将使用新的命名规范
2. 旧格式模型仍可正常使用，但建议逐步迁移
3. 模型文件保存在项目根目录的 saved_models/ 目录下
4. 删除模型时请确保相关损失曲线图片也被清理