# sam_infer_polygon_http1.py 接口说明

## 1. 服务说明

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

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

默认监听地址：

```bash
http://172.16.31.195:8090/infer
```

## 2. 推理接口

### 2.1 请求地址

```http
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 示例

```bash
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 示例

```json
{
  "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` 返回框坐标

```json
[
  {
    "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` 返回多边形点位

```json
[
  {
    "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. 错误返回示例

```json
{
  "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 编码
- 请求体更小
- 更适合大图片场景