jc-video-recognize/third-party/README.md

# 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+ 模型格式
- 提供预处理、可视化等工具

### 依赖安装
在服务器虚拟环境中安装以下依赖：

```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
```

## 模型管理

### 统一管理
所有模型文件统一存储在 `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 模型
```python
from services.detection_service import DetectionService
# 自动加载 models/ 目录中的 YOLO 模型
```

### PaddlePaddle 模型
```python
from services.paddle_detection_service import SmokingDetectionModel
# 自动加载 models/smoking_detection_paddle/ 目录
```

## 性能优化

### Apple Silicon 优化
- 本地部署相比 Docker 性能提升 30 倍
- 推理时间：3-4秒 → 0.123秒
- 内存占用：~3GB → ~0.5GB

### 环境变量
必须在 Python 进程启动前设置：
```bash
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/
```

**安全更新流程：**
```bash
# 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. 模型加载失败**
```bash
# 检查模型文件完整性
ls -la ../models/smoking_detection_paddle/

# 应该包含以下文件：
model.pdmodel      # 模型结构（约1MB）
model.pdiparams    # 模型参数（约30MB）
infer_cfg.yml      # 推理配置（约1KB）

# 检查文件权限
chmod 644 ../models/smoking_detection_paddle/*
```

**2. PaddlePaddle 导入失败**
```bash
# 检查 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. 推理速度慢**
```bash
# 检查 CPU 使用情况
top -p $(pgrep -f python)

# 检查内存使用情况
free -h

# 性能优化建议：
# 1. 首次加载2秒是正常的（模型加载）
# 2. 后续推理0.2秒是优秀的
# 3. 如果推理时间 > 1秒，考虑优化模型大小
```

### 性能监控

**实时推理时间监控**
```bash
# 查看推理日志
tail -f ../apps/server/logs/*.log | grep "推理时间"
```

**系统资源监控**
```bash
# CPU 使用率
mpstat 1

# 内存使用情况
free -m -s 1

# 磁盘 I/O
iostat -x 1
```

## 协作指南

### 新成员上手流程

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd jc-video-recognize
   ```

2. **安装主项目依赖**
   ```bash
   pnpm install
   cd apps/server
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   cd ../..
   ```

3. **安装 PaddlePaddle 环境**
   ```bash
   bash scripts/setup-paddlepaddle.sh
   ```

4. **验证安装**
   ```bash
   pnpm dev
   # 检查日志确认 PaddlePaddle 模型加载成功
   ```

### 版本管理策略

**Git 版本控制：**
- ✅ **包含**：源代码文件
- ❌ **排除**：模型文件（.gitignore）
- ❌ **排除**：第三方库（.gitignore）
- ❌ **排除**：虚拟环境（.gitignore）

**模型文件管理：**
- 使用独立存储服务（如 S3、MinIO）
- 在配置文件中记录模型版本
- 定期备份训练好的模型

### 性能基准

**标准性能指标：**
- 首次加载：< 3秒
- 后续推理：< 0.5秒
- 内存占用：< 1GB
- CPU 使用率：< 80%

**性能测试方法：**
```bash
# 使用测试图像进行基准测试
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