forsetsystem/docs/09_环境配置与安装说明.md

环境配置与安装说明

1. 推荐环境

为保证传统机器学习模型和 LSTM+MLP 深度学习模型均可正常训练，推荐使用 conda 虚拟环境 管理本项目依赖。

推荐环境：

• 操作系统：Windows 10 / Windows 11
• Python：3.11
• Conda：Anaconda 或 Miniconda
• Node.js：16+
• pnpm：8+
• CUDA：建议与 PyTorch GPU 轮子版本匹配

2. 创建 conda 虚拟环境

conda create -n forsetenv python=3.11 -y
conda activate forsetenv

说明：

• 后续所有 Python 依赖安装、数据生成、模型训练和后端启动，均建议在 forsetenv 环境中进行。

3. 推荐安装顺序

推荐严格按下面顺序执行：

1. 创建并激活 conda 虚拟环境
2. 单独安装 PyTorch GPU 版
3. 安装其余后端依赖
4. 安装前端依赖

说明：

• backend/requirements.txt 中包含 torch==2.6.0
• 如果在 Windows 下先直接执行 pip install -r backend/requirements.txt，可能安装成非预期构建
• 因此深度学习环境建议先执行官方 cu124 安装命令，再补齐其余依赖

4. 安装 PyTorch GPU 版

本项目的 hybrid 深度学习模型要求：

• torch >= 2.6

推荐安装方式：

• 使用 pip 官方 cu124 轮子
• 避免在 Windows 上由 conda 自动解析成 cpu_mkl 构建

安装命令如下：

pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124

5. 安装其余后端依赖

如果你已经按上一步安装了 GPU 版 torch，推荐补装其余后端依赖：

pip install Flask==2.3.3 Flask-CORS==4.0.0 python-dotenv==1.0.0
pip install pandas==2.0.3 numpy==1.24.3 scikit-learn==1.3.0 joblib==1.3.1
pip install xgboost==1.7.6 lightgbm==4.1.0

如果你仍然希望直接使用依赖文件，可以在完成 GPU 版 torch 安装后执行：

pip install -r backend/requirements.txt

这一步通常不会影响已经安装好的 cu124 版本；如有覆盖风险，可在执行后再次运行上一节的 GPU 安装命令。

6. 安装前端依赖

cd frontend
pnpm install

7. 一键执行示例

下面是一套推荐的 conda 环境安装流程：

conda create -n forsetenv python=3.11 -y
conda activate forsetenv
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
pip install Flask==2.3.3 Flask-CORS==4.0.0 python-dotenv==1.0.0
pip install pandas==2.0.3 numpy==1.24.3 scikit-learn==1.3.0 joblib==1.3.1
pip install xgboost==1.7.6 lightgbm==4.1.0
cd frontend
pnpm install

8. 验证安装

8.1 验证基础依赖

python -c "import pandas,numpy,sklearn,flask;print('base ok')"

8.2 验证传统模型依赖

python -c "import xgboost,lightgbm;print('ml ok')"

8.3 验证 PyTorch GPU

python -c "import torch;print(torch.__version__);print(torch.cuda.is_available())"

如果输出为 True，说明 GPU 版本 PyTorch 可正常使用。

9. 项目启动顺序

9.1 生成数据集

cd backend
python core/generate_dataset.py

9.2 训练模型

python core/train_model.py

9.3 启动后端

python app.py

9.4 启动前端

cd ..\frontend
pnpm dev

10. 常见问题

10.1 PyTorch 被安装成 CPU 版

原因：

• 使用了默认 pip install torch
• 或使用 conda 在 Windows 上自动解析成 CPU 构建

建议：

• 直接使用本文提供的官方 cu124 安装命令

10.2 训练过程中无法加载深度学习模型

检查项：

• 当前是否处于 forsetenv conda 环境
• torch 是否成功安装
• torch.cuda.is_available() 是否为 True

10.3 xgboost / lightgbm 缺失

可执行：

pip install xgboost==1.7.6 lightgbm==4.1.0

10.4 如何确认当前使用的是 conda 环境

可执行：

conda info --envs
where python

如果当前环境为 forsetenv，且 python 指向对应环境目录，说明切换成功。

11. 建议

• 毕设演示或论文实验时，统一使用 conda activate forsetenv
• 深度学习模型训练时优先使用 GPU 环境
• 若仅进行页面展示，可先训练传统模型，再补充深度学习实验结果