このチュートリアルでは、Google Kubernetes Engine（GKE）上の GPU を使用する Gemma 3 大規模言語モデル（LLM）を vLLM サービング フレームワークによってデプロイしてサービングする方法について説明します。これにより、マネージド Kubernetes 環境における推論用 LLM の実用的なデプロイに関する基礎を学ぶことができます。vLLM を実行する事前構築済みコンテナを GKE にデプロイします。また、Hugging Face から Gemma 1B、4B、12B、27B の重みを読み込むように GKE を構成します。
このチュートリアルは、ML エンジニア、プラットフォームの管理者とオペレーターのほか、Kubernetes のコンテナ オーケストレーション機能を使用して H200、H100、A100、L4 GPU ハードウェアで AI / ML ワークロードをサービングすることに関心があるデータと AI のスペシャリストを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。
ML モデルを費用対効果の高い方法で迅速に構築してサービングする目的で設計された統合マネージド AI プラットフォームが必要な場合は、Vertex AI デプロイ ソリューションをお試しになることをおすすめします。
このページを読む前に、次のことをよく理解しておいてください。
背景
このセクションでは、このガイドで使用されている重要なテクノロジーについて説明します。
Gemma
Gemma は、オープン ライセンスでリリースされて一般公開されている、軽量の生成 AI モデルのセットです。これらの AI モデルは、アプリケーション、ハードウェア、モバイル デバイス、ホスト型サービスで実行できます。Gemma 3 ではマルチモダリティが導入され、ビジョン言語入力とテキスト出力がサポートされています。最大 128,000 トークンのコンテキスト ウィンドウを処理でき、140 を超える言語に対応しています。また Gemma 3 では、構造化出力や関数呼び出しなど、数学、推論、チャット関連の機能が強化されています。
Gemma モデルはテキスト生成に使用できますが、特殊なタスク用にチューニングすることもできます。
詳細については、Gemma のドキュメントをご覧ください。
GPU
GPU を使用すると、ノードで実行される特定のワークロード（ML やデータ処理など）を高速化できます。GKE では、NVIDIA H200、H100、L4、A100 GPU を搭載したマシンタイプをはじめとする、さまざまなマシンタイプ オプションをノード構成に使用できます。
vLLM
vLLM は、GPU のサービング スループットを向上できる、高度に最適化されたオープンソースの LLM サービング フレームワークであり、次のような機能を備えています。
- PagedAttention による Transformer の実装の最適化
- サービング スループットを全体的に向上させる連続的なバッチ処理
- 複数の GPU でのテンソル並列処理と分散サービング
詳細については、vLLM のドキュメントをご覧ください。
モデルへのアクセス権を取得する
Hugging Face からモデルにアクセスするには、Hugging Face トークンが必要です。
トークンをまだ生成していない場合は、次の手順に沿って生成します。
- [Your Profile] > [Settings] > [Access Tokens] の順にクリックします。
- [New Token] を選択します。
- 任意の名前と、少なくとも
Readロールを指定します。 - [Generate a token] を選択します。
- トークンをクリップボードにコピーします。
環境を準備する
このチュートリアルでは、Cloud Shell を使用してGoogle Cloudでホストされているリソースを管理します。Cloud Shell には、このチュートリアルに必要な kubectl や gcloud CLI などのソフトウェアがプリインストールされています。
Cloud Shell を使用して環境を設定するには、次の操作を行います。
Google Cloud コンソールで
（Cloud Shell をアクティブにする）をクリックして、Google Cloud コンソールで Cloud Shell セッションを起動します。これにより、 Google Cloud コンソールの下部ペインでセッションが起動します。デフォルトの環境変数を設定します。
gcloud config set project PROJECT_ID gcloud config set billing/quota_project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAME export HF_TOKEN=HF_TOKEN次の値を置き換えます。
PROJECT_ID: Google Cloudプロジェクト ID。REGION: 使用するアクセラレータ タイプをサポートするリージョン（たとえば、L4 GPU の場合はus-central1）。CLUSTER_NAME: クラスタの名前。HF_TOKEN: 先ほど生成した Hugging Face トークン。
Google Cloud リソースを作成して構成する
次の手順で、必要なリソースを作成します。
GKE クラスタとノードプールを作成する
GKE Autopilot クラスタまたは GKE Standard クラスタの GPU で Gemma を提供できます。フルマネージドの Kubernetes エクスペリエンスを実現するには、Autopilot クラスタを使用することをおすすめします。ワークロードに最適な GKE の運用モードを選択するには、GKE の運用モードを選択するをご覧ください。
Autopilot
Cloud Shell で、次のコマンドを実行します。
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
次の値を置き換えます。
PROJECT_ID: Google Cloudのプロジェクト ID。CONTROL_PLANE_LOCATION: クラスタのコントロール プレーンの Compute Engine の リージョン。使用するアクセラレータ タイプをサポートするリージョンを指定します（たとえば、L4 GPU の場合はus-central1）。CLUSTER_NAME: クラスタの名前。
GKE は、デプロイされたワークロードからのリクエストに応じた CPU ノードと GPU ノードを持つ Autopilot クラスタを作成します。
Standard
Cloud Shell で、次のコマンドを実行して Standard クラスタを作成します。
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=CONTROL_PLANE_LOCATION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1次の値を置き換えます。
PROJECT_ID: Google Cloudのプロジェクト ID。CONTROL_PLANE_LOCATION: クラスタのコントロール プレーンの Compute Engine の リージョン。使用するアクセラレータ タイプをサポートするリージョンを指定します（たとえば、L4 GPU の場合はus-central1）。CLUSTER_NAME: クラスタの名前。
クラスタの作成には数分かかることもあります。
クラスタ用のノードプールを適切なディスクサイズで作成するため、次のコマンドを実行します。
Gemma 3 1B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE 上で、ノードごとに 1 つの L4 GPU を含む単一のノードプールが作成されます。
Gemma 3 4B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE 上で、ノードごとに 1 つの L4 GPU を含む単一のノードプールが作成されます。
Gemma 3 12B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-48 \ --num-nodes=1GKE 上で、ノードごとに 4 つの L4 GPU を含む単一のノードプールが作成されます。
Gemma 3 27B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-a100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a2-ultragpu-1g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256GKE 上で、1 つの A100 80 GB GPU を含む単一のノードプールが作成されます。
Hugging Face の認証情報用の Kubernetes Secret を作成する
Cloud Shell で、次の操作を行います。
クラスタと通信できるように
kubectlを構成します。gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGION次の値を置き換えます。
REGION: 使用するアクセラレータ タイプをサポートするリージョン（たとえば、L4 GPU の場合はus-central1）。CLUSTER_NAME: クラスタの名前。
Hugging Face トークンを含む Kubernetes Secret を作成します。
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -HF_TOKENは、先ほど生成した Hugging Face トークンに置き換えます。
vLLM をデプロイする
このセクションでは、使用する Gemma モデルをサービングする vLLM コンテナをデプロイします。このチュートリアルでは、モデルをデプロイするために Kubernetes Deployment を使用します。Deployment は、クラスタ内のノードに分散された Pod の複数のレプリカを実行できる Kubernetes API オブジェクトです。
Gemma 3 1B-it
Gemma 3 1B の指示チューニング済みモデル（テキストのみの入力）をデプロイする手順は次のとおりです。
次の
vllm-3-1b-it.yamlマニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
Gemma 3 4B の指示チューニング済みモデルをデプロイする手順は次のとおりです。
次の
vllm-3-4b-it.yamlマニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-3-4b-it.yamlこの例では、vLLM オプション
--max-model-len=32768を使用してコンテキスト ウィンドウを 32K に制限しています。コンテキスト ウィンドウのサイズを大きくする場合（最大 128K）は、マニフェストとノードプールの構成を調整して GPU 容量を増やします。
Gemma 3 12B-it
Gemma 3 12B の指示チューニング済みモデルをデプロイする手順は次のとおりです。
次の
vllm-3-12b-it.yamlマニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-3-12b-it.yamlこの例では、vLLM オプション
--max-model-len=16384を使用してコンテキスト ウィンドウを 16K に制限しています。コンテキスト ウィンドウのサイズを大きくする場合（最大 128K）は、マニフェストとノードプールの構成を調整して GPU 容量を増やします。
Gemma 3 27B-it
Gemma 3 27B の指示チューニング済みモデルをデプロイする手順は次のとおりです。
次の
vllm-3-27b-it.yamlマニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-3-27b-it.yamlこの例では、vLLM オプション
--max-model-len=32768を使用してコンテキスト ウィンドウを 32K に制限しています。コンテキスト ウィンドウのサイズを大きくする場合（最大 128K）は、マニフェストとノードプールの構成を調整して GPU 容量を増やします。
クラスタ内の 1 つの Pod が Hugging Face からモデルの重みをダウンロードしてサービス提供エンジンを起動します。
Deployment が利用可能になるまで待ちます。
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
実行中の Deployment のログを表示します。
kubectl logs -f -l app=gemma-server
Deployment リソースによってモデルデータがダウンロードされます。この処理には数分かかることがあります。出力は次のようになります。
INFO: Automatically detected platform cuda.
...
INFO [launcher.py:34] Route: /v1/chat/completions, Methods: POST
...
INFO: Started server process [13]
INFO: Waiting for application startup.
INFO: Application startup complete.
Default STARTUP TCP probe succeeded after 1 attempt for container "vllm--google--gemma-3-4b-it-1" on port 8080.
モデルが完全にダウンロードされたことを確認してから、次のセクションに進んでください。
モデルを提供する
このセクションでは、モデルを操作します。
ポート転送をセットアップする
次のコマンドを実行して、モデルへのポート転送を設定します。
kubectl port-forward service/llm-service 8000:8000
出力は次のようになります。
Forwarding from 127.0.0.1:8000 -> 8000
curl を使用してモデルを操作する
このセクションでは、デプロイした Gemma 3 指示チューニング済みモデルを基本的なスモークテストによって検証する方法を説明します。他のモデルの場合は、gemma-3-4b-it をモデル名に置き換えます。
この例では、Gemma 3 4B の指示チューニング済みモデル（テキストのみの入力）をテストする方法を示します。
新しいターミナル セッションで、curl を使用してモデルとチャットします。
curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-4b-it",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
出力は次のようになります。
{
"id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
"object": "chat.completion",
"created": 1741763029,
"model": "google/gemma-3-4b-it",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": 106
}
],
"usage": {
"prompt_tokens": 15,
"total_tokens": 668,
"completion_tokens": 653,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
（省略可）Gradio のチャット インターフェースでモデルを操作する
このセクションでは、指示チューニング済みモデルを操作できるウェブチャット アプリケーションを作成します。わかりやすくするため、このセクションでは 4B-it モデルを使用したテスト方法についてのみ説明します。
Gradio は、chatbot のユーザー インターフェースを作成する ChatInterface ラッパーを含む Python ライブラリです。
チャット インターフェースをデプロイする
Cloud Shell で、次のマニフェストを
gradio.yamlとして保存します。google/gemma-2-9b-itは、google/gemma-3-4b-itまたはデプロイで使用した別の Gemma 3 モデル名に変更します。次のようにマニフェストを適用します。
kubectl apply -f gradio.yamlDeployment が利用可能になるまで待ちます。
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
チャット インターフェースを使用する
Cloud Shell で、次のコマンドを実行します。
kubectl port-forward service/gradio 8080:8080これにより、Cloud Shell から Gradio サービスへのポート転送が作成されます。
Cloud Shell タスクバーの右上にある [
ウェブでプレビュー] ボタンをクリックします。[ポート 8080 でプレビュー] をクリックします。ブラウザで新しいタブが開きます。Gradio のチャット インターフェースを使用して Gemma を操作します。プロンプトを追加して [送信] をクリックします。
問題のトラブルシューティング
Empty reply from serverというメッセージが表示された場合は、コンテナがモデルデータのダウンロードを完了していない可能性があります。モデルがサービス提供の準備ができていることを示すConnectedというメッセージがないか、再度 Pod のログを確認します。Connection refusedが表示された場合は、ポート転送が有効であることを確認します。
モデルのパフォーマンスをモニタリングする
モデルのオブザーバビリティ指標のダッシュボードを表示する手順は次のとおりです。
Google Cloud コンソールで、[デプロイされるモデル] ページに移動します。
特定のデプロイの詳細（指標、ログ、ダッシュボードなど）を表示するには、リスト内のモデル名をクリックします。
モデルの詳細ページで、[オブザーバビリティ] タブをクリックして、次のダッシュボードを表示します。プロンプトが表示されたら、[有効にする] をクリックして、クラスタの指標収集を有効にします。
- [インフラストラクチャの使用量] ダッシュボードには、使用率の指標が表示されます。
- [DCGM] ダッシュボードには、DCGM 指標が表示されます。
- vLLM を使用している場合は、[モデルのパフォーマンス] ダッシュボードが使用可能になり、vLLM モデルのパフォーマンスの指標が表示されます。
Cloud Monitoring の vLLM ダッシュボード統合で指標を表示することもできます。これらの指標は、事前設定されたフィルタを使用することなくすべての vLLM デプロイで集計されます。
Cloud Monitoring でダッシュボードを使用するには、GKE クラスタで Google Cloud Managed Service for Prometheus を有効にする必要があります。これにより、vLLM から指標が収集されるようになります。vLLM はデフォルトで Prometheus 形式の指標を公開するため、追加のエクスポーターをインストールする必要はありません。Google Cloud Managed Service for Prometheus を使用したモデルからの指標の収集については、Cloud Monitoring のドキュメントで vLLM のオブザーバビリティ ガイダンスをご覧ください。