延寿水库

4.7 KiB

Raw Blame History

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

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 调用示例

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 返回示例

{
  "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 请求体示例

{
  "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 调用示例

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 提交成功返回示例

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

6. webhook_url 参数说明

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

7. 视频流回调数据格式

7.1 回调 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

4.7 KiB Raw Blame History