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年8月6日にHF papersで公開され、2024年9月5日に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 は、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 architecture. Taken from the original paper.

ヒント:

バッチ生成を計算する際は、より正確な結果が得られるため、padding_side="left"の使用を推奨します。生成を行う前に、processor.tokenizer.padding_side = "left"を呼び出すことを確認してください。

Llava-OneVision は画像に対して異なる数のパッチを使用するため、入力の処理時に実行されるパディングとは別に、モデリングコード内で入力をパディングする必要があります。デフォルトの設定は、モデルが eval() モードにある場合は「左パディング」、それ以外の場合は「右パディング」です。

Chat テンプレートによるプロンプトの整形

各チェックポイントは、基盤となる大規模言語モデルのバックボーンに応じて、特定のプロンプト形式で学習されています。正しい形式を確保するために、プロセッサの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/アクセラレータにアクセスできることを確認してください。

bitsandbytes は、CUDA 以外の複数のバックエンドをサポートするためにリファクタリングされています。現在、ROCm (AMD GPU) と Intel CPU の実装は成熟しており、Intel XPU は進行中、Apple Silicon のサポートは第4四半期/第1四半期に提供される予定です。インストール手順や最新のバックエンド更新については、このリンクをご覧ください。

正式リリース前にバグを特定するために、フィードバックを大切にしています!詳細とフィードバックのリンクについては、これらのドキュメントをご覧ください。

上記のスニペットを以下に変更するだけです:

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 テンプレートによるプロンプトの整形

使用例

単一画像の推論

複数画像の推論

動画推論

モデルの最適化

bitsandbytes を使用した量子化

Flash-Attention 2 を使用して、生成をさらに高速化します

LlavaOnevisionConfig

クラス transformers.LlavaOnevisionConfig

LlavaOnevisionProcessor

class transformers.LlavaOnevisionProcessor

__call__

LlavaOnevisionImageProcessor

class transformers.LlavaOnevisionImageProcessor

preprocess

LlavaOnevisionImageProcessorPil

クラス transformers.LlavaOnevisionImageProcessorPil

preprocess

LlavaOnevisionVideoProcessor

class 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