cmvr_edge_ai/models/README.md

# 模型资产目录

本目录保存 cmvr-edge-ai 在边缘端部署时使用的模型资产和模型说明。它与
`src/cmvr_edge_ai/detection/models/` 的 Python 代码职责不同：

- `models/` 保存权重、版本和模型卡；
- `src/cmvr_edge_ai/detection/models/` 保存 backend adapter 与模型注册代码；
- `configs/` 决定某条 Pipeline 选择哪个注册模型和哪份权重。

目前的资产类型：

- [Detection 模型](detection/README.md)

## 目录约定

模型资产使用以下结构：

```text
models/
└── detection/
    └── <model-name>/
        └── v<version>/
            ├── README.md
            ├── <weights-file>
            └── manifest.json       # ONNX 版本包含
```

注册 ID 中的数字版本与目录版本一一对应。例如：

```text
construction-ppe-yolov8@1
            │
            └── models/detection/construction-ppe-yolov8/v1/
```

发布新权重时应新增版本目录和新的注册 ID，不能直接覆盖已经部署的权重。模型卡至少应
记录有序标签、输入要求、运行参数、评估指标、限制、许可证、来源和权重 SHA256。

## 大文件管理

Detection 的 `.pt` 与 `.onnx` 权重直接作为普通 Git blob 保存在仓库中，不使用 Git LFS。克隆
仓库后即可获得完整权重，不需要执行 `git lfs pull`。新增大权重前应同时确认 Git
服务及反向代理允许对应的 push 大小和上传时长；当前 People-Talking FP32 ONNX 单文件
约 273 MB，推送前尤其需要确认服务端单文件限制。

将新权重加入仓库前，先核对模型卡中的 SHA256：

```bash
sha256sum models/detection/<model-name>/v<version>/<weights-file>
```

不要把训练数据集、训练缓存、原模型仓库的 `.git` 目录或无关评估产物放入本目录。