# 概念分割

概念分割为某一概念的每个实例返回一个蒙版：街景中的所有汽车、摊位上的所有李子、所有与框选样例相似的物体。实例数量事先未知，调用方也不逐个标记。典型用途包括计数、数据集自动标注，以及先找出某一类的全部物体再做筛选。如需分割由调用方用点、框或点选标出的物体，请参阅[交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/)。

## 文本提示

文本提示以 1 至 200 个字符给出一个概念。图片中该概念的每个实例都作为单独的蒙版返回，并附带分数。一次调用可以包含多个提示，图片只编码一次（见 [SAM 调用如何计费](https://stack.foldbun.com/zh/docs/billing/#sam-调用如何计费)）。

![街景图片：提示 "car" 对应 9 辆车的蓝色蒙版，提示 "person" 对应 18 个人的青色蒙版。](../../../../../assets/docs/sam3-text-prompts.webp)

*`sam3`：提示 `car` 和 `person` 的 Playground 录制结果。每个蒙版对应 `instances` 中的一项，按 `prompt` 着色。*

## 样例框

样例框为围绕一个物体的 `[x1, y1, x2, y2]`。只含框时，`sam3` 返回框内的物体以及与之相似的物体：调用中的所有框合成一个视觉查询。框和文本提示可以混用，此时这些框作用于同一调用中的每个文本提示。样例框适合难以命名或有大量相似物体的情形，例如下图中的水果。

![水果摊：一个李子周围有一个绿色样例框，90 个李子上有青色蒙版。](../../../../../assets/docs/sam3-exemplar-boxes.webp)

*`sam3`：单个样例框（绿色轮廓）的 Playground 录制结果。90 个蒙版的 `label` 为 `_exemplar`，图例中的 "exemplar box" 即指此值。*

`positive` 默认为 `true`，表示“找出更多类似的”。设为 `"positive": false` 时，该框为负样例框（“不要这样的”）：与框内物体相似的物体会被排除。负框用于修整每个文本提示的查询，或只含框时的查询。只含框的调用至少需要一个正样例框，框全部为负的调用需要有文本提示。点不计入：只与点并存的负框不被接受。样例框最多 10 个。

## 与点提示混用

一次调用还可以包含点提示。每个点恰好返回一个物体，即点所在位置的最佳蒙版，其实例没有 `label`。点不受 `filter`、`nms`、`options.maxInstances` 和样例框影响。点提示的详细说明见[用点标出物体](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/#用点标出物体)。

## 过滤、限制与合并

分数低于 `filter.minScore`（默认 0.5）的实例被丢弃，最多返回 `options.maxInstances`（默认 100）个搜索实例。尺寸与面积过滤、重叠去除（`nms`）、碎片清理和按 `group` 合并同样是选项，可在 `options.defaults` 中为整个调用设置，也可在 `prompts[].options` 中为单个提示设置。`dropStats` 报告每个提示丢失了什么。全部选项、处理顺序和限制见[后处理](https://stack.foldbun.com/zh/docs/post-processing/)。

## 支持的模型

概念提示仅由 [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/#概念分割) 提供；`sam-lite` 既不接受文本提示，也不接受样例框。

| | [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/#概念分割) |
|---|---|
| 模型 | SAM 3 |
| 接受 | 文本提示（1 至 200 个字符）、样例框（正向或负向）、点 |
| 返回 | 每个匹配一个实例，标注为提示文字或 `_exemplar` |
| 标价（额度） | 图片编码每张 0.5 + 每个文本提示 0.05（样例框不另外收费；只含框的调用计为一次提示），每个点 0.02 |
| 模型池 | 付费池：从余额中扣费 |
| 录制的处理时间 | 约 390 至 560 ms（录制的概念提示调用） |

`sam3` 如何得出这些结果，见[工作原理](https://stack.foldbun.com/zh/docs/models/sam3/#工作原理)。

## 调用示例

在第一张图的街景上使用文本提示 `car` 和 `person`，发送到 `POST /v1/segment`：

```bash
curl https://api.stack.foldbun.com/v1/segment \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sam3",
    "image": { "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2" },
    "prompts": [{ "text": "car" }, { "text": "person" }]
  }'
```

以下响应有删减：实例列表和多边形环已缩短。

```json
{
  "id": "call_01a1913c-25a0-73fd-a074-7a6ac6154590",
  "model": "sam3",
  "image": {
    "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2",
    "width": 1343,
    "height": 1008,
    "bytes": 388375,
    "contentType": "image/jpeg"
  },
  "instances": [
    {
      "prompt": 0,
      "label": "car",
      "score": 0.9696,
      "bbox": [0, 716, 207, 889],
      "area": 14261,
      "polygon": [
        { "outer": [0, 888, 0, 762, 41, 744, 96, 718, 158, 724, 206, 781, 206, 888] }
      ]
    }
  ],
  "cache": "miss",
  "imageFee": 0.5,
  "cost": 0.6,
  "balance": 998.4,
  "timing": { "queueMs": 0, "processingMs": 473 },
  "billing": {
    "lines": [
      { "unit": "encode_image", "quantity": 1, "unitPrice": 0.5, "amount": 0.5, "waived": false },
      { "unit": "prompt", "quantity": 2, "unitPrice": 0.05, "amount": 0.1, "waived": false }
    ],
    "total": 0.6,
    "charged": true,
    "pool": null
  }
}
```

### 响应解读

- `instances` 为每个匹配一项：图中有 9 辆车和 18 个人，JSON 只显示第一项。`prompt` 是 `prompts` 中的索引（0 为 `car`），`label` 重复提示文字；样例框产生的实例，`label` 为 `_exemplar`。
- `score` 为 0.9696，是该实例的检测置信度，范围 0 至 1。
- `bbox` 和 `polygon` 的单位为摆正后的原图的像素，此处为 1343 × 1008（`image.width`、`image.height`）。`bbox` 为 `[x1, y1, x2, y2]`，x2 和 y2 不包含在内；`area` 为物体的像素面积。`polygon` 是按面积从大到小排列的部分列表：每个部分有 `outer` 环，物体有洞时还有 `holes`，均为扁平整数数组 `[x0, y0, x1, y1, ...]`。像素蒙版只在请求时返回（见[后处理](https://stack.foldbun.com/zh/docs/post-processing/#多边形coco-还是-webp)和[图片](https://stack.foldbun.com/zh/docs/images/#蒙版)）。
- `dropStats`（此处未显示）按提示列出被丢弃的候选数量及原因。没有丢弃任何实例时为空数组。
- `cache` 为 `miss`，`imageFee` 为 0.5：图片在本次调用中完成编码。对同一图片的后续调用，例如点选修整，通常返回 `hit`，`imageFee` 为 0。
- `billing.lines` 中 `encode_image` 出现一次，`prompt` 的 `quantity` 为 2，对应两个文本提示。`charged` 为 `true`，`pool` 为 `null`，因此 `cost` 等于 `total`，并已从 `balance` 中扣除。

全部字段：[API 参考](https://stack.foldbun.com/zh/docs/api/operations/segment/)。

**本次调用的费用。** 新图片为 0.5（`encode_image`）+ 2 × 0.05（`prompt`）= 0.60 额度，与本响应的实际扣费一致；编码已缓存时为 0.10 额度。单价见[计费](https://stack.foldbun.com/zh/docs/billing/#价目表)。

## 接口与参考

| 接口 | 在本用例中 | 参考 |
|---|---|---|
| `POST /v1/segment` | 根据 1 至 50 个提示找出某一概念的全部实例：文本提示、样例框，以及可选的点 | [API 参考](https://stack.foldbun.com/zh/docs/api/operations/segment/) |

- [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/)：模型的工作原理、限制和实测延迟。
- [SAM 调用如何计费](https://stack.foldbun.com/zh/docs/billing/#sam-调用如何计费)：计费单位与计费示例，包括带样例框的提示。
- [交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/)：使用 `sam3` 或 `sam-lite`，通过点、框和点选分割单个物体。