# SAM 3 (sam3)

`sam3` 即 Meta 发布的 SAM 3（Segment Anything Model 3）。它按概念分割：简短的文本提示或样例框会为图片中每个匹配的实例返回一个蒙版。它也能分割调用方用点、框或点选标出的单个物体。Stack 在同一份图片编码上运行 SAM 3 的概念检测器和单物体跟踪器，因此对同一图片的概念调用和点选调用可以复用同一份缓存的编码。

| | |
|---|---|
| 模型 ID | `sam3`（`POST /v1/refine` 的默认模型） |
| 模型 | SAM 3（Meta） |
| 权重 | Meta 发布的官方 SAM 3 权重（`facebook/sam3`） |
| 用例 | [概念分割](https://stack.foldbun.com/zh/docs/use-cases/concept-segmentation/)、[交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/) |
| 接口 | `POST /v1/segment`、`POST /v1/refine` |
| 模型池 | 付费池：从余额中扣费 |
| 计费单位 | `encode_image`（缓存命中时减免）、`prompt`、`point`、`refine`。单位与价格：[计费](https://stack.foldbun.com/zh/docs/billing/#价目表) |
| 许可证 | SAM License |

## 工作原理

一次调用分为两个阶段：图片只编码一次，之后每个提示各自单独解码。计费与这两个阶段对应。

**图片编码。** 图片被缩放到 1008 × 1008 像素，送入图片编码器，即一个把图片转换为特征图的视觉 Transformer（ViT）主干。这是工作量最大的部分，每次调用计费一次，计为 `encode_image`。编码结果按账户和图片缓存，保留方式为尽力而为，最长保留 7 天；之后的调用在缓存中找到该编码时，跳过这一阶段，编码费减免。SAM 3 的概念检测器和单物体跟踪器读取同一份编码，因此对同一图片的概念调用和点选调用可以共用一条缓存。缓存的编码以紧凑方式存储，因此缓存命中时的结果与重新编码的结果可能有极细微的差异。

**概念提示。** 每个文本提示是概念检测器的一次解码。样例框本身不单独解码：调用中的所有框，无论正负，都会加入每个文本提示的查询。只有框而没有文本提示的调用，把全部框合成一个视觉查询，计为一次解码。解码时，融合编码器让 72 × 72 = 5,184 个图像 token 以查询为条件，带有 200 个对象查询的 DETR 风格解码器提出候选实例，蒙版头为每个候选生成蒙版，存在性分数对结果把关，因此图片中不存在的概念不会返回任何内容。整个解码对每个查询重新运行一次，所以每个文本提示都要计费（`prompt`），只含框的调用计费一次。样例框不另外收费，因为它们属于每个文本提示的解码。文本提示的长度不影响价格：文本编码器的输出按字符串缓存，任何提示的解码代价相同。

**点提示。** `POST /v1/segment` 中的每个点提示是单物体跟踪器的一次解码：点被编码为提示，蒙版解码器返回该物体的最佳蒙版。因此每个点计为一次 `point`，其实例没有 `label`。

**修整。** `POST /v1/refine` 是针对一个物体的一次跟踪器解码。全部点和可选的框都是这同一次推理的输入，所以无论带多少个点，调用只计费一次，计为 `refine`。设置 `options.multimask` 时，同一次推理返回最多 3 个候选蒙版。

每个实例默认带有图片像素坐标下的含洞简化多边形；像素蒙版（COCO RLE 或无损 WebP）按需返回，详见[后处理](https://stack.foldbun.com/zh/docs/post-processing/)。概念实例的 `score` 为检测置信度；点实例和修整实例的 `score` 为蒙版的预测 IoU。

## 各用例下的特性

### 概念分割

`POST /v1/segment`，使用文本提示、样例框或两者兼用。实例数量事先未知。

- 文本提示以 1 至 200 个字符给出一个概念。该概念的每个实例都作为单独的物体返回，并附带分数，`label` 为提示文字。
- 样例框为围绕一个物体的 `[x1, y1, x2, y2]`，返回框内的物体以及与之相似的物体（"找出更多类似的"），`positive` 默认为 `true`；设为 `positive: false` 时，该框为负样例框（“不要这样的”）。调用中的所有样例框，无论正负，都会作用于同一调用中的每个文本提示。没有文本提示时，所有框合成一个视觉查询，其实例的 `label` 为 `_exemplar`，该查询至少需要一个正样例框。框全部为负的调用需要有文本提示；点不计入。框和文本提示可以混用。样例框适合难以命名或有大量相似物体的情形。
- `filter.minScore`（默认 0.5）、尺寸与面积过滤、`nms` 和 `options.maxInstances`（1 至 300，默认 100）用于筛选和限制实例。详见[后处理](https://stack.foldbun.com/zh/docs/post-processing/)。

用例说明与调用示例：[概念分割](https://stack.foldbun.com/zh/docs/use-cases/concept-segmentation/)。

### 交互分割

`sam3` 有两种方式标出单个物体。

- **`POST /v1/segment` 中的点。** 提示 `{ "point": { "x", "y" } }` 恰好返回一个实例，即点所在物体的最佳蒙版。该实例没有 `label`，其 `score` 为预测 IoU。点只能是正向标记；负点用于 `POST /v1/refine`。点可以与文本提示和样例框在同一调用中混用。`filter`、`nms` 和 `options.maxInstances` 不作用于点实例，样例框从不影响点。
- **`POST /v1/segment` 中的框不用于标出物体。** 它仍是样例框，同时会返回相似物体。如需分割框内的单个物体，请将框发送到 `POST /v1/refine`。
- **`POST /v1/refine` 中的点选和框。** 最多 20 个正负点和一个可选的框描述同一个物体。响应包含最佳蒙版；设置 `options.multimask` 时包含最多 3 个候选蒙版。整个调用是一次解码。该调用为交互优先级，截止时间为 2 秒。`sam3` 是该接口的默认模型。

与 [`sam-lite`](https://stack.foldbun.com/zh/docs/models/sam-lite/) 的对比：[交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/#支持的模型)。

用例说明与调用示例：[交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/)。

## 限制与说明

- 每次分割调用 1 至 50 个提示，文本提示、样例框和点合计，点没有单独的上限。最多 10 个样例框。一次调用至少需要一个文本提示、正样例框或点；框全部为负的调用需要有文本提示。文本提示 1 至 200 个字符。`options.maxInstances` 最大为 300。
- 每次修整调用最多 20 个点，且至少有一个点或一个框。
- 框和点的坐标须为非负数，并位于图片之内。
- 图片限制：详见[图片](https://stack.foldbun.com/zh/docs/images/)。所有坐标均为摆正后的原图的像素。多边形和框使用图片像素。按需返回的蒙版位于长边不超过 `options.maskSize`（默认 2048 px）的网格上：应按 `mask.size` 缩放。
- 延迟：Playground 录制的调用中，`timing.processingMs` 约在 390 至 560 ms 之间。该数值取决于图片、排队情况和节点负载，不作保证。