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

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

---

### 第1步：创建模型训练器

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

1.  **创建新文件**：在 [`server/trainers/`](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`](server/utils/multi_store_data_utils.py) 加载数据，并根据 `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`](server/trainers/__init__.py)。
    *   在文件顶部，从您的新训练器文件中导入训练函数，例如 `from .new_model_trainer import train_product_model_with_new_model`。
    *   在文件底部的 `__all__` 列表中，添加您的新训练函数名。

2.  **添加调度逻辑**：打开 [`server/core/predictor.py`](server/core/predictor.py)。
    *   在 `train_model` 方法中，找到 `if/elif` 逻辑块，为您的新模型添加一个新的 `elif model_type == 'new_model':` 分支，并在此分支中调用您的新训练函数。

---

### 第3步：实现预测逻辑

1.  **修改预测器**：打开 [`server/predictors/model_predictor.py`](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`](server/api.py)。
    *   在 `/api/training` 路由（`start_training` 函数）的 `valid_model_types` 列表中，添加您的新模型ID（例如 `'new_model'`）。
    *   在 `/api/model_types` 路由（`get_model_types` 函数）返回的列表中，添加您新模型的描述信息，以便它能显示在前端界面。

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

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