生成と調整の例については、Gemma クックブックリポジトリをご覧ください。詳細

このページは Cloud Translation API によって翻訳されました。

Hugging Face Transformers と QLoRA を使用して Gemma をファインチューニングしてビジョンタスクを実行する

このガイドでは、Hugging Face の Transformers と TRL を使用して、ビジョンタスク（商品説明の生成）用のカスタム画像とテキストデータセットで Gemma をファインチューニングする方法について説明します。学習内容:

量子化低ランク適応（QLoRA）とは
開発環境を設定する
ビジョンタスク用のファインチューニングデータセットを作成して準備する
TRL と SFTTrainer を使用して Gemma をファインチューニングする
モデル推論をテストし、画像とテキストから商品説明を生成します。

量子化低ランク適応（QLoRA）とは

このガイドでは、Quantized Low-Rank Adaptation（QLoRA）の使用方法について説明します。QLoRA は、高いパフォーマンスを維持しながら計算リソースの要件を削減できるため、LLM を効率的にファインチューニングするための一般的な方法として登場しました。QloRA では、事前トレーニング済みモデルは 4 ビットに量子化され、重みは固定されます。次に、トレーニング可能なアダプタレイヤ（LoRA）が接続され、アダプタレイヤのみがトレーニングされます。その後、アダプタの重みはベースモデルと統合することも、別個のアダプタとして保持することもできます。

開発環境を設定する

まず、TRL などの Hugging Face ライブラリと、オープンモデルを微調整するためのデータセットをインストールします。

# Install Pytorch & other libraries
%pip install "torch>=2.4.0" tensorboard torchvision

# Install Gemma release branch from Hugging Face
%pip install git+https://github.com/huggingface/transformers@v4.49.0-Gemma-3

# Install Hugging Face libraries
%pip install  --upgrade \
  "datasets==3.3.2" \
  "accelerate==1.4.0" \
  "evaluate==0.4.3" \
  "bitsandbytes==0.45.3" \
  "trl==0.15.2" \
  "peft==0.14.0" \
  "pillow==11.1.0" \
  protobuf \
  sentencepiece

トレーニングを開始する前に、Gemma の利用規約に同意する必要があります。Hugging Face でライセンスに同意するには、モデルページ（http://huggingface.co/google/gemma-3-4b-pt）で [Agree and access repository] ボタンをクリックします（または、使用しているビジョン対応の Gemma モデルの適切なモデルページ）。

ライセンスを承認した後、モデルにアクセスするには有効な Hugging Face トークンが必要です。Google Colab 内で実行している場合は、Colab シークレットを使用して Hugging Face トークンを安全に使用できます。それ以外の場合は、login メソッドでトークンを直接設定できます。トレーニング中にモデルを Hub に push するため、トークンに書き込みアクセス権があることを確認してください。

from google.colab import userdata
from huggingface_hub import login

# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)

ファインチューニングデータセットを作成して準備する

LLM をファインチューニングする際は、ユースケースと解決するタスクを把握することが重要です。これにより、モデルを微調整するためのデータセットを作成できます。ユースケースをまだ定義していない場合は、最初からやり直すことをおすすめします。

このガイドでは、次のユースケースを例に説明します。

Gemma モデルをファインチューニングして、モバイル検索向けにカスタマイズされた、e コマースプラットフォーム向けの簡潔で SEO 最適化された商品説明を生成します。

このガイドでは、philschmid/amazon-product-descriptions-vlm データセットを使用します。これは、商品画像やカテゴリを含む Amazon 商品説明のデータセットです。

Hugging Face TRL はマルチモーダル会話をサポートしています。重要なのは「image」ロールです。これは、画像を読み込む必要があることを処理クラスに指示します。構造は次のようになります。

{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}

これで、Hugging Face Datasets ライブラリを使用してデータセットを読み込み、プロンプトテンプレートを作成して画像、商品名、カテゴリを組み合わせ、システムメッセージを追加できます。データセットには、画像が Pil.Image オブジェクトとして含まれています。

from datasets import load_dataset
from PIL import Image

# System message for the assistant
system_message = "You are an expert product description writer for Amazon."

# User prompt that combines the user query and the schema
user_prompt = """Create a Short Product description based on the provided <PRODUCT> and <CATEGORY> and image.
Only return description. The description should be SEO optimized and for a better mobile search experience.

<PRODUCT>
{product}
</PRODUCT>

<CATEGORY>
{category}
</CATEGORY>
"""

# Convert dataset to OAI messages
def format_data(sample):
    return {
        "messages": [
            {
                "role": "system",
                "content": [{"type": "text", "text": system_message}],
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": user_prompt.format(
                            product=sample["Product Name"],
                            category=sample["Category"],
                        ),
                    },
                    {
                        "type": "image",
                        "image": sample["image"],
                    },
                ],
            },
            {
                "role": "assistant",
                "content": [{"type": "text", "text": sample["description"]}],
            },
        ],
    }

def process_vision_info(messages: list[dict]) -> list[Image.Image]:
    image_inputs = []
    # Iterate through each conversation
    for msg in messages:
        # Get content (ensure it's a list)
        content = msg.get("content", [])
        if not isinstance(content, list):
            content = [content]

        # Check each content element for images
        for element in content:
            if isinstance(element, dict) and (
                "image" in element or element.get("type") == "image"
            ):
                # Get the image and convert to RGB
                if "image" in element:
                    image = element["image"]
                else:
                    image = element
                image_inputs.append(image.convert("RGB"))
    return image_inputs

# Load dataset from the hub
dataset = load_dataset("philschmid/amazon-product-descriptions-vlm", split="train")

# Convert dataset to OAI messages
# need to use list comprehension to keep Pil.Image type, .mape convert image to bytes
dataset = [format_data(sample) for sample in dataset]

print(dataset[345]["messages"])

TRL と SFTTrainer を使用して Gemma をファインチューニングする

これで、モデルをファインチューニングする準備が整いました。Hugging Face TRL の SFTTrainer を使用すると、オープン LLM を教師ありでファインチューニングできます。SFTTrainer は transformers ライブラリの Trainer のサブクラスであり、ロギング、評価、チェックポイントなど、同じ機能をすべてサポートしていますが、次のような QOL 機能も追加されています。

データセットのフォーマット（会話形式や指示形式など）
完了のみをトレーニングし、プロンプトを無視する
データセットを圧縮してトレーニングを効率化する
QloRA を含むパラメータエフィシエントファインチューニング（PEFT）のサポート
会話のファインチューニング用のモデルとトークン化ツールの準備（特殊トークンの追加など）

次のコードは、Hugging Face から Gemma モデルとトークン化ツールを読み込み、量子化構成を初期化します。

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig

# Hugging Face model id
model_id = "google/gemma-3-4b-pt" # or `google/gemma-3-12b-pt`, `google/gemma-3-27-pt`

# Check if GPU benefits from bfloat16
if torch.cuda.get_device_capability()[0] < 8:
    raise ValueError("GPU does not support bfloat16, please use a GPU that supports bfloat16.")

# Define model init arguments
model_kwargs = dict(
    attn_implementation="eager", # Use "flash_attention_2" when running on Ampere or newer GPU
    torch_dtype=torch.bfloat16, # What torch dtype to use, defaults to auto
    device_map="auto", # Let torch decide how to load the model
)

# BitsAndBytesConfig int-4 config
model_kwargs["quantization_config"] = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=model_kwargs["torch_dtype"],
    bnb_4bit_quant_storage=model_kwargs["torch_dtype"],
)

# Load model and tokenizer
model = AutoModelForImageTextToText.from_pretrained(model_id, **model_kwargs)
processor = AutoProcessor.from_pretrained("google/gemma-3-4b-it")

SFTTrainer は peft との組み込み統合をサポートしているため、QLoRA を使用して LLM を効率的にチューニングできます。LoraConfig を作成してトレーナーに提供するだけです。

from peft import LoraConfig

peft_config = LoraConfig(
    lora_alpha=16,
    lora_dropout=0.05,
    r=16,
    bias="none",
    target_modules="all-linear",
    task_type="CAUSAL_LM",
    modules_to_save=[
        "lm_head",
        "embed_tokens",
    ],
)

トレーニングを開始する前に、SFTConfig で使用するハイパーパラメータと、ビジョン処理を処理するカスタム collate_fn を定義する必要があります。collate_fn は、テキストと画像を含むメッセージを、モデルが理解できる形式に変換します。

from trl import SFTConfig

args = SFTConfig(
    output_dir="gemma-product-description",     # directory to save and repository id
    num_train_epochs=1,                         # number of training epochs
    per_device_train_batch_size=1,              # batch size per device during training
    gradient_accumulation_steps=4,              # number of steps before performing a backward/update pass
    gradient_checkpointing=True,                # use gradient checkpointing to save memory
    optim="adamw_torch_fused",                  # use fused adamw optimizer
    logging_steps=5,                            # log every 5 steps
    save_strategy="epoch",                      # save checkpoint every epoch
    learning_rate=2e-4,                         # learning rate, based on QLoRA paper
    bf16=True,                                  # use bfloat16 precision
    max_grad_norm=0.3,                          # max gradient norm based on QLoRA paper
    warmup_ratio=0.03,                          # warmup ratio based on QLoRA paper
    lr_scheduler_type="constant",               # use constant learning rate scheduler
    push_to_hub=True,                           # push model to hub
    report_to="tensorboard",                    # report metrics to tensorboard
    gradient_checkpointing_kwargs={
        "use_reentrant": False
    },  # use reentrant checkpointing
    dataset_text_field="",                      # need a dummy field for collator
    dataset_kwargs={"skip_prepare_dataset": True},  # important for collator
)
args.remove_unused_columns = False # important for collator

# Create a data collator to encode text and image pairs
def collate_fn(examples):
    texts = []
    images = []
    for example in examples:
        image_inputs = process_vision_info(example["messages"])
        text = processor.apply_chat_template(
            example["messages"], add_generation_prompt=False, tokenize=False
        )
        texts.append(text.strip())
        images.append(image_inputs)

    # Tokenize the texts and process the images
    batch = processor(text=texts, images=images, return_tensors="pt", padding=True)

    # The labels are the input_ids, and we mask the padding tokens and image tokens in the loss computation
    labels = batch["input_ids"].clone()

    # Mask image tokens
    image_token_id = [
        processor.tokenizer.convert_tokens_to_ids(
            processor.tokenizer.special_tokens_map["boi_token"]
        )
    ]
    # Mask tokens for not being used in the loss computation
    labels[labels == processor.tokenizer.pad_token_id] = -100
    labels[labels == image_token_id] = -100
    labels[labels == 262144] = -100

    batch["labels"] = labels
    return batch

これで、SFTTrainer を作成してモデルのトレーニングを開始するために必要なすべてのビルディングブロックが揃いました。

from trl import SFTTrainer

trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=dataset,
    peft_config=peft_config,
    processing_class=processor,
    data_collator=collate_fn,
)

train() メソッドを呼び出してトレーニングを開始します。

# Start training, the model will be automatically saved to the Hub and the output directory
trainer.train()

# Save the final model again to the Hugging Face Hub
trainer.save_model()

モデルをテストする前に、メモリを解放してください。

# free the memory again
del model
del trainer
torch.cuda.empty_cache()

QLoRA を使用する場合は、アダプターのみをトレーニングし、モデル全体をトレーニングしません。つまり、トレーニング中にモデルを保存する場合は、アダプターの重みのみを保存し、モデル全体は保存しません。完全なモデルを保存して、vLLM や TGI などのサービングスタックで簡単に使用できるようにするには、merge_and_unload メソッドを使用してアダプター重みをモデル重みに統合し、save_pretrained メソッドでモデルを保存します。これにより、推論に使用できるデフォルトモデルが保存されます。

from peft import PeftModel

# Load Model base model
model = AutoModelForImageTextToText.from_pretrained(model_id, low_cpu_mem_usage=True)

# Merge LoRA and base model and save
peft_model = PeftModel.from_pretrained(model, args.output_dir)
merged_model = peft_model.merge_and_unload()
merged_model.save_pretrained("merged_model", safe_serialization=True, max_shard_size="2GB")

processor = AutoProcessor.from_pretrained(args.output_dir)
processor.save_pretrained("merged_model")

モデル推論をテストして商品説明を生成する

トレーニングが完了したら、モデルを評価してテストする必要があります。テストデータセットからさまざまなサンプルを読み込み、それらのサンプルでモデルを評価できます。

import torch

# Load Model with PEFT adapter
model = AutoModelForImageTextToText.from_pretrained(
  args.output_dir,
  device_map="auto",
  torch_dtype=torch.bfloat16,
  attn_implementation="eager",
)
processor = AutoProcessor.from_pretrained(args.output_dir)

商品名、カテゴリ、画像を指定して推論をテストできます。sample には、マーベルアクションフィギュアが含まれています。

import requests
from PIL import Image

# Test sample with Product Name, Category and Image
sample = {
  "product_name": "Hasbro Marvel Avengers-Serie Marvel Assemble Titan-Held, Iron Man, 30,5 cm Actionfigur",
  "category": "Toys & Games | Toy Figures & Playsets | Action Figures",
  "image": Image.open(requests.get("https://m.media-amazon.com/images/I/81+7Up7IWyL._AC_SY300_SX300_.jpg", stream=True).raw).convert("RGB")
}

def generate_description(sample, model, processor):
    # Convert sample into messages and then apply the chat template
    messages = [
        {"role": "system", "content": [{"type": "text", "text": system_message}]},
        {"role": "user", "content": [
            {"type": "image","image": sample["image"]},
            {"type": "text", "text": user_prompt.format(product=sample["product_name"], category=sample["category"])},
        ]},
    ]
    text = processor.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    # Process the image and text
    image_inputs = process_vision_info(messages)
    # Tokenize the text and process the images
    inputs = processor(
        text=[text],
        images=image_inputs,
        padding=True,
        return_tensors="pt",
    )
    # Move the inputs to the device
    inputs = inputs.to(model.device)
    
    # Generate the output
    stop_token_ids = [processor.tokenizer.eos_token_id, processor.tokenizer.convert_tokens_to_ids("<end_of_turn>")]
    generated_ids = model.generate(**inputs, max_new_tokens=256, top_p=1.0, do_sample=True, temperature=0.8, eos_token_id=stop_token_ids, disable_compile=True)
    # Trim the generation and decode the output to text
    generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
    output_text = processor.batch_decode(
        generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
    )
    return output_text[0]

# generate the description
description = generate_description(sample, model, processor)
print(description)

まとめと次のステップ

このチュートリアルでは、TRL と QLoRA を使用して、特に商品説明の生成に使用される画像タスク用の Gemma モデルをファインチューニングする方法について説明しました。次に、次のドキュメントをご覧ください。

Gemma モデルでテキストを生成する方法を学習する。
Hugging Face Transformers を使用してテキストタスク用に Gemma をファインチューニングする方法を学びます。
Gemma モデルで分散ファインチューニングと推論を行う方法を学習する。
Vertex AI で Gemma オープンモデルを使用する方法を学習する。
KerasNLP を使用して Gemma をファインチューニングし、Vertex AI にデプロイする方法を学習する。