456 lines
10 KiB
Markdown
456 lines
10 KiB
Markdown
# Bird Detect Cascade Service：YOLOv5 + ConvNeXt 鸟类级联识别服务
|
||
|
||
本项目用于将 **YOLOv5 目标检测模型** 和 **ConvNeXt 鸟类细粒度分类模型** 级联起来：
|
||
|
||
1. 接收图片或视频；
|
||
2. 使用 YOLOv5 检测鸟类目标位置；
|
||
3. 对每个检测框进行目标裁剪；
|
||
4. 将裁剪图送入 ConvNeXt 分类模型；
|
||
5. 返回每个目标的位置、检测置信度、分类类别、分类置信度；
|
||
6. 可选返回画框后的图片或视频。
|
||
|
||
项目默认使用 **ONNX Runtime** 推理，适合用 Docker 部署成 HTTP API 服务，方便网站后端调用。
|
||
|
||
---
|
||
|
||
## 1. 项目结构
|
||
|
||
```text
|
||
bird_detect_cascade_service/
|
||
├── app/
|
||
│ ├── main.py # FastAPI 接口入口
|
||
│ ├── config.py # 配置读取
|
||
│ ├── schemas.py # 返回结构
|
||
│ ├── pipeline.py # YOLO + 裁剪 + ConvNeXt 级联流程
|
||
│ ├── utils.py # 图像工具函数
|
||
│ └── inference/
|
||
│ ├── yolo_onnx.py # YOLOv5 ONNX 推理与后处理
|
||
│ └── convnext_onnx.py # ConvNeXt ONNX 推理
|
||
├── models/
|
||
│ ├── yolov5.onnx # 你的 YOLOv5 ONNX 模型，需自行放入
|
||
│ ├── convnext.onnx # 你的 ConvNeXt ONNX 模型，需自行放入
|
||
│ ├── det_classes.txt # YOLO 类别名
|
||
│ └── cls_classes.txt # ConvNeXt 类别名
|
||
├── test_client.py # 本地接口测试脚本
|
||
├── requirements.txt
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 模型准备
|
||
|
||
### 2.1 YOLOv5 导出 ONNX
|
||
|
||
如果你的 YOLOv5 是 `.pt` 权重，一般可在 YOLOv5 项目目录下执行：
|
||
|
||
```bash
|
||
python export.py \
|
||
--weights /path/to/best.pt \
|
||
--img 960 960 \
|
||
--batch 1 \
|
||
--device cpu \
|
||
--include onnx \
|
||
--simplify
|
||
```
|
||
|
||
导出后把 ONNX 文件复制为：
|
||
|
||
```bash
|
||
models/yolov5.onnx
|
||
```
|
||
|
||
### 2.2 ConvNeXt 导出 ONNX
|
||
|
||
如果你已有 ConvNeXt 的 `.onnx`，直接复制为：
|
||
|
||
```bash
|
||
models/convnext.onnx
|
||
```
|
||
|
||
如果你只有 PyTorch 权重，需要用你训练时的模型定义导出，输入通常为：
|
||
|
||
```text
|
||
1 × 3 × 224 × 224
|
||
```
|
||
|
||
如果你的 ConvNeXt 输入尺寸不是 224，需要修改 `.env` 或 `docker-compose.yml` 中的：
|
||
|
||
```bash
|
||
CLS_IMG_SIZE=224
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 类别文件格式
|
||
|
||
### 3.1 YOLO 检测类别
|
||
|
||
`models/det_classes.txt`
|
||
|
||
如果 YOLO 只检测鸟，可以写：
|
||
|
||
```text
|
||
bird
|
||
```
|
||
|
||
如果 YOLO 有多个检测类别，例如：
|
||
|
||
```text
|
||
bird
|
||
person
|
||
cat
|
||
dog
|
||
```
|
||
|
||
每一行对应一个类别，行号从 0 开始。
|
||
|
||
### 3.2 ConvNeXt 分类类别
|
||
|
||
`models/cls_classes.txt`
|
||
|
||
每一行一个鸟类类别，顺序必须和训练时类别索引一致，例如：
|
||
|
||
```text
|
||
Aix_galericulata
|
||
Anas_crecca
|
||
Anser_cygnoides
|
||
Cygnus_columbianus
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 本地直接运行
|
||
|
||
安装依赖：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
启动服务：
|
||
|
||
```bash
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
访问接口文档：
|
||
|
||
```text
|
||
http://127.0.0.1:8000/docs
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Docker 构建与运行
|
||
|
||
### 5.1 构建镜像
|
||
|
||
```bash
|
||
docker build -t bird-detect-cascade-service:latest .
|
||
```
|
||
|
||
### 5.2 启动容器
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name bird-detect-cascade-service \
|
||
-p 8000:8000 \
|
||
-v $(pwd)/models:/app/models \
|
||
bird-detect-cascade-service:latest
|
||
```
|
||
|
||
### 5.3 使用 docker compose
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
docker logs -f bird-detect-cascade-service
|
||
```
|
||
|
||
停止服务：
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
---
|
||
|
||
## 6. API 说明
|
||
|
||
### 6.1 健康检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/health
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"det_model_loaded": true,
|
||
"cls_model_loaded": true
|
||
}
|
||
```
|
||
|
||
### 6.2 图片识别接口
|
||
|
||
接口：
|
||
|
||
```text
|
||
POST /predict
|
||
```
|
||
|
||
参数：
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|---|---|---:|---|
|
||
| file | file | 必填 | 上传图片 |
|
||
| return_image | bool | false | 是否返回画框后的 base64 图片 |
|
||
| det_conf | float | 配置文件默认值 | YOLO 检测置信度阈值 |
|
||
| iou_thres | float | 配置文件默认值 | NMS 的 IoU 阈值 |
|
||
|
||
curl 示例：
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:8000/predict?return_image=true" \
|
||
-F "file=@/path/to/test.jpg"
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"image_width": 1920,
|
||
"image_height": 1080,
|
||
"num_objects": 1,
|
||
"results": [
|
||
{
|
||
"bbox_xyxy": [500.2, 130.7, 820.9, 600.4],
|
||
"det_confidence": 0.91,
|
||
"det_class_id": 0,
|
||
"det_class_name": "bird",
|
||
"cls_class_id": 12,
|
||
"cls_class_name": "Aix_galericulata",
|
||
"cls_confidence": 0.87
|
||
}
|
||
],
|
||
"annotated_image_base64": "..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Python 测试调用
|
||
|
||
```bash
|
||
python test_client.py \
|
||
--url http://127.0.0.1:8000/predict \
|
||
--image /path/to/test.jpg \
|
||
--save result.jpg
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 关键环境变量
|
||
|
||
这些配置可以在 `docker-compose.yml` 中修改。
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|---|---:|---|
|
||
| DET_MODEL_PATH | /app/models/yolov5.onnx | YOLOv5 ONNX 路径 |
|
||
| CLS_MODEL_PATH | /app/models/convnext.onnx | ConvNeXt ONNX 路径 |
|
||
| DET_CLASSES_PATH | /app/models/det_classes.txt | 检测类别文件 |
|
||
| CLS_CLASSES_PATH | /app/models/cls_classes.txt | 分类类别文件 |
|
||
| DET_IMG_SIZE | 960 | YOLO 输入尺寸 |
|
||
| CLS_IMG_SIZE | 224 | ConvNeXt 输入尺寸 |
|
||
| DET_CONF_THRES | 0.25 | YOLO 默认置信度阈值 |
|
||
| DET_IOU_THRES | 0.45 | NMS 默认 IoU 阈值 |
|
||
| CROP_PADDING_RATIO | 0.08 | 裁剪框外扩比例 |
|
||
| MAX_DETECTIONS | 50 | 单张图片最多返回目标数 |
|
||
| DEVICE | cpu | onnxruntime 设备，默认 cpu |
|
||
|
||
---
|
||
|
||
## 9. 给网站同事的集成方式
|
||
|
||
网站后端只需要以 `multipart/form-data` 方式上传图片到：
|
||
|
||
```text
|
||
POST http://服务器IP:8000/predict
|
||
```
|
||
|
||
前端或后端拿到 JSON 后，根据 `results` 字段展示识别结果即可。
|
||
|
||
如果网站只需要结果，不需要画框图：
|
||
|
||
```text
|
||
return_image=false
|
||
```
|
||
|
||
如果网站需要展示画框图：
|
||
|
||
```text
|
||
return_image=true
|
||
```
|
||
|
||
返回的 `annotated_image_base64` 是 JPEG 的 base64 字符串，前端可拼接为：
|
||
|
||
```javascript
|
||
const imgSrc = "data:image/jpeg;base64," + annotated_image_base64;
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 注意事项
|
||
|
||
1. YOLO 的输入尺寸必须和导出 ONNX 时一致，例如导出时是 `--img 960 960`，配置里也建议用 `DET_IMG_SIZE=960`。
|
||
2. ConvNeXt 的类别文件顺序必须和训练时完全一致。
|
||
3. 如果 YOLO 输出不是标准 YOLOv5 ONNX 格式 `[1, num_boxes, 5 + num_classes]`，需要根据实际输出改 `app/inference/yolo_onnx.py`。
|
||
4. 如果 ConvNeXt 训练时使用了非 ImageNet 的 mean/std，需要修改 `app/inference/convnext_onnx.py` 中的归一化参数。
|
||
5. 如果部署机器没有 GPU，默认 CPU 推理即可；如果需要 GPU 版本，需要替换 `onnxruntime` 为 `onnxruntime-gpu`，并使用支持 CUDA 的基础镜像。
|
||
|
||
---
|
||
|
||
## 11. 常见问题
|
||
|
||
### 11.1 为什么要用 HTTP API？
|
||
|
||
因为最终要集成到网站中，HTTP API 是最直接的对接方式。网站后端不需要关心模型细节，只需要上传图片并接收 JSON。
|
||
|
||
### 11.2 为什么先检测再分类？
|
||
|
||
YOLOv5 负责解决“鸟在哪里”，ConvNeXt 负责解决“这只鸟是什么种类”。先裁剪目标区域可以减少背景干扰，更适合细粒度分类。
|
||
|
||
### 11.3 多只鸟怎么处理？
|
||
|
||
YOLO 检测到几个目标，就裁剪几个目标，并分别送入 ConvNeXt 分类，最终返回一个结果列表。
|
||
|
||
### 11.4 没检测到鸟怎么办？
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"num_objects": 0,
|
||
"results": []
|
||
}
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## 12. 视频识别接口
|
||
|
||
当前版本新增视频接口：
|
||
|
||
```text
|
||
POST /predict_video
|
||
```
|
||
|
||
### 12.1 后台测试视频上传
|
||
|
||
启动服务后，在项目根目录执行：
|
||
|
||
```bash
|
||
bash backend_test_video.sh /path/to/test.mp4
|
||
```
|
||
|
||
等价于：
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:8000/predict_video?sample_interval=25&save_annotated_video=true" \
|
||
-F "file=@/path/to/test.mp4"
|
||
```
|
||
|
||
其中：
|
||
|
||
- `sample_interval=25` 表示每 25 帧处理 1 帧；
|
||
- `save_annotated_video=true` 表示保存画框后视频；
|
||
- 如果视频很长，可以把 `sample_interval` 调大，例如 50、100，减少计算量。
|
||
|
||
### 12.2 视频运行结果保存位置
|
||
|
||
如果使用 `docker compose up -d --build` 启动，`docker-compose.yml` 已经挂载：
|
||
|
||
```yaml
|
||
volumes:
|
||
- ./models:/app/models
|
||
- ./runs:/app/runs
|
||
```
|
||
|
||
所以结果会同时出现在：
|
||
|
||
容器内：
|
||
|
||
```text
|
||
/app/runs/video_时间_随机ID/
|
||
```
|
||
|
||
宿主机项目目录下：
|
||
|
||
```text
|
||
./runs/video_时间_随机ID/
|
||
```
|
||
|
||
每次处理一个视频，会生成一个新的任务目录，例如：
|
||
|
||
```text
|
||
runs/
|
||
└── video_20260518_123000_a1b2c3d4/
|
||
├── source_video.mp4 # 上传的原始视频副本
|
||
├── annotated.mp4 # 画框后的结果视频
|
||
├── summary.json # 本次视频任务摘要
|
||
├── frame_results.json # 每个抽帧的详细识别结果
|
||
└── frames/
|
||
├── frame_00000000.jpg # 有识别结果的关键帧截图
|
||
├── frame_00000025.jpg
|
||
└── ...
|
||
```
|
||
|
||
### 12.3 返回结果示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task_dir": "/app/runs/video_20260518_123000_a1b2c3d4",
|
||
"source_video": "/app/runs/video_20260518_123000_a1b2c3d4/source_video.mp4",
|
||
"annotated_video": "/app/runs/video_20260518_123000_a1b2c3d4/annotated.mp4",
|
||
"frames_dir": "/app/runs/video_20260518_123000_a1b2c3d4/frames",
|
||
"frame_results_json": "/app/runs/video_20260518_123000_a1b2c3d4/frame_results.json",
|
||
"summary_json": "/app/runs/video_20260518_123000_a1b2c3d4/summary.json",
|
||
"sample_interval": 25,
|
||
"processed_frames": 120,
|
||
"detected_frames": 87,
|
||
"elapsed_sec": 35.6
|
||
}
|
||
```
|
||
|
||
### 12.4 网站集成建议
|
||
|
||
网站后端上传视频到：
|
||
|
||
```text
|
||
POST http://服务器IP:8000/predict_video
|
||
```
|
||
|
||
如果网站需要展示结果，可以让网站后端读取返回的：
|
||
|
||
```text
|
||
annotated_video
|
||
frame_results_json
|
||
summary_json
|
||
```
|
||
|
||
正式部署时更推荐把 `runs/` 目录映射到网站后端可访问的静态文件目录，或者在本服务里再增加 `/files/...` 静态下载接口。
|