このチュートリアルでは、Llama 4 Scout（17Bx16E）、17B 大規模言語モデル（LLM）をデプロイして、vLLM フレームワークを使用してサービングする方法について説明します。このモデルは、Google Kubernetes Engine（GKE）の単一の A4 仮想マシン（VM）インスタンスにデプロイします。
このチュートリアルは、Kubernetes コンテナ オーケストレーション機能を使用して推論ワークロードを処理することに関心のある ML エンジニア、プラットフォーム管理者、オペレーター、データと AI のスペシャリストを対象としています。
目標
Hugging Face を使用して Llama 4 にアクセスします。
環境を準備します。
Autopilot モードで GKE クラスタを作成する。
Hugging Face の認証情報用の Kubernetes Secret を作成します。
vLLM コンテナを GKE クラスタにデプロイする。
curl を使用して Llama 4 を操作します。
クリーンアップする。
費用
このチュートリアルでは、Google Cloud の課金対象となる以下のコンポーネントを使用します。
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
始める前に
- 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 プロジェクトの名前に置き換えます。
必要な 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 プロジェクトの名前に置き換えます。
必要な API を有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。gcloud services enable container.googleapis.com
-
ユーザー アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。
roles/container.admingcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
次のように置き換えます。
PROJECT_ID: プロジェクト ID。USER_IDENTIFIER: ユーザー アカウントの識別子。例:myemail@example.comROLE: ユーザー アカウントに付与する IAM ロール。
- Hugging Face アカウントにログインするか、アカウントを作成します。
Hugging Face を使用して Llama 4 にアクセスする
Hugging Face を使用して Llama 4 にアクセスする手順は次のとおりです。
- Llama 4 を使用するための同意契約に署名します。
- Hugging Face
readアクセス トークンを作成します。 readアクセス トークンの値をコピーして保存します。これは、このチュートリアルの後半で使用します。
環境を準備する
環境を準備するには、次の変数を設定します。
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を指定します。
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 を作成するには、次の操作を行います。
GKE クラスタと通信するように
kubectlを構成します。gcloud container clusters get-credentials $CLUSTER_NAME \ --location=$REGION前の手順で作成した Hugging Face
read accessトークンを含む 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 クラスタにデプロイする
Llama-4-Scout-17B-16E-Instruct モデルをサービングする vLLM コンテナをデプロイする手順は次のとおりです。
選択した 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 livenessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 1800 periodSeconds: 10 readinessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 1800 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: 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: 30svllm-l4-17b.yamlファイルは GKE クラスタに適用します。kubectl apply -f vllm-l4-17b.yamlデプロイ プロセス中に、コンテナは Hugging Face から
Llama-4-Scout-17B-16E-Instructモデルをダウンロードする必要があります。そのため、コンテナのデプロイが完了するまでに 30 分ほどかかることがあります。完了ステータスを確認するには、次のコマンドを実行します。
kubectl wait \ --for=condition=Available \ --timeout=1800s deployment/vllm-llama4-deployment--timeout=1800sフラグを使用すると、コマンドはデプロイを最大 30 分間モニタリングできます。
curl を使用して Llama 4 を操作する
デプロイした Llama 4 Scout モデルを検証する手順は次のとおりです。
Llama 4 Scout へのポート転送を設定します。
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": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "messages": [ { "role": "user", "content": "Describe a sailboat in one short sentence?" } ] }'表示される出力は次のようになります。
{ "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 アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
プロジェクトの削除
Google Cloud プロジェクトを削除します。
gcloud projects delete PROJECT_ID
リソースの削除
vllm-l4-17b.yamlファイルのデプロイとサービス、および Kubernetes Secret を GKE クラスタから削除するには、次のコマンドを実行します。kubectl delete -f vllm-l4-17b.yaml kubectl delete secret hf-secretGKE クラスタを削除するには、次のコマンドを実行します。
gcloud container clusters delete $CLUSTER_NAME \ --region=$REGION