先说个背景别嫌我啰嗦。我之前在某边缘计算项目里接到一个需求要把一个已经训练好的YOLO检测模型集成到一套纯Java的后端服务里跑实时行为分析然后部署到一台低功耗边缘设备上。那段时间我翻遍了社区里的帖子发现一个很扎心的事实网上90%的YOLO实战文章都是PythonCUDAJava能参考的内容少得可怜偶尔找到几篇也停留在“跑通一个Demo”的程度离真正落地差了十万八千里。这篇文章就把我当时从模型适配到边缘部署的完整链路拆开讲一遍。不聊虚的全是实操包括Java端怎么加载ONNX模型、怎么处理letterbox和坐标映射、行为分析那部分是怎么在“只有检测框”的情况下实现越界和逗留判定的以及最后部署到边缘盒子时踩过的一堆性能坑。如果你也是Java后端工程师想在项目里引入目标检测但不想为了这事单独拆一个Python服务出来这篇文章应该能帮你少走不少弯路。1. 为什么非要用Java跑检测模型而不是老老实实套个Python壳子我猜很多人第一反应是YOLO这种明显偏Python生态的东西为什么要硬塞给Java直接起一个Python进程当算法服务不就行了吗这个想法本身没毛病中小型项目里也确实有人这么干但它在某些场景下会带来比想象中更多的麻烦。1.1 业务系统里的真实困境我当时所在的系统主体是一套老牌的Java服务负责视频流接入、告警工单、设备管理这些事。如果检测这块单独拆成Python服务意味着要同时维护两套部署环境、两套日志体系、两套异常处理机制。更难受的是检测结果一旦涉及业务联动——比如检测到入侵行为要给值班人员派单Java业务代码就要跨进程去调Python接口中间多了一层网络开销和序列化开销出了问题排查起来也费劲。所以在Java进程内直接做推理不是为了炫技而是为了降低整体系统的复杂度和运维成本。一个进程扛下所有事情链路短、可控性强、部署也简单。代价是Java侧做CV相关的脏活累活都得自己来但这些坑一旦趟平了后面维护起来是真的省心。1.2 三种Java推理方案我最后选了哪个Java生态里跑YOLO绕不开三个主流方案OpenCV DNN、ONNX Runtime、DJL。我先把三者的核心差异列个表再说我的选择。方案底层引擎算子覆盖部署体积上手难度适合场景OpenCV DNNOpenCV自带仅基础算子中等低快速验证、简单模型ONNX Runtime微软ONNX Runtime覆盖全支持NMS较大中生产级推理多平台DJL可切换引擎依赖后端引擎较大中高同时想要深度学习训练/推理一体化我的结论是生产环境首选ONNX Runtime。原因有三个。第一模型兼容性Ultralytics导出的ONNX模型ONNX Runtime基本能直接吃不用做太多算子改造。第二后处理支持ONNX Runtime的Java API虽然不能像Python那样直接调torchvision.ops.nms但我们可以把NMS逻辑写在Java侧性能完全够。第三多平台支持它原生支持Linux ARM64、x86、Windows这对边缘部署很重要模型不用换换个so库就行。OpenCV DNN我也试过它的问题是有些较新的模型结构特别是用到一些自定义算子的会直接报错不支持而且OpenCV那套Mat API在Java里处理图片要特别小心内存释放搞不好就OutOfMemory。DJL是个好框架但抽象层厚调起来涉及很多额外概念对于只做推理的项目来说有点重了。2. 模型适配链路从PyTorch权重到Java能读的ONNX模型模型适配是整个流程里最容易出问题的环节因为大部分教程会直接把导出这一步带过仿佛model.export()一句话就完事了。实际上这里的细节决定了后续Java代码的复杂度。2.1 导出ONNX前的三个决策尺寸、动态轴和预处理第一步是确认输入尺寸。YOLOv8默认是640×640这个尺寸对边缘设备来说可以接受。如果你追求更高帧率可以导出成416×416或者320×320但检测效果会下降。我建议在项目初期先把640跑通后面再根据性能瓶颈测试是否降尺寸。第二步是决定是否使用动态轴。导出ONNX时PyTorch的torch.onnx.export有个dynamic_axes参数可以把batch维度甚至宽高维度设成动态。但我在Java侧实测下来动态宽高是个大坑一是ONNX Runtime Java API对这部分的封装不友好二是在边缘设备上固定形状能明显提升推理速度。所以我的建议是batch设动态可以因为要跑批量推理时方便但宽高锁定640。第三步很关键预处理参数要不要融进模型里Ultralytics导出ONNX时默认会把归一化和某些通道变换融进计算图里但你还是要自己处理letterbox等比例缩放填充。仔细看导出的模型输入节点接收的是0-1范围内的浮点数而不是原始0-255的像素值所以Java端要记得先做归一化再喂给模型。2.2 导出实操我用的是这种方法如果你用的是Ultralytics的包导出代码非常简单from ultralytics import YOLO model YOLO(best.pt) model.export(formatonnx, imgsz640, dynamic{bbox: True}, simplifyTrue, opset12)但这里有个细节dynamic{bbox: True}不一定会在导出后保持输出张量的动态性我曾在某个模型上遇到导出后仍是固定形状的情况当时没深究因为固定形状也能跑。关键导出完成后一定要用Python脚本验证一下import onnxruntime as ort import numpy as np session ort.InferenceSession(best.onnx) input_name session.get_inputs()[0].name output_names [o.name for o in session.get_outputs()] print(输入:, input_name, session.get_inputs()[0].shape) print(输出:, output_names, [session.get_outputs()[i].shape for i in range(len(output_names))]) # 模拟一张640x640的输入 dummy np.random.randn(1, 3, 640, 640).astype(np.float32) outs session.run(output_names, {input_name: dummy}) print(输出尺寸:, [o.shape for o in outs])这里输出的形状直接决定你Java侧怎么解析数据务必记录下来。以YOLOv8为例当检测类别数为80时输出通常是1×84×8400——84代表4个坐标cx, cy, w, h加80个类别分数8400代表640×640输入下所有候选框的数量不同尺度的特征图加起来。2.3 后处理放模型图里还是放Java代码里Ultralytics的ONNX导出支持nmsTrue参数能把NMS算子直接融进模型里这样模型输出直接就是筛选后的检测框。听起来很香对吧但我实际用下来发现一个很尴尬的情况某些ONNX Runtime版本对模型中集成NMS的支持不稳定报错或者结果不正确而且集成NMS后模型体积变大、推理速度变慢。我的选择是Java侧手写后处理。核心就是解析1×84×8400这份数据先按置信度阈值筛掉大部分框再做IoU计算用非极大值抑制去掉重叠框。这部分逻辑用Java写并不复杂而且出了任何问题都能自己掌控。2.4 预处理对齐letterbox的细节目标检测的输入通常不能直接resize因为那样会拉伸图像导致检测框变形所以需要用letterbox做等比例缩放四周补灰边。这一步看似简单但有两个细节容易翻车。第一个是通道顺序。Java侧用OpenCV读图得到的是BGR而模型训练时用的是RGB。忘记转换的话检测效果会明显变差框歪、置信度低而且很难排查。第二个是归一化尺度。导出ONNX时预处理已经内嵌了1/255的归一化Java侧不要再额外除以255否则输入范围变成0~0.0039模型什么都检不出来。// 伪代码示意 Mat resized new Mat(); // 计算缩放比例 double scale Math.min(640.0 / img.cols(), 640.0 / img.rows()); Size newSize new Size(Math.round(img.cols() * scale), Math.round(img.rows() * scale)); Imgproc.resize(img, resized, newSize); // 创建640x640画布灰度127填充 Mat canvas new Mat(new Size(640, 640), img.type(), new Scalar(127, 127, 127)); // 把resized贴到画布中央 resized.copyTo(canvas.submat(0, resized.rows(), 0, resized.cols())); // BGR转RGB Imgproc.cvtColor(canvas, canvas, Imgproc.COLOR_BGR2RGB); // 转CHW并归一化到0-1 float[] chw new float[3 * 640 * 640]; // 填充chw数组...这个letterbox的缩放比例和填充偏移量后面要用到因为检测框坐标是在640×640画布上的要映射回原始图像尺寸才能正确显示。3. 工程核心Java端推理代码的骨架与性能细节模型适配完之后真正的工程难点开始了怎么把推理代码写得又快又稳还能支撑多路视频流。3.1 ONNX Runtime Java API的最小可用代码ONNX Runtime在Java中的基本用法很固定创建OrtEnvironment用createSession加载模型然后每次推理时构造OnnxTensor调用session.run拿到结果。import ai.onnxruntime.*; public class YoloDetector { private final OrtEnvironment env; private final OrtSession session; private final String inputName; public YoloDetector(String modelPath) throws OrtException { env OrtEnvironment.getEnvironment(); session env.createSession(modelPath, new OrtSession.SessionOptions()); inputName session.getInputNames().iterator().next(); } public float[][][] detect(float[] chwData) throws OrtException { // 构造输入tensorshape为 [1, 3, 640, 640] long[] shape {1L, 3L, 640L, 640L}; OnnxTensor inputTensor OnnxTensor.createTensor(env, chwData, shape); OrtSession.Result result session.run(java.util.Collections.singletonMap(inputName, inputTensor)); // 拿到输出 OnnxTensor outputTensor (OnnxTensor) result.get(0); float[][][] output (float[][][]) outputTensor.getValue(); inputTensor.close(); result.close(); return output; // 形状为 [1, 84, 8400] 或 [1, 5N, 8400] } }这里特别强调一下session必须在整个程序生命周期内复用不能每次检测都重新创建。createSession的代价非常高包含了模型文件读取、计算图构建、内存分配我实测一次模型加载差不多要几百毫秒到一两秒放到实时检测流程里是灾难。3.2 内存管理与多路视频流的并发设计边缘设备的内存本来就紧Java又有GC如果每帧都产生大量临时对象GC停顿会导致视频流卡顿。我后来做了三件事效果立竿见影。第一输入tensor复用。不要每帧都createTensor而是申请一个固定大小的ByteBuffer或float[]把像素数据填进去复用。OnnxTensor.createTensor也可以包装一个已有的ByteBuffer这样能大幅度减少对象创建。更激进的做法是直接用FloatBuffer配合OnnxTensor.createTensor(env, buffer, shape, memoryType)但要小心内存对齐。第二输出解析的数组池。YOLO输出有8400个候选框Java侧做置信度过滤、坐标转换、NMS时会产生大量临时数组。我把这些数组做成可回收的对象池或者直接复用ArrayList并在每次检测前clear()能把GC频率压到安全范围。第三多路视频流用线程池。每个摄像头流的抽帧、推理、行为分析任务可以用一个固定大小的线程池来调度关键在于控制最大并发数。实时性要求高的场景可以设置一个有界队列满了就丢弃最老的帧保证处理的永远是最新一帧。这个策略在真实场景里非常有效因为如果处理速度跟不上等着的那些旧帧已经没意义了不如及时丢帧。3.3 性能实测把预算花在刀刃上我在一台Intel边缘盒子上实测过CPU型号大概就是常见的i7-8550U级别跑YOLOv8s模型640输入FP32精度单路视频流的推理耗时大约在80-120ms一帧加上解码和前后处理整体在150ms左右。这个数字意味着大约6-8帧每秒对行为分析来说基本够用但如果想跑得更流畅或者同时处理多路流就必须上模型量化或者换硬件加速器。有一句话我想写在前面不要一开始就追求极限帧率先保证流程能稳定跑起来再按瓶颈逐段优化。很多人在模拟环境里跑得很爽一到真实场景就崩往往就是前期把大量时间花在了不重要的优化上。4. 实时视频流的接入与行为分析逻辑检测模型跑通了只是一半另一半是把检测结果翻译成业务能理解的行为事件。这部分我分享一下我用的最朴素的方案。4.1 RTSP拉流、解码与抽帧边缘设备上拉RTSP流我用的JavaCV封装了FFmpeg。核心代码如下FFmpegFrameGrabber grabber new FFmpegFrameGrabber(rtsp://xxx); grabber.setOption(rtsp_transport, tcp); // TCP传输更稳 grabber.setOption(fflags, nobuffer); // 降低延迟 grabber.setOption(flags, low_delay); grabber.start(); Java2DFrameConverter converter new Java2DFrameConverter(); while (running) { Frame frame grabber.grabImage(); if (frame null) { // 断流重连逻辑 grabber.restart(); continue; } Mat mat new Mat(converter.convert(frame)); // 丢到检测线程池 pool.execute(new DetectTask(mat)); }几个关键点的经验rtsp_transporttcpUDP在某些网络环境下会花屏、丢包TCP虽然延迟稍高但稳定性好很多。断流重连必须做。摄像头断电、网络抖动都会导致grabImage()返回null此时要设置一个退避重连策略比如第一次等3秒之后每次翻倍最大不超过30秒。抽帧策略不要每帧都送去检测一是性能扛不住二是行为分析本身就允许一定的时间间隔。10-15帧里抽1帧通常足够。4.2 行为分析如何在只有检测框的情况下做判断行 为分析听起来高级但在没有姿态估计模型的情况下我们只能基于检测框的位置、大小、轨迹来做规则判定。这套方案简单可靠适合越界、逗留、闯入这类场景。越界检测定义一条或多条线段作为警戒线。人的检测框中心点cx, cy如果从一线段的一侧跨到另一侧就触发越界事件。判定用向量叉积就能算// 判断点P是否在直线AB的某一侧 double cross (b.x - a.x) * (p.y - a.y) - (b.y - a.y) * (p.x - a.x); // cross 0 在一侧cross 0 在另一侧然后记录每个人上一帧所处的侧别只要侧别发生变化且变化方向符合预设比如从“安全区”跨入“危险区”就触发报警。逗留检测逗留是指在某个区域里待的时间超过阈值。核心是追踪同一目标并累计时间。如果用YOLO直接输出结果每一帧的人都是独立的需要做轻量级目标追踪不然没法区分前后帧的“同一个人”。最简单的追踪算法是基于质心距离的IOU匹配对当前帧的每个检测框计算它与上一帧所有检测框的IoU或者中心点欧氏距离取相似度最高的那个作为同一目标然后更新时间戳。这种方案在人群密度不高的场景下特别有效完全不需要引入额外的追踪模型。跌倒检测跌倒检测其实是这类规则方案里比较实用的一个。思路是检测类别为“person”的框计算宽高比h/w或者w/h并跟踪中心点速度。当人的pose从站立宽高比较大突然变成躺卧宽高比较小且中心点在短时间内发生了快速位移就判定为跌倒。要注意的是这种基于2D框的方法对视角很敏感摄像头侧面视角效果最好俯视视角会误报。这也是落地时需要在方案文档里写清楚的限制。行为分析这一层的核心思想就是把检测结果当作数据源用规则去匹配业务语义。它不需要多复杂的模型但在真实场景中的确能解决大部分需求。4.3 追踪器的一个实际坑目标编号跳变前面提到的IoU匹配追踪在目标被遮挡数帧后会失效重新出现时会被当成新目标导致逗留时间被重置。我当时的临时方案是保留每个目标的“失帧缓冲”允许目标消失最多5帧仍然保留追踪ID这样大部分短时遮挡都能撑过去。这个缓冲值要根据实际帧率调整值太大会导致两个不同的人被当成同一个。5. 边缘部署落地从性能瓶颈到守护运维模型在开发机上跑得再好部署到边缘盒子又是另一回事。这一章讲硬件选型、模型量化和正式运行时的运维细节。5.1 硬件选型和模型量化带来的质变边缘设备我试过两种形态一类是Intel CPU的工业盒子一类是带GPU的嵌入式平台比如Jetson系。Java在这两类设备上都能跑真正的区别在于推理引擎的加速方式。带GPU的设备可以通过CUDA加速ONNX RuntimeJava API里只需要在创建SessionOptions时指定setExecutionMode和setOptimizationLevel或者用CUDA Provider。但要注意Jetson上的CUDA Provider安装在默认配置里没有需要自己事先编译/安装这一步很容易在环境准备阶段卡住。如果是纯CPU设备我强烈建议你尝试模型量化。ONNX Runtime的Java API支持加载INT8量化的模型但模型本身得预先量化好。我这里提供一个粗糙但实用的量化方法用Ultralytics的export(formatonnx, int8True, datacoco.yaml)它会使用校准数据集做动态量化。实测下来YOLOv8n从FP32转INT8mAP会下降1-3个百分点但帧率可能提升2-3倍在边缘设备上这笔买卖通常非常划算。精度类型模型大小推理耗时(Intel盒子上)精度表现FP32约42MB约90ms/帧基准FP16约21MB约60ms/帧基本无损INT8约11MB约30ms/帧轻微下降5.2 部署形态systemd守护与自我恢复Java服务部署到边缘设备上不能指望有人天天盯着进程。我用的是systemd管理服务[Unit] DescriptionEdge Detection Service Afternetwork.target [Service] Typesimple Useredge WorkingDirectory/opt/edge-detection ExecStart/usr/bin/java -Xmx1g -jar edge-detection.jar Restartalways RestartSec5 EnvironmentMODEL_PATH/data/models/best_int8.onnx EnvironmentSTREAM_URLrtsp://xxx [Install] WantedBymulti-user.target这里特别强调Restartalways。边缘设备的稳定性远没有服务器那么可靠断电、内存不足、网络断开都是常态服务能自动拉起是底线。另外日志要轮转。我用logback配置了按天滚动最多保留7天。边缘设备存储有限日志撑爆磁盘导致服务崩溃这种低级问题一定要提前避免。5.3 一台机器跑多个模型实例的内存与并发规划如果你需要在同一台设备上跑多个模型比如一个模型检测人另一个检测车辆就得提前规划内存和并发策略。以JVM进程为例-Xmx设1GB两个实例就是2GB起步再加上设备上其他服务的内存占用很容易触顶。我有两个建议一是在一个JVM进程内创建多个OrtSession共用同一个OrtEnvironment二是按优先级排队把显存/CPU资源按轮询分配到不同任务避免同时跑满。还有个很容易被忽视的点线程数不等于性能提升。边缘设备的CPU核心数有限我用4核心的盒子跑2路视频流推理线程设置为2解码线程设置为2效果刚好。线程设多了反而因为上下文切换导致吞吐下降。6. 踩坑实录排查了三个通宵才搞定的问题最后这部分是我最想写的。因为有些问题在官方文档里永远找不到答案只能靠一个坑一个坑地踩。6.1 检测结果全空原因是模型输入节点名不是“images”我拿到的第一个模型导出之后输入名是images后面换了一个新模型输入名变成了input。Java代码里我写死的还是session.getInputNames().iterator().next()按道理动态获取不应该出错。但有一个版本getInputNames()返回的集合顺序和我预期的不一致我直接取了第一个元素结果传错了输入名推理结果全是空的。排查了非常久最后打印了session.getInputInfo()才发现问题。教训是哪怕是用迭代器动态获取也要把输入名先打日志确认一次不要想当然。6.2 letterbox之后检测框坐标没映射回原图这个问题出现得非常隐蔽。我在Java侧做letterbox之后检测框在640×640画布上是对的在画布上可视化也没问题。但一旦要叠加到原始摄像头画面上显示就需要把检测框坐标还原成原图坐标x_original (x_canvas - pad_x) / scale y_original (y_canvas - pad_y) / scale忘记反向映射的话框的位置偏移特别明显而且越靠近右下角偏移越大。这类坐标映射问题一定要写单元测试把letterbox的缩放比例和填充偏移都用固定样例验证一遍。6.3 “第一次推理特别慢”是正常的别乱优化ONNX Runtime在第一次执行推理时会做很多初始化工作包括内存池分配、线程池预热所以第一帧可能耗时300ms以上之后逐步稳定在80ms。这不是模型或者代码有问题是引擎的懒加载机制。处理方式是程序启动后立即做一次“预热推理”跑一张空图把初始化全部触发掉再开始处理真实视频流。6.4 CPU被打满但GPU利用率不到20%这个现象尤其容易出现在“采集-处理-分析”全链路里。有一次我在带GPU的设备上跑检测CPU核心全部跑到100%显卡却闲着一开始以为是推理卡的模型有问题后来仔细排查发现瓶颈在解码环节。JavaCV拉RTSP流做软解码特别吃CPU而且我用的是grabImage()它不只是解码还在做图像格式转换。解法是不要用JavaCV的解码输出直接做检测而是让视频解码走硬件加速有些底层库支持或者降低解码帧率只解需要的抽帧频率。这件事的教训是当你发现某个环节资源占用异常先确定瓶颈在哪一层不要只盯着推理那一层看。最后分享一点体会整个项目从模型适配到边缘部署前前后后花了两周多。说实话最花时间的不是写代码而是查明那些莫名其妙的问题。如果你现在正准备用Java做YOLO检测我有一个建议第一步不要追求多路流、行为分析这些高级功能先把“单路视频流-推理-画框显示”整个链路跑通再去叠加复杂度。另外有个小技巧把模型的元信息输入名、输出名、类别数、输入尺寸在启动时打印到日志里或者干脆在配置文件里写明。别看这个动作不起眼它在后期排查问题的时候能帮你节省大量时间。部署到边缘设备前先在目标设备上跑一段基准测试记录处理延迟和帧率再评估是否需要量化。模型不是越准越好而是越适合硬件和业务场景越好。 
长河君 · 2026/10/23 3:37:07 · 阅读 1.2k Java + ONNX Runtime实现YOLO目标检测：从模型部署到边缘实战
先说个背景别嫌我啰嗦。我之前在某边缘计算项目里接到一个需求要把一个已经训练好的YOLO检测模型集成到一套纯Java的后端服务里跑实时行为分析然后部署到一台低功耗边缘设备上。那段时间我翻遍了社区里的帖子发现一个很扎心的事实网上90%的YOLO实战文章都是PythonCUDAJava能参考的内容少得可怜偶尔找到几篇也停留在“跑通一个Demo”的程度离真正落地差了十万八千里。这篇文章就把我当时从模型适配到边缘部署的完整链路拆开讲一遍。不聊虚的全是实操包括Java端怎么加载ONNX模型、怎么处理letterbox和坐标映射、行为分析那部分是怎么在“只有检测框”的情况下实现越界和逗留判定的以及最后部署到边缘盒子时踩过的一堆性能坑。如果你也是Java后端工程师想在项目里引入目标检测但不想为了这事单独拆一个Python服务出来这篇文章应该能帮你少走不少弯路。1. 为什么非要用Java跑检测模型而不是老老实实套个Python壳子我猜很多人第一反应是YOLO这种明显偏Python生态的东西为什么要硬塞给Java直接起一个Python进程当算法服务不就行了吗这个想法本身没毛病中小型项目里也确实有人这么干但它在某些场景下会带来比想象中更多的麻烦。1.1 业务系统里的真实困境我当时所在的系统主体是一套老牌的Java服务负责视频流接入、告警工单、设备管理这些事。如果检测这块单独拆成Python服务意味着要同时维护两套部署环境、两套日志体系、两套异常处理机制。更难受的是检测结果一旦涉及业务联动——比如检测到入侵行为要给值班人员派单Java业务代码就要跨进程去调Python接口中间多了一层网络开销和序列化开销出了问题排查起来也费劲。所以在Java进程内直接做推理不是为了炫技而是为了降低整体系统的复杂度和运维成本。一个进程扛下所有事情链路短、可控性强、部署也简单。代价是Java侧做CV相关的脏活累活都得自己来但这些坑一旦趟平了后面维护起来是真的省心。1.2 三种Java推理方案我最后选了哪个Java生态里跑YOLO绕不开三个主流方案OpenCV DNN、ONNX Runtime、DJL。我先把三者的核心差异列个表再说我的选择。方案底层引擎算子覆盖部署体积上手难度适合场景OpenCV DNNOpenCV自带仅基础算子中等低快速验证、简单模型ONNX Runtime微软ONNX Runtime覆盖全支持NMS较大中生产级推理多平台DJL可切换引擎依赖后端引擎较大中高同时想要深度学习训练/推理一体化我的结论是生产环境首选ONNX Runtime。原因有三个。第一模型兼容性Ultralytics导出的ONNX模型ONNX Runtime基本能直接吃不用做太多算子改造。第二后处理支持ONNX Runtime的Java API虽然不能像Python那样直接调torchvision.ops.nms但我们可以把NMS逻辑写在Java侧性能完全够。第三多平台支持它原生支持Linux ARM64、x86、Windows这对边缘部署很重要模型不用换换个so库就行。OpenCV DNN我也试过它的问题是有些较新的模型结构特别是用到一些自定义算子的会直接报错不支持而且OpenCV那套Mat API在Java里处理图片要特别小心内存释放搞不好就OutOfMemory。DJL是个好框架但抽象层厚调起来涉及很多额外概念对于只做推理的项目来说有点重了。2. 模型适配链路从PyTorch权重到Java能读的ONNX模型模型适配是整个流程里最容易出问题的环节因为大部分教程会直接把导出这一步带过仿佛model.export()一句话就完事了。实际上这里的细节决定了后续Java代码的复杂度。2.1 导出ONNX前的三个决策尺寸、动态轴和预处理第一步是确认输入尺寸。YOLOv8默认是640×640这个尺寸对边缘设备来说可以接受。如果你追求更高帧率可以导出成416×416或者320×320但检测效果会下降。我建议在项目初期先把640跑通后面再根据性能瓶颈测试是否降尺寸。第二步是决定是否使用动态轴。导出ONNX时PyTorch的torch.onnx.export有个dynamic_axes参数可以把batch维度甚至宽高维度设成动态。但我在Java侧实测下来动态宽高是个大坑一是ONNX Runtime Java API对这部分的封装不友好二是在边缘设备上固定形状能明显提升推理速度。所以我的建议是batch设动态可以因为要跑批量推理时方便但宽高锁定640。第三步很关键预处理参数要不要融进模型里Ultralytics导出ONNX时默认会把归一化和某些通道变换融进计算图里但你还是要自己处理letterbox等比例缩放填充。仔细看导出的模型输入节点接收的是0-1范围内的浮点数而不是原始0-255的像素值所以Java端要记得先做归一化再喂给模型。2.2 导出实操我用的是这种方法如果你用的是Ultralytics的包导出代码非常简单from ultralytics import YOLO model YOLO(best.pt) model.export(formatonnx, imgsz640, dynamic{bbox: True}, simplifyTrue, opset12)但这里有个细节dynamic{bbox: True}不一定会在导出后保持输出张量的动态性我曾在某个模型上遇到导出后仍是固定形状的情况当时没深究因为固定形状也能跑。关键导出完成后一定要用Python脚本验证一下import onnxruntime as ort import numpy as np session ort.InferenceSession(best.onnx) input_name session.get_inputs()[0].name output_names [o.name for o in session.get_outputs()] print(输入:, input_name, session.get_inputs()[0].shape) print(输出:, output_names, [session.get_outputs()[i].shape for i in range(len(output_names))]) # 模拟一张640x640的输入 dummy np.random.randn(1, 3, 640, 640).astype(np.float32) outs session.run(output_names, {input_name: dummy}) print(输出尺寸:, [o.shape for o in outs])这里输出的形状直接决定你Java侧怎么解析数据务必记录下来。以YOLOv8为例当检测类别数为80时输出通常是1×84×8400——84代表4个坐标cx, cy, w, h加80个类别分数8400代表640×640输入下所有候选框的数量不同尺度的特征图加起来。2.3 后处理放模型图里还是放Java代码里Ultralytics的ONNX导出支持nmsTrue参数能把NMS算子直接融进模型里这样模型输出直接就是筛选后的检测框。听起来很香对吧但我实际用下来发现一个很尴尬的情况某些ONNX Runtime版本对模型中集成NMS的支持不稳定报错或者结果不正确而且集成NMS后模型体积变大、推理速度变慢。我的选择是Java侧手写后处理。核心就是解析1×84×8400这份数据先按置信度阈值筛掉大部分框再做IoU计算用非极大值抑制去掉重叠框。这部分逻辑用Java写并不复杂而且出了任何问题都能自己掌控。2.4 预处理对齐letterbox的细节目标检测的输入通常不能直接resize因为那样会拉伸图像导致检测框变形所以需要用letterbox做等比例缩放四周补灰边。这一步看似简单但有两个细节容易翻车。第一个是通道顺序。Java侧用OpenCV读图得到的是BGR而模型训练时用的是RGB。忘记转换的话检测效果会明显变差框歪、置信度低而且很难排查。第二个是归一化尺度。导出ONNX时预处理已经内嵌了1/255的归一化Java侧不要再额外除以255否则输入范围变成0~0.0039模型什么都检不出来。// 伪代码示意 Mat resized new Mat(); // 计算缩放比例 double scale Math.min(640.0 / img.cols(), 640.0 / img.rows()); Size newSize new Size(Math.round(img.cols() * scale), Math.round(img.rows() * scale)); Imgproc.resize(img, resized, newSize); // 创建640x640画布灰度127填充 Mat canvas new Mat(new Size(640, 640), img.type(), new Scalar(127, 127, 127)); // 把resized贴到画布中央 resized.copyTo(canvas.submat(0, resized.rows(), 0, resized.cols())); // BGR转RGB Imgproc.cvtColor(canvas, canvas, Imgproc.COLOR_BGR2RGB); // 转CHW并归一化到0-1 float[] chw new float[3 * 640 * 640]; // 填充chw数组...这个letterbox的缩放比例和填充偏移量后面要用到因为检测框坐标是在640×640画布上的要映射回原始图像尺寸才能正确显示。3. 工程核心Java端推理代码的骨架与性能细节模型适配完之后真正的工程难点开始了怎么把推理代码写得又快又稳还能支撑多路视频流。3.1 ONNX Runtime Java API的最小可用代码ONNX Runtime在Java中的基本用法很固定创建OrtEnvironment用createSession加载模型然后每次推理时构造OnnxTensor调用session.run拿到结果。import ai.onnxruntime.*; public class YoloDetector { private final OrtEnvironment env; private final OrtSession session; private final String inputName; public YoloDetector(String modelPath) throws OrtException { env OrtEnvironment.getEnvironment(); session env.createSession(modelPath, new OrtSession.SessionOptions()); inputName session.getInputNames().iterator().next(); } public float[][][] detect(float[] chwData) throws OrtException { // 构造输入tensorshape为 [1, 3, 640, 640] long[] shape {1L, 3L, 640L, 640L}; OnnxTensor inputTensor OnnxTensor.createTensor(env, chwData, shape); OrtSession.Result result session.run(java.util.Collections.singletonMap(inputName, inputTensor)); // 拿到输出 OnnxTensor outputTensor (OnnxTensor) result.get(0); float[][][] output (float[][][]) outputTensor.getValue(); inputTensor.close(); result.close(); return output; // 形状为 [1, 84, 8400] 或 [1, 5N, 8400] } }这里特别强调一下session必须在整个程序生命周期内复用不能每次检测都重新创建。createSession的代价非常高包含了模型文件读取、计算图构建、内存分配我实测一次模型加载差不多要几百毫秒到一两秒放到实时检测流程里是灾难。3.2 内存管理与多路视频流的并发设计边缘设备的内存本来就紧Java又有GC如果每帧都产生大量临时对象GC停顿会导致视频流卡顿。我后来做了三件事效果立竿见影。第一输入tensor复用。不要每帧都createTensor而是申请一个固定大小的ByteBuffer或float[]把像素数据填进去复用。OnnxTensor.createTensor也可以包装一个已有的ByteBuffer这样能大幅度减少对象创建。更激进的做法是直接用FloatBuffer配合OnnxTensor.createTensor(env, buffer, shape, memoryType)但要小心内存对齐。第二输出解析的数组池。YOLO输出有8400个候选框Java侧做置信度过滤、坐标转换、NMS时会产生大量临时数组。我把这些数组做成可回收的对象池或者直接复用ArrayList并在每次检测前clear()能把GC频率压到安全范围。第三多路视频流用线程池。每个摄像头流的抽帧、推理、行为分析任务可以用一个固定大小的线程池来调度关键在于控制最大并发数。实时性要求高的场景可以设置一个有界队列满了就丢弃最老的帧保证处理的永远是最新一帧。这个策略在真实场景里非常有效因为如果处理速度跟不上等着的那些旧帧已经没意义了不如及时丢帧。3.3 性能实测把预算花在刀刃上我在一台Intel边缘盒子上实测过CPU型号大概就是常见的i7-8550U级别跑YOLOv8s模型640输入FP32精度单路视频流的推理耗时大约在80-120ms一帧加上解码和前后处理整体在150ms左右。这个数字意味着大约6-8帧每秒对行为分析来说基本够用但如果想跑得更流畅或者同时处理多路流就必须上模型量化或者换硬件加速器。有一句话我想写在前面不要一开始就追求极限帧率先保证流程能稳定跑起来再按瓶颈逐段优化。很多人在模拟环境里跑得很爽一到真实场景就崩往往就是前期把大量时间花在了不重要的优化上。4. 实时视频流的接入与行为分析逻辑检测模型跑通了只是一半另一半是把检测结果翻译成业务能理解的行为事件。这部分我分享一下我用的最朴素的方案。4.1 RTSP拉流、解码与抽帧边缘设备上拉RTSP流我用的JavaCV封装了FFmpeg。核心代码如下FFmpegFrameGrabber grabber new FFmpegFrameGrabber(rtsp://xxx); grabber.setOption(rtsp_transport, tcp); // TCP传输更稳 grabber.setOption(fflags, nobuffer); // 降低延迟 grabber.setOption(flags, low_delay); grabber.start(); Java2DFrameConverter converter new Java2DFrameConverter(); while (running) { Frame frame grabber.grabImage(); if (frame null) { // 断流重连逻辑 grabber.restart(); continue; } Mat mat new Mat(converter.convert(frame)); // 丢到检测线程池 pool.execute(new DetectTask(mat)); }几个关键点的经验rtsp_transporttcpUDP在某些网络环境下会花屏、丢包TCP虽然延迟稍高但稳定性好很多。断流重连必须做。摄像头断电、网络抖动都会导致grabImage()返回null此时要设置一个退避重连策略比如第一次等3秒之后每次翻倍最大不超过30秒。抽帧策略不要每帧都送去检测一是性能扛不住二是行为分析本身就允许一定的时间间隔。10-15帧里抽1帧通常足够。4.2 行为分析如何在只有检测框的情况下做判断行 为分析听起来高级但在没有姿态估计模型的情况下我们只能基于检测框的位置、大小、轨迹来做规则判定。这套方案简单可靠适合越界、逗留、闯入这类场景。越界检测定义一条或多条线段作为警戒线。人的检测框中心点cx, cy如果从一线段的一侧跨到另一侧就触发越界事件。判定用向量叉积就能算// 判断点P是否在直线AB的某一侧 double cross (b.x - a.x) * (p.y - a.y) - (b.y - a.y) * (p.x - a.x); // cross 0 在一侧cross 0 在另一侧然后记录每个人上一帧所处的侧别只要侧别发生变化且变化方向符合预设比如从“安全区”跨入“危险区”就触发报警。逗留检测逗留是指在某个区域里待的时间超过阈值。核心是追踪同一目标并累计时间。如果用YOLO直接输出结果每一帧的人都是独立的需要做轻量级目标追踪不然没法区分前后帧的“同一个人”。最简单的追踪算法是基于质心距离的IOU匹配对当前帧的每个检测框计算它与上一帧所有检测框的IoU或者中心点欧氏距离取相似度最高的那个作为同一目标然后更新时间戳。这种方案在人群密度不高的场景下特别有效完全不需要引入额外的追踪模型。跌倒检测跌倒检测其实是这类规则方案里比较实用的一个。思路是检测类别为“person”的框计算宽高比h/w或者w/h并跟踪中心点速度。当人的pose从站立宽高比较大突然变成躺卧宽高比较小且中心点在短时间内发生了快速位移就判定为跌倒。要注意的是这种基于2D框的方法对视角很敏感摄像头侧面视角效果最好俯视视角会误报。这也是落地时需要在方案文档里写清楚的限制。行为分析这一层的核心思想就是把检测结果当作数据源用规则去匹配业务语义。它不需要多复杂的模型但在真实场景中的确能解决大部分需求。4.3 追踪器的一个实际坑目标编号跳变前面提到的IoU匹配追踪在目标被遮挡数帧后会失效重新出现时会被当成新目标导致逗留时间被重置。我当时的临时方案是保留每个目标的“失帧缓冲”允许目标消失最多5帧仍然保留追踪ID这样大部分短时遮挡都能撑过去。这个缓冲值要根据实际帧率调整值太大会导致两个不同的人被当成同一个。5. 边缘部署落地从性能瓶颈到守护运维模型在开发机上跑得再好部署到边缘盒子又是另一回事。这一章讲硬件选型、模型量化和正式运行时的运维细节。5.1 硬件选型和模型量化带来的质变边缘设备我试过两种形态一类是Intel CPU的工业盒子一类是带GPU的嵌入式平台比如Jetson系。Java在这两类设备上都能跑真正的区别在于推理引擎的加速方式。带GPU的设备可以通过CUDA加速ONNX RuntimeJava API里只需要在创建SessionOptions时指定setExecutionMode和setOptimizationLevel或者用CUDA Provider。但要注意Jetson上的CUDA Provider安装在默认配置里没有需要自己事先编译/安装这一步很容易在环境准备阶段卡住。如果是纯CPU设备我强烈建议你尝试模型量化。ONNX Runtime的Java API支持加载INT8量化的模型但模型本身得预先量化好。我这里提供一个粗糙但实用的量化方法用Ultralytics的export(formatonnx, int8True, datacoco.yaml)它会使用校准数据集做动态量化。实测下来YOLOv8n从FP32转INT8mAP会下降1-3个百分点但帧率可能提升2-3倍在边缘设备上这笔买卖通常非常划算。精度类型模型大小推理耗时(Intel盒子上)精度表现FP32约42MB约90ms/帧基准FP16约21MB约60ms/帧基本无损INT8约11MB约30ms/帧轻微下降5.2 部署形态systemd守护与自我恢复Java服务部署到边缘设备上不能指望有人天天盯着进程。我用的是systemd管理服务[Unit] DescriptionEdge Detection Service Afternetwork.target [Service] Typesimple Useredge WorkingDirectory/opt/edge-detection ExecStart/usr/bin/java -Xmx1g -jar edge-detection.jar Restartalways RestartSec5 EnvironmentMODEL_PATH/data/models/best_int8.onnx EnvironmentSTREAM_URLrtsp://xxx [Install] WantedBymulti-user.target这里特别强调Restartalways。边缘设备的稳定性远没有服务器那么可靠断电、内存不足、网络断开都是常态服务能自动拉起是底线。另外日志要轮转。我用logback配置了按天滚动最多保留7天。边缘设备存储有限日志撑爆磁盘导致服务崩溃这种低级问题一定要提前避免。5.3 一台机器跑多个模型实例的内存与并发规划如果你需要在同一台设备上跑多个模型比如一个模型检测人另一个检测车辆就得提前规划内存和并发策略。以JVM进程为例-Xmx设1GB两个实例就是2GB起步再加上设备上其他服务的内存占用很容易触顶。我有两个建议一是在一个JVM进程内创建多个OrtSession共用同一个OrtEnvironment二是按优先级排队把显存/CPU资源按轮询分配到不同任务避免同时跑满。还有个很容易被忽视的点线程数不等于性能提升。边缘设备的CPU核心数有限我用4核心的盒子跑2路视频流推理线程设置为2解码线程设置为2效果刚好。线程设多了反而因为上下文切换导致吞吐下降。6. 踩坑实录排查了三个通宵才搞定的问题最后这部分是我最想写的。因为有些问题在官方文档里永远找不到答案只能靠一个坑一个坑地踩。6.1 检测结果全空原因是模型输入节点名不是“images”我拿到的第一个模型导出之后输入名是images后面换了一个新模型输入名变成了input。Java代码里我写死的还是session.getInputNames().iterator().next()按道理动态获取不应该出错。但有一个版本getInputNames()返回的集合顺序和我预期的不一致我直接取了第一个元素结果传错了输入名推理结果全是空的。排查了非常久最后打印了session.getInputInfo()才发现问题。教训是哪怕是用迭代器动态获取也要把输入名先打日志确认一次不要想当然。6.2 letterbox之后检测框坐标没映射回原图这个问题出现得非常隐蔽。我在Java侧做letterbox之后检测框在640×640画布上是对的在画布上可视化也没问题。但一旦要叠加到原始摄像头画面上显示就需要把检测框坐标还原成原图坐标x_original (x_canvas - pad_x) / scale y_original (y_canvas - pad_y) / scale忘记反向映射的话框的位置偏移特别明显而且越靠近右下角偏移越大。这类坐标映射问题一定要写单元测试把letterbox的缩放比例和填充偏移都用固定样例验证一遍。6.3 “第一次推理特别慢”是正常的别乱优化ONNX Runtime在第一次执行推理时会做很多初始化工作包括内存池分配、线程池预热所以第一帧可能耗时300ms以上之后逐步稳定在80ms。这不是模型或者代码有问题是引擎的懒加载机制。处理方式是程序启动后立即做一次“预热推理”跑一张空图把初始化全部触发掉再开始处理真实视频流。6.4 CPU被打满但GPU利用率不到20%这个现象尤其容易出现在“采集-处理-分析”全链路里。有一次我在带GPU的设备上跑检测CPU核心全部跑到100%显卡却闲着一开始以为是推理卡的模型有问题后来仔细排查发现瓶颈在解码环节。JavaCV拉RTSP流做软解码特别吃CPU而且我用的是grabImage()它不只是解码还在做图像格式转换。解法是不要用JavaCV的解码输出直接做检测而是让视频解码走硬件加速有些底层库支持或者降低解码帧率只解需要的抽帧频率。这件事的教训是当你发现某个环节资源占用异常先确定瓶颈在哪一层不要只盯着推理那一层看。最后分享一点体会整个项目从模型适配到边缘部署前前后后花了两周多。说实话最花时间的不是写代码而是查明那些莫名其妙的问题。如果你现在正准备用Java做YOLO检测我有一个建议第一步不要追求多路流、行为分析这些高级功能先把“单路视频流-推理-画框显示”整个链路跑通再去叠加复杂度。另外有个小技巧把模型的元信息输入名、输出名、类别数、输入尺寸在启动时打印到日志里或者干脆在配置文件里写明。别看这个动作不起眼它在后期排查问题的时候能帮你节省大量时间。部署到边缘设备前先在目标设备上跑一段基准测试记录处理延迟和帧率再评估是否需要量化。模型不是越准越好而是越适合硬件和业务场景越好。