169 lines
4.0 KiB
Markdown
169 lines
4.0 KiB
Markdown
# 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 编码
|
|
- 请求体更小
|
|
- 更适合大图片场景
|