---
library_name: "fastforks"
pipeline_tag: "mask-generation"
license: "other"
license_name: "sam-license"
license_link: "https://huggingface.co/facebook/sam3/blob/main/LICENSE"
tags:
- "promptable_segmentation"
- "segment-anything"
- "promptable-segmentation"
- "cuda"
- "pytorch"
- "fastforks"
---
# Segment Anything 3 (SAM 3), image (fastforks)

Segment Anything 3 (Meta, 2025), image mode: promptable concept segmentation, every instance matching a text and / or exemplar-box prompt (positive / negative boxes; returns boxes, scores, masks). A ViT trunk with an FPN neck, a CLIP text encoder, a geometry encoder, a DETR encoder / decoder with a presence token and a mask decoder (no video tracker). The portable `module()` is the image encoder only.

This repo is the model card only: it holds no weights. fastforks downloads the authors' weights from the links below and checks them against the SHA-256 in the model card. Code: <https://github.com/kleinicke/fastforks>. Kernels for the `kernels` backend: <https://huggingface.co/fastforks/kernels>. Original code: <https://github.com/facebookresearch/sam3> at `0570b3a`.

Author weight repos: <https://huggingface.co/facebook/sam3>.

Task: promptable_segmentation. Tier: stable. Outputs: `boxes`, `scores`, `masks`. Backends: `portable`, `kernels`.

Input: one image plus a point, box or text prompt. Output: masks with quality scores.

## Variants

Weights are the authors' files (not hosted here). SHA-256 shortened to 12 hex digits; the full hashes are in [`card.toml`](https://github.com/kleinicke/fastforks/blob/main/src/fastforks/promptable_segmentation/models/sam3/card.toml).

| variant | weights (author link) | SHA-256 | weights licence | commercial use |
|---|---|---|---|---|
| `sam3@1` | [model.safetensors](https://huggingface.co/facebook/sam3/resolve/3c879f39826c281e95690f02c7821c4de09afae7/model.safetensors)<br>[vocab.json](https://huggingface.co/facebook/sam3/resolve/3c879f39826c281e95690f02c7821c4de09afae7/vocab.json)<br>[merges.txt](https://huggingface.co/facebook/sam3/resolve/3c879f39826c281e95690f02c7821c4de09afae7/merges.txt) | `6d06f0a5f84e`<br>`5047b556ce86`<br>`9fd691f7c803` | LicenseRef-SAM-License | yes |

## Licence

Original-code strings, recorded as they are (research-use package; check them before any other use). Code: LicenseRef-SAM-License AND Apache-2.0. Files: `LICENSE`, `LICENSE-transformers`.

Training data: the SA-Co data engine's image and video annotations plus public and internal datasets per the paper; not released as one dataset.

- Licence note: The weights use Meta's SAM License, not Apache-2.0; its terms were not re-checked here.

Licence evidence: https://huggingface.co/facebook/sam3/blob/main/LICENSE (SAM License, Nov 19 2025); the weights are gated: download them from Meta's Hugging Face repo after accepting the licence and point FASTFORKS_WEIGHTS_PATH at the local copy; fastforks never mirrors them

## Input size

any H x W >= 1, resized inside to the fixed encoder input 1008x1008 (the default export size)
Tested up to (portable, fp16, RTX 5060 Ti 16 GB): `sam3` 1080x1920 (1.9 GiB peak allocated, 2.1 reserved)

## Speed and memory

### Promptable segmentation, synthetic, 1024x1024

| model | time (ms): original fp32 | original | portable | kernels | kernels speed-up: vs original | vs portable | peak memory (MiB, allocated / reserved): original | portable | kernels |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `sam3` | 695 | 281 | 179 | 116 | 2.4x | 1.5x | 5255 / 5334 | 1922 / 2004 | 2019 / 2264 |

### Startup and first call

| model | load (s): original | portable | kernels | first call (s): original | portable | kernels |
| --- | --- | --- | --- | --- | --- | --- |
| `sam3` | 1.12 (840x1297) | 2.95 | 0.70† | 0.96 (840x1297) | 0.18† | 0.12† |

### torch.compile and TensorRT

| model | input | portable ms | compile ms | compile s (cold) | TensorRT fp16 ms | ONNX + build s | kernels ms | peak MiB (alloc / reserved): portable | compile | TensorRT (device) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `sam3` | 1024x1024 | 179 | 168.2 | 20.0 | 89.5 | 54 | 116 | 1922 / 2004 | 1910 / 2004 | 1122 |

### Fixed-size speed and peak memory, all models

| model | mode | 480x640 | 720x1280 | 1080x1920 | 12 MP 3000x4000 |
| --- | --- | --- | --- | --- | --- |
| `sam3` | portable | 179.8 ms / 1928 / 2196 | 181.5 ms / 1935 / 2208 | 182.6 ms / 1948 / 2192 | - |
| `sam3` | kernels | 116.3 ms / 2052 / 2460 | 116.5 ms / 2059 / 2420 | 116.9 ms / 2072 / 2490 | - |

Fixed-size cells: time (ms) / peak allocated / peak reserved memory (MiB).

Hardware, protocol and caveats: [benchmarks](https://github.com/kleinicke/fastforks/blob/main/docs/benchmarks.md) (RTX 5060 Ti 16 GB, sm_120). Original = the authors' code at the precision of portable (fp16, or `(fp32)` where fp16 is unsupported or not finite); original fp32 = its default fp32 run. Peak memory is the torch allocator's.

## Accuracy

### Parity with the original code

Every variant is checked against reference outputs of the original code at its pinned commit. CPU, float32: max |diff| <= 0.0005 vs the original. GPU, float16 (the default), portable and kernels: mean |diff| <= 0.35 and p99 <= 2.0 (absolute error of the output `boxes`).

## Usage

```python
from fastforks import promptable_segmentation

model = promptable_segmentation.load("sam3")  # mode="auto": the preferred backend from recorded measurements
result = model("photo.jpg", text="coin")  # a concept: every instance of it; or input_boxes= exemplar boxes
result.boxes, result.scores, result.masks  # [N, 4], [N], [N, H, W] bool
result.backend  # what ran, e.g. Backend(mode='portable', device='cuda:0', dtype='float16')
```

Install with `pip install fastforks` (see <https://github.com/kleinicke/fastforks>). Other variants: `sam3`.

## Kernels backend

`promptable_segmentation.load("sam3", mode="kernels")` runs our CUDA kernels (`fastbb`, `cudnn_hacc`). It needs a prebuilt kernel for your GPU architecture (downloaded from <https://huggingface.co/fastforks/kernels> on first use) and a recent NVIDIA driver; if there is none it raises `BackendUnavailableError` with the reason and never falls back silently. `mode="auto"` picks `kernels` when it can run and logs the choice.

<!-- staged from fastforks feccac41 (2026-11-06) -->