model_train_dm/sam_infer_polygon_http1_API.md

sam_infer_polygon_http1.py 接口说明

1. 服务说明

该服务用于通过 HTTP 上传图片并进行目标识别，返回标注框坐标或多边形标注点。

• 健康检查：GET /health
• 推理接口：POST /infer

默认监听地址：

http://172.16.31.195:8090/infer

2. 推理接口

2.1 请求地址

POST /infer

2.2 支持的请求方式

当前支持两种传图方式：

1. multipart/form-data 上传图片文件，推荐
2. application/json 传 image_base64

同时保留了旧的 image_path 方式兼容，但建议后续统一切到 HTTP 上传。

3. 请求参数

3.1 公共参数

参数名	类型	必填	说明
label_content	string	是	标签信息。可以直接传字符串，如 fish，也可以传 JSON 字符串，如 [{"label":"fish","name":"鱼","color":"#409eff"}]
text_prompt	string	否	检测提示词。未传时会尝试从 label_content 中解析
type	int	否	返回类型，0 返回框坐标，1 返回多边形点位
score_threshold	float	否	置信度过滤阈值，大于该值的结果才会返回

3.2 multipart/form-data 额外参数

参数名	类型	必填	说明
image_file	file	是	上传的图片文件
image_name	string	否	自定义图片名称，不传则使用上传文件名

说明：

• 文件字段也兼容 image 或 file

3.3 JSON 传图参数

参数名	类型	必填	说明
image_base64	string	是	图片的 Base64 内容，支持纯 Base64 或 Data URL
image_name	string	否	图片名称

4. 请求示例

4.1 multipart/form-data 示例

curl -X POST "http://127.0.0.1:8090/infer" \
  -H "Content-Type: multipart/form-data" \
  -F "image_file=@D:/AI-TrainPrediction/AI-TrainPrediction/backend/test/1.jpg" \
  -F "label_content=[{\"label\":\"fish\",\"name\":\"鱼\",\"color\":\"#409eff\"}]" \
  -F "text_prompt=fish" \
  -F "type=0" \
  -F "score_threshold=0.2"

4.2 JSON Base64 示例

{
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "image_name": "demo.jpg",
  "label_content": "[{\"label\":\"fish\",\"name\":\"鱼\",\"color\":\"#409eff\"}]",
  "text_prompt": "fish",
  "type": 0,
  "score_threshold": 0.2
}

5. 返回格式

接口返回 JSON Array，每一项表示一个识别结果。

5.1 type=0 返回框坐标

[
  {
    "label": "fish",
    "name": "鱼",
    "color": "#409eff",
    "bbox_xyxy": [125.34, 80.12, 365.78, 240.66],
    "region": [
      ["125.34", "80.12"],
      ["365.78", "240.66"]
    ],
    "score": 0.9345
  }
]

字段说明：

字段名	类型	说明
label	string	标签编码
name	string	标签名称
color	string	标注颜色
bbox_xyxy	number[]	标注框坐标，格式为 [x1, y1, x2, y2]
region	string[][]	兼容旧格式的框坐标，格式为 [[x1, y1], [x2, y2]]
score	float	置信度

5.2 type=1 返回多边形点位

[
  {
    "label": "fish",
    "name": "鱼",
    "color": "#409eff",
    "bbox_xyxy": [125.34, 80.12, 365.78, 240.66],
    "region": [
      ["126.00", "82.00"],
      ["140.50", "79.20"],
      ["168.30", "81.60"]
    ],
    "score": 0.9345
  }
]

说明：

• type=1 时，region 为多边形点坐标
• bbox_xyxy 仍然会返回，方便前端或调用方直接绘制检测框

6. 错误返回示例

{
  "ok": false,
  "error": "image_file or image_base64 is required, image_path is only kept for compatibility"
}

常见错误：

• invalid image_base64
• request body must be valid JSON or multipart/form-data
• label_content and text_prompt are required
• image_path not found

7. 建议调用方式

推荐优先使用 multipart/form-data 上传图片文件：

• 不需要额外做 Base64 编码
• 请求体更小
• 更适合大图片场景