feat: 新增车辆检测Paddle模型及相关服务，优化依赖与代码兼容性
1. 新增3套PaddlePaddle车辆检测相关模型文件 2. 新增车辆检测服务类与违停检测功能 3. 更新服务依赖并添加环境初始化脚本与文档 4. 修复YOLO检测tensor转换兼容问题 5. 新增PyTorch版本兼容性修复逻辑 6. 扩展模型服务支持Paddle模型加载
This commit is contained in:
wwh
199
apps/server/ENVIRONMENT.md
Normal file
199
apps/server/ENVIRONMENT.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# 环境配置说明
|
||||
|
||||
## 📦 当前环境版本 (2026-05-21 验证通过)
|
||||
|
||||
### 核心框架
|
||||
- **Python**: 3.12
|
||||
- **FastAPI**: 0.136.1
|
||||
- **Uvicorn**: 0.34.0 (with standard extras)
|
||||
- **Pydantic**: 2.10.6
|
||||
|
||||
### 深度学习框架
|
||||
- **PyTorch**: 2.12.0
|
||||
- **TorchVision**: 0.27.0
|
||||
- **Ultralytics**: 8.4.52 (YOLO 模型支持)
|
||||
- **Ultralytics-THOP**: 2.0.19
|
||||
|
||||
### PaddlePaddle 生态
|
||||
- **PaddlePaddle**: 3.0.0
|
||||
- **Paddle2ONNX**: 2.1.0
|
||||
|
||||
### 数值计算和数据处理
|
||||
- **NumPy**: 2.4.6 ⚠️ **需要注意兼容性**
|
||||
- **Pandas**: 2.3.3
|
||||
- **SciPy**: 1.15.2
|
||||
- **Scikit-Image**: 0.26.2
|
||||
|
||||
### 图像和计算机视觉
|
||||
- **OpenCV**: 4.13.0.92
|
||||
- **Pillow**: 11.1.0
|
||||
- **ImageIO**: 2.37.3
|
||||
- **imgaug**: 0.4.0 ⚠️ **需要手动修复**
|
||||
|
||||
### 其他依赖
|
||||
- **aiofiles**: 25.1.0
|
||||
- **python-multipart**: 0.0.20
|
||||
- **websockets**: 14.1
|
||||
- **matplotlib**: 3.10.1
|
||||
- **Shapely**: 2.1.0
|
||||
- **tqdm**: 4.69.2
|
||||
|
||||
## 🔧 特殊注意事项
|
||||
|
||||
### 1. imgaug NumPy 2.0 兼容性问题
|
||||
|
||||
**问题**: imgaug 0.4.0 使用了 `np.sctypes` 属性，但 NumPy 2.0+ 移除了这个 API。
|
||||
|
||||
**解决方案**: 手动修复 `imgaug.py` 文件
|
||||
|
||||
**修复文件路径**: `venv/lib/python3.12/site-packages/imgaug/imgaug.py`
|
||||
|
||||
**需要修改的行**: 第 45-47 行
|
||||
|
||||
**原始代码**:
|
||||
```python
|
||||
NP_FLOAT_TYPES = set(np.sctypes["float"])
|
||||
NP_INT_TYPES = set(np.sctypes["int"])
|
||||
NP_UINT_TYPES = set(np.sctypes["uint"])
|
||||
```
|
||||
|
||||
**修复后代码**:
|
||||
```python
|
||||
NP_FLOAT_TYPES = {np.float16, np.float32, np.float64}
|
||||
NP_INT_TYPES = {np.int8, np.int16, np.int32, np.int64}
|
||||
NP_UINT_TYPES = {np.uint8, np.uint16, np.uint32, np.uint64}
|
||||
```
|
||||
|
||||
### 2. PyTorch 2.12.0 与 Ultralytics 兼容性
|
||||
|
||||
**状态**: ✅ 完全兼容，无需额外配置
|
||||
|
||||
**说明**:
|
||||
- PyTorch 2.12.0 与 Ultralytics 8.4.52 完全兼容
|
||||
- 无需手动添加安全全局变量
|
||||
- 模型加载和推理功能正常
|
||||
|
||||
### 3. NumPy 2.4.6 兼容性
|
||||
|
||||
**状态**: ✅ 所有主要包都已验证兼容
|
||||
|
||||
**兼容包**:
|
||||
- ✅ PyTorch 2.12.0
|
||||
- ✅ TorchVision 0.27.0
|
||||
- ✅ Ultralytics 8.4.52
|
||||
- ✅ PaddlePaddle 3.0.0
|
||||
- ✅ OpenCV 4.13.0.92
|
||||
- ⚠️ imgaug 0.4.0 (需要手动修复)
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
### 核心目录
|
||||
```
|
||||
jc-video-recognize/
|
||||
├── apps/server/
|
||||
│ ├── venv/ # 虚拟环境
|
||||
│ ├── models/ # 模型文件
|
||||
│ │ ├── smoking_yolo/ # 吸烟检测模型
|
||||
│ │ ├── fire_detection/ # 火灾检测模型
|
||||
│ │ ├── vehicle_detection_paddle/ # 车辆检测模型
|
||||
│ │ └── smoking_detection_paddle/ # Paddle吸烟检测模型
|
||||
│ ├── api/ # API 端点
|
||||
│ ├── services/ # 业务逻辑服务
|
||||
│ ├── static/ # 静态文件和结果
|
||||
│ ├── requirements.txt # Python 依赖
|
||||
│ ├── setup_env.sh # 环境初始化脚本
|
||||
│ └── main.py # 应用入口
|
||||
└── third-party/
|
||||
└── paddle-inference/ # PaddleDetection 部署代码
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 环境初始化
|
||||
|
||||
```bash
|
||||
# 使用自动初始化脚本
|
||||
cd apps/server
|
||||
chmod +x setup_env.sh
|
||||
./setup_env.sh
|
||||
```
|
||||
|
||||
### 2. 手动安装
|
||||
|
||||
```bash
|
||||
# 创建虚拟环境
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 修复 imgaug (如果自动脚本未执行)
|
||||
# 手动修改 venv/lib/python3.12/site-packages/imgaug/imgaug.py 第45-47行
|
||||
```
|
||||
|
||||
### 3. 启动服务
|
||||
|
||||
```bash
|
||||
# 激活虚拟环境
|
||||
source venv/bin/activate
|
||||
|
||||
# 启动服务
|
||||
python main.py
|
||||
|
||||
# 或使用启动脚本
|
||||
./start_server_with_env.sh
|
||||
```
|
||||
|
||||
## 🔍 已知问题和解决方案
|
||||
|
||||
### 问题 1: YOLO 模型 tensor 转换错误
|
||||
|
||||
**错误信息**: `ValueError: only one element tensors can be converted to Python scalars`
|
||||
|
||||
**影响文件**:
|
||||
- `services/detection_service.py` (第 62-72 行, 第 175-184 行)
|
||||
|
||||
**解决方案**: 已修复，使用 `box.xyxy.squeeze().tolist()` 安全转换 tensor
|
||||
|
||||
### 问题 2: PaddleDetection imgaug 兼容性
|
||||
|
||||
**错误信息**: `AttributeError: np.sctypes was removed in the NumPy 2.0 release`
|
||||
|
||||
**影响文件**: `venv/lib/python3.12/site-packages/imgaug/imgaug.py`
|
||||
|
||||
**解决方案**: 手动修复第 45-47 行（如上所述）
|
||||
|
||||
### 问题 3: PyTorch WeightsUnpickler 错误
|
||||
|
||||
**状态**: ✅ 已通过升级 PyTorch 和 Ultralytics 解决
|
||||
|
||||
## 📝 版本选择理由
|
||||
|
||||
1. **PyTorch 2.12.0**: 最新稳定版本，与 TorchVision 0.27.0 完全兼容
|
||||
2. **NumPy 2.4.6**: 最新版本，性能更好，通过手动修复兼容性问题
|
||||
3. **Ultralytics 8.4.52**: 与 PyTorch 2.12.0 完全兼容，支持最新 YOLO 模型
|
||||
4. **PaddlePaddle 3.0.0**: 官方稳定版本，支持所有车辆检测功能
|
||||
5. **imgaug 0.4.0**: 最后一个稳定版本，虽然不兼容 NumPy 2.0 但可手动修复
|
||||
|
||||
## 🤝 给团队成员的建议
|
||||
|
||||
1. **严格遵循版本要求**: 不要随意更改依赖版本
|
||||
2. **执行初始化脚本**: 使用 `setup_env.sh` 自动处理兼容性问题
|
||||
3. **检查环境**: 每次启动前验证关键包版本
|
||||
4. **备份环境**: 使用 `pip freeze > environment.txt` 备份当前环境
|
||||
5. **报告问题**: 如遇到新的兼容性问题，及时更新此文档
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如遇到环境相关问题，请：
|
||||
1. 检查此文档的已知问题部分
|
||||
2. 确认所有依赖版本符合要求
|
||||
3. 验证 imgaug 手动修复是否成功
|
||||
4. 查看服务日志获取详细错误信息
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-05-21
|
||||
**维护者**: 开发团队
|
||||
**环境状态**: ✅ 生产就绪
|
||||
Reference in New Issue
Block a user