Transformers documentation

Idefics2

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年5月3日にHF papersで公開され、2024年4月15日にHugging Face Transformersに貢献されました。

Idefics2

概要

Idefics2モデルは、Léo Tronchon、Hugo Laurencon、Victor Sanh による論文 What matters when building vision-language models? で提案されました。関連するブログ記事はこちらでご覧いただけます。

Idefics2 は、画像とテキストの任意のシーケンスを受け取り、テキストを出力するオープンなマルチモーダルモデルです。このモデルは、画像に関する質問に答えたり、視覚的な内容を説明したり、複数の画像に基づいたストーリーを作成したり、視覚入力なしで純粋な言語モデルとして動作したりできます。Idefics2 は IDEFICS-1 を改善しており、特にドキュメント理解、OCR、視覚的推論において向上しています。Idefics2 は軽量（80億パラメータ）であり、画像をネイティブのアスペクト比と解像度で扱うため、推論効率を調整できます。

論文の抄録は以下の通りです。

ビジョン・ランゲージモデル（VLM）への関心が高まっている背景には、大規模言語モデルやビジョン・トランスフォーマーの進歩があります。この分野に関する文献は豊富ですが、VLMの設計に関する重要な判断が正当化されていないことが多いという問題が観察されます。これらの根拠のない判断は、どの選択がモデルの性能向上に寄与するかを特定しにくくするため、分野全体の進歩を妨げていると私たちは考えます。この問題に対処するため、事前学習済みモデル、アーキテクチャの選択、データ、および学習手法围绕して広範な実験を実施しました。これらの知見の統合として、80億パラメータの効率的な基盤VLMであるIdefics2を開発しました。Idefics2は、そのサイズカテゴリにおいて、さまざまなマルチモーダルベンチマークで最先端の性能を達成しており、4倍のサイズのモデルと同等の性能を発揮するケースも少なくありません。モデル（ベース、指示付き、チャット）と、その学習用に作成したデータセットを公開します。

Idefics2 architecture. Taken from the original paper.

このモデルはamyerobertsによって提供されました。元のコードはこちらで確認できます。

使用のコツ

各サンプルには複数の画像が含まれる場合があり、サンプル間で画像の数は変動します。プロセッサは、モデルへの入力として、バッチ内の最大画像数まで入力をパディングします。
プロセッサにはdo_image_splittingオプションがあります。Trueの場合、各入力画像は4つのサブ画像に分割され、元の画像と連結されて5つの画像が形成されます。これはモデルの性能向上に役立ちます。モデルがこのオプションなしで学習された場合は、processor.image_processor.do_image_splittingがFalseに設定されていることを確認してください。
プロセッサに渡すtextには、画像を挿入する位置に<image>トークンを含める必要があります。また、テキストがチャットメッセージの場合は、各発話の末尾に<end_of_utterance>を付与してください。
プロセッサには独自のapply_chat_templateメソッドがあり、チャットメッセージをテキストに変換できます。変換されたテキストは、プロセッサにtextとして渡すことができます。

チャットメッセージでプロセッサを使用する方法の例:

import requests
from PIL import Image

from transformers import Idefics2ForConditionalGeneration, Idefics2Processor


url_1 = "http://images.cocodataset.org/val2017/000000039769.jpg"
url_2 = "http://images.cocodataset.org/val2017/000000219578.jpg"

image_1 = Image.open(requests.get(url_1, stream=True).raw)
image_2 = Image.open(requests.get(url_2, stream=True).raw)
images = [image_1, image_2]

messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "What’s the difference between these two images?"},
        {"type": "image"},
        {"type": "image"},
    ],
}]

processor = Idefics2Processor.from_pretrained("HuggingFaceM4/idefics2-8b")
model = Idefics2ForConditionalGeneration.from_pretrained("HuggingFaceM4/idefics2-8b", device_map="auto")

# at inference time, one needs to pass `add_generation_prompt=True` in order to make sure the model completes the prompt
text = processor.apply_chat_template(messages, add_generation_prompt=True)
print(text)
# 'User: What’s the difference between these two images?<image><image><end_of_utterance>\nAssistant:'

inputs = processor(images=images, text=text, return_tensors="pt").to(model.device)

generated_text = model.generate(**inputs, max_new_tokens=500)
generated_text = processor.batch_decode(generated_text, skip_special_tokens=True)[0]
print("Generated text:", generated_text)

学習中、モデルが学習すべきでないトークンを特定することが重要です。Idefics2 の場合、これは通常、画像トークンとパディングトークンに限定されます。したがって、ラベルは次のように作成できます。

import requests
from PIL import Image

from transformers import Idefics2ForConditionalGeneration, Idefics2Processor


url_1 = "http://images.cocodataset.org/val2017/000000039769.jpg"
url_2 = "http://images.cocodataset.org/val2017/000000219578.jpg"

image_1 = Image.open(requests.get(url_1, stream=True).raw)
image_2 = Image.open(requests.get(url_2, stream=True).raw)
images = [image_1, image_2]

messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "What’s the difference between these two images?"},
        {"type": "image"},
        {"type": "image"},
    ],
},
{
    "role": "assistant",
    "content": [
        {"type": "text", "text": "The difference is that one image is about dogs and the other one about cats."},
    ],
}]


processor = Idefics2Processor.from_pretrained("HuggingFaceM4/idefics2-8b")
model = Idefics2ForConditionalGeneration.from_pretrained("HuggingFaceM4/idefics2-8b", device_map="auto")

text = processor.apply_chat_template(messages, add_generation_prompt=False)
inputs = processor(images=images, text=text, return_tensors="pt").to(model.device)

labels = inputs.input_ids.clone()
labels[labels == processor.tokenizer.pad_token_id] = -100
labels[labels == model.config.image_token_id] = -100

inputs["labels"] = labels

outputs = model(**inputs)
loss = outputs.loss
loss.backward()

Idefics2をユーザーとアシスタントのマルチターン会話で学習させる場合、通常はユーザーメッセージに対応するすべてのトークンも-100に設定します。

モデルの最適化: Flash Attention

上記のコードスニペットは、最適化テクニックを一切使わない推論を示しています。しかし、モデル内で使用されるアテンションメカニズムのより高速な実装であるFlash Attentionを活用することで、モデルを大幅に高速化できます。

まず、スライディングウィンドウアテンション機能を含む最新のFlash Attention 2をインストールしてください。

pip install -U flash-attn --no-build-isolation

Flash-Attention 2 と互換性のあるハードウェアを使用していることも確認してください。詳細については、flash attention リポジトリの公式ドキュメントを参照してください。また、モデルを半精度（例: torch.float16）で読み込むことも確認してください。

Flash Attention-2を使用してモデルを読み込み、実行するには、上記のコードスニペットを次のように変更するだけです。

model = Idefics2ForConditionalGeneration.from_pretrained(
    "HuggingFaceM4/idefics2-8b",
+    dtype=torch.float16,
+    attn_implementation="flash_attention_2",
    device_map="auto",
)

量子化による Idefics2 のサイズ縮小

Idefics2モデルは80億のパラメータを持つため、各パラメータが2バイトで保存される半精度（float16）では、GPU RAMに約16GB必要になります。ただし、量子化を用いることでモデルのサイズを縮小できます。モデルを4ビット（パラメータあたり半バイト）に量子化すると、必要なRAMは約3.5GBに抑えられます。

モデルの量子化は、モデルにquantization_configを渡すだけで簡単に実行できます。上記のコードスニペットを、以下の変更点で修正してください。ここではBitsAndyBytesによる量子化を利用しますが、他の量子化手法についてはこのページを参照してください。

+ from transformers import BitsAndBytesConfig

+ quantization_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_use_double_quant=True,
+    bnb_4bit_compute_dtype=torch.float16
+ )
model = Idefics2ForConditionalGeneration.from_pretrained(
    "HuggingFaceM4/idefics2-8b",
+    dtype=torch.float16,
+    quantization_config=quantization_config,
    device_map="auto",
)

リソース

Idefics2 の入門を支援するための、Hugging Face 公式およびコミュニティ（🌎 で示されています）のリソースのリストです。ここにリソースを掲載していただくことを希望される場合は、Pull Request を開いてください。レビューいたします。リソースは、既存のリソースと重複するのではなく、新しい内容をデモンストレーションするものが望ましいです。

Trainer を使用してカスタムデータセットで Idefics2 をファインチューニングする方法を示すノートブックは、こちらで確認できます。フルファインチューニングと（量子化された）LoRa の両方をサポートしています。
TRLライブラリを使用してIdefics2をファインチューニングする方法に関するスクリプトは、こちらで確認できます。
JSON抽出ユースケースにおけるIdefics2のファインチューニングに関するデモノートブックは、こちらで確認できます。🌎

Transformers

Idefics2

概要

使用のコツ

モデルの最適化: Flash Attention

量子化による Idefics2 のサイズ縮小

リソース

Idefics2Config

クラス transformers.Idefics2Config

Idefics2VisionConfig

クラス transformers.Idefics2VisionConfig

Idefics2PerceiverConfig

クラス transformers.Idefics2PerceiverConfig

Idefics2Model

クラス transformers.Idefics2Model

forward

get_image_features

Idefics2ForConditionalGeneration

クラス transformers.Idefics2ForConditionalGeneration

forward

get_image_features

Idefics2ImageProcessor

クラス transformers.Idefics2ImageProcessor

preprocess

Idefics2ImageProcessorPil

class transformers.Idefics2ImageProcessorPil

preprocess

Idefics2Processor

class transformers.Idefics2Processor

__call__

call