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

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

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

目標

Hugging Face を使用して Gemma 3 にアクセスする。
環境を準備する。
Autopilot モードで GKE クラスタを作成する。
Hugging Face の認証情報用の Kubernetes Secret を作成する。
vLLM コンテナを GKE クラスタにデプロイする。
curl を使用して Gemma 3 を操作する。
クリーンアップする。

費用

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

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

始める前に

アカウントにログインします Google Cloud を初めて使用する場合は、 Google Cloud アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

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

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

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

gcloud init

プロジェクトを 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 プロジェクトの名前に置き換えます。

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

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

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

API を有効にするには、権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。serviceusage.services.enableロールを付与する方法を確認する。

gcloud services enable container.googleapis.com

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

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

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

gcloud init

プロジェクトを 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 プロジェクトの名前に置き換えます。

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

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

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

gcloud services enable container.googleapis.com

ユーザーアカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。roles/container.admin
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- USER_IDENTIFIER: ユーザーアカウントの識別子。例: myemail@example.com。
- ROLE: ユーザーアカウントに付与する IAM ロール。
Hugging Face アカウントにログインするか、アカウントを作成します。

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

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

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

環境を準備する

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

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export RESERVATION_URL=RESERVATION_URL
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HUGGING_FACE_TOKEN=HUGGING_FACE_TOKEN
export NETWORK=NETWORK_NAME
export SUBNETWORK=SUBNETWORK_NAME

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

PROJECT_ID: GKE クラスタを作成する Google Cloud プロジェクトの ID。
RESERVATION_URL: GKE クラスタの作成に使用する予約の URL。予約が存在するプロジェクトに基づいて、次のいずれかの値を指定します。
- 予約がプロジェクトに存在する場合: RESERVATION_NAME
- 予約が別のプロジェクトに存在し、プロジェクトで予約を使用できる場合: 予約を使用できます: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
REGION: GKE クラスタを作成するリージョン。クラスタを作成できるのは、予約が存在するリージョンのみです。
CLUSTER_NAME: 作成する GKE クラスタの名前。
HUGGING_FACE_TOKEN: 前のセクションで作成した Hugging Face アクセストークン。
NETWORK_NAME: GKE クラスタが使用するネットワーク。次のいずれかの値を指定します。
- カスタムネットワークを作成した場合は、ネットワークの名前を指定します。
- それ以外の場合は、default を指定します。
SUBNETWORK_NAME: 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 クラスタの作成が完了するまでに時間がかかることがあります。クラスタの作成が完了したことを確認するには、コンソールで Kubernetes クラスタに移動します。 Google Cloud Google Cloud

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

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

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

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

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 コンテナをデプロイする手順は次のとおりです。

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

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  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: 600
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 600
          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

vllm-3-27b-it.yaml ファイルを GKE クラスタに適用します。
```
kubectl apply -f vllm-3-27b-it.yaml
```
デプロイプロセス中に、コンテナは Hugging Face から Gemma 3 をダウンロードする必要があります。そのため、コンテナのデプロイが完了するまでに最大 30 分かかることがあります。

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

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

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

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

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

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

新しいターミナルウィンドウを開きます。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?"
    }
  ]
}'

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

{
  "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 ダッシュボードの統合を使用できます。このダッシュボードでは、トークンのスループット、ネットワークレイテンシ、エラー率など、モデルの重要なパフォーマンス指標を確認できます。詳細については、 Monitoring のドキュメントのvLLMをご覧ください。

クリーンアップする。

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

プロジェクトの削除

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

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

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

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

gcloud projects delete PROJECT_ID

GKE クラスタを削除する

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

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

yaml ファイルと Kubernetes Secret を削除する

vllm-3-27b-it.yaml ファイルと Kubernetes Secret を GKE クラスタから削除するには、次のコマンドを実行します。

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

次のステップ

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