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 CLI をインストールします。

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

    詳細については、 フェデレーション ID を使用して gcloud CLI にログインするをご覧ください。

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

    gcloud init

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

  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

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

  8. 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_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export HF_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}

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

  • 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_REGION: GKE クラスタを作成するリージョン。クラスタは、予約が存在するリージョンでのみ作成できます。

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

  • YOUR_HF_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 がクラスタの作成を完了したことを確認するには、 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 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 ダッシュボードの統合を使用します。このダッシュボードでは、トークンのスループット、リクエスト レイテンシ、エラー率などの重要なパフォーマンス指標を確認できます。

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

クリーンアップ

このチュートリアルで使用したリソースについて、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

次のステップ