40 KiB
40 KiB
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 | 消息查询与统计分析页面未实现 |