ShopTRAINING/README.md

# 🏪 药店单品销售预测系统

## 📋 项目简介

这个项目使用先进的深度学习模型，对药店单品销售进行预测，帮助药店管理者进行更精准的库存管理和销售规划。系统利用历史销售数据，结合季节性、促销、天气等因素，预测未来7天的单品销售量。

## 📋 系统特点

- **多模型支持**：结合使用Transformer、扩展型LSTM(sLSTM)、矩阵LSTM(mLSTM)和Kolmogorov-Arnold网络(KAN)进行预测
- **内存优化**：提供优化版KAN模型，显著降低内存占用，提高训练速度
- **GPU加速**：自动检测并使用GPU加速模型训练和预测
- **高精度预测**：综合多种因素，提供更准确的销售预测
- **可视化分析**：自动生成预测结果图表和评估指标
- **灵活配置**：可以针对不同药品选择不同的预测模型
- **友好用户界面**：提供简单易用的命令行交互界面
- **完善的模型管理功能**：可以管理多个模型，包括查看、比较和删除模型

## 🚀 安装指南

### 前提条件

- Python 3.8+
- PyTorch 1.7+
- pandas, numpy, matplotlib, scikit-learn
- tqdm
- 如需GPU加速：NVIDIA GPU + CUDA

### 安装步骤

#### Windows

1. 克隆或下载本仓库
2. 运行安装脚本选择安装版本：
   ```
   install_dependencies.bat
   ```

#### Linux/Mac

1. 克隆或下载本仓库
2. 为安装脚本添加执行权限并运行：
   ```bash
   chmod +x install_dependencies.sh
   ./install_dependencies.sh
   ```

### 手动安装

如果你想手动安装依赖，可以根据你的环境选择以下命令之一：

- CPU版本：
  ```
  pip install -r requirements.txt
  ```

- GPU版本 (CUDA 12.1)：
  ```
  pip install numpy==2.3.0 pandas==2.3.0 matplotlib==3.10.3 scikit-learn==1.7.0 tqdm==4.67.1 openpyxl==3.1.5
  pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu121
  ```

- GPU版本 (CUDA 11.8)：
  ```
  pip install numpy==2.3.0 pandas==2.3.0 matplotlib==3.10.3 scikit-learn==1.7.0 tqdm==4.67.1 openpyxl==3.1.5
  pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu118
  ```

### 检查GPU支持

安装完成后，可以运行以下命令检查GPU支持状态：
```
python check_gpu.py
```

## 🚀 使用方法

1. 启动系统：
   ```
   python run_pharmacy_prediction.py
   ```

2. 按照交互式菜单选择操作：
   - 训练所有药品的销售预测模型
   - 训练单个药品的销售预测模型（Transformer、mLSTM、KAN或优化版KAN）
   - 比较原始KAN和优化版KAN模型性能
   - 查看已有预测结果
   - 使用已训练的模型进行预测
   - 比较不同模型的预测结果
   - 模型管理
   - 退出

## 📊 数据说明

系统使用的数据包含以下特征：
- 日期
- 产品ID和名称
- 销售量
- 价格
- 星期几
- 月份
- 是否节假日
- 是否周末
- 是否促销
- 气温

首次运行时，系统会自动生成模拟数据进行测试。

## 🧠 模型介绍

- **Transformer**：基于自注意力机制的序列处理模型，能有效捕获时间序列中的长期依赖关系
- **标量LSTM (sLSTM)**：改进版LSTM，增强了对突变点的处理能力和稳定性
- **矩阵LSTM (mLSTM)**：使用矩阵代替标量存储隐藏状态，提高模型表达能力
- **KAN**：基于柯尔莫哥洛夫-阿诺尔德定理的神经网络，能有效学习复杂非线性映射
- **优化版KAN**：在原始KAN基础上进行内存优化，显著降低内存占用，提高训练速度，适用于大规模数据集

## 📁 文件结构

- `run_pharmacy_prediction.py` - 主程序入口
- `pharmacy_predictor.py` - 核心预测功能实现
- `generate_pharmacy_data.py` - 生成模拟数据
- `check_gpu.py` - 检查GPU支持状态
- `models/` - 模型实现目录
  - `transformer_model.py` - Transformer模型实现
  - `slstm_model.py` - 标量LSTM模型实现
  - `mlstm_model.py` - 矩阵LSTM模型实现
  - `kan_model.py` - KAN模型实现
  - `optimized_kan_forecaster.py` - 优化版KAN模型实现
  - `data_utils.py` - 数据处理工具
  - `utils.py` - GPU加速工具

## 🔄 模型对比

系统支持四种主要的模型训练方式：

1. **基于Transformer的标准模型**: 默认训练方式，适合大多数预测任务
2. **mLSTM增强模型**: 结合了矩阵LSTM和Transformer的混合模型，在捕捉复杂季节性和非线性模式方面可能表现更佳
3. **KAN模型**: Kolmogorov-Arnold网络，利用B样条基函数自适应学习非线性关系，特别适合捕捉数据中的复杂非线性模式和季节性变化
4. **优化版KAN模型**: 在原始KAN基础上进行内存优化，显著降低内存占用，提高训练速度，适用于大规模数据集和资源受限的环境

您可以通过启动脚本中的选项选择不同的模型进行训练，并比较它们的预测效果。系统还提供了专门的功能来比较原始KAN和优化版KAN的性能差异。

## 👨‍💻 自定义数据

如果你想使用自己的数据，只需将数据保存为与模拟数据相同格式的Excel文件，命名为`pharmacy_sales.xlsx`，放在项目根目录下即可。

## 📊 评估指标

- **MSE**: 均方误差
- **RMSE**: 均方根误差
- **MAE**: 平均绝对误差
- **R²**: 决定系数
- **MAPE**: 平均绝对百分比误差

## 🔮 未来改进

- 增加更多类型的预测模型
- 添加季节性分解分析
- 实现Web界面
- 支持导入/导出模型
- 添加库存优化建议

## 📄 模型管理功能

系统提供了强大的模型管理功能，可以通过以下方式使用：

1. 在主程序中选择"模型管理"选项
2. 或直接运行模型管理工具：

```bash
python model_management.py
```

### 模型管理功能包括：

- **查看所有模型**：列出系统中所有已保存的模型
- **查看特定产品的模型**：列出特定产品的所有模型
- **查看模型详情**：查看模型的详细信息，包括训练参数、评估指标等
- **使用模型预测**：使用选定的模型进行预测
- **比较不同模型**：比较不同模型的预测结果
- **删除模型**：删除不需要的模型
- **导出/导入模型**：导出模型以共享或导入外部模型

模型管理工具还支持命令行参数，方便批处理和自动化操作：

```bash
# 列出所有模型
python model_management.py --action list

# 查看特定产品的模型详情
python model_management.py --action details --product_id P001 --model_type mlstm

# 使用特定模型进行预测
python model_management.py --action predict --product_id P001 --model_type mlstm

# 比较不同模型的预测结果
python model_management.py --action compare --product_id P001 --compare_models mlstm,kan,transformer

# 删除模型
python model_management.py --action delete --product_id P001 --model_type mlstm

# 导出模型
python model_management.py --action export --product_id P001 --model_type mlstm --export_dir exported_models

# 导入模型
python model_management.py --action import --file_path path/to/model.pt
```

## 📄 贡献

欢迎提交问题报告和功能建议！

## 📄 许可证

MIT许可证

## 🌐 API服务

系统提供了完整的RESTful API服务，支持所有药店销售预测功能，方便集成到其他系统中。

### API服务安装

```bash
# Windows
install_api_dependencies.bat

# Linux/Mac
chmod +x install_api_dependencies.sh
./install_api_dependencies.sh
```

### 启动API服务

```bash
python api.py
```

默认情况下，API服务会在 http://localhost:5000 上运行，并启用Swagger UI文档界面。

### API参数选项

```bash
# 指定主机和端口
python api.py --host 127.0.0.1 --port 8080

# 禁用Swagger UI
python api.py --swagger false

# 禁用调试模式
python api.py --debug false
```

### API文档

启动服务后，访问 http://localhost:5000 将自动重定向到Swagger UI文档界面，可以查看所有API接口说明并进行测试。

API服务提供以下功能组：
- 数据管理API：上传和查询销售数据
- 模型训练API：训练销售预测模型
- 模型预测API：使用模型进行预测
- 模型管理API：管理已训练的模型