Transformers documentation
Video Processor
Video Processor
Video Processor là một 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.
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 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.
Sử dụng from_pretrained() để tải cấu hình bộ xử lý video (kích thước ảnh, có chuẩn hóa và co giãn hay không, v.v.) từ một mô hình video trên Hub của Hugging Face hoặc thư mục cục bộ. Cấu hình cho mỗi mô hình được huấn luyện trước nên được lưu trong tệp [video_preprocessor_config.json] nhưng các mô hình cũ hơn có thể lưu cấu hình trong tệp preprocessor_config.json. Lưu ý rằng tệp sau ít được ưu tiên hơn và sẽ bị loại bỏ trong tương lai.
Khi video processor là một phần của multimodal processor, cấu hình của nó được lồng trong processor_config.json. Xem Lưu và tải processor để biết chi tiết.
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")Hiện tại, nếu sử dụng bộ xử lý ảnh cơ bản cho video, dữ liệu video sẽ được xử lý bằng cách coi mỗi khung hình là một ảnh riêng lẻ và áp dụng các phép biến đổi theo từng khung hình. Mặc dù cách tiếp cận này hoạt động được, nhưng nó không hiệu quả cao. Việc sử dụng AutoVideoProcessor cho phép chúng ta tận dụng các bộ xử lý video nhanh, khai thác thư viện torchvision. Các bộ xử lý nhanh xử lý toàn bộ lô video cùng lúc, mà không cần lặp qua từng video hay từng khung hình. Những cập nhật này giới thiệu tăng tốc GPU và cải thiện đáng kể tốc độ xử lý, đặc biệt là đối với các tác vụ yêu cầu thông lượng cao.
Các bộ xử lý video nhanh có sẵn cho tất cả các model và được nạp mặc định khi khởi tạo AutoVideoProcessor. Khi sử dụng bộ xử lý video nhanh, bạn cũng có thể đặt đối số device để chỉ định thiết bị mà quá trình xử lý sẽ được thực hiện. Mặc định, quá trình xử lý được thực hiện trên cùng thiết bị với các đầu vào nếu các đầu vào là tensor, hoặc trên CPU trong trường hợp ngược lại. Để cải thiện tốc độ hơn nữa, chúng ta có thể biên dịch bộ xử lý khi sử dụng bộ tăng tốc làm thiết bị.
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")Lấy mẫu khung
Bộ xử lý video giải mã video và chọn các khung hình mà mô hình thực sự nhìn thấy. Đặt do_sample_frames=True để bật lấy mẫu, sau đó chọn các khung hình theo một trong hai cách.
num_framesyêu cầu một số lượng cố định được phân bố đều trên toàn bộ video.fpsyêu cầu một tốc độ tính bằng số khung hình mỗi giây.
Truyền một đường dẫn hoặc URL và trình xử lý sẽ giải mã video cho bạn bằng torchcodec, trình giải mã mặc định. Nếu torchcodec không khả dụng và bạn đang dùng phiên bản torchvision cũ hơn, quá trình giải mã sẽ chuyển sang torchvision.
Thêm return_metadata=True để nhận lại các chỉ số khung hình đã lấy mẫu, kích thước gốc, thời lượng và fps.
from transformers import AutoVideoProcessor
processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
inputs = processor(videos=["video.mp4"], do_sample_frames=True, fps=1, return_metadata=True, return_tensors="pt")
print(inputs.pixel_values_videos.shape, inputs.video_grid_thw)
print(inputs["video_metadata"][0].total_num_frames)Mặc định của quá trình lấy mẫu (sampling) được xác định theo từng mô hình, và yêu cầu về num_frames hoặc fps chỉ là điểm khởi đầu chứ không phải cam kết. Qwen3-VL lấy mẫu với fps=2 và kẹp kết quả nằm trong khoảng từ min_frames=4 đến max_frames=768, do đó một đoạn clip một giây vẫn cho ra 4 khung hình, trong khi một bản ghi dài sẽ bị giới hạn ở mức thấp hơn nhiều so với số khung hình thực tế.
Các mô hình có temporal_patch_size thêm một ràng buộc thứ hai, trong đó các khung hình được nhóm thành các patch gồm số khung hình đó dọc theo trục thời gian, và khung hình cuối cùng được lặp lại cho đến khi số lượng chia hết.
Nếu bạn truyền vào một mảng video đã được giải mã và vẫn muốn lấy mẫu theo đặc thù của model, hãy cung cấp cả video_metadata. Nếu không có nó, bộ lấy mẫu sẽ không biết được thời lượng gốc hoặc fps, và việc lấy mẫu theo fps sẽ phát ra cảnh báo và giả định rằng video được ghi lại ở 24 fps.
import torch
from transformers import AutoVideoProcessor
from transformers.video_utils import VideoMetadata
processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
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)
inputs = processor(
videos=[video], video_metadata=[video_metadata], do_sample_frames=True, num_frames=16, return_tensors="pt"
)