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.1).

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

Este modelo foi publicado em papers do HF em 2025-01-22 e contribuído para o Hugging Face Transformers em 2025-10-13.

VideoLLaMA3

Visão geral

O modelo VideoLLaMA3 é uma atualização importante do VideoLLaMA2, da Alibaba DAMO Academy.

O resumo do artigo é o seguinte:

Neste artigo, propomos o VideoLLaMA 3, um modelo de fundação multimodal mais avançado para a compreensão de imagens e vídeos. A filosofia de design central do VideoLLaMA3 é centrada na visão. O significado de “centrado na visão” é duplo: o paradigma de treinamento centrado na visão e o design de framework centrado na visão. O principal insight do nosso paradigma de treinamento centrado na visão é que dados de imagem-texto de alta qualidade são cruciais para a compreensão tanto de imagens quanto de vídeos. Em vez de preparar conjuntos de dados massivos de vídeo-texto, focamos na construção de conjuntos de dados de imagem-texto em larga escala e de alta qualidade. O VideoLLaMA3 possui quatro estágios de treinamento: 1) Adaptação do Vision Encoder, que permite que o vision encoder aceite imagens de resoluções variáveis como entrada; 2) Alinhamento Visão-Linguagem, que ajusta conjuntamente o vision encoder, o projetor e o LLM com dados de imagem-texto em larga escala cobrindo múltiplos tipos (incluindo imagens de cena, documentos e gráficos), bem como dados apenas de texto. 3) Fine-tuning Multi-tarefa, que incorpora dados SFT de imagem-texto para tarefas downstream e dados de vídeo-texto para estabelecer uma base para a compreensão de vídeos. 4) Fine-tuning centrado em vídeo, que melhora ainda mais a capacidade do modelo na compreensão de vídeos. Quanto ao design do framework, para capturar melhor os detalhes finos nas imagens, o vision encoder pré-treinado é adaptado para codificar imagens de tamanhos variados em vision tokens com números correspondentes, em vez de um número fixo de tokens. Para entradas de vídeo, reduzimos o número de vision tokens de acordo com sua similaridade, de modo que a representação dos vídeos seja mais precisa e compacta. Beneficiando-se dos designs centrados na visão, o VideoLLaMA3 alcança desempenhos impressionantes em benchmarks de compreensão tanto de imagens quanto de vídeos.

VideoLLaMA3 architecture. Taken from the technical report.

Este modelo foi contribuído por lkhl.

Exemplo de uso

Inferência de mídia única

O modelo pode aceitar tanto imagens quanto vídeos como entrada. Aqui está um exemplo de código para inferência.

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)

Inferência em Lote de Mídia Mista

O modelo pode processar em lote entradas compostas por amostras mistas de vários tipos, como imagens, vídeos e texto. Aqui está um exemplo.

# 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 para acelerar a geração

Primeiro, certifique-se de instalar a versão mais recente do Flash Attention 2:

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

Além disso, você deve ter um hardware compatível com Flash-Attention 2. Leia mais sobre isso na documentação oficial do repositório flash attention. O FlashAttention-2 só pode ser usado quando um modelo é carregado em torch.float16 ou torch.bfloat16.

Para carregar e executar um modelo usando Flash Attention-2, basta adicionar attn_implementation="flash_attention_2" ao carregar o modelo, conforme mostrado a seguir:

from transformers import VideoLlama3ForConditionalGeneration

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

Transformers

VideoLLaMA3

Visão geral

Exemplo de uso

Inferência de mídia única

Inferência em Lote de Mídia Mista

Flash-Attention 2 para acelerar a geração

VideoLlama3Config

classe transformers.VideoLlama3Config

VideoLlama3VisionConfig

classe transformers.VideoLlama3VisionConfig

VideoLlama3ImageProcessor

classe transformers.VideoLlama3ImageProcessor

pré-processamento

VideoLlama3VideoProcessor

classe transformers.VideoLlama3VideoProcessor

pré-processamento

VideoLlama3ImageProcessorPil

classe transformers.VideoLlama3ImageProcessorPil

pré-processamento

VideoLlama3Processor

classe transformers.VideoLlama3Processor

__call__

VideoLlama3Model

classe transformers.VideoLlama3Model

forward

get_video_features

get_image_features

VideoLlama3VisionModel

classe transformers.VideoLlama3VisionModel

forward

VideoLlama3ForConditionalGeneration

classe transformers.VideoLlama3ForConditionalGeneration

forward

get_video_features

get_image_features

call