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

Bu model, 2025-11-19 tarihinde Hugging Face Transformers'a katkıda bulunulmuştur.

SAM3

Genel Bakış

SAM3 (Segment Anything Model 3), SAM 3: Segment Anything with Concepts makalesinde tanıtılmıştır.

SAM3, görüntüler üzerinde Promptable Concept Segmentation (PCS) gerçekleştirir. PCS, metin ve/veya görsel örnekleri girdi olarak alır (ör. “yellow school bus”) ve kavramla eşleşen her bir nesne için örnekleme ve anlamsal maskeleri tahmin eder.

Makalenin özeti aşağıdaki gibidir:

Segment Anything Model (SAM) 3'ü sunuyoruz. Bu, kısa isim tamlamaları (ör. “yellow school bus”), görsel örnekler veya her ikisinin birleşimi olarak tanımladığımız kavram istemlerine (concept prompts) dayanarak görüntülerde ve videolarda nesneleri algılayan, segmente eden ve izleyen birleşik bir modeldir. Promptable Concept Segmentation (PCS), bu tür istemleri alır ve eşleşen tüm nesne örnekleri için segmentasyon maskeleri ve benzersiz kimlikler döndürür. PCS'yi ilerletmek için, görüntüler ve videolar arasında zor negatifleri (hard negatives) içeren, 4M benzersiz kavram etiketine sahip yüksek kaliteli bir veri seti üreten ölçeklenebilir bir veri motoru geliştiriyoruz. Modelimiz, tek bir omurga (backbone) paylaşan görüntü düzeyinde bir algılayıcı ve bellek tabanlı bir video izleyiciden oluşur. Tanıma ve konumlandırma, algılama doğruluğunu artıran bir varlık başlığı (presence head) ile ayrıştırılır. SAM 3, hem görüntü hem de video PCS'de mevcut sistemlerin doğruluğunu ikiye katlar ve önceki SAM yeteneklerini görsel segmentasyon görevlerinde iyileştirir. Promptable concept segmentation için yeni Segment Anything with Concepts (SA-Co) benchmark'ımızla birlikte SAM 3'ü açık kaynak olarak yayımlıyoruz.

Bu model yonigozlan ve ronghanghu tarafından katkıda bulunmuştur.

🤗 Transformers ile kullanım örnekleri

Sadece Metin İfadeleri

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

Tek Sınır Kutusu İfadesi

Görsel kavram üzerinde bir sınırlayıcı kutu kullanarak nesneleri segmente edin:

# 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]

Çoklu Kutu İpuçları (Pozitif ve Negatif)

Kavramı ince ayar yapmak için pozitif ve negatif etiketlere sahip birden fazla kutu kullanın:

# 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]

Birleştirilmiş İfadeler (Metin + Negatif Kutu)

Kavramı ince ayarlamak için negatif görsel istemlerle metin istemleri kullanın:

# 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

Metin İfadeleriyle Toplu Çıkarım

Farklı metin istemcileriyle birden fazla görüntüyü verimli bir şekilde işleyin:

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

Toplu Karışık İfadeler

Aynı partideki farklı görüntüler için farklı istem türleri kullanın:

# 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

Anlamsal Segmentasyon Çıktısı

SAM3, örnek maskelerinin yanı sıra anlamsal segmentasyon da sağlar:

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

Tek Görüntüde Verimli Çoklu İstem Çıkarımı

Aynı görüntü üzerinde birden çok metin istemi çalıştırırken, gereksiz hesaplamalardan kaçınmak için görsel gömme değerlerini önceden hesaplayın:

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

Birden Fazla Görselde Verimli Tek İfade Çıkarımı

Aynı metin istemini birden fazla görüntüde çalıştırırken, gereksiz hesaplamalardan kaçınmak için metin gömme değerlerini önceden hesaplayın:

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

Özel Çözünürlükte Çıkarım

⚠️ **Performans Notu**: Özel çözünürlükler doğruluğu düşürebilir. Model, 1008px çözünürlükte kullanılacak şekilde tasarlanmıştır.

Daha hızlı çıkarım veya daha düşük bellek kullanımı için:

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

Prompt Etiket Sözleşmeleri

SAM3 aşağıdaki etiket kurallarını kullanır:

Noktalar ve kutular için:

1: Olumlu istem (bu bölgeyi/nesneyi dahil et)
0: Negatif istem (bu bölgeyi/nesneyi hariç tut)
-10: Toplu girdiler için dolgu değeri

Koordinat biçimleri:

Giriş kutuları: [x1, y1, x2, y2] (xyxy biçimi) piksel koordinatlarında
Çıkış kutuları (ham): [x1, y1, x2, y2] (xyxy biçimi), [0, 1] aralığına normalize edilmiş
Çıktı kutuları (son işlem yapılmış): [x1, y1, x2, y2] (xyxy biçimi) mutlak piksel koordinatlarında

Transformers

SAM3

Genel Bakış

🤗 Transformers ile kullanım örnekleri

Sadece Metin İfadeleri

Tek Sınır Kutusu İfadesi

Çoklu Kutu İpuçları (Pozitif ve Negatif)

Birleştirilmiş İfadeler (Metin + Negatif Kutu)

Metin İfadeleriyle Toplu Çıkarım

Toplu Karışık İfadeler

Anlamsal Segmentasyon Çıktısı

Tek Görüntüde Verimli Çoklu İstem Çıkarımı

Birden Fazla Görselde Verimli Tek İfade Çıkarımı

Özel Çözünürlükte Çıkarım

Prompt Etiket Sözleşmeleri

Sam3Config

sınıf transformers.Sam3Config

Sam3ViTConfig

sınıf transformers.Sam3ViTConfig

Sam3VisionConfig

sınıf transformers.Sam3VisionConfig

Sam3GeometryEncoderConfig

sınıf transformers.Sam3GeometryEncoderConfig

Sam3DETREncoderConfig

sınıf transformers.Sam3DETREncoderConfig

Sam3DETRDecoderConfig

sınıf transformers.Sam3DETRDecoderConfig

Sam3MaskDecoderConfig

sınıf transformers.Sam3MaskDecoderConfig

Sam3Processor

sınıf transformers.Sam3Processor

__call__

Sam3ImageProcessor

sınıf transformers.Sam3ImageProcessor

ön işleme

Sam3ViTModel

sınıf transformers.Sam3ViTModel

forward

Sam3VisionModel

sınıf transformers.Sam3VisionModel

forward

Sam3Model

sınıf transformers.Sam3Model

forward

get_text_features

call