initial commit

2026-08-21 14:19:14 +08:00
commit 0bafbee31f
@@ -0,0 +1,455 @@
+# 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/...` 静态下载接口。