# jc-video-web 视频模型检测平台 - 基于YOLO的实时视频检测系统 ## 项目架构 ``` jc-video-web/ ├── apps/ │ ├── web/ # 前端应用 (Vue 3 + Vite) │ └── server/ # 后端服务 (FastAPI) ├── packages/ │ └── shared-types/ # 前后端共享类型定义 ├── models/ # AI模型文件 │ ├── fire_detection/ # 火灾检测模型 │ ├── helmet_detection/ # 安全帽检测模型 │ ├── crowd_detection/ # 人群检测模型 │ └── smoking_detection/# 抽烟检测模型 ├── scripts/ # 构建/开发脚本 └── docker/ # Docker配置 ``` ## 技术栈 ### 前端 - **框架**: Vue 3 + Composition API - **构建工具**: Vite 5 - **UI组件库**: Element Plus - **状态管理**: Pinia - **路由**: Vue Router 4 - **HTTP客户端**: Axios ### 后端 - **框架**: FastAPI - **服务器**: Uvicorn - **AI推理**: Ultralytics (YOLO) - **图像处理**: OpenCV, Pillow - **实时通信**: WebSocket ## 快速开始 ### 环境要求 - Node.js >= 18 - Python >= 3.9 - pnpm >= 9.0 ### 安装依赖 ```bash # 运行初始化脚本 bash scripts/setup.sh ``` 或手动安装： ```bash # 安装根依赖 pnpm install # 安装前端依赖 cd apps/web pnpm install cd ../.. # 创建 Python 虚拟环境并安装依赖 cd apps/server python3 -m venv venv source venv/bin/activate pip install -r requirements.txt cd ../.. ``` ### 开发模式 在项目根目录执行： ```bash # 同时启动前后端（需先激活后端虚拟环境） pnpm dev # 只启动前端 pnpm dev:web # 只启动后端（需先激活虚拟环境） cd apps/server source venv/bin/activate # macOS/Linux # 或 venv\Scripts\activate # Windows pnpm dev:server ``` 访问地址： - 前端: http://localhost:5173 - 后端: http://localhost:8000 - API文档: http://localhost:8000/docs ## 功能特性 ### 检测模型 1. **火灾检测** - 基于YOLOv10的火焰和烟雾检测 2. **安全帽检测** - 基于YOLOv8的工地安全检测 3. **人群检测** - 基于YOLOv8的人群聚集检测 4. **抽烟检测** - 基于YOLOv8的吸烟行为检测 ### 输入方式 - 图片上传检测 - 摄像头实时检测 ### 核心功能 - 可拖拽布局配置 - 实时WebSocket视频流 - 检测结果可视化 - 多模型切换 - 置信度阈值调整 ## 项目脚本 ```bash pnpm dev # 启动开发服务器 pnpm build # 构建生产版本 pnpm build:web # 只构建前端 pnpm test # 运行测试 pnpm lint # 代码检查 pnpm clean # 清理构建产物 ``` ## 模型配置 ### 统一模型管理 所有模型文件统一存放在 `models/` 目录下： ``` models/ ├── smoking_detection/ # YOLOv8 抽烟检测 ├── smoking_detection_paddle/ # PaddlePaddle PP-YOLOE-s 抽烟检测 ├── fire_detection/ # YOLOv10 火灾检测 ├── helmet_detection/ # YOLOv8 安全帽检测 ├── crowd_detection/ # YOLOv8 人群检测 └── loitering_detection/ # YOLOv8 徘徊检测 ``` ### 模型类型说明 **YOLO 模型：** - 使用 `yolov8n.pt` 或 `yolov10n.pt` 格式 - 通过 `detection_service.py` 自动加载 - 支持：抽烟检测、火灾检测、安全帽检测、人群检测、徘徊检测 **PaddlePaddle 模型：** - 使用 `model.pdmodel` + `model.pdiparams` 格式 - 通过 `paddle_detection_service.py` 加载 - 支持：抽烟检测（PP-YOLOE-s） ### 模型文件格式 **YOLO 模型：** ``` smoking_detection/ └── yolov8n.pt # YOLO 模型文件 ``` **PaddlePaddle 模型：** ``` smoking_detection_paddle/ ├── model.pdmodel # 模型结构 ├── model.pdiparams # 模型参数 └── infer_cfg.yml # 推理配置 ``` ## PaddlePaddle 环境配置 ### 本地 PaddlePaddle 部署 项目使用本地 PaddlePaddle 进行抽烟检测推理（不使用 Docker），以获得更好的性能。 ### 整合架构说明 PaddlePaddle 模型整合在现有的视频检测平台中，提供补充的检测能力。 **系统架构层级** 1. **前端层** - 通过 Web 界面接收用户输入 - 调用后端 API 进行图像检测 - 展示检测结果和实时视频流 2. **后端服务层** - FastAPI 提供 REST API 接口 - WebSocket 支持实时视频流传输 - 路由不同检测请求到对应的模型服务 3. **检测服务层** - YOLO 检测服务：处理火灾、安全帽、人群、徘徊等检测任务 - PaddlePaddle 检测服务：专门处理抽烟检测任务 - 统一的检测结果格式输出 4. **推理引擎层** - YOLO 推理引擎：基于 Ultralytics 库 - PaddlePaddle 推理引擎：基于 PaddleDetection 库 - 各自独立的模型加载和推理逻辑 **调用流程** 前端发起检测请求 → 后端 API 接收 → 路由到对应检测服务 → 推理引擎处理 → 返回检测结果 → 前端展示 **模型选择策略** - 系统根据检测类型自动选择合适的推理引擎 - 抽烟检测优先使用 PaddlePaddle 模型（精度更高） - 其他检测使用 YOLO 模型（速度更快） - 支持配置切换模型类型 ### 依赖关系说明 PaddlePaddle 整合依赖于多个组件的协同工作。 **核心依赖组件** 1. **PaddlePaddle 框架** - 版本要求：3.0.0 - 提供深度学习推理基础能力 - 支持 CPU 推理（本地部署环境） 2. **PaddleDetection 库** - 来源：GitHub PaddlePaddle/PaddleDetection release-2.9 - 提供目标检测专用功能 - 包含预处理、推理、后处理和可视化模块 3. **FastAPI 服务** - 主后端框架，提供 Web 服务 - 整合 PaddlePaddle 检测服务 - 处理 HTTP 请求和 WebSocket 连接 4. **虚拟环境** - 统一使用 `apps/server/venv` - 包含所有必需的 Python 依赖 - 隔离运行环境，避免版本冲突 **依赖链路** 用户请求 → FastAPI → PaddleDetection 服务 → PaddlePaddle 框架 → 模型推理 → 结果返回 **环境变量依赖** - `FLAGS_enable_pir_api=0`：禁用新版 PIR API，确保与旧模型兼容 - Python 路径配置：确保正确加载 PaddleDetection 模块 **系统资源依赖** - CPU：支持多线程推理 - 内存：最小要求 2GB，推荐 4GB 以上 - 磁盘空间：模型文件约 30MB，推理代码约 50MB **与其他组件的关系** - 与 YOLO 检测服务并列运行，互不干扰 - 共享 FastAPI 的路由和中间件 - 使用相同的日志系统和错误处理机制 - 统一的模型管理目录结构 ### 环境设置 1. 运行环境设置脚本验证/安装 PaddlePaddle： ```bash bash scripts/setup-paddlepaddle.sh ``` 2. 如果是首次设置，按照脚本提示完成以下步骤： - 下载 PaddleDetection release-2.9 到 `PaddlePaddle/PaddleDetection-release-2.9/` - 安装 PaddlePaddle 和依赖到服务器虚拟环境 - 将模型文件复制到 `models/smoking_detection_paddle/` ### 目录结构 ``` third-party/paddle-inference/ # PaddleDetection 推理代码 ├── infer.py # 推理引擎 ├── preprocess.py # 图像预处理 ├── utils.py # 工具函数 └── visualize.py # 结果可视化 models/smoking_detection_paddle/ # PaddlePaddle 模型文件 ├── model.pdmodel # 模型结构 ├── model.pdiparams # 模型参数 └── infer_cfg.yml # 推理配置 ``` ### 性能优化 本地部署相比 Docker 性能提升： - 推理时间：3-4秒 → 0.123秒（提升 ~30 倍） - 内存占用：~3GB → ~0.5GB（减少 83%） - 启动时间：~10秒 → 即时 - CPU 利用率：提升 50% ### PaddlePaddle 详细操作指南 #### 首次设置完整流程 1. **下载 PaddleDetection 代码** ```bash # 进入项目根目录 cd jc-video-recognize # 下载 PaddleDetection release-2.9 git clone -b release/2.9 https://github.com/PaddlePaddle/PaddleDetection.git /tmp/PaddleDetection-release-2.9 # 或手动下载并解压 # 从 https://github.com/PaddlePaddle/PaddleDetection/releases/tag/release%2F2.9 ``` 2. **复制推理代码** ```bash # 复制必要的推理文件到项目中 cp -r /tmp/PaddleDetection-release-2.9/deploy/python/* third-party/paddle-inference/ # 删除临时文件 rm -rf /tmp/PaddleDetection-release-2.9 ``` 3. **安装 PaddlePaddle 依赖** ```bash # 进入服务器目录 cd apps/server # 激活虚拟环境 source venv/bin/activate # 安装 PaddlePaddle 和相关依赖 pip install paddlepaddle==3.0.0 pip install 'numpy==1.26.4' 'opencv-python==4.7.0.72' pip install imgaug==0.4.0 ``` 4. **放置模型文件** ```bash # 确保模型文件在正确位置 ls -la models/smoking_detection_paddle/ # 应该包含：model.pdmodel, model.pdiparams, infer_cfg.yml ``` 5. **验证安装** ```bash # 运行验证脚本 bash scripts/setup-paddlepaddle.sh ``` #### 日常维护操作 **更新 PaddlePaddle 推理代码** ```bash # 下载新版推理代码 cd /tmp git clone -b release/2.9 https://github.com/PaddlePaddle/PaddleDetection.git PaddleDetection-release-2.9 # 备份现有代码 cd ../jc-video-recognize cp -r third-party/paddle-inference third-party/paddle-inference.backup # 更新推理代码 cp -r /tmp/PaddleDetection-release-2.9/deploy/python/* third-party/paddle-inference/ # 测试新代码 pnpm dev:server # 如果测试失败，恢复备份 # rm -rf third-party/paddle-inference # mv third-party/paddle-inference.backup third-party/paddle-inference ``` **更新模型文件** ```bash # 停止服务器 pkill -f "python.*main.py" # 备份现有模型 cp -r models/smoking_detection_paddle models/smoking_detection_paddle.backup # 放置新模型 cp /path/to/new/model.pdmodel models/smoking_detection_paddle/ cp /path/to/new/model.pdiparams models/smoking_detection_paddle/ cp /path/to/new/infer_cfg.yml models/smoking_detection_paddle/ # 重启服务器验证 cd apps/server && ./start_server_with_env.sh ``` **更新依赖版本** ```bash # 进入服务器虚拟环境 cd apps/server source venv/bin/activate # 升级 PaddlePaddle pip install --upgrade paddlepaddle==3.0.0 # 升级其他依赖 pip install --upgrade 'numpy==1.26.4' 'opencv-python==4.7.0.72' pip install --upgrade imgaug==0.4.0 # 测试新版本 python -c "import paddle; print(paddle.__version__)" ``` #### 故障排查指南 **问题 1：模型加载失败** ```bash # 检查模型文件完整性 ls -la models/smoking_detection_paddle/ # 检查必要文件 model.pdmodel # 模型结构 model.pdiparams # 模型参数 infer_cfg.yml # 推理配置 # 验证文件大小（应该 > 30MB） du -sh models/smoking_detection_paddle/ ``` **问题 2：PaddlePaddle 导入失败** ```bash # 检查 PaddlePaddle 安装 source apps/server/venv/bin/activate pip list | grep paddle # 重新安装 PaddlePaddle pip install paddlepaddle==3.0.0 --force-reinstall # 检查环境变量 echo $FLAGS_enable_pir_api # 应该是 0 ``` **问题 3：推理速度慢** ```bash # 检查 CPU 使用情况 top -p $(pgrep -f python) # 检查内存使用情况 free -h # 优化建议： # 1. 减少批处理大小 # 2. 使用更小的模型（如果精度允许） # 3. 启用 GPU 加速（如果有 NVIDIA GPU） ``` #### 性能监控 **实时监控推理时间** ```bash # 查看服务器日志中的推理时间 tail -f apps/server/logs/*.log | grep "推理时间" ``` **性能基准测试** ```bash # 使用测试图像进行基准测试 curl -X POST "http://localhost:8000/api/detect" \ -F "image=@test_image.jpg" \ -F "model=smoking_detection_paddle" ``` **系统资源监控** ```bash # CPU 使用率 mpstat 1 # 内存使用情况 free -m -s 1 # 磁盘 I/O iostat -x 1 ``` #### Git 管理 **排除文件** ```bash # .gitignore 中已配置以下排除 models/*/ # 模型文件 third-party/paddle-inference/ # 第三方代码 apps/server/venv/ # 虚拟环境 ``` **版本控制策略** - ✅ 只版本控制代码文件 - ❌ 不版本控制模型文件（太大） - ❌ 不版本控制第三方库 - ✅ 使用 Git LFS 如果必须版本控制大文件 #### 协作建议 **团队协作流程** 1. 每个成员独立运行 `setup-paddlepaddle.sh` 2. 在 README 中记录使用的 PaddlePaddle 版本 3. 定期同步模型文件和配置更新 4. 使用统一的环境变量配置 ## 许可证 [MIT](LICENSE)