# 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 は、1 つ以上の画像/動画に条件付けられてテキストを生成できる Vision-Language Model です。このモデルは、SigLIP ビジョンエンコーダーと Qwen2 言語バックボーンで構成されています。画像は anyres-9 技術で処理され、9 つのパッチに分割されることで、高解像度画像をより適切に処理し、可能な限り多くの詳細を捉えます。一方、動画は、よりメモリ効率の高い計算のために、各フレームが合計 196 トークンのシーケンス長にプーリングされます。LLaVA-OneVision は 0.5B、7B、72B の 3 つのサイズで提供され、ベンチマーク評価において優れたパフォーマンスを達成しています。
論文の抄録は以下の通りです。
*LLaVA-NeXTブログシリーズで得られたデータ、モデル、視覚表現に関する知見を統合し、オープンな大規模マルチモーダルモデル（LMM）のファミリーであるLLaVA-OneVisionを提示します。実験結果により、LLaVA-OneVisionは、単一画像、複数画像、動画という3つの重要なコンピュータビジョンシナリオにおいて、オープンLMMの性能の限界を同時に押し広げられる初の単一モデルであることが示されました。特に重要なのは、LLaVA-OneVisionの設計により、異なるモダリティ/シナリオ間で強力な転移学習が可能となり、新たな創発的能力が得られる点です。具体的には、画像から動画へのタスク転移を通じて、強力な動画理解とシナリオ横断能力が実証されています。*
LLaVA-OneVisionのアーキテクチャ。元の論文より引用。
ヒント:
- バッチ生成を計算する際は、より正確な結果が得られるため、`padding_side="left"`の使用を推奨します。生成を行う前に、`processor.tokenizer.padding_side = "left"`を呼び出すことを確認してください。
- Llava-OneVision は画像に対して異なる数のパッチを使用するため、入力の処理時に実行されるパディングとは別に、モデリングコード内で入力をパディングする必要があります。デフォルトの設定は、モデルが `eval()` モードにある場合は "left-padding"、それ以外の場合は "right-padding" です。
### Chat テンプレートによるプロンプトの整形
各**チェックポイント**は、基盤となる大規模言語モデルのバックボーンに応じて、特定のプロンプト形式で学習されています。正しい形式を確保するために、プロセッサの`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/アクセラレータにアクセスできることを確認してください。
bitsandbytes は、CUDA 以外の複数のバックエンドをサポートするためにリファクタリングされています。現在、ROCm (AMD GPU) と Intel CPU の実装は成熟しており、Intel XPU は進行中、Apple Silicon のサポートは第4四半期/第1四半期に提供される予定です。インストール手順や最新のバックエンド更新については、[このリンク](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/main/src/transformers/models/llava_onevision/configuration_llava_onevision.py#L26)
**パラメータ:**
vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : ビジョンバックボーンの 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_feature_layer (`Union[int, list[int]]`、*任意*、デフォルトは`-1`) : 視覚特徴を選択するレイヤーのインデックスです。複数のインデックスが指定された場合、対応するインデックスの視覚特徴が連結されて視覚特徴が形成されます。
multimodal_projector_bias (`bool`、*任意*、デフォルトは`True`) : マルチモーダルプロジェクターでバイアスを使用するかどうか。
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)と類似した設定が得られます。
設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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 = '