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 scripts/setup.sh

或手动安装：

# 安装根依赖
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 ../..

开发模式

在项目根目录执行：

# 同时启动前后端（需先激活后端虚拟环境）
pnpm dev

# 只启动前端
pnpm dev:web

# 只启动后端（需先激活虚拟环境）
cd apps/server
source venv/bin/activate  # macOS/Linux
# 或 venv\Scripts\activate  # Windows
pnpm dev:server

访问地址：

功能特性

检测模型

火灾检测 - 基于YOLOv10的火焰和烟雾检测
安全帽检测 - 基于YOLOv8的工地安全检测
人群检测 - 基于YOLOv8的人群聚集检测
抽烟检测 - 基于YOLOv8的吸烟行为检测

输入方式

图片上传检测
摄像头实时检测

核心功能

可拖拽布局配置
实时WebSocket视频流
检测结果可视化
多模型切换
置信度阈值调整

项目脚本

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 模型整合在现有的视频检测平台中，提供补充的检测能力。

系统架构层级

前端层
- 通过 Web 界面接收用户输入
- 调用后端 API 进行图像检测
- 展示检测结果和实时视频流
后端服务层
- FastAPI 提供 REST API 接口
- WebSocket 支持实时视频流传输
- 路由不同检测请求到对应的模型服务
检测服务层
- YOLO 检测服务：处理火灾、安全帽、人群、徘徊等检测任务
- PaddlePaddle 检测服务：专门处理抽烟检测任务
- 统一的检测结果格式输出
推理引擎层
- YOLO 推理引擎：基于 Ultralytics 库
- PaddlePaddle 推理引擎：基于 PaddleDetection 库
- 各自独立的模型加载和推理逻辑

调用流程

前端发起检测请求 → 后端 API 接收 → 路由到对应检测服务 → 推理引擎处理 → 返回检测结果 → 前端展示

模型选择策略

系统根据检测类型自动选择合适的推理引擎
抽烟检测优先使用 PaddlePaddle 模型（精度更高）
其他检测使用 YOLO 模型（速度更快）
支持配置切换模型类型

依赖关系说明

PaddlePaddle 整合依赖于多个组件的协同工作。

核心依赖组件

PaddlePaddle 框架
- 版本要求：3.0.0
- 提供深度学习推理基础能力
- 支持 CPU 推理（本地部署环境）
PaddleDetection 库
- 来源：GitHub PaddlePaddle/PaddleDetection release-2.9
- 提供目标检测专用功能
- 包含预处理、推理、后处理和可视化模块
FastAPI 服务
- 主后端框架，提供 Web 服务
- 整合 PaddlePaddle 检测服务
- 处理 HTTP 请求和 WebSocket 连接
虚拟环境
- 统一使用 apps/server/venv
- 包含所有必需的 Python 依赖
- 隔离运行环境，避免版本冲突

依赖链路

用户请求 → FastAPI → PaddleDetection 服务 → PaddlePaddle 框架 → 模型推理 → 结果返回

环境变量依赖

FLAGS_enable_pir_api=0：禁用新版 PIR API，确保与旧模型兼容
Python 路径配置：确保正确加载 PaddleDetection 模块

系统资源依赖

CPU：支持多线程推理
内存：最小要求 2GB，推荐 4GB 以上
磁盘空间：模型文件约 30MB，推理代码约 50MB

与其他组件的关系

与 YOLO 检测服务并列运行，互不干扰
共享 FastAPI 的路由和中间件
使用相同的日志系统和错误处理机制
统一的模型管理目录结构

环境设置

运行环境设置脚本验证/安装 PaddlePaddle：

bash scripts/setup-paddlepaddle.sh

如果是首次设置，按照脚本提示完成以下步骤：
- 下载 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 详细操作指南

首次设置完整流程

下载 PaddleDetection 代码

# 进入项目根目录
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

复制推理代码

# 复制必要的推理文件到项目中
cp -r /tmp/PaddleDetection-release-2.9/deploy/python/* third-party/paddle-inference/

# 删除临时文件
rm -rf /tmp/PaddleDetection-release-2.9

安装 PaddlePaddle 依赖

# 进入服务器目录
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

放置模型文件

# 确保模型文件在正确位置
ls -la models/smoking_detection_paddle/
# 应该包含：model.pdmodel, model.pdiparams, infer_cfg.yml

验证安装

# 运行验证脚本
bash scripts/setup-paddlepaddle.sh

日常维护操作

更新 PaddlePaddle 推理代码

# 下载新版推理代码
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

更新模型文件

# 停止服务器
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

更新依赖版本

# 进入服务器虚拟环境
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：模型加载失败

# 检查模型文件完整性
ls -la models/smoking_detection_paddle/

# 检查必要文件
model.pdmodel    # 模型结构
model.pdiparams  # 模型参数  
infer_cfg.yml   # 推理配置

# 验证文件大小（应该 > 30MB）
du -sh models/smoking_detection_paddle/

问题 2：PaddlePaddle 导入失败

# 检查 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：推理速度慢

# 检查 CPU 使用情况
top -p $(pgrep -f python)

# 检查内存使用情况
free -h

# 优化建议：
# 1. 减少批处理大小
# 2. 使用更小的模型（如果精度允许）
# 3. 启用 GPU 加速（如果有 NVIDIA GPU）

性能监控

实时监控推理时间

# 查看服务器日志中的推理时间
tail -f apps/server/logs/*.log | grep "推理时间"

性能基准测试

# 使用测试图像进行基准测试
curl -X POST "http://localhost:8000/api/detect" \
  -F "image=@test_image.jpg" \
  -F "model=smoking_detection_paddle"

系统资源监控

# CPU 使用率
mpstat 1

# 内存使用情况  
free -m -s 1

# 磁盘 I/O
iostat -x 1

Git 管理

排除文件

# .gitignore 中已配置以下排除
models/*/                  # 模型文件
third-party/paddle-inference/ # 第三方代码
apps/server/venv/         # 虚拟环境

版本控制策略

✅ 只版本控制代码文件
❌ 不版本控制模型文件（太大）
❌ 不版本控制第三方库
✅ 使用 Git LFS 如果必须版本控制大文件

协作建议

团队协作流程

每个成员独立运行 setup-paddlepaddle.sh
在 README 中记录使用的 PaddlePaddle 版本
定期同步模型文件和配置更新
使用统一的环境变量配置

许可证

MIT

Languages

Python 75.9%

Vue 20.6%

Shell 2.4%

JavaScript 0.7%

TypeScript 0.3%

README.md Unescape Escape

jc-video-web

项目架构

技术栈

前端

后端