GKE で vLLM を使用して Gemma 3 27B 推論をサービングする

このチュートリアルでは、vLLM サービング フレームワークを使用して Gemma 3 27B 大規模言語モデル（LLM） をデプロイしてサービングする方法について説明します。Google Kubernetes Engine（GKE）上の単一の A4 仮想マシン（VM）インスタンスに Gemma 3 をデプロイします。

**重要:** このチュートリアルを完了するには、 A4 VM を作成するための容量を予約しておく必要があります。AI Hypercomputer で将来の日時に容量を予約する方法については、使用オプションを選択するをご覧ください。

このチュートリアルは、Kubernetes コンテナ オーケストレーション機能を使用して推論ワークロードを処理することに関心のある、機械学習（ML）エンジニア、プラットフォーム管理者とオペレーター、データと AI のスペシャリストを対象としています。

目標

1. Hugging Face を使用して Gemma 3 にアクセスする。

2. 環境を準備する。

3. Autopilot モードで GKE クラスタを作成する。

4. Hugging Face の認証情報用の Kubernetes Secret を作成する。

5. vLLM コンテナを GKE クラスタにデプロイする。

6. curl を使用して Gemma 3 を操作する。

7. クリーンアップする。

費用

このチュートリアルでは、Google Cloud の課金対象となる以下のコンポーネントを使用します。

• Google Kubernetes Engine の料金
• GPU の料金

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

始める前に

1. Google Cloud CLI をインストールします。

2. フェデレーション ID（連携 ID）を使用するように gcloud CLI を構成します。

   詳細については、連携 ID を使用して gcloud CLI にログインするをご覧ください。

3. gcloud CLI を初期化するには、次のコマンドを実行します:

   gcloud init

4. プロジェクトを Google Cloud 作成または選択します。

   プロジェクトを選択または作成するために必要なロール

   • プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトを選択できます。
   • プロジェクトを作成する: プロジェクトを作成するには、プロジェクト作成者ロール （roles/resourcemanager.projectCreator）が必要です。これには resourcemanager.projects.create 権限が含まれています。詳しくは、ロールを付与する方法をご覧ください。
   注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、 プロジェクトに関連するすべてのリソースを削除できます。

   • プロジェクトを作成する Google Cloud :

     gcloud projects create PROJECT_ID

     PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。

   • 作成した Google Cloud プロジェクトを選択します。

     gcloud config set project PROJECT_ID

     PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

5. プロジェクト Google Cloud に対して課金が有効になっていることを確認します。

6. 必要な API を有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限が付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。詳しくは、ロールを付与する方法をご覧ください。

   gcloud services enable container.googleapis.com

7. ユーザー アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。roles/container.admin

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   次のように置き換えます。

   • PROJECT_ID: プロジェクト ID。
   • USER_IDENTIFIER: ユーザー アカウント。例については、 IAM ポリシーで Workforce プール ユーザーを表すをご覧ください。
   • ROLE: ユーザー アカウントに付与する IAM ロール。
8. Hugging Face アカウントにログインするか、アカウントを作成します。

Hugging Face を使用して Gemma 3 にアクセスする

Hugging Face を使用して Gemma 3 にアクセスする手順は次のとおりです。

1. Hugging Face にログインします。
2. Hugging Face の read アクセス トークンを作成します。 Your Profile > Settings > Access tokens > +Create new token をクリックします。
3. read access トークン値をコピーして保存します。このチュートリアルで後ほど使用します。

環境を準備する

環境を準備するには、デフォルトの環境変数を設定します。

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

次のように置き換えます。

• PROJECT_ID: GKE クラスタを作成する Google Cloud プロジェクト の ID。

• RESERVATION_URL: GKE クラスタの作成に使用する予約の URL。予約が存在するプロジェクトに基づいて、次のいずれかの値を指定します。

  • 予約がプロジェクトに存在する場合: RESERVATION_NAME

  • 予約が別のプロジェクトに存在し、プロジェクトで予約を使用できる場合: 予約を使用できます: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

• REGION: GKE クラスタを作成するリージョン。クラスタは、予約が存在するリージョンでのみ作成できます。

• CLUSTER_NAME: 作成する GKE クラスタの名前。

• YOUR_HF_TOKEN: 前のセクションで作成した Hugging Face アクセス トークン。

• NETWORK: GKE クラスタが使用するネットワーク。次のいずれかの値を指定します。

  • カスタム ネットワークを作成した場合は、ネットワークの名前を指定します。

  • それ以外の場合は、default を指定します。

• SUBNETWORK: GKE クラスタが使用するサブネットワーク。次のいずれかの値を指定します。

  • カスタム サブネットワークを作成した場合は、サブネットワークの名前を指定します。指定できるサブネットワークは、予約と同じリージョンに存在するサブネットワークのみです。

  • それ以外の場合は、default を指定します。

Autopilot モードで GKE クラスタを作成する

Autopilot モードで GKE クラスタを作成するには、次のコマンドを実行します。

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

GKE クラスタの作成が完了するまでに時間がかかることがあります。クラスタの作成が完了したことを Google Cloud 確認するには、 Google Cloud コンソールで Kubernetes クラスタ に移動します。

Hugging Face の認証情報用の Kubernetes Secret を作成する

Hugging Face の認証情報用の Kubernetes Secret を作成する手順は次のとおりです。

1. GKE クラスタと通信するように kubectl を構成します。

   gcloud container clusters get-credentials $CLUSTER_NAME \
       --location=$REGION

2. Hugging Face トークンを保存する Kubernetes Secret を作成します。

   kubectl create secret generic hf-secret \
       --from-literal=hf_api_token=${HUGGING_FACE_TOKEN} \
       --dry-run=client -o yaml | kubectl apply -f -

vLLM コンテナを GKE クラスタにデプロイする

Kubernetes Deployment を使用して Gemma 3 27B モデルをサービングする vLLM コンテナをデプロイする手順は次のとおりです。

1. 選択した vLLM デプロイを含む vllm-3-27b-it.yaml ファイルを作成します。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: vllm-gemma-deployment
   spec:
     progressDeadlineSeconds: 900
     replicas: 1
     selector:
       matchLabels:
         app: gemma-server
     template:
       metadata:
         labels:
           app: gemma-server
           ai.gke.io/model: gemma-3-27b-it
           ai.gke.io/inference-server: vllm
           examples.ai.gke.io/source: user-guide
       spec:
         containers:
         - name: inference-server
           image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250801_0916_RC01
           resources:
             requests:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "120Gi"
               nvidia.com/gpu: "8"
             limits:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "120Gi"
               nvidia.com/gpu: "8"
           command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
           args:
           - --model=$(MODEL_ID)
           - --tensor-parallel-size=8
           - --host=0.0.0.0
           - --port=8000
           - --max-model-len=4096
           - --max-num-seqs=4
           env:
           - name: MODEL_ID
             value: google/gemma-3-27b-it
           - name: HUGGING_FACE_HUB_TOKEN
             valueFrom:
               secretKeyRef:
                 name: hf-secret
                 key: hf_api_token
           volumeMounts:
           - mountPath: /dev/shm
             name: dshm
           livenessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 720
             periodSeconds: 10
           readinessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 720
             periodSeconds: 5
         volumes:
         - name: dshm
           emptyDir:
               medium: Memory
         nodeSelector:
           cloud.google.com/gke-accelerator: nvidia-b200
           cloud.google.com/reservation-name: $RESERVATION_URL
           cloud.google.com/reservation-affinity: "specific"
           cloud.google.com/gke-gpu-driver-version: latest
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: llm-service
   spec:
     selector:
       app: gemma-server
     type: ClusterIP
     ports:
       - protocol: TCP
         port: 8000
         targetPort: 8000

2. vllm-3-27b-it.yaml ファイルを GKE クラスタに適用します。

   envsubst < vllm-3-27b-it.yaml | kubectl apply -f -

   デプロイ プロセス中に、コンテナは Hugging Face から Gemma 3 をダウンロードする必要があります。そのため、コンテナのデプロイが完了するまでに最大 30 分かかることがあります。

3. デプロイが完了するまで待ちます。

   kubectl wait \
       --for=condition=Available \
       --timeout=1800s deployment/vllm-gemma-deployment

curl を使用して Gemma 3 を操作する

デプロイした Gemma 3 27B の指示チューニング済みモデルを確認する手順は次のとおりです。

1. Gemma 3 へのポート転送を設定します。

   kubectl port-forward service/llm-service 8000:8000

2. 新しいターミナル ウィンドウを開きます。curl を使用してモデルとチャットできます。

   curl http://127.0.0.1:8000/v1/chat/completions \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{
     "model": "google/gemma-3-27b-it",
     "messages": [
       {
         "role": "user",
         "content": "Why is the sky blue?"
       }
     ]
   }' | jq .

   出力は次のようになります。

   {
     "id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
     "object": "chat.completion",
     "created": 1741763029,
     "model": "google/gemma-3-27b-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
   }
   

モデルのパフォーマンスをモニタリングする場合は、Cloud Monitoring で vLLM ダッシュボードの統合を使用できます。このダッシュボードでは、トークンのスループット、ネットワーク レイテンシ、エラー率など、モデルの重要なパフォーマンス指標を確認できます。詳細については、 vLLM のドキュメントの vLLM をご覧ください。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

リソースの削除

1. vllm-3-27b-it.yaml ファイルで定義されたデプロイとサービス、および Kubernetes Secret を GKE クラスタから削除するには、次のコマンドを実行します。

   envsubst < vllm-3-27b-it.yaml | kubectl delete -f -
   kubectl delete secret hf-secret

2. GKE クラスタを削除するには、次のコマンドを実行します。

   gcloud container clusters delete $CLUSTER_NAME \
       --region=$REGION \
       --quiet

プロジェクトの削除

注意: プロジェクトを削除すると、次のような影響があります。

• プロジェクト内のすべてのものが削除されます。既存のプロジェクトを使用してこのドキュメントのタスクを行った場合、そのプロジェクトを削除すると、プロジェクト内で行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（例: appspot.com）を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると プロジェクトの割り当て上限を超えないようにすることができます。

プロジェクト Google Cloud を削除する:

gcloud projects delete PROJECT_ID

次のステップ

• AI 最適化 GKE クラスタを管理する