# 光瓣识别与 PYNQ-Z2 FPGA 部署 本项目面向光斑/光瓣图像识别,包含 PC 端神经网络训练、量化模型实验、Vitis HLS 加速器工程和 PYNQ-Z2 板端推理脚本。PC 端以 MobileNetV2 作为主要识别模型;FPGA 端提供 TinyCNN/HLS-QCNN 两条轻量化上板验证路线,用于演示从训练、导出权重、HLS 综合到 PYNQ 推理的完整流程。 ## 项目结构 ```text . ├── 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 端依赖: ```bash pip install -r pc_training/requirements.txt ``` ## 数据集下载 本项目使用自采光瓣图像数据集,共 10 类,500 张图片。 下载地址: - [light-petal-dataset.zip](https://git.simgreek.com/abaishu0730/light-petal-recognition/releases/download/dataset-v1/light-petal-dataset.zip) 数据划分: - `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 构建产物和压缩包。请按需在本地准备以下目录: ```text 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: ```bash cd pc_training python train.py --data_dir ../data/processed --num_classes 10 --input_size 224 --epochs 50 --batch_size 32 --pretrained ``` 训练 TinyCNN: ```bash 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: ```bash cd pc_training python train_hls_qcnn.py --data_dir ../data/processed --save_path ../data/models/hls_qcnn_stable_best.pth ``` 运行 PC 端评估: ```bash 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 权重并运行构建: ```bat 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 上板文件: ```bat 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: ```bash 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: ```bash 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: ```bash 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 端部署闭环”分开描述:前者体现算法效果,后者体现硬件加速器设计与部署流程。 ## 许可证 如需公开复用,请在发布前补充正式开源许可证文件。