Bộ xử lý video

Video Processor là tiện ích chịu trách nhiệm chuẩn bị các đặc trưng đầu vào cho các mô hình video, cũng như xử lý hậu xử lý đầu ra của chúng. Nó cung cấp các phép biến đổi như thay đổi kích thước, chuẩn hóa và chuyển đổi sang PyTorch. Cùng với các phép biến đổi, lớp VideoProcessor xử lý việc giải mã video từ đường dẫn cục bộ hoặc URL (yêu cầu torchcodec) và lấy mẫu khung hình theo các chiến lược cụ thể của từng mô hình.

Bộ xử lý video mở rộng chức năng của bộ xử lý ảnh bằng cách cho phép các Mô hình Ngôn ngữ Lớn Thị giác (VLM) xử lý video với một bộ đối số riêng biệt so với ảnh. Nó đóng vai trò là cầu nối giữa dữ liệu video thô và mô hình, đảm bảo rằng các đặc trưng đầu vào được tối ưu hóa cho VLM.

Cấu hình video processor được lưu trong video_preprocessor_config.json. Các checkpoint cũ hơn có thể lưu chúng trong preprocessor_config.json. Xem Lưu và nạp lại để biết về việc đăng ký backend tùy chỉnh khi nạp lại.

Ví dụ sử dụng

Dưới đây là một ví dụ về cách tải bộ xử lý video với mô hình 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")

Preprocessing được thực thi trên thiết bị của tensor đầu vào, hoặc trên CPU đối với các đầu vào khác. Đặt device để di chuyển video sang một thiết bị khác trước khi tiền xử lý; điều này không thay đổi backend. Bạn cũng có thể biên dịch tiền xử lý của torchvision bằng torch.compile khi sử dụng bộ tăng tốc.

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

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

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

Các backend của bộ xử lý video

Bộ xử lý video tích hợp sử dụng torchvision để thực hiện việc thay đổi kích thước, điều chỉnh tỷ lệ và chuẩn hóa theo lô. Hãy cài đặt PyTorch và torchvision để sử dụng chúng. Khác với bộ xử lý ảnh, các bộ xử lý video tích hợp không cung cấp backend PIL.

AutoVideoProcessor mặc định chọn torchvision. Bạn cũng có thể yêu cầu backend này một cách tường minh và kiểm tra thuộc tính backend của processor đã được nạp.

from transformers import AutoVideoProcessor

model_id = "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
video_processor = AutoVideoProcessor.from_pretrained(model_id, backend="torchvision")
print(video_processor.backend)
# torchvision

Tham số backend chọn cài đặt tiền xử lý, không phải trình giải mã video. Xem Hành vi lấy mẫu để biết về việc giải mã và lấy mẫu khung hình.

Các backend tùy chỉnh

BaseVideoProcessor cung cấp tiền xử lý dựa trên torchvision. Đối với một triển khai không dùng torchvision, bạn có thể kế thừa VideoProcessorMixin và ghi đè preprocess để trả về một BatchFeature chứa các đầu vào mà model kỳ vọng.

Đăng ký các lớp tùy chỉnh với AutoVideoProcessor.register(), và sử dụng video_processor_classes để ánh xạ tên backend sang các lớp. Ví dụ bên dưới giả định NewCustomVideoProcessor được định nghĩa với các bước tiền xử lý cần thiết cho checkpoint LLaVA-OneVision.

from transformers import LlavaOnevisionConfig

AutoVideoProcessor.register(
    LlavaOnevisionConfig,
    video_processor_classes={"custom": NewCustomVideoProcessor},
    exist_ok=True,
)
custom_processor = AutoVideoProcessor.from_pretrained(model_id, backend="custom")

Sử dụng exist_ok=True vì LlavaOnevisionConfig đã được đăng ký. Các mục được cung cấp sẽ được gộp vào ánh xạ backend của nó, trong đó các mục có tên trùng khớp sẽ bị thay thế, còn các mục không được cung cấp, chẳng hạn như torchvision, sẽ được giữ nguyên.

Lưu và nạp lại

save_pretrained() lưu cấu hình tiền xử lý, không lưu các ánh xạ backend được thêm bằng AutoVideoProcessor.register(). Trong cùng một tiến trình Python, tải lại bộ xử lý đã lưu với backend="custom":

custom_processor.save_pretrained("./saved-video-processor")
custom_processor = AutoVideoProcessor.from_pretrained("./saved-video-processor", backend="custom")

Các đăng ký tùy chỉnh chỉ áp dụng cho tiến trình Python hiện tại. Trong một tiến trình mới, hãy định nghĩa hoặc nhập lớp tùy chỉnh và đăng ký lại trước khi tải.

Hành vi lấy mẫu

Video processor cũng có thể lấy mẫu các khung hình video bằng kỹ thuật phù hợp nhất cho mô hình được chỉ định. Hành vi lấy mẫu được kiểm soát bằng đối số do_sample_frames và có thể được cấu hình thông qua các tham số cụ thể của mô hình như num_frames hoặc fps (tốc độ mà video sẽ được lấy mẫu). Nếu video đầu vào được cung cấp dưới dạng đường dẫn cục bộ hoặc URL (str), trình xử lý sẽ tự động giải mã nó. Để lấy các siêu dữ liệu về video đã được giải mã, chẳng hạn như chỉ số các khung hình được lấy mẫu, kích thước gốc, thời lượng và fps, hãy truyền return_metadata=True cho trình xử lý.

Việc chỉ định num_frames không đảm bảo rằng đầu ra sẽ chứa chính xác số khung hình đó. Tùy thuộc vào mô hình, trình lấy mẫu có thể áp dụng giới hạn tối thiểu hoặc tối đa về số khung hình.

Bộ giải mã mặc định là torchcodec, và bạn phải cài đặt nó.

import torch
from transformers import AutoVideoProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processed_video_inputs = processor(videos=["video_path.mp4"], return_metadata=True, do_sample_frames=True, return_tensors="pt")
video_metadata = processed_video_inputs["video_metadata"]

# See how many frames the original video had and what was the original FPS
print(video_metadata.total_num_frames, video_metadata.fps)

Nếu bạn truyền vào một mảng video đã được giải mã nhưng vẫn muốn bật lấy mẫu khung hình theo mô hình, rất khuyến nghị cung cấp video_metadata. Điều này cho phép bộ lấy mẫu biết được thời lượng và FPS của video gốc. Bạn có thể truyền metadata dưới dạng một đối tượng VideoMetadata hoặc một dict thông thường.

import torch
from transformers import AutoVideoProcessor
from transformers.video_utils import VideoMetadata

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
decoded_video = torch.randint(0, 255, size=(100, 3, 1280, 1280)) # short video of 100 frames
video_metadata = VideoMetadata(
    total_num_frames=100,
    fps=24,
    duration=4.1, # in seconds
)
processed_video_inputs = processor(videos=[decoded_video], video_metadata=video_metadata, do_sample_frames=True, num_frames=10, return_tensors="pt")
print(processed_video_inputs.pixel_values_videos.shape)
[10, 3, 384, 384]

VideoProcessorMixin

lớp transformers.VideoProcessorMixin

< source >

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

fetch_videos

< source >

( video_url_or_urls: str | list[str] | list[list[str]]sample_indices_fn = None )

Chuyển đổi một hoặc một danh sách các url thành các đối tượng np.array tương ứng.

Nếu một url duy nhất được truyền vào, giá trị trả về sẽ là một đối tượng duy nhất. Nếu một danh sách được truyền vào, một danh sách các đối tượng sẽ được trả về.

from_dict

< source >

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

Tham số

video_processor_dict (dict[str, Any]) — Từ điển sẽ được dùng để khởi tạo đối tượng video processor. Một từ điển như vậy có thể được lấy từ checkpoint được huấn luyện trước bằng cách sử dụng phương thức ~video_processing_utils.VideoProcessorBase.to_dict.
kwargs (dict[str, Any]) — Các tham số bổ sung để khởi tạo đối tượng video processor.

Trả về

~video_processing_utils.VideoProcessorBase

Đối tượng video processor được khởi tạo từ các tham số đó.

Tạo một kiểu ~video_processing_utils.VideoProcessorBase từ một từ điển Python chứa các tham số.

from_json_file

< source >

( json_file: str | os.PathLike ) → A video processor of type ~video_processing_utils.VideoProcessorBase

Tham số

json_file (str hoặc os.PathLike) — Đường dẫn đến tệp JSON chứa các tham số.

Trả về

Bộ xử lý video có kiểu ~video_processing_utils.VideoProcessorBase

Đối tượng video_processor được khởi tạo từ tệp JSON đó.

Tạo một video processor có kiểu ~video_processing_utils.VideoProcessorBase từ đường dẫn đến tệp JSON chứa các tham số.

from_pretrained

< source >

Tham số

pretrained_model_name_or_path (str hoặc os.PathLike) — Đây có thể là:
- một chuỗi, model id của một video được huấn luyện trước được lưu trữ trong một kho model trên huggingface.co.
- đường dẫn đến một thư mục chứa tệp video processor được lưu bằng phương thức ~video_processing_utils.VideoProcessorBase.save_pretrained, ví dụ: ./my_model_directory/.
- đường dẫn đến tệp JSON của video processor đã lưu file, ví dụ: ./my_model_directory/video_preprocessor_config.json.
cache_dir (str hoặc os.PathLike, tùy chọn) — Đường dẫn đến thư mục mà trình xử lý video của mô hình được huấn luyện trước đã tải xuống sẽ được lưu đệm, nếu không sử dụng bộ lưu đệm tiêu chuẩn.
force_download (bool, tùy chọn, mặc định là False) — Có nên buộc (tải lại) các tệp video processor và ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không.
proxies (dict[str, str], tuỳ chọn) — Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ: {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Các proxy này được sử dụng cho mỗi yêu cầu.
token (str hoặc bool, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True, hoặc không được chỉ định, sẽ sử dụng token được tạo khi chạy hf auth login (được lưu trong ~/.huggingface).
revision (str, tùy chọn, mặc định là "main") — Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ hoặc id commit, vì chúng tôi sử dụng hệ thống dựa trên git để lưu trữ các mô hình và các sản phẩm khác trên huggingface.co, do đó revision có thể là bất kỳ định danh nào được git cho phép.

Tạo một kiểu ~video_processing_utils.VideoProcessorBase từ một video processor.

Ví dụ:

# 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/video_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

< source >

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

Tham số

pretrained_model_name_or_path (str hoặc os.PathLike) — Định danh của checkpoint được huấn luyện trước mà chúng ta muốn lấy từ điển các tham số từ đó.
subfolder (str, tùy chọn, mặc định là "") — Trong trường hợp các tệp liên quan nằm trong một thư mục con của kho mô hình trên huggingface.co, bạn có thể chỉ định tên thư mục ở đây.

Trả về

tuple[Dict, Dict]

Từ điển sẽ được sử dụng để khởi tạo đối tượng video processor.

Từ pretrained_model_name_or_path, phân giải thành một từ điển các tham số, để sử dụng cho việc khởi tạo một video processor có kiểu ~video_processing_utils.VideoProcessorBase bằng from_dict.

preprocess

< source >

( videos: 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]]]**kwargs: *<class 'transformers.processing_utils.VideosKwargs'> ) → ~image_processing_base.BatchFeature

Tham số

videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]) — Video cần tiền xử lý. Kỳ vọng một video đơn hoặc một lô video có giá trị pixel từ 0 đến 255. Nếu truyền vào các video có giá trị pixel từ 0 đến 1, hãy đặt do_rescale=False.
do_convert_rgb (bool, kwargs, optional) — Có nên chuyển đổi ảnh sang RGB hay không.
do_resize (bool, kwargs, optional) — Có nên thay đổi kích thước ảnh hay không.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Mô tả các kích thước đầu vào tối đa của mô hình.
default_to_square (bool, kwargs, tuỳ chọn) — Có mặc định thành ảnh vuông khi thay đổi kích thước hay không, nếu size là một số nguyên.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Bộ lọc lấy mẫu lại (resampling filter) được sử dụng khi thay đổi kích thước ảnh. Giá trị này có thể là một trong các hằng số liệt kê (enum) của PILImageResampling. Chỉ có hiệu lực khi do_resize được đặt thành True.
do_rescale (bool, kwargs, optional) — Có nên điều chỉnh lại tỷ lệ ảnh hay không.
rescale_factor (float, kwargs, optional) — Hệ số rescale để rescale ảnh nếu do_rescale được đặt thành True.
do_normalize (bool, kwargs, optional) — Có nên chuẩn hóa ảnh hay không.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, optional) — Giá trị trung bình của ảnh để sử dụng cho việc chuẩn hóa. Chỉ có hiệu lực nếu do_normalize được đặt thành True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, optional) — Độ lệch chuẩn của ảnh để sử dụng cho việc chuẩn hóa. Chỉ có hiệu lực nếu do_normalize được đặt thành True.
do_center_crop (bool, kwargs, optional) — Có nên cắt ảnh ở vị trí trung tâm hay không.
do_pad (bool, kwargs, optional) — Có nên chèn padding cho ảnh hay không. Padding được thực hiện đến kích thước lớn nhất trong batch hoặc đến một kích thước vuông cố định cho mỗi ảnh. Chiến lược padding cụ thể phụ thuộc vào model.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Kích thước của ảnh đầu ra sau khi áp dụng center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, optional) — Chỉ hỗ trợ ChannelDimension.FIRST. Được thêm vào để tương thích với các bộ xử lý chậm.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, tùy chọn) — Định dạng chiều kênh cho ảnh đầu vào. Nếu không được đặt, định dạng chiều kênh sẽ được suy ra từ ảnh đầu vào. Có thể là một trong các giá trị:
- "channels_first" hoặc ChannelDimension.FIRST: ảnh ở định dạng (num_channels, height, width).
- "channels_last" hoặc ChannelDimension.LAST: ảnh ở định dạng (height, width, num_channels).
- "none" hoặc ChannelDimension.NONE: ảnh ở định dạng (chiều cao, chiều rộng).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Thiết bị để xử lý các video. Nếu không được đặt, thiết bị sẽ được suy ra từ các video đầu vào.
do_sample_frames (bool, kwargs, tuỳ chọn) — Có lấy mẫu các khung hình từ video trước khi xử lý hay xử lý toàn bộ video hay không.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadata của video, chứa thông tin về tổng thời lượng, fps và tổng số khung hình. Nó sẽ được sử dụng để lấy mẫu các khung hình từ video hoặc tính toán mốc thời gian. Không truyền bất kỳ metadata nào trừ khi bạn đang cố gắng giải mã video thủ công trước khi xử lý
fps (Annotated[int | float | None, None], kwargs) — Số khung hình mục tiêu cần lấy mẫu mỗi giây khi do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Số khung hình tối đa cần lấy mẫu khi do_sample_frames=True.
return_metadata (bool, kwargs, optional) — Có nên trả về metadata của video hay không. Video metadata là một object chứa thông tin về thời lượng video, fps, backend giải mã, v.v.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Trả về các tensor được xếp chồng nếu được đặt thành 'pt', ngược lại trả về một danh sách các tensor.

Trả về

~image_processing_base.BatchFeature

data (dict) — Từ điển chứa các danh sách/mảng/tensor được trả về bởi phương thức call (‘pixel_values’, v.v.).
tensor_type (Union[None, str, TensorType], tùy chọn) — Bạn có thể cung cấp một tensor_type tại đây để chuyển đổi các danh sách số nguyên trong Tensor PyTorch/Numpy khi khởi tạo.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

Tham số

auto_class (str hoặc type, tùy chọn, mặc định là "AutoVideoProcessor ") — Lớp auto để đăng ký trình xử lý video mới này.

Đăng ký lớp này với một lớp auto cho trước. Chỉ nên sử dụng cho các video processor tùy chỉnh vì các video processor trong thư viện đã được ánh xạ với AutoVideoProcessor.

API này đang ở giai đoạn thử nghiệm và có thể có một số thay đổi nhỏ gây mất tương thích trong các bản phát hành tiếp theo.

save_pretrained

< source >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

Tham số

save_directory (str hoặc os.PathLike) — Thư mục nơi tệp JSON của video processor sẽ được lưu (sẽ được tạo nếu chưa tồn tại).
push_to_hub (bool, tùy chọn, mặc định là False) — Có đẩy mô hình của bạn lên Hugging Face model hub sau khi lưu hay không. Bạn có thể chỉ định kho lưu trữ muốn đẩy đến bằng repo_id (mặc định sẽ là tên của save_directory trong namespace của bạn).
kwargs (dict[str, Any], tùy chọn) — Các đối số từ khóa bổ sung được truyền đến phương thức push_to_hub().

Lưu đối tượng video processor vào thư mục save_directory để có thể tải lại bằng phương thức lớp ~video_processing_utils.VideoProcessorBase.from_pretrained.

to_dict

< source >

( ) → dict[str, Any]

Trả về

dict[str, Any]

Từ điển chứa tất cả các thuộc tính cấu thành lên bản thể video processor này.

Chuẩn hóa bản thể này thành một từ điển Python.

BaseVideoProcessor

lớp transformers.BaseVideoProcessor

< source >

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

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

Tham số

video ("torch.Tensor") — Video cần chuyển đổi.

Trả về

torch.Tensor

Video đã được chuyển đổi.

Chuyển đổi video sang định dạng RGB.

sample_frames

< source >

( metadata: VideoMetadatanum_frames: int | None = Nonefps: int | float | None = None**kwargs ) → np.ndarray

Tham số

metadata (VideoMetadata) — Metadata của video, chứa thông tin về tổng thời lượng, fps và tổng số khung hình.
num_frames (int, tùy chọn) — Số khung hình tối đa cần lấy mẫu. Mặc định là self.num_frames.
fps (int hoặc float, tùy chọn) — Số khung hình mục tiêu cần lấy mẫu mỗi giây. Mặc định là self.fps.

Trả về

np.ndarray

Chỉ số để lấy mẫu các khung hình video.

Hàm lấy mẫu mặc định, lấy mẫu đều số khung hình mong muốn giữa 0 và tổng số khung hình. Nếu fps được truyền cùng với metadata, fps khung hình mỗi giây sẽ được lấy mẫu đều. Các đối số num_frames và fps là loại trừ lẫn nhau.

Update on GitHub

Transformers

Bộ xử lý video

Ví dụ sử dụng

Các backend của bộ xử lý video

Các backend tùy chỉnh

Lưu và nạp lại

Hành vi lấy mẫu

VideoProcessorMixin

lớp transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

preprocess

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

lớp transformers.BaseVideoProcessor

convert_to_rgb

sample_frames