GKE で vLLM を使用して Llama 4 で推論を実行する

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

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

目標

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

  2. 環境を準備する。

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

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

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

  6. curl を使用して Llama 4 を操作する。

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

費用

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

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

始める前に

  1. アカウントにログインします。 Google Cloud を初めて使用する場合は、 Google Cloud、 アカウントを作成して、 実際のシナリオでプロダクトがどのように機能するかを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイに利用できる $300 分の無料クレジットも提供されます。

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

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

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

    gcloud init

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

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

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

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

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

    gcloud services enable container.googleapis.com

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

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

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

    gcloud init

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

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

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

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

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

    gcloud services enable container.googleapis.com
    14.

  14. ユーザー アカウントにロールを付与します。次の 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 ロール。
  15. Hugging Face アカウントにログインするか、アカウントを作成します。

Hugging Face を使用して Llama 4 にアクセスする

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

  1. Llama 4 を使用するための同意契約に署名します。
  2. Hugging Face read アクセス トークンを作成します。
  3. read アクセス トークンの値をコピーして保存します。このチュートリアルで後ほど使用します。

環境を準備する

環境を準備するには、次の変数を設定します。

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_NAME="YOUR_RESERVATION_NAME"
export REGION="YOUR_CLUSTER_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export HF_TOKEN="YOUR_HUGGING_FACE_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}

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

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

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

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

    • 予約が別のプロジェクトに存在し、プロジェクトで予約を使用できる場合。完全パス（ RESERVATION_URL とも呼ばれます）を指定します: projects/YOUR_RESERVATION_PROJECT_ID/reservations/YOUR_RESERVATION_NAME。 YOUR_RESERVATION_PROJECT_ID は、共有予約が作成されたプロジェクトの ID に置き換えます。

      プロジェクトに、他のプロジェクトの予約を使用するために必要な権限があることを確認します。

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

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

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

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

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

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

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

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

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

リソースを作成して構成する Google Cloud

このセクションの手順に沿って、必要なリソースを作成します。

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 がクラスタの作成を完了したことを確認するには、 [Kubernetes クラスタ] に Google Cloud 移動します。

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

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

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

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

  2. 前の手順で作成した Hugging Face read access トークンを含む Kubernetes Secret を作成します。

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

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

Llama-4-Scout-17B-16E-Instruct モデルをサービングする vLLM コンテナをデプロイする手順は次のとおりです。

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

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-llama4-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: llama4-server
  template:
    metadata:
      labels:
        app: llama4-server
        ai.gke.io/model: llama-4-scout-17b
        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:20250722_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=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=4096
        - --max-num-seqs=4
        env:
        - name: MODEL_ID
          value: meta-llama/Llama-4-Scout-17B-16E-Instruct
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        startupProbe:
          httpGet:
            path: /health
            port: 8000
          failureThreshold: 200
          periodSeconds: 15
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 15
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 15
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: ${RESERVATION_NAME}
        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: llama4-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-llama4-monitoring
spec:
  selector:
    matchLabels:
      app: llama4-server
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

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

    envsubst < vllm-l4-17b.yaml | kubectl apply -f -

    デプロイ プロセス中に、コンテナは Hugging Face から Llama-4-Scout-17B-16E-Instruct モデルをダウンロードする必要があります。このため、コンテナのデプロイが完了するまでに最大 30 分かかることがあります。

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

    kubectl wait \
    --for=condition=Available \
    --timeout=3000s \
    deployment/vllm-llama4-deployment

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

curl を使用して Llama 4 を操作する

デプロイした Llama 4 Scout モデルを確認する手順は次のとおりです。

  1. Llama 4 Scout へのポート転送を設定します。

    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": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
       "messages": [
         {
           "role": "user",
           "content": "Describe a sailboat in one short sentence?"
         }
       ]
     }' | jq .

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

    {
      "id": "chatcmpl-ec0ad6310c494a889b17600881c06e3d",
      "object": "chat.completion",
      "created": 1754073279,
      "model": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "A sailboat is a type of watercraft that uses the wind for propulsion, typically featuring a hull, mast, and one or more sails.",
            "refusal": null,
            "annotations": null,
            "audio": null,
            "function_call": null,
            "tool_calls": [],
            "reasoning_content": null
          },
          "logprobs": null,
          "finish_reason": "stop",
          "stop_reason": null
        }
      ],
      "service_tier": null,
      "system_fingerprint": null,
      "usage": {
        "prompt_tokens": 19,
        "total_tokens": 49,
        "completion_tokens": 30,
        "prompt_tokens_details": null
      },
      "prompt_logprobs": null,
      "kv_transfer_params": null
    }

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

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

Managed Service for Prometheus を使用してモデルから指標を収集する方法については、Cloud Monitoring のドキュメントで vLLM のオブザーバビリティ ガイダンスをご覧ください。 Google Cloud

クリーンアップする。

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

リソースの削除

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

    kubectl delete -f vllm-l4-17b.yaml
kubectl delete secret hf-secret

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

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

プロジェクトの削除

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

gcloud projects delete PROJECT_ID

次のステップ