319 lines
8.4 KiB
Markdown
319 lines
8.4 KiB
Markdown
# Deeplearning 使用说明
|
||
|
||
## 1. Conda 环境迁移
|
||
|
||
环境文件在 `conda_env/`：
|
||
|
||
- `conda_env/environment.portable.yml`：通用迁移（推荐）
|
||
- `conda_env/environment.lock.txt`：精确锁定（同系统/同架构优先）
|
||
- `conda_env/env.yml`：历史文件
|
||
|
||
### 1.1 创建环境
|
||
|
||
```bash
|
||
# 方式1（推荐）：通用创建
|
||
conda env create -f conda_env/environment.portable.yml
|
||
conda activate Deeplearning
|
||
|
||
# 方式2：精确复现
|
||
conda create -n Deeplearning --file conda_env/environment.lock.txt
|
||
conda activate Deeplearning
|
||
|
||
# 验证
|
||
python -V
|
||
python -c "import torch; print(torch.__version__)"
|
||
```
|
||
|
||
### 1.2 同名环境已存在时
|
||
|
||
```bash
|
||
# 方式A：保留旧环境，改名创建
|
||
conda env create -f conda_env/environment.portable.yml -n Deeplearning_v2
|
||
conda activate Deeplearning_v2
|
||
|
||
# 或者（lock 方式）
|
||
conda create -n Deeplearning_v2 --file conda_env/environment.lock.txt
|
||
conda activate Deeplearning_v2
|
||
```
|
||
|
||
```bash
|
||
# 方式B：删除旧环境后重建（谨慎）
|
||
conda env remove -n Deeplearning
|
||
conda env create -f conda_env/environment.portable.yml
|
||
conda activate Deeplearning
|
||
```
|
||
|
||
### 1.3 重新导出环境
|
||
|
||
```bash
|
||
conda env export -n Deeplearning --no-builds > conda_env/environment.portable.yml
|
||
conda list -n Deeplearning --explicit > conda_env/environment.lock.txt
|
||
```
|
||
|
||
### 1.4 主要依赖包
|
||
|
||
训练与数据处理核心依赖：
|
||
|
||
- Python 3.12
|
||
- pytorch / torchvision / torchaudio
|
||
- pandas / numpy / scipy
|
||
- scikit-learn
|
||
- matplotlib / seaborn
|
||
- openpyxl / xlrd（用于 xls/xlsx 读写）
|
||
|
||
说明：项目仓库已提供完整环境文件，优先用 `conda_env/environment.portable.yml` 或 `conda_env/environment.lock.txt` 创建环境。
|
||
|
||
### 1.5 依赖安装方式（Conda / pip）
|
||
|
||
方式 A（推荐，Conda 一步到位）：
|
||
|
||
```bash
|
||
conda env create -f conda_env/environment.portable.yml
|
||
conda activate Deeplearning
|
||
```
|
||
|
||
方式 B（Conda 最小安装，适合自定义环境）：
|
||
|
||
```bash
|
||
conda create -n Deeplearning python=3.12 -y
|
||
conda activate Deeplearning
|
||
|
||
# GPU 机器（CUDA 12.4）
|
||
conda install -y pytorch torchvision torchaudio pytorch-cuda=12.4 -c pytorch -c nvidia
|
||
|
||
# CPU 机器（无 CUDA）
|
||
# conda install -y pytorch torchvision torchaudio cpuonly -c pytorch
|
||
|
||
conda install -y pandas numpy scipy scikit-learn matplotlib seaborn openpyxl xlrd
|
||
```
|
||
|
||
方式 C（pip 安装，适合已有虚拟环境）：
|
||
|
||
```bash
|
||
pip install torch torchvision torchaudio
|
||
pip install pandas numpy scipy scikit-learn matplotlib seaborn openpyxl xlrd
|
||
```
|
||
|
||
可选开发工具：
|
||
|
||
```bash
|
||
pip install black autopep8 basedpyright
|
||
```
|
||
|
||
## 2. 项目约定
|
||
|
||
### 2.1 输入数据格式
|
||
每一类数据支持 `xls/xlsx/csv`。读取时默认取偶数列（索引 1,3,5...）作为特征，奇数列内容可忽略。
|
||
|
||
示意：
|
||
|
||
| 任意值 | 特征值 | 任意值 | 特征值 |
|
||
|---|---|---|---|
|
||
| arbitrary value | value | arbitrary value | value |
|
||
|
||
### 2.2 目录约定
|
||
训练数据放在 `Static/`，输出结果放在 `Result/`。
|
||
|
||
推荐目录：
|
||
|
||
```text
|
||
.
|
||
├─ Static/
|
||
│ └─ 20241009MaterialDiv/
|
||
└─ Result/
|
||
```
|
||
|
||
## 3. 快速开始
|
||
|
||
### 3.1 准备数据
|
||
1. 将数据目录命名为 `日期+项目名`，例如 `20241009MaterialDiv`。
|
||
2. 准备 `label_names`（建议英文或数字）。
|
||
3. 将数据目录放入 `Static/`。
|
||
|
||
### 3.2 数据目录模板
|
||
|
||
单文件模式（每个标签一个文件）：
|
||
|
||
```text
|
||
Static/
|
||
20241009MaterialDiv/
|
||
Acrlic.xlsx
|
||
Ecoflex.xlsx
|
||
PDMS.xlsx
|
||
PLA.xlsx
|
||
Wood.xlsx
|
||
```
|
||
|
||
多子特征模式（每个标签一个子目录，目录下可有多个文件）：
|
||
|
||
```text
|
||
Static/
|
||
20241009MaterialDiv/
|
||
Acrlic/
|
||
sample_01.xlsx
|
||
sample_02.xlsx
|
||
Ecoflex/
|
||
sample_01.xlsx
|
||
sample_02.xlsx
|
||
PDMS/
|
||
sample_01.xlsx
|
||
sample_02.xlsx
|
||
PLA/
|
||
sample_01.xlsx
|
||
sample_02.xlsx
|
||
Wood/
|
||
sample_01.xlsx
|
||
sample_02.xlsx
|
||
```
|
||
|
||
命名规则（重要）：
|
||
|
||
- `label_names` 中每一项必须与文件名（单文件模式）或子文件夹名（多子特征模式）一致。
|
||
- `label_names` 顺序就是标签编码顺序，训练结果和混淆矩阵按该顺序展示。
|
||
|
||
示例：
|
||
|
||
```python
|
||
label_names = ['Acrlic', 'Ecoflex', 'PDMS', 'PLA', 'Wood']
|
||
```
|
||
|
||
对应关系：
|
||
|
||
```text
|
||
Acrlic <-> Acrlic.xlsx 或 Acrlic/
|
||
Ecoflex <-> Ecoflex.xlsx 或 Ecoflex/
|
||
PDMS <-> PDMS.xlsx 或 PDMS/
|
||
PLA <-> PLA.xlsx 或 PLA/
|
||
Wood <-> Wood.xlsx 或 Wood/
|
||
```
|
||
|
||
### 3.3 通用：数据导入
|
||
|
||
```python
|
||
from Qfunctions.loadData import load_data
|
||
|
||
projet_name = '20241009MaterialDiv'
|
||
label_names = ['Acrlic', 'Ecoflex', 'PDMS', 'PLA', 'Wood']
|
||
|
||
# 自动识别数据模式（支持 xls/xlsx/csv）
|
||
data = load_data(projet_name, label_names)
|
||
```
|
||
|
||
### 3.4 模型调用
|
||
|
||
#### 3.4.1 MLP
|
||
|
||
```python
|
||
from Qtorch.Models.Qmlp import Qmlp
|
||
|
||
model = Qmlp(
|
||
data=data,
|
||
labels=label_names,
|
||
hidden_layers=[128, 256, 128],
|
||
test_size=0.3,
|
||
dropout_rate=0,
|
||
)
|
||
|
||
model.fit(300)
|
||
```
|
||
|
||
#### 3.4.2 1D CNN
|
||
|
||
```python
|
||
from Qtorch.Models.Qcnn import QCNN
|
||
|
||
model = QCNN(
|
||
data=data,
|
||
labels=label_names,
|
||
conv_channels=(16, 32),
|
||
kernel_size=3,
|
||
hidden_size=128,
|
||
test_size=0.3,
|
||
dropout_rate=0,
|
||
)
|
||
|
||
model.fit(300)
|
||
```
|
||
|
||
### 3.5 通用：结果获取与图表导出
|
||
|
||
```python
|
||
from Qfunctions.saveToXlsx import save_to_xlsx
|
||
|
||
pca_2d, pca_3d = model.get_PCA()
|
||
cm = model.get_cm()
|
||
cmn = model.get_cmn()
|
||
epoch_data = model.get_epoch_data()
|
||
|
||
save_to_xlsx(project_name=projet_name, file_name='pca_2d', data=pca_2d)
|
||
save_to_xlsx(project_name=projet_name, file_name='pca_3d', data=pca_3d)
|
||
save_to_xlsx(project_name=projet_name, file_name='cm', data=cm)
|
||
save_to_xlsx(project_name=projet_name, file_name='cmn', data=cmn)
|
||
save_to_xlsx(project_name=projet_name, file_name='acc_and_loss', data=epoch_data)
|
||
```
|
||
|
||
### 3.6 每次运行参数与结果 YAML 存档
|
||
|
||
当前 `main.py` 会为每次运行创建时间戳目录：
|
||
|
||
- `Result/<project_name>/<YYYYMMDD_HHMMSS>/`
|
||
|
||
并在目录下自动保存：
|
||
|
||
- `run_params.yaml`：本次运行参数快照。
|
||
- `run_result.yaml`：本次运行结果摘要（最佳轮次与最后轮次指标）。
|
||
|
||
这样可以直接对比不同运行的参数与结果变化。
|
||
|
||
## 4. load_data 参数说明
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| folder | str | 必填 | `Static/` 下的数据目录名 |
|
||
| labelNames | list | 必填 | 类别名称列表，用于读取和排序标签 |
|
||
|
||
自动识别规则：
|
||
|
||
- 若每个 `label` 都对应 `folder/label/*.(xlsx|xls|csv)`，识别为多子特征模式。
|
||
- 若每个 `label` 都对应 `folder/label.(xlsx|xls|csv)`，识别为单文件模式。
|
||
- 超出支持范围的文件格式（仅支持 xls/xlsx/csv）会报错。
|
||
- 若两种都成立（同名文件和同名子目录同时存在），会报错并提示只保留一种目录结构。
|
||
- 若两种都不成立，会报错并提示检查目录结构或 `label_names`。
|
||
|
||
读取路径规则：
|
||
|
||
- 单文件模式：`./Static/folder/labelNames[i].(xlsx|xls|csv)`
|
||
- 多子特征模式：`./Static/folder/labelNames[i]/*.(xlsx|xls|csv)`
|
||
|
||
## 5. 常见问题
|
||
|
||
### 5.1 找不到文件
|
||
优先检查：
|
||
|
||
- `label_names` 与文件/文件夹是否同名
|
||
- 文件后缀是否为 `.xls`、`.xlsx` 或 `.csv`（其他格式将报错）
|
||
|
||
## 6. TODO（后续计划）
|
||
|
||
### 阶段一：基础稳定与可维护性
|
||
|
||
- [ ] 固化模型基类契约：`build_model`、输入变换钩子、统一训练配置。
|
||
- [ ] 封装 `QDL` 包结构（`qdl.data / qdl.models / qdl.export / qdl.api`）。
|
||
- [ ] 增加兼容层：保留旧导入路径，逐步迁移到新包路径。
|
||
- [ ] 增加最小测试集：`load_data`、`Qmlp.fit(1)`、`QCNN.fit(1)`、导出函数。
|
||
|
||
### 阶段二：高维与复合模型能力
|
||
|
||
- [ ] 将 batch 结构升级为字典（`x/y/lengths/mask/meta`），支持复合输入。
|
||
- [ ] 在训练框架中加入钩子：`prepare_batch`、`forward_step`、`compute_loss`。
|
||
- [ ] 引入编码器层（Encoder）抽象：按策略扩展（MLP/CNN/LSTM/GNN/Transformer），不按维度硬扩类。
|
||
- [ ] 支持可变长时间序列（`collate_fn + lengths + mask`），作为后续复合模型基础。
|
||
- [ ] 增加多分支融合模板（时序分支 + 静态分支），预留多任务损失组合。
|
||
|
||
### 阶段三：对外能力与发布
|
||
|
||
- [ ] 统一对外入口：提供高层 API（例如 `train_mlp`、`train_cnn1d`、`train_hybrid`）。
|
||
- [ ] 在模型文档中预留扩展位：`3.4.3 LSTM`、`3.4.4 GNN`、`3.4.5 Hybrid`。
|
||
- [ ] 完成打包配置（`pyproject.toml`）与本地可编辑安装说明。
|
||
- [ ] 发布前回归：在 Conda 与 pip 环境分别跑通最小端到端流程。
|