Hugging Face Transformers で Gemma を実行する

ai.google.dev で表示

Google Colab で実行

Kaggle で実行する

Vertex AI で開く

GitHub でソースを見る

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

セットアップ

このチュートリアルを始める前に、次の手順を行います。

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

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

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

Hugging Face アクセス トークンをシークレットとして追加するには:

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

アクセス トークンを 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 クラスのインスタンスを作成します。出力の生成や指示の実行にモデルを使用する場合は、指示用調整（IT）モデルを選択します。通常、モデル ID 文字列に 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> 構文を使用します。

テキスト生成を実行する

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

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 モデルを使用して、次のようなモデルを構築して探索できます。

• Hugging Face Transformers を使用してテキストタスク用に Gemma をファインチューニングする
• Hugging Face Transformers を使用して Gemma をビジョン タスク用にファインチューニングする
• Gemma モデルで分散ファインチューニングと推論を実行する
• Vertex AI で Gemma オープンモデルを使用する
• Keras を使用して Gemma をファインチューニングし、Vertex AI にデプロイする