174 lines
12 KiB
Markdown
174 lines
12 KiB
Markdown
# 智能药品销售预测系统：技术白皮书与核心SOP
|
||
|
||
## 1. 项目概述
|
||
|
||
本文档旨在为新成员提供一个全面的、由浅入深的项目技术指南，并系统性地沉淀项目在迭代演进过程中的核心设计思想、关键决策和标准作业程序（SOP）。
|
||
|
||
### 1.1. 核心价值
|
||
|
||
本系统是一个基于深度学习和机器学习模型的智能预测平台，旨在解决药品零售行业的核心痛点：
|
||
|
||
* **精准库存管理**：通过对未来销量的精确预测，指导采购与备货，降低库存成本，避免缺货损失。
|
||
* **智能化决策支持**：为营销活动、人员排班、资金规划等提供量化的、数据驱动的决策依据。
|
||
* **多维度洞察**：支持从“单品”、“店铺”到“区域全局”等多个维度进行训练和预测，满足不同层级的业务分析需求。
|
||
|
||
### 1.2. 技术栈
|
||
|
||
* **后端**: Python, Flask, Socket.IO, SQLAlchemy
|
||
* **前端**: Vue.js, Element Plus, Chart.js
|
||
* **AI框架**: PyTorch, XGBoost, Scikit-learn
|
||
* **核心模型**: Transformer, KAN, mLSTM, TCN, CNN-BiLSTM-Attention, XGBoost
|
||
* **数据存储**: SQLite (用于历史记录), Parquet (用于核心时序数据)
|
||
* **版本与进程管理**: 自研的 `ModelManager` 和 `TrainingProcessManager`
|
||
|
||
---
|
||
|
||
## 2. 核心架构设计
|
||
|
||
系统采用经典的前后端分离架构，并通过模块化的设计，实现了业务逻辑、AI能力与数据处理的有效解耦。
|
||
|
||
### 2.1. 架构分层图
|
||
|
||
```
|
||
+---------------------+ +-----------------------+ +---------------------+
|
||
| 前端 (UI) | <--> | API层 (Flask) | <--> | 核心逻辑层 |
|
||
| (Vue.js, Chart.js) | | (api.py, Socket.IO) | | (predictor.py) |
|
||
+---------------------+ +-----------------------+ +---------------------+
|
||
| |
|
||
| |
|
||
+-------------------------------------------------------+
|
||
|
|
||
v
|
||
+--------------------------+ +---------------------------+
|
||
| AI能力层 (Trainers) | <--> | 模型与算法 (Models) |
|
||
| (kan_trainer.py, etc.) | | (kan_model.py, etc.) |
|
||
+--------------------------+ +---------------------------+
|
||
| |
|
||
| |
|
||
v v
|
||
+-------------------------------------------------------------------+
|
||
| 数据与工具层 (Utils) |
|
||
| (new_data_loader.py, model_manager.py, training_process_manager.py) |
|
||
+-------------------------------------------------------------------+
|
||
|
|
||
v
|
||
+--------------------------+ +---------------------------+
|
||
| 数据存储 (Storage) | | 原始数据 (Data) |
|
||
| (prediction_history.db) | | (*.parquet) |
|
||
+--------------------------+ +---------------------------+
|
||
```
|
||
|
||
### 2.2. 核心工作流：“数据 -> 智能”的闭环
|
||
|
||
1. **数据加载**: 所有的数据请求都由 `server/utils/new_data_loader.py` 统一处理。
|
||
2. **模型训练**:
|
||
* 前端通过 **API层** 发起训练请求。
|
||
* **进程管理器** (`TrainingProcessManager`) 创建一个独立的后台进程来处理该任务。
|
||
* **核心逻辑层** (`predictor.py`) 根据请求参数（如训练模式、范围），从数据加载器获取并预处理数据。
|
||
* **AI能力层** (具体的 `trainer.py`) 被调用，负责执行模型的训练、评估和保存。
|
||
* **模型管理器** (`ModelManager`) 负责将训练好的模型，以统一、规范的命名格式保存到磁盘。
|
||
3. **模型预测**:
|
||
* 前端通过 **API层** 发起预测请求。
|
||
* **模型管理器** 根据请求参数找到正确的模型文件。
|
||
* **核心预测器** (`model_predictor.py`) 加载模型，并从数据加载器获取预测所需的历史数据。
|
||
* 根据模型类型（自回归 vs 直接输出），执行相应的预测逻辑。
|
||
* 结果通过 **API层** 返回给前端，并在数据库中留下历史记录。
|
||
4. **结果可视化**: 前端使用 `Chart.js` 将API返回的历史数据和预测数据渲染成趋势图。
|
||
|
||
---
|
||
|
||
## 3. 项目演进全景回顾
|
||
|
||
### 第一阶段：奠基与探索 (早期修复与重构)
|
||
|
||
此阶段的核心目标是**打通系统最基础的“训练->预测”闭环**，并解决一系列阻碍核心功能运行的初始Bug。
|
||
|
||
* **设计思路**：采用“问题驱动”的模式，从最表层的UI失败开始，逐层深入，定位并修复了从数据流、模型算法到前后端通信的多个核心问题。
|
||
* **关键改动与修复**：
|
||
1. **数据流重构**：修复了 `predictor.py` 中数据处理流程中断，导致特征丢失的根本性问题。
|
||
2. **模型算法修复**：
|
||
* 根治了所有PyTorch模型因**维度不匹配**而无法学习（R²恒为0）的严重Bug。
|
||
* 修复了 `mLSTM` 模型因**算法设计缺陷**导致预测结果无效的问题。
|
||
3. **配置持久化**：系统性地修复了所有训练器，确保在保存模型时，会将**完整的、可用于重新实例化模型的配置**写入检查点，解决了除Transformer外所有模型预测失败的问题。
|
||
4. **版本管理统一**：引入了 `ModelManager` 作为系统中**唯一**负责版本管理、模型命名和IO的组件，彻底解决了因命名和路径不统一导致模型无法被找到的混乱状况。
|
||
5. **前后端链路打通**：通过修复**JSON序列化**、**API响应结构**、**数据时间戳连续性**和**图表日期格式化**等一系列问题，最终成功实现了所有预测视图的图表渲染。
|
||
|
||
### 第二阶段：涅槃与重生 (核心数据源替换)
|
||
|
||
此阶段的核心目标是将项目的数据源，从一个简单的、理想化的样本数据，彻底更换为**全新的、结构更复杂、更贴近真实业务场景的核心数据集**。这是一次“换引擎”级别的大手术。
|
||
|
||
#### **“更换数据源”标准作业程序 (SOP)**
|
||
|
||
我们在此次重构中，沉淀出了一套可复用的、用于安全更换核心数据源的SOP。
|
||
|
||
**第1步：分析与评估 (Analysis & Assessment)**
|
||
|
||
* **目标**：全面理解新旧数据源的差异，识别风险，制定策略。
|
||
* **动作**：
|
||
* 对比新旧 `.parquet` 文件的Schema（表结构）。
|
||
* 识别出**“断裂性变更”**，例如：列名不同 (`subbh` vs `store_id`)、数据类型变化、特征缺失（如 `is_promotion`）。
|
||
* **决策**：放弃“直接修改代码以适应新数据”的高风险方案，选择**“适配器模式”**，以最小的侵入性实现兼容。
|
||
|
||
**第2步：构建数据适配器 (Adapter Construction)**
|
||
|
||
* **目标**：创建一个独立的、统一的数据入口，将“新数据”动态转换为“旧代码能理解的格式”。
|
||
* **动作**：
|
||
* 创建 `server/utils/new_data_loader.py`。
|
||
* 在该模块中，集中实现所有的数据转换逻辑：
|
||
* **列名重映射**：`{'subbh': 'store_id', 'hh': 'product_id', ...}`。
|
||
* **特征填充**：为缺失的 `is_promotion` 列创建代理并填充默认值 `0`。
|
||
* **数据类型转换**：将日期列统一转换为 `datetime` 对象。
|
||
|
||
**第3步：全面重构 (Refactoring)**
|
||
|
||
* **目标**：将系统中所有直接读取旧数据的代码，全部重构为通过新的数据适配器获取数据。
|
||
* **动作**：
|
||
* 系统性地修改了所有数据消费端，包括：`api.py`, `core/predictor.py`, 以及 `trainers/` 目录下的**所有**训练器脚本。
|
||
* 删除了所有旧的、已废弃的数据加载工具，确保了数据源的唯一性。
|
||
|
||
**第4步：端到端测试与迭代修复 (E2E Testing & Iterative Fixing)**
|
||
|
||
* **目标**：在新数据源上，对系统的所有核心功能（所有训练模式、所有预测模式）进行完整测试，并修复因此次变更而引发的所有连锁Bug。
|
||
* **关键修复成果**：
|
||
* **`NaN`值处理**：在聚合运算（如“按店铺训练”）后，增加了 `.fillna(0)` 数据清理步骤，解决了因数据稀疏性引入`NaN`值而导致的训练失败。
|
||
* **架构错配修复**：
|
||
* **问题**：`XGBoost` 和 `CnnBiLstmAttention` 模型在预测时，被错误地调用了为“自回归”模型设计的循环预测逻辑，导致在自定义预测天数时崩溃或返回无效结果。
|
||
* **修复**：在 `model_predictor.py` 中为这两类“直接多步输出”模型创建了**专属的、正确的、非循环的**预测逻辑分支。
|
||
* **全链路参数传递修复**：
|
||
* **问题**：“自定义全局训练”功能因新增的 `selected_stores` 和 `selected_products` 参数在 `api.py` -> `training_process_manager.py` -> `predictor.py` 的调用链中丢失而失败。
|
||
* **修复**：对整条调用链上的所有相关模块进行了**同步升级**，确保了复杂参数的完整、正确传递。
|
||
* **数据特性澄清**：确认了“负销量”是源于真实业务（如退货）的数据特性，并决策在代码层面**尊重**而非修改它，这是一个重要的技术决策。
|
||
|
||
**第5步：环境清理 (Environment Cleanup)**
|
||
|
||
* **目标**：在最终验证前，确保一个完全纯净的、不受任何旧数据或旧模型干扰的系统环境。
|
||
* **动作**：
|
||
* 删除了 `saved_models` 和 `saved_predictions` 文件夹中的所有历史产物。
|
||
* 删除了 `prediction_history.db` 数据库文件，并验证了系统具备自动重建的能力。
|
||
|
||
### 第三阶段：展望 (模型优化与能力升级)
|
||
|
||
在当前稳定的系统基础上，我们规划了以下四个方向的重点工作，以进一步提升系统的核心价值。
|
||
|
||
1. **特征工程**：通过创造时间特征、滞后特征和滑动平均特征，充分挖掘新数据源的潜力，提升模型预测精度。
|
||
2. **模型可解释性**：引入SHAP等工具，让AI模型不再是“黑盒”，为每一次预测提供清晰、量化的归因分析。
|
||
3. **超参数调优**：引入Optuna等自动化调优框架，为每个模型找到其最佳的超参数组合，进一步压榨模型性能。
|
||
4. **架构限制突破**：通过改造训练器和API，最终实现让所有模型都能在**训练时**自由指定预测天数，提升系统的灵活性和易用性。
|
||
|
||
---
|
||
|
||
## 4. 系统维护与扩展
|
||
|
||
### 4.1. 如何引入一个新模型？
|
||
|
||
1. **创建模型文件**：在 `server/models/` 目录下，创建一个新的模型定义文件（如 `new_model.py`），确保它是一个标准的PyTorch `nn.Module`。
|
||
2. **创建训练器文件**：在 `server/trainers/` 目录下，创建一个新的训练器文件（如 `new_model_trainer.py`）。
|
||
* 参考现有训练器的结构，实现完整的“数据准备->训练循环->评估->保存”逻辑。
|
||
* 在文件末尾，使用 `@register_trainer('new_model_id', train_function)` 将其注册到系统中。
|
||
3. **（可选）创建专属预测器**：如果你的新模型不是标准的“自回归”模型（像XGBoost那样），则需要在 `server/predictors/model_predictor.py` 中为其创建一个专属的预测逻辑分支。
|
||
4. **更新API**：`api.py` 会自动通过注册表发现你的新模型，无需修改。
|
||
|
||
### 4.2. 系统清理与数据管理
|
||
|
||
* **清理旧模型**：可以直接删除 `saved_models/` 目录下的 `.pth` 文件。
|
||
* **清理旧预测**：可以安全地删除 `saved_predictions/` 目录下的 `.json` 文件和根目录下的 `prediction_history.db` 数据库文件。系统会在下次运行时自动重建。 |