# yolo_opencl

**Repository Path**: luzhihaoTestingLab/yolo_opencl

## Basic Information

- **Project Name**: yolo_opencl
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-23
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Minimal YOLO Torch + OpenCL 推理

- 项目目标：使用 PyTorch 训练一个极简 YOLO 结构的 CIFAR-10 分类器，并将其权重导出为 C++ 数组，在 OpenCL 环境（CPU/POCL、Intel FPGA、Xilinx FPGA）中进行仅推理。
- 重要文件：
  - [minimal_yolo_torch.py](file:///d:/workspace2/yolo_opencl/minimal_yolo_torch.py) 训练脚本与模型定义
  - [export_minimal_yolo_weights.py](file:///d:/workspace2/yolo_opencl/export_minimal_yolo_weights.py) 将训练权重导出为 C++ 头文件
  - [run_minimal_yolo_opencl.cpp](file:///d:/workspace2/yolo_opencl/run_minimal_yolo_opencl.cpp) OpenCL 仅推理程序
  - [minimal_yolo_kernels.cl](file:///d:/workspace2/yolo_opencl/minimal_yolo_kernels.cl) OpenCL kernel 源码
  - [Dockerfile.opencl-base](file:///d:/workspace2/yolo_opencl/Dockerfile.opencl-base) Docker 基础镜像（OpenCL/POCL/PyTorch）
  - [docker-compose.yml](file:///d:/workspace2/yolo_opencl/docker-compose.yml) 多厂商运行编排（generic/Intel/Xilinx）

## Python 训练
- 安装依赖（建议 Python 3.10+）：
  - `pip install torch torchvision`
- 训练示例（默认会下载 CIFAR-10 到 ./data）：
  - `python minimal_yolo_torch.py --epochs 10 --batch-size 128 --lr 1e-3 --device cuda`
  - 若无 GPU：`python minimal_yolo_torch.py --device cpu`
- 训练产物：
  - 最佳模型权重保存为 `minimal_yolo_cifar10.pth`（包含 `state_dict` 与最佳精度）
- 相关函数：
  - 分类 logits 聚合：[forward_class_logits](file:///d:/workspace2/yolo_opencl/minimal_yolo_torch.py#L89-L95)
  - 数据加载与增强：[get_cifar10_loaders](file:///d:/workspace2/yolo_opencl/minimal_yolo_torch.py#L98-L116)
  - 训练/验证循环：[train_cifar10](file:///d:/workspace2/yolo_opencl/minimal_yolo_torch.py#L134-L160)

## 导出权重到 C++
- 命令：
  - `python export_minimal_yolo_weights.py --ckpt minimal_yolo_cifar10.pth --out minimal_yolo_weights.hpp --num-classes 10`
- 输出：
  - 生成 `minimal_yolo_weights.hpp`，包含所有 Conv 权重和 BatchNorm 参数，以及 Head 的输出层 1x1 Conv 的权重与 bias
  - 同时写入 `NUM_CLASSES=10`，供 C++ 推理读取
- 命名约定（示例）：
  - `b0_conv_w, b0_bn_gamma, b0_bn_beta, b0_bn_mean, b0_bn_var`
  - `b1_conv_w ... b5_conv_w ...`
  - `n3_conv_w, n4d_conv_w, n4_conv_w`
  - `h3c_conv_w, h3c_bn_* , h3_out_w, h3_out_b`
  - `h4c_conv_w, h4c_bn_* , h4_out_w, h4_out_b`

## C++ OpenCL 仅推理
- 推理程序入口与拓扑：[run_minimal_yolo_opencl.cpp](file:///d:/workspace2/yolo_opencl/run_minimal_yolo_opencl.cpp)
- 输入尺寸：`N=1, C=3, H=W=32`（当前使用随机输入做功能验证）
- 分类输出：
  - 从 `h3/h4` 的前 `NUM_CLASSES` 通道做全局平均，按 `(avg_h3 + avg_h4)/2` 聚合，打印 logits 与最佳类别索引
- 内核加载策略：
  - 通过环境变量 `CL_KERNEL_BINARY` 指定 OpenCL 程序：
    - 指向 `.cl` 时使用 `clCreateProgramWithSource` 编译
    - 指向 `.aocx/.xclbin` 时使用 `clCreateProgramWithBinary` 加载离线内核
  - 若未设置，则默认使用 `minimal_yolo_kernels.cl`


## 手工编译（主机内）
- 需先导出权重：
  - `python export_minimal_yolo_weights.py --ckpt minimal_yolo_cifar10.pth --out minimal_yolo_weights.hpp --num-classes 10`
- 安装 OpenCL 开发包并编译：
  - Linux 示例：`g++ -std=c++17 -O2 run_minimal_yolo_opencl.cpp -o build/run_minimal_yolo_opencl -lOpenCL`
- 运行：
  - `./build/run_minimal_yolo_opencl 10`
  - 可通过 `CL_KERNEL_BINARY` 指定 `.cl/.aocx/.xclbin`

## 常见问题
- 没有权重头文件：
  - 先按上面的导出步骤生成 `minimal_yolo_weights.hpp`
- FPGA 无法识别设备：
  - 请确认宿主机已安装并加载对应厂商驱动，并正确映射设备节点到容器
- 使用真实图片作为输入：
  - 当前程序用随机输入做功能验证，如需读取图片并预处理为 `NCHW 32x32`，可在 `run_minimal_yolo_opencl.cpp` 中加入图像读取与归一化逻辑