# 延寿水库智能识别服务接口说明

## 1. 项目概述

本服务基于 FastAPI 和 YOLO 模型，为延寿水库项目提供按场景划分的智能识别能力。当前支持两类能力：

- 图像识别：上传单张图片并返回识别结果。
- 视频流识别：提交 RTSP 或本地视频流地址，系统异步分析并通过回调地址推送结果。

服务中的 `model_type` 对应具体业务场景，每个场景绑定一个独立模型文件。

## 2. 支持场景

- `floating`：水面漂浮物识别。用于识别水面漂浮垃圾、杂物等目标。
- `gate`：闸口场景识别。用于识别闸口、闸门区域中的目标和异常情况。
- `shore_garbage`：岸边垃圾识别。用于识别岸线附近堆积或散落的垃圾目标。
- `water_gauge`：水尺识别。用于识别水尺、水位尺等目标，服务于水位监测场景。

## 3. 接口列表

- `POST /{model_type}/predict/image`：按场景执行图片识别。
- `POST /{model_type}/predict/stream`：按场景提交视频流识别任务。
- `POST /v1/task/stream`：兼容旧版视频流接口，通过 `scene_type` 指定场景。
- `POST /v1/predict/image`：旧版图片接口说明入口，当前会返回引导信息，请改用新接口。

## 4. 图片识别接口

### 4.1 请求地址

`POST /{model_type}/predict/image`

### 4.2 路径参数

- `model_type`：场景类型，可选值为 `floating`、`gate`、`shore_garbage`、`water_gauge`。

### 4.3 请求方式

`multipart/form-data`

### 4.4 请求参数

- `file`：待识别图片文件，支持常见图片格式。

### 4.5 调用示例

```bash
curl -X POST "http://localhost:8000/floating/predict/image" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@test.jpg;type=image/jpeg"
```

### 4.6 返回示例

```json
{
  "results": [
    {
      "name": "floating_object",
      "class": 0,
      "confidence": 0.93,
      "box": {
        "x1": 102.4,
        "y1": 55.2,
        "x2": 260.8,
        "y2": 188.6
      }
    }
  ]
}
```

## 5. 视频流识别接口

### 5.1 新版接口

`POST /{model_type}/predict/stream`

### 5.2 兼容接口

`POST /v1/task/stream`

兼容接口中，场景通过请求体的 `scene_type` 指定，其可选值与 `model_type` 一致。

### 5.3 请求体参数

- `source_url`：视频流地址，支持 `rtsp://...`、本地视频文件路径等 OpenCV 可读取地址。
- `webhook_url`：识别结果回调地址，必须是服务端可访问的 `HTTP/HTTPS POST` 接口。
- `roi`：可选电子围栏，多边形坐标数组，格式为 `[[x1, y1], [x2, y2], ...]`。不传时默认检测整幅画面。

### 5.4 请求体示例

```json
{
  "source_url": "rtsp://admin:password@192.168.1.100:554/h264/ch1/main/av_stream",
  "webhook_url": "https://example.com/api/reservoir/webhook",
  "roi": [[0, 0], [1920, 0], [1920, 1080], [0, 1080]]
}
```

### 5.5 调用示例

```bash
curl -X POST "http://localhost:8000/floating/predict/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "rtsp://admin:password@192.168.1.100:554/h264/ch1/main/av_stream",
    "webhook_url": "https://example.com/api/reservoir/webhook",
    "roi": [[0, 0], [1920, 0], [1920, 1080], [0, 1080]]
  }'
```

### 5.6 提交成功返回示例

```json
{
  "code": 200,
  "msg": "task submitted",
  "task_type": "floating"
}
```

## 6. webhook_url 参数说明

- `webhook_url` 必须是业务系统提供的接收地址。
- 请求方法为 `POST`。
- 请求体格式为 `application/json`。
- 当视频流识别到目标时才会触发回调；未识别到目标时不会持续推送空结果。
- 业务系统应保证该地址可被算法服务访问，并能在超时时间内返回。

## 7. 视频流回调数据格式

### 7.1 回调 JSON 示例

```json
{
  "event": "RESERVOIR_ALARM",
  "scene": "floating",
  "stream_url": "rtsp://example.com/live",
  "details": [
    {
      "label": "floating_object",
      "confidence": 0.93,
      "bbox": [102.4, 55.2, 260.8, 188.6]
    }
  ],
  "msg": "detected floating event"
}
```

### 7.2 字段说明

- `event`：事件类型，当前为 `RESERVOIR_ALARM`。
- `scene`：触发识别的场景类型，对应接口中的 `model_type`。
- `stream_url`：本次识别的视频流地址。
- `details`：识别结果数组。
- `label`：识别类别名称。
- `confidence`：识别置信度，范围通常为 0 到 1。
- `bbox`：目标框坐标，格式为 `[x1, y1, x2, y2]`。
- `msg`：简要告警说明。

## 8. 使用建议

- 视频流接口为异步提交接口，请结合业务系统的 `webhook_url` 接收识别结果。
- 若需要限定检测区域，建议传入 `roi`，减少无关区域误报。
- 推荐通过 FastAPI 自带文档页面查看接口：
  - Swagger UI：`/docs`
  - ReDoc：`/redoc`