Deeplearning 使用说明

1. Conda 环境迁移

环境文件在 conda_env/：

• conda_env/environment.portable.yml：通用迁移（推荐）
• conda_env/environment.lock.txt：精确锁定（同系统/同架构优先）
• conda_env/env.yml：历史文件

1.1 创建环境

# 方式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 同名环境已存在时

# 方式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

# 方式B：删除旧环境后重建（谨慎）
conda env remove -n Deeplearning
conda env create -f conda_env/environment.portable.yml
conda activate Deeplearning

1.3 重新导出环境

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 一步到位）：

conda env create -f conda_env/environment.portable.yml
conda activate Deeplearning

方式 B（Conda 最小安装，适合自定义环境）：

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 安装，适合已有虚拟环境）：

pip install torch torchvision torchaudio
pip install pandas numpy scipy scikit-learn matplotlib seaborn openpyxl xlrd

可选开发工具：

pip install black autopep8 basedpyright

2. 项目约定

2.1 输入数据格式

每一类数据支持 xls/xlsx/csv。读取时默认取偶数列（索引 1,3,5...）作为特征，奇数列内容可忽略。

示意：

任意值	特征值	任意值	特征值
arbitrary value	value	arbitrary value	value

2.2 目录约定

训练数据放在 Static/，输出结果放在 Result/。

推荐目录：

.
├─ Static/
│  └─ 20241009MaterialDiv/
└─ Result/

3. 快速开始

3.1 准备数据

1. 将数据目录命名为 日期+项目名，例如 20241009MaterialDiv。
2. 准备 label_names（建议英文或数字）。
3. 将数据目录放入 Static/。

3.2 数据目录模板

单文件模式（每个标签一个文件）：

Static/
  20241009MaterialDiv/
    Acrlic.xlsx
    Ecoflex.xlsx
    PDMS.xlsx
    PLA.xlsx
    Wood.xlsx

多子特征模式（每个标签一个子目录，目录下可有多个文件）：

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 顺序就是标签编码顺序，训练结果和混淆矩阵按该顺序展示。

示例：

label_names = ['Acrlic', 'Ecoflex', 'PDMS', 'PLA', 'Wood']

对应关系：

Acrlic  <-> Acrlic.xlsx   或  Acrlic/
Ecoflex <-> Ecoflex.xlsx  或  Ecoflex/
PDMS    <-> PDMS.xlsx     或  PDMS/
PLA     <-> PLA.xlsx      或  PLA/
Wood    <-> Wood.xlsx     或  Wood/

3.3 通用：数据导入

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

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

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 通用：结果获取与图表导出

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 环境分别跑通最小端到端流程。