cmvr_edge_ai/detect_server/README.md

# PPE 检测流水线

`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，并验证 smoke 与本检测配置：

```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。

直接编辑 `detect_server/pipeline.yaml` 中的部署参数：

```yaml
endpoints:
  cmvr_es:
    target: 127.0.0.1:50052
  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: /home/xtkuang/Projects/cmvr/changan_robot/construction-ppe-yolov8/best.pt
            device: cpu
      repeat_gate:
        with:
          alert_image:
            enabled: true
            jpeg_quality: 85
      platform:
        with:
          failure_mode: log_and_drop
```

完成配置后启动，不需要再通过 shell `export` 传入这些值：

```bash
uv run --no-sync cmvr-edge-ai models
uv run --no-sync cmvr-edge-ai validate \
  -c detect_server/pipeline.yaml \
  --pipeline detection
uv run --no-sync cmvr-edge-ai run -c detect_server/pipeline.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` 等值。

## 模型与标签

`detection.model@1` 不绑定某一个框架；它通过 `DetectionModelRegistry` 查找配置中的
`model`。每个 `DetectionModelSpec` 注册版本化模型 ID、模型名称、backend 和有序
`supported_labels`。注册表当前包含两个内置模型，但 Pipeline 只引用第一个：

- `construction-ppe-yolov8@1`：19 类，包含原分支用于违规告警的 `No-*` 标签；
- `ppe-6classes-yolov8n@1`：`Gloves`、`Vest`、`goggles`、`helmet`、`mask`、
  `safety_shoe` 六个正向装备标签。

可用 `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 的每个直接前驱都是安全门，安全门和执行器之间不能插入普通变换节点，也不能存在绕过路径。