HLS-QCNN PC端训练与导出说明
==========================

一、PC端做什么
-------------

PC端负责：

  1. 训练 HLS-QCNN 模型
  2. 评估浮点模型准确率
  3. 导出 Conv+BN 融合后的 HLS 权重
  4. 跑 Python 定点参考
  5. 生成 HLS 需要的参数、权重、testbench 数据
  6. 再进入 Vitis HLS / Vivado 生成 bit/hwh

PYNQ-Z2 板端不训练模型，也不运行 HLS/Vivado。


二、进入项目目录
---------------

Windows CMD 或 PowerShell 中执行：

  cd /d 项目根目录

这里的“项目根目录”指能看到下面这些目录的位置：

  pc_training
  hls_cnn
  data
  results

如果是在完整交付包里操作，就进入解压后的根目录。

示例：

  cd /d 你解压的位置\hls_qcnn_full_delivery_package

根目录下应能看到：

  pc_training
  hls_cnn
  data
  results


三、训练脚本
-----------

训练主脚本：

  pc_training/train_hls_qcnn.py

模型结构文件：

  pc_training/hls_qcnn.py

默认模型：

  输入：128x128 RGB
  通道：[16,40,64,96,128]
  hidden：160
  输出类别：10

注意：最终上板使用的是瘦身 HLS-QCNN，不是 MobileNetV2，也不是旧 TinyCNN。


四、推荐训练命令
---------------

在项目根目录执行：

  cd /d 项目根目录

推荐命令：

  python pc_training\train_hls_qcnn.py --data_dir data\processed --teacher_path data\models\best_model.pth --save_path data\models\hls_qcnn_slim_best.pth --metrics_path results\hls_qcnn_slim_metrics.json --channels 16,40,64,96,128 --hidden_features 160 --input_size 128 --epochs 250 --batch_size 32 --min_acc 72 --stable_acc 70 --stable_min_avg 70 --stable_min_hits 5

如果显存或内存不足，把 batch size 改成 16：

  python pc_training\train_hls_qcnn.py --data_dir data\processed --teacher_path data\models\best_model.pth --save_path data\models\hls_qcnn_slim_best.pth --metrics_path results\hls_qcnn_slim_metrics.json --channels 16,40,64,96,128 --hidden_features 160 --input_size 128 --epochs 250 --batch_size 16 --min_acc 72 --stable_acc 70 --stable_min_avg 70 --stable_min_hits 5

训练会使用 teacher 蒸馏：

  data/models/best_model.pth

teacher cache 默认保存到：

  data/models/hls_qcnn_teacher_cache.json


五、训练输出
-----------

训练成功后重点看这两个文件：

  data/models/hls_qcnn_slim_best.pth
  results/hls_qcnn_slim_metrics.json

当前已经达标的模型是：

  data/models/hls_qcnn_slim_best.pth

当前 PC 浮点评估结果约为：

  83/100

后续定点参考结果为：

  79/100


六、浮点模型评估
---------------

评估脚本：

  pc_training/eval_hls_qcnn.py

推荐命令：

  python pc_training\eval_hls_qcnn.py --checkpoint data\models\hls_qcnn_slim_best.pth --data_dir data\processed\val --output results\hls_qcnn_slim_eval.json --min_acc 72

如果准确率低于 72%，不建议进入 HLS。先继续训练或调参。

当前已保存评估文件：

  results/hls_qcnn_slim_eval.json


七、导出 HLS 权重
---------------

导出脚本：

  hls_cnn/export_hls_qcnn_weights.py

该脚本会把 Conv+BN 融合，并把权重量化成 int16，scale 默认 1024。

推荐命令：

  python hls_cnn\export_hls_qcnn_weights.py --checkpoint data\models\hls_qcnn_slim_best.pth --test_image data\processed\val\class_0\10.jpg --npz_out hls_cnn\include\hls_qcnn_slim_weights.npz --json_out hls_cnn\include\hls_qcnn_slim_manifest.json --test_out hls_cnn\include\hls_qcnn_slim_test_image.npy --weight_scale 1024

输出文件：

  hls_cnn/include/hls_qcnn_slim_weights.npz
  hls_cnn/include/hls_qcnn_slim_manifest.json
  hls_cnn/include/hls_qcnn_slim_test_image.npy

注意：HLS 最终使用的是后续生成的 flat 权重：

  hls_cnn/include/hls_qcnn_weights_flat.npy


八、Python 定点参考验证
--------------------

定点参考脚本：

  hls_cnn/hls_qcnn_fixed_ref.py

推荐命令：

  python hls_cnn\hls_qcnn_fixed_ref.py --manifest hls_cnn\include\hls_qcnn_slim_manifest.json --weights hls_cnn\include\hls_qcnn_slim_weights.npz --data_dir data\processed\val --output results\hls_qcnn_slim_fixed_eval.json --min_acc 70

当前正式定点结果：

  fixed accuracy: 79.00% (79/100)

输出文件：

  results/hls_qcnn_slim_fixed_eval.json

如果定点准确率低于 70%，不要进入 HLS，先检查：

  1. 权重导出是否对应 hls_qcnn_slim_best.pth
  2. manifest 是否对应同一次导出
  3. weight_scale 是否仍为 1024
  4. 图像预处理是否仍是 128x128 RGB


九、生成 HLS artifact
-------------------

artifact 生成脚本：

  hls_cnn/generate_hls_qcnn_artifacts.py

推荐命令：

  python hls_cnn\generate_hls_qcnn_artifacts.py --manifest hls_cnn\include\hls_qcnn_slim_manifest.json --weights hls_cnn\include\hls_qcnn_slim_weights.npz --test_image data\processed\val\class_0\10.jpg --out_dir hls_cnn\include

生成文件：

  hls_cnn/include/hls_qcnn_params.h
  hls_cnn/include/hls_qcnn_tb_data.h
  hls_cnn/include/hls_qcnn_weights_flat.npy
  hls_cnn/include/hls_qcnn_test_image_words.npy
  hls_cnn/include/hls_qcnn_golden_logits.npy
  hls_cnn/include/hls_qcnn_artifact_manifest.json

当前 class_0/10.jpg 的 golden 输出：

  golden_class: 0
  golden_logits: [8262, 7193, 1266, -4729, -6985, -7235, -7197, -2445, -1752, -1996]


十、进入 HLS/Vivado
----------------

完成 PC 端训练、导出和定点验证后，才进入 HLS/Vivado。

运行 Vitis HLS：

  hls_cnn\run_hls_qcnn.bat

运行 Vivado：

  hls_cnn\run_vivado_qcnn.bat

最终输出：

  hls_cnn/output/hls_qcnn.bit
  hls_cnn/output/hls_qcnn.hwh

这两个文件成对上传到 PYNQ-Z2。


十一、当前已经完成的正式结果
--------------------------

当前已经训练并上板验证的模型：

  data/models/hls_qcnn_slim_best.pth

PC 浮点结果：

  83/100

Python 定点结果：

  79/100

PYNQ-Z2 板端三次 100 张重复实验：

  Run 1: 79.00% (79/100), 18797.64 ms/image, 0.05 FPS
  Run 2: 79.00% (79/100), 18796.86 ms/image, 0.05 FPS
  Run 3: 79.00% (79/100), 18796.64 ms/image, 0.05 FPS

正式结果文件：

  results/hls_qcnn_pynq_val100_x3/hls_qcnn_pynq_val100_x3_result.md
  results/hls_qcnn_pynq_val100_x3/hls_qcnn_pynq_val100_x3_summary.json
  results/hls_qcnn_pynq_val100_x3/run100_1.log
  results/hls_qcnn_pynq_val100_x3/run100_2.log
  results/hls_qcnn_pynq_val100_x3/run100_3.log


十二、常见问题
------------

1. 没有 data/processed/val

说明验证集没有放到项目里。需要准备：

  data/processed/train/class_0 ... class_9
  data/processed/val/class_0 ... class_9


2. teacher_path 不存在

如果没有：

  data/models/best_model.pth

可以加：

  --no_teacher

但准确率可能下降。


3. 训练结果不稳定

优先检查：

  --channels 16,40,64,96,128
  --hidden_features 160
  --input_size 128
  --batch_size 32 或 16
  --epochs 250
  --seed 42


4. 定点结果明显低于浮点结果

先不要改 HLS，优先检查：

  hls_qcnn_slim_best.pth
  hls_qcnn_slim_weights.npz
  hls_qcnn_slim_manifest.json
  hls_qcnn_weights_flat.npy

这几个文件是否来自同一次导出。


5. 上板结果和定点参考不一致

优先检查：

  hls_qcnn.bit 和 hls_qcnn.hwh 是否成对
  hls_qcnn_weights_flat.npy 是否为最新
  PYNQ 脚本是否为 fpga_deployment/hls_qcnn_inference.py
  图像预处理是否仍是 128x128 RGB
