# SAM3-LiteText ## 概述 SAM3-LiteText 由 Chengxi Zeng、Yuxuan Jiang、Ge Gao、Shuai Wang、Duolikun Danier、Bin Zhu、Stevan Rudinac、David Bull 和 Fan Zhang 在 [SAM3-LiteText: An Anatomical Study of the SAM3 Text Encoder for Efficient Vision-Language Segmentation](https://huggingface.co/papers/2602.12173) 中提出。 SAM3-LiteText 是 [SAM3](sam3) 的轻量级变体，它用基于 MobileCLIP 的紧凑文本编码器替换了原模型中庞大的 SAM3 文本编码器（353M 参数），该编码器通过知识蒸馏进行了优化。SAM3 的 ViT-H 图像编码器保持不变。这一改动将文本编码器的参数量减少了最多 88%，同时保持了与原始模型相当的分割性能。 该论文的摘要如下： *诸如 SAM3 的视觉-语言分割模型支持灵活、基于提示的视觉定位，但它们继承了原本为开放式语言理解而设计的大型通用文本编码器。在实际应用中，分割提示通常简短、结构化且语义受限，这导致文本编码器的容量存在严重的过度配置，并带来持续的算力与内存开销。本文对视觉-语言分割中的文本提示进行了大规模解剖式分析，涵盖多个基准测试中的 404,796 个真实提示。分析揭示了严重的冗余性：大多数上下文窗口未被充分利用，词汇使用高度稀疏，且尽管表示维度很高，文本嵌入仍位于低维流形上。基于这些发现，我们提出了 SAM3-LiteText，一个轻量级文本编码框架，它使用通过知识蒸馏优化的紧凑 MobileCLIP 学生模型来替换原始 SAM3 的文本编码器。在图像和视频分割基准上的大量实验表明，SAM3-LiteText 将文本编码器的参数量减少了最多 88%，显著降低了静态内存占用，同时保持了与原始模型相当的分割性能。* 文本编码器架构基于 [MobileCLIP](https://huggingface.co/papers/2311.17049)，共有三种变体： | 变体 | 文本编码器 | 文本参数 | 归约 | |---|---|---|---| | SAM3-LiteText-S0-16 | MobileCLIP-S0 | 42.54M | ~88% | | SAM3-LiteText-S1-16 | MobileCLIP-S1 | 63.53M | ~82% | | SAM3-LiteText-L-16 | MobileCLIP2-L | 123.80M | ~65% | 该模型由 [nielsr](https://huggingface.co/nielsr) 和 [yonigozlan](https://huggingface.co/yonigozlan) 贡献。原始代码可在[此处](https://github.com/SimonZeng7108/efficientsam3/tree/sam3_litetext)找到。 ## 用法 SAM3-LiteText 是 SAM3 的即插即用替代方案，采用轻量级文本编码器。它使用相同的处理器（[Sam3Processor](/docs/transformers/main/zh/model_doc/sam3#transformers.Sam3Processor)），并支持相同的提示接口。有关详细的使用示例（包括文本提示、框提示、批量推理等），请参阅 [SAM3 文档](sam3)。 ```python from io import BytesIO from huggingface_hub.utils import httpx from PIL import Image from transformers import AutoModel, AutoProcessor model = AutoModel.from_pretrained("yonigozlan/sam3-litetext-s0", device_map="auto") processor = AutoProcessor.from_pretrained("yonigozlan/sam3-litetext-s0") image_url = "http://images.cocodataset.org/val2017/000000077595.jpg" image = Image.open(BytesIO(httpx.get(image_url).content)).convert("RGB") inputs = processor(images=image, text="ear", return_tensors="pt").to(model.device) outputs = model(**inputs) results = processor.post_process_instance_segmentation( outputs, threshold=0.5, mask_threshold=0.5, target_sizes=inputs.get("original_sizes").tolist(), )[0] print(f"Found {len(results['masks'])} objects") ``` ## Sam3LiteTextConfig[[transformers.Sam3LiteTextConfig]] #### transformers.Sam3LiteTextConfig[[transformers.Sam3LiteTextConfig]] ```python transformers.Sam3LiteTextConfig(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, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, geometry_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, detr_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, detr_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/configuration_sam3_lite_text.py#L145) **参数：** vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：视觉骨干网络的配置对象或字典。 text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：文本骨干网络的配置对象或字典。 geometry_encoder_config (`dict` 或 `Sam3LiteTextGeometryEncoderConfig`，*可选*)：几何编码器的配置。 detr_encoder_config (`dict` 或 `Sam3LiteTextDETREncoderConfig`，*可选*)：DETR 编码器的配置。 detr_decoder_config (`dict` 或 `Sam3LiteTextDETRDecoderConfig`，*可选*)：DETR 解码器的配置。 mask_decoder_config (`dict` 或 `Sam3LiteTextMaskDecoderConfig`，*可选*)：掩码解码器的配置。 initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 这是用于存储 Sam3LiteTextModel 配置的类。它根据指定的参数实例化 Sam3 Lite Text 模型，并定义模型架构。使用默认值实例化配置将生成与 [yonigozlan/sam3-litetext-s0](https://huggingface.co/yonigozlan/sam3-litetext-s0) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 示例： ```python >>> from transformers import Sam3LiteTextConfig, Sam3LiteTextModel >>> # Initializing a SAM3_LITE_TEXT configuration >>> configuration = Sam3LiteTextConfig() >>> # Initializing a model from the configuration >>> model = Sam3LiteTextModel(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## Sam3LiteTextTextConfig[[transformers.Sam3LiteTextTextConfig]] #### transformers.Sam3LiteTextTextConfig[[transformers.Sam3LiteTextTextConfig]] ```python transformers.Sam3LiteTextTextConfig(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, vocab_size: int = 49408, hidden_size: int = 512, intermediate_size: int = 2048, projection_dim: int = 512, num_hidden_layers: int = 12, num_attention_heads: int = 8, max_position_embeddings: int = 77, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-05, attention_dropout: float = 0.0, use_repmixer_blocks: bool = True, layer_scale_init_value: float = 1e-05, repmixer_kernel_size: int = 11) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/configuration_sam3_lite_text.py#L115) **参数：** vocab_size (`int`，*可选*，默认值为 `49408`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。 hidden_size (`int`，*可选*，默认为 `512`)：隐藏表示的维度。 intermediate_size (`int`，*可选*，默认为 `2048`)：MLP 表示的维度。 projection_dim (`int`，*可选*，默认值为 `512`)：文本和视觉投影层的维度。 num_hidden_layers (`int`，*可选*，默认为 `12`)：Transformer 解码器中的隐藏层数。 num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。 max_position_embeddings (`int`，*可选*，默认值为 `77`)：该模型可能使用的最大序列长度。 hidden_act (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。 attention_dropout (`float`, *可选*, 默认为 `0.0`) : 注意力概率的 dropout 比率。 use_repmixer_blocks (`bool`, *可选*, 默认为 `True`) : 是否对第一个和最后一个编码器层使用 RepMixer 块（MobileCLIP 风格）。当 `False` 时，所有层均为标准的 Transformer 编码器层。 layer_scale_init_value (`float`, *可选*，默认为 `1e-5`)：RepMixer 块（残差分支）中可学习 layer-scale 参数的初始值。 repmixer_kernel_size (`int`, *可选*，默认为 `11`)：RepMixer 块中深度卷积的核大小（token mixer 和卷积前馈路径）。 这是用于存储 Sam3LiteTextModel 配置的类。它根据指定的参数实例化 Sam3 Lite Text 模型，并定义模型架构。使用默认值实例化配置将生成与 [yonigozlan/sam3-litetext-s0](https://huggingface.co/yonigozlan/sam3-litetext-s0) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ## Sam3LiteTextGeometryEncoderConfig[[transformers.Sam3LiteTextGeometryEncoderConfig]] #### transformers.Sam3LiteTextGeometryEncoderConfig[[transformers.Sam3LiteTextGeometryEncoderConfig]] ```python transformers.Sam3LiteTextGeometryEncoderConfig(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, num_layers: int = 3, num_attention_heads: int = 8, intermediate_size: int = 2048, dropout: float | int = 0.1, hidden_act: str = 'relu', hidden_dropout: float | int = 0.0, layer_norm_eps: float = 1e-06, roi_size: int = 7, initializer_range: float = 0.02) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/configuration_sam3_lite_text.py#L30) **参数：** hidden_size (`int`，*可选*，默认为 `256`)：隐藏表示的维度。 num_layers (`int`，*可选*，默认为 `3`)：Transformer 解码器中的隐藏层数。 num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。 intermediate_size (`int`，*可选*，默认为 `2048`)：MLP 表示的维度。 dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。 hidden_act (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 hidden_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：嵌入层、编码器和池化器中所有全连接层的 dropout 概率。 layer_norm_eps (`float`, *可选*, 默认为 `1e-06`) : 层归一化层使用的 epsilon。 roi_size (`int`，*可选*，默认为 7)：用于框池化操作的 ROI 大小。 initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 这是用于存储 Sam3LiteTextModel 配置的类。它根据指定的参数实例化 Sam3 Lite Text 模型，并定义模型架构。使用默认值实例化配置将生成与 [yonigozlan/sam3-litetext-s0](https://huggingface.co/yonigozlan/sam3-litetext-s0) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ## Sam3LiteTextDETREncoderConfig[[transformers.Sam3LiteTextDETREncoderConfig]] #### transformers.Sam3LiteTextDETREncoderConfig[[transformers.Sam3LiteTextDETREncoderConfig]] ```python transformers.Sam3LiteTextDETREncoderConfig(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, num_layers: int = 6, num_attention_heads: int = 8, intermediate_size: int = 2048, dropout: float | int = 0.1, hidden_act: str = 'relu', hidden_dropout: float | int = 0.0, layer_norm_eps: float = 1e-06, initializer_range: float = 0.02) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/configuration_sam3_lite_text.py#L52) **参数：** hidden_size (`int`，*可选*，默认为 `256`)：隐藏表示的维度。 num_layers (`int`，*可选*，默认为 `6`)：Transformer 解码器中的隐藏层数。 num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。 intermediate_size (`int`，*可选*，默认为 `2048`)：MLP 表示的维度。 dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。 hidden_act (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 hidden_dropout (`float`, *可选*, 默认值为 0.0) : 隐藏状态的 Dropout 概率。 layer_norm_eps (`float`, *可选*, 默认为 `1e-06`) : 层归一化层使用的 epsilon。 initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 这是用于存储 Sam3LiteTextModel 配置的类。它根据指定的参数实例化 Sam3 Lite Text 模型，并定义模型架构。使用默认值实例化配置将生成与 [yonigozlan/sam3-litetext-s0](https://huggingface.co/yonigozlan/sam3-litetext-s0) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ## Sam3LiteTextDETRDecoderConfig[[transformers.Sam3LiteTextDETRDecoderConfig]] #### transformers.Sam3LiteTextDETRDecoderConfig[[transformers.Sam3LiteTextDETRDecoderConfig]] ```python transformers.Sam3LiteTextDETRDecoderConfig(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, num_layers: int = 6, num_queries: int = 200, num_attention_heads: int = 8, intermediate_size: int = 2048, dropout: float | int = 0.1, hidden_act: str = 'relu', hidden_dropout: float | int = 0.0, layer_norm_eps: float = 1e-06, initializer_range: float = 0.02) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/configuration_sam3_lite_text.py#L74) **参数：** hidden_size (`int`，*可选*，默认为 `256`)：隐藏表示的维度。 num_layers (`int`，*可选*，默认为 `6`)：Transformer 解码器中的隐藏层数。 num_queries (`int`，*可选*，默认为 200)：对象查询的数量。 num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。 intermediate_size (`int`，*可选*，默认为 `2048`)：MLP 表示的维度。 dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。 hidden_act (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 hidden_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：嵌入层、编码器和池化器中所有全连接层的 dropout 概率。 layer_norm_eps (`float`, *可选*, 默认为 `1e-06`) : 层归一化层使用的 epsilon。 initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 这是用于存储 Sam3LiteTextModel 配置的类。它根据指定的参数实例化 Sam3 Lite Text 模型，并定义模型架构。使用默认值实例化配置将生成与 [yonigozlan/sam3-litetext-s0](https://huggingface.co/yonigozlan/sam3-litetext-s0) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ## Sam3LiteTextMaskDecoderConfig[[transformers.Sam3LiteTextMaskDecoderConfig]] #### transformers.Sam3LiteTextMaskDecoderConfig[[transformers.Sam3LiteTextMaskDecoderConfig]] ```python transformers.Sam3LiteTextMaskDecoderConfig(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, num_upsampling_stages: int = 3, layer_norm_eps: float = 1e-06, dropout: float | int = 0.0, num_attention_heads: int = 8, initializer_range: float = 0.02) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/configuration_sam3_lite_text.py#L97) **参数：** hidden_size (`int`，*可选*，默认为 `256`)：隐藏表示的维度。 num_upsampling_stages (`int`, *可选*，默认为 3)：像素解码器（FPN）中的上采样阶段数。 layer_norm_eps (`float`, *可选*, 默认为 `1e-06`) : 层归一化层使用的 epsilon。 dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：所有 dropout 层的比率。 num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。 initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 这是用于存储 Sam3LiteTextModel 配置的类。它根据指定的参数实例化 Sam3 Lite Text 模型，并定义模型架构。使用默认值实例化配置将生成与 [yonigozlan/sam3-litetext-s0](https://huggingface.co/yonigozlan/sam3-litetext-s0) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ## Sam3LiteTextTextModel[[transformers.Sam3LiteTextTextModel]] #### transformers.Sam3LiteTextTextModel[[transformers.Sam3LiteTextTextModel]] ```python transformers.Sam3LiteTextTextModel(config: Sam3LiteTextTextConfig) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/modeling_sam3_lite_text.py#L371) **参数：** config ([Sam3LiteTextTextConfig](/docs/transformers/main/zh/model_doc/sam3_lite_text#transformers.Sam3LiteTextTextConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 MobileCLIP MCT 文本编码器，用于 EfficientSAM3 LiteText。 当 `config.use_repmixer_blocks` 为 `True` 时，第一层和最后一层是 `Sam3LiteTextRepMixerBlock` 模块；其余层均为标准的 `Sam3LiteTextTextEncoderLayer` 层。 该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。 该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。 #### forward[[transformers.Sam3LiteTextTextModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/modeling_sam3_lite_text.py#L393) **参数：** input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) **返回：** `Sam3LiteTextTextEncoderOutput` 或 `tuple(torch.Tensor)` `Sam3LiteTextTextEncoderOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Sam3LiteTextConfig](/docs/transformers/main/zh/model_doc/sam3_lite_text#transformers.Sam3LiteTextConfig)）和输入。 [Sam3LiteTextTextModel](/docs/transformers/main/zh/model_doc/sam3_lite_text#transformers.Sam3LiteTextTextModel) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 来自文本编码器的完整隐藏状态序列。 - **pooler_output**（形状为 `(batch_size, projection_dim)` 的 `torch.Tensor`）-- 通过内部 CLIP 风格的投影映射到 `projection_dim` 的 EOT 池化输出。 - **hidden_states** (`tuple(torch.Tensor)`, *可选*) -- 各层隐藏状态的元组，当 `output_hidden_states=True` 时返回。 - **attentions** (`tuple(torch.Tensor)`，*可选*) -- 每个 Transformer 层的注意力权重元组，当 `output_attentions=True` 时返回。 ## Sam3LiteTextModel[[transformers.Sam3LiteTextModel]] #### transformers.Sam3LiteTextModel[[transformers.Sam3LiteTextModel]] ```python transformers.Sam3LiteTextModel(config: Sam3LiteTextConfig) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/modeling_sam3_lite_text.py#L1922) #### forward[[transformers.Sam3LiteTextModel.forward]] ```python forward(pixel_values: typing.Optional[torch.Tensor] = None, vision_embeds: transformers.models.sam3_lite_text.modeling_sam3_lite_text.Sam3LiteTextVisionEncoderOutput | None = None, input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, text_embeds: typing.Optional[torch.Tensor] = None, input_boxes: typing.Optional[torch.Tensor] = None, input_boxes_labels: typing.Optional[torch.LongTensor] = None, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/modeling_sam3_lite_text.py#L2038) **参数：** pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [Sam3ImageProcessor](/docs/transformers/main/zh/model_doc/sam3#transformers.Sam3ImageProcessor) 获取像素值。有关详细信息，请参阅 [Sam3ImageProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[Sam3Processor](/docs/transformers/main/zh/model_doc/sam3#transformers.Sam3Processor) 使用 [Sam3ImageProcessor](/docs/transformers/main/zh/model_doc/sam3#transformers.Sam3ImageProcessor) 处理图像）。 vision_embeds (`Sam3LiteTextVisionEncoderOutput`, *可选*) : 预计算的视觉嵌入。可用于轻松复用视觉嵌入。如果提供了该参数，则不应传入 `pixel_values`。与 `pixel_values` 互斥。 input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) text_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：预计算好的文本嵌入。可用于轻松复用文本嵌入。如果提供了该参数，则不应传入 `input_ids`。与 `input_ids` 互斥。 input_boxes (`torch.Tensor`，形状为 `(batch_size, num_boxes, 4)`，*可选*)：位于 [0, 1] 范围内的归一化框坐标，格式为 (cx, cy, w, h)。 input_boxes_labels (`torch.LongTensor`，形状为 `(batch_size, num_boxes)`，*可选*)：框的标签：1（正样本），0（负样本）。 **返回：** `Sam3LiteTextImageSegmentationOutput` 或 `tuple(torch.Tensor)` `Sam3LiteTextImageSegmentationOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Sam3LiteTextConfig](/docs/transformers/main/zh/model_doc/sam3_lite_text#transformers.Sam3LiteTextConfig)）和输入。 [Sam3LiteTextModel](/docs/transformers/main/zh/model_doc/sam3_lite_text#transformers.Sam3LiteTextModel) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **pred_masks**（形状为 `(batch_size, num_queries, height, width)` 的 `torch.Tensor`）-- 每个查询的预测分割掩码。 - **pred_boxes**（形状为 `(batch_size, num_queries, 4)` 的 `torch.Tensor`）-- 以 (x1, y1, x2, y2) 格式表示的预测边界框。 - **pred_logits** (`torch.Tensor`，形状为 `(batch_size, num_queries)`，*可选*) -- 每个查询的分类置信度分数，通过解码器查询特征与文本特征之间的点积计算得出。 - **presence_logits** (`torch.Tensor`，形状为 `(batch_size, 1)`，*可选*) -- 来自 DETR 解码器 presence token 的存在性 logits（仅最后一层）。这些 logits 指示场景中是否存在物体。可与 pred_logits 相乘来计算最终分数：`final_scores = pred_logits.sigmoid() * presence_logits.sigmoid()`。 - **semantic_seg** (`torch.Tensor`，形状为 `(batch_size, 1, height, width)`，*可选*) -- 语义分割输出。 - **decoder_hidden_states** (`tuple[torch.Tensor]`，*可选*) -- 来自所有 DETR 解码器层的隐藏状态元组。每个张量的形状为 `(batch_size, num_queries, hidden_size)`。 - **decoder_reference_boxes**（形状为 `(num_layers, batch_size, num_queries, 4)` 的 `torch.Tensor`，*可选*）-- 来自所有 DETR 解码器层的参考框。 - **encoder_hidden_states** (`tuple[torch.Tensor]`，*可选*) -- 来自所有 DETR 编码器层的隐藏状态元组。 - **vision_hidden_states** (`tuple[torch.Tensor]`，*可选*) -- 来自所有视觉编码器（ViT）层的隐藏状态元组。 - **vision_attentions** (`tuple[torch.Tensor]`，*可选*) -- 来自视觉编码器（ViT）层的注意力权重。 - **detr_encoder_attentions** (`tuple[torch.Tensor]`，*可选*) -- 来自 DETR 编码器层的注意力权重。 - **detr_decoder_attentions** (`tuple[torch.Tensor]`, *可选*) -- 来自 DETR 解码器层的注意力权重（自注意力和交叉注意力）。 - **mask_decoder_attentions** (`tuple[torch.Tensor]`，*可选*) -- 来自 mask decoder 层的注意力权重。 示例： ```python >>> from PIL import Image >>> from huggingface_hub.utils import httpx >>> from io import BytesIO >>> from transformers import AutoModel, AutoProcessor >>> model = AutoModel.from_pretrained("facebook/sam3_lite_text") >>> processor = AutoProcessor.from_pretrained("facebook/sam3_lite_text") >>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png" >>> with httpx.stream("GET", url) as response: ... image = Image.open(BytesIO(response.read())).convert("RGB") >>> text = "car" >>> inputs = processor(images=image, text=text, return_tensors="pt") >>> # Get segmentation output >>> outputs = model(**inputs) >>> pred_masks = outputs.pred_masks >>> pred_boxes = outputs.pred_boxes ``` ## Sam3LiteTextPreTrainedModel[[transformers.Sam3LiteTextPreTrainedModel]] #### transformers.Sam3LiteTextPreTrainedModel[[transformers.Sam3LiteTextPreTrainedModel]] ```python transformers.Sam3LiteTextPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_lite_text/modeling_sam3_lite_text.py#L343) **参数：** config ([PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。 该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。 #### forward[[transformers.Sam3LiteTextPreTrainedModel.forward]] ```python forward(*args, **kwargs) ``` 点分路径（例如 `torch.float32`）的模拟值：属性访问链和调用行为如同透传装饰器，`repr` 为点分路径，将其用作基类时会替换为普通的 `type` 基类（PEP 560 `__mro_entries__`），因此真实的子类保留正常的元类，且 `inspect.signature` 读取的是它们真实的 `__init__`，而非模拟对象的。