Transformers documentation

VideoLLaMA3

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Эта модель была опубликована в HF papers 22.01.2025 и добавлена в Hugging Face Transformers 13.10.2025.

VideoLLaMA3

Обзор

Модель VideoLLaMA3 представляет собой значительное обновление модели VideoLLaMA2 от Alibaba DAMO Academy.

Аннотация из статьи звучит следующим образом:

В данной статье мы предлагаем VideoLLaMA 3 — более продвинутую мультимодальную базовую модель для понимания изображений и видео. Ключевая идея проектирования VideoLLaMA3 строится вокруг зрения (vision-centric). Понятие «vision-centric» имеет двойной смысл: это и vision-centric парадигма обучения, и vision-centric архитектура. Ключевой инсайт нашей vision-centric парадигмы обучения состоит в том, что высококачественные данные «изображение-текст» критически важны как для понимания изображений, так и для понимания видео. Вместо подготовки огромных датасетов «видео-текст» мы сосредотачиваемся на создании крупномасштабных высококачественных датасетов «изображение-текст». Обучение VideoLLaMA3 состоит из четырёх этапов: 1) адаптация визуального энкодера (Vision Encoder Adaptation), которая позволяет энкодеру принимать на вход изображения с переменным разрешением; 2) выравнивание визуального и языкового представлений (Vision-Language Alignment), на котором совместно настраиваются визуальный энкодер, проектор и LLM на крупномасштабных данных «изображение-текст», охватывающих несколько типов (включая сцены, документы и диаграммы), а также на чисто текстовых данных; 3) дообучение на множестве задач (Multi-task Fine-tuning), в ходе которого используются данные SFT «изображение-текст» для задач нижнего уровня и данные «видео-текст» для формирования основы понимания видео; 4) дообучение с акцентом на видео (Video-centric Fine-tuning), которое дополнительно улучшает способность модели к пониманию видео. Что касается архитектуры, то для более точного захвата детальных особенностей изображений предобученный визуальный энкодер адаптируется так, чтобы кодировать изображения разного размера в визуальные токены, количество которых соответствует размеру изображения, а не фиксированное число токенов. Для видеовходов мы сокращаем количество визуальных токенов на основе их сходства, чтобы представление видео было более точным и компактным. Благодаря vision-centric дизайну VideoLLaMA3 демонстрирует впечатляющие результаты на бенчмарках понимания изображений и видео.

VideoLLaMA3 architecture. Taken from the technical report.

Эта модель была предоставлена пользователем lkhl.

Пример использования

Вывод для одиночных медиа

Модель может принимать в качестве входных данных как изображения, так и видео. Ниже приведён пример кода для инференса.

from transformers import AutoProcessor, VideoLlama3ForConditionalGeneration


# Load the model in half-precision on the available device(s)
model = VideoLlama3ForConditionalGeneration.from_pretrained("lkhl/VideoLLaMA3-2B-Image-HF", device_map="auto")
processor = AutoProcessor.from_pretrained("lkhl/VideoLLaMA3-2B-Image-HF")


conversation = [
    {
        "role":"user",
        "content":[
            {"type": "image", "image": "https://github.com/DAMO-NLP-SG/VideoLLaMA3/raw/refs/heads/main/assets/sora.png"},
            {"type": "text", "text": "Describe this image."}
        ]
    }
]

inputs = processor.apply_chat_template(
    conversation,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt"
).to(model.device)

# Inference: Generation of the output
output_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids = [output_ids[len(input_ids):] for input_ids, output_ids in zip(inputs.input_ids, output_ids)]
output_text = processor.batch_decode(generated_ids, skip_special_tokens=True, clean_up_tokenization_spaces=True)
print(output_text)



# Video
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "video", "video": "https://github.com/DAMO-NLP-SG/VideoLLaMA3/raw/refs/heads/main/assets/cat_and_chicken.mp4"},
            {"type": "text", "text": "What happened in the video?"},
        ],
    }
]

inputs = processor.apply_chat_template(
    conversation,
    fps=1,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt"
).to(model.device)


# Inference: Generation of the output
output_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids = [output_ids[len(input_ids):] for input_ids, output_ids in zip(inputs.input_ids, output_ids)]
output_text = processor.batch_decode(generated_ids, skip_special_tokens=True, clean_up_tokenization_spaces=True)
print(output_text)

Пакетный вывод для смешанных мультимедийных данных

Модель может обрабатывать батчи входных данных, состоящие из смешанных образцов различных типов, таких как изображения, видео и текст. Ниже приведен пример.

# Image
conversation1 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://github.com/DAMO-NLP-SG/VideoLLaMA3/raw/refs/heads/main/assets/sora.png"},
            {"type": "text", "text": "Describe this image."}
        ]
    }
]

# Video
conversation2 = [
    {
        "role": "user",
        "content": [
            {"type": "video", "video": "https://github.com/DAMO-NLP-SG/VideoLLaMA3/raw/refs/heads/main/assets/cat_and_chicken.mp4"},
            {"type": "text", "text": "What happened in the video?"},
        ],
    }
]

# Text
conversation3 = [
    {
        "role": "user",
        "content": "What color is a banana?"
    }
]


conversations = [conversation1, conversation2, conversation3]
# Preparation for batch inference
inputs = processor.apply_chat_template(
    conversations,
    fps=1,
    add_generation_prompt=True,
    tokenize=True,
    padding=True,
    padding_side="left",
    return_dict=True,
    return_tensors="pt"
).to(model.device)


# Batch Inference
output_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids = [output_ids[len(input_ids):] for input_ids, output_ids in zip(inputs.input_ids, output_ids)]
output_text = processor.batch_decode(generated_ids, skip_special_tokens=True, clean_up_tokenization_spaces=True)
print(output_text)

Flash-Attention 2 для ускорения генерации

Сначала убедитесь, что установлена последняя версия Flash Attention 2:

pip install -U flash-attn --no-build-isolation

Также у вас должно быть оборудование, совместимое с Flash-Attention 2. Подробнее об этом можно прочитать в официальной документации репозитория flash attention. FlashAttention-2 можно использовать только тогда, когда модель загружена в формате torch.float16 или torch.bfloat16.

Чтобы загрузить и запустить модель с использованием Flash Attention-2, просто добавьте attn_implementation="flash_attention_2" при загрузке модели, как показано ниже:

from transformers import VideoLlama3ForConditionalGeneration

model = VideoLlama3ForConditionalGeneration.from_pretrained(
    "lkhl/VideoLLaMA3-2B-Image-HF", , 
    attn_implementation="flash_attention_2",
 device_map="auto")

Transformers

VideoLLaMA3

Обзор

Пример использования

Вывод для одиночных медиа

Пакетный вывод для смешанных мультимедийных данных

Flash-Attention 2 для ускорения генерации

VideoLlama3Config

класс transformers.VideoLlama3Config

VideoLlama3VisionConfig

класс transformers.VideoLlama3VisionConfig

VideoLlama3ImageProcessor

класс transformers.VideoLlama3ImageProcessor

preprocess

VideoLlama3VideoProcessor

класс transformers.VideoLlama3VideoProcessor

preprocess

VideoLlama3ImageProcessorPil

класс transformers.VideoLlama3ImageProcessorPil

preprocess

VideoLlama3Processor

класс transformers.VideoLlama3Processor

__call__

VideoLlama3Model

класс transformers.VideoLlama3Model

forward

get_video_features

get_image_features

VideoLlama3VisionModel

класс transformers.VideoLlama3VisionModel

forward

VideoLlama3ForConditionalGeneration

класс transformers.VideoLlama3ForConditionalGeneration

forward

get_video_features

get_image_features

call