247 lines
7.6 KiB
Markdown
247 lines
7.6 KiB
Markdown
# 光瓣识别与 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 端部署闭环”分开描述:前者体现算法效果,后者体现硬件加速器设计与部署流程。
|
||
|
||
## 许可证
|
||
|
||
如需公开复用,请在发布前补充正式开源许可证文件。
|