1. 为什么需要手写一个Java版YOLO推理引擎？

在目标检测领域，YOLO系列模型因其速度和精度的平衡而广受欢迎。但很多开发者在使用时，往往直接调用ONNX Runtime或TensorRT等现成推理引擎的API，这就像只会开车却不懂发动机原理一样。当我第一次尝试用纯Java实现YOLOv8推理时，才真正理解了那些隐藏在API背后的精妙设计。

这个轻量级实现的核心价值在于教学意义。它剥离了工业级推理引擎的复杂优化（如GPU加速、算子融合），让我们能聚焦三个最关键的环节：

  1. 输入预处理 ：如何把一张普通图片转换成模型能理解的数字矩阵
  2. 前向推理 ：模型内部的数据流动与变换过程（虽然我们做了简化）
  3. 输出后处理 ：从一堆晦涩的数字中提取出人类可理解的检测结果

注意：由于Java在矩阵运算上的性能局限，我们不会真的实现所有卷积运算，而是用预计算的模型输出来模拟。这就像先用静态数据学习汽车仪表盘读数含义，再深入引擎原理。

2. 项目结构与核心类设计

先来看工程的整体结构。为了让代码更易维护，我设计了这些核心类：

// 定义检测结果的数据结构
public class DetectionResult {
    private String className;
    private float confidence;
    private float[] bbox; // [x_center, y_center, width, height]
    // getters & setters...
}

// 主引擎类
public class YOLOv8Java {
    private static final int INPUT_SIZE = 640;
    
    public List<DetectionResult> predict(BufferedImage image) {
        float[] inputTensor = preprocess(image);
        float[] outputTensor = forward(inputTensor); // 模拟推理
        return postprocess(outputTensor);
    }
    
    private float[] preprocess(BufferedImage image) { ... }
    private float[] forward(float[] input) { ... }
    private List<DetectionResult> postprocess(float[] output) { ... }
}

这种设计有几点考虑：

  • DetectionResult 封装了检测结果，避免到处使用原始数组
  • YOLOv8Java 作为主类，明确划分三个核心阶段
  • INPUT_SIZE 常量避免魔法数字，方便后续适配不同版本YOLO

3. 输入预处理详解

预处理的目标是把任意尺寸的RGB图片转换为640x640的归一化float数组。这里有几个技术细节需要注意：

3.1 保持长宽比的缩放

直接拉伸图片会导致目标变形。正确做法是先计算缩放比例，然后在较短的边填充灰边：

BufferedImage paddedImage = new BufferedImage(640, 640, BufferedImage.TYPE_INT_RGB);
Graphics2D g = paddedImage.createGraphics();
g.setColor(Color.GRAY); // 填充色
g.fillRect(0, 0, 640, 640);

// 计算保持比例的缩放尺寸
double scale = Math.min(640.0 / image.getWidth(), 640.0 / image.getHeight());
int scaledWidth = (int)(image.getWidth() * scale);
int scaledHeight = (int)(image.getHeight() * scale);

// 居中绘制缩放后的图像
int x = (640 - scaledWidth) / 2;
int y = (640 - scaledHeight) / 2;
g.drawImage(image.getScaledInstance(scaledWidth, scaledHeight, Image.SCALE_SMOOTH), x, y, null);

3.2 归一化与通道转换

YOLO模型期望的输入是：

  • 像素值归一化到0~1
  • 通道顺序为CHW（Channel-Height-Width）
  • 数据类型为float32
float[] chwData = new float[3 * 640 * 640];
int[] rgb = paddedImage.getRGB(0, 0, 640, 640, null, 0, 640);

for (int i = 0; i < rgb.length; i++) {
    int pixel = rgb[i];
    // 注意OpenCV默认是BGR顺序
    chwData[i] = ((pixel >> 16) & 0xFF) / 255.0f; // R
    chwData[i + 640*640] = ((pixel >> 8) & 0xFF) / 255.0f; // B
    chwData[i + 2*640*640] = (pixel & 0xFF) / 255.0f; // G
}

踩坑提醒：很多教程会忽略通道顺序问题。OpenCV默认使用BGR，而Java的BufferedImage是RGB。如果顺序错了，模型性能会大幅下降！

4. 模拟前向推理

真实的前向推理包含数十个卷积层、激活函数等复杂计算。为简化学习，我们直接从文件加载预计算的输出：

private float[] forward(float[] input) {
    // 实际项目中这里应该是真正的模型计算
    // 我们改为从资源文件加载预计算的输出
    try (InputStream is = getClass().getResourceAsStream("/yolov8n_output.bin")) {
        byte[] bytes = is.readAllBytes();
        float[] output = new float[bytes.length / 4];
        ByteBuffer.wrap(bytes).asFloatBuffer().get(output);
        return output;
    } catch (IOException e) {
        throw new RuntimeException("加载模型输出失败", e);
    }
}

这个模拟输出的维度是[1,84,8400]，对应YOLOv8的输出格式：

  • 1：batch size
  • 84：每个检测框的数据（4坐标 + 80类置信度）
  • 8400：预测框总数（3个检测头的总和）

5. 输出后处理实战

后处理是YOLO推理中最复杂的部分，需要完成三个关键步骤：

5.1 解析原始输出

首先将8400个预测框转换为Java对象：

List<DetectionResult> rawResults = new ArrayList<>();
for (int i = 0; i < 8400; i++) {
    float[] bbox = Arrays.copyOfRange(output, i*84, i*84+4);
    float[] scores = Arrays.copyOfRange(output, i*84+4, i*84+84);
    
    int classId = 0;
    float maxScore = 0;
    for (int j = 0; j < 80; j++) {
        if (scores[j] > maxScore) {
            maxScore = scores[j];
            classId = j;
        }
    }
    
    if (maxScore > 0.25f) { // 初步置信度过滤
        DetectionResult dr = new DetectionResult();
        dr.setClassName(COCO_CLASSES[classId]);
        dr.setConfidence(maxScore);
        dr.setBbox(bbox);
        rawResults.add(dr);
    }
}

5.2 坐标转换

模型输出的bbox是[x_center, y_center, width, height]格式，且是相对于640x640输入尺寸的。需要转换回原始图片坐标：

// 获取实际图像区域（去除灰边）
int origW = image.getWidth();
int origH = image.getHeight();
float scale = Math.min(640.0f / origW, 640.0f / origH);
int padW = (int)((640 - origW * scale) / 2);
int padH = (int)((640 - origH * scale) / 2);

// 转换坐标
float[] bbox = result.getBbox();
float x = (bbox[0] - padW) / scale;
float y = (bbox[1] - padH) / scale;
float w = bbox[2] / scale;
float h = bbox[3] / scale;
// 转换为[x1,y1,x2,y2]格式
float[] converted = new float[]{x-w/2, y-h/2, x+w/2, y+h/2};

5.3 非极大值抑制(NMS)

NMS用于消除冗余检测框，保留最合适的那个：

List<DetectionResult> finalResults = new ArrayList<>();
rawResults.sort((a,b) -> Float.compare(b.getConfidence(), a.getConfidence()));

while (!rawResults.isEmpty()) {
    DetectionResult best = rawResults.remove(0);
    finalResults.add(best);
    
    Iterator<DetectionResult> it = rawResults.iterator();
    while (it.hasNext()) {
        DetectionResult other = it.next();
        if (iou(best.getBbox(), other.getBbox()) > 0.45f) {
            it.remove();
        }
    }
}

其中IOU（交并比）计算：

private float iou(float[] box1, float[] box2) {
    float area1 = (box1[2]-box1[0])*(box1[3]-box1[1]);
    float area2 = (box2[2]-box2[0])*(box2[3]-box2[1]);
    
    float x1 = Math.max(box1[0], box2[0]);
    float y1 = Math.max(box1[1], box2[1]);
    float x2 = Math.min(box1[2], box2[2]);
    float y2 = Math.min(box1[3], box2[3]);
    
    float inter = Math.max(0, x2-x1) * Math.max(0, y2-y1);
    return inter / (area1 + area2 - inter);
}

6. 性能优化与扩展方向

虽然这个实现侧重教学，但仍有优化空间：

6.1 内存优化技巧

  • 重用float数组而非频繁创建新数组
  • 使用ByteBuffer直接操作二进制数据
  • 对中间结果使用对象池
// 对象池示例
private static final Queue<float[]> ARRAY_POOL = new ConcurrentLinkedQueue<>();

float[] getTempArray(int size) {
    float[] arr = ARRAY_POOL.poll();
    if (arr == null || arr.length < size) {
        return new float[size];
    }
    return arr;
}

void releaseArray(float[] arr) {
    ARRAY_POOL.offer(arr);
}

6.2 扩展真实推理

如果想实现完整推理，可以：

  1. 用JavaCPP调用OpenCV的DNN模块
  2. 使用ND4J等Java矩阵库实现卷积运算
  3. 自己实现最基础的卷积算法（教学用）
// 简单卷积示例（非优化版）
public static float[] conv2d(float[] input, int width, int height, 
                            float[] kernel, int kSize) {
    float[] output = new float[(width-kSize+1)*(height-kSize+1)];
    
    for (int y = 0; y <= height - kSize; y++) {
        for (int x = 0; x <= width - kSize; x++) {
            float sum = 0;
            for (int ky = 0; ky < kSize; ky++) {
                for (int kx = 0; kx < kSize; kx++) {
                    sum += input[(y+ky)*width + (x+kx)] * kernel[ky*kSize + kx];
                }
            }
            output[y*(width-kSize+1) + x] = sum;
        }
    }
    return output;
}

7. 常见问题排查

在实际教学中，学生们常遇到这些问题：

  1. 检测框偏移 ：通常是坐标转换时没考虑padding。建议绘制预处理后的图像检查填充是否正确
  2. 置信度异常低 ：检查通道顺序（RGB/BGR）和归一化范围（0-1）
  3. NMS后结果过多 ：调整IOU阈值（通常0.4-0.6）和置信度阈值（0.25-0.5）
  4. 性能瓶颈 ：Java数组操作较慢，热点可能在：
    • 图像缩放（改用原生方法）
    • 大数组拷贝（使用System.arraycopy）
    • 嵌套循环（尝试展开或分块）

这个轻量级实现虽然不能用于生产环境，但通过剥离复杂性，确实让我更清晰地理解了YOLO推理的每个细节。建议读者可以尝试在此基础上逐步添加真实卷积运算、多线程处理等功能，最终实现一个完整的Java推理引擎。

# 目标检测
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区