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

تمت مساهمة هذا النموذج في Hugging Face Transformers في 2025-11-19.

SAM3

نظرة عامة

تم تقديم SAM3 (نموذج تقسيم أي شيء 3) في SAM 3: Segment Anything with Concepts.

يُنفّذ SAM3 تجزئة المفاهيم القابلة للتوجيه (PCS) على الصور. تستقبل PCS نصوصًا و/أو أمثلةً مرئيةً كمدخلات (مثلًا: "حافلة مدرسية صفراء")، وتُتنبأ بأقنعة كائنات وأقنعة دلالية لكل كائن واحد يطابق المفهوم.

المستخلص من الورقة البحثية هو كالتالي:

نقدّم نموذج Segment Anything Model (SAM) 3، وهو نموذج موحّد يكشف عن الكائنات ويقسّمها ويتتبّعها في الصور والفيديوهات بناءً على محفّزات المفاهيم، والتي نعرّفها إما على أنها عبارات اسمية قصيرة (مثل "حافلة مدرسية صفراء")، أو أمثلة مصوّرة، أو مزيج من الاثنين معاً. يستقبل تقسيم المفاهيم القابل للمحفّز (PCS) هذه المحفّزات ويعيد أقنعة التقسيم والهويات الفريدة لجميع حالات الكائنات المطابقة. ولتطوير PCS، بنينا محرك بيانات قابل للتوسّع ينتج مجموعة بيانات عالية الجودة تحتوي على 4 ملايين تسمية مفهوم فريدة، بما في ذلك السلبات الصعبة، عبر الصور والفيديوهات. يتكوّن نموذجنا من كاشف على مستوى الصورة ومتتبّع فيديو يعتمد على الذاكرة، يتشاركان في عمود فقري واحد. يتم فصل التعرّف عن تحديد الموقع بواسطة رأس حضور، مما يعزّز دقة الكشف. يضاعف SAM 3 دقة الأنظمة الحالية في كل من PCS للصور والفيديوهات، ويحسّن قدرات 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")

الموجّهات المختلطة المجمّعة

استخدم أنواعًا مختلفة من الأوامر (prompts) لصور مختلفة في نفس الدفعة (batch):

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

الاستدلال بدقة مخصصة

⚠️ **ملاحظة حول الأداء**: قد تؤدي الدقات المخصصة إلى تدهور الدقة. صُمم النموذج للاستخدام عند دقة 1008 بكسل.

للحصول على استنتاج أسرع أو استخدام أقل للذاكرة:

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

فئة transformers.Sam3Config

Sam3ViTConfig

فئة transformers.Sam3ViTConfig

Sam3VisionConfig

فئة transformers.Sam3VisionConfig

Sam3GeometryEncoderConfig

فئة transformers.Sam3GeometryEncoderConfig

Sam3DETREncoderConfig

فئة transformers.Sam3DETREncoderConfig

Sam3DETRDecoderConfig

فئة transformers.Sam3DETRDecoderConfig

Sam3MaskDecoderConfig

فئة transformers.Sam3MaskDecoderConfig

Sam3Processor

فئة transformers.Sam3Processor

__call__

Sam3ImageProcessor

فئة transformers.Sam3ImageProcessor

preprocess

Sam3ViTModel

فئة transformers.Sam3ViTModel

forward

Sam3VisionModel

فئة transformers.Sam3VisionModel

forward

Sam3Model

فئة transformers.Sam3Model

forward

get_text_features

call