Transformers documentation

PE 视频

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2025-04-17 在 HF papers 上发布,并于 2025-12-16 贡献至 Hugging Face Transformers。 该模型于 2025-04-17 发布,并于 2025-12-16 添加至 Hugging Face Transformers。

PE 视频

PE Video 是 Meta 的 Perception Encoder 系列中的视频分支。它将视频片段与文本在共享的嵌入空间中进行对比对齐,从而能够基于单一预训练骨干网络实现零样本视频分类和图文检索。

编码器的旋转位置嵌入和补丁嵌入器将时间轴视为一等维度,因此无需对每一帧进行独立平铺,即可对可变长度的片段进行编码。

您可以在 perception-encoder-audio-visual 集合中找到所有官方的 PE Audio 检查点。

快速入门

import torch
from transformers import AutoProcessor, PeVideoModel
from transformers.video_utils import load_video

processor = AutoProcessor.from_pretrained("facebook/pe-av-large")
model = PeVideoModel.from_pretrained(
    "facebook/pe-av-large",
    device_map="auto",
)

video, _ = load_video("https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4")
labels = ["a person playing tennis", "a person cooking", "a cat sleeping"]

video_inputs = processor.video_processor(video, num_frames=16, return_tensors="pt").to(model.device)
text_inputs = processor.tokenizer(labels, padding=True, return_tensors="pt").to(model.device)
inputs = {**video_inputs, **text_inputs}

with torch.no_grad():
    outputs = model(**inputs)

probs = outputs.logits_video_text.sigmoid()
print({label: p.item() for label, p in zip(labels, probs[0])})

使用技巧与说明

  • 可变长度视频使用 padding_mask_videos(而非 attention_mask)。视频处理器仅在设置了 return_tensors 时才会填充并返回该掩码——否则,你将得到一个包含每个片段张量的列表,且没有掩码。
  • 将 num_frames 传递给视频处理器,以在 [0, total_frames-1] 范围内进行固定长度的均匀采样。省略该参数则会回退到基类中的基于 fps 的采样。检查点通常在特定的帧数下训练,因此请确保与检查点所期望的帧数一致。
  • 编码器的输入为 pixel_values_videos。编码器的 main_input_name 是 "pixel_values_videos",而完整模型的 main_input_name 是 "input_ids"。当通过检查 main_input_name 的通用工具进行路由时,这一点至关重要。

PeVideoConfig

class transformers.PeVideoConfig

< >

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

参数

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig],可选) — 文本骨干网络的配置对象或字典。
  • video_config (dict 或 PreTrainedConfig,可选) — 视频编码器组件的配置。

这是用于存储 PeVideoModel 配置的类。它根据指定的参数实例化 Pe Video 模型,并定义模型架构。使用默认值实例化配置将得到与 facebook/pe-av-large 类似的配置。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请参阅 PreTrainedConfig 的文档。

>>> from transformers import PeVideoModel, PeVideoConfig

>>> # Initializing a PeVideoModel style configuration
>>> configuration = PeVideoConfig()

>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeVideoModel(configuration)

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

PeVideoEncoderConfig

类 transformers.PeVideoEncoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonehidden_size: int = 1792intermediate_size: int = 4800num_hidden_layers: int = 6num_attention_heads: int = 14num_key_value_heads: int | None = Nonehead_dim: int = 128hidden_act: str = 'silu'max_position_embeddings: int = 10000initializer_range: float = 0.02rms_norm_eps: float = 1e-05rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int = 0.0 )

参数

  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig],可选) — 视觉骨干网络的配置对象或字典。
  • hidden_size (int,可选,默认为 1792) — 隐藏表示的维度。
  • intermediate_size (int,可选,默认为 4800) — MLP 表示的维度。
  • num_hidden_layers (int,可选,默认为 6) — Transformer 解码器中的隐藏层数量。
  • num_attention_heads (int,可选,默认为 14) — Transformer 解码器中每个注意力层的注意力头数量。
  • num_key_value_heads (int, 可选) — 这是用于实现 Grouped Query Attention 的 key_value 头数。如果 num_key_value_heads=num_attention_heads,模型将使用 Multi Head Attention (MHA);如果 num_key_value_heads=1,模型将使用 Multi Query Attention (MQA);否则使用 GQA。在将多头检查点转换为 GQA 检查点时,每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 这篇论文。如果未指定,则默认为 num_attention_heads。
  • head_dim (int,可选,默认为 128) — 注意力头维度。如果为 None,则默认为 hidden_size // num_attention_heads
  • hidden_act (str,可选,默认为 silu) — 解码器中的非线性激活函数(函数或字符串)。例如,"gelu"、 "relu"、"silu" 等。
  • max_position_embeddings (int,可选,默认为 10000) — 该模型可能使用的最大序列长度。
  • initializer_range (float,可选,默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
  • rms_norm_eps (float,可选,默认为 1e-05) — RMS 归一化层使用的 epsilon 值。
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 可选) — 包含 RoPE 嵌入配置参数的字典。该字典应包含 rope_theta 的值,并且如果希望使用 RoPE 处理更长的 max_position_embeddings,则可选地包含用于缩放的参数。
  • attention_bias (bool,可选,默认为 False) — 在自注意力机制中,是否在 query、key、value 和 output 投影层中使用偏置。
  • attention_dropout (Union[float, int],可选,默认为 0.0) — 注意力概率的 dropout 比率。

这是用于存储 PeVideoModel 配置的类。它根据指定的参数实例化 Pe Video 模型,并定义模型架构。使用默认值实例化配置将得到与 facebook/pe-av-large 类似的配置。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请参阅 PreTrainedConfig 的文档。

示例:

>>> from transformers import PeAudioEncoder, PeAudioEncoderConfig

>>> # Initializing a PeAudioEncoder style configuration
>>> configuration = PeAudioEncoderConfig()

>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioEncoder(configuration)

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

PeVideoVideoProcessor

class transformers.PeVideoVideoProcessor

< >

( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )

参数

  • do_convert_rgb (bool,kwargs,可选) — 是否将图像转换为 RGB。
  • do_resize (bool,kwargs,可选) — 是否调整图像大小。
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 描述模型的最大输入维度。
  • default_to_square (bool,kwargs,可选,默认为 True) — 当 size 为 int 时,是否在调整大小时默认使用正方形图像。
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs,默认为 2) — 如果调整图像大小,则使用的重采样滤波器。它可以是枚举 PILImageResampling 中的一个值。仅当 do_resize 设置为 True 时才会生效。
  • do_rescale (bool,kwargs,可选) — 是否对图像进行重新缩放。
  • rescale_factor (float,kwargs,可选,默认为 0.00392156862745098) — 当 do_rescale 设置为 True 时,用于对图像进行缩放的缩放因子。
  • do_normalize (bool,kwargs,可选) — 是否对图像进行归一化。
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像均值。仅当 do_normalize 设置为 True 时生效。
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像标准差。仅当 do_normalize 设置为 True 时生效。
  • do_center_crop (bool,kwargs,可选) — 是否对图像进行中心裁剪。
  • do_pad (bool, kwargs, 可选) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸,或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用 center_crop 后输出图像的尺寸。
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持 ChannelDimension.FIRST。为兼容旧版处理器而添加。
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置,则从输入图像中推断通道维度格式。可以是以下之一:
    • "channels_first" 或 ChannelDimension.FIRST:图像采用 (num_channels, height, width) 格式。
    • "channels_last" 或 ChannelDimension.LAST:图像采用 (height, width, num_channels) 格式。
    • "none" 或 ChannelDimension.NONE:图像为 (height, width) 格式。
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置,则从输入视频中推断设备。
  • do_sample_frames (bool, kwargs, 可选) — 是否在处理前对视频进行帧采样,还是处理整个视频。
  • video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — 视频的元数据,包含总时长、帧率(fps)和总帧数等信息。该元数据将用于从视频中采样帧或计算时间戳。除非您打算在预处理之前手动解码视频,否则请勿传入任何元数据。
  • fps (Annotated[int | float | None, None], kwargs) — 当 do_sample_frames=True 时,每秒要采样的目标帧数。
  • num_frames (Annotated[int | None, None], kwargs) — 当 do_sample_frames=True 时,要采样的最大帧数。
  • return_metadata (bool,kwargs,可选,默认为 False) — 是否返回视频元数据。视频元数据是一个包含视频时长、帧率、解码后端等信息的对象。
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置,将返回特定框架的张量。可接受的值为:
    • 'pt':返回 PyTorch torch.Tensor 对象。
    • 'np':返回 NumPy np.ndarray 对象。
  • **kwargs (VideosKwargs,可选) — 每种模态(文本、图像、视频、音频)的额外处理选项。模型特定参数已在上方列出;有关支持参数的完整列表,请参阅 TypedDict 类。

构造一个 PeVideoVideoProcessor 视频处理器。

PeVideoProcessor

class transformers.PeVideoProcessor

< >

( *args**kwargs )

PeVideoEncoder

class transformers.PeVideoEncoder

< >

( config: PeVideoEncoderConfig )

参数

  • config (PeVideoEncoderConfig) — 模型的配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

PeVideo Encoder 模型。

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( pixel_values_videos: Tensorpadding_mask_videos: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

参数

  • pixel_values_videos(形状为 (batch_size, num_frames, num_channels, frame_size, frame_size) 的 torch.Tensor)— 对应输入视频的张量。可以使用 PeVideoVideoProcessor 获取视频的像素值。有关详细信息,请参阅 PeVideoVideoProcessor.call()(PeVideoProcessor 使用 PeVideoVideoProcessor 来处理视频)。
  • padding_mask_videos (torch.Tensor 形状为 (batch_size, num_frames), ,可选) — 用于避免对填充视频帧执行注意力机制的掩码。掩码值在 [0, 1]:
    • 1 对于未被掩码的帧,
    • 对于被掩码的帧,值为 0。

返回值

BaseModelOutputWithPooling 或 tuple(torch.Tensor)

一个 BaseModelOutputWithPooling 或 torch.Tensor 元组(如果传入了 return_dict=False 或 config.return_dict=False),其包含的元素取决于配置(PeVideoConfig)和输入。

PeVideoEncoder 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义,但之后应调用 Module 实例,而不是直接调用此函数,因为前者会负责执行预处理和后处理步骤,而后者则会静默地忽略这些步骤。

  • last_hidden_state(形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor)— 模型最后一层输出的隐藏状态序列。

  • pooler_output (torch.Tensor,形状为 (batch_size, hidden_size)) — 序列中第一个 token(分类 token)的最后一层隐藏状态,经过用于辅助预训练任务的层进一步处理后得到。例如,对于 BERT 系列模型,这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测(分类)目标进行训练。

  • hidden_states (tuple(torch.Tensor),可选,当传入 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — 一个 torch.Tensor 元组(如果模型具有嵌入层,则包含嵌入层的输出,以及每一层的输出),形状为 (batch_size, sequence_length, hidden_size)。

    模型在每一层输出处的隐藏状态,以及可选的初始嵌入输出。

  • attentions (tuple(torch.Tensor),可选,当传入 output_attentions=True 或 config.output_attentions=True 时返回) — 一个 torch.Tensor 元组(每层一个),形状为 (batch_size, num_heads, sequence_length, sequence_length)。

    注意力权重,即经过注意力 softmax 之后的权重,用于在自注意力头中计算加权平均值。

PeVideoModel

class transformers.PeVideoModel

< >

( config: PeVideoConfig )

forward

< >

( input_ids: Tensorpixel_values_videos: Tensorattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = Nonereturn_loss: bool | None = None**kwargs ) → PeVideoOutput or tuple(torch.Tensor)

参数

  • input_ids (torch.Tensor 形状为 (batch_size, sequence_length)) — 输入序列中各 token 在词汇表中的索引。默认情况下,填充(padding)会被忽略。

    可以使用 AutoTokenizer 获取索引。有关详细信息,请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

    什么是输入 ID?

  • pixel_values_videos(形状为 (batch_size, num_frames, num_channels, frame_size, frame_size) 的 torch.Tensor)— 对应输入视频的张量。可以使用 PeVideoVideoProcessor 获取视频的像素值。有关详细信息,请参阅 PeVideoVideoProcessor.call()(PeVideoProcessor 使用 PeVideoVideoProcessor 来处理视频)。
  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ,可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token,
    • 对于被掩码的 token,值为 0。

    什么是注意力掩码?

  • padding_mask_videos (torch.Tensor 形状为 (batch_size, num_frames), ,可选) — 用于避免对填充视频帧执行注意力机制的掩码。掩码值在 [0, 1]:
    • 1 对于未被掩码的帧,
    • 对于被掩码的帧,值为 0。
  • return_loss (bool, 可选) — 是否返回损失值。

返回值

PeVideoOutput 或 tuple(torch.Tensor)

PeVideoOutput 或 torch.Tensor 元组(当传入 return_dict=False 或 config.return_dict=False 时),其包含的元素取决于配置(PeVideoConfig)和输入。

PeVideoModel 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义,但之后应调用 Module 实例,而不是直接调用此函数,因为前者会负责执行预处理和后处理步骤,而后者则会静默地忽略这些步骤。

  • loss (torch.Tensor,形状为 (1,),可选) — 在视频和文本表示之间计算的对比损失。
  • logits_video_text(形状为 (batch_size, batch_size) 的 torch.Tensor,可选)— 视频嵌入与文本嵌入之间的相似度 logits。
  • text_video_embeds(形状为 (batch_size, hidden_size) 的 torch.Tensor,可选)— 投影到视频-文本空间的文本嵌入。
  • video_embeds(形状为 (batch_size, hidden_size) 的 torch.Tensor,可选)— 投影到视频-文本空间的视频嵌入。
  • text_outputs (BaseModelOutputWithPooling,可选) — 文本编码器的模型输出,包括最后一个隐藏状态和池化输出。
  • video_outputs (BaseModelOutputWithPooling,可选) — 视频编码器的模型输出,包括最后一个隐藏状态和池化输出。
Update on GitHub