视频内容行为识别软件（BehaviorVision）

轻量化视觉画面分析检测客户端 · 开源版（不含付费授权/加密模块）

无 GPU、低内存的 Windows 工控机上实时运行的视觉画面分析检测软件：纯 CPU 推理，支持多路视频源接入、目标检测、高危行为识别、告警推送与二次分析。

✨ 功能特性

• 多路视频源：RTSP 网络流 / 本地视频文件 / USB 摄像头，多路同屏网格显示
• 实时目标检测：YOLOX ONNX（Apache-2.0 权重）纯 CPU 推理，默认 COCO 80 类，可替换自训练模型
• 多检测内核：yolox（通用 CNN）/ motion（纯运动检测）/ hog（行人+人脸）/ hybrid（运动预筛+精检），工具栏下拉框热切换无需重启
• 高危行为识别（VLM）：可选本机 MiniCPM-V-4.6（1.3B 视觉语言模型，纯 CPU 离线）理解画面语义，识别抽烟/攀爬/盗窃/打斗/坠落等，输出中文概述（「理解输出」面板）
• 告警推送：Webhook（POST JSON）/ MQTT / SMTP 邮件，支持类别/置信度/冷却/ROI 过滤，命中自动存快照
• 二次分析：快照 OCR（rapidocr）、虚拟线目标计数、检测热力图、人员聚集告警
• 目标自由配置：预定义语义组（人员/车辆/动物等 10 组）+ 自定义类别 id 并集过滤
• 用户引导：首次启动向导、应用内帮助文档、空状态提示
• 轻量化铁律：运行时仅依赖 opencv + onnxruntime + numpy + PySide6，零 PyTorch / 零 ultralytics

🏗️ 架构

┌─────────────────────────── UI 层 (PySide6) ───────────────────────────┐
│  主窗口 │ 多路画面网格 │ 源管理面板 │ 事件日志面板 │ 理解输出 │ 设置    │
└───────▲───────────────────────────────────────────▲──────────────────┘
        │ QSignal(帧图/检测结果/事件/理解文本)        │ 配置读写
┌───────┴───────────────────────────────────────────┴──────────────────┐
│                         服务层（线程）                                 │
│  Capture(每源一线程) → FrameQueue(背压 maxlen=2) → InferenceWorker      │
│        → VlmWorker(独立帧缓存，不阻塞主循环) → AlertManager            │
│        → Analysis(OCR/计数/热力图/聚集)                                │
└──────────────────────────────────────────────────────────────────────┘
        │ onnxruntime(CPU/OpenVINO)                │ llama-server 子进程(VLM)
┌───────┴───────────────────────────────────────────┴──────────────────┐
│  模型: models/yolox.onnx   视频源: RTSP/文件/摄像头                    │
└──────────────────────────────────────────────────────────────────────┘

数据流要点

环节	说明
采集线程	每源一个 VideoSource（QThread）；RTSP 默认 TCP + 指数退避重连；文件源可循环/变速（0.25x-8x）
背压队列	每源 deque(maxlen=2)；队列满暂停解码，按推理速率消费，防内存膨胀
推理线程	单个 InferenceWorker 轮询各源，按 stride 跳帧，共享单例 YoloEngine
VLM 线程	VlmWorker 独立线程 + 独立帧缓存（信号直喂，不读共享队列，多源互不阻塞），per-sid 节流
告警	规则过滤 → 事件 JSON → 三通道推送 + 快照；VLM 高危行为无条件告警
UI	Qt 信号跨线程回传；core 不依赖任何 Qt UI 组件

🚀 快速开始

环境要求

• 目标运行环境：Windows 10/11 x64（无 GPU、4GB 内存起）
• 开发机：Python 3.11+（测试于 3.14）

源码运行

pip install -r requirements.txt
python -m yolovision.main          # 启动桌面界面

首次运行自动生成 %APPDATA%/BehaviorVision/config.yaml（模板见 yolovision/config.yaml）。

无头自检（不弹窗，合成视频跑 N 秒输出统计）：

python -m yolovision.main --selftest 15

获取模型

YOLO 检测模型需放入 models/ 目录（Apache-2.0 opencv_zoo YOLOX 或自训练 ONNX）：

文件	说明
models/yolox.onnx	默认检测模型（opencv_zoo，Apache-2.0）
models/coco80.names	COCO 80 类名文件（UTF-8，每行一个）

VLM 高危行为识别模型（可选，约 1.6GB）从 ModelScope 下载：

powershell -ExecutionPolicy Bypass -File scripts/fetch_vlm_models.ps1

⚙️ 配置说明

配置文件：%APPDATA%/BehaviorVision/config.yaml。改配置后按提示重启生效。

model:                            # 检测模型与推理
  engine: yolox                   # yolox | motion | hog | hybrid（工具栏可热切换）
  path: models/yolox.onnx
  conf: 0.15                      # 置信度阈值
  imgsz: 640                      # 320/416/640
  stride: 1                       # 跳帧（低配机 2-3）
  provider: cpu                   # cpu | openvino

sources:                          # 视频源列表（rtsp/file/camera）
  - id: demo
    type: file
    url: demo.mp4
    loop: true

alert:                            # 告警规则
  classes: [0]                    # 关注类别（0=person；[]=全部）
  cooldown_sec: 5
  snapshot: true
  webhook: { enabled: false, url: "http://127.0.0.1:8765" }
  mqtt:    { enabled: false, host: "", port: 1883 }
  smtp:    { enabled: false, host: "", ssl: true, user: "", pass: "", to: [] }

detect:                           # 目标过滤（语义组 + 自定义类别 id 并集；空=全部）
  groups: []
  classes: []

vlm:                              # 本机 VLM 高危行为识别（可选）
  enabled: false
  model_path: models/minicpm-v/MiniCPM-V-4_6-Q4_K_M.gguf
  interval_sec: 15                # 推理节流（秒）
  conf: 0.30
  behaviors: [smoking, climbing, stealing, fighting, falling]

🧠 本机 VLM 高危行为识别

使用 MiniCPM-V-4.6（1.3B 视觉语言模型）在本机纯 CPU 离线识别高危行为，免费、无按次计费：

1. 下载模型：scripts/fetch_vlm_models.ps1（从 ModelScope）
2. 设置 → 本机识别 → 启用
3. 画面右侧「理解输出」面板显示每路的中文概述与命中描述（🧠 前缀）

VLM 推理在独立线程（每源独立节流），不拖慢主检测；命中以紫色虚线框叠加并无条件触发告警。

自检：

python scripts/vlm_selftest.py [图片路径]   # 缺省生成合成图

🧪 测试

python -m pytest tests/ -v

• 单元测试覆盖：配置/推理/告警/分析/跟踪/目标过滤/VLM 解析与多源调度/UI 构建
• 集成测试（test_vlm_integration.py）：真实 llama-server + 模型推理（模型缺失自动 skip）
• 全量基线：约 70+ 用例，覆盖单/多视频源场景

📦 打包

PyInstaller 构建免安装目录版：

pyinstaller yolovision.spec --noconfirm

产物在 dist/BehaviorVision/（BehaviorVision.exe + _internal/ 同层，不可单独拷贝 exe）。

📁 目录结构

├── yolovision/               # 主包
│   ├── main.py               # 入口（GUI / --selftest 自检）
│   ├── controller.py         # 调度器：采集→推理→VLM→告警 信号接线
│   ├── core/                 # 核心（不依赖 Qt UI）
│   │   ├── inference.py      # YoloEngine ONNX 推理（YOLOX/YOLO26 自适应）
│   │   ├── backends/         # 多内核注册表（yolox/motion/hog/hybrid）
│   │   ├── vlm.py            # VLM 客户端（llama-server 子进程/节流/解析）
│   │   ├── vlm_prompt.py     # VLM 提示词模板（结构化 JSON）
│   │   ├── alert.py          # 告警规则引擎（三通道推送+快照）
│   │   ├── analysis.py       # 二次分析（热力图）
│   │   ├── capture.py        # 视频源采集（RTSP/文件/摄像头）
│   │   ├── tracker.py        # 虚拟线计数 + IoU 关联
│   │   └── targets.py        # 目标语义组过滤
│   ├── ui/                   # PySide6 界面
│   │   ├── main_window.py    # 主窗口（工具栏含内核下拉框）
│   │   ├── video_widget.py   # 单路画面（叠加框分色：绿=本地/红=云端/紫=VLM）
│   │   ├── settings_dialog.py# 设置（模型/目标/告警/分析/云识别/本机识别）
│   │   ├── welcome_wizard.py # 首次启动引导向导
│   │   ├── help_dialog.py    # 应用内帮助文档
│   │   └── source_panel.py   # 视频源管理
│   └── utils/                # 配置/日志/摄像头枚举
├── scripts/                  # 工具脚本（模型下载/自检/联调 mock）
├── tests/                    # pytest 测试
├── docs/                     # 设计文档与使用说明
├── requirements.txt          # 运行时依赖
├── launcher.py               # PyInstaller 打包入口
└── yolovision.spec           # PyInstaller 配置

📄 许可证

本项目源码基于 Apache-2.0 协议开源。

• 检测模型：opencv_zoo YOLOX（Apache-2.0）
• 视觉语言模型：MiniCPM-V-4.6（Apache-2.0）
• 推理引擎：llama.cpp（MIT）
• 第三方依赖见 requirements.txt（详见 docs/开源协议合规报告.md）

注：本开源版不含付费授权/登录加密模块（认证、试用、激活码等已在发布源码中移除），客户端为免登录全功能形态。

🤝 贡献

欢迎提交 Issue 与 PR。开发请先阅读 docs/ACCEPTANCE.md 与 docs/TRAIN.md（自定义模型训练）。