表面缺陷质检 — 部署指南

套餐

IP 摄像头 + reComputer J30 / J40（Orin）

Jetson Orin 拉取摄像头的 RTSP 流做缺陷检测，判定输出到 Modbus TCP 与 MQTT，PLC 可选接入。

  • 摄像头： 任意对着钢带或工件取景的 RTSP 摄像头，准备好带用户名密码的 RTSP 地址并先用 VLC 测过。
  • 使用限制： 仅限内部验证。模型训练自 NEU-DET 的转载版，用于对外 demo、客户现场或商业物料前须先与数据集方确认许可，或用自己的图像重训。crazing 类精度在六类中最低，调阈值无法改善；帧级误报须用自己的产线图像测。
  • 网络： PLC 或 MES 能访问设备的 502（Modbus）和 1883（MQTT）端口。
1

部署表面质检

部署检测器并在设备上构建 TensorRT engine，预留约 10 分钟，首次启动需等构建完成。

前置条件
  1. 模型文件未上 CDN（许可未确认）：部署前手工把 yolox_tiny_neu6.onnx 放到设备的 ~/edge-inspection-surface/jetson_inspection/models/yolox_tiny_neu6.onnx，部署时会校验 sha256。
  2. 判定阈值默认 0.35。
  3. 检测器 Track：默认 yolox；dfine、rtdetrv2 可选，构建耗时以实际为准，0.35 阈值是按 yolox 标定的，换 track 后按自己的产线图像调整。
故障排查
现象处理
engine 构建报 Static model does not take explicit shapes用上游 build_engine.sh 手工构建时设 TRT_STATIC_SHAPE=true
engine 构建失败或中途停下确认 /usr/src/tensorrt/bin/trtexec 存在、磁盘有 10 GB 可用；删掉残留的 .part 文件后重试
容器里 numpy.core.multiarray failed to import，或 cv2 导入失败只挂载宿主的 /usr/lib/python3.10/dist-packages/tensorrt，不要挂整个 dist-packages
docker compose 去读 ._docker-compose.yml 报错在 compose 目录执行 find . -name '._*' -delete
相机没有画面用 VLC 测 RTSP 地址，检查路径和用户名密码
ONNX 的 sha256 对不上删掉文件，重新拷贝正确的模型文件
部署连不上 SSH确认 SSH 可达、用户名正确（常用 recomputer、nvidia 或 ubuntu）
部署方式

通过 SSH 部署到 Jetson。设备须为 JetPack 6.x 且 NVIDIA container runtime 可用，至少 10 GB 可用磁盘。

部署时需要填写（在 SenseCraft Solution 应用里填）
  • Jetson IP*
  • SSH 用户名*默认 recomputer

    常见默认值：recomputer（Seeed reComputer J30 / J40 系列）、nvidia 或 ubuntu。

  • SSH 密码*
  • 设备名称*默认 orin-nx

    MQTT 主题的第一段——按产线或工位命名，多台设备在同一个 broker 上就不会混

  • 流编号*默认 line1-cam1

    会拼在 MQTT 主题里，用于区分同一台设备上的多路相机

  • 相机 RTSP 地址*

    先用 VLC 测一下这个地址——路径或用户名密码写错是最常见的失败原因

  • 产线节拍（FPS）*默认 10

    从视频源取帧的速率。所有实测时延数字都是在 10 FPS 下取得的。

  • 检测器 Track*默认 yolox
    3 项可选
    • · YOLOX-Tiny——有实测数据的默认部署项
    • · D-FINE-S——CPU 基准显示等精度下召回更高；尚无 Orin engine 实测耗时
    • · RT-DETRv2-S——仅有 CPU 基准，CPU 上比 D-FINE 慢；尚无 Orin engine 实测耗时

    选择构建并运行哪种检测器架构。yolox 是唯一在这块板上实测过的 track（TensorRT engine，构建 291 s），也是 Hailo 套餐上唯一提供的 一个。dfine 与 rtdetrv2 在 CPU-only 对比（单种子，见方案页）里 等精度下召回持平或更高，但还没有在 Orin 上构建过 engine 或计过时—— 本页所有 291 s 构建耗时与 Jetson 时延数字，在补上之前只对 yolox 成立。

  • 判定阈值*默认 0.35
    3 项可选
    • · 0.25——召回更高，误报更多
    • · 0.35——部署冻结值（按 yolox 标定）
    • · 0.45——精度更高，漏检更多

    检测框计入 NG 判定的分数门限。0.35 是按 YOLOX 的 obj×cls 分数分布在 290 张 val 图上标定的冻结值，见方案页。dfine/rtdetrv2 没有单独重新 标定——它们的 sigmoid decoder 分数分布不同，同一个数值在那两个 track 上不代表同一个置信水平。

  • Modbus 从站号*默认 1

    502 端口上 Modbus TCP 的 unit id。指南里的寄存器表按 unit 1 写。

2

查看实时检测画面

打开设备自带页面，查看实时画面上的检测框和健康计数。

故障排查
现象处理
页面打不开执行 docker ps 确认容器已起，并确认 8080 端口没有被占用
预览在动但从来不出框先看 /events 里最近的判定，再确认画面里有缺陷或调低阈值
frames_dropped 一直涨调低配置的 FPS，或减少路数
mqtt.rejected 非零查看容器日志中的契约校验错误
部署完成后

结果发到 MQTT 1883 端口的 <设备名>/inspection/<流编号>/results，判定同时写到 Modbus TCP 502 端口、unit 1 的线圈 0 与 1。

快速验证

  1. 打开 http://<设备 IP>:8080/，MJPEG 预览在动。
  2. 打开 http://<设备 IP>:8080/healthz：inference_time_ms 为几毫秒，10 FPS 下 frames_dropped 为 0，mqtt.rejected 为 0。
  3. 把一件有缺陷的样品放到相机前，出现带类别名与分数的检测框。
  4. 在另一台机器执行 mosquitto_sub -h <设备 IP> -t '<设备名>/inspection/#' -v，能收到消息。

MQTT 消息

一帧一条，verdict 为 OK / NG，defect_count 为缺陷数，detections[] 为该帧所有检测框（class_name、score、归一化中心点宽高 bbox）。无缺陷时 primary_class_id 为 -1，对应的 Modbus 寄存器为 0。

下一步

  • 把 Modbus 线圈接到剔除或打标工位，然后做步骤 3。
  • 把 MES 或历史库指向 MQTT 主题。
  • 加相机前先压测：Orin NX 在不发 MQTT、不写 Modbus 时稳定运行 8 路。
3

核对 Modbus 输出

确认 Modbus 主站读到的判定正确。只用 MQTT 的现场可以跳过。

前置条件
  1. 一台同网段、能做 Modbus TCP 主站的机器。
  2. 设备 IP 和部署时填的从站号（下表按 unit 1）。
故障排查
现象处理
502 端口连接被拒检查设备上 config/config.json 里的 modbus.enabled，并确认容器已起
MQTT 有检测结果但寄存器全 0核对从站号，或换一帧 NG 再读
框的位置对不上HR 2-5 是归一化 x10000 的中心点与宽高，除以 10000 再乘画面尺寸
接了多路相机却只有一组寄存器只有一组寄存器，多路时以最后一次判定为准；逐路结果从 MQTT 取
部署完成后

寄存器表，502 端口上的 unit 1：

地址含义
Coil 0NG，与线圈 1 互斥
Coil 1OK，与线圈 0 互斥
HR 0主缺陷类别 ID（本帧最高分的框）；OK 时为 0
HR 1缺陷数
HR 2主缺陷框 cx，归一化 x10000
HR 3主缺陷框 cy，归一化 x10000
HR 4主缺陷框 w，归一化 x10000
HR 5主缺陷框 h，归一化 x10000
HR 6心跳 Unix 秒，uint32 高字
HR 7心跳 Unix 秒，uint32 低字

快速验证

  1. 读 unit 1、端口 502 的线圈 0-1 与 HR 0-7，可用上游仓库的 python evaluation/read_modbus.py --host <设备 IP> --port 502 --unit 1。
  2. 让有缺陷的样品经过相机时连续采样，线圈对随之翻转。
  3. 同一次采样里两个线圈不能同时为 1；读到 (1,1) 时停用并排查。
  4. NG 帧上 HR 2-5 在 0-10000 内，与 MQTT 消息里的框一致；OK 帧上 HR 0-5 全为 0。
  5. 没有新判定时 HR 6-7 仍在递增。

下一步

  • PLC 以线圈为触发信号，线圈翻转时寄存器已是该帧数据。
  • 对心跳停更报警，用于区分“没有缺陷”和“检测器停止”。
4

启用无监督异常检测（可选）

可选。在检测器旁运行 EfficientAD-S（只用无缺陷图训练），把与 OK 参考集不像的帧标出来，包括检测器没学过的缺陷类型。不参与判定。

前置条件
  • 步骤 1 已完成，改配置并重启容器即可。
  • EfficientAD-S 的 ONNX 已手工拷到设备上（未上 CDN）。
  • 需要用 anomaly_score 做判断时，先用实际检测相机采集自己的 OK 样本标定 anomaly.threshold。
故障排查
现象处理
MQTT 事件里没有 anomaly_score确认 anomaly.enabled: true 已保存且容器已重启，查看容器日志里 anomaly.path 模型加载错误
anomaly_score 对任何样品都接近同一个值用自己相机的 OK 集重新标定 anomaly.threshold
按单帧 anomaly_score 判异常结果不稳定单帧分数接近随机，改用像素/区域级信号（heatmap_ref 加分数）