523 lines
20 KiB
Markdown
523 lines
20 KiB
Markdown
# 项目整合计划书：视频检测平台功能扩展
|
||
|
||
## 文档信息
|
||
|
||
- **项目名称**: jc-video-recognize 视频模型检测平台
|
||
- **模块路径**: `/Users/wwh/project/jc-video-recognize/apps/server`
|
||
- **制定日期**: 2026-06-02
|
||
- **文档版本**: v1.0
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#1-项目概述)
|
||
2. [视频流接入方案](#2-视频流接入方案)
|
||
3. [MQTT预警事件消息系统](#3-mqtt预警事件消息系统)
|
||
4. [AI分析辅助功能集成](#4-ai分析辅助功能集成)
|
||
5. [大模型二次判断架构](#5-大模型二次判断架构)
|
||
6. [项目管理与实施计划](#6-项目管理与实施计划)
|
||
7. [交付成果清单](#7-交付成果清单)
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 现有系统架构
|
||
|
||
当前系统是一个基于 **FastAPI + YOLO/PaddlePaddle** 的实时视频检测平台：
|
||
|
||
| 层级 | 技术栈 | 说明 |
|
||
|------|--------|------|
|
||
| **前端** | Vue 3 + Vite + Element Plus | 用户界面与可视化 |
|
||
| **后端** | FastAPI + Uvicorn | REST API + WebSocket |
|
||
| **AI推理** | YOLOv8/v10 + PaddlePaddle | 多模型检测服务 |
|
||
| **实时通信** | WebSocket | 摄像头视频流传输 |
|
||
| **检测模型** | 火灾/安全帽/人群/抽烟/徘徊检测 | 已集成的AI能力 |
|
||
|
||
### 1.2 核心需求确认
|
||
|
||
| 需求 | 确认内容 |
|
||
|------|----------|
|
||
| **视频流接入** | 局域网环境，RTSP协议直接接入 |
|
||
| **消息系统** | 复用现有MQTT Broker |
|
||
| **AI扩展** | 大模型（GPT-4V/Claude等）进行二次深度判断 |
|
||
|
||
---
|
||
|
||
## 2. 视频流接入方案
|
||
|
||
### 2.1 系统架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 局域网环境 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 摄像头-1 │ │ 摄像头-2 │ │ 摄像头-N │ │
|
||
│ │ RTSP流 │ │ RTSP流 │ │ RTSP流 │ │
|
||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||
│ │ │ │ │
|
||
│ └───────────────┼───────────────┘ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────┐ │
|
||
│ │ Stream Manager │ │
|
||
│ │ (多路流管理调度) │ │
|
||
│ └──────────┬──────────┘ │
|
||
│ │ │
|
||
│ ┌───────────────┼───────────────┐ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 解码线程-1 │ │ 解码线程-2 │ │ 解码线程-N │ │
|
||
│ │(FFmpeg/CV2)│ │(FFmpeg/CV2)│ │(FFmpeg/CV2)│ │
|
||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||
│ │ │ │ │
|
||
│ └──────────────┼──────────────┘ │
|
||
│ ▼ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ AI检测引擎 │ │
|
||
│ │ YOLO/Paddle+大模型 │ │
|
||
│ └────────┬─────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ MQTT Publisher │ │
|
||
│ │ 预警事件发布 │ │
|
||
│ └──────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 技术方案选型
|
||
|
||
| 组件 | 技术选型 | 说明 |
|
||
|------|----------|------|
|
||
| **RTSP客户端** | `opencv-python` + `ffmpeg` | 支持硬件加速解码 |
|
||
| **流管理** | 异步线程池 | 每路流独立解码线程 |
|
||
| **帧缓冲** | 环形缓冲区 (Ring Buffer) | 防止内存溢出，支持丢帧策略 |
|
||
| **解码优化** | FFmpeg硬解码 (可选) | NVIDIA/Intel GPU加速 |
|
||
|
||
### 2.3 关键设计决策
|
||
|
||
**1. 解码方案选择**
|
||
- **方案A**: OpenCV VideoCapture (简单，已验证)
|
||
- **方案B**: FFmpeg子进程 (更稳定，支持更多格式)
|
||
- **推荐**: 方案A为主，方案B作为备选
|
||
|
||
**2. 多路并发策略**
|
||
|
||
```python
|
||
# 每路摄像头配置
|
||
{
|
||
"camera_id": "cam_001",
|
||
"rtsp_url": "rtsp://192.168.1.100:554/stream",
|
||
"decode_fps": 5, # 解码帧率（降低AI负载）
|
||
"buffer_size": 30, # 缓冲区大小
|
||
"reconnect_interval": 5 # 断线重连间隔(秒)
|
||
}
|
||
```
|
||
|
||
**3. 性能预估**
|
||
|
||
| 指标 | 目标值 | 说明 |
|
||
|------|--------|------|
|
||
| 单路延迟 | < 300ms | 解码+AI推理 |
|
||
| 并发路数 | 16路+ | CPU推理 |
|
||
| CPU占用 | < 70% | 16路@720p |
|
||
|
||
### 2.4 开发与集成任务
|
||
|
||
- [ ] 设计视频流接收、解码、存储及转发的系统架构
|
||
- [ ] 开发RTSP协议解析模块
|
||
- [ ] 实现视频流数据处理管道，确保低延迟与高稳定性
|
||
- [ ] 编写视频流接入模块的单元测试与集成测试用例
|
||
|
||
### 2.5 质量保障与验收标准
|
||
|
||
| 指标 | 目标值 |
|
||
|------|--------|
|
||
| 视频流传输延迟 | < 500ms |
|
||
| 异常恢复时间 | < 5秒 |
|
||
| 并发视频流支持 | ≥ 16路 |
|
||
| 系统可用性 | 7×24小时 |
|
||
|
||
---
|
||
|
||
## 3. MQTT预警事件消息系统
|
||
|
||
### 3.1 系统架构设计
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ AI检测服务 │────▶│ 事件处理器 │────▶│ MQTT Broker │
|
||
└─────────────┘ └─────────────┘ └──────┬──────┘
|
||
│
|
||
┌──────────────────────┼──────────┐
|
||
▼ ▼ ▼
|
||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||
│ Web前端 │ │ 移动端 │ │ 第三方 │
|
||
└─────────┘ └─────────┘ └─────────┘
|
||
```
|
||
|
||
### 3.2 消息主题设计
|
||
|
||
```
|
||
# 主题层级结构
|
||
jc-video/
|
||
├── alerts/
|
||
│ ├── fire/ # 火灾预警
|
||
│ │ └── {camera_id} # 具体摄像头
|
||
│ ├── smoking/ # 抽烟预警
|
||
│ ├── loitering/ # 徘徊预警
|
||
│ └── illegal_parking/ # 违停预警
|
||
├── status/
|
||
│ ├── camera/ # 摄像头状态
|
||
│ └── system/ # 系统状态
|
||
└── commands/
|
||
└── camera/ # 摄像头控制指令
|
||
```
|
||
|
||
### 3.3 预警事件消息格式
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
|
||
"event_type": "fire",
|
||
"event_level": "critical",
|
||
"timestamp": "2026-06-02T10:30:00.123Z",
|
||
"camera_id": "cam_001",
|
||
"camera_name": "大厅摄像头",
|
||
"location": {
|
||
"building": "A栋",
|
||
"floor": "1F",
|
||
"area": "大厅"
|
||
},
|
||
"detection": {
|
||
"class": "Fire",
|
||
"confidence": 0.95,
|
||
"bbox": [100, 200, 150, 180],
|
||
"snapshot_url": "/static/alerts/evt_550e8400.jpg"
|
||
},
|
||
"ai_analysis": {
|
||
"llm_verified": true,
|
||
"llm_confidence": 0.92,
|
||
"llm_reasoning": "检测到明显火焰特征，伴随烟雾..."
|
||
},
|
||
"metadata": {
|
||
"model_id": "fire_detection",
|
||
"processing_time_ms": 150
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 QoS策略
|
||
|
||
| 消息类型 | QoS等级 | 说明 |
|
||
|----------|---------|------|
|
||
| 预警事件 | QoS 2 | 确保只送达一次 |
|
||
| 状态上报 | QoS 1 | 至少送达一次 |
|
||
| 控制指令 | QoS 1 | 至少送达一次 |
|
||
|
||
### 3.5 开发与集成任务
|
||
|
||
- [ ] 设计预警事件消息的结构格式与传输协议
|
||
- [ ] 配置MQTT服务器安全认证机制
|
||
- [ ] 开发MQTT客户端模块，实现消息发布与订阅功能
|
||
- [ ] 设计预警事件触发机制与消息路由策略
|
||
- [ ] 实现消息持久化存储与消费确认机制
|
||
- [ ] 开发预警消息管理后台，支持消息查询与统计分析
|
||
|
||
### 3.6 质量保障与验收标准
|
||
|
||
| 指标 | 目标值 |
|
||
|------|--------|
|
||
| 消息传输成功率 | 100% |
|
||
| 消息丢失率 | 0 |
|
||
| 预警消息延迟 | < 1秒 |
|
||
| 并发客户端连接 | ≥ 100个 |
|
||
|
||
---
|
||
|
||
## 4. AI分析辅助功能集成
|
||
|
||
### 4.1 当前已支持的检测能力
|
||
|
||
- ✅ 火灾检测 (YOLOv10)
|
||
- ✅ 安全帽检测 (YOLOv8)
|
||
- ✅ 人群检测 (YOLOv8)
|
||
- ✅ 抽烟检测 (YOLOv8 + PaddlePaddle)
|
||
- ✅ 徘徊检测 (YOLOv8 + 行为分析)
|
||
|
||
### 4.2 建议扩展的AI能力
|
||
|
||
| 功能 | 技术方案 | 优先级 |
|
||
|------|----------|--------|
|
||
| 人脸识别/属性分析 | InsightFace / PaddleFace | 中 |
|
||
| 车辆识别/车牌检测 | PP-Vehicle (已有基础) | 高 |
|
||
| 异常行为检测 | 自定义行为分析算法 | 中 |
|
||
| 越界/入侵检测 | 虚拟围栏算法 | 高 |
|
||
|
||
### 4.3 开发与集成任务
|
||
|
||
- [ ] 根据业务需求评估并选择合适的AI模型
|
||
- [ ] 搭建AI模型训练与推理环境，配置必要的GPU资源
|
||
- [ ] 制定AI模型性能评估指标与优化策略
|
||
- [ ] 设计AI分析接口，实现与视频流数据的对接
|
||
- [ ] 开发AI模型推理服务，支持实时分析与批量处理两种模式
|
||
- [ ] 实现AI分析结果与预警系统的联动机制
|
||
- [ ] 开发AI模型效果监控与反馈优化模块
|
||
|
||
### 4.4 质量保障与验收标准
|
||
|
||
| 指标 | 目标值 |
|
||
|------|--------|
|
||
| AI分析准确率 | ≥ 90% |
|
||
| 单帧视频分析处理时间 | < 200ms |
|
||
| 模型更新支持 | 定期更新与持续优化 |
|
||
|
||
---
|
||
|
||
## 5. 大模型二次判断架构
|
||
|
||
### 5.1 架构设计
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ AI分析流程 │
|
||
│ │
|
||
│ 视频帧 → YOLO初检 → 触发条件? ──否──→ 丢弃 │
|
||
│ │ │
|
||
│ 是 │
|
||
│ ▼ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ 截取ROI区域 │ │
|
||
│ │ (目标区域放大) │ │
|
||
│ └────────┬────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ 大模型视觉分析 │ │
|
||
│ │ (GPT-4V/Claude) │ │
|
||
│ │ │ │
|
||
│ │ Prompt: │ │
|
||
│ │ "分析图片中是否 │ │
|
||
│ │ 存在火灾/抽烟 │ │
|
||
│ │ 等危险行为" │ │
|
||
│ └────────┬────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ 结果融合决策 │ │
|
||
│ │ │ │
|
||
│ │ YOLO置信度 × │ │
|
||
│ │ LLM置信度 = │ │
|
||
│ │ 最终预警等级 │ │
|
||
│ └────────┬────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ 生成预警事件 │ │
|
||
│ │ 发布MQTT │ │
|
||
│ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.2 大模型选型对比
|
||
|
||
| 模型 | 优点 | 缺点 | 成本 | 适用场景 |
|
||
|------|------|------|------|----------|
|
||
| **GPT-4o** | 视觉能力强，响应快 | 需翻墙，成本较高 | $$$ | 高精度场景 |
|
||
| **Claude 3.5 Sonnet** | 推理能力强，中文好 | 国内访问不稳定 | $$ | 复杂场景分析 |
|
||
| **Qwen-VL (通义千问)** | 国内可用，成本低 | 精度略低 | $ | 成本敏感场景 |
|
||
| **GLM-4V (智谱)** | 国内可用，中文优化 | 生态较小 | $ | 本地化部署 |
|
||
|
||
### 5.3 推荐方案：多模型策略
|
||
|
||
```python
|
||
# 大模型配置
|
||
LLM_CONFIGS = {
|
||
"primary": {
|
||
"provider": "openai",
|
||
"model": "gpt-4o",
|
||
"api_key_env": "OPENAI_API_KEY",
|
||
"max_tokens": 500,
|
||
"temperature": 0.3
|
||
},
|
||
"fallback": {
|
||
"provider": "dashscope", # 阿里通义千问
|
||
"model": "qwen-vl-max",
|
||
"api_key_env": "DASHSCOPE_API_KEY",
|
||
"max_tokens": 500,
|
||
"temperature": 0.3
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.4 Prompt设计模板
|
||
|
||
#### 火灾检测Prompt
|
||
|
||
```
|
||
你是一位专业的消防安全分析师。请仔细分析这张图片，判断是否存在以下情况：
|
||
|
||
1. **真实火焰** - 明火、燃烧现象
|
||
2. **烟雾** - 可见烟雾
|
||
3. **误报可能** - 红色物体、灯光、反光等非火灾情况
|
||
|
||
请按以下格式回复：
|
||
```json
|
||
{
|
||
"has_fire": true/false,
|
||
"has_smoke": true/false,
|
||
"confidence": 0-1,
|
||
"reasoning": "详细分析说明",
|
||
"risk_level": "low/medium/high/critical"
|
||
}
|
||
```
|
||
|
||
注意：必须严格区分真实火灾和视觉相似物（如红色衣服、灯光）。
|
||
|
||
|
||
|
||
|
||
### 5.5 触发大模型的条件
|
||
|
||
```python
|
||
# 触发策略配置
|
||
TRIGGER_CONFIG = {
|
||
# 条件1: YOLO置信度在模糊区间
|
||
"confidence_range": [0.5, 0.85],
|
||
|
||
# 条件2: 特定场景强制触发
|
||
"force_trigger_scenes": ["indoor_no_smoking_area"],
|
||
|
||
# 条件3: 时间窗口去重（避免重复调用）
|
||
"dedup_window_seconds": 30,
|
||
|
||
# 条件4: 并发限制
|
||
"max_concurrent_llm_calls": 5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 项目管理与实施计划
|
||
|
||
### 6.1 项目时间轴
|
||
|
||
| 阶段 | 时间范围 | 主要任务 | 交付物 |
|
||
|------|----------|----------|--------|
|
||
| **阶段一** | 第1周 | 需求分析与技术方案确定 | 技术方案文档 |
|
||
| **阶段二** | 第2-3周 | RTSP接入开发 | RTSP服务模块 |
|
||
| **阶段三** | 第4周 | MQTT预警系统开发 | MQTT服务模块 |
|
||
| **阶段四** | 第5-6周 | 大模型集成 | AI分析服务 |
|
||
| **阶段五** | 第7周 | 系统集成与联调 | 集成测试报告 |
|
||
| **阶段六** | 第8周 | 系统测试与性能优化 | 性能测试报告 |
|
||
| **阶段七** | 第9周 | 部署上线与运维支持 | 生产版本 |
|
||
|
||
### 6.2 资源需求
|
||
|
||
#### 6.2.1 人员配置
|
||
|
||
| 角色 | 人数 | 职责 |
|
||
|------|------|------|
|
||
| 后端开发 | 2人 | FastAPI服务、MQTT、视频流 |
|
||
| AI算法 | 1人 | 模型优化、大模型集成 |
|
||
| 测试 | 1人 | 功能测试、性能测试 |
|
||
|
||
#### 6.2.2 硬件资源
|
||
|
||
| 资源 | 数量 | 用途 |
|
||
|------|------|------|
|
||
| 服务器 | 2台 | 主备部署 |
|
||
| GPU (可选) | 1块 | AI推理加速 |
|
||
| 摄像头 | 若干 | 测试验证 |
|
||
|
||
#### 6.2.3 软件资源
|
||
|
||
- 开发工具：VS Code、PyCharm
|
||
- 测试环境：Docker、Postman
|
||
- 部署平台：Linux服务器
|
||
|
||
### 6.3 风险管理
|
||
|
||
| 风险点 | 影响 | 应对策略 |
|
||
|--------|------|----------|
|
||
| RTSP延迟过高 | 高 | 采用硬件解码、优化缓冲策略 |
|
||
| MQTT消息丢失 | 高 | 实现QoS等级、消息持久化 |
|
||
| AI模型性能不足 | 中 | 模型量化、批处理优化 |
|
||
| 大模型API不稳定 | 中 | 多模型降级策略、本地缓存 |
|
||
| 并发处理能力 | 中 | 异步架构、服务拆分 |
|
||
|
||
---
|
||
|
||
## 7. 交付成果清单
|
||
|
||
### 7.1 文档交付物
|
||
|
||
- [ ] 系统设计文档与技术方案说明书
|
||
- [ ] 用户操作手册与开发文档
|
||
- [ ] 系统部署包与环境配置说明
|
||
|
||
### 7.2 代码交付物
|
||
|
||
| 文件路径 | 功能 |
|
||
|----------|------|
|
||
| `services/rtsp_service.py` | RTSP流接收与解码 |
|
||
| `services/stream_manager.py` | 多路流管理调度 |
|
||
| `services/mqtt_service.py` | MQTT客户端连接 |
|
||
| `services/alert_service.py` | 预警事件生成 |
|
||
| `services/llm_analysis_service.py` | 大模型视觉分析 |
|
||
| `models/stream_schemas.py` | 流数据模型 |
|
||
| `models/alert_schemas.py` | 预警数据模型 |
|
||
| `api/streaming.py` | 流管理API |
|
||
| `api/alerts.py` | 预警查询API |
|
||
|
||
### 7.3 测试交付物
|
||
|
||
- [ ] 测试报告与性能评估报告
|
||
- [ ] 单元测试用例与覆盖率报告
|
||
- [ ] 集成测试报告
|
||
|
||
### 7.4 部署交付物
|
||
|
||
- [ ] 源代码与构建部署脚本
|
||
- [ ] Docker镜像与编排文件
|
||
- [ ] 环境变量配置模板
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 技术依赖清单
|
||
|
||
```
|
||
# 新增Python依赖
|
||
paho-mqtt>=1.6.0 # MQTT客户端
|
||
openai>=1.0.0 # OpenAI API
|
||
httpx>=0.24.0 # 异步HTTP客户端
|
||
aioredis>=2.0.0 # Redis缓存（可选）
|
||
pydantic-settings>=2.0.0 # 配置管理
|
||
```
|
||
|
||
### B. 环境变量配置
|
||
|
||
```bash
|
||
# MQTT配置
|
||
MQTT_BROKER_HOST=localhost
|
||
MQTT_BROKER_PORT=1883
|
||
MQTT_USERNAME=admin
|
||
MQTT_PASSWORD=password
|
||
|
||
# 大模型API配置
|
||
OPENAI_API_KEY=sk-xxx
|
||
DASHSCOPE_API_KEY=sk-xxx
|
||
|
||
# RTSP配置
|
||
RTSP_DEFAULT_FPS=5
|
||
RTSP_BUFFER_SIZE=30
|
||
RTSP_RECONNECT_INTERVAL=5
|
||
```
|
||
|
||
---
|
||
|
||
*文档结束*
|