先说清楚一件事：YOLO 从来不是 Python 工程师的专属玩具。作为一个常年跟 Spring Boot、Maven 和 Java 8 打交道的老后端，我在真正接触目标检测之前，也以为 AI 落地是算法工程师的事，Java 顶多写个 API 壳子。直到某次项目里需要在服务端直接处理视频流里的目标识别，不想再单独维护一套 Python 微服务，我才花了两周时间把 YOLO 从模型导出到 Java 产线部署整条链路啃了下来。这篇文章就是把那段时间踩过的坑、验证过的方案、写进生产环境的代码逻辑，完整做个复盘。

适合谁看？服务端工程师、架构师，以及被要求“用 Java 把模型跑起来”又没什么头绪的开发者。我会从模型选型、转换格式、Java 推理框架，一路讲到 Spring Boot 里如何做并发控制、资源回收、模型热切换。实话实说，跑通一个 Demo 不难，难的是让它稳稳妥妥地扛住线上流量。

1. 先把技术路线定明白：Java 侧接入 YOLO 的几条路怎么选

1.1 主流接入方式大盘点

第一次搜 Java 怎么调用 YOLO，你会搜到很多看似可行、实则深浅不一的方案。我按实际工程侵入度和维护成本排了个序，这里直接分享对比结论。

先砍掉 Python 微服务方案。理由很简单：标题既然叫“Java 工程师玩转”，那核心诉求就是减少技术栈割裂。Java 服务里通过 HTTP 去调 Python，等于你写了半天 Java，最关键的推理环节还是黑盒，出了问题两边扯皮。而且每一个目标检测请求都要多一次网络往返，在视频帧密集场景下，延迟很难看。

OpenCV DNN 模块我单独说两句。它在简单分类模型上真香，代码几行就能跑，但如果模型里用了一些较新的算子（比如部分 YOLO 版本的多头注意力模块），会直接报 Unknown Layer 或者算子不支持。你不可能为了它去改模型结构，所以这个方案作为兜底可以，当作主力不行。

最后剩下 DJL 和 ONNX Runtime Java API 二选一。两个我都写了 Demo，最终选了 ONNX Runtime Java API。不是因为 DJL 不好，而是它封装层次太高，对 YOLO 这种“输入是图像、输出需要大量自定义后处理”的场景，你反而被它抽象出的 Predictor 接口束缚住，获取中间特征或精细控制内存不方便。ONNX Runtime 则更底层也更坦诚——你给它一个张量，它给你一个张量，中间的细节你自己掌控，这才符合后端工程师的控制欲。

1.2 为什么我最终选了 ONNX Runtime Java API

工程选型不能只看技术热度，还要看团队维护能力和排障半径。ONNX Runtime Java API 背后是微软在维护，模型算子兼容性迭代很快，你导出的 ONNX 基本都能加载。而且它支持 CPU、GPU 多种执行提供方，切换时只改配置不改代码，这一点对后续性能优化特别重要。

另一个让我倾向它的点是：它不强制你学习一套新的深度学习抽象体系。你只需要理解三件事：Session 加载模型、Tensor 构建输入、Tensor 读取输出。这对 Java 工程师非常友好，因为你的知识短板本来就不是“深度学习理论”，而是“模型 I/O 如何对接”，ONNX Runtime 恰好把这个边界划得很干净。

当然，代价也很明确：YOLO 的预处理和后处理（letterbox、归一化、NMS 非极大值抑制）在 Java 里没有现成的库给你调，全部要手写。这正是本文后面要花大篇幅展开的原因——模型推理本身只是内存搬运，真正的工程难点全在模型前后的数据处理。

2. 前置准备：把 YOLO 模型变成 Java 能用的“资产”

2.1 模型导出：从训练格式到 ONNX

不要去网上随便下载一个 .pt 权重文件就完事，YOLO 模型文件格式有好几种，你得保证导出 ONNX 时输入输出结构符合你的预期。我以最常用的 YOLOv8 为例，导出命令非常简单：

pip install ultralytics yolo export model=yolov8n.pt format=onnx imgsz=640 opset=12

导出后有四个关键点要确认：

第一，输入尺寸固定为 640x640。这是 YOLO 系列的标准输入分辨率。你当然可以导成 320 或者 1280，但模型训练时的默认锚框和感受野都是围绕 640 设计的，贸然改大会掉精度，改小会漏检。除非你有特殊需求，否则别动。

第二，opset 版本号。ONNX Runtime 不同版本对 opset 的兼容范围不一样，我习惯固定在 12。opset 太高，低版本的 ONNX Runtime 加载会报错；opset 太低，部分新算子无法导出。12 是一个平衡点，兼容性和算子支持都够用。

第三，导出时留意模型是否包含训练专用层。YOLO 的 export 方法会自动剥离训练头，导出为纯推理图。如果你是从其他框架手动转 ONNX，一定记得把 BatchNorm 和 Dropout 折叠掉，否则推理结果会和训练时不一致，而且 Java 侧排错极其痛苦。

第四，动态轴问题。默认导出的 ONNX 输入 shape 是 [1, 3, 640, 640]，这个 1 是 batch size。如果你想要更高的吞吐，可以导出为动态 batch（dynamic=True），但 Java 侧处理动态输入会复杂一些，而且不是所有生产场景都需要。没有并发批处理需求的话，固定 batch=1 最简单，性能也够。

2.2 拿到 ONNX 后的三项体检

模型导出后别急着写 Java，先做个“静态体检”。我用三个工具做检查，总共不超过十分钟。

先用 Netron 打开 ONNX 模型，人工确认输入节点名称、输出节点名称和数据维度。不同版本 YOLO 的输出节点名称差别很大：YOLOv5 的输出通常是一个 [1, 25200, 85] 的大张量，YOLOv8 的输出格式则变成了 [1, 84, 8400] 这样的三分支结构。你在 Java 解析时，必须知道输出张量的确切形状，否则索引错位会导致结果完全混乱。

接着写一个极简 Python 脚本，用 onnxruntime 加载模型，构造一个全零输入，跑一次推理。这一步不是为了测性能，而是为了确认模型本身没问题，顺便记录输出张量的 name、shape 和 dtype。这个信息后面写 Java 解析逻辑时会反复用到。

import onnxruntime as ort import numpy as np sess = ort.InferenceSession("yolov8n.onnx", providers=["CPUExecutionProvider"]) input_name = sess.get_inputs()[0].name output_names = [o.name for o in sess.get_outputs()] print(input_name, sess.get_inputs()[0].shape) for name in output_names: print(name, sess.get_outputs()[0].shape)

最后是精度基线确认。找一张带目标的测试图片，在 Python 里完成预处理、推理、后处理，记录目标数量和坐标。这张图存起来，后面 Java 侧跑出结果做比对用。千万不要跳过这步，Java 后处理代码写完后，如果没有基线，你根本分不清是模型问题还是代码问题。

2.3 预处理和后处理为什么必须自己写

很多 Java 工程师在这里会卡住：ONNX Runtime 只负责“张量进、张量出”，它不管你的图像怎么变成张量，也不管输出张量怎么变成坐标框。YOLO 模型的输入要求是：RGB 三通道、0-1 归一化、640x640 尺寸，并且图像要经过 letterbox 处理——也就是等比缩放后填充灰边，保证原始图像不变形。

你可能想问：不 letterbox，直接 resize 到 640x640 行不行？我试过，对于宽高比接近 1 的图可能问题不大，但换成长条形图片，目标直接被压扁，检测框偏移明显。letterbox 是为了让缩放比例保持统一，同时保留原始宽高比的语义信息。

后处理则更麻烦。模型输出的 8400 个候选框里，绝大部分是背景和低置信度预测，你要做的事包括：阈值过滤（objectness 和 class score）、类别置信度计算、以及 NMS（非极大值抑制）合并重叠框。这个过程在 Python 里有 numpy 和 torchvision 帮你向量化，但在 Java 里你得手动遍历数组，算坐标变换，做排序和去重。这就是“Java 玩 YOLO”最核心也最容易被低估的部分。

3. 在 Java 里把推理流程跑通：核心代码与关键参数

3.1 Maven 依赖与推理引擎初始化

Java 侧我用的是 ONNX Runtime 的官方 Java 包，在 Maven 里加一行依赖即可：

<dependency> <groupId>com.microsoft.onnxruntime</groupId> <artifactId>onnxruntime</artifactId> <version>1.17.1</version> </dependency>

注意这个包自带 Linux/Windows/macOS 的原生库，不需要额外安装。如果你是部署在 Docker 容器里，确保基础镜像的 glibc 版本不太旧就行。

推理引擎初始化是整个服务的核心。很多初学者会犯一个错误：每个请求都 new 一个 OrtSession，跑完就丢。这个代价极大，因为 ONNX 模型加载涉及大量的内存映射和算子初始化，一次加载可能要几百毫秒甚至更久。正确做法是在 Spring Boot 启动时加载一次，作为单例常驻。

import ai.onnxruntime.OrtEnvironment; import ai.onnxruntime.OrtSession; OrtEnvironment env = OrtEnvironment.getEnvironment(); OrtSession.SessionOptions opts = new OrtSession.SessionOptions(); opts.setIntraOpNumThreads(4); opts.setOptimizationLevel(OrtSession.SessionOptions.OptLevel.ALL_OPT); OrtSession session = env.createSession(modelPath, opts);

关于setIntraOpNumThreads我这里说明一下：它控制模型内部算子并行计算的线程数。并不是越大越好，当你的服务本身已经有线程池在跑并发请求时，每个 session 的算子线程再放大，CPU 上下文切换开销会吃掉性能。经过压测，在我的 8 核容器里，设为 4 是收益最高点。至于setOptimizationLevel，建议直接拉到ALL_OPT，ONNX Runtime 会自动做算子融合和常量折叠，推理延迟能再降 10% 到 20%。

3.2 图像预处理：Java 版 letterbox 与张量构造

图像读取和基础缩放，我用 OpenCV 的 Java 接口（org.bytedeco:javacv-platform 或者 org.opencv:opencv 均可）。OpenCV 在 Java 生态里是最成熟的图像处理库，不要在“纯 Java 实现图像缩放”上浪费时间。

letterbox 的核心逻辑是：计算缩放比例、得到填充后的画布尺寸、把原图贴到画布中央。直接上代码：

public static Mat letterbox(Mat src, int targetSize) { int h = src.rows(); int w = src.cols(); double scale = Math.min((double) targetSize / w, (double) targetSize / h); int newW = (int) Math.round(w * scale); int newH = (int) Math.round(h * scale); Mat resized = new Mat(); org.opencv.imgproc.Imgproc.resize(src, resized, new org.opencv.core.Size(newW, newH)); int padW = (targetSize - newW) / 2; int padH = (targetSize - newH) / 2; Mat canvas = new Mat(targetSize, targetSize, src.type(), new org.opencv.core.Scalar(114, 114, 114)); org.opencv.core.Mat roi = canvas.submat(padH, padH + newH, padW, padW + newW); resized.copyTo(roi); return canvas; }

注意灰边填充值是 114，这是 YOLO 训练时默认的填充色。如果你填 0，模型看到的图像边缘色彩和训练数据分布不一致，边界目标检测率会下降。

图像转张量这一步，坑在通道顺序和内存布局。YOLO 需要的是 RGB 顺序、归一化到 0-1 的浮点张量，而 OpenCV 读出来是 BGR，取值范围是 0-255，而且 Mat 默认是 HWC 内存布局。你要把它变成 ONNX Runtime 需要的 CHW 连续内存。

public static float[] matToTensorData(Mat mat) { Mat rgb = new Mat(); org.opencv.imgproc.Imgproc.cvtColor(mat, rgb, org.opencv.imgproc.Imgproc.COLOR_BGR2RGB); float[] data = new float[3 * 640 * 640]; for (int c = 0; c < 3; c++) { for (int i = 0; i < 640; i++) { for (int j = 0; j < 640; j++) { double[] pixel = rgb.get(i, j); data[c * 640 * 640 + i * 640 + j] = (float) (pixel[c] / 255.0); } } } return data; }

我知道这段代码性能很差，每次 get 像素都涉及 JNI 调用。实际上线时我改成了直接操作 Mat 的 ByteBuffer，再手动做通道重排，速度能快 3-5 倍。但作为演示，上面的实现最容易理解。先跑通，再优化，这是工程上的黄金顺序。

张量构造有两种方式：一种是用FloatBuffer包装上面的 float 数组，另一种是直接用OnnxTensor.createTensor(env, dataBuffer, shape)。注意dataBuffer必须用ByteBuffer.allocateDirect（堆外内存），ONNX Runtime 对堆内ByteBuffer支持不稳定，轻则性能差，重则直接抛异常。

3.3 推理调用与输出解析：从张量到检测框

推理调用本身只有一行：

OrtSession.Result result = session.run(Map.of(inputName, inputTensor));

这里的inputName是在 2.1 节里记录的输入节点名称，通常叫images。输出可以按输出名取，也可以按索引取。我建议按索引取，因为名称在不同版本间变化大，而索引顺序在导出时通常不会变。

拿到输出张量后，真正的重头戏开始了。以 YOLOv8 为例，输出 shape 是 [1, 84, 8400]。这个 84 的含义是：4（box 坐标 ）+ 80（COCO 类别概率）。8400 是三个不同尺度特征图上的候选框总数（80x80 + 40x40 + 20x20）。

解析第一步是把 8400 个候选框的解析做好：

float[] outputData = ((OnnxTensor) result.get(0)).getFloatBuffer().array(); int numBoxes = 8400; int numClasses = 80; List<Detection> detections = new ArrayList<>(); for (int i = 0; i < numBoxes; i++) { float cx = outputData[i]; float cy = outputData[numBoxes + i]; float w = outputData[2 * numBoxes + i]; float h = outputData[3 * numBoxes + i]; float maxScore = 0; int classId = -1; for (int j = 0; j < numClasses; j++) { float score = outputData[(4 + j) * numBoxes + i]; if (score > maxScore) { maxScore = score; classId = j; } } if (maxScore > 0.25f) { detections.add(new Detection(cx, cy, w, h, maxScore, classId)); } }

这里有两个容易翻车的地方。

第一个是索引计算。YOLOv8 的输出是“属性优先”布局，也就是先存所有候选框的第 0 个属性、再存第 1 个属性，以此类推。很多照着 YOLOv5 的解析习惯写的人，会把输出当成 [8400, 84] 的行优先布局，直接导致坐标和类别概率错位。我自己第一次跑出来的检测框全部偏到图像左上角，就是这个原因。

第二个是置信度阈值。0.25 是我测试后得到的比较稳的值。阈值太低，会有一堆低质量框；阈值太高，小目标容易漏检。这个参数在产线里建议放进配置中心，不要写死在代码里。

坐标解析用的 cx、cy、w、h 是模型预测的中心点坐标和宽高，它相对于 640x640 的输入图像。要映射回原始图像坐标，必须把 letterbox 的 pad 和 scale 反向计算：

int padX = padW; int padY = padH; double x1 = (cx - w / 2.0 - padX) / scale; double y1 = (cy - h / 2.0 - padY) / scale; double x2 = (cx + w / 2.0 - padX) / scale; double y2 = (cy + h / 2.0 - padY) / scale;

3.4 NMS：把重叠框合并成一个

NMS 的思路不复杂：把所有候选框按置信度降序排序，从最高分的框开始，保留它，然后剔除所有与它 IoU 超过阈值的其他框，重复这个过程直到处理完所有候选。

Java 实现我直接给出核心逻辑：

public static List<Detection> nms(List<Detection> detections, float iouThreshold) { detections.sort((a, b) -> Float.compare(b.score, a.score)); List<Detection> result = new ArrayList<>(); boolean[] suppressed = new boolean[detections.size()]; for (int i = 0; i < detections.size(); i++) { if (suppressed[i]) continue; result.add(detections.get(i)); for (int j = i + 1; j < detections.size(); j++) { if (!suppressed[j] && iou(detections.get(i), detections.get(j)) > iouThreshold) { suppressed[j] = true; } } } return result; }

IoU 就是两个框交集面积除以并集面积，用 x1/y1/x2/y2 四个坐标算即可。iouThreshold 一般取 0.45 到 0.5，我生产环境用的 0.45。

写 NMS 时有个性能细节：候选框可能上千个，双重循环是 O(n²)，在 Java 里面对几百个框还好，但如果你做一个实时视频流检测，每帧都跑 O(n²) 会累积成瓶颈。优化手段是：先按类别分组，不同类别的框不需要互相抑制，可以在每个类别内部做 NMS，这样循环次数能减少到原来的 1/类别数。

4. 从离线 Demo 到在线服务：工程化改造是真正的分水岭

4.1 并发模型：别让每一个请求都排队等推理

Demo 阶段你写完一个 main 方法，加载图片，输出结果，看起来一切完美。但拿到 Spring Boot 里一压测，吞吐量惨不忍睹，基本上就是串行执行。原因很简单：你很可能在 Controller 里直接调用那个保存为单例的 session，而同一个 ONNX Runtime session 内部有共享状态，无法并发执行推理。

解决方案有两条路。第一条是给 session 加锁，保证任意时刻只有一个线程在推理。这个方案在 CPU 推理场景下其实不算差，因为 ONNX Runtime 内部已经用多线程算子并行，你把服务层并发度压到 1，CPU 密集型任务反而能跑得更满，也避免线程之间互相争抢资源。缺点是你拿不到“多请求并行”的吞吐量，服务端同时来 10 个请求，9 个得排队。

第二条路是维护一个 session 池。既然单 session 不能并发，那就创建多个 session，每个占一个线程，用连接池的思路做负载分配。我参照线程池模型写了一个简单的 session 池：

public class OrtSessionPool { private final List<OrtSession> sessions; private final AtomicInteger index = new AtomicInteger(0); public OrtSessionPool(OrtEnvironment env, String modelPath, int poolSize) throws Exception { sessions = new ArrayList<>(); for (int i = 0; i < poolSize; i++) { sessions.add(env.createSession(modelPath, createOptions())); } } public OrtSession borrow() { return sessions.get(Math.floorMod(index.getAndIncrement(), sessions.size())); } }

池大小建议和 CPU 核心数 2 倍关系以内。因为每个 session 内部还会开 4 个算子线程，池越大，线程越多，一旦超过 CPU 核心数，你就在用上下文切换对抗并行计算。

这里我要多说一句：如果你有 GPU，情况会不同。GPU 推理的并发特性比 CPU 好很多，可以用更小的池甚至单 session + 流式提交。但本文主要面向大多数直接用 CPU 跑推理的中小型服务，GPU 的优化路径我这里不展开。

4.2 Spring Boot 集成：初始化、优雅关闭与超时

把上面的组件整合进 Spring Boot，用@Configuration管理生命周期：

@Configuration public class YoloConfig { @Bean(destroyMethod = "close") public OrtSessionPool yoloSessionPool( @Value("${yolo.model-path}") String modelPath, @Value("${yolo.pool-size}") int poolSize) throws Exception { OrtEnvironment env = OrtEnvironment.getEnvironment(); return new OrtSessionPool(env, modelPath, poolSize); } @Bean public YoloDetector yoloDetector(OrtSessionPool pool, @Value("${yolo.conf-threshold}") float confThreshold, @Value("${yolo.iou-threshold}") float iouThreshold) { return new YoloDetector(pool, confThreshold, iouThreshold); } }

@Bean(destroyMethod = "close")是每个 Java 工程师容易忽略的细节。OrtSession 持有堆外内存资源，如果不在 Spring 容器关闭时释放，服务重启时会造成内存泄漏累积，严重时会 OOM。显式声明 destroyMethod 后，Spring 会在容器销毁时自动调用 close。

超时控制更是刚需。模型推理偶尔会因为 CPU 抢占或异常输入拖长时间，你不希望一个慢请求占满 Tomcat 线程。我用 CompletableFuture 做最简单的超时包裹：

public DetectionResult detect(Mat image) throws Exception { Future<DetectionResult> future = CompletableFuture.supplyAsync(() -> doDetect(image), executor); return future.get(300, TimeUnit.MILLISECONDS); }

executor用线程池，300ms 是经过压测后选的值。正常 CPU 推理单帧大概 80-120ms，300ms 留给负载波动足够，又不至于拖垮整个服务。超时后记得丢弃这个任务，让它自己结束，不要中断线程（中断持锁的推理线程可能导致 ONNX Runtime 内部状态损坏）。

4.3 图像输入形态：Base64、文件、HTTP 流怎么统一

真实业务里，你的输入来源千奇百怪。最省事的方式是统一接收 Base64 编码的图像字符串。Controller 层只做一件事：解码，然后交给检测服务。

@PostMapping("/detect") public Result detect(@RequestBody DetectRequest request) { byte[] bytes = Base64.getDecoder().decode(request.getImageBase64()); Mat mat = Imgcodecs.imdecode(new MatOfByte(bytes), Imgcodecs.IMREAD_COLOR); DetectionResult result = yoloDetector.detect(mat); // 输出也要转回 Base64 或坐标数据 return Result.ok(result); }

这里我提醒一个细节：imdecode出来的 Mat 可能是任意尺寸，进入检测服务前最好做一次“快路径判断”。如果图片宽度超过 4000px，先等比缩小到宽 2000 以内再做推理。因为超清大图直接扔进 letterbox，最终细节都压缩没了，而且预处理时间会显著增加。对检测任务来说，1080P 的图像已经能覆盖绝大多数场景，没必要为超高分辨率付出推理延迟代价。

实时视频流场景更麻烦一点。如果你接入的是 RTSP 流，不要每帧都走 HTTP 调用，那延迟没法看。我当时的做法是：单独起一个抓帧线程，用 OpenCV VideoCapture 循环取帧，攒够一个时间窗口（比如每秒最多 5 帧），异步丢给检测线程池。检测结果写回 Redis 或内存队列，消费端直接读最新结果即可。这样把“抓帧”和“检测”解耦，任何一方慢都不会拖垮另一方。

5. 性能和稳定性：线上最容易翻车的三件事

5.1 内存稳定：堆外内存和 DirectByteBuffer

ONNX Runtime 的输入输出张量都是堆外内存，这意味着 JVM 的-Xmx可能完全无法约束它。你辛辛苦苦调好的 2G 堆，推理引擎在堆外悄无声息再吃几百 MB，一旦容器内存上限卡得紧，直接 OOM Kill。

我的经验是两个原则。第一，Tensor 用完立刻 close，千万不要依赖 GC。ONNX Runtime 的 Tensor 在被垃圾回收时虽然有关联的 cleaner，但你不知道它什么时候跑，在流量高峰期后果是灾难性的。第二，尽量复用 ByteBuffer，不要每次请求都 allocateDirect。一个 640x640x3 的 float 数组需要 4.9MB 堆外内存，并发 50 个请求就是 245MB，频繁申请释放会产生大量碎片。

推荐的复用方式：

ThreadLocal<ByteBuffer> bufferThreadLocal = ThreadLocal.withInitial( () -> ByteBuffer.allocateDirect(640 * 640 * 3 * 4) );

每个线程持有一个专用 Buffer，消除了并发竞争和反复分配。注意 ByteBuffer 的字节序要和模型输入一致，通常是ByteOrder.nativeOrder()，否则你填进去的 float 数据会是乱码，输出检测框坐标全是 NaN。

5.2 精度对不上：和 Python 结果不一致的排查顺序

你拿着模型在 Python 里跑得好好的，换到 Java 之后发现检测框偏移、置信度变了，甚至什么都检不出来。这个问题的排查顺序我建议固定为以下三步，不要跳步：

第一步查预处理。通道顺序对不对（OpenCV 默认 BGR，必须转 RGB）；归一化除没除 255；letterbox 的填充值是不是 114；缩放后有没有做过像素类型转换。这四项任何一个不对，结果都会天差地别。我统计过，大约 80% 的“Java 结果不对”都是预处理差异导致的。

第二步查输出布局。你在 3.3 节已经看到了，YOLOv8 是属性优先布局，不是行优先。用getFloatBuffer读数组时，要确保你取的数据顺序和模型输出端一致。这一步错了，解析出来的坐标会张冠李戴。

第三步查数值类型。ONNX Runtime 输出的是 float32，你如果用 float64 数组接收，精度波动虽然在可接受范围，但如果后端代码里不小心把 float 和 double 混用，某些 JVM 优化后的比较逻辑可能出现反直觉的结果。保持全程 float32，不要混型。

我把精度排查做成了一张速查表：

5.3 资源释放：别让你的服务跑三天就挂

Kubernetes 里 Java 服务跑三天后宿主机内存飙升，十有八九和推理资源未释放有关。ONNX Runtime 的释放链条是：OrtSession 的 Result 要 close、OnnxTensor 要 close、ByteBuffer 虽然归 GC 管但 DirectBuffer 需要手动回收。

最常见的泄漏点，是很多人只关了 session，忽略了 Result。Session.run 返回的 Result 里包含多个 OnnxTensor，它们持有堆外内存。完整写法是这样：

try (OrtSession.Result result = session.run(inputs)) { OnnxTensor outputTensor = (OnnxTensor) result.get(0); FloatBuffer buffer = outputTensor.getFloatBuffer(); // 业务处理 }

Java 7 的 try-with-resources 在这里完美适配，Result 实现了 Closeable，关闭它时内部 Tensor 也会释放。同理，输入的 OnnxTensor 也要在推理完成后关闭：

try (OnnxTensor inputTensor = OnnxTensor.createTensor(env, buffer, shape)) { try (OrtSession.Result result = session.run(Map.of("images", inputTensor))) { // ... } }

我把这个准则在代码评审时定成铁律：凡是createTensor或run出来的对象，要么 try-with-resources，要么在 finally 中显式 close，没有第三种写法。

另外一个隐性资源是 OpenCV 的 Mat。每次imdecode创建 Mat，用完不 release 会累积原生内存。JavaCV 的 Mat 有close()方法，同样建议放进 finally 里。我用了一个简单的封装，把所有 Mat 生命周期管理交给 try-with-resources。

6. 产线落地的完整路径：灰度、监控与模型迭代

6.1 一个真实的落地案例：从摄像头画面到业务结果

讲一个我做过的某零售项目的简化版案例，帮助你把前面所有内容串起来。场景是店铺摄像头抓拍画面，需要实时识别货架上的商品类别和数量，辅助补货决策。

整体架构是这样：摄像头 RTSP 流 → 抓帧服务（Java）→ 帧图像发送到内部 Kafka 队列 → 消费端调用 YOLO 检测服务 → 检测结果写入 Redis 并以 WebSocket 推送给前端。

抓帧服务处理 4 路 RTSP 流，每路流单独一个抓帧线程，每秒抽帧 5 张。用了 5.2 节说的“快路径判断”，先看图像分辨率，高于 1920 的先缩小。Kafka 在这里的作用是削峰填谷，因为摄像头画面在促销时段会频繁变化，检测服务的处理能力相对恒定，直接用同步 HTTP 调用容易积压。

这个案例里有个小优化很值得说：检测服务对同一路流的结果做了“时间平滑”。因为单帧检测偶尔会漏检或误检，我保留最近 5 帧的检测结果，用多数投票决定最终输出。比如连续 5 帧里 4 帧检测到某个商品，那这个商品的置信度就很高；反之，如果只有 1 帧检到，大概率是误检。这个策略让识别准确率在业务报表层面提升了约 7%，而算法本身没有任何改动。

6.2 模型版本管理与灰度发布

模型文件不是一次性部署就完事的。你后续一定会因为新增类别、调优精度而训练新模型，这时就面临模型切换问题。最稳妥方式不是重新打包发布整个服务，而是模型文件与代码解耦，做成配置化加载。

我在项目里的做法：

models/ yolov8n_v1.onnx yolov8n_v2.onnx current_version # 文本文件，内容为 yolov8n_v2.onnx

Java 服务启动时读current_version文件，动态拼接模型路径。服务对外保留一个管理接口，修改版本文件后，调用预热接口重新加载模型到新的 session 池，然后把流量切过去。

灰度发布的细节在于“预热”。新模型用真实流量预热 10 秒，确认无报错，再从旧 session 池切换到新 session 池。切换过程要保证双池并存一段时间，避免切换瞬间出现 4xx/5xx。

public synchronized void switchModel(String newModelPath) throws Exception { OrtSessionPool newPool = new OrtSessionPool(env, newModelPath, poolSize); // 预热一次 newPool.borrow().run(preheatInput); // 旧池最后关闭 OrtSessionPool oldPool = this.sessionPool; this.sessionPool = newPool; oldPool.close(); }

我强烈建议保留“一键回滚”按钮。因为模型切换不像代码发布，你没法通过 git revert 回滚。只要新旧 session 池切换后检测结果出现大面积异常，立刻切换回旧模型。项目上线头两周，我因为新模型在一类光线条件下误检率剧增，回滚了至少三次。

6.3 监控指标与告警：模型也要像接口一样被观察

模型推理接入产线后，最怕的不是功能问题，而是“静默劣化”——接口正常返回，但是检测结果不准确了。你要在监控系统里建立一套专门指标。

延迟指标：P99 推理延迟、预处理耗时、后处理耗时分开统计。不要只报一个总延迟，否则根本无法定位到底是图像处理慢了还是模型推理慢了。

正确性指标：这里有个技巧，用“无检测结果率”作为粗粒度告警。正常情况下，一帧画面里至少应该检出一些目标，如果连续 10 分钟内检测结果为空的比例超过 60%，大概率是模型加载异常或输入图像质量出了问题。

资源指标：堆外内存用量、线程池活跃度、session borrow 等待时间。这部分我建议走 Micrometer 接入 Prometheus，Grafana 里配置看板。Java 工程师对这套体系已经很熟了，只需要把推理组件相关的指标补充进去。

还有一个小细节：模型输出的类别分布也要做统计。比如某个类别在业务上预期占比约 20%，如果实际突然飙升到 60%，不是业务变了就是模型抽风了。类别分布异常比单纯延迟告警更有业务价值，因为它能提前发现数据分布漂移。

写在最后的实操体会

整个链路走下来，我最深的体会是：Java 做 YOLO 部署，难度根本不在推理框架本身，而在“工程整合”这四个字。ONNX Runtime 给 Java 提供了足够好的底层能力，但围绕它的图像处理、内存管理、并发控制、模型版本管理，全部还是要靠后端基本功。

如果你第一次尝试，建议按这个顺序推进：先把 Python 导出 ONNX、用 Netron 确认节点结构；再在 Java 里跑通一张图的预处理、推理、后处理；然后把 NMS 的正确性验证透，拿业务图片多测几轮；最后才是 Spring Boot 集成和性能优化。千万不要一上来就想着接 Kafka 或者 GPU，那样一旦出问题，你连排查的抓手都没有。

最后再送一个实用小技巧：所有可能在流程中出问题的参数——置信度阈值、IoU 阈值、填充值、模型路径、线程数——全部放进配置中心，因为产线调参的频率远比你想象得高，而且每次调参都要发版的话，运维会疯掉的。