Files

7.6 KiB
Raw Permalink Blame History

光瓣识别与 PYNQ-Z2 FPGA 部署

本项目面向光斑/光瓣图像识别,包含 PC 端神经网络训练、量化模型实验、Vitis HLS 加速器工程和 PYNQ-Z2 板端推理脚本。PC 端以 MobileNetV2 作为主要识别模型;FPGA 端提供 TinyCNN/HLS-QCNN 两条轻量化上板验证路线,用于演示从训练、导出权重、HLS 综合到 PYNQ 推理的完整流程。

项目结构

.
├── pc_training/          # PC 端数据集加载、训练、推理、量化和模型定义
├── hls_cnn/              # HLS C/C++ 内核、权重导出脚本、Vivado/Vitis HLS 构建脚本
├── fpga_deployment/      # PYNQ-Z2 板端推理脚本
├── finn_deployment/      # FINN 量化部署实验脚本
├── scripts/              # 辅助脚本
├── notebooks/            # 实验 notebook
├── docs/                 # 复现实验、Vivado、PYNQ、训练导出等说明文档
└── data/                 # 数据集和模型权重占位目录,大文件不纳入 git

已归档的过程说明、录屏指南、阶段总结等文档位于 docs/notes/。

环境要求

PC 训练环境:

  • Python 3.8+
  • PyTorch、torchvision、NumPy、Pillow、OpenCV、matplotlib、scikit-learn
  • 可选:TensorBoard、Brevitas、QONNX、ONNX Runtime

FPGA/HLS 环境:

  • PYNQ-Z2,Zynq-7020 xc7z020clg400-1
  • PYNQ v2.7
  • Xilinx Vivado / Vitis HLS 2020.2
  • 板端 Python 3、NumPy、Pillow、PYNQ

安装 PC 端依赖:

pip install -r pc_training/requirements.txt

数据集下载

本项目使用自采光瓣图像数据集,共 10 类,500 张图片。

下载地址:

数据划分:

  • train: 400 张
  • val: 100 张

测试结果

以下结果均来自仓库 results/ 目录中的记录文件,测试集默认是 data/processed/val 的 100 张验证图像。

PC 端 MobileNetV2

来源文件:results/PC端推理结果报告.md、results/inference_results.json

项目 数值
测试样本 100
总体准确率 77.00%
正确 / 总数 77 / 100
平均推理时间 11.28 ms / 图像
吞吐量 88.63 FPS

分类型表现:

  • class_0: 87.50% precision,70.00% recall
  • class_1: 75.00% precision,90.00% recall
  • class_2: 90.91% precision,100.00% recall
  • class_3: 88.89% precision,80.00% recall
  • class_4: 72.73% precision,80.00% recall
  • class_5: 75.00% precision,60.00% recall
  • class_6: 70.00% precision,70.00% recall
  • class_7: 69.23% precision,90.00% recall
  • class_8: 70.00% precision,70.00% recall
  • class_9: 75.00% precision,60.00% recall

HLS-QCNN 定点参考

来源文件:results/hls_qcnn_eval.json、results/hls_qcnn_stable_eval.json、results/hls_qcnn_slim_eval.json

检查点 测试样本 准确率 平均延迟 吞吐量
hls_qcnn_best.pth 100 72.00% 8.07 ms / 图像 123.98 FPS
hls_qcnn_stable_best.pth 100 80.00% 11.71 ms / 图像 85.37 FPS
hls_qcnn_slim_best.pth 100 83.00% 10.73 ms / 图像 93.18 FPS

补充说明:

  • hls_qcnn_stable_best.pth 的稳定性门控通过,stable_gate.passed = true
  • hls_qcnn_slim_best.pth 目前在这组三个候选里验证准确率最高
  • 三个版本都使用同一套 10 类、每类 10 张的验证集

PYNQ-Z2 板端结果

来源文件:results/hls_qcnn_pynq_val100_x3/hls_qcnn_pynq_val100_x3_summary.json、results/hls_qcnn_pynq_val100_x3/run100_summary.txt

项目 数值
测试样本 100
重复次数 3
每次准确率 79.00%
平均准确率 79.00%
平均单图耗时 18,797.05 ms
吞吐量 0.05 FPS

分类型结果(3 次结果一致):

  • class_0: 50%
  • class_1: 90%
  • class_2: 100%
  • class_3: 100%
  • class_4: 100%
  • class_5: 100%
  • class_6: 60%
  • class_7: 80%
  • class_8: 60%
  • class_9: 50%

说明:

  • 这是当前正式板端结果,使用的是 100 张验证图像的完整测试集
  • 结果与定点参考一致性较好,准确率维持在 79%
  • 当前实现属于偏串行的板端版本,单图延迟较高,但适合作为闭环验证基线

数据与模型文件

公开仓库不包含训练图片、模型权重、ONNX 文件、bitstream、Vivado/HLS 构建产物和压缩包。请按需在本地准备以下目录:

data/processed/
├── train/
│   ├── class_0/
│   ├── class_1/
│   └── ...
└── val/
    ├── class_0/
    ├── class_1/
    └── ...

data/models/
├── best_model.pth
├── tiny_cnn.pth
└── hls_qcnn_stable_best.pth

目录中的类别文件夹名称会被数据集加载脚本用作分类标签。原始大文件可在本地保留,但不要直接提交到 git。

PC 端训练与推理

训练 MobileNetV2:

cd pc_training
python train.py --data_dir ../data/processed --num_classes 10 --input_size 224 --epochs 50 --batch_size 32 --pretrained

训练 TinyCNN:

cd pc_training
python train_tiny_cnn.py --data_dir ../data/processed --input_size 64 --epochs 150 --save_path ../data/models/tiny_cnn.pth

训练 HLS-QCNN:

cd pc_training
python train_hls_qcnn.py --data_dir ../data/processed --save_path ../data/models/hls_qcnn_stable_best.pth

运行 PC 端评估:

cd pc_training
python inference.py --model_path ../data/models/best_model.pth --data_dir ../data/processed/val --output_dir ../results/inference

HLS 与 Vivado 构建

中文路径可能导致 Xilinx 2020.2 工具链行为不稳定。建议将仓库复制到纯英文路径后再运行 HLS/Vivado 构建,例如 C:\hls_light_petal。

导出 TinyCNN HLS 权重并运行构建:

python hls_cnn\export_weights.py --model data\models\tiny_cnn.pth --test_image data\processed\val\class_0\10.jpg
hls_cnn\run_hls.bat
hls_cnn\run_vivado.bat

导出 HLS-QCNN 上板文件:

python hls_cnn\export_hls_qcnn_weights.py --checkpoint data\models\hls_qcnn_stable_best.pth --test_image data\processed\val\class_0\10.jpg
python hls_cnn\generate_hls_qcnn_artifacts.py
hls_cnn\run_hls_qcnn.bat
hls_cnn\run_vivado_qcnn.bat

更多细节见:

  • hls_cnn/README.md
  • docs/HLS_QCNN_PYNQ复现实验教程.md
  • docs/Vivado设计指南.md

PYNQ-Z2 板端运行

将 bitstream、hwh、权重和推理脚本复制到 PYNQ:

scp hls_cnn/output/tiny_cnn.bit xilinx@192.168.2.99:~/
scp hls_cnn/output/tiny_cnn.hwh xilinx@192.168.2.99:~/
scp fpga_deployment/tiny_cnn_inference.py xilinx@192.168.2.99:~/
scp -r data/processed/val xilinx@192.168.2.99:~/test_images

在板端运行 TinyCNN:

python3 tiny_cnn_inference.py --bitstream tiny_cnn.bit --image test_images/class_0/10.jpg
python3 tiny_cnn_inference.py --bitstream tiny_cnn.bit --test_dir test_images --runs 100

运行 HLS-QCNN:

python3 hls_qcnn_inference.py --bitstream hls_qcnn.bit --weights hls_qcnn_weights.json --image test_images/class_0/10.jpg
python3 hls_qcnn_inference.py --bitstream hls_qcnn.bit --weights hls_qcnn_weights.json --test_dir test_images --runs 100

当前状态

  • PC 端 MobileNetV2 用于主要识别精度验证。
  • TinyCNN/HLS-QCNN 用于 PYNQ-Z2 上板闭环和硬件部署流程验证。
  • HLS 产物、模型权重和数据集体积较大,默认由 .gitignore 排除。
  • 若用于论文或验收,建议将“PC 端识别精度”和“FPGA 端部署闭环”分开描述:前者体现算法效果,后者体现硬件加速器设计与部署流程。

许可证

如需公开复用,请在发布前补充正式开源许可证文件。