hertz_django/docs/API接口文档/YOLO模块接口文档.md

Hertz Studio Django YOLO 接口文档

• 基础路径: /api/yolo/
• 统一响应: 使用 HertzResponse 封装，结构为：

  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {}
  }
  

  参考 hertz_studio_django_utils/responses/HertzResponse.py
• 认证说明: 标注“需要登录”的接口需在请求头携带 Authorization: Bearer <token>，验证逻辑参考 hertz_studio_django_auth/utils/decorators/auth_decorators.py。

一、模型上传与转换

（1）上传模型（压缩包或文件夹）

• 方法: POST
• 路径: /api/yolo/upload/
• 认证: 不需要
• 请求类型: multipart/form-data
• 参数:
  • zip_file: ZIP 压缩包文件，与 folder_files 互斥
  • folder_files[...]: 文件夹内的多个文件（键名形如 folder_files[path/to/file]），与 zip_file 互斥
  • name: 模型名称（必填）
  • version: 模型版本（默认 1.0）
  • description: 模型描述（可选）
• 参考实现: views.py 中 model_upload，_handle_zip_upload，_handle_folder_upload，_validate_and_create_model（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1018,1058,1129,1182）
• 示例请求（ZIP 上传）:

  curl -X POST "http://localhost:8000/api/yolo/upload/" \
    -F "zip_file=@/path/to/yolo_model.zip" \
    -F "name=MyYolo" \
    -F "version=1.0" \
    -F "description=Demo model"
  

• 示例响应:

  {
    "success": true,
    "code": 200,
    "message": "模型上传成功",
    "data": {
      "id": 12,
      "name": "MyYolo",
      "version": "1.0",
      "folder_path": "/absolute/path/to/media/models/MyYolo_xxxxxxxx",
      "weights_path": "/absolute/path/to/media/models/MyYolo_xxxxxxxx/weights",
      "model_path": "/absolute/path/to/media/models/MyYolo_xxxxxxxx/weights/best.pt",
      "best_model_path": "/absolute/path/to/media/models/.../weights/best.pt",
      "last_model_path": "/absolute/path/to/media/models/.../weights/last.pt",
      "categories": {"0":"person","1":"bicycle"},
      "created_at": "2025-10-22T03:20:00Z"
    }
  }
  

（2）上传 .pt 并转换为 ONNX

• 方法: POST
• 路径: /api/yolo/onnx/upload/
• 认证: 不需要
• 请求类型: multipart/form-data
• 参数:
  • file: .pt 模型文件（必填）
  • imgsz: 导出图像尺寸（如 640 或 640,640，默认 640）
  • opset: ONNX opset 版本（默认 12）
  • simplify: 是否简化 ONNX（true/false，默认 false）
• 参考实现: views.py 中 upload_pt_convert_onnx（d:\All_template\yolo\hertz_studio_django_yolo\views.py:877）
• 示例请求:

  curl -X POST "http://localhost:8000/api/yolo/onnx/upload/" \
    -F "file=@/path/to/best.pt" \
    -F "imgsz=640" \
    -F "opset=12" \
    -F "simplify=true"
  

• 示例响应:

  {
    "success": true,
    "code": 200,
    "message": "ONNX 导出成功",
    "data": {
      "onnx_relative_path": "yolo/ONNX/best_xxxxxxxx.onnx",
      "download_url": "http://localhost:8000/media/yolo/ONNX/best_xxxxxxxx.onnx",
      "labels_relative_path": "yolo/ONNX/best_xxxxxxxx.labels.json",
      "labels_download_url": "http://localhost:8000/media/yolo/ONNX/best_xxxxxxxx.labels.json"
    }
  }
  

二、模型管理

（1）获取模型列表

• 方法: GET
• 路径: /api/yolo/models/
• 认证: 不需要
• 参考实现: model_list（d:\All_template\yolo\hertz_studio_django_yolo\views.py:101）
• 示例响应:

  {
    "success": true,
    "code": 200,
    "message": "获取模型列表成功",
    "data": [
      {"id": 1, "name": "ModelA", "version": "1.0", "is_enabled": true, "created_at": "2025-10-22T03:20:00Z"}
    ]
  }
  

（2）获取模型详情

• 方法: GET
• 路径: /api/yolo/models/{pk}/
• 认证: 不需要
• 参考实现: model_detail（d:\All_template\yolo\hertz_studio_django_yolo\views.py:121）
• 示例响应（节选）:

  {
    "success": true,
    "code": 200,
    "message": "获取模型详情成功",
    "data": {
      "id": 1,
      "name": "ModelA",
      "version": "1.0",
      "model_file": "/media/yolo/models/modela.pt",
      "model_folder_path": "/abs/path/models/modela_...",
      "model_path": "/abs/path/models/modela_/weights/best.pt",
      "weights_folder_path": "/abs/path/models/modela_/weights",
      "categories": {"0": "person"},
      "is_enabled": true,
      "description": "...",
      "created_at": "...",
      "updated_at": "..."
    }
  }
  

（2）更新模型

• 方法: PUT 或 PATCH
• 路径: /api/yolo/models/{pk}/update/
• 认证: 不需要
• 请求类型: application/json 或 multipart/form-data
• 可更新字段: description, is_enabled,（如上传 model_file 必须为 .pt）
• 参考实现: model_update（d:\All_template\yolo\hertz_studio_django_yolo\views.py:134）
• 示例请求（PATCH）:

  PATCH /api/yolo/models/1/update/
  Content-Type: application/json
  
  {
    "description": "更新描述",
    "is_enabled": true
  }
  

• 示例响应:

  {"success": true, "code": 200, "message": "模型更新成功", "data": {"id": 1, "name": "ModelA", "is_enabled": true}}
  

（3）删除模型

• 方法: DELETE
• 路径: /api/yolo/models/{pk}/delete/
• 认证: 不需要
• 参考实现: model_delete（d:\All_template\yolo\hertz_studio_django_yolo\views.py:152）
• 示例响应:

  {"success": true, "code": 200, "message": "模型删除成功"}
  

（4）启用指定模型

• 方法: POST
• 路径: /api/yolo/models/{pk}/enable/
• 认证: 不需要
• 行为: 先禁用其他模型，再启用当前模型
• 参考实现: model_enable（d:\All_template\yolo\hertz_studio_django_yolo\views.py:165）
• 示例响应:

  {"success": true, "code": 200, "message": "模型 ModelA 已启用", "data": {"id": 1, "is_enabled": true}}
  

（5）获取当前启用的模型

• 方法: GET
• 路径: /api/yolo/models/enabled/
• 认证: 不需要
• 参考实现: model_enabled（d:\All_template\yolo\hertz_studio_django_yolo\views.py:186）
• 示例响应:

  {"success": true, "code": 200, "message": "获取启用模型成功", "data": {"id": 1, "name": "ModelA"}}
  

（6）创建模型（占位）

• 方法: POST
• 路径: /api/yolo/models/create/
• 说明: 返回 405，提示使用 /api/yolo/upload/
• 参考实现: model_create（d:\All_template\yolo\hertz_studio_django_yolo\views.py:114）

三、模型类别管理

提示：类别通常随模型上传自动导入。手动创建/删除不推荐，仅保留接口。

（1）获取类别列表

• 方法: GET
• 路径: /api/yolo/categories/
• 认证: 不需要
• 参考实现: category_list（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1301）

（2）获取类别详情

• 方法: GET
• 路径: /api/yolo/categories/{pk}/
• 认证: 不需要
• 参考实现: category_detail（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1329）

（3）更新类别

• 方法: PUT 或 PATCH
• 路径: /api/yolo/categories/{pk}/update/
• 认证: 不需要
• 请求类型: application/json
• 可更新字段: alias, alert_level（high|medium|low|none）, is_active
• 参考实现: category_update（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1342）
• 示例请求（PATCH）:

  PATCH /api/yolo/categories/10/update/
  Content-Type: application/json
  
  {"alias": "行人", "alert_level": "high", "is_active": true}
  

• 示例响应:

  {"success": true, "code": 200, "message": "更新类别成功", "data": {"id": 10, "alias": "行人", "alert_level": "high"}}
  

（4）切换类别启用状态

• 方法: POST
• 路径: /api/yolo/categories/{pk}/toggle-status/
• 认证: 不需要
• 参考实现: category_toggle_status（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1385）
• 示例响应:

  {"success": true, "code": 200, "message": "类别 'person' 启用成功", "data": {"is_active": true}}
  

（5）获取启用的类别列表

• 方法: GET
• 路径: /api/yolo/categories/active/
• 认证: 不需要
• 参考实现: category_active_list（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1405）

（6）创建类别（不推荐）

• 方法: POST
• 路径: /api/yolo/categories/create/
• 认证: 不需要
• 请求类型: application/json
• 参考实现: category_create（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1312）

（7）删除类别（不推荐）

• 方法: DELETE
• 路径: /api/yolo/categories/{pk}/delete/
• 认证: 不需要
• 参考实现: category_delete（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1362）

四、目标检测

执行检测

• 方法: POST
• 路径: /api/yolo/detect/
• 认证: 需要登录（Authorization: Bearer <token>）
• 请求类型: multipart/form-data
• 参数:
  • file: 要检测的图片或视频文件（支持图片：.jpg,.jpeg,.png,.bmp,.tiff,.webp；视频：.mp4,.avi,.mov,.mkv,.wmv,.flv）
  • model_id: 指定模型ID（可选，未提供则使用当前启用模型）
  • confidence_threshold: 置信度阈值（默认 0.5，范围 0.1-1.0）
• 参考实现: yolo_detection（d:\All_template\yolo\hertz_studio_django_yolo\views.py:446）
• 示例请求:

  curl -X POST "http://localhost:8000/api/yolo/detect/" \
    -H "Authorization: Bearer <token>" \
    -F "file=@/path/to/image.jpg" \
    -F "model_id=1" \
    -F "confidence_threshold=0.5"
  

• 示例响应:

  {
    "success": true,
    "code": 200,
    "message": "检测完成",
    "data": {
      "detection_id": 1001,
      "result_file_url": "/media/detection/result/result_xxx.jpg",
      "original_file_url": "/media/detection/original/uuid_image.jpg",
      "object_count": 3,
      "detected_categories": ["person"],
      "confidence_scores": [0.91, 0.87, 0.79],
      "avg_confidence": 0.8567,
      "processing_time": 0.43,
      "model_used": "ModelA 1.0",
      "confidence_threshold": 0.5,
      "user_id": 2,
      "user_name": "alice",
      "alert_level": "medium"
    }
  }
  

五、检测记录

（1）获取检测记录列表

• 方法: GET
• 路径: /api/yolo/detections/
• 认证: 不需要
• 查询参数:
  • type: image 或 video
  • model_id: 模型ID
  • user_id: 用户ID
• 参考实现: detection_list（d:\All_template\yolo\hertz_studio_django_yolo\views.py:204）
• 示例响应（节选）:

  {
    "success": true,
    "code": 200,
    "message": "获取检测记录列表成功",
    "data": [
      {
        "id": 1001,
        "original_file": "/media/detection/original/uuid_image.jpg",
        "result_file": "/media/detection/result/result_xxx.jpg",
        "original_filename": "uuid_image.jpg",
        "result_filename": "result_xxx.jpg",
        "detection_type": "image",
        "model_name": "ModelA 1.0",
        "model_info": {"id":1, "name":"ModelA", "version":"1.0"},
        "object_count": 3,
        "detected_categories": ["person"],
        "confidence_threshold": 0.5,
        "confidence_scores": [0.91, 0.87, 0.79],
        "avg_confidence": 0.8567,
        "processing_time": 0.43,
        "created_at": "..."
      }
    ]
  }
  

（2）获取指定用户的检测记录

• 方法: GET
• 路径: /api/yolo/detections/{user_id}/user/
• 认证: 不需要
• 查询参数同上
• 参考实现: user_detection_records（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:231）

（3）获取检测记录详情

• 方法: GET
• 路径: /api/yolo/detections/{pk}/
• 认证: 不需要
• 参考实现: detection_detail（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:253）

（4）删除检测记录

• 方法: DELETE
• 路径: /api/yolo/detections/{pk}/delete/
• 认证: 不需要
• 行为: 同时删除其关联的原始文件、结果文件及关联的告警
• 参考实现: detection_delete（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:265）
• 示例响应:

  {"success": true, "code": 200, "message": "检测记录删除成功"}
  

（5）批量删除检测记录

• 方法: POST
• 路径: /api/yolo/detections/batch-delete/
• 认证: 不需要
• 请求类型: application/json
• 请求体:

  {"ids": [1001, 1002, 1003]}
  

• 参考实现: detection_batch_delete（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:299）
• 示例响应:

  {
    "success": true,
    "code": 200,
    "message": "成功删除 3 条检测记录",
    "data": {
      "deleted_count": 3,
      "found_ids": ["1001","1002","1003"],
      "not_found_ids": []
    }
  }
  

（6）检测统计

• 方法: GET
• 路径: /api/yolo/stats/
• 认证: 不需要
• 参考实现: detection_stats（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:840）

六、告警记录

（1）获取告警记录列表（管理员）

• 方法: GET
• 路径: /api/yolo/alerts/
• 认证: 不需要
• 查询参数:
  • status: 默认 pending；传 all 表示不过滤
  • level: 告警等级（high|medium|low|none）
  • user_id: 用户ID
  • alter_category: 告警类别关键字（注意字段名为 alter_category）
• 参考实现: alert_list（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:358）

（2）获取用户的告警记录

• 方法: GET
• 路径: /api/yolo/users/{user_id}/alerts/
• 认证: 需要登录（仅本人或管理员可查）
• 查询参数:
  • status: pending|is_confirm|false_positive|all
  • level: high|medium|low|none
  • category: 类别关键字
• 参考实现: user_alert_records（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:391）

（3）更新告警状态

• 方法: PUT 或 PATCH
• 路径: /api/yolo/alerts/{pk}/update-status/
• 认证: 不需要
• 请求类型: application/json
• 请求体:

  {"status": "is_confirm"}
  

• 可选值: pending, is_confirm, false_positive
• 参考实现: alert_update_status（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:426）
• 示例响应:

  {
    "success": true,
    "code": 200,
    "message": "更新告警状态成功",
    "data": {
      "id": 555,
      "status": "is_confirm",
      "alert_level": "medium",
      "alert_category": "person",
      "alert_level_display": "中"
    }
  }
  

七、备注

• 所有文件型字段响应通常包含可直接访问的媒体 URL，媒体服务由 MEDIA_URL=/media/ 提供。
• 分类的告警等级枚举参考 ModelCategory.ALERT_LEVELS 与 Alert.ALERT_LEVELS（d:\AllTemplate\yolo\hertz_studio_django_yolo\models.py:118,153）。
• 检测请求的文件大小限制：图片 ≤ 50MB，视频 ≤ 500MB（d:\AllTemplate\yolo\hertz_studio_django_yolo\serializers.py:99）。