Transformers documentation

LLaVA-OneVision

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

이 모델은 2024-08-06에 HF papers에 게시되었으며, 2024-09-05에 Hugging Face Transformers에 기여되었습니다.

LLaVA-OneVision

개요

LLaVA-OneVision 모델은 Bo Li, Yuanhan Zhang, Dong Guo, Renrui Zhang, Feng Li, Hao Zhang, Kaichen Zhang, Yanwei Li, Ziwei Liu, Chunyuan Li가 LLaVA-OneVision: Easy Visual Task Transfer에서 제안했습니다.

LLaVA-OneVision은 하나 이상의 이미지/비디오를 조건으로 텍스트를 생성할 수 있는 Vision-Language Model입니다. 이 모델은 SigLIP vision encoder와 Qwen2 language backbone으로 구성됩니다. 이미지는 anyres-9 기법을 사용하여 처리되며, 이는 이미지를 9개의 패치로 분할하여 고해상도 이미지를 더 잘 처리하고 가능한 한 많은 세부 정보를 포착하도록 합니다. 반면, 비디오는 각 프레임당 총 196개의 토큰 길이에 풀링(pooled)되어 더 메모리 효율적인 계산을 수행합니다. LLaVA-OneVision은 0.5B, 7B, 72B의 세 가지 크기로 제공되며, 벤치마크 평가에서 뛰어난 성능을 달성합니다.

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

LLaVA-NeXT 블로그 시리즈에서 데이터, 모델, 시각 표현에 대한 통찰을 통합하여 개발한 오픈 대형 멀티모달 모델(LMM) 계열인 LLaVA-OneVision을 소개합니다. 실험 결과에 따르면 LLaVA-OneVision은 단일 이미지, 다중 이미지, 비디오라는 세 가지 중요한 컴퓨터 비전 시나리오에서 오픈 LMM의 성능 한계를 동시에 확장할 수 있는 최초의 단일 모델입니다. 특히 LLaVA-OneVision의 설계는 다양한 모달리티/시나리오 간에 강력한 전이 학습을 가능하게 하여 새로운 신흥 역량을 제공합니다. 구체적으로, 이미지에서 비디오로의 작업 전이를 통해 강력한 비디오 이해 및 시나리오 간 역량이 입증되었습니다.

LLaVA-OneVision architecture. Taken from the original paper.

팁:

배치 생성을 계산할 때 padding_side="left"를 사용하도록 권장합니다. 더 정확한 결과를 얻을 수 있기 때문입니다. 생성 전에 processor.tokenizer.padding_side = "left"를 호출하도록 하세요.

Llava-OneVision은 이미지마다 패치의 수가 다르기 때문에, 입력 처리 시 수행되는 패딩과 별개로 모델링 코드 내에서 입력을 패딩해야 합니다. 기본 설정은 모델이 eval() 모드에 있을 때 “left-padding”, 그 외에는 “right-padding”입니다.

Chat Templates를 사용하여 프롬프트 형식 지정

각 checkpoint는 기반이 되는 large language model backbone에 따라 특정 prompt 형식으로 학습됩니다. 올바른 형식을 보장하려면 processor의 apply_chat_template 메서드를 사용하세요.

중요:

대화 히스토리를 구성해야 합니다. 일반 문자열만 전달하면 작동하지 않습니다.
각 메시지는 "role"와 "content" 키를 가진 딕셔너리여야 합니다.
"content"은 "text"와 "image"와 같은 다양한 모달리티에 대한 사전 목록이어야 합니다.

입력 구조를 구성하는 예시를 보여 드리겠습니다. llava-onevision-qwen2-7b-si-hf와 텍스트 및 이미지로 이루어진 대화 히스토리를 사용합니다. 각 content 필드는 다음과 같이 dict의 리스트여야 합니다:

from transformers import AutoProcessor


processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-si-hf")

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "What’s shown in this image?"},
        ],
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "This image shows a red stop sign."},]
    },
    {

        "role": "user",
        "content": [
            {"type": "text", "text": "Describe the image in more details."},
        ],
    },
]

text_prompt = processor.apply_chat_template(conversation, add_generation_prompt=True)

# Note that the template simply formats your prompt, you still have to tokenize it and obtain pixel values for your images
print(text_prompt)
'<|im_start|>user\n<image>What is shown in this image?<|im_end|>\n<|im_start|>assistant\nPage showing the list of options.<|im_end|>'

🚀 보너스: transformers>=4.49.0를 사용 중이라면 apply_chat_template에서 벡터화된 출력도 얻을 수 있습니다. 사용 방법에 대한 자세한 내용은 아래 사용 예시를 참고하세요.

이 모델은 RaushanTurganbay님이 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.

사용 예시

단일 이미지 추론

다음은 모델을 로드하고 반정밀도(torch.float16)로 추론을 수행하는 방법입니다:

import torch

from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration


processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf")
model = LlavaOnevisionForConditionalGeneration.from_pretrained(
    "llava-hf/llava-onevision-qwen2-7b-ov-hf",
    device_map="auto"
)

# prepare image and text prompt, using the appropriate prompt template
url = "https://github.com/haotian-liu/LLaVA/blob/1a91fc274d7c35a9b50b3cb29c4247ae5837ce39/images/llava_v1_5_radar.jpg?raw=true"
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": url},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
]
inputs = processor.apply_chat_template(conversation, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(model.device)
inputs = inputs.to(model.device, torch.float16)

# autoregressively complete prompt
output = model.generate(**inputs, max_new_tokens=100)
print(processor.decode(output[0], skip_special_tokens=True))
'user\n\nWhat is shown in this image?\nassistant\nThe image shows a radar chart, also known as a spider chart or a star chart, which is used to compare multiple quantitative variables. Each axis represents a different variable, and the chart is filled with'

멀티 이미지 추론

LLaVa-OneVision은 여러 이미지를 입력으로 받아 추론을 수행할 수 있으며, 이때 이미지는 동일한 프롬프트에 속하거나 서로 다른 프롬프트에 속할 수 있습니다(배치 추론). 이를 위해 "ov" 접미사가 있는 체크포인트를 사용해야 합니다. 다중 이미지 경우를 위해 입력으로 이미지의 중첩 리스트 사용을 권장합니다. 그렇지 않으면 모든 이미지가 패치화되어 많은 메모리를 차지하게 됩니다. 방법은 다음과 같습니다:

import torch

from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration


# Load the model in half-precision
model = LlavaOnevisionForConditionalGeneration.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf", device_map="auto")
processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf")

# Prepare a batch of two prompts, where the first one is a multi-turn conversation and the second is not
conversation_1 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://www.ilankelman.org/stopsigns/australia.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "There is a red stop sign in the image."},
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
            {"type": "text", "text": "What about this image? How many cats do you see?"},
        ],
    },
]

conversation_2 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/microsoft/kosmos-2-patch14-224/resolve/main/snowman.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
]

inputs = processor.apply_chat_template(
    [conversation_1, conversation_2],
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    padding=True,
    padding_side="left",
    return_tensors="pt",
).to(model.device, torch.float16)

# Generate
generate_ids = model.generate(**inputs, max_new_tokens=30)
processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)
['user\n\nWhat is shown in this image?\nassistant\nThere is a red stop sign in the image.\nuser\n\nWhat about this image? How many cats do you see?\nassistant\ntwo', 'user\n\nWhat is shown in this image?\nassistant\nThe image shows a whimsical scene of a snowman sitting by a campfire. The snowman is anthropomorphized, wearing a hat and']

비디오 추론

LLaVa-OneVision은 비디오를 입력으로 받아 추론을 수행할 수도 있으며, 이때 비디오 프레임은 여러 이미지로 처리됩니다. 방법은 다음과 같습니다:

from huggingface_hub import hf_hub_download
import torch
from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration

# Load the model in half-precision
model = LlavaOnevisionForConditionalGeneration.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf", device_map="auto")
processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf")

video_path = hf_hub_download(repo_id="raushan-testing-hf/videos-test", filename="sample_demo_1.mp4", repo_type="dataset")
conversation = [
    {

        "role": "user",
        "content": [
            {"type": "video", "path": video_path},
            {"type": "text", "text": "Why is this video funny?"},
            ],
    },
]

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

out = model.generate(**inputs, max_new_tokens=60)
processor.batch_decode(out, skip_special_tokens=True, clean_up_tokenization_spaces=True)
["user\n\nWhy is this video funny?\nassistant\nThe video appears to be humorous because it shows a young child, who is wearing glasses and holding a book, seemingly reading with a serious and focused expression. The child's glasses are a bit oversized for their face, which adds a comical touch, as it's a common trope to see children wearing"]

모델 최적화

bitsandbytes를 사용한 양자화

모델은 8비트 또는 4비트로 로드할 수 있으며, 이는 원래 모델의 성능을 유지하면서 메모리 요구 사항을 크게 줄여 줍니다. 먼저 pip install bitsandbytes을 실행하여 bitsandbytes를 설치하고, 해당 라이브러리가 지원하는 GPU/accelerator에 접근할 수 있는지 확인하세요.

bitsandbytes는 CUDA를 넘어 여러 백엔드를 지원하도록 리팩터링되고 있습니다. 현재 ROCm(AMD GPU)과 Intel CPU 구현이 성숙했으며, Intel XPU는 진행 중이고 Apple Silicon 지원은 Q4/Q1에 예정되어 있습니다. 설치 방법 및 최신 백엔드 업데이트에 대해서는 이 링크를 방문하세요.

정식 출시 전 버그를 식별하는 데 도움이 되는 여러분의 피드백을 소중히 생각합니다! 자세한 내용과 피드백 링크는 이 문서를 확인하세요.

위 스니펫을 다음과 같이 변경하기만 하면 됩니다:

from transformers import BitsAndBytesConfig, LlavaOnevisionForConditionalGeneration


# specify how to quantize the model
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
)

model = LlavaOnevisionForConditionalGeneration.from_pretrained(model_id, quantization_config=quantization_config, device_map="auto")

Flash-Attention 2를 사용하여 생성 속도를 더 빠르게 만듭니다

먼저 flash-attn을 설치했는지 확인하세요. 해당 패키지의 설치 방법은 Flash Attention의 원본 저장소를 참고하세요. 위의 스니펫을 다음과 같이 변경하세요:

from transformers import LlavaOnevisionForConditionalGeneration


model = LlavaOnevisionForConditionalGeneration.from_pretrained(
    model_id,
    use_flash_attention_2=True
).to(0, device_map="auto")

Transformers

LLaVA-OneVision

개요

Chat Templates를 사용하여 프롬프트 형식 지정

사용 예시

단일 이미지 추론

멀티 이미지 추론

비디오 추론

모델 최적화

bitsandbytes를 사용한 양자화

Flash-Attention 2를 사용하여 생성 속도를 더 빠르게 만듭니다

LlavaOnevisionConfig

클래스 transformers.LlavaOnevisionConfig

LlavaOnevisionProcessor

class transformers.LlavaOnevisionProcessor

__call__

LlavaOnevisionImageProcessor

class transformers.LlavaOnevisionImageProcessor

preprocess

LlavaOnevisionImageProcessorPil

class transformers.LlavaOnevisionImageProcessorPil

preprocess

LlavaOnevisionVideoProcessor

클래스 transformers.LlavaOnevisionVideoProcessor

LlavaOnevisionModel

클래스 transformers.LlavaOnevisionModel

forward

get_image_features

get_placeholder_mask

get_video_features

pack_image_features

LlavaOnevisionForConditionalGeneration

클래스 transformers.LlavaOnevisionForConditionalGeneration

forward

get_image_features

get_video_features

call