SAM 3 (sam3)

以 Markdown 查看在 Playground 中试用即将推出

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


模型 ID	`sam3`（`POST /v1/refine` 的默认模型）
模型	SAM 3（Meta）
权重	Meta 发布的官方 SAM 3 权重（`facebook/sam3`）
用例	概念分割、交互分割
接口	`POST /v1/segment`、`POST /v1/refine`
模型池	付费池：从余额中扣费
计费单位	`encode_image`（缓存命中时减免）、`prompt`、`point`、`refine`。单位与价格：计费
许可证	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）按需返回，详见后处理。概念实例的 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）用于筛选和限制实例。详见后处理。

用例说明与调用示例：概念分割。

交互分割

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 的对比：交互分割。

用例说明与调用示例：交互分割。

限制与说明

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