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만 개의 고유한 개념 라벨(어려운 음수 포함)을 포함하는 고품질 데이터셋을 생성하는 확장 가능한 데이터 엔진을 구축했습니다. 우리의 모델은 단일 백본을 공유하는 이미지 수준의 감지기와 메모리 기반 비디오 트래커로 구성됩니다. 존재 헤드(presence head)를 통해 인식과 위치 파악을 분리하여 감지 정확도를 높였습니다. SAM 3은 이미지와 비디오 PCS 모두에서 기존 시스템의 정확도를 2배로 높였으며, 시각 분할 작업에서 이전 SAM의 기능을 향상시켰습니다. 우리는 프롬프트 기반 개념 분할을 위한 새로운 Segment Anything with Concepts(SA-Co) 벤치마크와 함께 SAM 3을 오픈소스로 공개합니다.

이 모델은 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: Negative prompt(해당 영역/객체를 제외)
-10: 배치 입력에 사용되는 패딩 값

좌표 형식:

입력 상자: [x1, y1, x2, y2] (xyxy 형식) 픽셀 좌표
출력 박스 (원시값): [x1, y1, x2, y2] (xyxy 형식), [0, 1]로 정규화
출력 박스(후처리됨): 절대 픽셀 좌표의 [x1, y1, x2, y2](xyxy 형식)

Transformers

SAM3

개요

🤗 Transformers를 활용한 사용 예시

텍스트 전용 프롬프트

단일 바운딩 박스 프롬프트

여러 개의 박스 프롬프트(긍정 및 부정)

결합 프롬프트(텍스트 + 네거티브 박스)

텍스트 프롬프트를 사용한 배치 추론

배치된 혼합 프롬프트

의미 분할 출력

단일 이미지에서 효율적인 멀티 프롬프트 추론

여러 이미지에서 효율적인 단일 프롬프트 추론

사용자 지정 해상도 추론

프롬프트 라벨 규칙

Sam3Config

클래스 transformers.Sam3Config

Sam3ViTConfig

클래스 transformers.Sam3ViTConfig

Sam3VisionConfig

클래스 transformers.Sam3VisionConfig

Sam3GeometryEncoderConfig

클래스 transformers.Sam3GeometryEncoderConfig

Sam3DETREncoderConfig

클래스 transformers.Sam3DETREncoderConfig

Sam3DETRDecoderConfig

클래스 transformers.Sam3DETRDecoderConfig

Sam3MaskDecoderConfig

class transformers.Sam3MaskDecoderConfig

Sam3Processor

class transformers.Sam3Processor

__call__

Sam3ImageProcessor

클래스 transformers.Sam3ImageProcessor

preprocess

Sam3ViTModel

클래스 transformers.Sam3ViTModel

forward

Sam3VisionModel

class transformers.Sam3VisionModel

forward

Sam3Model

class transformers.Sam3Model

forward

get_text_features

call