# 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](https://huggingface.co/papers/2408.03326)에서 제안했습니다.
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 아키텍처. 원 논문에서 가져왔습니다.
팁:
- 배치 생성을 계산할 때 `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](https://huggingface.co/llava-hf/llava-onevision-qwen2-7b-si-hf)와 텍스트 및 이미지 대화 기록을 사용합니다. 각 content 필드는 다음과 같이 dict의 리스트여야 합니다:
```python
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\nWhat 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](https://huggingface.co/RaushanTurganbay)님이 기여했습니다. 원본 코드는 [여기](https://github.com/LLaVA-VL/LLaVA-NeXT/tree/main)에서 찾을 수 있습니다.
## 사용 예시
### 단일 이미지 추론
다음은 모델을 로드하고 반정밀도(`torch.float16`)로 추론을 수행하는 방법입니다:
```python
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" 접미사가 있는 체크포인트를 사용해야 합니다. 다중 이미지 경우를 위해 입력으로 **이미지의 중첩 목록**을 사용하는 것을 권장합니다. 그렇지 않으면 모든 이미지가 패치화되어 많은 메모리를 차지하게 됩니다. 방법은 다음과 같습니다:
```python
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은 비디오를 입력으로 받아 추론을 수행할 수도 있으며, 이때 비디오 프레임은 여러 이미지로 처리됩니다. 방법은 다음과 같습니다:
```python
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에 예정되어 있습니다. 설치 방법 및 최신 백엔드 업데이트에 대해서는 [이 링크](https://huggingface.co/docs/bitsandbytes/main/en/installation#multi-backend)를 방문하세요.
정식 출시 전 버그를 식별하는 데 도움이 되는 여러분의 피드백을 소중히 생각합니다! 자세한 내용과 피드백 링크는 [이 문서](https://huggingface.co/docs/bitsandbytes/main/en/non_cuda_backends)를 확인하세요.
위 스니펫을 다음과 같이 변경하기만 하면 됩니다:
```python
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의 원본 저장소](https://github.com/Dao-AILab/flash-attention)를 참고하세요. 위의 스니펫을 다음과 같이 변경하세요:
```python
from transformers import LlavaOnevisionForConditionalGeneration
model = LlavaOnevisionForConditionalGeneration.from_pretrained(
model_id,
use_flash_attention_2=True
).to(0, device_map="auto")
```
## LlavaOnevisionConfig[[transformers.LlavaOnevisionConfig]]
#### transformers.LlavaOnevisionConfig[[transformers.LlavaOnevisionConfig]]
```python
transformers.LlavaOnevisionConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, image_token_index: int = 151646, video_token_index: int = 151647, projector_hidden_act: str = 'gelu', vision_feature_select_strategy: typing.Literal['default', 'full'] = 'full', vision_feature_layer: int | list[int] = -1, multimodal_projector_bias: bool = True, tie_word_embeddings: bool = False, image_grid_pinpoints: list | None = None, vision_aspect_ratio: str = 'anyres_max_9')
```
[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/llava_onevision/configuration_llava_onevision.py#L26)
**매개변수:**
vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 비전 백본의 config 객체 또는 사전 정의된 config 딕셔너리입니다.
text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 텍스트 백본의 config 객체 또는 사전입니다.
image_token_index (`int`, *선택 사항*, 기본값 `151646`) : 입력 이미지의 자리표시자로 사용되는 이미지 토큰 인덱스입니다.
video_token_index (`int`, *선택 사항*, 기본값 `151647`) : 입력 비디오의 플레이스홀더로 사용되는 비디오 토큰 인덱스입니다.
projector_hidden_act (`str`, *선택 사항*, 기본값 `gelu`) : 멀티모달 프로젝터에 사용되는 활성화 함수입니다.
vision_feature_select_strategy (`Literal[default, full]`, *선택 사항*, 기본값 `full`) : vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다.
vision_feature_layer (`Union[int, list[int]]`, *선택 사항*, 기본값 `-1`) : 시각 특징을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특징이 연결되어 시각 특징을 형성합니다.
multimodal_projector_bias (`bool`, *선택 사항*, 기본값 `True`) : 멀티모달 프로젝터에 bias를 사용할지 여부.
tie_word_embeddings (`bool`, *선택 사항*, 기본값 `False`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.
image_grid_pinpoints (`List`, *선택 사항*) : 고해상도 이미지 처리에 사용할 가능한 해상도의 목록입니다. 목록의 각 항목은 `(height, width)` 형태의 튜플 또는 리스트여야 합니다.
vision_aspect_ratio (`str`, *선택 사항*, 기본값 `"anyres_max_9"`) : 이미지 특징을 처리할 때 사용되는 종횡비입니다. 기본값은 "anyres_max_9"입니다.
이것은 LlavaOnevisionModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Llava Onevision 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [llava-hf/llava-onevision-qwen2-7b-ov-hf](https://huggingface.co/llava-hf/llava-onevision-qwen2-7b-ov-hf)와 유사한 구성이 생성됩니다.
Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.
예:
```python
>>> from transformers import LlavaOnevisionForConditionalGeneration, LlavaOnevisionConfig, SiglipVisionConfig, Qwen2Config
>>> # Initializing a CLIP-vision config
>>> vision_config = SiglipVisionConfig()
>>> # Initializing a Llama config
>>> text_config = Qwen2Config()
>>> # Initializing a Llava-Next llava-hf/llava-onevision-qwen2-7b-ov-hf style configuration
>>> configuration = LlavaOnevisionConfig(vision_config, text_config)
>>> # Initializing a model from the llava-hf/llava-onevision-qwen2-7b-ov-hf style configuration
>>> model = LlavaOnevisionForConditionalGeneration(configuration)
>>> # Accessing the model configuration
>>> configuration = model.config
```
## LlavaOnevisionProcessor[[transformers.LlavaOnevisionProcessor]]
#### transformers.LlavaOnevisionProcessor[[transformers.LlavaOnevisionProcessor]]
```python
transformers.LlavaOnevisionProcessor(image_processor = None, tokenizer = None, video_processor = None, num_image_tokens = None, vision_feature_select_strategy = None, chat_template = None, image_token = '', video_token = '