# People Talking YOLOv8x v1

本版本作为可信 PT 导出源与回滚版本保留；当前部署使用
[`people-talking-yolov8x@2`](../v2/README.md) ONNX 制品。

## 注册信息

| 字段 | 值 |
|---|---|
| Model ID | `people-talking-yolov8x@1` |
| 注册名称 | `People Talking YOLOv8x` |
| Backend | `ultralytics-yolo` |
| 任务 | 画面中人员正在打电话的行为检测 |
| 权重 | `models/detection/people-talking-yolov8x/v1/best.pt` |
| 权重格式 | PyTorch/Ultralytics `.pt` checkpoint |
| 权重大小 | `136694313` bytes |
| SHA256 | `86cd63926de1c69f70dd7f8755e4de9e382bbdeb0668821b7c3846b826471526` |
| 基础模型 | YOLOv8x（约 6815 万参数） |
| checkpoint Ultralytics | `8.0.196` |
| 回滚环境 Ultralytics | `8.4.31` |

Model ID 的 `@1` 与本目录的 `v1` 对应。权重从用户提供的
`/home/xtkuang/Projects/cmvr/changan_robot/call_phone/best.pt` 复制；复制前后的大小和
SHA256 必须一致。不兼容的新权重应使用新版本目录和注册 ID，不能覆盖本文件记录的
`v1`。

## 有序标签

checkpoint 的类别编号必须与下表严格一致：

| ID | 标签 | 部署用途 |
|---:|---|---|
| 0 | `label` | 上游 checkpoint 中含义不清的通用类别；当前 Pipeline 不选择 |
| 1 | `talking on phone` | 电话使用行为告警 |

`label` 不是背景类，不能从注册信息中删除，否则类别编号会错位并导致模型加载失败。
v1 回滚配置通过 `detect_labels: [talking on phone]` 只请求 class 1。

## 输入与运行参数

- 输入必须是已经解码的 `BGR8` 或 `RGB8` 三通道图像；
- checkpoint 训练参数记录的 `imgsz` 为 `640`；
- v1 CPU 回滚配置从 `max_fps: 5`、`confidence: 0.50` 开始；
- 该权重由带 `dill` 的环境序列化，项目的 `yolo`/`yolo-cpu` extra 已显式包含
  `dill`，不能依赖 Ultralytics 运行时临时联网安装；
- `.pt` 由 PyTorch pickle loader 读取，只应部署经过校验的可信制品。

配置示例：

```yaml
phone_detector:
  uses: detection.model@1
  with:
    model: people-talking-yolov8x@1
    detect_labels:
      - talking on phone
    confidence: 0.50
    max_fps: 5
    attach_frame: true
    model_options:
      weights: models/detection/people-talking-yolov8x/v1/best.pt
      device: cpu
      imgsz: 640
      iou: 0.70
      half: false
      max_det: 100
```

## 来源与许可

- 上游项目：[`Anidipta/People-Talking`](https://github.com/Anidipta/People-Talking)；
- 上游仓库根 `LICENSE` 标记为 Apache-2.0，但 README 的许可段落写为 MIT；
- 上游没有在模型卡中单独说明训练数据和权重的再分发许可。

因此在外部发布或商业部署前，需要进一步确认代码、权重和训练数据各自的授权范围，
不能把仓库 README 的一句许可描述直接当成全部资产的授权结论。仓库中的 `.pt` 作为
普通 Git blob 保存，克隆后会直接获得完整权重。

## 限制

- 这是视觉行为检测，不读取手机屏幕、通话音频或运营商状态；它不能判断来电/去电、
  是否真正接通，也不能区分普通手持手机与真实通话的全部边界情况；
- 上游只提供曲线图片，未给出可复核的逐类 AP/precision/recall 数值；当前没有把
  未知测试集上的指标写成部署承诺；
- 手部和手机被遮挡、远距离小目标、侧后视角、弱光以及相似手势都可能导致漏检或误检；
- 当前 adapter 是逐帧检测，不跟踪具体人员。`repeat_gate` 的 `scope: source` 只能表示
  同一相机连续命中，不能证明连续命中来自同一个人；
- YOLOv8x 在 CPU 上较重，必须在目标设备测量推理延迟、内存和实际 FPS 后再调高
  `max_fps`。

## 验证

从仓库根目录执行：

```bash
sha256sum models/detection/people-talking-yolov8x/v1/best.pt
uv run --no-sync cmvr-edge-ai models
uv run --no-sync cmvr-edge-ai validate \
  --config configs/active_detection.yaml \
  --pipeline detection
```

`validate` 只检查配置和 DAG，不加载权重。发布前还必须执行真实模型加载和单帧推理
smoke test，确认日志或测试结果中模型 ID、标签顺序和推理输出均正确。