File size: 11,056 Bytes
ba6c3fe
 
 
 
 
 
 
 
 
 
 
7e01c43
ba6c3fe
f947a8a
ba6c3fe
f947a8a
ba6c3fe
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7e01c43
ba6c3fe
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f947a8a
 
 
 
ba6c3fe
 
 
 
 
f947a8a
 
 
 
ba6c3fe
 
 
f947a8a
 
 
 
 
 
ba6c3fe
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f947a8a
ba6c3fe
 
 
f947a8a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ba6c3fe
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7e01c43
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
---
library_name: "fastforks"
pipeline_tag: "mask-generation"
license: "apache-2.0"
tags:
- "promptable_segmentation"
- "segment-anything"
- "promptable-segmentation"
- "cuda"
- "pytorch"
- "fastforks"
- "fastforks-card"
---
# Segment Anything 2.1 (SAM 2.1) (fastforks)

Segment Anything 2.1 (Ravi et al. 2024), image mode: promptable segmentation with a hierarchical Hiera image encoder, an FPN neck and the SAM prompt encoder / mask decoder with high-resolution skip features; masks from points, boxes and mask logits. `video` follows objects prompted on the first frame through a video with the original memory attention / memory encoder (`SAM2VideoPredictor`, forward, memory features in bfloat16 as upstream); the memory side has no fused kernels yet. Option `samurai` tracks as SAMURAI (Yang et al. 2024: a Kalman filter on the mask box picks among the multimask outputs, and the memory keeps only confident frames); upstream SAMURAI tracks one object, here every object has its own filter and memory. 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/sam2> at `2b90b9f`.

Task: promptable_segmentation. Tier: stable. Outputs: `pred_masks`, `iou_scores`. 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/sam2/card.toml).

| variant | weights (author link) | SHA-256 | weights licence | commercial use |
|---|---|---|---|---|
| `sam2.1-hiera-base-plus@1` | [sam2.1_hiera_base_plus.pt](https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_base_plus.pt) | `a2345aede871` | Apache-2.0 | yes |
| `sam2.1-hiera-large@1` | [sam2.1_hiera_large.pt](https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_large.pt) | `2647878d5dfa` | Apache-2.0 | yes |
| `sam2.1-hiera-small@1` | [sam2.1_hiera_small.pt](https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_small.pt) | `6d1aa6f30de5` | Apache-2.0 | yes |
| `sam2.1-hiera-tiny@1` | [sam2.1_hiera_tiny.pt](https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_tiny.pt) | `7402e0d864fa` | Apache-2.0 | yes |

## Licence

Original-code strings, recorded as they are (research-use package; check them before any other use). Code: Apache-2.0. Licence files: `LICENSE`.

Training data: SA-1B and the SA-V video dataset (plus internal data) per the paper; SA-V itself is under CC BY 4.0, SA-1B under its research licence.

Licence evidence: https://github.com/facebookresearch/sam2/blob/main/README.md (License section: model checkpoints and code under Apache 2.0)

## Input size

any H x W >= 1, resized inside to the fixed encoder input 1024x1024 (the default export size)
Tested up to (portable, fp16, RTX 5060 Ti 16 GB): `sam2.1-hiera-base-plus` 1080x1920 (0.4 GiB peak allocated, 0.6 reserved); `sam2.1-hiera-large` 1080x1920 (0.7 GiB peak allocated, 0.9 reserved); `sam2.1-hiera-small` 1080x1920 (0.3 GiB peak allocated, 0.4 reserved); `sam2.1-hiera-tiny` 1080x1920 (0.3 GiB peak allocated, 0.4 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 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `sam2.1-hiera-base-plus` | 107 | 47.2 | 32.0 | 25.1 | 1.9x | 1.3x | 823 / 870 | 412 / 464 | 426 / 524 |
| `sam2.1-hiera-large` | 242 | 86.4 | 68.0 | 48.8 | 1.8x | 1.4x | 1656 / 1724 | 742 / 768 | 760 / 828 |
| `sam2.1-hiera-small` | 74.8 | 41.8 | 18.8 | 15.6 | 2.7x | 1.2x | 618 / 662 | 318 / 366 | 330 / 386 |
| `sam2.1-hiera-tiny` | 66.3 | 38.0 | 16.6 | 13.9 | 2.7x | 1.2x | 577 / 636 | 304 / 382 | 316 / 362 |

### Startup and first call

| model | load (s): original | portable | kernels | first call (s): original | portable | kernels |
| --- | --- | --- | --- | --- | --- | --- |
| `sam2.1-hiera-base-plus` | 0.74 | 0.43 | 0.19† | 0.14 | 0.03† | 0.03† |
| `sam2.1-hiera-large` | 1.95 | 1.10 | 0.39† | 0.18 | 0.07† | 0.05† |
| `sam2.1-hiera-small` | 0.48 | 0.36 | 0.13† | 0.14 | 0.02† | 0.02† |
| `sam2.1-hiera-tiny` | 0.41 | 0.25 | 0.11† | 0.15 | 0.02† | 0.01† |

### torch.compile and TensorRT

| model | input | time: portable | compile | TensorRT fp16 | kernels | preparation: compile (cold first call) | ONNX + engine build | peak MiB (alloc / reserved): portable | compile | kernels | TensorRT (engine + torch) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `sam2.1-hiera-base-plus` | 1024x1024 | 32.0 ms | 26.4 ms | 16.7 ms (image encoder only) | 25.1 ms | 28.3 s | 43.7 s | 412 / 464 | 365 / 404 | 426 / 524 | 588 / 620 |
| `sam2.1-hiera-large` | 1024x1024 | 68.0 ms | 59.5 ms | 38.1 ms (image encoder only) | 48.8 ms | 38.9 s | 55.3 s | 742 / 768 | 678 / 748 | 760 / 828 | 1212 / 1232 |
| `sam2.1-hiera-small` | 1024x1024 | 18.8 ms | 14.9 ms | 9.93 ms (image encoder only) | 15.6 ms | 24.5 s | 40.2 s | 318 / 366 | 283 / 326 | 330 / 386 | 429 / 452 |
| `sam2.1-hiera-tiny` | 1024x1024 | 16.6 ms | 14.2 ms | 8.56 ms (image encoder only) | 13.9 ms | 13.4 s | 34.1 s | 304 / 382 | 270 / 322 | 316 / 362 | 414 / 446 |

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

| model | mode | 480x640 | 720x1280 | 1080x1920 | 12 MP 3000x4000 |
| --- | --- | --- | --- | --- | --- |
| `sam2.1-hiera-base-plus` | portable | 32.0 ms / 395 / 540 | 31.9 ms / 402 / 558 | 32.1 ms / 415 / 568 | - |
| `sam2.1-hiera-base-plus` | kernels | 25.1 ms / 408 / 472 | 25.1 ms / 415 / 490 | 25.3 ms / 428 / 472 | - |
| `sam2.1-hiera-large` | portable | 68.2 ms / 724 / 936 | 68.6 ms / 732 / 948 | 68.3 ms / 745 / 954 | - |
| `sam2.1-hiera-large` | kernels | 48.7 ms / 742 / 824 | 48.7 ms / 750 / 836 | 49.0 ms / 763 / 842 | - |
| `sam2.1-hiera-small` | portable | 18.7 ms / 298 / 420 | 19.1 ms / 305 / 422 | 18.9 ms / 319 / 426 | - |
| `sam2.1-hiera-small` | kernels | 15.4 ms / 310 / 356 | 15.5 ms / 317 / 358 | 15.6 ms / 331 / 346 | - |
| `sam2.1-hiera-tiny` | portable | 16.7 ms / 285 / 410 | 16.6 ms / 292 / 410 | 16.8 ms / 305 / 426 | - |
| `sam2.1-hiera-tiny` | kernels | 13.8 ms / 296 / 346 | 13.8 ms / 304 / 346 | 14.0 ms / 317 / 346 | - |

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 original code named above 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

### On public datasets

One point per ground-truth instance (the interior point farthest from the border); IoU of the best-scored of 3 masks / of the single mask. Semi-supervised: every object's first-frame mask as `input_masks`, `video` forward at 480p; the lower object id wins where masks overlap; J (IoU) and F (boundary) as davis2017-evaluation, mean over objects. Original = the original code named under Details, same checkpoint and protocol.

| variant | dataset | original fp32 | original fp16 | portable | kernels | note |
|---|---|---|---|---|---|---|
| `sam2.1-hiera-tiny` | COCO val2017, every 10th image, point prompts, mIoU best of 3 / single mask % | 57.63 / 57.69 | 57.56 / 57.64 | 57.62 / 57.72 | 57.61 / 57.77 |  |
| `sam2.1-hiera-tiny` | DAVIS 2017 val, every 3rd sequence, video tracking, J&F / J / F % | 83.80 / 79.70 / 87.90 | 83.86 / 79.50 / 88.22 | 83.76 / 79.68 / 87.84 | 83.77 / 79.68 / 87.85 |  |
| `sam2.1-hiera-tiny` | DAVIS 2017 val, video tracking, J&F / J / F % | 87.54 / 84.83 / 90.26 | 87.65 / 84.86 / 90.45 | 87.53 / 84.84 / 90.23 | 87.54 / 84.84 / 90.24 |  |
| `sam2.1-hiera-small` | COCO val2017, every 10th image, point prompts, mIoU best of 3 / single mask % | 59.39 / 58.46 | 59.34 / 58.42 | 59.38 / 58.49 | 59.38 / 58.47 |  |
| `sam2.1-hiera-small` | DAVIS 2017 val, every 3rd sequence, video tracking, J&F / J / F % | 84.08 / 80.26 / 87.90 | 84.11 / 80.28 / 87.93 | 84.13 / 80.31 / 87.94 | 84.13 / 80.31 / 87.95 |  |
| `sam2.1-hiera-base-plus` | COCO val2017, every 10th image, point prompts, mIoU best of 3 / single mask % | 58.79 / 58.67 | 58.73 / 58.57 | 58.81 / 58.71 | 58.82 / 58.73 |  |
| `sam2.1-hiera-base-plus` | DAVIS 2017 val, every 3rd sequence, video tracking, J&F / J / F % | 83.88 / 80.62 / 87.14 | 83.88 / 80.61 / 87.16 | 83.87 / 80.61 / 87.13 | 83.86 / 80.60 / 87.12 |  |
| `sam2.1-hiera-large` | COCO val2017, every 10th image, point prompts, mIoU best of 3 / single mask % | 64.88 / 64.71 | 64.77 / 64.73 | 64.86 / 64.68 | 64.87 / 64.70 |  |
| `sam2.1-hiera-large` | DAVIS 2017 val, every 3rd sequence, video tracking, J&F / J / F % | 85.91 / 82.21 / 89.62 | 85.98 / 82.25 / 89.71 | 85.92 / 82.22 / 89.63 | 85.92 / 82.22 / 89.63 |  |

Measured on NVIDIA GeForce RTX 5060 Ti, torch 2.14.1+cu130, fastforks 84ba91d4 / 939adfe8, 2026-11-06 to 2026-11-12.

### 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.002 vs the original. GPU, float16 (the default), portable and kernels: mean |diff| <= 3 % and p99 <= 15 % of the reference's median |value| (absolute error of the output `pred_masks`).

## Usage

```python
from fastforks import promptable_segmentation

model = promptable_segmentation.load("sam2.1-hiera-base-plus")  # mode="auto": the preferred backend from recorded measurements
result = model("photo.jpg", input_points=[[x, y]], input_labels=[1])
result.masks  # [M, H, W] bool
# SAM 3 (text prompts): model("photo.jpg", text="coin") -> boxes, scores, masks
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: `sam2.1-hiera-base-plus`, `sam2.1-hiera-large`, `sam2.1-hiera-small`, `sam2.1-hiera-tiny`.

## Kernels backend

`promptable_segmentation.load("sam2.1-hiera-base-plus", mode="kernels")` runs our CUDA kernels (`dpt_fused`). 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 1cbf1671 (2026-11-15) -->