Hugging Face Transformers で Gemma を実行する

[ai.google.dev で表示] [Run in Google Colab] [Kaggle で実行] [Vertex AI で開く] [GitHub 上のソースを見る]

Gemma オープンモデルでは、テキストの生成、要約、コンテンツの分析など、さまざまなタスクを実行できます。このチュートリアルでは、Hugging Face Transformers を使用して Gemma を実行し、テキストと画像の両方の入力を使用してテキスト コンテンツを生成する方法について説明します。Transformers Python ライブラリは、Gemma を含む事前トレーニング済みの生成 AI モデルにアクセスするための API を提供します。詳細については、Transformers のドキュメントをご覧ください。

設定

このチュートリアルを開始する前に、次の手順を完了してください。

  • Hugging Face にログインし、Gemma モデルの [Acknowledge license] を選択して、Gemma にアクセスします。
  • 実行する Gemma モデルのサイズを実行するのに十分なリソースを備えた Colab ランタイムを選択します。詳細
  • Hugging Face アクセス トークンを生成して、Colab 環境に追加します。

アクセス トークンを構成する

アクセス トークンを Colab に追加して、Hugging Face ウェブサイトから Gemma モデルをダウンロードできるようにします。Colab のシークレット 機能を使用して、トークンを作業コードに追加せずに安全に保存します。

Hugging Face アクセス トークンをシークレットとして追加する手順は次のとおりです。

  1. インターフェースの左側にある鍵アイコンを選択してシークレット タブを開くか、[ツール] > [コマンド パレット] を選択して「secrets」と入力し、Enter キーを押します。
  2. [Add new secret] を選択して、新しいシークレット エントリを追加します。
  3. [名前] フィールドに「HF_TOKEN」と入力します。
  4. [値] フィールドに、Hugging Face アクセス トークンのテキストを入力します。
  5. [Notebook access] フィールドで、スイッチを選択してアクセスを有効にします。

アクセス トークンを HF_TOKEN と値として入力したら、次のコードを使用して Colab ノートブック環境内でアクセスして設定できます。

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)

Python パッケージをインストールする

Gemma モデルの実行とリクエストの作成に必要な Hugging Face ライブラリをインストールします。

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

# Install a transformers version that supports Gemma 3 (>= 4.51.3)
%pip install "transformers>=4.51.3"

テキストからテキストを生成する

テキストで Gemma モデルにプロンプトを表示してテキスト レスポンスを取得する方法は、Gemma を使用する最も簡単な方法であり、ほぼすべての Gemma バリアントで機能します。このセクションでは、Hugging Face Transformers ライブラリを使用して、テキストからテキストへの生成用に Gemma モデルを読み込んで構成する方法について説明します。

モデルの読み込み

torch ライブラリと transformers ライブラリを使用して、Gemma を使用してモデル実行 pipeline クラスのインスタンスを作成します。モデルを使用して出力を生成したり、指示に従ったりする場合は、通常、モデル ID 文字列に it が含まれる命令チューニング（IT）モデルを選択します。pipeline オブジェクトを使用して、使用する Gemma バリアントと実行するタスクのタイプを指定します。次のコード例に示すように、テキストからテキストへの生成の場合は "text-generation" を指定します。

import torch
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="google/gemma-3-4b-it",
    device=0, # "cuda" for Colab, "msu" for iOS devices
    torch_dtype=torch.bfloat16
)

Gemma では、生成に使用できる task 設定はごくわずかです。使用可能な task 設定の詳細については、Hugging Face Pipelines task() のドキュメントをご覧ください。torch データ型 torch.bfloat16 を使用すると、モデルの出力品質に大きな影響を与えることなく、モデルの精度と必要なコンピューティング リソースを削減できます。device 設定では、Colab の場合は "cuda"、iOS デバイスの場合は "msu" を使用できます。また、これを 0（ゼロ）に設定して、システムの最初の GPU を指定することもできます。Pipeline クラスの使用方法の詳細については、Hugging Face Pipelines のドキュメントをご覧ください。

テキスト生成を実行する

Gemma モデルを読み込んで pipeline オブジェクトで構成したら、モデルにプロンプトを送信できます。次のコード例は、text_inputs パラメータを使用した基本的なリクエストを示しています。

pipeline(text_inputs="roses are red")

[{'generated_text': 'roses are red, violets are blue, \ni love you more than you ever knew.\n\n**Explanation'}]

プロンプト テンプレートを使用する

より複雑なプロンプトでコンテンツを生成する場合は、プロンプト テンプレートを使用してリクエストを構造化します。プロンプト テンプレートを使用すると、user や model などの特定のロールからの入力を指定できます。これは、Gemma モデルとのマルチターン チャット インタラクションを管理するために必要な形式です。次のコード例は、Gemma のプロンプト テンプレートを作成する方法を示しています。

messages = [
    [
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."},]
        },
        {
            "role": "user",
            "content": [{"type": "text", "text": "Roses are red..."},]
        },
    ],
]

pipeline(messages, max_new_tokens=50)

画像データからテキストを生成する

Gemma 3 以降では、モデルサイズが 4B 以上の場合は、プロンプトの一部として画像データを使用できます。このセクションでは、Transformers ライブラリを使用して、画像データとテキスト入力を使用してテキスト出力を生成するように Gemma モデルを読み込んで構成する方法について説明します。

モデルの読み込み

画像データで使用するために Gemma モデルを読み込む場合は、画像で使用するように Transformer pipeline インスタンスを構成します。特に、次のコード例に示すように、task パラメータを "image-text-to-text" に設定して、ビジュアル データを処理できるパイプライン構成を選択する必要があります。

import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text", # required for image input
    model="google/gemma-3-4b-it",
    device=0,
    torch_dtype=torch.bfloat16
)

テキスト生成を実行する

pipeline インスタンスを使用して画像入力を処理するように Gemma モデルを構成したら、画像を含むプロンプトをモデルに送信できます。<start_of_image>トークンを使用して、プロンプトのテキストに画像を追加します。次のコード例は、pipeline パラメータを使用した基本的なリクエストを示しています。

pipeline(
    "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg",
    text="<start_of_image> What is shown in this image?"
)

[{'input_text': '<start_of_image> What is shown in this image?',
  'generated_text': '<start_of_image> What is shown in this image?\n\nThis image showcases a traditional Indian Thali. A Thali is a platter that contains a variety'}]

プロンプト テンプレートを使用する

より複雑なプロンプトでコンテンツを生成する場合は、プロンプト テンプレートを使用してリクエストを構造化します。プロンプト テンプレートを使用すると、user や model などの特定のロールからの入力を指定できます。これは、Gemma モデルとのマルチターン チャット インタラクションを管理するために必要な形式です。次のコード例は、Gemma のプロンプト テンプレートを作成する方法を示しています。

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "This image shows"},
        ],
    },
]

pipeline(text=messages, max_new_tokens=50, return_full_text=False)

`content` リストに `"type": "image",` エントリを追加することで、プロンプトに複数の画像を含めることができます。

音声データからテキストを生成する

Gemma 3n では、プロンプトの一部として音声データを使用できます。このセクションでは、Transformers ライブラリを使用して、音声データとテキスト入力を使用してテキスト出力を生成するように Gemma モデルを読み込んで構成する方法について説明します。

Python パッケージをインストールする

Gemma で音声入力を使用するには、Transformers ライブラリの最新バージョンが必要です。以下に示すように、Gemma モデルを実行し、音声データを使用してリクエストを行うための Hugging Face ライブラリをインストールします。

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

# Install a transformers version that supports Gemma 3n (>= 4.53)
%pip install "transformers>=4.53.0"

モデルの読み込み

音声データで使用するために Gemma モデルを読み込む場合は、音声データで使用するように Transformer インスタンスを構成します。特に、次のコード例に示すように、AutoProcessor クラスと AutoModelForImageTextToText クラスを使用して processor オブジェクトと model オブジェクトを定義する必要があります。

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

GEMMA_MODEL_ID = "google/gemma-3n-E4B-it"

processor = AutoProcessor.from_pretrained(GEMMA_MODEL_ID, device_map="auto")
model = AutoModelForImageTextToText.from_pretrained(
            GEMMA_MODEL_ID, torch_dtype="auto", device_map="auto")

プロンプト テンプレートを使用する

音声を使用してコンテンツを生成する場合は、プロンプト テンプレートを使用してリクエストを構造化します。プロンプト テンプレートを使用すると、user や model などの特定のロールからの入力を指定できます。これは、Gemma モデルとのマルチターン チャット インタラクションを管理するために必要な形式です。次のコード例は、音声データ入力を使用して Gemma のプロンプト テンプレートを作成する方法を示しています。

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
            {"type": "text", "text": "Transcribe this audio and complete the statement"},
        ]
    }
]

`content` リストに `"type": "audio",` エントリを追加することで、プロンプトに複数の音声ファイルを含めることができます。音声データを使用してプロンプトを表示しているが、テンプレートを使用していない場合は、プロンプトのテキストで <audio_soft_token> 構文を使用します。

テキスト生成を実行する

processor オブジェクトと model オブジェクトを使用して Gemma モデルを構成し、プロンプト テンプレートを使用して音声データを含むプロンプトを作成したら、プロンプトを送信して出力を生成できます。次のコード例は、チャット テンプレートを使用したリクエスト、出力の生成、レスポンスのデコードを示しています。

input_ids = processor.apply_chat_template(
        messages,
        add_generation_prompt=True,
        tokenize=True, return_dict=True,
        return_tensors="pt",
)
input_ids = input_ids.to(model.device, dtype=model.dtype)

# Generate output from the model
outputs = model.generate(**input_ids, max_new_tokens=128)

# decode and print the output as text
text = processor.batch_decode(
    outputs,
    skip_special_tokens=False,
    clean_up_tokenization_spaces=False
)
print(text[0])

次のステップ

Gemma モデルを使用してさらに構築して探索する。