GKE で vLLM を使用して gpt-oss-120b で推論を実行する

このチュートリアルでは、vLLM フレームワークを使用して gpt-oss-120b 言語モデルをデプロイしてサービングする方法について説明します。このモデルを Google Kubernetes Engine（GKE）Autopilot クラスタにデプロイし、8 個の B200 GPU を搭載した単一の A4 仮想マシン（VM）を使用します。

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

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

目標

1. Hugging Face を使用して gpt-oss-120b にアクセスします。
2. 環境を準備します。
3. Autopilot モードで GKE クラスタを作成する。
4. Hugging Face の認証情報用の Kubernetes Secret を作成します。
5. vLLM コンテナを GKE クラスタにデプロイする。
6. curl を使用して gpt-oss 言語モデルを操作します。
7. クリーンアップする。

費用

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

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

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

始める前に

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

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

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

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

gcloud init

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

プロジェクトの選択または作成に必要なロール

• プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
• プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

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

gcloud services enable container.googleapis.com

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

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

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

gcloud init

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

プロジェクトの選択または作成に必要なロール

• プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
• プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

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

gcloud services enable container.googleapis.com

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

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

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

   • PROJECT_ID: プロジェクト ID。
   • USER_IDENTIFIER: ユーザー アカウントの識別子。例: [e-mail]
   • ROLE: ユーザー アカウントに付与する IAM ロール。
2. Hugging Face アカウントにログインするか、アカウントを作成します。

Hugging Face を使用して gpt-oss にアクセスする

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

1. Hugging Face にログインして、gpt-oss モデルを確認します。
2. Hugging Face read アクセス トークンを作成します。
3. 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 クラスタの作成には時間がかかることがあります。 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_token=${HUGGING_FACE_TOKEN} \
       --dry-run=client -o yaml | kubectl apply -f -
   

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

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

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: vllm-gpt-oss-deployment
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: gpt-oss
     template:
       metadata:
         labels:
           app: gpt-oss
           ai.gke.io/model: gpt-oss-120b
           ai.gke.io/inference-server: vllm
           examples.ai.gke.io/source: user-guide
       spec:
         containers:
         - name: vllm-inference
           image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250822_0916_RC01
           resources:
             requests:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "240Gi"
               nvidia.com/gpu: "8"
             limits:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "240Gi"
               nvidia.com/gpu: "8"
           command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
           args:
           - --model=$(MODEL_ID)
           - --tensor-parallel-size=2
           - --host=0.0.0.0
           - --port=8000
           - --max-model-len=8192
           - --max-num-seqs=4
           env:
           - name: MODEL_ID
             value: openai/gpt-oss-120b
           - name: HUGGING_FACE_HUB_TOKEN
             valueFrom:
               secretKeyRef:
                 name: hf-secret
                 key: hf_token
           volumeMounts:
           - mountPath: /dev/shm
             name: dshm
           livenessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 1200
             periodSeconds: 10
           readinessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 1200
             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: oss-service
   spec:
     selector:
       app: gpt-oss
     type: ClusterIP
     ports:
       - protocol: TCP
         port: 8000
         targetPort: 8000
   ---
   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: vllm-gpt-oss-monitoring
   spec:
     selector:
       matchLabels:
         app: gpt-oss
     endpoints:
     - port: 8000
       path: /metrics
       interval: 30s
   

2. vllm-gpt-oss-120b.yaml ファイルは GKE クラスタに適用します。

   envsubst < vllm-gpt-oss-120b.yaml | kubectl apply -f -
   

3. デプロイ プロセス中に、コンテナは Hugging Face から gpt-oss-120b モデルをダウンロードする必要があります。そのため、コンテナのデプロイが完了するまでに 20 分ほどかかることがあります。

4. 完了ステータスを確認するには、次のコマンドを実行します。

   kubectl wait \
   --for=condition=Available \
   --timeout=1200s deployment/vllm-gpt-oss-deployment
   

   --timeout=1200s フラグを使用すると、コマンドはデプロイを最大 20 分間モニタリングできます。

curl を使用して gpt-oss モデルを操作する

デプロイした gpt-oss モデルを確認する手順は次のとおりです。

1. gpt-oss モデルへのポート転送を設定します。

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

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

   curl http://127.0.0.1:8000/v1/chat/completions \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{
     "model": "openai/gpt-oss-120b",
     "messages": [
       {
         "role": "user",
         "content": "Describe a sailboat in one short sentence?"
       }
     ]
   }'
   

3. 表示される出力は次のようになります。

   {
     "id": "chatcmpl-2235c39759c040daae23ce2addc40c0a",
     "object": "chat.completion",
     "created": 1756831629,
     "model": "openai/gpt-oss-120b",
     "choices": [
       {
         "index": 0,
         "message": {
           "role": "assistant",
           "content": "A sleek vessel gliding on water, its cloth sails billowing like captured wind.",
           "refusal": null,
           "annotations": null,
           "audio": null,
           "function_call": null,
           "tool_calls": [],
           "reasoning_content": "User asks: \"Describe a sailboat in one short sentence?\" We need to produce a short sentence description. Should comply with policy. It's fine. Provide a short sentence."
         },
         "logprobs": null,
         "finish_reason": "stop",
         "stop_reason": null
       }
     ],
     "service_tier": null,
     "system_fingerprint": null,
     "usage": {
       "prompt_tokens": 80,
       "total_tokens": 142,
       "completion_tokens": 62,
       "prompt_tokens_details": null
     },
     "prompt_logprobs": null,
     "kv_transfer_params": null
   }
   

   モデルのパフォーマンスをモニタリングする

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

クリーンアップ

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

プロジェクトの削除

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

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

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

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

gcloud projects delete PROJECT_ID

リソースの削除

1. vllm-gpt-oss-120b.yaml ファイルのデプロイとサービス、および GKE クラスタの Kubernetes Secret を削除するには、次のコマンドを実行します。

   kubectl delete -f vllm-gpt-oss-120b.yaml
   kubectl delete secret hf-secret
   

2. GKE クラスタを削除する手順は次のとおりです。

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

次のステップ

• AI 最適化 GKE クラスタを管理する
• AI / ML ワークロードにおすすめのストレージ サービスについて学習する