Surveillance Video Analyst

---
name: 公安视频分析师 (Surveillance Video Analyst)
description: >
  在监控视频中定位目标——支持自然语言描述、人脸照片、人体照片三种输入模式。自动检测+跟踪+标注，
  输出时间区间、包围框轨迹、标注视频。Mac (Apple Silicon MPS) 和 Windows (CUDA/CPU) 通用。
  视频文件不上传——全本地处理(可选 GLM 视觉 API 稀疏增强)。首次使用时引导用户下载模型、
  配置 API key。
profession: 公安视频分析师
platform: Mac (Apple Silicon MPS) / Windows (CUDA / CPU fallback)
inputs: text description | face photo | body photo
---

# 公安视频分析师 (Surveillance Video Analyst)

在监控视频中按**文字描述**、**人脸照片**或**人体照片**定位目标人物/车辆/物体。
输出:时间戳范围、每帧包围框(BBox)轨迹、标注视频帧。
**视频全程留在本地机器**——只有可选的 GLM-VLM 稀疏增强模式上传极少量裁切图。


## 首次使用 — 环境配置 (First-Time Setup)

### 0. 自动检查清单
开始前自动检测:
- Python 3.12+ 是否存在
- 是否已有可用的 venv
- 模型文件是否存在
- ZHIPUAI_API_KEY 是否已设置
- GPU/MPS 是否可用

**Mac (Apple Silicon):**
```bash
python3 -c "import torch; print('MPS available:', torch.backends.mps.is_available())"
```
- 返回 `True` → 使用 `--device mps`(GPU 加速,约 25fps)
- 返回 `False` → 使用 `--device cpu`

**Windows:**
```bash
python -c "import torch; print('CUDA:', torch.cuda.is_available())"
```
- 返回 `True` → 使用 `--device cuda:0`(NVIDIA GPU)
- 返回 `False` → 使用 `--device cpu`

### 1. 安装 Python 环境
**如果尚未安装,提示用户执行以下步骤:**

**Mac:**
```bash
# 安装 Python 3.12(如果缺失)
brew install python@3.12
# 创建 venv
python3.12 -m venv ~/video-analyst-venv
source ~/video-analyst-venv/bin/activate
```

**Windows (PowerShell):**
```powershell
# 安装 Python 3.12 (https://www.python.org/downloads/)
# 创建 venv
python -m venv %USERPROFILE%\video-analyst-venv
%USERPROFILE%\video-analyst-venv\Scripts\activate
```

### 2. 安装依赖
```bash
# 激活 venv 后
pip install torch torchvision  # 自动选平台(Mac MPS / Win CUDA / CPU)
pip install ultralytics opencv-python transformers pillow fastapi uvicorn
pip install insightface onnxruntime  # 人脸匹配(可选,person_search 需要)
```

> ⚠️ **如果 `pip install torch` 在 Windows 上找不到 CUDA 版本:**
> 去 https://pytorch.org/get-started/locally/ 复制对应 CUDA 版本的安装命令。

**Windows 额外:** 如果 insightface 安装失败(VC++ Redist 缺失),跳过 insightface——
person_search 会自动降级到 CLIP + GLM-VLM 模式。

### 3. 下载模型文件

**YOLO-World 模型(文字→视频定位必需):**
```bash
# 自动下载到 ~/.video-analyst/models/
mkdir -p ~/.video-analyst/models   # Windows: %USERPROFILE%\.video-analyst\models
# 如果网络不通,手动从这里下载:
#   链接: https://huggingface.co/... (模型链接)
#   放到 ~/.video-analyst/models/yolov8s-worldv2.pt
```
首次运行 `locate.py` 时如果模型不存在,脚本会提示用户:
```
[setup] YOLO-World model not found at ~/.video-analyst/models/yolov8s-worldv2.pt
[setup] Download? [y/N]: 
```
输入 `y` 自动下载。

**人脸/人体识别模型(照片→视频定位可选):**
首次运行 `person_search.py` 时:
- `insightface buffalo_l` (ArcFace 人脸) 自动下载到 `~/.insightface/models/`
- OSNet ReID 权重要求手动下载(Google Drive),提示用户:
  ```
  [setup] OSNet person-ReID weights not found.
  [setup] Download osnet_x1_0_market_256x128_amsgrad_ep150_stp60_lr0.0015_b64_fb10_softmax_labelsmooth_flip.pth
  [setup] from: https://drive.google.com/... 
  [setup] to:   ~/.video-analyst/models/
  [setup] Without this, person search falls back to CLIP → GLM-VLM (needs API key).
  ```
**不需要 OSNet 也可以运行**——自动降级。

### 4. 配置 API Key (可选,仅 GLM 视觉增强需要)
```bash
export ZHIPUAI_API_KEY="你的智谱 API key"
# Windows PowerShell:
# $env:ZHIPUAI_API_KEY="你的智谱 API key"
```

> 📌 **没有 API key?** 文字查询模式(YOLO-World + BoT-SORT)完全本地运行,不需要 key。
> 只有两种场景需要 key:
> - 复杂属性查询("穿米色大衣的人"、"白色带天窗的SUV")——VLM 增强识别
> - 人脸/人体匹配的 VLM 降级模式(如果没有安装 insightface/OSNet)
>
> 获取 key: https://open.bigmodel.cn/ → 注册 → API 管理


## 三种工作模式

### 🅰️ 文字描述定位 (Text → Video)
**用途:** "找到视频中穿红色外套的人"、"定位白色轿车"、"追踪蓝色背包的人"
**技术:** YOLO-World 开放词汇检测 + BoT-SORT 多目标跟踪 + 可选 GLM-VLM 稀疏增强

```bash
VENV=~/video-analyst-venv  # 或 Windows: %USERPROFILE%\video-analyst-venv
# Mac 额外设置 SSL:
export SSL_CERT_FILE=/etc/ssl/cert.pem REQUESTS_CA_BUNDLE=/etc/ssl/cert.pem

"$VENV/bin/python3" scripts/locate.py \
  --video <监控视频.mp4> \
  --query "<目标中文/英文描述>" \
  --device mps \      # Mac: mps | Windows: cuda:0 或 cpu
  --out <输出目录> \
  --use-vlm           # 可选:启用 GLM-VLM 增强识别(需要 ZHIPUAI_API_KEY)
```

**输出:**
- `annotated.mp4` — 每帧带绿框+标签的标注视频
- `boxes.json` — 每帧 BBox 坐标 `[x1,y1,x2,y2]`
- `intervals.json` — 目标出现的时间区间 `[{start_s, end_s}]`
- `metrics.json` — 覆盖率/fps/内存

### 🅱️ 人脸照片定位 (Face Photo → Video)
**用途:** "用这张嫌疑人照片,在视频中找到这个人出现的所有帧"
**技术:** insightface ArcFace 人脸嵌入匹配 → 每帧检测 → 余弦相似度 → CLIP 二次确认 → VLM 最终裁定

```bash
"$VENV/bin/python3" scripts/person_search.py \
  --video <监控视频.mp4> \
  --ref <嫌疑人照片.jpg> \
  --mode face \
  --out <输出目录> \
  --device mps \      # Mac: mps | Windows: cuda:0 或 cpu
  [--face-thresh 0.42]   # 匹配阈值(默认0.42,降低=更多候选,提高=更精确)
  [--backend auto]        # auto=insightface→CLIP→VLM 自动降级
```

**重要:** 参考照片需要是**包含人脸的大图**(如证件照、半身照),不能用抠出来的纯脸小块——insightface 需要自己检测人脸位置。

### 🅲 人体照片定位 (Body Photo → Video)
**用途:** "用这张全身照/背影照,在视频中追踪这个人"
**技术:** OSNet 行人重识别(ReID)嵌入匹配 → YOLO 人体检测 → 余弦相似度 → CLIP 确认

```bash
"$VENV/bin/python3" scripts/person_search.py \
  --video <监控视频.mp4> \
  --ref <目标人体照片.jpg> \
  --mode person \
  --out <输出目录> \
  --device mps \
  [--reid-thresh 0.55]   # 匹配阈值
  [--step 3]              # 每隔3帧检测一次(加速处理)
```

**自动选图规则:** 如果照片里同时有人脸和人体,`--mode auto` 优先选人脸(准确度更高) → 如果人脸太小或检测不到则自动切人体模式。


## 运行前 — 视频格式预检 (Always Run First)

**务必先运行 `preflight.py`**,很多 NVR/DVR 导出的视频(如 `.dav`、加密 `.mp4`)OpenCV 读不出真实帧,但不会报错——会返回全黑或条纹,引擎以为"目标不存在"。

```bash
"$VENV/bin/python3" scripts/preflight.py <视频路径> --sample test.jpg --recover clean.mp4
```
- `OK` → 直接使用原视频
- `SUSPECT` → 查看 `test.jpg`,确认画面正常
- `UNREADABLE` → 使用生成的 `clean.mp4`


## 常见问题

| 问题 | 原因 | 解决 |
|---|---|---|
| 全 0 检测结果 | 视频格式不兼容 | 跑 `preflight.py` 转换 |
| 人脸匹配全失败 | 参考照片中人脸太小 | 用包含人脸的较大图,不用纯脸裁切 |
| 人体匹配错误率太高 | OSNet 未安装,走了 CLIP 降级 | 安装 OSNet 或提高 `--reid-thresh` |
| 文字查询定位不准(穿粉色裙子=短裤) | 开放词汇检测的语义粒度问题 | 加 `--use-vlm` |
| MPS 崩溃 | 多次调用 set_classes | 重启进程,单次调用 |
| Windows GPU 找不到 | CUDA Toolkit 未装 | `pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118` |


## 隐私
默认全部本地处理——视频文件、人脸嵌入、人体嵌入都不上传。仅 `--use-vlm` 模式发送少数裁切图到 GLM API(用于无法确定的高难度匹配)。公安场景建议审批后使用 VLM 模式。