xz2000
5b2cdfa74a
**日期**: 2025-07-18
**主题**: 模型保存逻辑重构与集中化管理
### 目标
根据 `xz训练模型保存规则.md`，将系统中分散的模型文件保存逻辑统一重构，创建一个集中、健壮且可测试的路径管理系统。
### 核心成果
1. **创建了 `server/utils/file_save.py` 模块**: 这个新模块现在是系统中处理模型文件保存路径的唯一权威来源。
2. **实现了三种训练模式的路径生成**: 系统现在可以为“按店铺”、“按药品”和“全局”三种训练模式正确生成层级化的、可追溯的目录结构。
3. **集成了智能ID处理**:
* 对于包含**多个ID**的训练场景，系统会自动计算一个简短的哈希值作为目录名。
* 对于全局训练中只包含**单个店铺或药品ID**的场景，系统会直接使用该ID作为目录名，增强了路径的可读性。
4. **重构了整个训练流程**: 修改了API层、进程管理层以及所有模型训练器，使它们能够协同使用新的路径管理模块。
5. **添加了自动化测试**: 创建了 `test/test_file_save_logic.py` 脚本，用于验证所有路径生成和版本管理逻辑的正确性。
### 详细文件修改记录
1. **`server/utils/file_save.py`**
* **操作**: 创建
* **内容**: 实现了 `ModelPathManager` 类，包含以下核心方法：
* `_hash_ids`: 对ID列表进行排序和哈希。
* `_generate_identifier`: 根据训练模式和参数生成唯一的模型标识符。
* `get_next_version` / `save_version_info`: 线程安全地管理 `versions.json` 文件，实现版本号的获取和更新。
* `get_model_paths`: 作为主入口，协调以上方法，生成包含所有产物路径的字典。
2. **`server/api.py`**
* **操作**: 修改
* **位置**: `start_training` 函数 (`/api/training` 端点)。
* **内容**:
* 导入并实例化 `ModelPathManager`。
* 在接收到训练请求后，调用 `path_manager.get_model_paths()` 来获取所有路径信息。
* 将获取到的 `path_info` 字典和原始请求参数 `training_params` 一并传递给后台训练任务管理器。
* 修复了因重复传递关键字参数 (`model_type`, `training_mode`) 导致的 `TypeError`。
* 修复了 `except` 块中因未导入 `traceback` 模块导致的 `UnboundLocalError`。
3. **`server/utils/training_process_manager.py`**
* **操作**: 修改
* **内容**:
* 修改 `submit_task` 方法，使其能接收 `training_params` 和 `path_info` 字典。
* 在 `TrainingTask` 数据类中增加了 `path_info` 字段来存储路径信息。
* 在 `TrainingWorker` 中，将 `path_info` 传递给实际的训练函数。
* 在 `_monitor_results` 方法中，当任务成功完成时，调用 `path_manager.save_version_info` 来更新 `versions.json`，完成版本管理的闭环。
4. **所有训练器文件** (`mlstm_trainer.py`, `kan_trainer.py`, `tcn_trainer.py`, `transformer_trainer.py`)
* **操作**: 修改
* **内容**:
* 统一修改了主训练函数的签名，增加了 `path_info=None` 参数。
* 移除了所有内部手动构建文件路径的逻辑。
* 所有保存操作（最终模型、检查点、损失曲线图）现在都直接从传入的 `path_info` 字典中获取预先生成好的路径。
* 简化了 `save_checkpoint` 辅助函数，使其也依赖 `path_info`。
5. **`test/test_file_save_logic.py`**
* **操作**: 创建
* **内容**:
* 编写了一个独立的测试脚本，用于验证 `ModelPathManager` 的所有功能。
* 覆盖了所有训练模式及其子场景（包括单ID和多ID哈希）。
* 测试了版本号的正确递增和 `versions.json` 的写入。
* 修复了测试脚本中因绝对/相对路径不匹配和重复关键字参数导致的多个 `AssertionError` 和 `TypeError`。
---
**日期**: 2025-07-18 (后续修复)
**主题**: 修复API层调用路径管理器时的 `TypeError`
### 问题描述
在完成所有重构和测试后，实际运行API时，`POST /api/training` 端点在调用 `path_manager.get_model_paths` 时崩溃，并抛出 `TypeError: get_model_paths() got multiple values for keyword argument 'training_mode'`。
### 根本原因
这是一个回归错误。在修复测试脚本 `test_file_save_logic.py` 中的类似问题时，我未能将相同的修复逻辑应用回 `server/api.py`。代码在调用 `get_model_paths` 时，既通过关键字参数 `training_mode=...` 明确传递了该参数，又通过 `**data` 将其再次传入，导致了冲突。
### 解决方案
1. **文件**: `server/api.py`
2. **位置**: `start_training` 函数。
3. **操作**: 修改了对 `get_model_paths` 的调用逻辑。
4. **内容**:
```python
# 移除 model_type 和 training_mode 以避免重复关键字参数错误
data_for_path = data.copy()
data_for_path.pop('model_type', None)
data_for_path.pop('training_mode', None)
path_info = path_manager.get_model_paths(
training_mode=training_mode,
model_type=model_type,
**data_for_path # 传递剩余的payload
)
```
5. **原因**: 在通过 `**` 解包传递参数之前，先从字典副本中移除了所有会被明确指定的关键字参数，从而确保了函数调用签名的正确性。
---
**日期**: 2025-07-18 (最终修复)
**主题**: 修复因中间层函数签名未更新导致的 `TypeError`
### 问题描述
在完成所有重构后，实际运行API并触发训练任务时，程序在后台进程中因 `TypeError: train_model() got an unexpected keyword argument 'path_info'` 而崩溃。
### 根本原因
这是一个典型的“中间人”遗漏错误。我成功地修改了调用链的两端（`api.py` -> `training_process_manager.py` 和 `*_trainer.py`），但忘记了修改它们之间的中间层——`server/core/predictor.py` 中的 `train_model` 方法。`training_process_manager` 尝试将 `path_info` 传递给 `predictor.train_model`，但后者的函数签名中并未包含这个新参数，导致了 `TypeError`。
### 解决方案
1. **文件**: `server/core/predictor.py`
2. **位置**: `train_model` 函数的定义处。
3. **操作**: 在函数签名中增加了 `path_info=None` 参数。
4. **内容**:
```python
def train_model(self, ..., progress_callback=None, path_info=None):
# ...
```
5. **位置**: `train_model` 函数内部，对所有具体训练器（`train_product_model_with_mlstm`, `_with_kan`, etc.）的调用处。
6. **操作**: 在所有调用中，将接收到的 `path_info` 参数透传下去。
7. **内容**:
```python
# ...
metrics = train_product_model_with_transformer(
...,
path_info=path_info
)
# ...
```
8. **原因**: 通过在中间层函数上“打通”`path_info` 参数的传递通道，确保了从API层到最终训练器层的完整数据流，解决了 `TypeError`。
---
**日期**: 2025-07-18 (最终修复)
**主题**: 修复“按药品训练-聚合所有店铺”模式下的路径生成错误
### 问题描述
在实际运行中发现，当进行“按药品训练”并选择“聚合所有店铺”时，生成的模型保存路径中包含了错误的后缀 `_None`，而不是预期的 `_all` (例如 `.../17002608_None/...`)。
### 根本原因
在 `server/utils/file_save.py` 的 `_generate_identifier` 和 `get_model_paths` 方法中，当 `store_id` 从前端传来为 `None` 时，代码 `scope = store_id if store_id else 'all'` 会因为 `store_id` 是 `None` 而正确地将 `scope` 设为 `'all'`。然而，在 `get_model_paths` 方法中，我错误地使用了 `kwargs.get('store_id', 'all')`，这在 `store_id` 键存在但值为 `None` 时，仍然会返回 `None`，导致了路径拼接错误。
### 解决方案
1. **文件**: `server/utils/file_save.py`
2. **位置**: `_generate_identifier` 和 `get_model_paths` 方法中处理 `product` 训练模式的部分。
3. **操作**: 将逻辑从 `scope = kwargs.get('store_id', 'all')` 修改为更严谨的 `scope = store_id if store_id is not None else 'all'`。
4. **内容**:
```python
# in _generate_identifier
scope = store_id if store_id is not None else 'all'
# in get_model_paths
store_id = kwargs.get('store_id')
scope = store_id if store_id is not None else 'all'
scope_folder = f"{product_id}_{scope}"
```
5. **原因**: 这种写法能正确处理 `store_id` 键不存在、或键存在但值为 `None` 的两种情况，确保在这两种情况下 `scope` 都被正确地设置为 `'all'`，从而生成符合规范的路径。
---
**日期**: 2025-07-18 (最终修复)
**主题**: 修复 `KeyError: 'price'` 和单ID哈希错误
### 问题描述
在完成大规模重构后，实际运行时发现了两个隐藏的bug：
1. 在“按店铺训练”模式下，训练因 `KeyError: 'price'` 而失败。
2. 在“按店铺训练”模式下，当只选择一个“指定药品”时，系统仍然错误地对该药品的ID进行了哈希处理，而不是直接使用ID。
### 根本原因
1. **`KeyError`**: `server/utils/multi_store_data_utils.py` 中的 `get_store_product_sales_data` 函数包含了一个硬编码的列校验，该校验要求 `price` 列必须存在，但这与当前的数据源不符。
2. **哈希错误**: `server/utils/file_save.py` 中的 `get_model_paths` 方法在处理 `store` 训练模式时，没有复用 `_generate_identifier` 中已经写好的单ID判断逻辑，导致了逻辑不一致。
### 解决方案
1. **修复 `KeyError`**:
* **文件**: `server/utils/multi_store_data_utils.py`
* **位置**: `get_store_product_sales_data` 函数。
* **操作**: 从 `required_columns` 列表中移除了 `'price'`，根除了这个硬性依赖。
2. **修复哈希逻辑**:
* **文件**: `server/utils/file_save.py`
* **位置**: `_generate_identifier` 和 `get_model_paths` 方法中处理 `store` 训练模式的部分。
* **操作**: 统一了逻辑，确保在这两个地方都使用了 `scope = product_ids[0] if len(product_ids) == 1 else self._hash_ids(product_ids)` 的判断，从而在只选择一个药品时直接使用其ID。
3. **更新测试**:
* **文件**: `test/test_file_save_logic.py`
* **操作**: 增加了新的测试用例，专门验证“按店铺训练-单个指定药品”场景下的路径生成是否正确。
---
**日期**: 2025-07-18 (最终修复)
**主题**: 修复全局训练范围值不匹配导致的 `ValueError`
### 问题描述
在完成所有重构后，实际运行API并触发“全局训练-所有店铺所有药品”时，程序因 `ValueError: 未知的全局训练范围: all_stores_all_products` 而崩溃。
### 根本原因
前端传递的 `training_scope` 值为 `all_stores_all_products`，而 `server/utils/file_save.py` 中的 `_generate_identifier` 和 `get_model_paths` 方法只处理了 `all` 这个值，未能兼容前端传递的具体字符串，导致逻辑判断失败。
### 解决方案
1. **文件**: `server/utils/file_save.py`
2. **位置**: `_generate_identifier` 和 `get_model_paths` 方法中处理 `global` 训练模式的部分。
3. **操作**: 将逻辑判断从 `if training_scope == 'all':` 修改为 `if training_scope in ['all', 'all_stores_all_products']:`。
4. **原因**: 使代码能够同时兼容两种表示“所有范围”的字符串，确保了前端请求的正确处理。
5. **更新测试**:
* **文件**: `test/test_file_save_logic.py`
* **操作**: 增加了新的测试用例，专门验证 `training_scope` 为 `all_stores_all_products` 时的路径生成是否正确。
---
**日期**: 2025-07-18 (最终优化)
**主题**: 优化全局训练自定义模式下的单ID路径生成
### 问题描述
根据用户反馈，希望在全局训练的“自定义范围”模式下，如果只选择单个店铺和/或单个药品，路径中应直接使用ID而不是哈希值，以增强可读性。
### 解决方案
1. **文件**: `server/utils/file_save.py`
2. **位置**: `_generate_identifier` 和 `get_model_paths` 方法中处理 `global` 训练模式 `custom` 范围的部分。
3. **操作**: 为 `store_ids` 和 `product_ids` 分别增加了单ID判断逻辑。
4. **内容**:
```python
# in _generate_identifier
s_id = store_ids[0] if len(store_ids) == 1 else self._hash_ids(store_ids)
p_id = product_ids[0] if len(product_ids) == 1 else self._hash_ids(product_ids)
scope_part = f"custom_s_{s_id}_p_{p_id}"
# in get_model_paths
store_ids = kwargs.get('store_ids', [])
product_ids = kwargs.get('product_ids', [])
s_id = store_ids[0] if len(store_ids) == 1 else self._hash_ids(store_ids)
p_id = product_ids[0] if len(product_ids) == 1 else self._hash_ids(product_ids)
scope_parts.extend(['custom', s_id, p_id])
```
5. **原因**: 使 `custom` 模式下的路径生成逻辑与 `selected_stores` 和 `selected_products` 模式保持一致，在只选择一个ID时优先使用ID本身，提高了路径的可读性和一致性。
6. **更新测试**:
* **文件**: `test/test_file_save_logic.py`
* **操作**: 增加了新的测试用例，专门验证“全局训练-自定义范围-单ID”场景下的路径生成是否正确。
药店销售预测系统
这是一个基于多种深度学习模型的药店销售预测系统，支持多种时序预测模型，包括 Transformer、mLSTM、KAN 和 TCN。
功能特点
- 支持多种深度学习模型进行销量预测
- 提供命令行界面和API服务两种使用方式
- 支持模型训练、预测和评估
- 提供预测结果可视化和分析
- 支持模型比较和管理
项目结构
├── core/ # 核心模块
│ ├── __init__.py
│ ├── config.py # 全局配置参数
│ └── predictor.py # 核心预测器类
├── trainers/ # 模型训练器
│ ├── __init__.py
│ ├── mlstm_trainer.py # mLSTM模型训练函数
│ ├── kan_trainer.py # KAN模型训练函数
│ ├── tcn_trainer.py # TCN模型训练函数
│ └── transformer_trainer.py # Transformer模型训练函数
├── predictors/ # 预测模块
│ ├── __init__.py
│ └── model_predictor.py # 模型预测函数
├── analysis/ # 分析模块
│ ├── __init__.py
│ ├── metrics.py # 评估指标计算函数
│ ├── trend_analysis.py # 趋势分析函数
│ └── explanation.py # 预测解释函数
├── utils/ # 工具模块
│ ├── __init__.py
│ ├── data_utils.py # 数据处理工具函数
│ └── visualization.py # 可视化工具函数
├── models/ # 模型定义
│ ├── transformer_model.py
│ ├── mlstm_model.py
│ ├── kan_model.py
│ ├── tcn_model.py
│ └── optimized_kan_forecaster.py
├── pharmacy_predictor.py # 主接口文件
├── run_pharmacy_prediction.py # 命令行运行入口
├── api.py # API服务入口
└── pharmacy_sales.xlsx # 示例数据文件
支持的模型
- Transformer: 基于自注意力机制的时序预测模型
- mLSTM: 矩阵LSTM模型，结合了LSTM和Transformer的优点
- KAN: Kolmogorov-Arnold Network，一种基于柯尔莫哥洛夫-阿诺德定理的神经网络
- TCN: 时间卷积网络，使用因果卷积进行时序建模
- 优化版KAN: 经过优化的KAN模型，提高了预测精度和训练效率
使用方法
命令行界面
运行命令行界面：
python run_pharmacy_prediction.py
API服务
启动API服务：
python api.py
代码中使用
from pharmacy_predictor import PharmacyPredictor
# 创建预测器实例
predictor = PharmacyPredictor(data_path='pharmacy_sales.xlsx')
# 训练模型
metrics = predictor.train_model(product_id='P001', model_type='tcn', epochs=50)
# 使用模型预测
result = predictor.predict(product_id='P001', model_type='tcn', future_days=7, analyze_result=True)
依赖库
- PyTorch
- pandas
- numpy
- matplotlib
- scikit-learn
- Flask (用于API服务)
- pytorch-tcn (用于TCN模型)