8cd060aefe6be7cf6c763e690615b3e8b20c1c27
光瓣识别与 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 张
数据与模型文件
公开仓库不包含训练图片、模型权重、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.mddocs/HLS_QCNN_PYNQ复现实验教程.mddocs/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 端部署闭环”分开描述:前者体现算法效果,后者体现硬件加速器设计与部署流程。
许可证
如需公开复用,请在发布前补充正式开源许可证文件。