# snapshot-infer

配送任务视频 **门头 / 交付** 时刻检测推理服务（ONNX 视觉 + faster-whisper ASR 融合）。

## 架构

1. Java `dmvisit_service` 下载 MP4 到 FTP 后，异步调用 `POST /analyze`
2. 本服务下载视频 → 并行 **抽帧 ONNX 打分** + **ASR 关键词** → 融合时刻
3. Java 侧 FFmpeg 截帧并上传 FTP（`delivery_media_snapshot` 表）

## 环境要求

- Python 3.9+（Windows 用 `py` 启动器）
- **ffmpeg / ffprobe** 在 PATH 或设置 `FFMPEG_DIR`
- `models/` 目录下放置训练导出的 ONNX：
  - `storefront_int8.onnx` / `handover_int8.onnx`（或 float 版）
  - `version.json`

## 安装与启动（Windows CPU）

```powershell
cd server/snapshot_infer
py -m pip install -r requirements.txt
# 训练依赖（仅训练机）
# py -m pip install -r training/requirements-train.txt

$env:SNAPSHOT_MODEL_DIR = "./models"
$env:WHISPER_MODEL = "tiny"
$env:SNAPSHOT_SAMPLE_FPS = "0.5"
py -m uvicorn app.main:app --host 0.0.0.0 --port 8095
```

Linux:

```bash
cd server/snapshot_infer
python3 -m pip install -r requirements.txt
export SNAPSHOT_MODEL_DIR=./models WHISPER_MODEL=tiny SNAPSHOT_SAMPLE_FPS=0.5
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8095
```

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 返回 `status`, `modelVersion`, ONNX/ASR 加载状态 |
| POST | `/analyze` | 主推理（请求/响应 camelCase，与 Java DTO 对齐） |

### `/health` 示例

```json
{
  "status": "ok",
  "modelVersion": "1.0.0",
  "onnxStorefrontLoaded": true,
  "onnxHandoverLoaded": true,
  "asrAvailable": true
}
```

`status=degraded` 表示 ONNX 未加载完整，需部署模型文件。

## dmvisit 配置

`application-dev.yml` / `application-pro.yml`:

```yaml
snapshot:
  infer:
    base-url: http://127.0.0.1:8095
    sample-fps: 0.5
    fail-open-mock: false   # 生产必须为 false
```

- **dev** 可设 `fail-open-mock: true` 在无 ONNX 时回退 25%/75% mock
- **pro** 已默认 `fail-open-mock: false`，推理失败写入 `snapshot_status=3`

## 训练流程

详见 [`docs/annotation_spec.md`](docs/annotation_spec.md)。

```powershell
cd server/snapshot_infer/training
py -m pip install -r requirements-train.txt

# 1. 准备标注 JSONL -> data/annotations.jsonl
# 2. 抽帧打标
py prepare_dataset.py -c config.yaml

# 3. 训练
py train.py -c config.yaml

# 4. 导出 ONNX（Windows 若 INT8 量化崩溃，会自动使用 float .onnx）
py export_onnx.py -c config.yaml --version 1.0.0
# 或跳过量化：py export_onnx.py -c config.yaml --version 1.0.0 --no-quantize

# 5. 评估
py evaluate.py -c config.yaml --annotations ../data/annotations.jsonl
```

### Windows 无法生成 `*_int8.onnx`

部分 Windows 环境上 `onnxruntime.quantization` 会进程崩溃（exit `3221225477`）。**不影响使用**：

- 导出脚本会自动回退到 `storefront.onnx` / `handover.onnx`（float32）
- `version.json` 会记录实际文件名
- 推理服务同样可加载 float 模型，仅速度略慢于 INT8

若必须 INT8，可在 Linux 训练机执行 `export_onnx.py`，或尝试 `py -m pip install onnxruntime==1.16.3` 后重试。

## 工具

| 脚本 | 用途 |
|------|------|
| `tools/export_media_list.py --mysql` | 从 DB 导出待标注清单 |
| `tools/export_feedback.py` | 导出人工纠正反馈为训练 JSONL |
| `tools/benchmark_cpu.py <video_url>` | CPU 单条压测 |

## 监控

- 启动后访问 `GET http://127.0.0.1:8095/health`
- `onnxStorefrontLoaded=false` → 检查 `models/` 路径与环境变量 `SNAPSHOT_MODEL_DIR`
- 分析失败原因见 `collection_media.snapshot_message`

## 数据库（需执行 SQL）

- `server/db/business.delivery_media_snapshot_feedback.sql` — 人工纠正反馈表