e97bd503ec
1. 新增concurrently依赖用于并行启动服务 2. 新增服务器启动脚本统一管理环境变量和虚拟环境 3. 新增PaddlePaddle推理引擎和配套工具代码 4. 新增抽烟检测Paddle模型支持，完善模型管理 5. 重构开发启动脚本，优化开发体验 6. 更新.gitignore排除不必要的外部目录和缓存 7. 完善文档说明，新增PaddlePaddle部署指南
Third-Party Components
此目录包含项目所需的第三方依赖库和组件。
目录结构
third-party/
└── paddle-inference/ # PaddleDetection 推理组件库
├── infer.py # PaddleDetection 推理引擎
├── preprocess.py # 图像预处理
├── utils.py # 工具函数
├── visualize.py # 结果可视化
└── output_inference/ # 模型文件目录（空，已移到 models/）
models/ # 统一的模型文件目录
├── smoking_detection/ # YOLOv8 抽烟检测
├── smoking_detection_paddle/ # PaddlePaddle PP-YOLOE-s 抽烟检测
├── fire_detection/ # YOLOv10 火灾检测
├── helmet_detection/ # YOLOv8 安全帽检测
├── crowd_detection/ # YOLOv8 人群检测
└── loitering_detection/ # YOLOv8 徘徊检测
PaddlePaddle 推理组件
用途
- 提供 PaddlePaddle 模型的推理功能
- 支持 PP-YOLOE+ 模型格式
- 提供预处理、可视化等工具
依赖安装
在服务器虚拟环境中安装以下依赖：
# 进入服务器目录
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
模型管理
统一管理
所有模型文件统一存储在 models/ 目录：
YOLO 模型：
smoking_detection/- YOLOv8 抽烟检测fire_detection/- YOLOv10 火灾检测helmet_detection/- YOLOv8 安全帽检测crowd_detection/- YOLOv8 人群检测loitering_detection/- YOLOv8 徘徊检测
PaddlePaddle 模型：
smoking_detection_paddle/- PP-YOLOE-s 抽烟检测
模型文件格式
YOLO 模型：
smoking_detection/
└── yolov8n.pt # YOLO 模型文件
PaddlePaddle 模型：
smoking_detection_paddle/
├── model.pdmodel # 模型结构
├── model.pdiparams # 模型参数
└── infer_cfg.yml # 推理配置
使用方式
YOLO 模型
from services.detection_service import DetectionService
# 自动加载 models/ 目录中的 YOLO 模型
PaddlePaddle 模型
from services.paddle_detection_service import SmokingDetectionModel
# 自动加载 models/smoking_detection_paddle/ 目录
性能优化
Apple Silicon 优化
- 本地部署相比 Docker 性能提升 30 倍
- 推理时间：3-4秒 → 0.123秒
- 内存占用：~3GB → ~0.5GB
环境变量
必须在 Python 进程启动前设置：
export FLAGS_enable_pir_api=0
更新和维护
模型更新
要更新模型，将新文件复制到对应的 models/ 子目录：
models/smoking_detection/ # YOLO 模型
models/smoking_detection_paddle/ # PaddlePaddle 模型
推理代码更新
如需更新 PaddleDetection 推理代码，从官方仓库复制：
PaddleDetection-release-2.9/deploy/python/* → third-party/paddle-inference/
安全更新流程：
# 1. 下载新版代码
cd /tmp
git clone -b release/2.9 https://github.com/PaddlePaddle/PaddleDetection.git
# 2. 备份现有代码
cd ../../jc-video-recognize
cp -r third-party/paddle-inference third-party/paddle-inference.backup
# 3. 更新推理代码
cp -r /tmp/PaddleDetection-release-2.9/deploy/python/* third-party/paddle-inference/
# 4. 测试验证
cd apps/server
./start_server_with_env.sh
# 5. 如果失败，恢复备份
# rm -rf third-party/paddle-inference
# mv third-party/paddle-inference.backup third-party/paddle-inference
故障排查
常见问题
1. 模型加载失败
# 检查模型文件完整性
ls -la ../models/smoking_detection_paddle/
# 应该包含以下文件：
model.pdmodel # 模型结构（约1MB）
model.pdiparams # 模型参数（约30MB）
infer_cfg.yml # 推理配置（约1KB）
# 检查文件权限
chmod 644 ../models/smoking_detection_paddle/*
2. PaddlePaddle 导入失败
# 检查 PaddlePaddle 安装
source ../apps/server/venv/bin/activate
pip list | grep paddle
# 检查环境变量
echo $FLAGS_enable_pir_api
# 应该输出：0
# 重新安装 PaddlePaddle
pip install paddlepaddle==3.0.0 --force-reinstall
3. 推理速度慢
# 检查 CPU 使用情况
top -p $(pgrep -f python)
# 检查内存使用情况
free -h
# 性能优化建议：
# 1. 首次加载2秒是正常的（模型加载）
# 2. 后续推理0.2秒是优秀的
# 3. 如果推理时间 > 1秒，考虑优化模型大小
性能监控
实时推理时间监控
# 查看推理日志
tail -f ../apps/server/logs/*.log | grep "推理时间"
系统资源监控
# CPU 使用率
mpstat 1
# 内存使用情况
free -m -s 1
# 磁盘 I/O
iostat -x 1
协作指南
新成员上手流程
-
克隆项目
git clone <repository-url> cd jc-video-recognize -
安装主项目依赖
pnpm install cd apps/server python3 -m venv venv source venv/bin/activate pip install -r requirements.txt cd ../.. -
安装 PaddlePaddle 环境
bash scripts/setup-paddlepaddle.sh -
验证安装
pnpm dev # 检查日志确认 PaddlePaddle 模型加载成功
版本管理策略
Git 版本控制：
- ✅ 包含：源代码文件
- ❌ 排除：模型文件（.gitignore）
- ❌ 排除：第三方库（.gitignore）
- ❌ 排除：虚拟环境（.gitignore）
模型文件管理：
- 使用独立存储服务（如 S3、MinIO）
- 在配置文件中记录模型版本
- 定期备份训练好的模型
性能基准
标准性能指标：
- 首次加载：< 3秒
- 后续推理：< 0.5秒
- 内存占用：< 1GB
- CPU 使用率：< 80%
性能测试方法：
# 使用测试图像进行基准测试
curl -X POST "http://localhost:8000/api/detect" \
-F "image=@test_image.jpg" \
-F "model=smoking_detection_paddle"
来源
PaddleDetection 官方仓库: https://github.com/PaddlePaddle/PaddleDetection 当前版本: release-2.9