Transformers documentation

SAM3

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

このモデルは2025年11月19日にHugging Face Transformersに貢献されました。

SAM3

概要

SAM3 (Segment Anything Model 3) は、SAM 3: Segment Anything with Concepts で紹介されました。

SAM3は画像に対してPromptable Concept Segmentation (PCS)を実行します。PCSはテキストおよび/または画像のサンプルを入力として受け取り（例: “yellow school bus”）、その概念に一致するすべてのオブジェクトのインスタンスマスクとセマンティックマスクを予測します。

論文の抄録は以下の通りです。

本稿では、Segment Anything Model (SAM) 3 を紹介します。SAM 3 は、概念プロンプトに基づいて画像および動画内のオブジェクトを検出・セグメンテーション・トラッキングを行う統合モデルです。ここでいう概念プロンプトとは、短い名詞句（例：「yellow school bus」）、画像のサンプル、またはそれらの組み合わせを指します。Promptable Concept Segmentation (PCS) は、こうしたプロンプトを受け取り、一致するすべてのオブジェクトインスタンスに対してセグメンテーションマスクと一意のIDを返します。PCS の発展を目的として、画像と動画にわたって困難なネガティブ例を含む 400 万のユニークな概念ラベルからなる高品質なデータセットを生成するスケーラブルなデータエンジンを構築しました。本モデルは、単一のバックボーンを共有する画像レベルの検出器と、メモリベースの動画トラッカーで構成されています。存在ヘッドによって認識と位置特定を分離することで、検出精度を向上させています。SAM 3 は、画像および動画の PCS において既存システムの精度を 2 倍に向上させ、視覚的セグメンテーションタスクにおける従来の SAM の機能も改善しています。SAM 3 と、プロンプタブル概念セグメンテーションのための新ベンチマーク Segment Anything with Concepts (SA-Co) をオープンソースとして公開します。

このモデルは、yonigozlan 氏と ronghanghu 氏によって提供されました。

🤗 Transformers を使用した使用例

テキストのみのプロンプト

import requests
import torch
from PIL import Image

from transformers import Sam3Model, Sam3Processor


model = Sam3Model.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3Processor.from_pretrained("facebook/sam3")

# Load image
image_url = "http://images.cocodataset.org/val2017/000000077595.jpg"
image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")

# Segment using text prompt
inputs = processor(images=image, text="ear", return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Post-process results
results = processor.post_process_instance_segmentation(
    outputs,
    threshold=0.5,
    mask_threshold=0.5,
    target_sizes=inputs.get("original_sizes").tolist()
)[0]

print(f"Found {len(results['masks'])} objects")
# Results contain:
# - masks: Binary masks resized to original image size
# - boxes: Bounding boxes in absolute pixel coordinates (xyxy format)
# - scores: Confidence scores

単一のバウンディングボックスプロンプト

視覚的な概念に対してバウンディングボックスを指定してオブジェクトをセグメントします:

# Box in xyxy format: [x1, y1, x2, y2] in pixel coordinates
# Example: laptop region
box_xyxy = [100, 150, 500, 450]
input_boxes = [[box_xyxy]]  # [batch, num_boxes, 4]
input_boxes_labels = [[1]]  # 1 = positive box

inputs = processor(
    images=image,
    input_boxes=input_boxes,
    input_boxes_labels=input_boxes_labels,
    return_tensors="pt"
).to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Post-process results
results = processor.post_process_instance_segmentation(
    outputs,
    threshold=0.5,
    mask_threshold=0.5,
    target_sizes=inputs.get("original_sizes").tolist()
)[0]

複数のボックスプロンプト（正と負）

正ラベルと負ラベルを付けた複数のボックスを使用して、概念を洗練させます:

# Load kitchen image
kitchen_url = "http://images.cocodataset.org/val2017/000000136466.jpg"
kitchen_image = Image.open(requests.get(kitchen_url, stream=True).raw).convert("RGB")

# Define two positive boxes (e.g., dial and button on oven)
# Boxes are in xyxy format [x1, y1, x2, y2] in pixel coordinates
box1_xyxy = [59, 144, 76, 163]  # Dial box
box2_xyxy = [87, 148, 104, 159]  # Button box
input_boxes = [[box1_xyxy, box2_xyxy]]
input_boxes_labels = [[1, 1]]  # Both positive

inputs = processor(
    images=kitchen_image,
    input_boxes=input_boxes,
    input_boxes_labels=input_boxes_labels,
    return_tensors="pt"
).to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Post-process results
results = processor.post_process_instance_segmentation(
    outputs,
    threshold=0.5,
    mask_threshold=0.5,
    target_sizes=inputs.get("original_sizes").tolist()
)[0]

組み合わせプロンプト（テキスト + ネガティブボックス）

ネガティブなビジュアルプロンプトをテキストプロンプトと組み合わせて、コンセプトを洗練させます:

# Segment "handle" but exclude the oven handle using a negative box
text = "handle"
# Negative box covering oven handle area (xyxy): [40, 183, 318, 204]
oven_handle_box = [40, 183, 318, 204]
input_boxes = [[oven_handle_box]]

inputs = processor(
    images=kitchen_image,
    text=text,
    input_boxes=input_boxes,
    input_boxes_labels=[[0]],  # 0 = negative (exclude this region)
    return_tensors="pt"
).to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Post-process results
results = processor.post_process_instance_segmentation(
    outputs,
    threshold=0.5,
    mask_threshold=0.5,
    target_sizes=inputs.get("original_sizes").tolist()
)[0]
# This will segment pot handles but exclude the oven handle

テキストプロンプトによるバッチ推論

異なるテキストプロンプトを持つ複数の画像を効率的に処理します:

cat_url = "http://images.cocodataset.org/val2017/000000077595.jpg"
kitchen_url = "http://images.cocodataset.org/val2017/000000136466.jpg"
images = [
    Image.open(requests.get(cat_url, stream=True).raw).convert("RGB"),
    Image.open(requests.get(kitchen_url, stream=True).raw).convert("RGB")
]

# Different text prompt for each image
text_prompts = ["ear", "dial"]

inputs = processor(images=images, text=text_prompts, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Post-process results for both images
results = processor.post_process_instance_segmentation(
    outputs,
    threshold=0.5,
    mask_threshold=0.5,
    target_sizes=inputs.get("original_sizes").tolist()
)

print(f"Image 1: {len(results[0]['masks'])} objects found")
print(f"Image 2: {len(results[1]['masks'])} objects found")

バッチ化された混合プロンプト

同じバッチ内の異なる画像に異なるプロンプトタイプを使用するには:

# Image 1: text prompt "laptop"
# Image 2: visual prompt (dial box)
box2_xyxy = [59, 144, 76, 163]

inputs = processor(
    images=images,
    text=["laptop", None],  # Only first image has text
    input_boxes=[None, [box2_xyxy]],  # Only second image has box
    input_boxes_labels=[None, [1]],  # Positive box for second image
    return_tensors="pt"
).to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Post-process results for both images
results = processor.post_process_instance_segmentation(
    outputs,
    threshold=0.5,
    mask_threshold=0.5,
    target_sizes=inputs.get("original_sizes").tolist()
)
# Both images processed in single forward pass

セマンティックセグメンテーションの出力

SAM3 は、インスタンスマスクに加えてセマンティックセグメンテーションも提供します:

inputs = processor(images=image, text="ear", return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Instance segmentation masks
instance_masks = torch.sigmoid(outputs.pred_masks)  # [batch, num_queries, H, W]

# Semantic segmentation (single channel)
semantic_seg = outputs.semantic_seg  # [batch, 1, H, W]

print(f"Instance masks: {instance_masks.shape}")
print(f"Semantic segmentation: {semantic_seg.shape}")

単一画像での効率的なマルチプロンプト推論

同じ画像に対して複数のテキストプロンプトを実行する場合は、冗長な計算を避けるために、ビジョン埋め込みを事前計算してください。

from transformers import Sam3Processor, Sam3Model
import torch
from PIL import Image
import requests


model = Sam3Model.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3Processor.from_pretrained("facebook/sam3")

# Load image
image_url = "http://images.cocodataset.org/val2017/000000077595.jpg"
image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")

# Pre-process image and compute vision embeddings once
img_inputs = processor(images=image, return_tensors="pt").to(model.device)
with torch.no_grad():
    vision_embeds = model.get_vision_features(pixel_values=img_inputs.pixel_values)

# Run multiple text prompts efficiently
text_prompts = ["ear", "eye", "nose"]
all_results = []

for prompt in text_prompts:
    text_inputs = processor(text=prompt, return_tensors="pt").to(model.device)
    with torch.no_grad():
        outputs = model(vision_embeds=vision_embeds, **text_inputs)
...
    results = processor.post_process_instance_segmentation(
        outputs,
        threshold=0.5,
        mask_threshold=0.5,
        target_sizes=img_inputs.get("original_sizes").tolist()
    )[0]
    all_results.append({"prompt": prompt, "results": results})

for item in all_results:
    print(f"Prompt '{item['prompt']}': {len(item['results']['masks'])} objects found")

複数の画像に対する効率的なシングルプロンプト推論

複数の画像に対して同じテキストプロンプトを実行する場合は、冗長な計算を避けるために、テキスト埋め込みを事前計算してください。

from transformers import Sam3Processor, Sam3Model
import torch
from PIL import Image
import requests


model = Sam3Model.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3Processor.from_pretrained("facebook/sam3")

# Pre-compute text embeddings once
text_prompt = "ear"
text_inputs = processor(text=text_prompt, return_tensors="pt").to(model.device)
with torch.no_grad():
    text_embeds = model.get_text_features(**text_inputs)

# Load multiple images
image_urls = [
    "http://images.cocodataset.org/val2017/000000077595.jpg",
    "http://images.cocodataset.org/val2017/000000039769.jpg",
]
images = [Image.open(requests.get(url, stream=True).raw).convert("RGB") for url in image_urls]

# Run inference on each image reusing text embeddings
# Note: attention_mask must be passed along with text_embeds for proper masking
all_results = []

for image in images:
    img_inputs = processor(images=image, return_tensors="pt").to(model.device)
    with torch.no_grad():
        outputs = model(
            pixel_values=img_inputs.pixel_values,
            text_embeds=text_embeds,
            attention_mask=text_inputs.attention_mask,
        )
...
    results = processor.post_process_instance_segmentation(
        outputs,
        threshold=0.5,
        mask_threshold=0.5,
        target_sizes=img_inputs.get("original_sizes").tolist()
    )[0]
    all_results.append(results)

for i, results in enumerate(all_results):
    print(f"Image {i+1}: {len(results['masks'])} '{text_prompt}' objects found")

カスタム解像度推論

⚠️ **パフォーマンスに関する注意**: カスタム解像度を使用すると、精度が低下する可能性があります。このモデルは1008pxの解像度で使用することを前提としています。

より高速な推論や、メモリ使用量の削減のために:

config = Sam3Config.from_pretrained("facebook/sam3")
config.image_size = 560
model = Sam3Model.from_pretrained("facebook/sam3", config=config, device_map="auto")
processor = Sam3Processor.from_pretrained("facebook/sam3", size={"height": 560, "width": 560})

プロンプトのラベル規約

SAM3では、以下のラベル規約を使用します。

点とボックスについて:

1: ポジティブプロンプト（この領域/オブジェクトを含める）
0: 否定プロンプト（この領域/オブジェクトを除外）
-10: バッチ入力用のパディング値

座標形式:

入力ボックス: ピクセル座標の [x1, y1, x2, y2] (xyxy 形式)
出力ボックス（生データ）: [x1, y1, x2, y2]（xyxy形式）、[0, 1]に正規化済み
出力ボックス（後処理済み）: [x1, y1, x2, y2]（xyxy形式）の絶対ピクセル座標

Transformers

SAM3

概要

🤗 Transformers を使用した使用例

テキストのみのプロンプト

単一のバウンディングボックスプロンプト

複数のボックスプロンプト（正と負）

組み合わせプロンプト（テキスト + ネガティブボックス）

テキストプロンプトによるバッチ推論

バッチ化された混合プロンプト

セマンティックセグメンテーションの出力

単一画像での効率的なマルチプロンプト推論

複数の画像に対する効率的なシングルプロンプト推論

カスタム解像度推論

プロンプトのラベル規約

Sam3Config

class transformers.Sam3Config

Sam3ViTConfig

クラス transformers.Sam3ViTConfig

Sam3VisionConfig

class transformers.Sam3VisionConfig

Sam3GeometryEncoderConfig

class transformers.Sam3GeometryEncoderConfig

Sam3DETREncoderConfig

クラス transformers.Sam3DETREncoderConfig

Sam3DETRDecoderConfig

クラス transformers.Sam3DETRDecoderConfig

Sam3MaskDecoderConfig

クラス transformers.Sam3MaskDecoderConfig

Sam3Processor

クラス transformers.Sam3Processor

__call__

Sam3ImageProcessor

class transformers.Sam3ImageProcessor

preprocess

Sam3ViTModel

class transformers.Sam3ViTModel

forward

Sam3VisionModel

class transformers.Sam3VisionModel

forward

Sam3Model

class transformers.Sam3Model

forward

get_text_features

call