Files

247 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 光瓣识别与 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 端部署闭环”分开描述:前者体现算法效果,后者体现硬件加速器设计与部署流程。
## 许可证
如需公开复用,请在发布前补充正式开源许可证文件。