ShopTRAINING/xz模型添加流程.md

为系统添加新模型的标准流程

本文档总结了向本项目中添加一个新的预测模型（以XGBoost为例）的标准流程，旨在为未来的开发工作提供清晰、可复用的路线图。

---

第1步：创建模型训练器

这是最核心的一步，负责实现新模型的训练逻辑。

1. 创建新文件：在 server/trainers/ 目录下，创建一个新的Python文件，例如 new_model_trainer.py。

2. 定义训练函数：在该文件中，定义一个核心的训练函数，遵循项目的标准签名，接收 product_id, store_id, epochs, path_info 等参数。

3. 实现函数内部逻辑：

   • 数据加载：使用 utils.multi_store_data_utils.load_multi_store_data 加载数据，并根据 product_id 和 store_id 进行筛选。
   • 数据预处理：将时间序列数据转换为监督学习格式。对于像XGBoost这样的模型，这意味着创建一个“滑动窗口”（如我们实现的 create_dataset 函数）。
   • 数据缩放 (关键)：必须使用 sklearn.preprocessing.MinMaxScaler 对特征 (X) 和目标 (y) 进行归一化。创建并训练 scaler_X 和 scaler_y 两个缩放器。
   • 模型训练：初始化您的新模型，并使用归一化后的数据进行训练。
   • 生成损失曲线 (可选但推荐)：如果模型支持，在训练过程中捕获训练集和验证集的损失，然后使用 matplotlib 绘制损失曲线图，并将其保存为 ..._loss_curve.png。
   • 保存检查点 (可选但推荐)：如果模型支持回调（Callbacks），可以实现一个自定义回调函数，用于按指定轮次间隔保存模型检查点 (..._checkpoint_epoch_{N}.pth)。
   • 模型评估：使用反归一化后的预测结果来计算评估指标（RMSE, R2等）。
   • 模型保存 (关键)：
     • 创建一个字典（payload），必须包含以下内容：'model' (训练好的模型对象), 'config' (训练配置), 'scaler_X' (特征缩放器), 和 'scaler_y' (目标缩放器)。
     • 使用正确的库（PyTorch模型用 torch.save，其他模型如XGBoost用 joblib.dump）将这个字典保存到 path_info['model_path'] 指定的路径。文件名统一使用 .pth 扩展名。

---

第2步：将训练器集成到系统中

1. 注册训练器：打开 server/trainers/__init__.py。

   • 在文件顶部，从您的新训练器文件中导入训练函数，例如 from .new_model_trainer import train_product_model_with_new_model。
   • 在文件底部的 __all__ 列表中，添加您的新训练函数名。

2. 添加调度逻辑：打开 server/core/predictor.py。

   • 在 train_model 方法中，找到 if/elif 逻辑块，为您的新模型添加一个新的 elif model_type == 'new_model': 分支，并在此分支中调用您的新训练函数。

---

第3步：实现预测逻辑

1. 修改预测器：打开 server/predictors/model_predictor.py。
2. 添加预测分支：在 load_model_and_predict 函数中，找到 if/elif 逻辑块，为您的新模型添加一个新的 elif model_type == 'new_model': 分支。
3. 实现分支内部逻辑：
   • 使用与保存时相同的库（例如 joblib.load）加载 .pth 模型文件。
   • 从加载的字典中，必须提取出 model, config, scaler_X, 和 scaler_y。
   • 准备用于预测的输入数据（例如，最近N天的数据）。
   • 在进行预测时，必须先用 scaler_X.transform 对输入数据进行归一化。
   • 得到模型的预测结果后，必须用 scaler_y.inverse_transform 将结果反归一化，以得到真实的预测值。

---

第4步：更新API和依赖项

1. 更新API端点：打开 server/api.py。

   • 在 /api/training 路由（start_training 函数）的 valid_model_types 列表中，添加您的新模型ID（例如 'new_model'）。
   • 在 /api/model_types 路由（get_model_types 函数）返回的列表中，添加您新模型的描述信息，以便它能显示在前端界面。

2. 更新依赖：打开 requirements.txt 文件，添加您的新模型所需要的Python库（例如 xgboost）。

遵循以上四个步骤，您就可以将任何新的预测模型一致、健壮地集成到现有系统中。