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

이 모델은 2025-01-22에 HF papers에 게시되었으며, 2025-10-13에 Hugging Face Transformers에 기여되었습니다.

VideoLLaMA3

개요

VideoLLaMA3 모델은 Alibaba DAMO Academy의 VideoLLaMA2에 대한 주요 업데이트입니다.

해당 논문의 초록은 다음과 같습니다:

본 논문에서는 이미지와 영상 이해를 위한 보다 발전된 멀티모달 파운데이션 모델인 VideoLLaMA 3를 제안합니다. VideoLLaMA3의 핵심 설계 철학은 비전 중심(vision-centric)입니다. “비전 중심”의 의미는 두 가지 측면으로 나뉩니다: 비전 중심 학습 패러다임과 비전 중심 프레임워크 설계입니다. 우리의 비전 중심 학습 패러다임의 핵심 통찰은 고품질 이미지-텍스트 데이터가 이미지 이해와 영상 이해 모두에 필수적이라는 것입니다. 대량의 영상-텍스트 데이터셋을 준비하는 대신, 우리는 대규모 고품질 이미지-텍스트 데이터셋 구축에 집중합니다. VideoLLaMA3에는 네 가지 학습 단계가 있습니다: 1) 가변 해상도의 이미지를 입력으로 받을 수 있도록 비전 인코더를 적응시키는 Vision Encoder Adaptation, 2) 다양한 유형(장면 이미지, 문서, 차트 포함)의 대규모 이미지-텍스트 데이터와 텍스트 전용 데이터를 사용하여 비전 인코더, 프로젝터, LLM을 함께 튜닝하는 Vision-Language Alignment, 3) 다운스트림 작업을 위한 이미지-텍스트 SFT 데이터와 영상-텍스트 데이터를 포함하여 영상 이해의 기반을 마련하는 Multi-task Fine-tuning, 4) 모델의 영상 이해 능력을 한층 더 향상시키는 Video-centric Fine-tuning입니다. 프레임워크 설계와 관련하여, 이미지 내의 세밀한 디테일을 더 잘 포착하기 위해 사전 학습된 비전 인코더를 고정된 수의 토큰이 아닌, 이미지 크기에 해당하는 수의 비전 토큰으로 다양한 크기의 이미지를 인코딩하도록 적응시켰습니다. 영상 입력의 경우, 유사도에 따라 비전 토큰의 수를 줄여 영상 표현이 더 정확하고 간결하도록 했습니다. 이러한 비전 중심 설계의 이점으로, 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

class transformers.VideoLlama3ImageProcessorPil

preprocess

VideoLlama3Processor

클래스 transformers.VideoLlama3Processor

__call__

VideoLlama3Model

class transformers.VideoLlama3Model

forward

get_video_features

get_image_features

VideoLlama3VisionModel

클래스 transformers.VideoLlama3VisionModel

forward

VideoLlama3ForConditionalGeneration

클래스 transformers.VideoLlama3ForConditionalGeneration

forward

get_video_features

get_image_features

call