xz2000
87df49f764
数据文件保存机构改为### 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`
61 lines
4.6 KiB
Markdown
61 lines
4.6 KiB
Markdown
# 为系统添加新模型的标准流程
|
||
|
||
本文档总结了向本项目中添加一个新的预测模型（以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`）。
|
||
|
||
遵循以上四个步骤，您就可以将任何新的预测模型一致、健壮地集成到现有系统中。 |