Transformers documentation

Qwen2-VL

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年9月18日にHF papersで公開され、2024年8月26日にHugging Face Transformersに貢献されました。

Qwen2-VL

概要

Qwen2-VL（ブログ記事）モデルは、Alibaba Research の Qwen チームによる Qwen-VL の大幅なアップデートです。

ブログからの概要は以下の通りです。

本ブログでは、Qwen-VL モデルの高度なバージョンである Qwen2-VL を紹介します。Qwen2-VL は、過去 1 年間にわたり大幅な強化が施されてきました。主な改善点としては、画像理解能力の向上、高度な動画理解、統合されたビジュアルエージェント機能、そして多言語サポートの拡大が挙げられます。モデルアーキテクチャは、Naive Dynamic Resolution による任意の画像解像度への対応が最適化されており、1 次元のテキストデータと多次元の視覚データを効果的に処理するために、Multimodal Rotary Position Embedding (M-ROPE) を利用しています。この更新されたモデルは、GPT-4o や Claude 3.5 Sonnet などの主要な AI システムと比較して、ビジョン関連タスクで競争力のあるパフォーマンスを示しており、テキスト能力においてもオープンソースモデルの中で上位にランクインしています。これらの進歩により、Qwen2-VL は、堅牢なマルチモーダル処理と推論能力を必要とする多様なアプリケーションにおいて、多用途なツールとして機能します。

Qwen2-VL architecture. Taken from the blog post.

このモデルは simonJJJ によって提供されました。

使用例

単一メディア推論

モデルは画像と動画の両方を入力として受け取れます。推論のコード例を以下に示します。

from transformers import AutoProcessor, Qwen2VLForConditionalGeneration


# Load the model in half-precision on the available device(s)
model = Qwen2VLForConditionalGeneration.from_pretrained("Qwen/Qwen2-VL-7B-Instruct", device_map="auto")
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct")


conversation = [
    {
        "role":"user",
        "content":[
            {
                "type":"image",
                "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/qwen_vl_demo.jpeg"
            },
            {
                "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", "path": "/path/to/video.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)

バッチ混在メディア推論

モデルは、画像、動画、テキストなど、さまざまなタイプのサンプルが混在した入力をバッチ処理できます。以下に例を示します。


# Conversation for the first image
conversation1 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "path": "/path/to/image1.jpg"},
            {"type": "text", "text": "Describe this image."}
        ]
    }
]

# Conversation with two images
conversation2 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "path": "/path/to/image2.jpg"},
            {"type": "image", "path": "/path/to/image3.jpg"},
            {"type": "text", "text": "What is written in the pictures?"}
        ]
    }
]

# Conversation with pure text
conversation3 = [
    {
        "role": "user",
        "content": "who are you?"
    }
]


# Conversation with mixed media
conversation4 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "path": "/path/to/image3.jpg"},
            {"type": "image", "path": "/path/to/image4.jpg"},
            {"type": "video", "path": "/path/to/video.jpg"},
            {"type": "text", "text": "What are the common elements in these media?"},
        ],
    }
]

conversations = [conversation1, conversation2, conversation3, conversation4]
# Preparation for batch inference
inputs = processor.apply_chat_template(
    conversations,
    fps=1,
    add_generation_prompt=True,
    tokenize=True,
    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)

使用のコツ

画像解像度のトレードオフ

このモデルは幅広い解像度の入力をサポートしています。デフォルトでは、入力にネイティブ解像度を使用しますが、より高い解像度を使用することで、計算コストの増加を代償にパフォーマンスを向上させることができます。ユーザーは、最小ピクセル数と最大ピクセル数を設定することで、ニーズに最適な構成を実現できます。

min_pixels = 224*224
max_pixels = 2048*2048
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct", min_pixels=min_pixels, max_pixels=max_pixels)

GPU RAMが限られている場合、次のように解像度を下げることができます。

min_pixels = 256*28*28
max_pixels = 1024*28*28
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct", min_pixels=min_pixels, max_pixels=max_pixels)

これにより、各画像が256〜1024トークンの範囲の数値でエンコードされることが保証されます。28という値は、モデルがパッチサイズ14と時間方向のパッチサイズ2を使用していることから導かれます（14 x 2 = 28）。

複数の画像入力

デフォルトでは、画像や動画コンテンツは会話に直接含まれます。複数の画像を扱う場合、参照しやすくするために画像や動画にラベルを追加すると便利です。ユーザーは以下の設定でこの動作を制御できます。

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "Hello, how are you?"}
        ]
    },
    {
        "role": "assistant",
        "content": "I'm doing well, thank you for asking. How can I assist you today?"
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Can you describe these images and video?"},
            {"type": "image"},
            {"type": "image"},
            {"type": "video"},
            {"type": "text", "text": "These are from my vacation."}
        ]
    },
    {
        "role": "assistant",
        "content": "I'd be happy to describe the images and video for you. Could you please provide more context about your vacation?"
    },
    {
        "role": "user",
        "content": "It was a trip to the mountains. Can you see the details in the images and video?"
    }
]

# default:
prompt_without_id = processor.apply_chat_template(conversation, add_generation_prompt=True)
# Excepted output: '<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n<|im_start|>user\n<|vision_start|><|image_pad|><|vision_end|>Hello, how are you?<|im_end|>\n<|im_start|>assistant\nI'm doing well, thank you for asking. How can I assist you today?<|im_end|>\n<|im_start|>user\nCan you describe these images and video?<|vision_start|><|image_pad|><|vision_end|><|vision_start|><|image_pad|><|vision_end|><|vision_start|><|video_pad|><|vision_end|>These are from my vacation.<|im_end|>\n<|im_start|>assistant\nI'd be happy to describe the images and video for you. Could you please provide more context about your vacation?<|im_end|>\n<|im_start|>user\nIt was a trip to the mountains. Can you see the details in the images and video?<|im_end|>\n<|im_start|>assistant\n'


# add ids
prompt_with_id = processor.apply_chat_template(conversation, add_generation_prompt=True, add_vision_id=True)
# Excepted output: '<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n<|im_start|>user\nPicture 1: <|vision_start|><|image_pad|><|vision_end|>Hello, how are you?<|im_end|>\n<|im_start|>assistant\nI'm doing well, thank you for asking. How can I assist you today?<|im_end|>\n<|im_start|>user\nCan you describe these images and video?Picture 2: <|vision_start|><|image_pad|><|vision_end|>Picture 3: <|vision_start|><|image_pad|><|vision_end|>Video 1: <|vision_start|><|video_pad|><|vision_end|>These are from my vacation.<|im_end|>\n<|im_start|>assistant\nI'd be happy to describe the images and video for you. Could you please provide more context about your vacation?<|im_end|>\n<|im_start|>user\nIt was a trip to the mountains. Can you see the details in the images and video?<|im_end|>\n<|im_start|>assistant\n'

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 Qwen2VLForConditionalGeneration

model = Qwen2VLForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2-VL-7B-Instruct", 
    attn_implementation="flash_attention_2",
 device_map="auto")

Transformers

Qwen2-VL

概要

使用例

単一メディア推論

バッチ混在メディア推論

使用のコツ

画像解像度のトレードオフ

複数の画像入力

Flash-Attention 2 を使用して生成を高速化

Qwen2VLConfig

クラス transformers.Qwen2VLConfig

Qwen2VLVisionConfig

クラス transformers.Qwen2VLVisionConfig

Qwen2VLTextConfig

クラス transformers.Qwen2VLTextConfig

Qwen2VLImageProcessor

クラス transformers.Qwen2VLImageProcessor

preprocess

Qwen2VLVideoProcessor

class transformers.Qwen2VLVideoProcessor

preprocess

Qwen2VLImageProcessorPil

class transformers.Qwen2VLImageProcessorPil

preprocess

Qwen2VLProcessor

class transformers.Qwen2VLProcessor

__call__

Qwen2VLTextModel

クラス transformers.Qwen2VLTextModel

forward

Qwen2VLModel

class transformers.Qwen2VLModel

forward

get_video_features

get_image_features

Qwen2VLForConditionalGeneration

クラス transformers.Qwen2VLForConditionalGeneration

forward

get_video_features

get_image_features

call