a16e684e46
1. 新增3套PaddlePaddle车辆检测相关模型文件 2. 新增车辆检测服务类与违停检测功能 3. 更新服务依赖并添加环境初始化脚本与文档 4. 修复YOLO检测tensor转换兼容问题 5. 新增PyTorch版本兼容性修复逻辑 6. 扩展模型服务支持Paddle模型加载
199 lines
5.4 KiB
Markdown
199 lines
5.4 KiB
Markdown
# 环境配置说明
|
|
|
|
## 📦 当前环境版本 (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
|
|
**维护者**: 开发团队
|
|
**环境状态**: ✅ 生产就绪 |