ShopTRAINING/项目快速上手指南.md

10 KiB
Raw Blame History

项目快速上手指南 (v2.0 - 2025年7月版)

欢迎加入项目!本指南旨在帮助你快速理解项目的核心功能、最新的技术架构和开发流程。

1. 项目核心功能

这是一个基于历史销售数据的 智能销售预测系统,其核心是实现一个 "数据 -> 训练 -> 模型 -> 预测 -> 可视化" 的完整闭环。

所有功能均通过Web界面操作

  1. 模型训练: 用户可以选择某个药品、某个店铺全局数据然后选择一种机器学习算法如Transformer、KAN等进行训练。训练过程是异步并能通过WebSocket实时反馈进度。
  2. 销售预测: 使用已经训练好的模型,对未来的销量进行预测。
  3. 结果可视化: 将历史销量和预测销量在同一个图表中展示出来,方便用户直观地看到趋势。
  4. 模型与历史管理: 提供对已训练模型和历史预测记录的查询、详情查看和删除功能。

2. 技术栈

层面 本项目技术 说明
后端框架 Flask 轻量级的Python Web框架用于提供API接口。
前端框架 Vue.js 用于构建用户交互界面的现代化JavaScript框架。
核心算法库 PyTorch 实现深度学习算法的核心库。
数据处理 Pandas Python中用于数据分析和处理的核心库。
数据库 SQLite 一个轻量级的本地文件数据库,用于记录模型元数据和预测历史。
实时通信 Flask-SocketIO 用于后端在训练时向前端实时推送日志和进度。
异步任务 multiprocessing Python标准库用于将耗时的训练任务放到独立的子进程中执行避免阻塞API服务。

3. 系统架构与数据流

本项目是经典的前后端分离架构,其数据流和核心组件如下:

+-----------------------------------------------------------------+
|                      用户 (Browser - Vue.js)                      |
+-----------------------------------------------------------------+
      | (1. HTTP/WebSocket请求)
+-----------------------------------------------------------------+
|                 后端API层 (Backend API - Flask)                   |
|   - api.py: 定义所有RESTful接口 (e.g., /api/training)           |
|   - 接收请求, 验证参数, 调用核心服务层                           |
+-----------------------------------------------------------------+
      | (2. 调用核心服务)
+-----------------------------------------------------------------+
|                  核心服务与管理层 (Core Services)                  |
|   - training_process_manager.py: 异步训练任务管理器 (关键)      |
|   - model_manager.py: 模型保存、加载、版本控制 (关键)           |
|   - model_registry.py: 算法与训练器的注册表 (关键)              |
+-----------------------------------------------------------------+
      | (3. 执行具体任务)
+-----------------------------------------------------------------+
|                算法实现与数据处理层 (Algorithm & Data)             |
|   - trainers/*.py: 具体的算法训练逻辑 (e.g., kan_trainer.py)    |
|   - predictors/model_predictor.py: 模型加载与预测逻辑           |
|   - models/*.py: PyTorch模型定义 (e.g., kan_model.py)           |
|   - utils/data_utils.py: 数据预处理和转换工具                   |
+-----------------------------------------------------------------+
      | (4. 读写物理文件)
+-----------------------------------------------------------------+
|                       物理存储层 (Storage)                        |
|   - data/*.parquet: 原始时序数据                                |
|   - saved_models/*.pth: 训练好的模型文件 (权重、配置、缩放器)     |
|   - saved_predictions/*.json: 详细的预测结果文件                |
|   - prediction_history.db: SQLite数据库 (存储元数据)            |
+-----------------------------------------------------------------+

4. 核心工作流详解:“数据 -> 训练 -> 预测”

步骤一:数据准备

步骤二:模型训练 (异步)

  1. API触发: 前端调用 POST /api/training (server/api.py)。
  2. 任务提交: api.py 将训练请求提交给训练进程管理器 (training_process_manager)并立即返回一个任务ID不阻塞主服务。
  3. 动态执行:
    • 管理器在新的子进程中运行任务。
    • 它通过模型注册表 (model_registry) 找到 model_type 对应的训练器函数(例如,kan -> kan_trainer.py 中的函数)。
    • 训练器加载数据进行归一化然后执行PyTorch训练循环。
  4. 模型保存:
    • 训练完成后,调用模型管理器 (model_manager) 的 save_model 方法。
    • 模型(权重、配置、缩放器)被打包保存在 saved_models/ 目录下,命名如 kan_product_P001_v1.pth
    • 模型的元数据(路径、版本、指标)被写入数据库的 model_versions 表。

步骤三:模型预测 (同步)

  1. API触发: 前端调用 POST /api/prediction (server/api.py)。
  2. 模型定位: api.py 调用模型管理器 (model_manager),根据参数从数据库中找到对应的模型文件路径。
  3. 加载与预测:
    • 核心逻辑在 server/predictors/model_predictor.pyload_model_and_predict 函数中。
    • 该函数加载 .pth 文件,并利用其中的 configstate_dict 精确重建模型实例
    • 执行自回归预测:预测一天,将结果作为下一天输入的一部分,循环往复。
  4. 结果保存:
    • 完整的预测结果历史、预测、分析等被保存为一个JSON文件到 saved_predictions/ 目录。
    • 该次预测的元数据包括JSON文件路径被写入数据库的 prediction_history 表。
  5. 返回与渲染: 完整的JSON结果被返回给前端前端使用图表库进行可视化。

5. 如何添加一个新的算法?(开发者指南)

假设你要添加一个名为 NewNet 的新算法。

目标: 让 NewNet 出现在前端的“模型类型”下拉框中,并能成功训练和预测。

  1. 创建模型定义文件:

    • server/models/ 目录下,创建 newnet_model.py
    • 在其中定义你的 NewNet 模型类,继承自 torch.nn.Module
  2. 创建训练器文件:

    • server/trainers/ 目录下,创建 newnet_trainer.py
    • 复制一份现有训练器(如 kan_trainer.py)的内容作为模板。
    • 关键修改:
      • 导入你的 NewNet 模型。
      • 在训练函数中,实例化你的 NewNet 模型。
      • 在保存checkpoint时确保 config 字典里包含了重建 NewNet 所需的所有超参数。
      • 在文件末尾,注册你的训练器: register_trainer('newnet', your_training_function)
  3. 创建预测器逻辑 (如果需要):

    • 大多数情况,你可以复用默认的预测器。打开 server/predictors/model_predictor.py
    • load_model_and_predict 函数中,添加一个 elif loaded_model_type == 'newnet': 分支,确保它能根据 config 正确地创建 NewNet 模型实例。
    • 在文件末尾,注册你的预测器: register_predictor('newnet', default_pytorch_predictor)。如果你的模型有特殊的预测逻辑,可以自定义一个预测函数并注册它。
  4. 更新前端界面:

    • 打开 server/api.py 中的 get_model_types 函数。
    • model_meta 字典中添加 'newnet' 的元数据,包括名称、描述和标签类型。
    • 无需修改前端代码前端的下拉框会自动从这个API获取最新的模型列表。

完成以上步骤后,重启服务,你就可以在界面上选择并使用你的新算法了。这个插件式的设计大大简化了新算法的集成过程。

6. 系统维护与扩展

随着系统的持续运行,会不断产生模型文件、预测结果等历史产物。理解如何管理这些产物对于保持系统的健康至关重要。

6.1. 历史产物管理 (Artifacts Management)

问题: 随着时间推移,saved_models/saved_predictions/ 目录下的文件会越来越多,导致项目体积变得臃肿。

当前状态: 系统目前依赖手动清理。您可以通过Web界面删除单个模型或单条预测历史程序会自动删除对应的文件。

推荐的解决方案: 为了实现自动化管理,推荐创建一个独立的维护脚本,并实施数据保留策略 (Data Retention Policy)

自动化清理策略

  1. 创建清理脚本:

    • 可以在 server/tools/ 目录下创建一个新脚本,例如 cleanup_artifacts.py
  2. 定义保留规则:

    • 对于预测结果 (.json in saved_predictions/):
      • 基于时间: 只保留最近30天的记录。
      • 基于数量: 只保留最新的1000条记录。
    • 对于模型 (.pth in saved_models/):
      • 基于版本: 只保留每个模型同一种药品、同一种算法最新的3个版本。
      • 保留最佳模型: 始终保留性能最佳的 best 版本,不参与自动清理。
  3. 执行脚本:

    • 脚本的逻辑是:连接数据库,查询出所有符合清理条件的记录,然后安全地删除硬盘上对应的文件,最后再删除数据库中的条目。
    • 这个脚本可以通过服务器的定时任务如Linux的Cron Job或Windows的Task Scheduler设置为每日自动执行。

企业级方案:归档到冷存储

对于需要长期保留数据以备审计的场景更专业的做法是将旧文件归档至廉价的云对象存储如阿里云OSS, AWS S3等而不是直接删除。数据库中仅更新文件路径指向云端地址即可。