影片處理器

影片處理器是一種實用工具，負責為影片模型準備輸入特徵，以及處理其輸出的後處理。它提供諸如調整大小、歸一化和轉換為 PyTorch 等轉換。

影片處理器擴充套件了影像處理器的功能，允許視覺大型語言模型（VLM）使用與影像不同的引數集來處理影片。它充當原始影片資料和模型之間的橋樑，確保輸入特徵針對 VLM 進行了最佳化。

在新增新的 VLM 或更新現有 VLM 以啟用不同的影片預處理時，儲存和重新載入處理器配置會將影片相關引數儲存在一個名為 video_preprocessing_config.json 的專用檔案中。如果你還沒有更新你的 VLM，也不用擔心，處理器會嘗試從一個名為 preprocessing_config.json 的檔案中載入與影片相關的配置。

用法示例

這是一個如何使用 llava-hf/llava-onevision-qwen2-0.5b-ov-hf 模型載入影片處理器的示例。

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")

目前，如果使用基礎影像處理器處理影片，它會將影片的每一幀都當作一張單獨的影像，並逐幀應用變換。雖然這種方法可行，但效率不高。使用 AutoVideoProcessor 可以讓我們利用快速影片處理器，這些處理器利用了 torchvision 庫。快速處理器可以一次性處理整批影片，而無需遍歷每個影片或幀。這些更新引入了 GPU 加速，並顯著提高了處理速度，尤其對於需要高吞吐量的任務。

快速影片處理器適用於所有模型，並在初始化 AutoVideoProcessor 時預設載入。使用快速影片處理器時，你還可以設定 device 引數來指定處理應在哪個裝置上進行。預設情況下，如果輸入是張量，處理將在與輸入相同的裝置上進行，否則在 CPU 上進行。為了進一步提高速度，當使用“cuda”作為裝置時，我們可以編譯處理器。

import torch
from transformers.video_utils import load_video
from transformers import AutoVideoProcessor

video = load_video("video.mp4")
processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device="cuda")
processor = torch.compile(processor)
processed_video = processor(video, return_tensors="pt")

BaseVideoProcessor

class transformers.BaseVideoProcessor

< 來源 >

( **kwargs: typing_extensions.Unpack[transformers.processing_utils.VideosKwargs] )

引數

do_resize (bool, 可選, 預設為 self.do_resize) — 是否將影片的（高，寬）維度調整到指定的 size。可在 preprocess 方法中透過 do_resize 引數覆蓋。
size (dict, 可選, 預設為 self.size) — 調整大小後輸出影片的尺寸。可在 preprocess 方法中透過 size 引數覆蓋。
size_divisor (int, 可選, 預設為 self.size_divisor) — 用於確保高度和寬度都可以被其整除的大小。
default_to_square (bool, 可選, 預設為 self.default_to_square) — 在調整大小時，如果 size 是一個整數，是否預設調整為正方形影片。
resample (PILImageResampling, 可選, 預設為 self.resample) — 如果調整影片大小，使用的重取樣過濾器。僅在 do_resize 設定為 True 時有效。可在 preprocess 方法中透過 resample 引數覆蓋。
do_center_crop (bool, 可選, 預設為 self.do_center_crop) — 是否將影片中心裁剪到指定的 crop_size。可在 preprocess 方法中透過 do_center_crop 引數覆蓋。
do_pad (bool, 可選) — 是否將影片填充到批處理中影片的 (max_height, max_width)。
crop_size (dict[str, int] 可選, 預設為 self.crop_size) — 應用 center_crop 後輸出影片的尺寸。可在 preprocess 方法中透過 crop_size 引數覆蓋。
do_rescale (bool, 可選, 預設為 self.do_rescale) — 是否透過指定的縮放因子 rescale_factor 對影片進行縮放。可在 preprocess 方法中透過 do_rescale 引數覆蓋。
rescale_factor (int 或 float, 可選, 預設為 self.rescale_factor) — 如果對影片進行縮放，使用的縮放因子。僅在 do_rescale 設定為 True 時有效。可在 preprocess 方法中透過 rescale_factor 引數覆蓋。
do_normalize (bool, 可選, 預設為 self.do_normalize) — 是否對影片進行歸一化。可在 preprocess 方法中透過 do_normalize 引數覆蓋。可在 preprocess 方法中透過 do_normalize 引數覆蓋。
image_mean (float 或 list[float], 可選, 預設為 self.image_mean) — 如果對影片進行歸一化，使用的均值。這是一個浮點數或長度等於影片通道數的浮點數列表。可在 preprocess 方法中透過 image_mean 引數覆蓋。可在 preprocess 方法中透過 image_mean 引數覆蓋。
image_std (float 或 list[float], 可選, 預設為 self.image_std) — 如果對影片進行歸一化，使用的標準差。這是一個浮點數或長度等於影片通道數的浮點數列表。可在 preprocess 方法中透過 image_std 引數覆蓋。可在 preprocess 方法中透過 image_std 引數覆蓋。
do_convert_rgb (bool, 可選, 預設為 self.image_std) — 是否將影片轉換為 RGB。
video_metadata (VideoMetadata, 可選) — 包含影片總時長、fps 和總幀數等資訊的影片元資料。
do_sample_frames (int, 可選, 預設為 self.do_sample_frames) — 是在處理前從影片中取樣幀還是處理整個影片。
num_frames (int, 可選, 預設為 self.num_frames) — 當 do_sample_frames=True 時，取樣的最大幀數。
fps (int, 可選, 預設為 self.fps) — 當 do_sample_frames=True 時，每秒取樣的目標幀數。
return_tensors (str 或 TensorType, 可選) — 如果設定為 `pt`，返回堆疊的張量，否則返回張量列表。
data_format (ChannelDimension 或 str, 可選, 預設為 ChannelDimension.FIRST) — 輸出影片的通道維度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST: 影片格式為 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST: 影片格式為 (height, width, num_channels)。
- 未設定：使用輸入影片的通道維度格式。
input_data_format (ChannelDimension 或 str, 可選) — 輸入影片的通道維度格式。如果未設定，則從輸入影片推斷通道維度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST: 影片格式為 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST: 影片格式為 (height, width, num_channels)。
- "none" 或 ChannelDimension.NONE: 影片格式為 (height, width)。
device (torch.device, 可選) — 處理影片的裝置。如果未設定，則從輸入影片推斷裝置。

構建一個基礎影片處理器。

轉換為 RGB

< 來源 >

( video: torch.Tensor ) → torch.Tensor

引數

video ("torch.Tensor") — 要轉換的影片。

torch.Tensor

轉換後的影片。

將影片轉換為 RGB 格式。

fetch_videos

< 來源 >

( video_url_or_urls: typing.Union[str, list[str]] )

將單個或多個 URL 轉換為相應的 np.array 物件。

如果傳入單個 URL，返回值將是單個物件。如果傳入列表，則返回一個物件列表。

from_dict

< 來源 >

( video_processor_dict: dict **kwargs ) → ~video_processing_utils.VideoProcessorBase

引數

video_processor_dict (dict[str, Any]) — 將用於例項化影片處理器物件的字典。這樣的字典可以從預訓練的檢查點中透過 ~video_processing_utils.VideoProcessorBase.to_dict 方法獲取。
kwargs (dict[str, Any]) — 用於初始化影片處理器物件的附加引數。

~video_processing_utils.VideoProcessorBase

從這些引數例項化的影片處理器物件。

從一個 Python 字典引數中例項化一個 ~video_processing_utils.VideoProcessorBase 型別的物件。

from_json_file

< 來源 >

( json_file: typing.Union[str, os.PathLike] ) → 一個 ~video_processing_utils.VideoProcessorBase 型別的影片處理器

引數

json_file (str 或 os.PathLike) — 包含引數的 JSON 檔案的路徑。

一個 `~video_processing_utils.VideoProcessorBase` 型別的影片處理器

從該 JSON 檔案例項化的 video_processor 物件。

從一個包含引數的 JSON 檔案的路徑例項化一個 `~video_processing_utils.VideoProcessorBase` 型別的影片處理器。

from_pretrained

< 來源 >

( pretrained_model_name_or_path: typing.Union[str, os.PathLike] cache_dir: typing.Union[str, os.PathLike, NoneType] = None force_download: bool = False local_files_only: bool = False token: typing.Union[bool, str, NoneType] = None revision: str = 'main' **kwargs )

引數

pretrained_model_name_or_path (str 或 os.PathLike) — 這可以是以下之一：
- 一個字串，即託管在 huggingface.co 上的模型倉庫中的預訓練影片的 *模型 ID*。
- 一個包含使用 ~video_processing_utils.VideoProcessorBase.save_pretrained 方法儲存的影片處理器檔案的 *目錄* 路徑，例如 ./my_model_directory/。
- 一個儲存的影片處理器 JSON *檔案* 的路徑或 URL，例如 ./my_model_directory/preprocessor_config.json。
cache_dir (str 或 os.PathLike, 可選) — 如果不應使用標準快取，則為下載的預訓練模型影片處理器應快取到的目錄路徑。
force_download (bool, 可選, 預設為 False) — 是否強制（重新）下載影片處理器檔案並覆蓋已存在的快取版本。
resume_download — 已棄用並忽略。所有下載現在在可能的情況下預設恢復。將在 Transformers v5 中移除。
proxies (dict[str, str], 可選) — 一個按協議或端點使用的代理伺服器字典，例如 {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。代理在每次請求時使用。
token (str 或 bool, 可選) — 用作遠端檔案 HTTP 持有者授權的令牌。如果為 True 或未指定，將使用執行 huggingface-cli login 時生成的令牌（儲存在 ~/.huggingface 中）。
revision (str, 可選, 預設為 "main") — 要使用的特定模型版本。它可以是分支名、標籤名或提交 ID，因為我們在 huggingface.co 上使用基於 git 的系統來儲存模型和其他工件，所以 revision 可以是 git 允許的任何識別符號。

從一個影片處理器例項化一個 `~video_processing_utils.VideoProcessorBase` 型別的物件。

示例

# We can't instantiate directly the base class *VideoProcessorBase* so let's show the examples on a
# derived class: *LlavaOnevisionVideoProcessor*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
)  # Download video_processing_config from huggingface.co and cache.
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "./test/saved_model/"
)  # E.g. video processor (or model) was saved using *save_pretrained('./test/saved_model/')*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained("./test/saved_model/preprocessor_config.json")
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False
)
assert video_processor.do_normalize is False
video_processor, unused_kwargs = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False, return_unused_kwargs=True
)
assert video_processor.do_normalize is False
assert unused_kwargs == {"foo": False}

get_video_processor_dict

< 來源 >

( pretrained_model_name_or_path: typing.Union[str, os.PathLike] **kwargs ) → tuple[Dict, Dict]

引數

pretrained_model_name_or_path (str 或 os.PathLike) — 我們想要獲取引數字典的預訓練檢查點的識別符號。
subfolder (str, 可選, 預設為 "") — 如果相關檔案位於 huggingface.co 上模型倉庫的子資料夾內，你可以在此處指定資料夾名稱。

tuple[Dict, Dict]

將用於例項化影片處理器物件的字典。

從一個 pretrained_model_name_or_path 解析出一個引數字典，用於使用 from_dict 例項化一個 ~video_processing_utils.VideoProcessorBase 型別的影片處理器。

preprocess

< 原始碼 >

( videos: typing.Union[list['PIL.Image.Image'], ForwardRef('np.ndarray'), ForwardRef('torch.Tensor'), list['np.ndarray'], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list['np.ndarrray']], list[list['torch.Tensor']]] **kwargs: typing_extensions.Unpack[transformers.processing_utils.VideosKwargs] )

引數

do_resize (bool, 可選, 預設為 self.do_resize) — 是否將影片的（高、寬）維度調整為指定的 size。可在 preprocess 方法中透過 do_resize 引數覆蓋此設定。
size (dict, 可選, 預設為 self.size) — 調整大小後輸出影片的尺寸。可在 preprocess 方法中透過 size 引數覆蓋此設定。
size_divisor (int, 可選, 預設為 self.size_divisor) — 確保高度和寬度都能被該值整除。
default_to_square (bool, 可選, 預設為 self.default_to_square) — 當 size 為整數時，在調整大小時是否預設為方形影片。
resample (PILImageResampling, 可選, 預設為 self.resample) — 調整影片大小時使用的重取樣濾波器。僅當 do_resize 設定為 True 時有效。可在 preprocess 方法中透過 resample 引數覆蓋此設定。
do_center_crop (bool, 可選, 預設為 self.do_center_crop) — 是否將影片中心裁剪為指定的 crop_size。可在 preprocess 方法中透過 do_center_crop 引數覆蓋此設定。
do_pad (bool, 可選) — 是否將影片填充到批處理中影片的 (max_height, max_width)。
crop_size (dict[str, int] 可選, 預設為 self.crop_size) — 應用 center_crop 後輸出影片的尺寸。可在 preprocess 方法中透過 crop_size 引數覆蓋此設定。
do_rescale (bool, 可選, 預設為 self.do_rescale) — 是否透過指定的縮放因子 rescale_factor 對影片進行縮放。可在 preprocess 方法中透過 do_rescale 引數覆蓋此設定。
rescale_factor (int 或 float, 可選, 預設為 self.rescale_factor) — 縮放影片時使用的比例因子。僅當 do_rescale 設定為 True 時有效。可在 preprocess 方法中透過 rescale_factor 引數覆蓋此設定。
do_normalize (bool, 可選, 預設為 self.do_normalize) — 是否對影片進行歸一化。可在 preprocess 方法中透過 do_normalize 引數覆蓋此設定。
image_mean (float 或 list[float], 可選, 預設為 self.image_mean) — 歸一化影片時使用的均值。這是一個浮點數或長度等於影片通道數的浮點數列表。可在 preprocess 方法中透過 image_mean 引數覆蓋此設定。
image_std (float 或 list[float], 可選, 預設為 self.image_std) — 歸一化影片時使用的標準差。這是一個浮點數或長度等於影片通道數的浮點數列表。可在 preprocess 方法中透過 image_std 引數覆蓋此設定。
do_convert_rgb (bool, 可選, 預設為 self.image_std) — 是否將影片轉換為 RGB 格式。
video_metadata (VideoMetadata, 可選) — 影片的元資料，包含總時長、幀率和總幀數等資訊。
do_sample_frames (int, 可選, 預設為 self.do_sample_frames) — 是在處理前從影片中取樣幀，還是處理整個影片。
num_frames (int, 可選, 預設為 self.num_frames) — 當 do_sample_frames=True 時，要取樣的最大幀數。
fps (int, 可選, 預設為 self.fps) — 當 do_sample_frames=True 時，每秒取樣的目標幀數。
return_tensors (str 或 TensorType, 可選) — 如果設定為 `pt`，則返回堆疊的張量，否則返回張量列表。
data_format (ChannelDimension 或 str, 可選, 預設為 ChannelDimension.FIRST) — 輸出影片的通道維度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：影片格式為 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST：影片格式為 (height, width, num_channels)。
- 未設定：使用輸入影片的通道維度格式。
input_data_format (ChannelDimension 或 str, 可選) — 輸入影片的通道維度格式。如果未設定，則從輸入影片中推斷通道維度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：影片格式為 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST：影片格式為 (height, width, num_channels)。
- "none" 或 ChannelDimension.NONE：影片格式為 (height, width)。
device (torch.device, 可選) — 用於處理影片的裝置。如果未設定，將從輸入影片中推斷裝置。

register_for_auto_class

< 原始碼 >

( auto_class = 'AutoVideoProcessor' )

引數

auto_class (str 或 type, 可選, 預設為 "AutoVideoProcessor ") — 用於註冊此新影片處理器的自動類。

將此類註冊到給定的自動類中。這僅應用於自定義影片處理器，因為庫中的處理器已經與 AutoVideoProcessor 對映。

此 API 是實驗性的，在未來版本中可能會有輕微的不相容變更。

sample_frames

< 原始碼 >

( video: torch.Tensor metadata: typing.Union[transformers.video_utils.VideoMetadata, dict, NoneType] = None num_frames: typing.Optional[int] = None fps: typing.Optional[int] = None ) → torch.Tensor

引數

video (torch.Tensor) — 需要被取樣的影片。
metadata (VideoMetadata, 可選) — 影片的元資料，包含總時長、幀率和總幀數等資訊。
num_frames (int, 可選) — 要取樣的最大幀數。預設為 self.num_frames。
fps (int, 可選) — 每秒取樣的目標幀數。預設為 self.fps。

torch.Tensor

取樣後的影片幀。

預設取樣函式，它在 0 和總幀數之間均勻取樣所需數量的幀。如果 fps 與元資料一起傳遞，則每秒均勻取樣 fps 幀。引數 num_frames 和 fps 是互斥的。

save_pretrained

< 原始碼 >

( save_directory: typing.Union[str, os.PathLike] push_to_hub: bool = False **kwargs )

引數

save_directory (str 或 os.PathLike) — 將儲存影片處理器 JSON 檔案的目錄（如果不存在則會建立）。
push_to_hub (bool, 可選, 預設為 False) — 是否在儲存模型後將其推送到 Hugging Face 模型中心。您可以使用 repo_id 指定要推送到的倉庫（預設為您名稱空間中 save_directory 的名稱）。
kwargs (dict[str, Any], 可選) — 傳遞給 push_to_hub() 方法的其他關鍵字引數。

將影片處理器物件儲存到目錄 save_directory 中，以便之後可以使用 ~video_processing_utils.VideoProcessorBase.from_pretrained 類方法重新載入。

to_dict

< 原始碼 >

( ) → dict[str, Any]

dict[str, Any]

構成此影片處理器例項的所有屬性的字典。

將此例項序列化為 Python 字典。

< > 在 GitHub 上更新

Transformers

影片處理器

用法示例

BaseVideoProcessor

class transformers.BaseVideoProcessor

轉換為 RGB

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

preprocess

register_for_auto_class

sample_frames

save_pretrained

to_dict