# SAM3 Tracker Video

    
        
        
    

## Tổng quan

SAM3 (Segment Anything Model 3) được giới thiệu trong [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

Sam3TrackerVideo thực hiện **Phân đoạn thị giác có thể gợi ý (Promptable Visual Segmentation - PVS)** trên video. PVS nhận các gợi ý thị giác tương tác (điểm, hộp, mặt nạ) hoặc đầu vào dạng văn bản để theo dõi **một phiên bản đối tượng cụ thể** cho mỗi gợi ý xuyên suốt các khung hình của video.

Sam3TrackerVideo là phiên bản cập nhật của SAM2 Video, giữ nguyên API nhưng cung cấp hiệu suất và khả năng được cải thiện.

Tóm tắt từ bài báo như sau:

*Chúng tôi giới thiệu Segment Anything Model (SAM) 3, một mô hình thống nhất có khả năng phát hiện, phân đoạn và theo dõi các đối tượng trong ảnh và video dựa trên các prompt khái niệm, được chúng tôi định nghĩa là các cụm danh từ ngắn (ví dụ: "yellow school bus"), các ví dụ hình ảnh, hoặc sự kết hợp của cả hai. Promptable Concept Segmentation (PCS) nhận các prompt như vậy và trả về các mặt nạ phân đoạn cùng với danh tính duy nhất cho tất cả các phiên bản đối tượng khớp. Để thúc đẩy PCS, chúng tôi xây dựng một động cơ dữ liệu có khả năng mở rộng, tạo ra một bộ dữ liệu chất lượng cao với 4 triệu nhãn khái niệm duy nhất, bao gồm cả các âm tính khó, trên cả ảnh và video. Mô hình của chúng tôi bao gồm một bộ phát hiện ở cấp độ ảnh và một bộ theo dõi video dựa trên bộ nhớ, chia sẻ một backbone duy nhất. Nhận dạng và định vị được tách rời bằng một presence head, giúp tăng độ chính xác của việc phát hiện. SAM 3 gấp đôi độ chính xác so với các hệ thống hiện có trong cả PCS trên ảnh và video, đồng thời cải thiện các khả năng trước đó của SAM trên các nhiệm vụ phân đoạn thị giác. Chúng tôi mã nguồn mở SAM 3 cùng với bộ chuẩn đánh giá mới Segment Anything with Concepts (SA-Co) của chúng tôi cho phân đoạn khái niệm có thể prompt.*

Mô hình này được đóng góp bởi [yonigozlan](https://huggingface.co/yonigozlan) và [ronghanghu](https://huggingface.co/ronghanghu).

## Ví dụ sử dụng

### Phân đoạn và Theo dõi Video

#### Theo dõi video cơ bản

```python
from transformers import Sam3TrackerVideoModel, Sam3TrackerVideoProcessor
import torch

model = Sam3TrackerVideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerVideoProcessor.from_pretrained("facebook/sam3")

# Load video frames (example assumes you have a list of PIL Images)
# video_frames = [Image.open(f"frame_{i:05d}.jpg") for i in range(num_frames)]

# For this example, we'll use the video loading utility
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,
)

# Add click on first frame to select object
ann_frame_idx = 0
ann_obj_id = 1
points = [[[[210, 350]]]]
labels = [[[1]]]

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=ann_obj_id,
    input_points=points,
    input_labels=labels,
)

# Segment the object on the first frame (optional, you can also propagate the masks through the video directly)
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
    [outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Segmentation shape: {video_res_masks.shape}")
Segmentation shape: torch.Size([1, 1, 480, 854])

# Propagate through the entire video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks

print(f"Tracked object through {len(video_segments)} frames")
Tracked object through 180 frames
```

#### Theo dõi video đa đối tượng

Theo dõi nhiều đối tượng đồng thời qua các khung hình video:

```python
# Reset for new tracking session
inference_session.reset_inference_session()

# Add multiple objects on the first frame
ann_frame_idx = 0
obj_ids = [2, 3]
input_points = [[[[200, 300]], [[400, 150]]]]  # Points for two objects (batched)
input_labels = [[[1], [1]]]

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=obj_ids,
    input_points=input_points,
    input_labels=input_labels,
)

# Get masks for both objects on first frame (optional, you can also propagate the masks through the video directly)
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)

# Propagate both objects through video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = {
        obj_id: video_res_masks[i]
        for i, obj_id in enumerate(inference_session.obj_ids)
    }

print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 frames
```

#### Tinh chỉnh phân đoạn video

Bạn có thể thêm các lần nhấp bổ sung vào bất kỳ khung hình nào để tinh chỉnh việc theo dõi:

```python
# Add refinement click on a later frame
refine_frame_idx = 50
ann_obj_id = 2  # Refining first object
points = [[[[220, 280]]]]  # Additional point
labels = [[[1]]]  # Positive click

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=refine_frame_idx,
    obj_ids=ann_obj_id,
    input_points=points,
    input_labels=labels,
)

# Re-propagate with the additional information
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks
```

### Suy luận Video trực tiếp

Đối với các ứng dụng thời gian thực, Sam3TrackerVideo hỗ trợ xử lý các khung hình video ngay khi chúng được nhận:

```python
# Initialize session for streaming
inference_session = processor.init_video_session(
    inference_device=device,
)

# Process frames one by one
for frame_idx, frame in enumerate(video_frames[:10]):  # Process first 10 frames
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    if frame_idx == 0:
        # Add point input on first frame
        processor.add_inputs_to_inference_session(
            inference_session=inference_session,
            frame_idx=0,
            obj_ids=1,
            input_points=[[[[210, 350], [250, 220]]]],
            input_labels=[[[1, 1]]],
            original_size=inputs.original_sizes[0], # need to be provided when using streaming video inference
        )
...
    # Process current frame
    sam3_tracker_video_output = model(inference_session=inference_session, frame=inputs.pixel_values[0])
...
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=inputs.original_sizes, binarize=False
    )[0]
    print(f"Frame {frame_idx}: mask shape {video_res_masks.shape}")
```

#### Xử lý hàng loạt video cho nhiều đối tượng

Theo dõi nhiều đối tượng đồng thời trong video bằng cách thêm tất cả chúng cùng lúc:

```python
# Initialize video session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
)

# Add multiple objects on the first frame using batch processing
ann_frame_idx = 0
obj_ids = [2, 3]  # Track two different objects
input_points = [
    [[[200, 300], [230, 250], [275, 175]], [[400, 150]]]
]  # Object 2: 3 points (2 positive, 1 negative); Object 3: 1 point
input_labels = [
    [[1, 1, 0], [1]]
]  # Object 2: positive, positive, negative; Object 3: positive

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=obj_ids,
    input_points=input_points,
    input_labels=input_labels,
)

# Get masks for all objects on the first frame
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
    [outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Generated masks for {video_res_masks.shape[0]} objects")
Generated masks for 2 objects

# Propagate all objects through the video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = {
        obj_id: video_res_masks[i]
        for i, obj_id in enumerate(inference_session.obj_ids)
    }

print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 frames
```

## Sam3TrackerVideoConfig[[transformers.Sam3TrackerVideoConfig]]

#### transformers.Sam3TrackerVideoConfig[[transformers.Sam3TrackerVideoConfig]]

```python
transformers.Sam3TrackerVideoConfig(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, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, num_maskmem: int = 7, sigmoid_scale_for_mem_enc: float = 20.0, sigmoid_bias_for_mem_enc: float = -10.0, enable_occlusion_spatial_embedding: bool = True, multimask_output_in_sam: bool = True, multimask_min_pt_num: int = 0, multimask_max_pt_num: int = 1, multimask_output_for_tracking: bool = True, max_object_pointers_in_encoder: int = 16, max_cond_frame_num: int = 4, enable_temporal_pos_encoding_for_object_pointers: bool = True, memory_attention_hidden_size: int = 256, memory_attention_num_layers: int = 4, memory_attention_num_attention_heads: int = 1, memory_attention_downsample_rate: int = 1, memory_attention_feed_forward_hidden_size: int = 2048, memory_attention_feed_forward_hidden_act: str = 'relu', memory_attention_dropout: float | int = 0.1, memory_attention_rope_feat_sizes: list | None = None, memory_attention_rope_dropout: float | int = 0.1, memory_encoder_hidden_size: int = 256, memory_encoder_output_channels: int = 64, rope_parameters: dict | None = None, mask_downsampler_embed_dim: int = 256, mask_downsampler_kernel_size: int = 3, mask_downsampler_stride: int = 2, mask_downsampler_padding: int = 1, mask_downsampler_total_stride: int = 16, mask_downsampler_hidden_act: str = 'gelu', memory_fuser_num_layers: int = 2, memory_fuser_embed_dim: int = 256, memory_fuser_intermediate_dim: int = 1024, memory_fuser_kernel_size: int = 7, memory_fuser_padding: int = 3, memory_fuser_layer_scale_init_value: float = 1e-06, memory_fuser_hidden_act: str = 'gelu')
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/configuration_sam3_tracker_video.py#L99)

**Tham số:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *tùy chọn*) : Đối tượng config hoặc từ điển của vision backbone.

prompt_encoder_config (Union[`dict`, `Sam3TrackerVideoPromptEncoderConfig`], *optional*) : Từ điển các tùy chọn cấu hình được sử dụng để khởi tạo [Sam3TrackerVideoPromptEncoderConfig](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `Sam3TrackerVideoMaskDecoderConfig`], *optional*) : Từ điển các tùy chọn cấu hình được sử dụng để khởi tạo [Sam3TrackerVideoMaskDecoderConfig](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoMaskDecoderConfig).

initializer_range (`float`, *tuỳ chọn*, mặc định là 0.02) : Độ lệch chuẩn cho việc khởi tạo tham số.

num_maskmem (`int`, *tuỳ chọn*, mặc định là 7) : Số lượng khe bộ nhớ cho bộ nhớ mặt nạ.

sigmoid_scale_for_mem_enc (`float`, *tuỳ chọn*, mặc định là 20.0) : Hệ số tỷ lệ cho hàm sigmoid trong bộ mã hóa bộ nhớ.

sigmoid_bias_for_mem_enc (`float`, *tuỳ chọn*, mặc định là -10.0) : Bias cho hàm sigmoid trong bộ mã hóa bộ nhớ.

enable_occlusion_spatial_embedding (`bool`, *tùy chọn*, mặc định là `True`) : Có bật nhúng không gian cho các vùng bị che khuất hay không.

multimask_output_in_sam (`bool`, *tuỳ chọn*, mặc định là `True`) : Có xuất ra nhiều mask từ đầu SAM hay không.

multimask_min_pt_num (`int`, *optional*, mặc định là 0) : Số điểm tối thiểu để kích hoạt đầu ra multimask.

multimask_max_pt_num (`int`, *tuỳ chọn*, mặc định là 1) : Số điểm tối đa để kích hoạt đầu ra multimask.

multimask_output_for_tracking (`bool`, *tuỳ chọn*, mặc định là `True`) : Có sử dụng đầu ra đa mặt nạ cho việc theo dõi hay không.

max_object_pointers_in_encoder (`int`, *tuỳ chọn*, mặc định là 16) : Số lượng con trỏ đối tượng tối đa trong bộ mã hóa.

max_cond_frame_num (`int`, *optional*, mặc định là 4) : Số lượng tối đa các khung điều kiện được sử dụng trong bộ nhớ chú ý.

enable_temporal_pos_encoding_for_object_pointers (`bool`, *tùy chọn*, mặc định là `True`) : Có bật mã hóa vị trí theo thời gian cho các con trỏ đối tượng hay không.

memory_attention_hidden_size (`int`, *tuỳ chọn*, mặc định là 256) : Độ chiều của các trạng thái ẩn của chú ý bộ nhớ.

memory_attention_num_layers (`int`, *tuỳ chọn*, mặc định là 4) : Số lượng lớp trong module chú ý bộ nhớ.

memory_attention_num_attention_heads (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng đầu chú ý cho mỗi lớp chú ý trong chú ý bộ nhớ.

memory_attention_downsample_rate (`int`, *tuỳ chọn*, mặc định là 1) : Tốc độ hạ mẫu cho các lớp chú ý.

memory_attention_feed_forward_hidden_size (`int`, *tuỳ chọn*, mặc định là 2048) : Kích thước của mạng feedforward trong module chú ý bộ nhớ.

memory_attention_feed_forward_hidden_act (`str`, *tùy chọn*, mặc định là `"relu"`) : Hàm kích hoạt phi tuyến tính trong mạng feedforward của module chú ý bộ nhớ.

memory_attention_dropout (`float`, *tuỳ chọn*, mặc định là 0.1) : Tỷ lệ dropout cho module chú ý bộ nhớ.

memory_attention_rope_feat_sizes (`list[int]`, *tùy chọn*, mặc định là `[72, 72]`) : Kích thước đặc trưng cho mã hóa vị trí Rope.

memory_attention_rope_dropout (`float`, *optional*, mặc định là 0.1) : Tỷ lệ dropout cho mã hóa vị trí Rope.

memory_encoder_hidden_size (`int`, *optional*, mặc định là 256) : Độ chiều của các trạng thái ẩn của bộ mã hóa bộ nhớ.

memory_encoder_output_channels (`int`, *tuỳ chọn*, mặc định là 64) : Số lượng kênh đầu ra cho bộ mã hóa bộ nhớ.

rope_parameters (`dict`, *tùy chọn*) : Từ điển chứa các tham số cấu hình cho các embedding RoPE. Từ điển phải chứa một giá trị cho `rope_theta` và tùy chọn các tham số được sử dụng để mở rộng trong trường hợp bạn muốn sử dụng RoPE với `max_position_embeddings` dài hơn.

mask_downsampler_embed_dim (`int`, *optional*, mặc định là 256) : Kích thước của embedding bộ giảm mẫu mask.

mask_downsampler_kernel_size (`int`, *tuỳ chọn*, mặc định là 3) : Kích thước kernel cho bộ giảm mẫu mask.

mask_downsampler_stride (`int`, *tuỳ chọn*, mặc định là 2) : Bước nhảy (stride) cho bộ giảm mẫu (downsampler) của mặt nạ (mask).

mask_downsampler_padding (`int`, *tuỳ chọn*, mặc định là 1) : Lề đệm cho bộ giảm mẫu mặt nạ.

mask_downsampler_total_stride (`int`, *optional*, mặc định là 16) : Tổng bước nhảy (stride) cho bộ giảm kích thước (downsampler) của mặt nạ (mask).

mask_downsampler_hidden_act (`str`, *tùy chọn*, mặc định là `"gelu"`) : Hàm kích hoạt phi tuyến tính trong bộ giảm mẫu mặt nạ.

memory_fuser_num_layers (`int`, *tuỳ chọn*, mặc định là 2) : Số lượng lớp trong bộ hợp nhất bộ nhớ.

memory_fuser_embed_dim (`int`, *tuỳ chọn*, mặc định là 256) : Kích thước của lớp nhúng trong bộ hợp nhất bộ nhớ.

memory_fuser_intermediate_dim (`int`, *optional*, mặc định là 1024) : Kích thước của lớp trung gian trong bộ hợp nhất bộ nhớ.

memory_fuser_kernel_size (`int`, *tuỳ chọn*, mặc định là 7) : Kích thước kernel cho bộ hợp nhất bộ nhớ.

memory_fuser_padding (`int`, *tuỳ chọn*, mặc định là 3) : Lề đệm cho bộ hợp nhất bộ nhớ.

memory_fuser_layer_scale_init_value (`float`, *optional*, mặc định là 1e-06) : Giá trị ban đầu cho layer scale trong memory fuser.

memory_fuser_hidden_act (`str`, *tùy chọn*, mặc định là `"gelu"`) : Hàm kích hoạt phi tuyến tính trong bộ hợp nhất bộ nhớ.

Đây là lớp cấu hình để lưu trữ cấu hình của một Sam3TrackerVideoModel. Nó được sử dụng để khởi tạo một mô hình Sam3 Tracker Video theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [facebook/sam3](https://huggingface.co/facebook/sam3)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

```python
>>> from transformers import (
...     Sam3VisionConfig,
...     Sam3TrackerVideoPromptEncoderConfig,
...     Sam3TrackerVideoMaskDecoderConfig,
...     Sam3TrackerVideoModel,
... )

>>> # Initializing a Sam3TrackerVideoConfig with `"facebook/sam3"` style configuration
>>> configuration = Sam3TrackerVideoConfig()

>>> # Initializing a Sam3TrackerVideoModel (with random weights) from the `"facebook/sam3"` style configuration
>>> model = Sam3TrackerVideoModel(configuration)

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

>>> # We can also initialize a Sam3TrackerVideoConfig from a Sam3TrackerVideoVisionConfig, Sam3TrackerVideoPromptEncoderConfig, and Sam3TrackerVideoMaskDecoderConfig

>>> # Initializing SAM3 tracker video vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVideoVisionConfig()
>>> prompt_encoder_config = Sam3TrackerVideoPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerVideoMaskDecoderConfig()

>>> config = Sam3TrackerVideoConfig(vision_config, prompt_encoder_config, mask_decoder_config)
```

## Sam3TrackerVideoMaskDecoderConfig[[transformers.Sam3TrackerVideoMaskDecoderConfig]]

#### transformers.Sam3TrackerVideoMaskDecoderConfig[[transformers.Sam3TrackerVideoMaskDecoderConfig]]

```python
transformers.Sam3TrackerVideoMaskDecoderConfig(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, hidden_size: int = 256, hidden_act: str = 'gelu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, dynamic_multimask_via_stability: bool = True, dynamic_multimask_stability_delta: float = 0.05, dynamic_multimask_stability_thresh: float = 0.98)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/configuration_sam3_tracker_video.py#L60)

**Tham số:**

hidden_size (`int`, *tuỳ chọn*, mặc định là `256`) : Kích thước của các biểu diễn ẩn.

hidden_act (`str`, *tùy chọn*, mặc định là `gelu`) : Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, `"gelu"`, `"relu"`, `"silu"`, v.v.

mlp_dim (`int`, *tuỳ chọn*, mặc định là 2048) : Kích thước của MLP trong transformer hai chiều.

num_hidden_layers (`int`, *tuỳ chọn*, mặc định là `2`) : Số lượng lớp ẩn trong bộ giải mã Transformer.

num_attention_heads (`int`, *tuỳ chọn*, mặc định là `8`) : Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ giải mã Transformer.

attention_downsample_rate (`int`, *tuỳ chọn*, mặc định là 2) : Tốc độ hạ mẫu cho các lớp attention.

num_multimask_outputs (`int`, *tuỳ chọn*, mặc định là 3) : Số lượng đầu ra multimask.

iou_head_depth (`int`, *tuỳ chọn*, mặc định là 3) : Độ sâu của đầu IoU.

iou_head_hidden_dim (`int`, *optional*, mặc định là 256) : Kích thước chiều ẩn của đầu IoU.

dynamic_multimask_via_stability (`bool`, *tùy chọn*, mặc định là `True`) : Có sử dụng dynamic multimask thông qua stability hay không.

dynamic_multimask_stability_delta (`float`, *tuỳ chọn*, mặc định là 0.05) : Độ lệch ổn định cho dynamic multimask.

dynamic_multimask_stability_thresh (`float`, *optional*, mặc định là 0.98) : Ngưỡng ổn định cho dynamic multimask.

Đây là lớp cấu hình để lưu trữ cấu hình của một Sam3TrackerVideoModel. Nó được sử dụng để khởi tạo một mô hình Sam3 Tracker Video theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [facebook/sam3](https://huggingface.co/facebook/sam3)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

## Sam3TrackerVideoPromptEncoderConfig[[transformers.Sam3TrackerVideoPromptEncoderConfig]]

#### transformers.Sam3TrackerVideoPromptEncoderConfig[[transformers.Sam3TrackerVideoPromptEncoderConfig]]

```python
transformers.Sam3TrackerVideoPromptEncoderConfig(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, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1008, patch_size: int | list[int] | tuple[int, int] = 14, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, scale: int = 1)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/configuration_sam3_tracker_video.py#L34)

**Tham số:**

hidden_size (`int`, *tuỳ chọn*, mặc định là `256`) : Kích thước của các biểu diễn ẩn.

image_size (`Union[int, list[int], tuple[int, int]]`, *tùy chọn*, mặc định là `1008`) : Kích thước (độ phân giải) của mỗi hình ảnh.

patch_size (`Union[int, list[int], tuple[int, int]]`, *tùy chọn*, mặc định là `14`) : Kích thước (độ phân giải) của mỗi patch.

mask_input_channels (`int`, *tuỳ chọn*, mặc định là 16) : Số lượng kênh được đưa vào module `MaskDecoder`.

num_point_embeddings (`int`, *tuỳ chọn*, mặc định là 4) : Số lượng point embeddings sẽ được sử dụng.

hidden_act (`str`, *tùy chọn*, mặc định là `gelu`) : Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, `"gelu"`, `"relu"`, `"silu"`, v.v.

layer_norm_eps (`float`, *tuỳ chọn*, mặc định là `1e-06`) : Epsilon được sử dụng bởi các lớp chuẩn hóa lớp (layer normalization).

scale (`float`, *tuỳ chọn*, mặc định là 1) : Hệ số tỷ lệ cho bộ mã hóa prompt.

Đây là lớp cấu hình để lưu trữ cấu hình của một Sam3TrackerVideoModel. Nó được sử dụng để khởi tạo một mô hình Sam3 Tracker Video theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [facebook/sam3](https://huggingface.co/facebook/sam3)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

## Sam3TrackerVideoProcessor[[transformers.Sam3TrackerVideoProcessor]]

#### transformers.Sam3TrackerVideoProcessor[[transformers.Sam3TrackerVideoProcessor]]

```python
transformers.Sam3TrackerVideoProcessor(image_processor, video_processor, target_size: int | None = None, point_pad_value: int = -10, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L39)

**Tham số:**

image_processor (`Sam3ImageProcessor`) : Bộ xử lý ảnh là một đầu vào bắt buộc.

video_processor (`video_processor_class`) : Bộ xử lý video là một đầu vào bắt buộc.

target_size (`int`, *optional*) : Kích thước đích (tính bằng pixel) để chuẩn hóa các điểm đầu vào và hộp bao. Nếu không được cung cấp, mặc định sẽ dùng cấu hình kích thước của bộ xử lý ảnh. Tất cả các tọa độ đầu vào (điểm và hộp) sẽ được chuẩn hóa theo kích thước này trước khi được truyền vào mô hình. Điều này đảm bảo biểu diễn tọa độ nhất quán bất kể kích thước gốc của ảnh.

point_pad_value (`int`, *optional*, mặc định là -10) : Giá trị được dùng để đệm (padding) các điểm đầu vào khi xử lý các chuỗi có độ dài khác nhau theo lô (batching). Giá trị này được dùng để đánh dấu các vị trí đã đệm và được giữ nguyên trong quá trình chuẩn hóa tọa độ.

Tạo một Sam3TrackerVideoProcessor, đóng gói một bộ xử lý ảnh và một bộ xử lý video thành một bộ xử lý duy nhất.

[Sam3TrackerVideoProcessor](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoProcessor) cung cấp đầy đủ các chức năng của [Sam3ImageProcessor](/docs/transformers/main/vi/model_doc/sam3#transformers.Sam3ImageProcessor) và `video_processor_class`. Xem [~Sam3ImageProcessor](/docs/transformers/main/vi/model_doc/sam3#transformers.Sam3ImageProcessor) và `~video_processor_class` để biết thêm thông tin.

#### __call__[[transformers.Sam3TrackerVideoProcessor.__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, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], 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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L57)

**Tham số:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *tùy chọn*) : Ảnh cần tiền xử lý. Kỳ vọng một ảnh đơn hoặc một lô ảnh với giá trị pixel dao động từ 0 đến 255. Nếu truyền vào các ảnh có giá trị pixel nằm trong khoảng từ 0 đến 1, hãy đặt `do_rescale=False`.

segmentation_maps (`ImageInput`, *tùy chọn*) : Các bản đồ phân đoạn cần xử lý.

input_points (`list[list[list[list[float]]]]`, `torch.Tensor`, *tùy chọn*) : Các điểm cần thêm vào khung.

input_labels (`list[list[list[int]]]`, `torch.Tensor`, *tùy chọn*) : Nhãn cho các điểm.

input_boxes (`list[list[list[float]]]`, `torch.Tensor`, *tùy chọn*) : Các hộp bao (bounding boxes) cần thêm vào khung hình.

original_sizes (`list[list[float]]`, `torch.Tensor`, *tùy chọn*) : Kích thước gốc của các hình ảnh.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *tùy chọn*) : Nếu được đặt, sẽ trả về các tensor của một framework cụ thể. Các giá trị chấp nhận được là:  - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của NumPy.

**Trả về:** Một [BatchEncoding](/docs/transformers/main/vi/main_classes/tokenizer#transformers.BatchEncoding) với các trường sau

- `pixel_values` (`torch.Tensor`): Ảnh đã được xử lý.
- `original_sizes` (`list[list[float]]`): Kích thước gốc của các hình ảnh.
- `labels` (`torch.Tensor`): Các bản đồ phân đoạn đã được xử lý (nếu được cung cấp).
- `input_points` (`torch.Tensor`): Các điểm đã được xử lý.
- `input_labels` (`torch.Tensor`): Nhãn đã được xử lý.
- `input_boxes` (`torch.Tensor`): Các hộp bao đã được xử lý.

#### post_process_masks[[transformers.Sam3TrackerVideoProcessor.post_process_masks]]

```python
post_process_masks(masks, original_sizes, mask_threshold = 0.0, binarize = True, max_hole_area = 0.0, max_sprinkle_area = 0.0, apply_non_overlapping_constraints = False, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L463)

**Tham số:**

masks (`Union[List[torch.Tensor], List[np.ndarray]]`) : Các mask dạng batch từ mask_decoder ở định dạng (batch_size, num_channels, height, width).

original_sizes (`Union[torch.Tensor, List[Tuple[int,int]]]`) : Kích thước gốc của từng ảnh trước khi được điều chỉnh kích thước thành hình dạng đầu vào mong đợi của mô hình, theo định dạng (chiều cao, chiều rộng).

mask_threshold (`float`, *tuỳ chọn*, mặc định là 0.0) : Ngưỡng cho các thao tác nhị phân hóa và xử lý hậu kỳ.

binarize (`bool`, *tùy chọn*, mặc định là `True`) : Xác định có nhị phân hóa các mặt nạ hay không.

max_hole_area (`float`, *tuỳ chọn*, mặc định là 0.0) : Diện tích tối đa của một lỗ cần lấp đầy.

max_sprinkle_area (`float`, *tuỳ chọn*, mặc định là 0.0) : Diện tích tối đa của một vệt rắc để lấp đầy.

apply_non_overlapping_constraints (`bool`, *tùy chọn*, mặc định là `False`) : Có áp dụng các ràng buộc không chồng chéo lên các mặt nạ hay không.

**Trả về:** (`torch.Tensor`)

Mặt nạ dạng batch có định dạng batch_size, num_channels, height, width, trong đó (height, width) được xác định bởi original_size.

Loại bỏ padding và phóng to các mask lên kích thước ảnh gốc.

#### init_video_session[[transformers.Sam3TrackerVideoProcessor.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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L514)

**Tham số:**

video (`VideoInput`, *tùy chọn*) : Video cần xử lý. Không cần cung cấp khi đang phát trực tiếp.

inference_device (`str` hoặc `torch.device`, *tuỳ chọn*, mặc định là "cpu") : Thiết bị được sử dụng cho suy luận.

inference_state_device (`str` hoặc `torch.device`, *tùy chọn*) : Thiết bị để lưu trữ trạng thái suy luận.

processing_device (`str` hoặc `torch.device`, *tùy chọn*) : Thiết bị được sử dụng để xử lý video.

video_storage_device (`str` hoặc `torch.device`, *tùy chọn*) : Thiết bị để lưu các khung video đã xử lý.

max_vision_features_cache_size (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng tối đa các đặc trưng thị giác để lưu vào bộ nhớ đệm.

dtype (`torch.dtype`, *tùy chọn*, mặc định là `torch.float32`) : torch dtype được sử dụng cho toàn bộ phiên.

Khởi tạo phiên video cho suy luận. Nếu một video được cung cấp (suy luận bất đồng bộ), video sẽ được xử lý và lưu trữ trên `video_storage_device`.

#### add_inputs_to_inference_session[[transformers.Sam3TrackerVideoProcessor.add_inputs_to_inference_session]]

```python
add_inputs_to_inference_session(inference_session: Sam3TrackerVideoInferenceSession, frame_idx: int, obj_ids: list[int] | int, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = None, input_masks: typing.Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], NoneType] = None, original_size: tuple[int, int] | None = None, clear_old_inputs: bool = True)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L567)

**Tham số:**

inference_session (`Sam3TrackerVideoInferenceSession`) : Phiên suy luận cho video.

frame_idx (`int`) : Chỉ số của khung hình cần xử lý.

obj_ids (`list[int]` hoặc `int`) : ID đối tượng cần liên kết với các điểm hoặc hộp. Đây có thể là bất kỳ số nguyên nào và có thể được sử dụng lại sau đó để chỉ định một đối tượng.

input_points (`list[list[list[list[float]]]]`, `torch.Tensor`, *tùy chọn*) : Các điểm cần thêm vào khung.

input_labels (`list[list[list[int]]]`, `torch.Tensor`, *tùy chọn*) : Nhãn cho các điểm.

input_boxes (`list[list[list[float]]]`, `torch.Tensor`, *tùy chọn*) : Các hộp bao (bounding boxes) cần thêm vào khung hình.

input_masks (`np.ndarray`, `torch.Tensor`, `list[np.ndarray]`, hoặc `list[torch.Tensor]`, *tùy chọn*) : Mặt nạ (mask) cần thêm vào khung hình.

original_size (`tuple[int, int]`, *tùy chọn*) : Kích thước gốc của video. Cung cấp khi phát trực tiếp.

clear_old_inputs (`bool`, *tùy chọn*, mặc định là `True`) : Xác định có xóa các đầu vào cũ cho đối tượng hay không.

Xử lý các điểm, hộp hoặc mặt nạ mới cho một khung hình video và thêm chúng vào phiên suy luận.

## Sam3TrackerVideoInferenceSession[[transformers.Sam3TrackerVideoInferenceSession]]

#### transformers.Sam3TrackerVideoInferenceSession[[transformers.Sam3TrackerVideoInferenceSession]]

```python
transformers.Sam3TrackerVideoInferenceSession(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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L109)

**Tham số:**

video (`torch.Tensor`, *tùy chọn*) : Video cần xử lý. Không cần cung cấp khi đang phát trực tiếp.

video_height (`int`, *tuỳ chọn*) : Chiều cao của video.

video_width (`int`, *tuỳ chọn*) : Độ rộng của video.

inference_device (`torch.device`, *tùy chọn*, mặc định là `"cpu"`) : Thiết bị được sử dụng cho suy luận.

inference_state_device (`torch.device`, *tùy chọn*, mặc định là `"cpu"`) : Thiết bị để lưu trữ trạng thái suy luận.

video_storage_device (`torch.device`, *tùy chọn*, mặc định là `"cpu"`) : Thiết bị để lưu trữ video.

dtype (`torch.dtype`, *tùy chọn*, mặc định là `"float32"`) : Kiểu dữ liệu (dtype) để sử dụng cho video.

max_vision_features_cache_size (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng tối đa các đặc trưng thị giác để lưu vào bộ nhớ đệm.

Quản lý các tham số, trạng thái và bộ nhớ đệm của phiên suy luận video.

#### add_mask_inputs[[transformers.Sam3TrackerVideoInferenceSession.add_mask_inputs]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L229)

Thêm đầu vào mask với việc đặt thiết bị tự động.

#### add_new_frame[[transformers.Sam3TrackerVideoInferenceSession.add_new_frame]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L304)

Thêm khung mới với việc đặt thiết bị tự động.

#### add_point_inputs[[transformers.Sam3TrackerVideoInferenceSession.add_point_inputs]]

```python
add_point_inputs(obj_idx: int, frame_idx: int, inputs: dict)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L215)

Thêm các đầu vào điểm với việc đặt thiết bị tự động.

#### get_frame[[transformers.Sam3TrackerVideoInferenceSession.get_frame]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L320)

Lấy khung từ video.

#### get_obj_num[[transformers.Sam3TrackerVideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L210)

Lấy tổng số lượng id đối tượng duy nhất đã nhận được cho đến nay trong phiên này.

#### get_output[[transformers.Sam3TrackerVideoInferenceSession.get_output]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L277)

**Tham số:**

obj_idx (int) : Chỉ số của đối tượng.

frame_idx (int) : Chỉ số của khung hình.

output_key (str) : Khóa của đầu ra.

is_conditioning_frame (bool) : Xác định xem đầu ra có phải cho một khung điều kiện hay không.

Lấy kết quả với quản lý thiết bị thông minh.

#### obj_id_to_idx[[transformers.Sam3TrackerVideoInferenceSession.obj_id_to_idx]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L184)

Ánh xạ ID đối tượng tới chỉ số, tạo mục mới nếu cần.

#### obj_idx_to_id[[transformers.Sam3TrackerVideoInferenceSession.obj_idx_to_id]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L206)

Ánh xạ chỉ mục đối tượng phía mô hình sang id đối tượng phía client.

#### remove_mask_inputs[[transformers.Sam3TrackerVideoInferenceSession.remove_mask_inputs]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L235)

Xóa các đầu vào mask.

#### remove_point_inputs[[transformers.Sam3TrackerVideoInferenceSession.remove_point_inputs]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L225)

Xóa các đầu vào điểm.

#### reset_inference_session[[transformers.Sam3TrackerVideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L336)

Đặt lại dữ liệu theo dõi và bộ nhớ đệm.

#### reset_tracking_data[[transformers.Sam3TrackerVideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L324)

Đặt lại dữ liệu theo dõi nhưng giữ lại bộ nhớ đệm.

#### store_output[[transformers.Sam3TrackerVideoInferenceSession.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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L240)

**Tham số:**

obj_idx (int) : Chỉ số của đối tượng.

frame_idx (int) : Chỉ số của khung hình.

output_key (Optional[str]) : Khóa của đầu ra. Nếu là None, đầu ra sẽ được lưu dưới dạng từ điển.

output_value (Optional[Union[torch.Tensor, dict]]) : Giá trị của đầu ra.

is_conditioning_frame (bool) : Xác định xem đầu ra có phải cho một khung điều kiện hay không.

Lưu trữ đầu ra với quản lý thiết bị thông minh. Nếu output_key là None, đầu ra sẽ được lưu trữ dưới dạng từ điển.

## Sam3TrackerVideoModel[[transformers.Sam3TrackerVideoModel]]

#### transformers.Sam3TrackerVideoModel[[transformers.Sam3TrackerVideoModel]]

```python
transformers.Sam3TrackerVideoModel(config: Sam3TrackerVideoConfig, remove_vision_encoder: bool = False)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L1647)

**Tham số:**

config ([Sam3TrackerVideoConfig](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

remove_vision_encoder (`bool`, *tùy chọn*, mặc định là `False`) : Có nên loại bỏ bộ mã hóa thị giác hay không. Nếu là True, bộ mã hóa thị giác sẽ được đặt thành None.

Mô hình Sam3 Tracker Video thô, xuất ra các hidden-states thô mà không có bất kỳ head cụ thể nào ở phía trên.

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

#### forward[[transformers.Sam3TrackerVideoModel.forward]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L1789)

**Tham số:**

inference_session (`~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession`) : Đối tượng phiên suy luận video.

frame_idx (`int`, *optional*) : Chỉ số của khung hình mà bạn muốn chạy suy luận. Không cần cung cấp khi suy luận trên một khung hình mới được phát trực tiếp.

frame (`torch.Tensor`, *tùy chọn*) : Khung cần xử lý. Cung cấp khi đang phát trực tiếp.

reverse (`bool`, *tùy chọn*, mặc định là `False`) : Có lan truyền theo chiều ngược lại hay không.

run_mem_encoder (`bool`, *tuỳ chọn*, mặc định là `True`) : Có chạy bộ mã hóa bộ nhớ trên các mặt nạ dự đoán hay không. Bộ mã hóa bộ nhớ được xử lý theo lô trên tất cả các đối tượng để tối ưu hiệu suất.

**Trả về:** `Sam3TrackerVideoSegmentationOutput` hoặc `tuple(torch.Tensor)`

Một `Sam3TrackerVideoSegmentationOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình ([Sam3TrackerVideoConfig](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) và đầu vào.

Truyền các đối tượng qua một khung video được phát trực tiếp.

- **object_ids** (`list[int]`, *tùy chọn*) -- Danh sách các ID đối tượng đang được theo dõi trong khung hình hiện tại.
- **pred_masks** (`torch.Tensor` có hình dạng `(batch_size, num_masks, height, width)`) -- Các mặt nạ dự đoán được lưu ở độ phân giải của mô hình.
- **object_score_logits** (`torch.Tensor` có hình dạng `(batch_size,)`, *tùy chọn*) -- Logits cho điểm của các đối tượng, cho biết các đối tượng có hiện diện hay không.
- **frame_idx** (`int`, *tùy chọn*) -- Chỉ số khung của video.

#### propagate_in_video_iterator[[transformers.Sam3TrackerVideoModel.propagate_in_video_iterator]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L2812)

**Tham số:**

inference_session (`~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession`) : Đối tượng phiên suy luận video.

start_frame_idx (`int`, *optional*) : Chỉ số khung hình bắt đầu cho quá trình lan truyền. Cần được cung cấp nếu `forward` chưa được gọi trên các đầu vào mới. Nếu không được cung cấp, chỉ số khung hình bắt đầu sẽ là khung hình sớm nhất có các điểm đầu vào.

max_frame_num_to_track (`int`, *tùy chọn*) : Số khung hình tối đa cần theo dõi.

reverse (`bool`, *tùy chọn*, mặc định là `False`) : Có lan truyền theo chiều ngược lại hay không.

show_progress_bar (`bool`, *tùy chọn*, mặc định là `False`) : Có hiển thị thanh tiến trình trong quá trình lan truyền hay không.

**Trả về:** `Sam3TrackerVideoSegmentationOutput` hoặc `tuple(torch.Tensor)`

Một `Sam3TrackerVideoSegmentationOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình ([Sam3TrackerVideoConfig](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) và đầu vào.

Truyền các đối tượng qua các khung hình video. Được sử dụng khi khởi tạo phiên suy luận với một video hoàn chỉnh. Trả về Sam3TrackerVideoSegmentationOutput cho mỗi khung hình.

- **object_ids** (`list[int]`, *tùy chọn*) -- Danh sách các ID đối tượng đang được theo dõi trong khung hình hiện tại.
- **pred_masks** (`torch.Tensor` có hình dạng `(batch_size, num_masks, height, width)`) -- Các mặt nạ dự đoán được lưu ở độ phân giải của mô hình.
- **object_score_logits** (`torch.Tensor` có hình dạng `(batch_size,)`, *tùy chọn*) -- Logits cho điểm của các đối tượng, cho biết các đối tượng có hiện diện hay không.
- **frame_idx** (`int`, *tùy chọn*) -- Chỉ số khung của video.

#### get_image_features[[transformers.Sam3TrackerVideoModel.get_image_features]]

```python
get_image_features(pixel_values: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L1914)

**Tham số:**

pixel_values (`torch.Tensor`) : Giá trị pixel đầu vào có hình dạng `(batch_size, num_channels, height, width)`.

**Trả về:** `Sam3TrackerVideoVisionEncoderOutput` hoặc `tuple(torch.Tensor)`

Một `Sam3TrackerVideoVisionEncoderOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình ([Sam3TrackerVideoConfig](/docs/transformers/main/vi/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) và đầu vào.

- **last_hidden_state** (`torch.Tensor` có hình dạng `(batch_size, height, width, hidden_size)`) -- Chuỗi các hidden-state tại đầu ra của lớp cuối cùng của mô hình.
- **pooler_output** (`torch.Tensor` có hình dạng `(batch_size, hidden_size)`) -- Trạng thái ẩn của lớp cuối cùng cho token đầu tiên của chuỗi (token phân loại) sau khi được xử lý thêm thông qua các lớp dùng cho tác vụ tiền huấn luyện bổ trợ. Ví dụ, đối với các mô hình thuộc họ BERT, giá trị này trả về token phân loại sau khi được xử lý qua một lớp tuyến tính và một hàm kích hoạt tanh. Trọng số của lớp tuyến tính được huấn luyện từ mục tiêu dự đoán câu tiếp theo (phân loại) trong quá trình tiền huấn luyện.
- **hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple của `torch.Tensor` (một cho đầu ra của các embedding, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của mô hình tại đầu ra của mỗi lớp cùng với các đầu ra embedding ban đầu tùy chọn.
- **attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý sau softmax của attention, được sử dụng để tính trung bình có trọng số trong các đầu self-attention.
- **fpn_hidden_states** (`tuple(torch.Tensor)`) -- Tuple của `torch.Tensor` (một tensor cho mỗi mức đặc trưng, từ độ phân giải cao xuống thấp) có hình dạng `(batch_size, hidden_size, height, width)`. Các bản đồ đặc trưng từ phần neck của Feature Pyramid Network.
- **fpn_position_encoding** (`tuple(torch.Tensor)`) -- Tuple của `torch.Tensor` (một cho mỗi mức đặc trưng, từ độ phân giải cao xuống thấp) có hình dạng `(batch_size, hidden_size, height, width)`. Các mã hóa vị trí tương ứng với `fpn_hidden_states`.