From 0158b41712b8677e6ddcb0d05f83e203b001fed5 Mon Sep 17 00:00:00 2001 From: wuzhuorong <973204353@qq.com> Date: Tue, 16 Jun 2026 14:58:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=80=BB=E7=BB=93=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=8E=B0=E7=8A=B6=E4=B8=8E=E5=8A=9F=E8=83=BD=E6=A2=B3=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/项目现状与功能梳理.md | 821 +++++++++++++++++++++++++++++++++++++ 1 file changed, 821 insertions(+) create mode 100644 docs/项目现状与功能梳理.md diff --git a/docs/项目现状与功能梳理.md b/docs/项目现状与功能梳理.md new file mode 100644 index 0000000..52fefc8 --- /dev/null +++ b/docs/项目现状与功能梳理.md @@ -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 | 消息查询与统计分析页面未实现 |