# 项目整合计划书：视频检测平台功能扩展

## 文档信息

- **项目名称**: 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
```

---

*文档结束*