368 lines
18 KiB
Markdown
368 lines
18 KiB
Markdown
# PPE 检测流水线
|
||
|
||
`configs/edge_ai.yaml` 中的 `detection` Pipeline 是当前可运行的园区施工安全装备检测
|
||
链路。它与 `talk` Pipeline 共用一个部署 YAML，当前只启用 Construction PPE 模型和
|
||
8081 告警平台；六类模型与 8082 模拟平台的实现保留但不实例化：
|
||
|
||
```text
|
||
cmvr-es CameraService
|
||
-> H264/H265 ImageFrame/v1
|
||
-> media.video_decoder.pyav@1
|
||
-> BGR8 ImageFrame/v1
|
||
-> construction-ppe-yolov8@1 -> DetectionResult/v1
|
||
-> detection.repeat_gate@1 -> DetectionAlert/v1
|
||
-> POST 127.0.0.1:8081/v1/detection-alerts
|
||
```
|
||
|
||
## 安装与启动
|
||
|
||
从仓库根目录执行一键安装。默认 profile 安装锁定的 CPU 检测环境、生成 cmvr-es
|
||
bindings，并验证最小测试 fixture 与统一部署配置中的检测链路：
|
||
|
||
```bash
|
||
cd /home/xtkuang/Projects/cmvr/cmvr_edge_ai
|
||
bash scripts/bootstrap.sh
|
||
```
|
||
|
||
cmvr-es 不在相邻的 `../cmvr-es` 时指定实际路径：
|
||
|
||
```bash
|
||
bash scripts/bootstrap.sh \
|
||
--cmvr-es-root /home/xtkuang/Projects/cmvr/cmvr-es
|
||
```
|
||
|
||
环境固定 Python 3.10、Ultralytics 8.4.31、PyTorch 2.7.0 CPU 和 torchvision
|
||
0.22.0，并通过 `image` extra 安装 Pillow 以生成告警图片；所有具体包版本记录在
|
||
仓库的 `uv.lock` 中。GPU/Jetson 需要单独适配与驱动或 JetPack 匹配的 PyTorch
|
||
wheel，不能直接复用 `detection-cpu` profile。手动组合依赖时必须显式增加
|
||
`--extra image`，不能只依赖 YOLO 间接安装 Pillow。
|
||
|
||
直接编辑 `configs/edge_ai.yaml` 中 `detection` Pipeline 的部署参数：
|
||
|
||
```yaml
|
||
endpoints:
|
||
cmvr_es:
|
||
target: 127.0.0.1:50052
|
||
ppe_alert_platform:
|
||
base_url: http://127.0.0.1:8081
|
||
|
||
pipelines:
|
||
detection:
|
||
nodes:
|
||
camera:
|
||
with:
|
||
device_id: right_hand_cam
|
||
stream_log_interval_s: 5
|
||
detector:
|
||
with:
|
||
attach_frame: true
|
||
inference_log_interval_s: 5
|
||
model_options:
|
||
weights: models/detection/construction-ppe-yolov8/v1/best.pt
|
||
device: cpu
|
||
repeat_gate:
|
||
with:
|
||
alert_image:
|
||
enabled: true
|
||
jpeg_quality: 85
|
||
alert_platform:
|
||
with:
|
||
endpoint: ppe_alert_platform
|
||
failure_mode: log_and_drop
|
||
```
|
||
|
||
上述相对权重路径按进程启动时的当前工作目录（`cwd`）解析，不是按
|
||
`configs/edge_ai.yaml` 所在目录解析。下面的 validate、run 和 Viewer 命令都应先
|
||
`cd /home/xtkuang/Projects/cmvr/cmvr_edge_ai`；如果必须在其他 `cwd` 启动，请在
|
||
YAML 中使用正确的绝对权重路径。
|
||
|
||
完成配置后启动，不需要再通过 shell `export` 传入这些值：
|
||
|
||
```bash
|
||
uv run --no-sync cmvr-edge-ai models
|
||
uv run --no-sync cmvr-edge-ai validate \
|
||
-c configs/edge_ai.yaml \
|
||
--pipeline detection
|
||
uv run --no-sync cmvr-edge-ai run -c configs/edge_ai.yaml \
|
||
--pipeline detection \
|
||
--log-level INFO \
|
||
--log-format json
|
||
```
|
||
|
||
运行时会看到类似下面两类 JSON 日志：
|
||
|
||
```json
|
||
{"level":"INFO","logger":"cmvr_edge_ai.detection.operator","message":"detection model loaded node=detector model=construction-ppe-yolov8@1 ..."}
|
||
{"level":"INFO","logger":"cmvr_edge_ai.detection.operator","message":"detection inference node=detector model=construction-ppe-yolov8@1 total_frames=1 window_frames=1 window_detections=2 hit_labels=No-Helmet:2 ..."}
|
||
```
|
||
|
||
- `detection model loaded`：checkpoint 已成功加载并完成标签顺序校验；当前 detector
|
||
应出现一条；
|
||
- `detection inference`：模型确实收到解码帧并执行了 `predict`；第一帧立即输出，
|
||
后续按配置周期聚合；
|
||
- `window_detections=0 hit_labels=none`：模型在工作，但本周期没有高于配置阈值的命中；
|
||
- 只有 loaded、长期没有 inference：优先检查 cmvr-es 相机流、decoder 和关键帧；
|
||
- 短时观察可把 `inference_log_interval_s` 改为 `1` 秒，长期运行建议 `30`～`60` 秒，
|
||
省略该字段会关闭周期推理日志。
|
||
|
||
运行前确认 cmvr-es 已启用 `right_hand_cam`、Construction PPE 权重存在，并且 8081
|
||
平台接受 `POST /v1/detection-alerts`。默认 profile 下 `model_options.device` 应设为
|
||
`cpu`；只有完成设备专用的 CUDA/Jetson PyTorch 环境适配后，才能改为 `cuda:0` 等值。
|
||
|
||
## 实时画框 Demo
|
||
|
||
`configs/debug/detection_viewer.yaml` 和 `show_detections.py` 提供一个不访问 HTTP 平台的
|
||
独立调试链路：
|
||
|
||
```text
|
||
cmvr-es CameraService -> PyAV decoder -> YOLO detector -> OpenCV window
|
||
```
|
||
|
||
先编辑 `configs/debug/detection_viewer.yaml` 中的远端 cmvr-es 地址、相机 ID 和权重路径：
|
||
|
||
```yaml
|
||
endpoints:
|
||
cmvr_es:
|
||
target: 192.168.0.119:50052
|
||
|
||
pipelines:
|
||
detection_show:
|
||
nodes:
|
||
camera:
|
||
with:
|
||
device_id: wrist_cam
|
||
detector:
|
||
with:
|
||
max_fps: 10
|
||
model_options:
|
||
weights: /absolute/path/to/best.pt
|
||
device: cpu
|
||
```
|
||
|
||
`max_fps: 10` 表示最多每秒执行 10 次推理；视频流更快时，中间的已解码帧通过
|
||
`realtime_latest + drop_oldest` 丢弃，以保持低延迟。`attach_frame: true` 已在 Demo 配置
|
||
中启用，viewer 因而能拿到与本次推理严格对应的原图并绘制 bounding box。
|
||
|
||
只检查配置和插件连线，不连接相机、不加载模型、也不创建窗口：
|
||
|
||
```bash
|
||
uv run --no-sync python detect_server/show_detections.py \
|
||
--config configs/debug/detection_viewer.yaml \
|
||
--validate-only
|
||
```
|
||
|
||
启动实时显示：
|
||
|
||
```bash
|
||
uv run --no-sync python detect_server/show_detections.py \
|
||
--config configs/debug/detection_viewer.yaml \
|
||
--pipeline detection_show \
|
||
--log-level INFO \
|
||
--log-format json
|
||
```
|
||
|
||
相机 Source 会先调用 `StartCamera`，成功后再建立 gRPC 视频流。窗口显示每个实际推理
|
||
结果，即使本帧没有检测框也会刷新；按 `q`、`Q`、`Esc` 或关闭窗口可安全退出。这个
|
||
Demo 直接订阅 detector 输出，刻意绕过 `repeat_gate` 和 HTTP Sink，因此只用于观察模型
|
||
效果，不代表某条告警规则已满足。
|
||
|
||
OpenCV 窗口出现在运行命令的机器上。无桌面的边缘设备不能直接显示；通过 SSH 运行时
|
||
需要启用 X11 转发并确保 `DISPLAY` 可用，否则程序会给出明确错误并退出。依赖缺失时先
|
||
执行 `bash scripts/bootstrap.sh`。
|
||
|
||
## 模型与标签
|
||
|
||
`detection.model@1` 不绑定某一个框架；它通过 `DetectionModelRegistry` 查找配置中的
|
||
`model`。每个 `DetectionModelSpec` 注册版本化模型 ID、模型名称、backend 和有序
|
||
`supported_labels`。注册表当前包含两个内置模型，但 Pipeline 只引用第一个：
|
||
|
||
- [`construction-ppe-yolov8@1`](../models/detection/construction-ppe-yolov8/v1/README.md)：
|
||
对应制品目录 `v1`，19 类，包含用于违规告警的 `No-*` 标签；
|
||
- [`ppe-6classes-yolov8n@1`](../models/detection/ppe-6classes-yolov8n/v1/README.md)：
|
||
对应制品目录 `v1`，包含 `Gloves`、`Vest`、`goggles`、`helmet`、`mask`、
|
||
`safety_shoe` 六个正向装备标签。
|
||
|
||
模型 ID 尾部的 `@1` 与制品目录的 `v1` 对应；运行时不会根据 ID 自动拼接文件
|
||
路径，仍由 YAML 中的 `model_options.weights` 显式指定。训练信息、完整标签
|
||
顺序、性能、限制和许可信息请查看各自的 model card。
|
||
|
||
可用 `cmvr-edge-ai models` 核对 ID、名称、backend 和标签顺序。六类模型只表达
|
||
“检测到某件装备”，不包含 `Person` 或 `No-*` 类，也不执行人员/PPE 关联；所以它
|
||
不能直接判断某个人缺少装备。需要这种语义时，仍应增加人员检测、空间关联和缺失
|
||
判定节点，不能把“没有检测到 helmet”直接当成“人员未戴安全帽”。
|
||
|
||
检测节点的关键参数：
|
||
|
||
| 参数 | 语义 |
|
||
|---|---|
|
||
| `model` | 必须是已注册的精确模型 ID |
|
||
| `detect_labels` | 本次部署需要的标签；省略表示模型的全部注册标签 |
|
||
| `confidence` | 所有选中标签的默认置信度阈值 |
|
||
| `label_confidence` | 可选的逐标签阈值覆盖 |
|
||
| `max_fps` | 推理启动频率上限；过密的解码帧会被跳过 |
|
||
| `inference_log_interval_s` | 可选推理摘要周期（秒）；首帧立即输出，省略表示关闭周期日志 |
|
||
| `attach_frame` | 是否让 `DetectionResult` 临时附带对应解码帧；生成告警图片时必须为 `true` |
|
||
| `model_options` | backend 私有选项；当前 YOLO 支持 weights、device、imgsz、iou、half、max_det、agnostic_nms |
|
||
|
||
配置阶段会拒绝未知模型、模型不支持的 `detect_labels`、重复标签和非法阈值。YOLO 加载 checkpoint 时还会严格比较 checkpoint 的实际标签及顺序与注册信息，避免类别编号静默错位。
|
||
|
||
## 六类逐推理结果分支
|
||
|
||
这一分支当前默认关闭。恢复后，六类 detector 不连接 repeat gate，而是把每次完成推理产生的
|
||
`DetectionResult/v1` 直接交给第二个 HTTP Sink。其 POST Envelope 的
|
||
`schema` 为 `DetectionResult/v1`，`payload` 示例为：
|
||
|
||
```json
|
||
{
|
||
"detections": [
|
||
{
|
||
"label": "helmet",
|
||
"confidence": 0.91,
|
||
"box": {"x_min": 120.0, "y_min": 60.0, "x_max": 250.0, "y_max": 220.0},
|
||
"track_id": null
|
||
}
|
||
],
|
||
"model_id": "ppe-6classes-yolov8n@1",
|
||
"inference_ms": 34.2,
|
||
"model_name": "PPE Detection YOLOv8n (6 Classes)"
|
||
}
|
||
```
|
||
|
||
该结构刻意不同于原分支的 `DetectionAlert/v1`：它没有 `rule_id`、`hit_count`、
|
||
`event_id` 或 `image`，空检测帧也会以空 `detections` 数组上报。`cooldown_ms` 是
|
||
repeat gate 的内部规则配置，不属于 `DetectionAlert` payload。由于
|
||
payload 没有 event ID，HTTP Sink 的 `Idempotency-Key` 回退使用 Envelope
|
||
`trace_id`。这只是模拟的逐结果接口；若平台要求另一套字段命名或嵌套，需要增加
|
||
平台专用转换节点/Sink，而不是仅修改 endpoint。
|
||
|
||
## 重复触发规则
|
||
|
||
`detection.repeat_gate@1` 按规则维护滑动时间窗口。规则字段如下：
|
||
|
||
| 参数 | 语义 |
|
||
|---|---|
|
||
| `id` | 唯一规则 ID，写入告警 |
|
||
| `labels` | 任一标签匹配即视为该规则在当前帧命中 |
|
||
| `min_confidence` | 规则侧最低置信度，可高于 detector 阈值 |
|
||
| `min_hits` | 触发所需的不同帧数 |
|
||
| `window_ms` | 上述命中必须落入的时间窗口 |
|
||
| `cooldown_ms` | 告警后的静默期；期间不累计，结束后重新计数 |
|
||
| `scope` | `source` 按相机统计；`track` 按相机内的 `track_id` 分别统计 |
|
||
|
||
一次命中按 `(source_id, sequence)` 的不同视频帧计算：同一帧出现多个相同标签框只算一次，重复投递同一帧也不会增加计数。一个规则即使配置多个标签，同一 scope 在一帧内仍只增加一次。`time_source` 可选 `captured`、`received` 或优先采集时间的 `auto`；当前 cmvr-es 成功帧通常没有 `header.timestamp`，示例显式使用 `received`。
|
||
|
||
`alert_image.enabled` 默认为 `false`；启用后要求 detector 同时配置
|
||
`attach_frame: true`。`jpeg_quality` 是 `1..95` 的整数，默认 85。repeat gate
|
||
只在规则达到 `min_hits`、准备输出告警时，才用 Pillow 在当前阈值帧上绘制匹配的
|
||
bounding boxes、标签和置信度并编码 JPEG，不会为每个推理结果都渲染。告警里的
|
||
`detections` 和图片框均来自阈值帧；窗口内更早的命中只参与次数、时间范围和
|
||
`max_confidence` 统计。
|
||
|
||
同一阈值帧同时触发多条规则或多个 track 时，repeat gate 对这些告警相关框取并集，
|
||
只画框并编码一次，然后让本帧产生的告警共享该 JPEG，避免在边缘端重复编码。
|
||
非有限坐标、反向/退化框、非法置信度等 detection 会在规则计数前被忽略，并记录在
|
||
`invalid_detections` 健康指标中，避免 `NaN/Inf` 令整个 HTTP JSON 告警无法发送。
|
||
|
||
当前 YOLO adapter 是逐帧检测，不执行人员跟踪，输出的 `track_id` 为 `None`。因此示例使用 `scope: source`；如果业务要求“同一个人连续多次违规”，必须在 detector 和 repeat gate 之间加入 tracker 及人员/PPE 关联节点，之后才能使用 `scope: track`。
|
||
|
||
## 相机启动与视频流日志
|
||
|
||
cmvr-es 的 `StartCamera` 和 `GetRGBImageStream` 是两个不同阶段：前者打开物理相机，
|
||
后者只启动编码和流式传输。连接器在每个首次连接或重连 session 中严格执行：
|
||
|
||
```text
|
||
StartCamera -> 检查 feedback.header.success -> GetRGBImageStream -> 等待首帧
|
||
```
|
||
|
||
`StartCamera` 使用 `cmvr_es.timeout_s`；RPC 异常或 `header.success=false` 都进入同一套
|
||
指数退避重连。正常关闭只取消当前 stream，不自动调用设备级 `StopCamera`，避免影响
|
||
同一相机的其他客户端。
|
||
|
||
使用 `--log-level INFO --log-format json` 时，按顺序关注：
|
||
|
||
- `camera source configured`：endpoint、device 和超时配置完成；
|
||
- `camera start requested/succeeded`：StartCamera 已被调用并成功；
|
||
- `camera stream opening`：流请求已创建，正在等待第一帧；
|
||
- `camera stream first frame`：已经收到真实编码帧，包含 codec、尺寸、字节数和远程序号；
|
||
- `camera stream progress`：每 `stream_log_interval_s` 秒输出帧数、FPS、bitrate、关键帧、
|
||
最后序号和 `last_frame_age_s`；即使完全没帧也会输出 `first_frame_received=false`；
|
||
- `camera stream disconnected`：包含错误类型、重连次数和退避时间；
|
||
- `camera stream closed`、`camera source stopped`：当前 session 和本地 Source 已清理。
|
||
|
||
INFO 日志不会打印帧二进制。示例设置 `stream_log_interval_s: 5` 便于联调，正式部署
|
||
可改为 30～60 秒。
|
||
|
||
## 视频连续性和背压
|
||
|
||
H264/H265 是有参考关系的编码流，解码前不能任意丢包：
|
||
|
||
- `camera -> decoder` 使用 `video_contiguous + block`，保持 edge-ai 内部已经接受的数据连续；
|
||
- decoder 在新 session、编码参数变化、sequence gap 或解码错误后释放上下文，等待下一个关键帧；
|
||
- `decoder -> detector` 已经是完整 BGR 图像，使用 `realtime_latest + drop_oldest` 和容量 1，以有限内存换取较低实时延迟；
|
||
- `detector -> repeat_gate` 在 `attach_frame: true` 时携带未压缩图像，示例把队列容量限制为 2，避免排队的 `DetectionResult` 长时间占用大量内存。
|
||
|
||
该边使用 `drop_oldest` 偏向低延迟；持续过载时，被丢弃的推理结果不会计入
|
||
`min_hits`。如果业务更重视每次推理结果都参与计数，可改为 `overflow: block`，但要
|
||
接受延迟向上游传播，并继续保持很小的队列容量。
|
||
|
||
恢复第二模型时，应从 decoder 输出端口 fan-out，以避免第二次相机订阅和第二次
|
||
H264/H265 解码；这不会复用模型计算，两个 YOLO 实例仍会分别加载权重并共享应用的
|
||
有界线程池。
|
||
|
||
这个保证只覆盖 edge-ai 内部。当前 cmvr-es 服务端通过 `getLatestEncodedFrame` 读取最新编码数据；如果它在负载或时序竞争下已经跳过参考包，`video_contiguous` 无法恢复丢失内容，而且当前 edge-ai 的本地 sequence 不能可靠暴露这种上游跳包。此时 PyAV 可能报错，decoder 会重置并等待关键帧。上线前必须用真实摄像头长时间验证连续性；更稳妥的方案是让 cmvr-es 提供连续 access unit 流，或额外提供原始/JPEG/带显式 discontinuity 的 AI 接口。
|
||
|
||
相机 Source 默认启用指数退避重连；每次重新订阅生成新的 `session_id`，使 decoder 主动重置。`reconnect_initial_s`、`reconnect_max_s` 和可选 `max_reconnect_attempts` 可配置；省略最大次数表示持续重连直到进程关闭。
|
||
|
||
## HTTP 输出可靠性
|
||
|
||
每次规则触发会产生带唯一 `event_id` 的 `DetectionAlert/v1`。HTTP Sink 优先把该
|
||
`event_id` 放入 `Idempotency-Key`，没有事件 ID 时才回退到 `trace_id`。它对连接/超时
|
||
错误和配置的临时 HTTP 状态执行有限指数退避，示例最多尝试 3 次。
|
||
|
||
`failure_mode` 支持两种明确语义：默认 `raise` 在最终投递失败时让 Pipeline 失败；当前
|
||
检测配置使用 `log_and_drop`，最终连接失败、超时或非 2xx 时输出
|
||
`HTTP report dropped ... action=drop` WARNING，丢弃当前告警并继续处理后续视频帧。
|
||
`CancelledError`、序列化错误和未知本地程序异常不会被吞掉。
|
||
|
||
当前唯一 HTTP 输出将告警发送到
|
||
`http://127.0.0.1:8081/v1/detection-alerts`。8082 六类逐推理结果 endpoint 当前未配置。
|
||
|
||
启用告警图片后，POST JSON 的 `payload.image` 结构如下：
|
||
|
||
```json
|
||
{
|
||
"media_type": "image/jpeg",
|
||
"width": 1280,
|
||
"height": 720,
|
||
"encoding": "base64",
|
||
"data": "/9j/4AAQSk..."
|
||
}
|
||
```
|
||
|
||
`width/height` 是 JPEG 的像素尺寸；HTTP JSON Sink 将内部 JPEG `bytes` 特判为
|
||
上述扁平对象，`encoding` 固定为 `base64`。关闭 `alert_image`，或运行时因第三方
|
||
结果未附带帧、坏帧等原因渲染失败时，告警仍会发送且该字段为 `null`。Base64 会
|
||
额外增加约三分之一的体积，平台和反向代理需要配置足够的请求体上限。
|
||
|
||
这不是持久化 outbox：`log_and_drop` WARNING 表示该告警已经永久丢失，不会自动补发；
|
||
每次告警在放弃前仍会完成有限重试，因此平台离线时 Sink 队列会短暂阻塞。进程崩溃、
|
||
断电或告警仍在内存队列中时也可能丢失。平台必须按幂等键去重；对“不可丢告警”的
|
||
部署，还需要后续增加有界磁盘 outbox、投递确认和恢复发送。
|
||
|
||
## 部署风险
|
||
|
||
- 模型 README 报告某些小样本类别存在漏检，实际园区需要按相机角度、光照、遮挡和距离重新标定置信度与 `min_hits`；规则降噪不能补偿模型系统性漏检。
|
||
- 权重目录对权重许可的描述与 Ultralytics runtime/checkpoint 中的 AGPL 信息需要在商业部署前核对；同时确认训练数据来源和权重再分发权利。
|
||
- `.pt` 使用 PyTorch checkpoint loader，只加载可信构建和受控分发的权重，并固定、验证实际 Ultralytics 8.x 版本。
|
||
|
||
如果检测结果还要驱动机器人，控制路径必须保持：
|
||
|
||
```text
|
||
DetectionResult -> policy -> RobotCommand/v1
|
||
-> safety.robot_command_gate@1
|
||
-> ApprovedRobotCommand/v1
|
||
-> cmvr.grpc.agv_command_sink@1
|
||
```
|
||
|
||
编译器要求 actuator 的每个直接前驱都是安全门，安全门和执行器之间不能插入普通变换节点，也不能存在绕过路径。
|