feat: 新增PaddlePaddle检测支持，重构项目架构
1. 新增concurrently依赖用于并行启动服务 2. 新增服务器启动脚本统一管理环境变量和虚拟环境 3. 新增PaddlePaddle推理引擎和配套工具代码 4. 新增抽烟检测Paddle模型支持，完善模型管理 5. 重构开发启动脚本，优化开发体验 6. 更新.gitignore排除不必要的外部目录和缓存 7. 完善文档说明，新增PaddlePaddle部署指南
This commit is contained in:
wwh
373
README.md
373
README.md
@@ -125,7 +125,378 @@ pnpm clean # 清理构建产物
|
||||
|
||||
## 模型配置
|
||||
|
||||
模型文件存放在 `models/` 目录下，需要在 `apps/server/services/model_service.py` 中配置模型路径。
|
||||
### 统一模型管理
|
||||
|
||||
所有模型文件统一存放在 `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. 使用统一的环境变量配置
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user