| --- |
| 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) --> |
|
|
