jc-video-recognize/README.md

# jc-video-web

视频模型检测平台 - 基于YOLO的实时视频检测系统

## 项目架构

```
jc-video-web/
├── apps/
│   ├── web/              # 前端应用 (Vue 3 + Vite)
│   └── server/           # 后端服务 (FastAPI)
├── packages/
│   └── shared-types/     # 前后端共享类型定义
├── models/               # AI模型文件
│   ├── fire_detection/   # 火灾检测模型
│   ├── helmet_detection/ # 安全帽检测模型
│   ├── crowd_detection/  # 人群检测模型
│   └── smoking_detection/# 抽烟检测模型
├── scripts/              # 构建/开发脚本
└── docker/               # Docker配置
```

## 技术栈

### 前端
- **框架**: Vue 3 + Composition API
- **构建工具**: Vite 5
- **UI组件库**: Element Plus
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **HTTP客户端**: Axios

### 后端
- **框架**: FastAPI
- **服务器**: Uvicorn
- **AI推理**: Ultralytics (YOLO)
- **图像处理**: OpenCV, Pillow
- **实时通信**: WebSocket

## 快速开始

### 环境要求
- Node.js >= 18
- Python >= 3.9
- pnpm >= 9.0

### 安装依赖

```bash
# 运行初始化脚本
bash scripts/setup.sh
```

或手动安装：

```bash
# 安装根依赖
pnpm install

# 安装前端依赖
cd apps/web
pnpm install
cd ../..

# 创建 Python 虚拟环境并安装依赖
cd apps/server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd ../..
```

### 开发模式

在项目根目录执行：

```bash
# 同时启动前后端（需先激活后端虚拟环境）
pnpm dev

# 只启动前端
pnpm dev:web

# 只启动后端（需先激活虚拟环境）
cd apps/server
source venv/bin/activate  # macOS/Linux
# 或 venv\Scripts\activate  # Windows
pnpm dev:server
```

访问地址：
- 前端: http://localhost:5173
- 后端: http://localhost:8000
- API文档: http://localhost:8000/docs

## 功能特性

### 检测模型
1. **火灾检测** - 基于YOLOv10的火焰和烟雾检测
2. **安全帽检测** - 基于YOLOv8的工地安全检测
3. **人群检测** - 基于YOLOv8的人群聚集检测
4. **抽烟检测** - 基于YOLOv8的吸烟行为检测

### 输入方式
- 图片上传检测
- 摄像头实时检测

### 核心功能
- 可拖拽布局配置
- 实时WebSocket视频流
- 检测结果可视化
- 多模型切换
- 置信度阈值调整

## 项目脚本

```bash
pnpm dev          # 启动开发服务器
pnpm build        # 构建生产版本
pnpm build:web    # 只构建前端
pnpm test         # 运行测试
pnpm lint         # 代码检查
pnpm clean        # 清理构建产物
```

## 模型配置

### 统一模型管理

所有模型文件统一存放在 `models/` 目录下：

```
models/
├── smoking_detection/           # YOLOv8 抽烟检测
├── smoking_detection_paddle/    # PaddlePaddle PP-YOLOE-s 抽烟检测
├── fire_detection/             # YOLOv10 火灾检测
├── helmet_detection/          # YOLOv8 安全帽检测
├── crowd_detection/           # YOLOv8 人群检测
└── loitering_detection/       # YOLOv8 徘徊检测
```

### 模型类型说明

**YOLO 模型：**
- 使用 `yolov8n.pt` 或 `yolov10n.pt` 格式
- 通过 `detection_service.py` 自动加载
- 支持：抽烟检测、火灾检测、安全帽检测、人群检测、徘徊检测

**PaddlePaddle 模型：**
- 使用 `model.pdmodel` + `model.pdiparams` 格式
- 通过 `paddle_detection_service.py` 加载
- 支持：抽烟检测（PP-YOLOE-s）

### 模型文件格式

**YOLO 模型：**
```
smoking_detection/
└── yolov8n.pt                 # YOLO 模型文件
```

**PaddlePaddle 模型：**
```
smoking_detection_paddle/
├── model.pdmodel              # 模型结构
├── model.pdiparams            # 模型参数
└── infer_cfg.yml             # 推理配置
```

## PaddlePaddle 环境配置

### 本地 PaddlePaddle 部署

项目使用本地 PaddlePaddle 进行抽烟检测推理（不使用 Docker），以获得更好的性能。

### 整合架构说明

PaddlePaddle 模型整合在现有的视频检测平台中，提供补充的检测能力。

**系统架构层级**

1. **前端层**
   - 通过 Web 界面接收用户输入
   - 调用后端 API 进行图像检测
   - 展示检测结果和实时视频流

2. **后端服务层**
   - FastAPI 提供 REST API 接口
   - WebSocket 支持实时视频流传输
   - 路由不同检测请求到对应的模型服务

3. **检测服务层**
   - YOLO 检测服务：处理火灾、安全帽、人群、徘徊等检测任务
   - PaddlePaddle 检测服务：专门处理抽烟检测任务
   - 统一的检测结果格式输出

4. **推理引擎层**
   - YOLO 推理引擎：基于 Ultralytics 库
   - PaddlePaddle 推理引擎：基于 PaddleDetection 库
   - 各自独立的模型加载和推理逻辑

**调用流程**

前端发起检测请求 → 后端 API 接收 → 路由到对应检测服务 → 推理引擎处理 → 返回检测结果 → 前端展示

**模型选择策略**

- 系统根据检测类型自动选择合适的推理引擎
- 抽烟检测优先使用 PaddlePaddle 模型（精度更高）
- 其他检测使用 YOLO 模型（速度更快）
- 支持配置切换模型类型

### 依赖关系说明

PaddlePaddle 整合依赖于多个组件的协同工作。

**核心依赖组件**

1. **PaddlePaddle 框架**
   - 版本要求：3.0.0
   - 提供深度学习推理基础能力
   - 支持 CPU 推理（本地部署环境）

2. **PaddleDetection 库**
   - 来源：GitHub PaddlePaddle/PaddleDetection release-2.9
   - 提供目标检测专用功能
   - 包含预处理、推理、后处理和可视化模块

3. **FastAPI 服务**
   - 主后端框架，提供 Web 服务
   - 整合 PaddlePaddle 检测服务
   - 处理 HTTP 请求和 WebSocket 连接

4. **虚拟环境**
   - 统一使用 `apps/server/venv`
   - 包含所有必需的 Python 依赖
   - 隔离运行环境，避免版本冲突

**依赖链路**

用户请求 → FastAPI → PaddleDetection 服务 → PaddlePaddle 框架 → 模型推理 → 结果返回

**环境变量依赖**

- `FLAGS_enable_pir_api=0`：禁用新版 PIR API，确保与旧模型兼容
- Python 路径配置：确保正确加载 PaddleDetection 模块

**系统资源依赖**

- CPU：支持多线程推理
- 内存：最小要求 2GB，推荐 4GB 以上
- 磁盘空间：模型文件约 30MB，推理代码约 50MB

**与其他组件的关系**

- 与 YOLO 检测服务并列运行，互不干扰
- 共享 FastAPI 的路由和中间件
- 使用相同的日志系统和错误处理机制
- 统一的模型管理目录结构

### 环境设置

1. 运行环境设置脚本验证/安装 PaddlePaddle：

```bash
bash scripts/setup-paddlepaddle.sh
```

2. 如果是首次设置，按照脚本提示完成以下步骤：
   - 下载 PaddleDetection release-2.9 到 `PaddlePaddle/PaddleDetection-release-2.9/`
   - 安装 PaddlePaddle 和依赖到服务器虚拟环境
   - 将模型文件复制到 `models/smoking_detection_paddle/`

### 目录结构

```
third-party/paddle-inference/       # PaddleDetection 推理代码
├── infer.py                      # 推理引擎
├── preprocess.py                 # 图像预处理
├── utils.py                      # 工具函数
└── visualize.py                  # 结果可视化

models/smoking_detection_paddle/      # PaddlePaddle 模型文件
├── model.pdmodel                # 模型结构
├── model.pdiparams              # 模型参数
└── infer_cfg.yml                 # 推理配置
```

### 性能优化
本地部署相比 Docker 性能提升：
- 推理时间：3-4秒 → 0.123秒（提升 ~30 倍）
- 内存占用：~3GB → ~0.5GB（减少 83%）
- 启动时间：~10秒 → 即时
- CPU 利用率：提升 50%

### PaddlePaddle 详细操作指南

#### 首次设置完整流程

1. **下载 PaddleDetection 代码**
   ```bash
   # 进入项目根目录
   cd jc-video-recognize
   
   # 下载 PaddleDetection release-2.9
   git clone -b release/2.9 https://github.com/PaddlePaddle/PaddleDetection.git /tmp/PaddleDetection-release-2.9
   
   # 或手动下载并解压
   # 从 https://github.com/PaddlePaddle/PaddleDetection/releases/tag/release%2F2.9
   ```

2. **复制推理代码**
   ```bash
   # 复制必要的推理文件到项目中
   cp -r /tmp/PaddleDetection-release-2.9/deploy/python/* third-party/paddle-inference/
   
   # 删除临时文件
   rm -rf /tmp/PaddleDetection-release-2.9
   ```

3. **安装 PaddlePaddle 依赖**
   ```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
   ```

4. **放置模型文件**
   ```bash
   # 确保模型文件在正确位置
   ls -la models/smoking_detection_paddle/
   # 应该包含：model.pdmodel, model.pdiparams, infer_cfg.yml
   ```

5. **验证安装**
   ```bash
   # 运行验证脚本
   bash scripts/setup-paddlepaddle.sh
   ```

#### 日常维护操作

**更新 PaddlePaddle 推理代码**
```bash
# 下载新版推理代码
cd /tmp
git clone -b release/2.9 https://github.com/PaddlePaddle/PaddleDetection.git PaddleDetection-release-2.9

# 备份现有代码
cd ../jc-video-recognize
cp -r third-party/paddle-inference third-party/paddle-inference.backup

# 更新推理代码
cp -r /tmp/PaddleDetection-release-2.9/deploy/python/* third-party/paddle-inference/

# 测试新代码
pnpm dev:server

# 如果测试失败，恢复备份
# rm -rf third-party/paddle-inference
# mv third-party/paddle-inference.backup third-party/paddle-inference
```

**更新模型文件**
```bash
# 停止服务器
pkill -f "python.*main.py"

# 备份现有模型
cp -r models/smoking_detection_paddle models/smoking_detection_paddle.backup

# 放置新模型
cp /path/to/new/model.pdmodel models/smoking_detection_paddle/
cp /path/to/new/model.pdiparams models/smoking_detection_paddle/
cp /path/to/new/infer_cfg.yml models/smoking_detection_paddle/

# 重启服务器验证
cd apps/server && ./start_server_with_env.sh
```

**更新依赖版本**
```bash
# 进入服务器虚拟环境
cd apps/server
source venv/bin/activate

# 升级 PaddlePaddle
pip install --upgrade paddlepaddle==3.0.0

# 升级其他依赖
pip install --upgrade 'numpy==1.26.4' 'opencv-python==4.7.0.72'
pip install --upgrade imgaug==0.4.0

# 测试新版本
python -c "import paddle; print(paddle.__version__)"
```

#### 故障排查指南

**问题 1：模型加载失败**
```bash
# 检查模型文件完整性
ls -la models/smoking_detection_paddle/

# 检查必要文件
model.pdmodel    # 模型结构
model.pdiparams  # 模型参数  
infer_cfg.yml   # 推理配置

# 验证文件大小（应该 > 30MB）
du -sh models/smoking_detection_paddle/
```

**问题 2：PaddlePaddle 导入失败**
```bash
# 检查 PaddlePaddle 安装
source apps/server/venv/bin/activate
pip list | grep paddle

# 重新安装 PaddlePaddle
pip install paddlepaddle==3.0.0 --force-reinstall

# 检查环境变量
echo $FLAGS_enable_pir_api
# 应该是 0
```

**问题 3：推理速度慢**
```bash
# 检查 CPU 使用情况
top -p $(pgrep -f python)

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

# 优化建议：
# 1. 减少批处理大小
# 2. 使用更小的模型（如果精度允许）
# 3. 启用 GPU 加速（如果有 NVIDIA GPU）
```

#### 性能监控

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

**性能基准测试**
```bash
# 使用测试图像进行基准测试
curl -X POST "http://localhost:8000/api/detect" \
  -F "image=@test_image.jpg" \
  -F "model=smoking_detection_paddle"
```

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

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

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

#### Git 管理

**排除文件**
```bash
# .gitignore 中已配置以下排除
models/*/                  # 模型文件
third-party/paddle-inference/ # 第三方代码
apps/server/venv/         # 虚拟环境
```

**版本控制策略**
- ✅ 只版本控制代码文件
- ❌ 不版本控制模型文件（太大）
- ❌ 不版本控制第三方库
- ✅ 使用 Git LFS 如果必须版本控制大文件

#### 协作建议

**团队协作流程**
1. 每个成员独立运行 `setup-paddlepaddle.sh`
2. 在 README 中记录使用的 PaddlePaddle 版本
3. 定期同步模型文件和配置更新
4. 使用统一的环境变量配置



## 许可证

[MIT](LICENSE)