# SAM3 Video

    
        
        
    

## Resumen

SAM3 (Segment Anything Model 3) se presentó en [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

SAM3 Video realiza **Segmentación de Conceptos Promptables (PCS)** en videos. PCS toma texto como entrada (por ejemplo, "autobús escolar amarillo") y predice máscaras de instancia y semánticas para **cada objeto** que coincida con el concepto, al tiempo que preserva las identidades de los objetos a lo largo de los fotogramas del video.

El modelo combina un módulo de detección (SAM3) con un módulo de seguimiento (seguimiento de estilo SAM2) para permitir un seguimiento robusto de objetos a través de los fotogramas de un video mediante indicaciones de texto.

El resumen del artículo es el siguiente:

*Presentamos Segment Anything Model (SAM) 3, un modelo unificado que detecta, segmenta y realiza seguimiento de objetos en imágenes y vídeos a partir de prompts de concepto, que definimos como frases nominales cortas (p. ej., "autobús escolar amarillo"), ejemplos de imagen o una combinación de ambos. La Segmentación de Conceptos con Prompts (PCS) toma dichos prompts y devuelve máscaras de segmentación e identidades únicas para todas las instancias de objetos coincidentes. Para avanzar en PCS, construimos un motor de datos escalable que genera un conjunto de datos de alta calidad con 4M de etiquetas de concepto únicas, incluyendo negativos difíciles, en imágenes y vídeos. Nuestro modelo consta de un detector a nivel de imagen y un rastreador de vídeo basado en memoria que comparten un único backbone. El reconocimiento y la localización se desacoplan mediante una presencia head, lo que mejora la precisión de la detección. SAM 3 duplica la precisión de los sistemas existentes tanto en PCS de imagen como de vídeo, y mejora las capacidades anteriores de SAM en tareas de segmentación visual. Publicamos SAM 3 en código abierto junto con nuestro nuevo benchmark Segment Anything with Concepts (SA-Co) para la segmentación de conceptos con prompts.*

Este modelo fue aportado por [yonigozlan](https://huggingface.co/yonigozlan) y [ronghanghu](https://huggingface.co/ronghanghu).

## Ejemplo de uso

### Segmentación y seguimiento de video

#### Inferencia de video precargado

Procesa un video con todos los fotogramas ya disponibles 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}")
```

También puede seguir varias categorías de objetos simultáneamente proporcionando varios prompts. El modelo reutiliza de manera eficiente las características visuales entre todos los 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
```

#### Inferencia de video en streaming

⚠️ **Nota sobre la calidad de la inferencia en streaming**: la inferencia en streaming desactiva las heurísticas de hotstart que eliminan objetos no coincidentes y duplicados, ya que estas requieren acceso a los fotogramas futuros para tomar decisiones informadas. Esto puede dar lugar a más detecciones falsas positivas y a pistas de objetos duplicados en comparación con la inferencia en video precargado. Para obtener los mejores resultados, utilice la inferencia en video precargado cuando todos los fotogramas estén disponibles.

Para aplicaciones en tiempo real, SAM3 Video admite el procesamiento de fotogramas de video a medida que llegan:

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

#### Inferencia con resolución personalizada

⚠️ **Nota sobre el rendimiento**: las resoluciones personalizadas pueden degradar la precisión. El modelo está diseñado para usarse con una resolución de 1008 px.

Para una inferencia más rápida o un menor uso de memoria:

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

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

**Parámetros:**

detector_config (`dict` o `Sam3Config`, *opcional*) : Configuración para el modelo de detector Sam3. Si no se proporciona, se utilizará la configuración Sam3Config predeterminada.

tracker_config (`dict` o `Sam2VideoConfig`, *opcional*) : Configuración para el modelo de seguimiento Sam2Video. Si no se proporciona, se utilizará la configuración Sam2VideoConfig predeterminada.

initializer_range (`float`, *opcional*, valor predeterminado 0.02) : La desviación estándar de truncated_normal_initializer para inicializar las matrices de pesos.

low_res_mask_size (`int`, *opcional*, valor predeterminado 288) : Tamaño (altura y ancho) de las máscaras de baja resolución de salida del tracker antes de aumentar la escala a la resolución del video.

score_threshold_detection (`float`, *opcional*, valor predeterminado 0.5) : Umbral de probabilidad para las salidas de detección: solo se conservan las detecciones que superan este umbral.

det_nms_thresh (`float`, *opcional*, valor predeterminado 0.1) : Umbral de IoU para la NMS (Non-Maximum Suppression) de detección.

assoc_iou_thresh (`float`, *opcional*, valor predeterminado 0.1) : Umbral de IoU para el emparejamiento de detección a seguimiento. Una detección se considera "emparejada" con un tracklet si se superpone con el tracklet por encima de este umbral. A menudo se utiliza un umbral laxo como 0.1.

trk_assoc_iou_thresh (`float`, *opcional*, valor predeterminado 0.5) : Umbral de IoU para el emparejamiento de detección a seguimiento, utilizado para determinar si un masklet no está "emparejado" por ninguna detección. A menudo se utiliza un umbral más estricto, como 0.5.

new_det_thresh (`float`, *opcional*, valor predeterminado 0.7) : Umbral de probabilidad para que una detección se añada como un objeto nuevo.

recondition_on_trk_masks (`bool`, *opcional*, valor predeterminado `True`) : Indica si se deben usar máscaras rastreadas (True) o máscaras de detección (False) para la recondición. Utilice True cuando las máscaras rastreadas sean de mayor calidad y el detector actúe como señal de validación para reforzar la memoria y prevenir la deriva.

hotstart_delay (`int`, *opcional*, valor predeterminado: 15) : Número de fotogramas para almacenar en búfer las salidas durante el hotstart. Retenemos las salidas durante `hotstart_delay` fotogramas y eliminamos los tracklets según las heurísticas de hotstart.

hotstart_unmatch_thresh (`int`, *opcional*, valor predeterminado 8) : Número de fotogramas no coincidentes necesarios para eliminar un tracklet durante el período de hotstart.

hotstart_dup_thresh (`int`, *opcional*, valor predeterminado 8) : Número de fotogramas superpuestos necesarios para eliminar un tracklet duplicado durante el período de hotstart.

suppress_unmatched_only_within_hotstart (`bool`, *opcional*, valor predeterminado `True`) : Si se deben suprimir las máscaras solo dentro del período de hotstart. Si es False, se pueden suprimir máscaras incluso si comienzan antes del período de hotstart.

init_trk_keep_alive (`int`, *opcional*, valor predeterminado 30) : Contador inicial de keep-alive para nuevas pistas.

max_trk_keep_alive (`int`, *opcional*, valor predeterminado: 30) : Valor máximo del contador de keep-alive. Las detecciones coincidentes tienen su contador incrementado hasta este valor.

min_trk_keep_alive (`int`, *opcional*, valor predeterminado: -1) : Valor mínimo del contador de keep-alive. Las pistas con detecciones no coincidentes tienen su contador disminuido hasta este valor.

suppress_overlapping_based_on_recent_occlusion_threshold (`float`, *opcional*, valor predeterminado 0.7) : Umbral para suprimir objetos superpuestos en función de la oclusión reciente. Las máscaras superpuestas con un IoU superior a este umbral se suprimen según cuál fue ocluida más recientemente.

decrease_trk_keep_alive_for_empty_masklets (`bool`, *opcional*, valor predeterminado `False`) : Si se debe disminuir el contador de keep-alive para las masklets con área cero en la predicción de SAM2.

fill_hole_area (`int`, *opcional*, valor predeterminado 16) : Área mínima (en píxeles) para rellenar huecos en las máscaras y eliminar pequeñas motas.

max_num_objects (`int`, *opcional*, valor predeterminado 10000) : Número máximo de objetos a seguir. El valor predeterminado de 10000 desactiva efectivamente este límite.

recondition_every_nth_frame (`int`, *opcional*, valor predeterminado 16) : Frecuencia de la recondicionación de la máscara (en fotogramas). Establezca 0 para deshabilitar la recondicionación.

high_conf_thresh (`float`, *opcional*, valor predeterminado 0.8) : Umbral de alta confianza para el recondicionamiento. Solo las detecciones por encima de este umbral pueden recondicionar los tracklets.

high_iou_thresh (`float`, *opcional*, valor predeterminado 0.8) : Umbral de IoU alto para la recondicionamiento. Solo las detecciones con un IoU superior a este umbral pueden recondicionar los tracklets.

Esta es la clase de configuración para almacenar la configuración de un Sam3VideoModel. Se utiliza para instanciar un modelo Sam3 Video según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [facebook/sam3](https://huggingface.co/facebook/sam3)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

Ejemplo:
```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)
```

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

**Parámetros:**

image_processor (`Sam3ImageProcessor`) : El procesador de imágenes es un parámetro de entrada obligatorio.

video_processor (`video_processor_class`): el procesador de video es un parámetro de entrada obligatorio.

tokenizer (`CLIPTokenizer`) : El tokenizador es una entrada obligatoria.

target_size (`int`, *opcional*) : El tamaño objetivo (target_size, target_size) al que se redimensionará la imagen.

Construye un Sam3VideoProcessor que encapsula un procesador de imágenes, un procesador de video y un tokenizador en un único procesador.

[Sam3VideoProcessor](/docs/transformers/v5.23.0/es/model_doc/sam3_video#transformers.Sam3VideoProcessor) ofrece todas las funcionalidades de [Sam3ImageProcessor](/docs/transformers/v5.23.0/es/model_doc/sam3#transformers.Sam3ImageProcessor), `video_processor_class` y [CLIPTokenizer](/docs/transformers/v5.23.0/es/model_doc/clip#transformers.CLIPTokenizer). Consulte [~Sam3ImageProcessor](/docs/transformers/v5.23.0/es/model_doc/sam3#transformers.Sam3ImageProcessor), `~video_processor_class` y [~CLIPTokenizer](/docs/transformers/v5.23.0/es/model_doc/clip#transformers.CLIPTokenizer) para obtener más información.

#### __llamada__[[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)
```

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

**Parámetros:**

images (`ImageInput`, *opcional*) : La(s) imagen(es) a procesar.

segmentation_maps (`ImageInput`, *opcional*) : Los mapas de segmentación a procesar (opcional, para el procesador de imágenes).

original_sizes (`list[list[float]]`, `torch.Tensor`, *opcional*) : Los tamaños originales de las imágenes. Solo se utiliza cuando no se proporciona images.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *opcional*) : Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:  - `'pt'`: Devuelve objetos `torch.Tensor` de PyTorch. - `'np'`: Devuelve objetos `np.ndarray` de NumPy.

**Devuelve:** un [BatchEncoding](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.BatchEncoding) con los siguientes campos

- `pixel_values` (`torch.Tensor`): La(s) imagen(es) procesada(s).
- `original_sizes` (`list[list[float]]`): Los tamaños originales de las imágenes.
- `labels` (`torch.Tensor`, *opcional*): Los mapas de segmentación procesados (si se proporcionan).

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

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

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

**Parámetros:**

inference_session (`Sam3VideoInferenceSession`) : El objeto de sesión de inferencia.

model_outputs (`Sam3VideoSegmentationOutput`) : La salida cruda del modelo de `Sam3VideoModel.forward()`.

original_sizes (`list[list[float]]` o `torch.Tensor`, *opcional*) : Tamaños originales opcionales de los fotogramas [altura, ancho]. Obligatorio para la inferencia en streaming cuando video_height/video_width no están configurados en la sesión.

**Devuelve:** `dict`

Un diccionario que contiene las siguientes claves:
- **object_ids** (`torch.Tensor` de forma `(num_objects,)`): IDs de objeto para cada objeto detectado.
- **scores** (`torch.Tensor` de forma `(num_objects,)`): Puntuaciones de detección para cada objeto.
- **boxes** (`torch.Tensor` de forma `(num_objects, 4)`): Cajas delimitadoras en 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 segmentación binarias para cada objeto en la resolución original del video.
- **prompt_to_obj_ids** (`dict[str, list[int]]`): Mapeo del texto del prompt a la lista de IDs de objetos detectados por ese prompt.

Post-procesar las salidas del modelo para obtener las máscaras, cajas y puntuaciones finales.

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

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

**Parámetros:**

video (`VideoInput`, *opcional*) : El video a procesar. No es necesario proporcionarlo durante la transmisión.

inference_device (`str` o `torch.device`, *opcional*, valor predeterminado "cpu") : El dispositivo que se usará para la inferencia.

inference_state_device (`str` o `torch.device`, *opcional*) : El dispositivo en el que se almacenará el estado de inferencia.

processing_device (`str` o `torch.device`, *opcional*) : El dispositivo que se usará para el procesamiento de video.

video_storage_device (`str` o `torch.device`, *opcional*) : El dispositivo en el que se almacenarán los fotogramas de vídeo procesados.

max_vision_features_cache_size (`int`, *opcional*, valor predeterminado: 1) : El número máximo de características visuales que se pueden almacenar en caché.

dtype (`torch.dtype`, *opcional*, valor predeterminado `torch.float32`) : El dtype de torch que se usará para toda la sesión.

Inicializa una sesión de video para inferencia. Si se proporciona un video (inferencia asíncrona), el video se procesará y se almacenará en `video_storage_device`.

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

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

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

**Parámetros:**

inference_session (`Sam3VideoInferenceSession`) : La sesión de inferencia.

text (`str` o `list[str]`) : El o los prompts de texto a añadir.

**Devuelve:** `Sam3VideoInferenceSession`

La sesión de inferencia con los prompts de texto añadidos.

Agregue el o los prompts de texto a la sesión de inferencia.

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

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

**Parámetros:**

video (`torch.Tensor`, *opcional*) : El video a procesar. No es necesario proporcionarlo al transmitir en streaming.

video_height (`int`, *opcional*) : La altura del video.

video_width (`int`, *opcional*) : El ancho del video.

inference_device (`torch.device`, *opcional*, valor predeterminado `"cpu"`) : El dispositivo que se usará para la inferencia.

inference_state_device (`torch.device`, *opcional*, valor predeterminado `"cpu"`) : El dispositivo en el que se almacenará el estado de inferencia.

video_storage_device (`torch.device`, *opcional*, valor predeterminado `"cpu"`) : El dispositivo en el que se almacenará el video.

dtype (`torch.dtype`, *opcional*, valor predeterminado `"float32"`) : El dtype a utilizar para el vídeo.

max_vision_features_cache_size (`int`, *opcional*, valor predeterminado: 1) : El número máximo de características visuales que se pueden almacenar en caché.

Gestiona los parámetros, el estado y la caché de la sesión de inferencia de video.

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

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

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

Agregue entradas de máscara con colocación automática de dispositivos.

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

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

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

Agregue un nuevo marco con colocación automática de dispositivos.

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

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

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

Añade un prompt de texto a la sesión y devuelve su ID único. Si el prompt ya existe, devuelve el ID existente.

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

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

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

Obtener un fotograma del video.

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

```python
get_obj_num()
```

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

Obtenga el número total de ids de objetos únicos recibidos hasta ahora en esta sesión.

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

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

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

**Parámetros:**

obj_idx (int) : El índice del objeto.

frame_idx (int) : El índice del fotograma.

output_key (str) : La clave de la salida.

is_conditioning_frame (bool) : Indica si la salida corresponde a un fotograma de condicionamiento.

Obtén la salida con una gestión inteligente de dispositivos.

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

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

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

Mapea el ID del objeto a un índice, creando una nueva entrada si es necesario.

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

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

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

Mapea el índice de objeto del lado del modelo al id de objeto del lado del cliente.

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

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

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

Eliminar las entradas de máscara.

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

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

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

**Parámetros:**

obj_id (`int`) : El ID del objeto a eliminar.

strict (`bool`, *opcional*, valor predeterminado `False`) : Si se debe lanzar un error si el objeto no existe.

Elimina un objeto de la sesión de inferencia. Esto eliminará el objeto de todos los fotogramas del video.

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

```python
reset_inference_session()
```

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

Restablecer los datos de seguimiento y la caché.

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

```python
reset_state()
```

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

Restablecer el estado de la sesión de inferencia.

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

```python
reset_tracking_data()
```

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

Restablecer los datos de seguimiento pero conservar la caché.

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

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

**Parámetros:**

obj_idx (int) : El índice del objeto.

frame_idx (int) : El índice del fotograma.

output_key (Optional[str]) : La clave de la salida. Si es None, la salida se almacena como un diccionario.

output_value (Optional[Union[torch.Tensor, dict]]) : El valor de la salida.

is_conditioning_frame (bool) : Indica si la salida corresponde a un fotograma de condicionamiento.

Almacena la salida con una gestión inteligente de dispositivos. Si output_key es None, la salida se almacena como un diccionario.

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

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

**Parámetros:**

object_ids (`list[int]`, *opcional*) : Lista de IDs de objetos que se están rastreando en el fotograma actual.

obj_id_to_mask (`dict[int, torch.Tensor]`, *opcional*) : Diccionario que mapea los IDs de objetos a sus máscaras de baja resolución predichas. Cada máscara tiene la forma `(1, H_low, W_low)`.

obj_id_to_score (`dict[int, float]`, *opcional*) : Diccionario que mapea los IDs de objetos a sus puntuaciones de detección.

obj_id_to_tracker_score (`dict[int, float]`, *opcional*) : Diccionario que mapea los IDs de los objetos a sus puntuaciones del tracker para el fotograma actual.

removed_obj_ids (`set[int]`, *opcional*) : Conjunto de IDs de objetos que se han eliminado (p. ej., mediante heurísticas de hotstart).

suppressed_obj_ids (`set[int]`, *opcional*) : Conjunto de IDs de objetos que se han suprimido en el marco actual.

frame_idx (`int`, *opcional*) : El índice de fotograma del video.

Clase base para la salida del modelo Sam3Video.

## Sam3VideoModel[[transformers.Sam3VideoModel]]

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

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

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

**Parámetros:**

config ([Sam3VideoConfig](/docs/transformers/v5.23.0/es/model_doc/sam3_video#transformers.Sam3VideoConfig)) : Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método [from_pretrained()](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

El modelo Sam3 Video básico que genera estados ocultos sin ningún cabezal específico en la parte superior.

Este modelo hereda de [PreTrainedModel](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel). Consulte la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

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

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

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

**Parámetros:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : El objeto de sesión de inferencia de video.

frame_idx (`int`, *opcional*) : El índice del fotograma en el que se ejecutará la inferencia. No es necesario proporcionarlo al realizar la inferencia en un nuevo fotograma transmitido.

frame (`torch.Tensor`, *opcional*) : El fotograma a procesar. Proporciónalo durante la transmisión en directo.

reverse (`bool`, *opcional*, valor predeterminado `False`) : Si se debe propagar en reversa.

Propagar los objetos a través de un fotograma de video 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)
```

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

**Parámetros:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : El objeto de sesión de inferencia de video.

start_frame_idx (`int`, *opcional*, valor predeterminado `0`) : El índice de cuadro inicial para la propagación.

max_frame_num_to_track (`int`, *opcional*) : El número máximo de fotogramas a seguir. Si no se proporciona, se seguirán todos los fotogramas del video.

reverse (`bool`, *opcional*, valor predeterminado `False`) : Si se debe propagar en reversa.

show_progress_bar (`bool`, *opcional*, valor predeterminado `False`) : Si se muestra una barra de progreso durante la propagación.

**Devuelve:** [Sam3VideoSegmentationOutput](/docs/transformers/v5.23.0/es/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) o `tuple(torch.Tensor)`

Un [Sam3VideoSegmentationOutput](/docs/transformers/v5.23.0/es/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) o una tupla de `torch.Tensor` (si se pasa `return_dict=False` o cuando `config.return_dict=False`) que comprende varios elementos según la configuración ([Sam3VideoConfig](/docs/transformers/v5.23.0/es/model_doc/sam3_video#transformers.Sam3VideoConfig)) y las entradas.

Propaga los prompts para obtener resultados de grounding para el video completo. Se utiliza al inicializar una sesión de inferencia con un video completo. Genera Sam3VideoSegmentationOutput para cada fotograma.

- **object_ids** (`list[int]`, *opcional*) -- Lista de IDs de objetos que se están rastreando en el fotograma actual.
- **obj_id_to_mask** (`dict[int, torch.Tensor]`, *opcional*) -- Diccionario que mapea los IDs de objetos a sus máscaras de baja resolución predichas. Cada máscara tiene la forma `(1, H_low, W_low)`.
- **obj_id_to_score** (`dict[int, float]`, *opcional*) -- Diccionario que mapea los IDs de objetos a sus puntuaciones de detección.
- **obj_id_to_tracker_score** (`dict[int, float]`, *opcional*) -- Diccionario que mapea los IDs de objetos a sus puntuaciones del tracker para el fotograma actual.
- **removed_obj_ids** (`set[int]`, *opcional*) -- Conjunto de IDs de objetos que han sido eliminados (p. ej., mediante heurísticas de hotstart).
- **suppressed_obj_ids** (`set[int]`, *opcional*) -- Conjunto de IDs de objetos que han sido suprimidos en el marco actual.
- **frame_idx** (`int`, *opcional*) -- El índice del fotograma del video.