Hugging Face's logo

Transformers documentation

SAM3

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi contribuído para o Hugging Face Transformers em 19/11/2025.

SAM3

SDPA FlashAttention

Visão geral

O SAM3 (Segment Anything Model 3) foi introduzido em SAM 3: Segment Anything with Concepts.

O SAM3 executa Segmentação de Conceitos com Prompt (PCS) em imagens. O PCS recebe texto e/ou exemplos de imagem como entrada (por exemplo, “ônibus escolar amarelo”) e prevê máscaras de instância e semânticas para cada objeto que corresponda ao conceito.

O resumo do artigo é o seguinte:

Apresentamos o Segment Anything Model (SAM) 3, um modelo unificado que detecta, segmenta e rastreia objetos em imagens e vídeos com base em prompts de conceito, que definimos como frases nominais curtas (por exemplo, “yellow school bus”), exemplares de imagem ou uma combinação de ambos. A Segmentação de Conceito Promptável (PCS) recebe esses prompts e retorna máscaras de segmentação e identidades únicas para todas as instâncias de objetos correspondentes. Para avançar a PCS, construímos um motor de dados escalável que produz um conjunto de dados de alta qualidade com 4M de rótulos de conceito únicos, incluindo negativos difíceis, em imagens e vídeos. Nosso modelo consiste em um detector de nível de imagem e um rastreador de vídeo baseado em memória que compartilham um único backbone. O reconhecimento e a localização são desacoplados por meio de uma presença head, o que aumenta a precisão da detecção. O SAM 3 dobra a precisão dos sistemas existentes tanto na PCS de imagem quanto na de vídeo, e melhora as capacidades anteriores do SAM em tarefas de segmentação visual. Abre o código-fonte do SAM 3 junto com nosso novo benchmark Segment Anything with Concepts (SA-Co) para segmentação de conceito promptável.

Este modelo foi contribuído por yonigozlan e ronghanghu.

Exemplos de uso com 🤗 Transformers

Prompts somente de texto

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

Prompt de Caixa Delimitadora Única

Segmentar objetos usando uma caixa delimitadora no conceito visual:

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

Vários prompts de caixa (positivos e negativos)

Use múltiplas caixas com rótulos positivos e negativos para refinar o conceito:

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

Prompts combinados (Texto + Caixa negativa)

Use prompts de texto com prompts visuais negativos para refinar o conceito:

# 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

Inferência em lote com prompts de texto

Processe várias imagens com diferentes prompts de texto de forma eficiente:

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 misturados em lote

Use diferentes tipos de prompt para diferentes imagens no mesmo lote:

# 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

Saída de Segmentação Semântica

O SAM3 também fornece segmentação semântica junto com máscaras de instância:

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

Inferência eficiente de múltiplos prompts em uma única imagem

Ao executar vários prompts de texto na mesma imagem, pré-compute os embeddings de visão para evitar cálculos redundantes:

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

Inferência eficiente de prompt único em múltiplas imagens

Ao executar o mesmo prompt de texto em várias imagens, pré-compute os embeddings de texto para evitar cálculos redundantes:

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

Inferência com Resolução Personalizada

⚠️ **Nota de desempenho**: Resoluções personalizadas podem degradar a precisão. O modelo foi projetado para ser usado em resolução de 1008px.

Para inferência mais rápida ou menor uso de memória:

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

Convenções de Rótulos de Prompt

O SAM3 usa as seguintes convenções de rótulos:

Para pontos e caixas:

  • 1: Prompt positivo (inclua esta região/objeto)
  • 0: Prompt negativo (exclua esta região/objeto)
  • -10: Valor de padding para entradas em lote

Formatos de coordenadas:

  • Caixas de entrada: [x1, y1, x2, y2] (formato xyxy) em coordenadas de pixels
  • Caixas de saída (brutas): [x1, y1, x2, y2] (formato xyxy), normalizadas para [0, 1]
  • Caixas de saída (pós-processadas): [x1, y1, x2, y2] (formato xyxy) em coordenadas de pixels absolutas

Sam3Config

classe transformers.Sam3Config

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonegeometry_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonedetr_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonedetr_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02 )

Parâmetros

  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de visão.
  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de texto.
  • geometry_encoder_config (dict ou Sam3GeometryEncoderConfig, opcional) — Configuração para o codificador de geometria.
  • detr_encoder_config (dict ou Sam3DETREncoderConfig, opcional) — Configuração para o codificador DETR.
  • detr_decoder_config (dict ou Sam3DETRDecoderConfig, opcional) — Configuração para o decodificador DETR.
  • mask_decoder_config (dict ou Sam3MaskDecoderConfig, opcional) — Configuração para o decodificador de máscara.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> from transformers import Sam3Config, Sam3Model

>>> # Initializing a SAM3 configuration
>>> configuration = Sam3Config()

>>> # Initializing a model from the configuration
>>> model = Sam3Model(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

Sam3ViTConfig

classe transformers.Sam3ViTConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 1024intermediate_size: int = 4736num_hidden_layers: int = 32num_attention_heads: int = 16num_channels: int = 3image_size: int | list[int] | tuple[int, int] = 1008patch_size: int | list[int] | tuple[int, int] = 14hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06attention_dropout: float | int = 0.0window_size: int = 24global_attn_indexes: list[int] | None = Nonelayer_scale_init_value: float | None = Nonepretrain_image_size: int | list[int] | tuple[int, int] = 336hidden_dropout: float | int = 0.0initializer_range: float = 0.02rope_parameters: dict | None = None )

Parâmetros

  • hidden_size (int, opcional, padrão 1024) — Dimensão das representações ocultas.
  • intermediate_size (int, opcional, padrão 4736) — Dimensão das representações do MLP.
  • num_hidden_layers (int, opcional, padrão 32) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 16) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • num_channels (int, opcional, padrão 3) — O número de canais de entrada.
  • image_size (Union[int, list[int], tuple[int, int]], opcional, padrão 1008) — O tamanho (resolução) de cada imagem.
  • patch_size (Union[int, list[int], tuple[int, int]], opcional, padrão 14) — O tamanho (resolução) de cada patch.
  • hidden_act (str, opcional, padrão gelu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
  • attention_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
  • window_size (int, opcional, padrão 24) — Tamanho da janela para a atenção com janela.
  • global_attn_indexes (list[int], opcional, padrão [7, 15, 23, 31]) — Índices das camadas com atenção global.
  • layer_scale_init_value (float, opcional) — Escala a ser usada nas camadas de autoatenção. 0.1 para base, 1e-6 para grande. Defina 0 para desativar a escala da camada.
  • pretrain_image_size (int, opcional, padrão 336) — Tamanho da imagem do modelo pré-treinado para a inicialização do embedding de posição.
  • hidden_dropout (float, opcional, padrão 0.0) — Probabilidade de dropout para os estados ocultos.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
  • rope_parameters (dict, opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3VisionConfig

classe transformers.Sam3VisionConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonebackbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonefpn_hidden_size: int = 256backbone_feature_sizes: list | None = Nonescale_factors: list[float] | None = Nonehidden_act: str = 'gelu'layer_norm_eps: float = 1e-06initializer_range: float = 0.02 )

Parâmetros

  • backbone_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — A configuração do modelo backbone.
  • fpn_hidden_size (int, opcional, padrão 256) — A dimensão oculta do FPN.
  • backbone_feature_sizes (List[List[int]], opcional, padrão [[288, 288], [144, 144], [72, 72]]) — Os tamanhos espaciais (altura, largura) dos mapas de características do backbone em diferentes escalas.
  • scale_factors (list[float], opcional, padrão [4.0, 2.0, 1.0, 0.5]) — Fatores de escala para recursos multiescala do FPN. Lista de fatores de escala para cada nível do FPN.
  • hidden_act (str, opcional, padrão gelu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3GeometryEncoderConfig

classe transformers.Sam3GeometryEncoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256num_layers: int = 3num_attention_heads: int = 8intermediate_size: int = 2048dropout: float | int = 0.1hidden_act: str = 'relu'hidden_dropout: float | int = 0.0layer_norm_eps: float = 1e-06roi_size: int = 7initializer_range: float = 0.02 )

Parâmetros

  • hidden_size (int, opcional, padrão 256) — Dimensão das representações ocultas.
  • num_layers (int, opcional, padrão 3) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 8) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • intermediate_size (int, opcional, padrão 2048) — Dimensão das representações do MLP.
  • dropout (Union[float, int], opcional, padrão 0.1) — A proporção para todas as camadas de dropout.
  • hidden_act (str, opcional, padrão relu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • hidden_dropout (Union[float, int], opcional, padrão 0.0) — A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings, no encoder e no pooler.
  • layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
  • roi_size (int, opcional, padrão 7) — Tamanho da ROI para operações de box pooling.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3DETREncoderConfig

classe transformers.Sam3DETREncoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256num_layers: int = 6num_attention_heads: int = 8intermediate_size: int = 2048dropout: float | int = 0.1hidden_act: str = 'relu'hidden_dropout: float | int = 0.0layer_norm_eps: float = 1e-06initializer_range: float = 0.02 )

Parâmetros

  • hidden_size (int, opcional, padrão 256) — Dimensão das representações ocultas.
  • num_layers (int, opcional, padrão 6) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 8) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • intermediate_size (int, opcional, padrão 2048) — Dimensão das representações do MLP.
  • dropout (Union[float, int], opcional, padrão 0.1) — A proporção para todas as camadas de dropout.
  • hidden_act (str, opcional, padrão relu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • hidden_dropout (float, opcional, padrão 0.0) — Probabilidade de dropout para os estados ocultos.
  • layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3DETRDecoderConfig

classe transformers.Sam3DETRDecoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256num_layers: int = 6num_queries: int = 200num_attention_heads: int = 8intermediate_size: int = 2048dropout: float | int = 0.1hidden_act: str = 'relu'hidden_dropout: float | int = 0.0layer_norm_eps: float = 1e-06initializer_range: float = 0.02 )

Parâmetros

  • hidden_size (int, opcional, padrão 256) — Dimensão das representações ocultas.
  • num_layers (int, opcional, padrão 6) — Número de camadas ocultas no decodificador do Transformer.
  • num_queries (int, opcional, padrão 200) — Número de consultas de objeto.
  • num_attention_heads (int, opcional, padrão 8) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • intermediate_size (int, opcional, padrão 2048) — Dimensão das representações do MLP.
  • dropout (Union[float, int], opcional, padrão 0.1) — A proporção para todas as camadas de dropout.
  • hidden_act (str, opcional, padrão relu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • hidden_dropout (Union[float, int], opcional, padrão 0.0) — A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings, no encoder e no pooler.
  • layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3MaskDecoderConfig

classe transformers.Sam3MaskDecoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256num_upsampling_stages: int = 3layer_norm_eps: float = 1e-06dropout: float | int = 0.0num_attention_heads: int = 8initializer_range: float = 0.02 )

Parâmetros

  • hidden_size (int, opcional, padrão 256) — Dimensão das representações ocultas.
  • num_upsampling_stages (int, opcional, padrão 3) — Número de estágios de upsampling no decodificador de pixels (FPN).
  • layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
  • dropout (Union[float, int], opcional, padrão 0.0) — A proporção para todas as camadas de dropout.
  • num_attention_heads (int, opcional, padrão 8) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um Sam3Model. Ela é usada para instanciar um modelo Sam3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/sam3

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3Processor

classe transformers.Sam3Processor

< >

( image_processortokenizertarget_size: int | None = Nonepoint_pad_value: int = -10**kwargs )

Parâmetros

  • image_processor (Sam3ImageProcessor) — O processador de imagem é uma entrada obrigatória.
  • tokenizer (CLIPTokenizer) — O tokenizer é uma entrada obrigatória.
  • target_size (int, opcional) — O tamanho alvo (target_size, target_size) para o qual a imagem será redimensionada.
  • point_pad_value (int, opcional, padrão -10) — O valor usado para o preenchimento das caixas de entrada.

Constrói um Sam3Processor que encapsula um processador de imagem e um tokenizer em um único processador.

Sam3Processor oferece todas as funcionalidades de Sam3ImageProcessor e CLIPTokenizer. Consulte ~Sam3ImageProcessor e ~CLIPTokenizer para mais informações.

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonesegmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Noneinput_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = Noneinput_boxes_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = Noneoriginal_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs ) → A BatchEncoding with the following fields

Parâmetros

  • images (ImageInput, opcional) — A(s) imagem(ns) a ser processada(s).
  • text (str, list[str], list[list[str]], opcional) — O texto a ser processado.
  • segmentation_maps (ImageInput, opcional) — Os mapas de segmentação a serem processados.
  • input_boxes (list[list[list[float]]], torch.Tensor, opcional) — As caixas delimitadoras a serem processadas.
  • input_boxes_labels (list[list[int]], torch.Tensor, opcional) — Os rótulos para as caixas delimitadoras.
  • original_sizes (list[list[float]], torch.Tensor, opcional) — Os tamanhos originais das imagens.
  • return_tensors (Union[str, ~utils.generic.TensorType], opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.

Retorna

Um BatchEncoding com os seguintes campos

  • pixel_values (torch.Tensor): A(s) imagem(ns) processada(s).
  • original_sizes (list[list[float]]): Os tamanhos originais das imagens.
  • labels (torch.Tensor): Os mapas de segmentação processados (se fornecidos).
  • input_boxes_labels (torch.Tensor): Os rótulos processados para as caixas delimitadoras.
  • input_boxes (torch.Tensor): As caixas delimitadoras processadas.

Sam3ImageProcessor

classe transformers.Sam3ImageProcessor

< >

( **kwargs: *<class 'transformers.models.sam3.image_processing_sam3.Sam3ImageProcessorKwargs'> )

Parâmetros

  • do_convert_rgb (bool, kwargs, opcional, padrão True) — Se a imagem deve ser convertida para RGB.
  • do_resize (bool, kwargs, opcional, padrão True) — Se deve redimensionar a imagem.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, padrão {'height' -- 1008, 'width': 1008}): Descreve as dimensões máximas de entrada para o modelo.
  • default_to_square (bool, kwargs, opcional, padrão True) — Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Tamanho da imagem de saída após a aplicação de center_crop.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, padrão 2) — Filtro de reamostragem a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração PILImageResampling. Tem efeito apenas se do_resize estiver definido como True.
  • do_rescale (bool, kwargs, opcional, padrão True) — Se deve reescalar a imagem.
  • rescale_factor (float, kwargs, opcional, padrão 0.00392156862745098) — Fator de reescala para reescalar a imagem, caso do_rescale esteja definido como True.
  • do_normalize (bool, kwargs, opcional, padrão True) — Se a imagem deve ser normalizada.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opcional, padrão [0.5, 0.5, 0.5]) — Média da imagem a ser usada para normalização. Tem efeito apenas se do_normalize estiver definido como True.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, opcional, padrão [0.5, 0.5, 0.5]) — Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se do_normalize estiver definido como True.
  • do_pad (bool, kwargs, opcional, padrão None) — Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, padrão None) — O tamanho em {"height": int, "width" int} para o preenchimento das imagens. Deve ser maior que qualquer tamanho de imagem fornecido para o pré-processamento. Se pad_size não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando do_pad=True.
  • do_center_crop (bool, kwargs, opcional) — Se deve recortar a imagem centralmente.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — Apenas ChannelDimension.FIRST é suportado. Adicionado para compatibilidade com processadores lentos.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — O formato da dimensão de canal para a imagem de entrada. Se não definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes:
    • "channels_first" ou ChannelDimension.FIRST: imagem no formato (num_channels, height, width).
    • "channels_last" ou ChannelDimension.LAST: imagem no formato (altura, largura, num_canais).
    • "none" ou ChannelDimension.NONE: imagem no formato (altura, largura).
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — O dispositivo em que os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Retorna tensores empilhados se definido como 'pt'; caso contrário, retorna uma lista de tensores.
  • disable_grouping (bool, kwargs, opcional) — Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157
  • image_seq_length (int, kwargs, opcional) — O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros.
  • mask_size (dict[str, *kwargs*, int], opcional) — O tamanho {"height": int, "width": int} para redimensionar os mapas de segmentação.

Constrói um processador de imagem Sam3ImageProcessor.

pré-processamento

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.models.sam3.image_processing_sam3.Sam3ImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature

Parâmetros

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se passar imagens com valores de pixel entre 0 e 1, defina do_rescale=False.
  • segmentation_maps (ImageInput, opcional) — Os mapas de segmentação a serem pré-processados.
  • do_convert_rgb (bool, kwargs, opcional) — Se a imagem deve ser convertida para RGB.
  • do_resize (bool, kwargs, opcional) — Se deve redimensionar a imagem.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Descreve as dimensões máximas de entrada para o modelo.
  • default_to_square (bool, kwargs, opcional) — Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Tamanho da imagem de saída após a aplicação de center_crop.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Filtro de redimensionamento a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração PILImageResampling. Tem efeito apenas se do_resize estiver definido como True.
  • do_rescale (bool, kwargs, opcional) — Se deve reescalar a imagem.
  • rescale_factor (float, kwargs, opcional) — Fator de redimensionamento para redimensionar a imagem, caso do_rescale esteja definido como True.
  • do_normalize (bool, kwargs, opcional) — Se a imagem deve ser normalizada.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opcional) — Média da imagem a ser usada para normalização. Tem efeito apenas se do_normalize estiver definido como True.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, opcional) — Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se do_normalize estiver definido como True.
  • do_pad (bool, kwargs, opcional) — Indica se a imagem deve ser preenchida (padding). O preenchimento é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de preenchimento depende do modelo.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — O tamanho em {"height": int, "width" int} para o preenchimento das imagens. Deve ser maior que qualquer tamanho de imagem fornecido para o pré-processamento. Se pad_size não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando do_pad=True.
  • do_center_crop (bool, kwargs, opcional) — Se deve recortar a imagem centralmente.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — Apenas ChannelDimension.FIRST é suportado. Adicionado para compatibilidade com processadores lentos.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — O formato da dimensão de canal para a imagem de entrada. Se não definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes:
    • "channels_first" ou ChannelDimension.FIRST: imagem no formato (num_channels, height, width).
    • "channels_last" ou ChannelDimension.LAST: imagem no formato (altura, largura, num_canais).
    • "none" ou ChannelDimension.NONE: imagem no formato (altura, largura).
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — O dispositivo em que os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Retorna tensores empilhados se definido como 'pt'; caso contrário, retorna uma lista de tensores.
  • disable_grouping (bool, kwargs, opcional) — Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157
  • image_seq_length (int, kwargs, opcional) — O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros.
  • mask_size (dict[str, *kwargs*, int], opcional) — O tamanho {"height": int, "width": int} para redimensionar os mapas de segmentação.

Retorna

~image_processing_base.BatchFeature

  • data (dict) — Dicionário de listas/arrays/tensors retornados pelo método call (‘pixel_values’, etc.).
  • tensor_type (Union[None, str, TensorType], opcional) — Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização.

Sam3ViTModel

classe transformers.Sam3ViTModel

< >

( config: Sam3ViTConfig )

Parâmetros

  • config (Sam3ViTConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo Sam3 puro, que produz estados ocultos brutos sem nenhum head específico no topo.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutput or tuple(torch.Tensor)

Parâmetros

Retorna

BaseModelOutput ou tuple(torch.Tensor)

Um BaseModelOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (Sam3Config) e das entradas.

O método forward do Sam3ViTModel sobrescreve o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.

  • hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Sam3VisionModel

classe transformers.Sam3VisionModel

< >

( config: Sam3VisionConfig )

Parâmetros

  • config (Sam3VisionConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo de visão do Sam, sem nenhum cabeçalho ou projeção no topo.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

( pixel_values: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

Sam3Model

classe transformers.Sam3Model

< >

( config: Sam3Config )

forward

< >

( pixel_values: typing.Optional[torch.Tensor] = Nonevision_embeds: transformers.models.sam3.modeling_sam3.Sam3VisionEncoderOutput | None = Noneinput_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonetext_embeds: typing.Optional[torch.Tensor] = Noneinput_boxes: typing.Optional[torch.Tensor] = Noneinput_boxes_labels: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3ImageSegmentationOutput or tuple(torch.Tensor)

Parâmetros

  • pixel_values (torch.Tensor de forma (batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando Sam3ImageProcessor. Consulte Sam3ImageProcessor.call() para mais detalhes (Sam3Processor usa Sam3ImageProcessor para processar as imagens).
  • vision_embeds (Sam3VisionEncoderOutput, opcional) — Incorporações de visão pré-computadas. Podem ser usadas para reutilizar facilmente incorporações de visão. Se fornecidas, pixel_values não devem ser passadas. Mutuamente exclusivo com pixel_values.
  • input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.

    Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

    O que são IDs de entrada?

  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

  • text_embeds (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Incorporações de texto pré-computadas. Pode ser usado para reutilizar facilmente incorporações de texto. Se fornecido, input_ids não deve ser passado. Mutuamente exclusivo com input_ids.
  • input_boxes (torch.Tensor de forma (batch_size, num_boxes, 4), opcional) — Coordenadas de caixa normalizadas no intervalo [0, 1], no formato (cx, cy, w, h).
  • input_boxes_labels (torch.LongTensor de forma (batch_size, num_boxes), opcional) — Rótulos para as caixas: 1 (positivo), 0 (negativo).

Retorna

Sam3ImageSegmentationOutput ou tuple(torch.Tensor)

Um Sam3ImageSegmentationOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (Sam3Config) e das entradas.

O método forward do Sam3Model sobrescreve o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • pred_masks (torch.Tensor de forma (batch_size, num_queries, height, width)) — Máscaras de segmentação previstas para cada query.
  • pred_boxes (torch.Tensor de forma (batch_size, num_queries, 4)) — Caixas delimitadoras previstas no formato (x1, y1, x2, y2).
  • pred_logits (torch.Tensor de forma (batch_size, num_queries), opcional) — Pontuações de confiança de classificação para cada query, calculadas por meio do produto escalar entre os recursos de query do decodificador e os recursos de texto.
  • presence_logits (torch.Tensor de forma (batch_size, 1), opcional) — Presence logits do token de presença do decodificador DETR (apenas a última camada). Esses valores indicam se há objetos presentes na cena. Podem ser usados para calcular as pontuações finais multiplicando-os por pred_logits: final_scores = pred_logits.sigmoid() * presence_logits.sigmoid().
  • semantic_seg (torch.Tensor de forma (batch_size, 1, height, width), opcional) — Saída de segmentação semântica.
  • decoder_hidden_states (tuple[torch.Tensor], opcional) — Tupla de estados ocultos de todas as camadas do decodificador DETR. Cada tensor tem a forma (batch_size, num_queries, hidden_size).
  • decoder_reference_boxes (torch.Tensor de forma (num_layers, batch_size, num_queries, 4), opcional) — Caixas de referência de todas as camadas do decodificador DETR.
  • encoder_hidden_states (tuple[torch.Tensor], opcional) — Tupla de estados ocultos de todas as camadas do codificador DETR.
  • vision_hidden_states (tuple[torch.Tensor], opcional) — Tupla dos estados ocultos de todas as camadas do codificador de visão (ViT).
  • vision_attentions (tuple[torch.Tensor], opcional) — Pesos de atenção das camadas do codificador de visão (ViT).
  • detr_encoder_attentions (tuple[torch.Tensor], opcional) — Pesos de atenção das camadas do codificador do DETR.
  • detr_decoder_attentions (tuple[torch.Tensor], opcional) — Pesos de atenção das camadas do decodificador do DETR (autoatenção e atenção cruzada).
  • mask_decoder_attentions (tuple[torch.Tensor], opcional) — Pesos de atenção das camadas do decodificador de máscara.

Exemplo:

>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor

>>> model = AutoModel.from_pretrained("facebook/sam3")
>>> processor = AutoProcessor.from_pretrained("facebook/sam3")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")
>>> text = "car"
>>> inputs = processor(images=image, text=text, return_tensors="pt")

>>> # Get segmentation output
>>> outputs = model(**inputs)
>>> pred_masks = outputs.pred_masks
>>> pred_boxes = outputs.pred_boxes

get_text_features

< >

( input_ids: LongTensorattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

Parâmetros

  • input_ids (torch.LongTensor de forma (batch_size, sequence_length)) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão. Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes. O que são IDs de entrada?

    Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

    O que são IDs de entrada?

  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

Retorna

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Um BaseModelOutputWithPooling ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (Sam3Config) e das entradas.

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.

  • pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.

  • hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplo:

>>> from transformers import Sam3Model, Sam3Processor
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> model = Sam3Model.from_pretrained("facebook/sam3")
>>> processor = Sam3Processor.from_pretrained("facebook/sam3")

>>> # Pre-compute text embeddings
>>> text_inputs = processor(text="cat", return_tensors="pt")
>>> text_embeds = model.get_text_features(**text_inputs).pooler_output

>>> # Reuse text embeddings for multiple images
>>> url = "http://images.cocodataset.org/val2017/000000077595.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))
>>> img_inputs = processor(images=image, return_tensors="pt")
>>> outputs = model(pixel_values=img_inputs.pixel_values, text_embeds=text_embeds)
Update on GitHub

←Qwen3VLMoe SAM3 Vídeo→