# SAM 2.1 Hiera-S (sam-lite)

`sam-lite` 即 SAM 2.1 Hiera-S，是 Meta 发布的 Segment Anything Model 2.1 的小型版本。它根据框或点，每个提示分割一个物体，价格低于 `sam3`，并包含在免费池中。它不接受文本提示，也没有“找出更多类似的”模式。

| | |
|---|---|
| 模型 ID | `sam-lite` |
| 模型 | SAM 2.1 Hiera-S（Meta） |
| 权重 | Meta 发布的官方 SAM 2.1 Hiera-S 检查点 |
| 用例 | [交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/) |
| 接口 | `POST /v1/segment`、`POST /v1/refine` |
| 模型池 | 免费池（首次储值后）：每个 UTC 日的前 1,000 次调用免费，超出部分从余额中扣费 |
| 计费单位 | `encode_image`（缓存命中时减免）、`box`、`point`、`refine`。单位与价格：[计费](https://stack.foldbun.com/zh/docs/billing/#价目表) |
| 许可证 | Apache-2.0 |

## 工作原理

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

**图片编码。** 图片被缩放到 1024 × 1024 像素，送入 Hiera-S 图片编码器，即一个把图片转换为特征图的层次化视觉 Transformer。每次调用计费一次，计为 `encode_image`。编码结果按账户和图片缓存，保留方式为尽力而为，最长保留 7 天；之后的调用在缓存中找到该编码时，跳过这一阶段，编码费减免。缓存的编码以紧凑方式存储，因此缓存命中时的结果与重新编码的结果可能有极细微的差异。

**提示。** 轻量的提示编码器把点和框转换为嵌入，轻量的蒙版解码器生成蒙版。`/v1/segment` 调用中的各个提示会成批送入解码器，但每个提示各自得到一个蒙版，所以每个提示都要计费（`point` 或 `box`）。每个蒙版还需要后处理，即放大到图片尺寸并描绘多边形，这部分工作随图片尺寸增大。单个点本身存在歧义，因此解码器为它预测 3 个候选蒙版，并返回预测 IoU 最高的一个；实例的 `score` 即该预测 IoU。

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

## 各用例下的特性

### 交互分割

- **`POST /v1/segment`** 接受 `box`（框内的物体）和 `point`（点所在的物体）提示，可在一次调用中混用，每个提示恰好返回一个实例。每个实例包含 `prompt`、`score`、`bbox`、`area` 和 `polygon`，没有 `label`。
- `sam-lite` 不使用 `positive`：框始终标出物体，点始终为正向。负点用于 `POST /v1/refine`。
- 不接受文本提示和样例框，也没有“找出更多类似的”模式。概念提示由 [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/#概念分割) 提供。
- 每个提示都是物体提示，因此总是返回：`filter`、`nms` 和 `options.maxInstances` 不适用。`cleanup`、几何输出选项和 `merge` 适用，详见[后处理](https://stack.foldbun.com/zh/docs/post-processing/)。
- **`POST /v1/refine`** 为一个物体接受最多 20 个正负点和一个可选的框。响应包含最佳蒙版；设置 `options.multimask` 时包含最多 3 个候选蒙版。整个调用是一次解码。该调用为交互优先级，截止时间为 2 秒。

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

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

### 概念分割

不支持。`sam-lite` 既不接受文本提示，也不接受样例框。如需找出某一概念的全部实例，请使用 [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/#概念分割)。

## 限制与说明

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