# 环境配置说明

## 📦 当前环境版本 (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  
**维护者**: 开发团队  
**环境状态**: ✅ 生产就绪