2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00
2026-05-19 17:23:08 +08:00

光瓣识别与 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

数据与模型文件

公开仓库不包含训练图片、模型权重、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 端部署闭环”分开描述:前者体现算法效果,后者体现硬件加速器设计与部署流程。

许可证

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

S
Description
光瓣识别与 PYNQ-Z2 FPGA 部署项目
Readme
212 KiB
0 Stars 1 Watchers 0 Forks
2026-05-19 23:13:14 +08:00
Languages
Python 79.4%
C++ 6.3%
Tcl 4.8%
PowerShell 4.3%
Jupyter Notebook 2.7%
Other 2.5%