# SAM3 Vídeo

    
        
        
    

## Visão geral

SAM3 (Segment Anything Model 3) foi introduzido em [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

SAM3 Video executa **Segmentação de Conceitos Promptáveis (PCS)** em vídeos. O PCS recebe texto como entrada (por exemplo, "ônibus escolar amarelo") e prevê máscaras de instância e semânticas para **cada objeto** que corresponda ao conceito, preservando as identidades dos objetos entre os quadros do vídeo.

O modelo combina um módulo de detecção (SAM3) com um módulo de rastreamento (rastreador no estilo SAM2) para permitir o rastreamento robusto de objetos entre os quadros de um vídeo usando prompts de texto.

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 Conceitos 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 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. Tornamos o SAM 3 open source, juntamente com nosso novo benchmark Segment Anything with Concepts (SA-Co) para segmentação de conceitos promptável.*

Este modelo foi contribuído por [yonigozlan](https://huggingface.co/yonigozlan) e [ronghanghu](https://huggingface.co/ronghanghu).

## Exemplo de uso

### Segmentação e Rastreamento de Vídeo

#### Inferência de vídeo pré-carregado

Processe um vídeo com todos os quadros já disponíveis usando prompts de texto:

```python
from transformers import Sam3VideoModel, Sam3VideoProcessor
import torch

model = Sam3VideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3")

# Load video frames
from transformers.video_utils import load_video
video_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/bedroom.mp4"
video_frames, _ = load_video(video_url)

# Initialize video inference session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt to detect and track objects
text = "person"
inference_session = processor.add_text_prompt(
    inference_session=inference_session,
    text=text,
)

# Process all frames in the video
outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=inference_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(inference_session, model_outputs)
    outputs_per_frame[model_outputs.frame_idx] = processed_outputs

print(f"Processed {len(outputs_per_frame)} frames")
Processed 51 frames

# Access results for a specific frame
frame_0_outputs = outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects")
print(f"Object IDs: {frame_0_outputs['object_ids'].tolist()}")
print(f"Scores: {frame_0_outputs['scores'].tolist()}")
print(f"Boxes shape (XYXY format, absolute coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks shape: {frame_0_outputs['masks'].shape}")
```

Você também pode rastrear múltiplas categorias de objetos simultaneamente fornecendo múltiplos prompts. O modelo reutiliza de forma eficiente os recursos visuais entre todos os prompts:

```python
# Add multiple text prompts (or use a list in add_text_prompt)
multi_prompt_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)
>>>
prompts = ["person", "bed", "lamp"]
processor.add_text_prompt(multi_prompt_session, prompts)
>>>
# Process video - detects objects from ALL prompts in a single pass
multi_outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=multi_prompt_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(multi_prompt_session, model_outputs)
    multi_outputs_per_frame[model_outputs.frame_idx] = processed_outputs
>>>
# Check which objects were detected by each prompt
frame_0_outputs = multi_outputs_per_frame[0]
prompt_to_obj_ids = frame_0_outputs["prompt_to_obj_ids"]
for prompt, obj_ids in prompt_to_obj_ids.items():
    print(f"{prompt}: {len(obj_ids)} objects")
person: 2 objects
bed: 1 objects
lamp: 1 objects
```

#### Inferência de Vídeo em Streaming

⚠️ **Observação sobre a qualidade da inferência em streaming**: a inferência em streaming desativa as heurísticas de hotstart que removem objetos não correspondentes e duplicados, pois essas exigem acesso a quadros futuros para tomar decisões informadas. Isso pode resultar em mais detecções falsas positivas e rastreamentos de objetos duplicados em comparação com a inferência em vídeo pré-carregado. Para obter os melhores resultados, use a inferência em vídeo pré-carregado quando todos os quadros estiverem disponíveis.

Para aplicações em tempo real, o SAM3 Video suporta o processamento dos quadros de vídeo à medida que chegam:

```python
# Initialize session for streaming
streaming_inference_session = processor.init_video_session(
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt
text = "person"
streaming_inference_session = processor.add_text_prompt(
    inference_session=streaming_inference_session,
    text=text,
)

# Process frames one by one (streaming mode)
streaming_outputs_per_frame = {}
for frame_idx, frame in enumerate(video_frames[:50]):  # Process first 50 frames
    # First, process the frame using the processor
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    # Process frame using streaming inference - pass the processed pixel_values
    model_outputs = model(
        inference_session=streaming_inference_session,
        frame=inputs.pixel_values[0],  # Provide processed frame - this enables streaming mode
        reverse=False,
    )
...
    # Post-process outputs with original_sizes for proper resolution handling
    processed_outputs = processor.postprocess_outputs(
        streaming_inference_session,
        model_outputs,
        original_sizes=inputs.original_sizes,  # Required for streaming inference
    )
    streaming_outputs_per_frame[frame_idx] = processed_outputs
...
    if (frame_idx + 1) % 10 == 0:
        print(f"Processed {frame_idx + 1} frames...")

print(f"✓ Streaming inference complete! Processed {len(streaming_outputs_per_frame)} frames")
✓ Streaming inference complete! Processed 50 frames

# Access results
frame_0_outputs = streaming_outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects in first frame")
print(f"Boxes are in XYXY format (absolute pixel coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks are at original video resolution: {frame_0_outputs['masks'].shape}")
```

#### Inferência com Resolução Personalizada

⚠️ **Nota de desempenho**: resoluções personalizadas podem degradar a precisão. O modelo deve ser usado na resolução de 1008px.

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

```python
config = Sam3VideoConfig.from_pretrained("facebook/sam3")
config.image_size = 560
model = Sam3VideoModel.from_pretrained("facebook/sam3", config=config, device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3", size={"height": 560, "width": 560})
```

## Sam3VideoConfig[[transformers.Sam3VideoConfig]]

#### transformers.Sam3VideoConfig[[transformers.Sam3VideoConfig]]

```python
transformers.Sam3VideoConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, detector_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, tracker_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, low_res_mask_size: int = 288, score_threshold_detection: float = 0.5, det_nms_thresh: float = 0.1, assoc_iou_thresh: float = 0.1, trk_assoc_iou_thresh: float = 0.5, new_det_thresh: float = 0.7, recondition_on_trk_masks: bool = True, hotstart_delay: int = 15, hotstart_unmatch_thresh: int = 8, hotstart_dup_thresh: int = 8, suppress_unmatched_only_within_hotstart: bool = True, init_trk_keep_alive: int = 30, max_trk_keep_alive: int = 30, min_trk_keep_alive: int = -1, suppress_overlapping_based_on_recent_occlusion_threshold: float = 0.7, decrease_trk_keep_alive_for_empty_masklets: bool = False, fill_hole_area: int = 16, max_num_objects: int = 10000, recondition_every_nth_frame: int = 16, high_conf_thresh: float = 0.8, high_iou_thresh: float = 0.8)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/configuration_sam3_video.py#L28)

**Parâmetros:**

detector_config (`dict` ou `Sam3Config`, *opcional*) : Configuração para o modelo de detector Sam3. Se não for fornecida, a Sam3Config padrão será usada.

tracker_config (`dict` ou `Sam2VideoConfig`, *opcional*) : Configuração para o modelo de rastreamento Sam2Video. Se não for fornecida, a Sam2VideoConfig padrão será usada.

initializer_range (`float`, *opcional*, padrão 0.02) : O desvio padrão do truncated_normal_initializer para inicializar as matrizes de pesos.

low_res_mask_size (`int`, *opcional*, padrão 288) : Tamanho (altura e largura) das máscaras de baixa resolução de saída do rastreador antes do redimensionamento para a resolução do vídeo.

score_threshold_detection (`float`, *opcional*, padrão 0.5) : Limiar de probabilidade para as saídas de detecção - mantém apenas as detecções acima deste limiar.

det_nms_thresh (`float`, *opcional*, padrão 0.1) : Limiar de IoU para NMS (Non-Maximum Suppression) de detecção.

assoc_iou_thresh (`float`, *opcional*, padrão 0.1) : Limiar de IoU para o pareamento entre detecção e trilha. Uma detecção é considerada "pareada" a um tracklet se sobrepor ao tracklet acima deste limiar. Frequentemente, um limiar frouxo como 0.1.

trk_assoc_iou_thresh (`float`, *opcional*, padrão 0.5) : Limiar de IoU para o pareamento entre detecção e rastreamento, usado para determinar se um masklet é "não correspondido" por nenhuma detecção. Frequentemente, um limiar mais estrito, como 0.5.

new_det_thresh (`float`, *opcional*, padrão 0.7) : Limiar de probabilidade para uma detecção ser adicionada como um novo objeto.

recondition_on_trk_masks (`bool`, *opcional*, padrão `True`) : Se deve usar máscaras rastreadas (True) ou máscaras de detecção (False) para recondicionamento. Use True quando as máscaras rastreadas tiverem maior qualidade e o detector servir como sinal de validação para fortalecer a memória e prevenir deriva.

hotstart_delay (`int`, *opcional*, padrão 15) : Número de quadros para armazenar em buffer as saídas durante o hotstart. Retemos as saídas por `hotstart_delay` quadros e removemos tracklets com base em heurísticas de hotstart.

hotstart_unmatch_thresh (`int`, *opcional*, padrão 8) : Número de quadros não correspondidos necessários para remover um tracklet durante o período de hotstart.

hotstart_dup_thresh (`int`, *opcional*, padrão 8) : Número de quadros sobrepostos necessários para remover um tracklet duplicado durante o período de hotstart.

suppress_unmatched_only_within_hotstart (`bool`, *opcional*, padrão `True`) : Se deve suprimir máscaras apenas dentro do período de hotstart. Se False, podemos suprimir máscaras mesmo que comecem antes do período de hotstart.

init_trk_keep_alive (`int`, *opcional*, padrão 30) : Contador inicial de keep-alive para novas trilhas.

max_trk_keep_alive (`int`, *opcional*, padrão 30) : Valor máximo do contador de keep-alive. As faixas acompanhadas com detecções correspondentes têm seu contador incrementado até esse valor.

min_trk_keep_alive (`int`, *opcional*, padrão -1) : Valor mínimo do contador de keep-alive. As faixas com detecções não correspondidas têm seu contador reduzido para esse valor.

suppress_overlapping_based_on_recent_occlusion_threshold (`float`, *opcional*, padrão 0.7) : Limiar para suprimir objetos sobrepostos com base na oclusão recente. Máscaras sobrepostas com IoU acima deste limiar são suprimidas com base em qual foi ocluída mais recentemente.

decrease_trk_keep_alive_for_empty_masklets (`bool`, *opcional*, padrão `False`) : Se deve diminuir o contador de keep-alive para masklets com área zero na previsão do SAM2.

fill_hole_area (`int`, *opcional*, padrão 16) : Área mínima (em pixels) para preencher buracos nas máscaras e remover pequenos pontos.

max_num_objects (`int`, *opcional*, padrão 10000) : Número máximo de objetos a serem rastreados. O padrão 10000 efetivamente desativa esse limite.

recondition_every_nth_frame (`int`, *opcional*, padrão 16) : Frequência de recondicionamento da máscara (em quadros). Defina como 0 para desativar o recondicionamento.

high_conf_thresh (`float`, *opcional*, padrão 0.8) : Limiar de alta confiança para recondicionamento. Somente detecções acima deste limiar podem recondicionar tracklets.

high_iou_thresh (`float`, *opcional*, padrão 0.8) : Limite superior de IoU para recondicionamento. Somente detecções com IoU acima deste limite podem recondicionar tracklets.

Esta é a classe de configuração para armazenar a configuração de um Sam3VideoModel. Ela é usada para instanciar um modelo Sam3 Video 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](https://huggingface.co/facebook/sam3)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:
```python
>>> from transformers import Sam3VideoConfig, Sam3VideoModel

>>> # Initializing a SAM3 Video configuration with default detector and tracker
>>> configuration = Sam3VideoConfig()

>>> # Changing image size for custom resolution inference (automatically propagates to all nested configs)
>>> configuration.image_size = 560

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

>>> # Accessing the model configuration
>>> configuration = model.config
>>> detector_config = configuration.detector_config
>>> tracker_config = configuration.tracker_config
```

## Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

#### transformers.Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

```python
transformers.Sam3VideoProcessor(image_processor, video_processor, tokenizer, target_size: int | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L39)

**Parâmetros:**

image_processor (`Sam3ImageProcessor`) : O processador de imagem é uma entrada obrigatória.

video_processor (`video_processor_class`) : O processador de vídeo é 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.

Constrói um Sam3VideoProcessor que encapsula um processador de imagem, um processador de vídeo e um tokenizer em um único processador.

[Sam3VideoProcessor](/docs/transformers/main/pt/model_doc/sam3_video#transformers.Sam3VideoProcessor) oferece todas as funcionalidades de [Sam3ImageProcessor](/docs/transformers/main/pt/model_doc/sam3#transformers.Sam3ImageProcessor), `video_processor_class` e [CLIPTokenizer](/docs/transformers/main/pt/model_doc/clip#transformers.CLIPTokenizer). Consulte [~Sam3ImageProcessor](/docs/transformers/main/pt/model_doc/sam3#transformers.Sam3ImageProcessor), `~video_processor_class` e [~CLIPTokenizer](/docs/transformers/main/pt/model_doc/clip#transformers.CLIPTokenizer) para mais informações.

#### __call__[[transformers.Sam3VideoProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, 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, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L55)

**Parâmetros:**

images (`ImageInput`, *opcional*) : A(s) imagem(ns) a serem processadas.

segmentation_maps (`ImageInput`, *opcional*) : Os mapas de segmentação a serem processados (opcional, para o processador de imagem).

original_sizes (`list[list[float]]`, `torch.Tensor`, *opcional*) : Os tamanhos originais das imagens. Usado apenas quando images não é fornecido.

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](/docs/transformers/main/pt/main_classes/tokenizer#transformers.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`, *opcional*): Os mapas de segmentação processados (se fornecidos).

#### postprocess_outputs[[transformers.Sam3VideoProcessor.postprocess_outputs]]

```python
postprocess_outputs(inference_session, model_outputs, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L247)

**Parâmetros:**

inference_session (`Sam3VideoInferenceSession`) : O objeto de sessão de inferência.

model_outputs (`Sam3VideoSegmentationOutput`) : A saída bruta do modelo de `Sam3VideoModel.forward()`.

original_sizes (`list[list[float]]` ou `torch.Tensor`, *opcional*) : Tamanhos originais opcionais dos quadros [altura, largura]. Obrigatório para inferência em streaming quando video_height/video_width não estão definidos na sessão.

**Retorna:** `dict`

Um dicionário contendo as seguintes chaves:
- **object_ids** (`torch.Tensor` de forma `(num_objects,)`): IDs dos objetos para cada objeto detectado.
- **scores** (`torch.Tensor` de forma `(num_objects,)`): Pontuações de detecção para cada objeto.
- **boxes** (`torch.Tensor` de forma `(num_objects, 4)`): Caixas delimitadoras no formato XYXY (top_left_x, top_left_y, bottom_right_x, bottom_right_y).
- **máscaras** (`torch.Tensor` de forma `(num_objects, height, width)`): Máscaras de segmentação binárias para cada objeto na resolução original do vídeo.
- **prompt_to_obj_ids** (`dict[str, list[int]]`): Mapeamento do texto do prompt para a lista de IDs de objetos detectados por esse prompt.

Pós-processe as saídas do modelo para obter as máscaras, caixas e pontuações finais.

#### init_video_session[[transformers.Sam3VideoProcessor.init_video_session]]

```python
init_video_session(video: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None, inference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu', inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, processing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, video_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, max_vision_features_cache_size: int = 1, dtype: dtype = torch.float32)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L133)

**Parâmetros:**

video (`VideoInput`, *opcional*) : O vídeo a ser processado. Não é necessário fornecer durante o streaming.

inference_device (`str` ou `torch.device`, *opcional*, padrão "cpu") : O dispositivo a ser usado para inferência.

inference_state_device (`str` ou `torch.device`, *opcional*) : O dispositivo em que o estado de inferência será armazenado.

processing_device (`str` ou `torch.device`, *opcional*) : O dispositivo a ser usado para o processamento de vídeo.

video_storage_device (`str` ou `torch.device`, *opcional*) : O dispositivo em que os quadros de vídeo processados serão armazenados.

max_vision_features_cache_size (`int`, *opcional*, padrão 1) : O número máximo de recursos visuais a serem armazenados em cache.

dtype (`torch.dtype`, *opcional*, padrão `torch.float32`) : O dtype do torch a ser usado para toda a sessão.

Inicializa uma sessão de vídeo para inferência. Se um vídeo for fornecido (inferência assíncrona), o vídeo será processado e armazenado no `video_storage_device`.

#### add_text_prompt[[transformers.Sam3VideoProcessor.add_text_prompt]]

```python
add_text_prompt(inference_session: Sam3VideoInferenceSession, text: str | list[str])
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L101)

**Parâmetros:**

inference_session (`Sam3VideoInferenceSession`) : A sessão de inferência.

text (`str` ou `list[str]`) : O(s) prompt(s) de texto a adicionar.

**Retorna:** `Sam3VideoInferenceSession`

A sessão de inferência com o(s) prompt(s) de texto adicionado(s).

Adicione prompt(s) de texto à sessão de inferência.

## Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

#### transformers.Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

```python
transformers.Sam3VideoInferenceSession(video: typing.Optional[torch.Tensor] = None, video_height: int | None = None, video_width: int | None = None, inference_device: typing.Union[torch.device, str] = 'cpu', inference_state_device: typing.Union[torch.device, str] = 'cpu', video_storage_device: typing.Union[torch.device, str] = 'cpu', dtype: typing.Union[torch.dtype, str] = 'float32', max_vision_features_cache_size: int = 1)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L119)

**Parâmetros:**

video (`torch.Tensor`, *opcional*) : O vídeo a ser processado. Não é necessário fornecer durante o streaming.

video_height (`int`, *opcional*) : A altura do vídeo.

video_width (`int`, *opcional*) : A largura do vídeo.

inference_device (`torch.device`, *opcional*, padrão `"cpu"`) : O dispositivo a ser usado para inferência.

inference_state_device (`torch.device`, *opcional*, padrão `"cpu"`) : O dispositivo em que o estado de inferência será armazenado.

video_storage_device (`torch.device`, *opcional*, padrão `"cpu"`) : O dispositivo em que o vídeo será armazenado.

dtype (`torch.dtype`, *opcional*, padrão `"float32"`) : O dtype a ser usado para o vídeo.

max_vision_features_cache_size (`int`, *opcional*, padrão 1) : O número máximo de recursos visuais a serem armazenados em cache.

Gerencia os parâmetros, o estado e o cache da sessão de inferência de vídeo.

#### add_mask_inputs[[transformers.Sam3VideoInferenceSession.add_mask_inputs]]

```python
add_mask_inputs(obj_idx: int, frame_idx: int, inputs: Tensor)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L255)

Adicione entradas de máscara com posicionamento automático de dispositivo.

#### add_new_frame[[transformers.Sam3VideoInferenceSession.add_new_frame]]

```python
add_new_frame(pixel_values: Tensor, frame_idx: int | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L384)

Adicione um novo frame com posicionamento automático de dispositivo.

#### add_prompt[[transformers.Sam3VideoInferenceSession.add_prompt]]

```python
add_prompt(prompt_text: str)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L215)

Adiciona um prompt de texto à sessão e retorna seu ID exclusivo. Se o prompt já existir, retorna o ID existente.

#### get_frame[[transformers.Sam3VideoInferenceSession.get_frame]]

```python
get_frame(frame_idx: int)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L400)

Obter quadro do vídeo.

#### get_obj_num[[transformers.Sam3VideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L251)

Obtenha o número total de ids de objetos únicos recebidos até o momento nesta sessão.

#### get_output[[transformers.Sam3VideoInferenceSession.get_output]]

```python
get_output(obj_idx: int, frame_idx: int, output_key: str, is_conditioning_frame: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L357)

**Parâmetros:**

obj_idx (int) : O índice do objeto.

frame_idx (int) : O índice do quadro.

output_key (str) : A chave da saída.

is_conditioning_frame (bool) : Indica se a saída é para um quadro de condicionamento.

Obtenha a saída com gerenciamento inteligente de dispositivos.

#### obj_id_to_idx[[transformers.Sam3VideoInferenceSession.obj_id_to_idx]]

```python
obj_id_to_idx(obj_id: int)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L229)

Mapeia o ID do objeto para o índice, criando uma nova entrada, se necessário.

#### obj_idx_to_id[[transformers.Sam3VideoInferenceSession.obj_idx_to_id]]

```python
obj_idx_to_id(obj_idx: int)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L247)

Mapeia o índice do objeto no lado do modelo para o id do objeto no lado do cliente.

#### remove_mask_inputs[[transformers.Sam3VideoInferenceSession.remove_mask_inputs]]

```python
remove_mask_inputs(obj_idx: int, frame_idx: int)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L261)

Remova as entradas de máscara.

#### remove_object[[transformers.Sam3VideoInferenceSession.remove_object]]

```python
remove_object(obj_id: int, strict: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L265)

**Parâmetros:**

obj_id (`int`) : O ID do objeto a ser removido.

strict (`bool`, *opcional*, padrão `False`) : Se deve gerar um erro caso o objeto não exista.

Remove um objeto da sessão de inferência. Isso removeria o objeto de todos os quadros do vídeo.

#### reset_inference_session[[transformers.Sam3VideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L416)

Redefinir os dados de rastreamento e o cache.

#### reset_state[[transformers.Sam3VideoInferenceSession.reset_state]]

```python
reset_state()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L428)

Redefina o estado da sessão de inferência.

#### reset_tracking_data[[transformers.Sam3VideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L404)

Redefinir os dados de rastreamento, mas manter o cache.

#### store_output[[transformers.Sam3VideoInferenceSession.store_output]]

```python
store_output(obj_idx: int, frame_idx: int, output_key: str | None = None, output_value: typing.Union[torch.Tensor, dict, NoneType] = None, is_conditioning_frame: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L320)

**Parâmetros:**

obj_idx (int) : O índice do objeto.

frame_idx (int) : O índice do quadro.

output_key (Optional[str]) : A chave da saída. Se for None, a saída é armazenada como um dicionário.

output_value (Optional[Union[torch.Tensor, dict]]) : O valor da saída.

is_conditioning_frame (bool) : Indica se a saída é para um quadro de condicionamento.

Armazene a saída com gerenciamento inteligente de dispositivos. Se output_key for None, a saída é armazenada como um dicionário.

## Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

#### transformers.Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

```python
transformers.Sam3VideoSegmentationOutput(object_ids: list[int] | None = None, obj_id_to_mask: dict[int, torch.Tensor] | None = None, obj_id_to_score: dict[int, float] | None = None, obj_id_to_tracker_score: dict[int, float] | None = None, removed_obj_ids: set[int] | None = None, suppressed_obj_ids: set[int] | None = None, frame_idx: int | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L462)

**Parâmetros:**

object_ids (`list[int]`, *opcional*) : Lista de IDs de objetos sendo rastreados no quadro atual.

obj_id_to_mask (`dict[int, torch.Tensor]`, *opcional*) : Dicionário que mapeia IDs de objetos para suas máscaras de baixa resolução previstas. Cada máscara tem a forma `(1, H_low, W_low)`.

obj_id_to_score (`dict[int, float]`, *opcional*) : Dicionário que mapeia IDs de objetos para suas pontuações de detecção.

obj_id_to_tracker_score (`dict[int, float]`, *opcional*) : Dicionário que mapeia IDs de objetos para suas pontuações do rastreador no quadro atual.

removed_obj_ids (`set[int]`, *opcional*) : Conjunto de IDs de objetos que foram removidos (por exemplo, por meio de heurísticas de hotstart).

suppressed_obj_ids (`set[int]`, *opcional*) : Conjunto de IDs de objetos que foram suprimidos no frame atual.

frame_idx (`int`, *opcional*) : O índice do quadro do vídeo.

Classe base para a saída do modelo Sam3Video.

## Sam3VideoModel[[transformers.Sam3VideoModel]]

#### transformers.Sam3VideoModel[[transformers.Sam3VideoModel]]

```python
transformers.Sam3VideoModel(config: Sam3VideoConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L507)

**Parâmetros:**

config ([Sam3VideoConfig](/docs/transformers/main/pt/model_doc/sam3_video#transformers.Sam3VideoConfig)) : 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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sam3 Video básico, que gera os hidden-states brutos sem nenhum head específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.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](https://pytorch.org/docs/stable/nn.html#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 e comportamento gerais.

#### forward[[transformers.Sam3VideoModel.forward]]

```python
forward(inference_session: Sam3VideoInferenceSession, frame_idx: int | None = None, frame: typing.Optional[torch.Tensor] = None, reverse: bool = False, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L1693)

**Parâmetros:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : O objeto de sessão de inferência de vídeo.

frame_idx (`int`, *opcional*) : O índice do quadro em que a inferência será executada. Não é necessário fornecer ao inferir em um novo quadro transmitido.

frame (`torch.Tensor`, *opcional*) : O frame a ser processado. Forneça ao transmitir em streaming.

reverse (`bool`, *opcional*, padrão `False`) : Se deve propagar em sentido inverso.

Propague os objetos por meio de um quadro de vídeo transmitido.

#### propagate_in_video_iterator[[transformers.Sam3VideoModel.propagate_in_video_iterator]]

```python
propagate_in_video_iterator(inference_session: Sam3VideoInferenceSession, start_frame_idx: int = 0, max_frame_num_to_track: int | None = None, reverse: bool = False, show_progress_bar: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L1784)

**Parâmetros:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : O objeto de sessão de inferência de vídeo.

start_frame_idx (`int`, *opcional*, padrão `0`) : O índice do quadro inicial para a propagação.

max_frame_num_to_track (`int`, *opcional*) : O número máximo de quadros a serem rastreados. Se não for fornecido, todos os quadros do vídeo serão rastreados.

reverse (`bool`, *opcional*, padrão `False`) : Se deve propagar em sentido inverso.

show_progress_bar (`bool`, *opcional*, padrão `False`) : Se deve exibir uma barra de progresso durante a propagação.

**Retorna:** [Sam3VideoSegmentationOutput](/docs/transformers/main/pt/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) ou `tuple(torch.Tensor)`

Um [Sam3VideoSegmentationOutput](/docs/transformers/main/pt/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) 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 ([Sam3VideoConfig](/docs/transformers/main/pt/model_doc/sam3_video#transformers.Sam3VideoConfig)) e das entradas.

Propaga os prompts para obter resultados de grounding para o vídeo inteiro. Usado ao inicializar uma sessão de inferência com um vídeo completo. Gera Sam3VideoSegmentationOutput para cada quadro.

- **object_ids** (`list[int]`, *opcional*) -- Lista dos IDs de objetos rastreados no quadro atual.
- **obj_id_to_mask** (`dict[int, torch.Tensor]`, *opcional*) -- Dicionário que mapeia IDs de objetos para suas máscaras de baixa resolução previstas. Cada máscara tem a forma `(1, H_low, W_low)`.
- **obj_id_to_score** (`dict[int, float]`, *opcional*) -- Dicionário que mapeia IDs de objetos para suas pontuações de detecção.
- **obj_id_to_tracker_score** (`dict[int, float]`, *opcional*) -- Dicionário que mapeia IDs de objetos para suas pontuações do rastreador no quadro atual.
- **removed_obj_ids** (`set[int]`, *opcional*) -- Conjunto de IDs de objetos que foram removidos (por exemplo, por meio de heurísticas de hotstart).
- **suppressed_obj_ids** (`set[int]`, *opcional*) -- Conjunto de IDs de objetos que foram suprimidos no frame atual.
- **frame_idx** (`int`, *opcional*) -- O índice do quadro do vídeo.