jc/jc-video-recognize
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 总结项目现状与功能梳理

Browse Source
This commit is contained in:
wuzhuorong
2026-06-16 14:58:49 +08:00
parent 1409734c8a
commit 0158b41712
1 changed files with 821 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/项目现状与功能梳理.md
+821
View File
@@ -0,0 +1,821 @@
# jc-video-recognize 项目现状与功能梳理
> 基于 `event-judgment-algorithm-architecture.md` 和 `project-integration-plan.md` 两份架构设计文档，
> 结合三个 MVP 迭代的实际代码实现，对项目当前已实现功能的全面梳理。
---
## 文档信息
- **项目名称**: jc-video-recognize 视频模型检测平台
- **文档版本**: v2.0
- **更新日期**: 2026-06-16
- **覆盖范围**: MVP-1（事件判断管道）+ MVP-2（RTSP/MQTT/实时推送）+ MVP-3（LLM 二次判断）
---
## 1. 项目概述
本项目是一个全栈视频智能检测平台，集成了多种 AI 检测模型（YOLO 系列 + PaddlePaddle 系列），覆盖火灾、安全帽、人群、抽烟、徘徊、车辆违停、打架斗殴等场景。系统在原始检测能力基础上，构建了完整的事件判断管道、RTSP 视频流接入、MQTT 预警发布、WebSocket 实时推送、以及大模型二次判断等企业级能力。
### 1.1 技术栈
| 层级 | 技术栈 | 说明 |
|------|--------|------|
| **前端** | Vue 3 + Vite 5 + Element Plus + Pinia | 暗色主题 UI，4 个核心页面 |
| **后端** | FastAPI + Uvicorn | REST API + WebSocket |
| **AI 推理** | YOLOv8/v10 (Ultralytics) + PaddlePaddle 3.0 | 多模型检测服务 |
| **视频流** | OpenCV + RTSP | 多路摄像头实时接入 |
| **消息系统** | MQTT (paho-mqtt) | 预警事件发布 |
| **大模型** | OpenAI 兼容协议 (GPT-4V/Qwen-VL/GLM-4V) | 二次判断与结果融合 |
| **目标跟踪** | ByteTrack (纯 Python) | 稳定跟踪 ID 分配 |
| **构建部署** | pnpm + Turborepo + Docker + Nginx | Monorepo 管理 |
### 1.2 整体架构图
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 前端 (Vue 3) │
│ ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 模型检测 │ │ 摄像头管理 │ │ 规则配置 │ │ 预警列表 │ │
│ │ Home.vue │ │ CameraMgmt │ │ RuleConfig│ │ AlertList │ │
│ └────┬─────┘ └──────┬───────┘ └────┬─────┘ └──────┬───────┘ │
│ │ │ │ │ │
│ └───────────────┴──────────────┴───────────────┘ │
│ │ HTTP/REST + WebSocket │
└───────────────────────┼─────────────────────────────────────────────────────┘
│
┌───────────────────────┼─────────────────────────────────────────────────────┐
│ ▼ │
│ 后端 (FastAPI) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ API 层 │ │
│ │ /api/detect/* /api/models/* /api/rtsp/* /api/rules/* /api/llm/*│ │
│ │ /ws/camera /ws/alerts │ │
│ └──────────────────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼───────────────────────────────────────────┐ │
│ │ 服务层 │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│ │ │ DetectionSvc │ │ RTSPService │ │ StreamMgr │ │ MQTTService│ │ │
│ │ │ (检测核心) │ │ (流接入) │ │ (多路调度) │ │ (消息发布) │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬─────┘ │ │
│ │ │ │ │ │ │ │
│ │ ┌──────▼────────────────▼────────────────▼────────────────▼─────┐ │ │
│ │ │ 事件判断管道 │ │ │
│ │ │ │ │ │
│ │ │ DecisionEngine → AlertRuleEngine → EventAggregator │ │ │
│ │ │ │ │ │ │ │
│ │ │ ▼ ▼ │ │ │
│ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ LLM 二次判断管道 │ │ │ │
│ │ │ │ FrameAccumulator → LLMTrigger → LLMAnalysisService │ │ │ │
│ │ │ │ ResultFusion + LLMCostTracker (熔断降级) │ │ │ │
│ │ │ └──────────────────────────────────────────────────────┘ │ │ │
│ │ └───────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │
│ │ │ ByteTracker │ │ AlertPublisher│ │ DetectionAdapter │ │ │
│ │ │ (目标跟踪) │ │ (MQTT发布) │ │ (结果格式统一) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ 推理引擎层 │ │
│ │ ┌─────────┐ ┌──────────────┐ ┌────────────┐ │ │
│ │ │ YOLO │ │ PaddlePaddle │ │ Docker API │ │ │
│ │ │(Ultralytics) │(PP-YOLOE) │ │ (ppTSM) │ │ │
│ │ └─────────┘ └──────────────┘ └────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
```
---
## 2. 已实现功能清单
### 2.1 AI 检测能力（原始功能）
| 模型 ID | 名称 | 框架 | 检测类别 | 图片检测 | 视频检测 |
|---------|------|------|----------|---------|---------|
| `fire_detection` | 火灾检测 | YOLOv10 | 火焰、烟雾 | ✅ | ❌ |
| `helmet_detection` | 安全帽检测 | YOLOv8 | 人员、安全帽 | ✅ | ❌ |
| `crowd_detection` | 人群检测 | YOLOv8 | 人员 | ✅ | ❌ |
| `smoking_detection` | 抽烟检测 | YOLOv8 | 香烟、烟雾 | ✅ | ❌ |
| `smoking_detection_paddle` | 抽烟检测 (Paddle) | PP-YOLOE-s | 香烟 | ✅ | ❌ |
| `loitering_detection` | 徘徊检测 | YOLOv8 | 人员（含行为分析） | ✅ | ❌ |
| `vehicle_detection` | 车辆检测 | PP-YOLOE-l | 车辆 | ✅ | ❌ |
| `illegal_parking_detection` | 违停检测 | PP-YOLOE-l | 车辆（含违停判断） | ✅ | ❌ |
| `fight_detection` | 打架斗殴检测 | YOLOv8 | 暴力行为、正常 | ✅ | ✅ |
| `action_detection` | 打架检测 (Docker) | ppTSM | 打架、正常 | ✅ | ❌ |
**行为分析算法**（集成在 `loitering_detection` 下）：
| 算法 | 说明 | 参数 |
|------|------|------|
| 静止检测 | 基于位置匹配，检测人员静止停留 | 静止阈值(秒)、位置容差(像素) |
| 徘徊检测 | 基于跟踪ID，检测人员长时间停留 | 徘徊阈值(秒)、移动阈值(像素) |
**检测适配器**：通过 `DetectionAdapter` 将 YOLO、PaddlePaddle、Docker 三种不同输出格式统一为 `UnifiedDetection` / `DetectionResult`，为后续事件管道提供一致的数据入口。
---
### 2.2 事件判断管道（MVP-1 已实现）
对应设计文档 `event-judgment-algorithm-architecture.md` 中的「决策层」。
#### 2.2.1 事件决策引擎 (`EventDecisionEngine`)
**文件**: `services/event/decision_engine.py`
- 根据置信度阈值过滤检测结果
- 将底层 class_name 映射为统一 `EventType` 枚举（fire/smoke/smoking/fight/loitering/illegal_parking 等）
- 生成 `CandidateEvent` 候选事件，附带严重性级别、来源信息、检测详情
#### 2.2.2 预警规则引擎 (`AlertRuleEngine`)
**文件**: `services/event/rule_engine.py`
- 从 YAML 配置目录加载规则（`config/rules/*.yaml`）
- 支持规则类型：置信度阈值、事件类型、最小边界框面积、限定摄像头来源、必备标签
- 每条规则可配置严重性级别（info/low/medium/high/critical）
- 支持热重载（无需重启服务即可更新规则）
- 已内置规则文件：`fire.yaml`、`smoking.yaml`、`loitering.yaml`、`fight.yaml`、`vehicle.yaml`
#### 2.2.3 事件聚合器 (`EventAggregator`)
**文件**: `services/event/aggregator.py`
- 基于时间窗口去重：同一 (source_id, event_type, track_id) 在窗口内只产生一条预警
- 空间邻近合并：IOU 超过阈值的同类事件自动合并
- 置信度加权融合：历史置信度按衰减因子递减，新检测加权更新
- 输出 `AlertEvent`，包含首次/末次出现时间、触发次数、关联检测列表
#### 2.2.4 统一事件数据契约 (`event_schemas.py`)
**文件**: `models/event_schemas.py`
定义了完整的事件数据模型体系：
| 模型 | 说明 |
|------|------|
| `EventType` | 统一事件类型枚举（11 种） |
| `SeverityLevel` | 严重性级别枚举（5 级） |
| `DetectionSource` | 检测来源枚举（YOLO/Paddle/Docker/Behavior/Composite） |
| `BBox` | 边界框 (xyxy) |
| `UnifiedDetection` | 统一检测结果（含 track_id） |
| `DetectionResult` | 单帧检测结果集合 |
| `CandidateEvent` | 候选事件（决策引擎输出） |
| `AlertEvent` | 预警事件（聚合器输出，最终发布格式） |
---
### 2.3 RTSP 视频流接入（MVP-2 已实现）
对应设计文档 `project-integration-plan.md` 中的「视频流接入方案」。
#### 2.3.1 RTSP 流接入服务 (`RTSPService`)
**文件**: `services/rtsp_service.py`
- 基于 OpenCV VideoCapture 的 RTSP 接入，兼容主流 IP 摄像头
- 后台线程解码帧，避免阻塞事件循环
- 自动重连：断线后按指数退避策略重试（可配置最大次数、间隔、退避因子）
- 帧回调机制：每解码一帧触发回调，由 StreamManager 分发到检测管道
- 优雅关闭：stop() 等待解码线程退出，释放资源
- 流状态管理：idle → connecting → connected → reconnecting → stopped → error
#### 2.3.2 多路流调度管理器 (`StreamManager`)
**文件**: `services/stream_manager.py`
- 统一管理多路 RTSPService 实例（最大 16 路，可配置）
- 每路流对应一个 `FrameBuffer`（环形缓冲区），解耦解码与检测
- 检测调度：轮询帧缓冲区，按流配置的模型和参数执行检测
- 状态监控：汇总所有流状态，提供健康检查接口
- RESTful API 管理：添加/移除/启动/停止/配置更新
#### 2.3.3 帧缓冲区 (`FrameBuffer`)
**文件**: `services/frame_buffer.py`
- 环形缓冲区设计，防止内存溢出
- 支持丢帧策略（最新帧优先 / 均匀采样）
- 线程安全：解码线程写入、检测线程读取
#### 2.3.4 RTSP 管理 API
**文件**: `api/rtsp.py`
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rtsp/streams` | 获取所有流状态列表 |
| `GET` | `/api/rtsp/streams/{stream_id}` | 获取单路流详情 |
| `POST` | `/api/rtsp/streams` | 添加新摄像头流 |
| `DELETE` | `/api/rtsp/streams/{stream_id}` | 移除摄像头流 |
| `POST` | `/api/rtsp/streams/{stream_id}/start` | 启动指定流 |
| `POST` | `/api/rtsp/streams/{stream_id}/stop` | 停止指定流 |
| `PUT` | `/api/rtsp/streams/{stream_id}/config` | 更新流检测配置 |
| `POST` | `/api/rtsp/start-all` | 启动全部流 |
| `POST` | `/api/rtsp/stop-all` | 停止全部流 |
| `GET` | `/api/rtsp/health` | 健康检查 |
---
### 2.4 MQTT 预警消息系统（MVP-2 已实现）
对应设计文档 `project-integration-plan.md` 中的「MQTT预警事件消息系统」。
#### 2.4.1 MQTT 客户端服务 (`MQTTService`)
**文件**: `services/mqtt_service.py`
- 基于 paho-mqtt 的 MQTT 客户端封装
- 支持用户名/密码认证
- 自动重连：按指数退避策略重试（可配置最小/最大延迟）
- QoS 等级可配置（默认 QoS 1，确保至少送达一次）
- 消息保留（retain）可配置
#### 2.4.2 预警发布器 (`AlertPublisher`)
**文件**: `services/alert_publisher.py`
- 将 `AlertEvent` 格式化为标准 JSON 消息
- 主题命名规则：`{prefix}/{event_type}/{source_id}`（单流单类型）、`{prefix}/all`（全量订阅）
- 同时触发 WebSocket 广播（通过 AlertBroadcaster）
- 消息包含：alert_id、event_type、severity、confidence、source_id、rule_name、detections 等
#### 2.4.3 MQTT 配置
通过环境变量或 `.env` 文件配置：
| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| 启用 | `MQTT_ENABLED` | `false` | 是否启用 MQTT |
| Broker 地址 | `MQTT_BROKER_HOST` | `localhost` | MQTT 服务器 |
| Broker 端口 | `MQTT_BROKER_PORT` | `1883` | 端口 |
| 客户端 ID | `MQTT_CLIENT_ID` | `jc-video-recognize` | 客户端标识 |
| QoS | `MQTT_QOS` | `1` | 消息质量等级 |
| 主题前缀 | `MQTT_ALERT_TOPIC_PREFIX` | `video/alerts` | 主题前缀 |
---
### 2.5 目标跟踪服务（MVP-2 已实现）
对应设计文档 `event-judgment-algorithm-architecture.md` 中的「目标轨迹关联」。
#### 2.5.1 ByteTracker (`tracking_service.py`)
**文件**: `services/tracking_service.py`
- 基于 ByteTrack 论文的简化跟踪器，纯 Python 实现
- 按置信度将检测分为 high/low 两组
- 先用 high 检测与现有 tracks 进行 IOU 匹配
- 未匹配的 tracks 再与 low 检测匹配（拯救低置信度真实目标）
- 未匹配的 high 检测创建新 track
- 超过 `max_lost_frames` 的 tracks 移除
- 为每个检测目标分配稳定的 `track_id`，支持目标轨迹关联
---
### 2.6 WebSocket 实时推送（MVP-2 已实现）
对应设计文档 `project-integration-plan.md` 中的「实时通信」。
#### 2.6.1 预警 WebSocket (`/ws/alerts`)
**文件**: `api/alerts.py`
- `AlertBroadcaster` 维护 WebSocket 连接池
- 支持按事件类型、source_id 过滤订阅
- 心跳机制：前端每 30 秒发送 ping，后端回复 pong
- 预警事件通过 MQTT 发布的同时广播到所有 WebSocket 订阅者
- 消息格式：`{"type": "alert", "data": {...}}`
#### 2.6.2 摄像头 WebSocket (`/ws/camera`)
**文件**: `main.py` → `CameraService`
- 实时视频流传输（原始帧 + 标注帧双路）
- 支持动态切换模型、调整置信度/IOU 阈值
- 自动清理摄像头资源
---
### 2.7 LLM 大模型二次判断（MVP-3 已实现）
对应设计文档 `event-judgment-algorithm-architecture.md` 中的「AI增强层」和 `project-integration-plan.md` 中的「大模型二次判断架构」。
#### 2.7.1 多帧累积器 (`MultiFrameAccumulator`)
**文件**: `services/event/frame_accumulator.py`
- 累积同一目标在时间窗口内的候选事件
- 统计连续命中帧数、平均置信度、首次/末次出现时间
- LRU 淘汰机制：超出最大容量时淘汰最久未更新的条目
- 过期淘汰：超出时间窗口的条目自动清理
- 为 LLM 触发器提供累积统计数据
#### 2.7.2 LLM 触发器 (`LLMTrigger`)
**文件**: `services/event/llm_trigger.py`
- 基于累积统计决定是否触发 LLM 二次判断
- 触发条件：连续命中帧数 ≥ `min_consecutive_hits` 且平均置信度 ≥ `min_avg_confidence`
- 严重性旁路：`critical` 级别事件无需累积，立即触发 LLM
- 冷却机制：同一目标在冷却时间内不重复触发
- 输出 `TriggerDecision`，包含是否触发、累积帧列表、触发原因
#### 2.7.3 LLM 分析服务 (`LLMAnalysisService`)
**文件**: `services/llm_analysis_service.py`
- **Provider 抽象**：`BaseLLMProvider` 抽象基类，支持多种 LLM 后端
- `MockLLMProvider`：离线测试用，返回模拟结果
- `OpenAICompatibleProvider`：支持 OpenAI 兼容协议（GPT-4V/Qwen-VL/GLM-4V 等）
- 并发控制：`asyncio.Semaphore` 限制同时进行的 LLM 调用数
- 图像预处理：自动缩放到 `image_max_side` 以节省 token
- 结构化输出解析：从 LLM 响应中提取 confirmed/confidence/reasoning
- 调用统计：记录调用次数、成功/失败数、总延迟
#### 2.7.4 结果融合器 (`ResultFusion`)
**文件**: `services/result_fusion.py`
三种融合策略：
| 策略 | 说明 |
|------|------|
| `weighted` | 加权融合：YOLO 权重 × YOLO 置信度 + LLM 权重 × LLM 置信度 |
| `conservative` | 保守策略：LLM 明确否决时直接抑制预警 |
| `llm_priority` | LLM 优先：LLM 给出明确判定时以 LLM 为准 |
关键行为：
- LLM 不可用/未触发时，可配置是否回退到 YOLO 结果（`fallback_to_yolo`）
- LLM 明确否决时，可配置是否抑制预警（`suppress_on_llm_negative`）
- 高融合置信度时可自动提升严重性级别（`promote_severity_on_high_confidence`）
#### 2.7.5 LLM 成本追踪与熔断降级 (`LLMCostTracker`)
**文件**: `services/llm_cost_tracker.py`
- **成本追踪**：记录每次 LLM 调用的 token 用量、费用、延迟
- **日预算控制**：超过日预算自动拒绝调用
- **熔断降级**：
- 状态机：CLOSED → OPEN → HALF_OPEN → CLOSED
- 触发条件：最近 N 次调用错误率超过阈值
- 冷却恢复：OPEN 状态持续 `cooldown_seconds` 后进入 HALF_OPEN，允许一次试探
- 手动控制：支持紧急停用 / 重新启用 / 重置统计
- **定价表**：内置主流模型定价，支持自定义覆盖
- **统计接口**：提供日级统计、历史趋势、最近调用记录
#### 2.7.6 LLM 管理 API
**文件**: `api/llm.py`
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/llm/status` | 获取 LLM 运行状态（provider/模型/触发配置/融合配置/成本） |
| `GET` | `/api/llm/cost` | 获取当前成本统计 |
| `GET` | `/api/llm/cost/history` | 获取历史成本趋势（按天） |
| `GET` | `/api/llm/cost/records` | 获取最近调用记录 |
| `POST` | `/api/llm/disable` | 紧急停用 LLM |
| `POST` | `/api/llm/enable` | 重新启用 LLM |
| `POST` | `/api/llm/reset` | 重置成本统计与熔断状态 |
---
### 2.8 规则配置管理（MVP-3 已实现）
#### 2.8.1 规则管理 API
**文件**: `api/rules.py`
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rules` | 获取所有规则列表 |
| `GET` | `/api/rules/{name}` | 获取单条规则详情 |
| `POST` | `/api/rules` | 新增规则（写入 custom.yaml） |
| `PUT` | `/api/rules/{name}` | 更新规则 |
| `DELETE` | `/api/rules/{name}` | 删除规则 |
| `POST` | `/api/rules/reload` | 热重载规则（从 YAML 重新加载） |
| `GET` | `/api/rules/_stats` | 获取规则统计信息 |
---
### 2.9 统一配置管理（MVP-1/2/3 已实现）
**文件**: `core/settings.py`
基于 `pydantic-settings` 的多环境配置管理，支持环境变量、`.env` 文件、默认值三级加载。
| 子配置 | 环境变量前缀 | 覆盖范围 |
|--------|-------------|---------|
| `APISettings` | `API_` | 服务端口、CORS |
| `DetectionSettings` | `DETECTION_` | 默认置信度、IOU、最低置信度 |
| `ActionDetectionSettings` | `ACTION_DETECTION_` | Docker 行为识别服务 |
| `EventEngineSettings` | `EVENT_` | 去重窗口、规则目录、最大事件数 |
| `RTSPSettings` | `RTSP_` | 最大流数、缓冲区、重连策略 |
| `MQTTSettings` | `MQTT_` | Broker 配置、QoS、主题 |
| `TrackingSettings` | `TRACKING_` | ByteTrack 参数 |
| `AggregatorSettings` | `AGGREGATOR_` | 空间合并、置信度融合 |
| `LLMSettings` | `LLM_` | Provider、模型、API Key、并发 |
| `LLMTriggerSettings` | `LLM_TRIGGER_` | 触发阈值、冷却、严重性旁路 |
| `FusionSettings` | `FUSION_` | 融合策略、权重、回退 |
| `LLMCostSettings` | `LLM_COST_` | 日预算、熔断阈值、冷却 |
| `LoggingSettings` | `LOG_` | 日志级别、格式 |
| `PathSettings` | `PATH_` | 静态资源、模型路径 |
---
## 3. 前端功能清单
### 3.1 页面结构
| 页面 | 路径 | 组件 | 功能 |
|------|------|------|------|
| 模型检测 | `/` | `Home.vue` + `ImageDetection.vue` + `VideoDetection.vue` | 图片/视频/摄像头实时检测 |
| 摄像头管理 | `/cameras` | `CameraManagement.vue` | RTSP 流增删改查、启停控制 |
| 规则配置 | `/rules` | `RuleConfiguration.vue` | 规则 CRUD + LLM 状态面板 |
| 预警列表 | `/alerts` | `AlertList.vue` | 实时预警展示、过滤、LLM 结果展示 |
### 3.2 全局功能
- **暗色主题 UI**：统一深色设计风格
- **可折叠侧边栏**：4 个导航菜单项
- **实时连接状态**：显示 WebSocket 连接状态（已连接/连接中/未连接）
- **预警铃铛**：顶部显示未读预警数量，点击跳转预警列表
- **全局预警弹窗**：`AlertNotification.vue` 收到新预警时弹出桌面通知
- **WebSocket 自动重连**：指数退避策略，最多重试 10 次
- **心跳保活**：每 30 秒发送 ping
### 3.3 摄像头管理页面功能
- 统计卡片：摄像头总数、运行中、重连中、故障
- 搜索过滤：按 ID/URL 搜索、按状态过滤
- 摄像头操作：启动/停止/配置/移除
- 批量操作：全部启动/全部停止
- 添加/编辑弹窗：配置 RTSP URL、检测模型、置信度/IOU 阈值、帧采样间隔
- 自动刷新：每 5 秒轮询状态
### 3.4 规则配置页面功能
- **LLM 状态面板**：
- Provider/模型/融合策略/触发阈值展示
- 今日调用次数/成功/失败/费用/预算使用率
- 最近错误率/熔断状态
- 紧急停用/重新启用/重置统计操作
- **规则列表**：
- 按规则名/描述搜索、按事件类型过滤
- 规则卡片：严重级别标签、事件类型、启停开关、编辑/删除
- 规则元数据：最低置信度、最小边界框面积、限定摄像头、必备标签
- **新增/编辑规则弹窗**：
- 规则名称、事件类型、严重级别
- 最低置信度滑块、最小边界框面积
- 限定摄像头 ID（多选）、必备标签（多选）
- 描述、启用开关
### 3.5 预警列表页面功能
- 统计卡片：预警总数、未读、严重预警、订阅状态
- 过滤工具栏：按严重级别/事件类型/摄像头 ID 过滤
- 预警卡片：
- 严重性色条（红/橙/蓝/灰/绿）
- 未读标记（绿色圆点）
- 事件类型、置信度、触发次数、规则名称
- 检测标签（含 track_id）
- **LLM 二次判断结果**：LLM 确认/否决标签、LLM 置信度、推理摘要
- 操作：全部标为已读、清空记录、单条删除
---
## 4. 完整 API 接口一览
### 4.1 检测接口
| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/detect/image` | 图片检测（支持所有模型） |
| `POST` | `/api/detect/video` | 视频检测（仅 YOLO 模型，主要面向打架斗殴） |
| `GET` | `/api/algorithms/config` | 获取算法配置选项 |
### 4.2 模型管理
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/models` | 获取可用模型列表 |
| `GET` | `/api/models/{model_id}` | 获取单个模型信息 |
| `POST` | `/api/models/{model_id}/load` | 加载指定模型 |
### 4.3 RTSP 流管理
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rtsp/streams` | 获取所有流状态 |
| `GET` | `/api/rtsp/streams/{stream_id}` | 获取单路流详情 |
| `POST` | `/api/rtsp/streams` | 添加新摄像头流 |
| `DELETE` | `/api/rtsp/streams/{stream_id}` | 移除摄像头流 |
| `POST` | `/api/rtsp/streams/{stream_id}/start` | 启动指定流 |
| `POST` | `/api/rtsp/streams/{stream_id}/stop` | 停止指定流 |
| `PUT` | `/api/rtsp/streams/{stream_id}/config` | 更新流检测配置 |
| `POST` | `/api/rtsp/start-all` | 启动全部流 |
| `POST` | `/api/rtsp/stop-all` | 停止全部流 |
| `GET` | `/api/rtsp/health` | 健康检查 |
### 4.4 规则配置
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rules` | 获取所有规则 |
| `GET` | `/api/rules/{name}` | 获取单条规则 |
| `POST` | `/api/rules` | 新增规则 |
| `PUT` | `/api/rules/{name}` | 更新规则 |
| `DELETE` | `/api/rules/{name}` | 删除规则 |
| `POST` | `/api/rules/reload` | 热重载规则 |
| `GET` | `/api/rules/_stats` | 规则统计 |
### 4.5 LLM 管理
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/llm/status` | LLM 运行状态 |
| `GET` | `/api/llm/cost` | 当前成本统计 |
| `GET` | `/api/llm/cost/history` | 历史成本趋势 |
| `GET` | `/api/llm/cost/records` | 最近调用记录 |
| `POST` | `/api/llm/disable` | 紧急停用 LLM |
| `POST` | `/api/llm/enable` | 重新启用 LLM |
| `POST` | `/api/llm/reset` | 重置统计与熔断 |
### 4.6 WebSocket
| 路径 | 说明 |
|------|------|
| `/ws/camera` | 摄像头实时视频流 |
| `/ws/alerts` | 预警事件实时推送（支持过滤订阅） |
### 4.7 系统
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/` | 服务信息 |
| `GET` | `/api/health` | 健康检查 |
---
## 5. 数据流全景
### 5.1 实时检测管道（RTSP → 预警）
```
RTSP 摄像头
│
▼
RTSPService (解码线程)
│
▼
FrameBuffer (环形缓冲区)
│
▼
StreamManager (检测调度)
│
├──▶ ModelService (YOLO/Paddle 推理)
│ │
│ ▼
│ DetectionAdapter (格式统一)
│ │
│ ▼
│ ByteTracker (目标跟踪, 分配 track_id)
│
▼
DetectionResult (统一检测结果)
│
▼
EventDecisionEngine (置信度过滤 + 类型映射)
│
▼
CandidateEvent[]
│
├──▶ AlertRuleEngine (规则匹配)
│ │
│ ▼
│ AlertEvent[] (规则过滤后)
│
├──▶ MultiFrameAccumulator (多帧累积)
│ │
│ ▼
│ LLMTrigger (触发判定)
│ │
│ ▼ (触发时)
│ LLMAnalysisService (大模型分析)
│ │
│ ▼
│ ResultFusion (YOLO + LLM 融合)
│ │
│ ▼
│ LLMCostTracker (成本追踪 + 熔断)
│
▼
EventAggregator (去重 + 空间合并 + 置信度融合)
│
▼
AlertEvent (最终预警)
│
├──▶ AlertPublisher → MQTT (外部系统)
├──▶ AlertBroadcaster → WebSocket (前端实时推送)
└──▶ 前端 AlertList / 桌面通知
```
### 5.2 图片/视频检测管道（上传 → 结果）
```
用户上传图片/视频
│
▼
POST /api/detect/image 或 /api/detect/video
│
▼
DetectionService
│
├──▶ ModelService (推理)
│ │
│ ▼
│ 检测结果 + 标注图/视频
│
├──▶ 事件管道 (同上，但仅图片检测触发)
│
▼
返回检测结果 (含标注图/视频 URL/关键帧)
```
---
## 6. 测试覆盖
项目包含完整的单元测试和集成测试：
### 6.1 单元测试
| 测试文件 | 覆盖模块 |
|----------|---------|
| `test_decision_engine.py` | 事件决策引擎 |
| `test_rule_engine.py` | 预警规则引擎 |
| `test_aggregator.py` / `test_aggregator_v2.py` | 事件聚合器 |
| `test_event_schemas.py` | 事件数据模型 |
| `test_detection_adapter.py` | 检测适配器 |
| `test_frame_accumulator.py` | 多帧累积器 |
| `test_llm_trigger.py` | LLM 触发器 |
| `test_llm_analysis_service.py` | LLM 分析服务 |
| `test_llm_cost_tracker.py` | LLM 成本追踪 |
| `test_result_fusion.py` | 结果融合器 |
| `test_rtsp_service.py` | RTSP 流服务 |
| `test_stream_manager.py` | 多路流管理器 |
| `test_tracking_service.py` | 目标跟踪 |
| `test_mqtt_service.py` | MQTT 服务 |
| `test_alert_publisher.py` | 预警发布器 |
| `test_frame_buffer.py` | 帧缓冲区 |
| `test_settings.py` | 配置管理 |
### 6.2 集成测试
| 测试文件 | 覆盖场景 |
|----------|---------|
| `test_detect_image_integration.py` | 图片检测端到端 |
| `test_detection_service_pipeline.py` | 检测服务管道 |
| `test_event_pipeline.py` | 事件管道端到端 |
---
## 7. 设计文档对照：已实现 vs 待实现
### 7.1 `event-judgment-algorithm-architecture.md` 对照
| 设计模块 | 设计内容 | 实现状态 | 说明 |
|----------|---------|---------|------|
| 事件决策引擎 | 置信度评估、场景识别、初步筛选 | ✅ 已实现 | 置信度过滤 + 类型映射，场景识别暂未实现 |
| 预警规则引擎 | 规则匹配、时间窗口、区域规则 | ✅ 已实现 | 置信度/面积/来源/标签规则已实现，时间窗口规则暂未实现 |
| 事件聚合器 | 去重合并、时间窗口、事件关联 | ✅ 已实现 | 时间窗口去重 + 空间合并 + 置信度融合 |
| 大模型触发器 | 智能决策、优先级排序、并发控制 | ✅ 已实现 | 多帧累积 + 冷却 + 严重性旁路 |
| LLM 视觉分析 | 图像理解、场景分析、推理验证 | ✅ 已实现 | OpenAI 兼容协议 + Mock Provider |
| 结果融合 | 置信融合、决策输出 | ✅ 已实现 | weighted/conservative/llm_priority 三策略 |
| 严重性评估器 | 风险等级、优先级计算 | ⚠️ 部分实现 | 规则引擎指定严重性，动态评估暂未实现 |
| 事件格式化 | 标准格式、元数据填充 | ✅ 已实现 | AlertEvent 统一格式 |
| MQTT 发布 | 消息发布、QoS 管理 | ✅ 已实现 | AlertPublisher + MQTTService |
### 7.2 `project-integration-plan.md` 对照
| 设计模块 | 设计内容 | 实现状态 | 说明 |
|----------|---------|---------|------|
| RTSP 流接入 | 解码、缓冲、重连 | ✅ 已实现 | RTSPService + FrameBuffer + 指数退避重连 |
| 多路流管理 | 调度、状态监控 | ✅ 已实现 | StreamManager + REST API |
| MQTT 预警系统 | 消息发布、QoS、主题设计 | ✅ 已实现 | MQTTService + AlertPublisher |
| AI 模型扩展 | 车辆/打架检测 | ✅ 已实现 | fight_detection + vehicle_detection_paddle |
| 大模型二次判断 | 多模型策略、Prompt 设计 | ✅ 已实现 | Provider 抽象 + 结构化输出解析 |
| 触发条件 | 置信度区间、去重窗口、并发限制 | ✅ 已实现 | LLMTrigger + MultiFrameAccumulator |
| 成本控制 | 日预算、熔断降级 | ✅ 已实现 | LLMCostTracker (CLOSED/OPEN/HALF_OPEN) |
| WebSocket 实时推送 | 预警订阅、过滤 | ✅ 已实现 | AlertBroadcaster + 前端 WebSocket 客户端 |
| 消息持久化 | 存储与消费确认 | ❌ 未实现 | 当前仅内存存储，未做持久化 |
| 人脸识别/属性分析 | InsightFace / PaddleFace | ❌ 未实现 | — |
| 越界/入侵检测 | 虚拟围栏算法 | ❌ 未实现 | — |
| 异常行为检测 | 自定义行为分析 | ⚠️ 部分实现 | 已有静止/徘徊检测，通用异常行为未实现 |
---
## 8. 项目文件结构
```
jc-video-recognize/
├── apps/
│ ├── web/ # 前端 (Vue 3 + Vite 5)
│ │ └── src/
│ │ ├── api/detection.js # API 请求封装 (检测/摄像头/规则/LLM)
│ │ ├── components/
│ │ │ ├── AlertNotification.vue # 全局预警弹窗
│ │ │ ├── AlgorithmConfig.vue # 行为分析算法配置
│ │ │ ├── DetectionConfig.vue # 检测参数配置
│ │ │ ├── ImageDetection.vue # 图片检测模块
│ │ │ └── VideoDetection.vue # 视频/摄像头检测模块
│ │ ├── layouts/MainLayout.vue # 主布局 (侧边栏+顶栏+预警铃铛)
│ │ ├── router/index.js # 路由 (4 个页面)
│ │ ├── services/mqtt.client.js # WebSocket 预警客户端
│ │ ├── stores/alertStore.js # Pinia 预警状态管理
│ │ └── views/
│ │ ├── Home.vue # 模型检测首页
│ │ ├── CameraManagement.vue # 摄像头管理
│ │ ├── RuleConfiguration.vue # 规则配置 + LLM 面板
│ │ └── AlertList.vue # 预警列表
│ └── server/ # 后端 (FastAPI)
│ ├── main.py # 服务入口 + 生命周期管理
│ ├── api/
│ │ ├── detection.py # 检测 API
│ │ ├── models.py # 模型管理 API
│ │ ├── rtsp.py # RTSP 流管理 API
│ │ ├── alerts.py # 预警 WebSocket API
│ │ ├── rules.py # 规则配置 API
│ │ └── llm.py # LLM 管理 API
│ ├── config/rules/ # 规则 YAML 配置
│ │ ├── fire.yaml
│ │ ├── smoking.yaml
│ │ ├── loitering.yaml
│ │ ├── fight.yaml
│ │ └── vehicle.yaml
│ ├── core/settings.py # 统一配置管理 (14 个子配置)
│ ├── models/
│ │ ├── event_schemas.py # 统一事件数据契约
│ │ └── schemas.py # 检测请求/响应模型
│ ├── services/
│ │ ├── detection_service.py # 检测核心 (管道编排)
│ │ ├── model_service.py # 模型加载与管理
│ │ ├── rtsp_service.py # RTSP 流接入
│ │ ├── stream_manager.py # 多路流调度
│ │ ├── frame_buffer.py # 帧缓冲区
│ │ ├── mqtt_service.py # MQTT 客户端
│ │ ├── alert_publisher.py # 预警发布器
│ │ ├── tracking_service.py # ByteTrack 目标跟踪
│ │ ├── llm_analysis_service.py # LLM 分析服务
│ │ ├── llm_cost_tracker.py # LLM 成本追踪 + 熔断
│ │ ├── result_fusion.py # 结果融合器
│ │ ├── loitering_service.py # 徘徊检测服务
│ │ ├── camera_service.py # 摄像头 WebSocket 服务
│ │ ├── action_detection_service.py # Docker 行为识别适配器
│ │ ├── paddle_detection_service.py # PaddlePaddle 抽烟检测适配器
│ │ ├── vehicle_detection_service.py # 车辆/违停检测适配器
│ │ ├── adapters/detection_adapter.py # 检测结果格式统一适配器
│ │ └── event/
│ │ ├── decision_engine.py # 事件决策引擎
│ │ ├── rule_engine.py # 预警规则引擎
│ │ ├── aggregator.py # 事件聚合器
│ │ ├── frame_accumulator.py # 多帧累积器
│ │ └── llm_trigger.py # LLM 触发器
│ └── tests/ # 测试 (17 单元 + 3 集成)
├── models/ # AI 模型文件
│ ├── fire_detection/ # YOLOv10 火灾检测
│ ├── helmet_detection/ # YOLOv8 安全帽检测
│ ├── crowd_detection/ # YOLOv8 人群检测
│ ├── smoking_detection/ # YOLOv8 抽烟检测
│ ├── smoking_detection_paddle/ # PaddlePaddle 抽烟检测
│ ├── loitering_detection/ # YOLOv8 徒步检测
│ ├── fight_detection/ # YOLOv8 打架斗殴检测
│ └── vehicle_detection_paddle/ # PaddlePaddle 车辆检测
├── docs/ # 项目文档
└── docker/ # Docker 部署配置
```
---
## 9. 待完善功能
基于两份设计文档的对照，以下功能尚未实现：
| 优先级 | 功能 | 来源文档 | 说明 |
|--------|------|---------|------|
| 高 | 预警事件持久化存储 | project-integration-plan | 当前仅内存存储，重启后丢失 |
| 高 | 时间窗口规则 | event-judgment-algorithm | 规则引擎暂不支持工作时间/非工作时间过滤 |
| 中 | 场景识别 | event-judgment-algorithm | 决策引擎暂未实现室内/室外/禁区场景分类 |
| 中 | 动态严重性评估 | event-judgment-algorithm | 当前严重性由规则静态指定，未实现动态计算 |
| 中 | 越界/入侵检测 | project-integration-plan | 虚拟围栏算法未实现 |
| 中 | 人脸识别/属性分析 | project-integration-plan | InsightFace / PaddleFace 未集成 |
| 低 | 区域规则 | event-judgment-algorithm | 规则引擎暂不支持区域（禁区/普通区域）过滤 |
| 低 | 组合规则 | event-judgment-algorithm | 多条件组合规则未实现 |
| 低 | 消息消费确认机制 | project-integration-plan | MQTT 消息持久化与消费确认未实现 |
| 低 | 预警消息管理后台 | project-integration-plan | 消息查询与统计分析页面未实现 |