このチュートリアルでは、vLLM サービング フレームワークを使用し、Google Kubernetes Engine(GKE)で GPU を使用して Llama models 4 大規模言語モデル(LLM)のデプロイとサービングを行う方法について説明します。これにより、マネージド Kubernetes 環境における推論用 LLM の実用的なデプロイに関する基礎を学ぶことができます。vLLM を実行する事前構築済みコンテナを GKE にデプロイします。また、Hugging Face から Llama を読み込むように GKE を構成します。
このチュートリアルは、ML エンジニア、プラットフォームの管理者とオペレーターのほか、Kubernetes のコンテナ オーケストレーション機能を使用して H200、H100、A100、L4 GPU ハードウェアで AI / ML ワークロードをサービングすることに関心があるデータと AI のスペシャリストを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE Enterprise ユーザーロールとタスクをご覧ください。
ML モデルを費用対効果の高い方法で迅速に構築してサービングする目的で設計された統合マネージド AI プラットフォームが必要な場合は、Vertex AI デプロイ ソリューションをお試しになることをおすすめします。
このページを読む前に、次のことをよく理解しておいてください。
背景
このセクションでは、このガイドで使用されている重要なテクノロジーについて説明します。
Llama
Llama は、テキスト生成、翻訳、質問応答など、さまざまな自然言語処理タスク用に設計された Meta の大規模言語モデルです。GKE は、この規模のモデルの分散トレーニングとサービングの実現に必要なインフラストラクチャを提供します。詳細については、Llama のドキュメントをご覧ください。
GPU
GPU を使用すると、ノードで実行される特定のワークロード(ML やデータ処理など)を高速化できます。GKE では、NVIDIA H200、H100、L4、A100 GPU を搭載したマシンタイプをはじめとする、さまざまなマシンタイプ オプションをノード構成に使用できます。
vLLM
vLLM は、GPU のサービング スループットを向上できる、高度に最適化されたオープンソースの LLM サービング フレームワークであり、次のような機能を備えています。
- PagedAttention による Transformer の実装の最適化
- サービング スループットを全体的に向上させる連続的なバッチ処理
- 複数の GPU でのテンソル並列処理と分散サービング
詳細については、vLLM のドキュメントをご覧ください。
目標
- Autopilot モードまたは Standard モードの GKE クラスタで環境を準備する。
- vLLM コンテナをクラスタにデプロイする。
- vLLM を使用して、curl とウェブチャット インターフェースを介して Llama 4 モデルをサービングする。
始める前に
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
-
Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
[IAM] に移動 - プロジェクトを選択します。
- [ アクセスを許可] をクリックします。
-
[新しいプリンシパル] フィールドに、ユーザー ID を入力します。 これは通常、Google アカウントのメールアドレスです。
- [ロールを選択] リストでロールを選択します。
- 追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。
- [保存] をクリックします。
-
- Hugging Face アカウントを作成します(まだ作成していない場合)。
- プロジェクトに H100 GPU と H200 GPU に十分な割り当てがあることを確認します。詳細については、GPU 割り当てを計画すると GPU 割り当てをご覧ください。
モデルへのアクセス権を取得する
Hugging Face からモデルにアクセスするには、Hugging Face トークンが必要です。
トークンをまだ生成していない場合は、次の手順に沿って生成します。
- [Your Profile] > [Settings] > [Access Tokens] の順にクリックします。
- [New Token] を選択します。
- 任意の名前と、少なくとも
Read
ロールを指定します。 - [Generate a token] を選択します。
- トークンをクリップボードにコピーします。
環境を準備する
このチュートリアルでは、Cloud Shell を使用してGoogle Cloudでホストされているリソースを管理します。Cloud Shell には、このチュートリアルに必要な kubectl
や gcloud CLI などのソフトウェアがプリインストールされています。
Cloud Shell を使用して環境を設定するには、次の操作を行います。
Google Cloud コンソールで
(Cloud Shell をアクティブにする)をクリックして、Google Cloud コンソールで Cloud Shell セッションを起動します。これにより、 Google Cloud コンソールの下部ペインでセッションが起動します。
デフォルトの環境変数を設定します。
gcloud config set project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAME export HF_TOKEN=HF_TOKEN
次の値を置き換えます。
PROJECT_ID
: Google Cloudプロジェクト ID。REGION
: 使用するアクセラレータ タイプをサポートするリージョン(たとえば、L4 GPU の場合はus-central1
)。CLUSTER_NAME
: クラスタの名前。HF_TOKEN
: 先ほど生成した Hugging Face トークン。
Google Cloud リソースを作成して構成する
次の手順で、必要なリソースを作成します。
GKE クラスタとノードプールを作成する
GKE Autopilot クラスタまたは GKE Standard クラスタの GPU で Llama 4 モデルをサービングできます。フルマネージドの Kubernetes エクスペリエンスを実現するには、Autopilot クラスタを使用することをおすすめします。ワークロードに最適な GKE の運用モードを選択するには、GKE の運用モードを選択するをご覧ください。
Autopilot
Cloud Shell で、次のコマンドを実行します。
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--region=REGION \
--release-channel=rapid
次の値を置き換えます。
PROJECT_ID
: Google Cloudプロジェクト ID。REGION
: 使用するアクセラレータ タイプをサポートするリージョン(たとえば、L4 GPU の場合はus-central1
)。CLUSTER_NAME
: クラスタの名前。
GKE は、デプロイされたワークロードからのリクエストに応じた CPU ノードと GPU ノードを持つ Autopilot クラスタを作成します。
Standard
Cloud Shell で、次のコマンドを実行して Standard クラスタを作成します。
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --region=REGION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1
次の値を置き換えます。
PROJECT_ID
: Google Cloudプロジェクト ID。REGION
: 使用するアクセラレータ タイプをサポートするリージョン(たとえば、H100 GPU の場合はus-central1
)。CLUSTER_NAME
: クラスタの名前。
クラスタの作成には数分かかることもあります。
クラスタ用のノードプールを適切なディスクサイズで作成するため、次のコマンドを実行します。
gcloud container node-pools create gpupool \ --accelerator type=nvidia-h100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a3-highgpu-8g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256
GKE は、8 つの H100 80 GB GPU を含む単一のノードプールを作成します。
Hugging Face の認証情報用の Kubernetes Secret を作成する
Cloud Shell で、次の操作を行います。
クラスタと通信できるように
kubectl
を構成します。gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGION
次の値を置き換えます。
REGION
: 使用するアクセラレータ タイプをサポートするリージョン(たとえば、L4 GPU の場合はus-central1
)。CLUSTER_NAME
: クラスタの名前。
Hugging Face トークンを含む Kubernetes Secret を作成します。
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -
HF_TOKEN
は、先ほど生成した Hugging Face トークンに置き換えます。
vLLM をデプロイする
このセクションでは、使用する Llama 4 モデルをサービングする vLLM コンテナをデプロイします。
- Llama 4 Maverick 17B-128E
- Llama 4 Scout 17B-16E
このチュートリアルでは、モデルをデプロイするために Kubernetes Deployment を使用します。Deployment は、クラスタ内のノードに分散された Pod の複数のレプリカを実行できる Kubernetes API オブジェクトです。
Llama 4 Maverick 17B-128e
Llama 4 Maverick 17B-128E モデルをデプロイする手順は次のとおりです。
次の
vllm-llama4-maverick-17b-128e.yaml
マニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-llama4-maverick-17b-128e.yaml
この例では、
--max-model-len=131072
vLLM オプションを使用してコンテキスト ウィンドウを 128,000 に制限しています。
Llama 4 Maverick 17B-128e-it
Llama 4 Maverick 17B-128e 指示チューニング型モデルをデプロイする手順は次のとおりです。
次の
vllm-llama4-maverick-17b-128e-instruct.yaml
マニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-llama4-maverick-17b-128e-instruct.yaml
この例では、
--max-model-len=131072
vLLM オプションを使用してコンテキスト ウィンドウを 128,000 に制限しています。
Llama 4 Maverick 17B-128e-it-fp8
Llama 4 Maverick 17B-128e-Instruct-FP8 モデルをデプロイする手順は次のとおりです。
次の
vllm-llama4-maverick-17b-128e-instruct-fp8.yaml
マニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-llama4-maverick-17b-128e-instruct-fp8.yaml
この例では、
--max-model-len=524288
vLLM オプションを使用してコンテキスト ウィンドウを 512,000 に制限しています。
Llama 4 Scout 17B-16e
Llama 4 Scout 17B-16E モデルをデプロイする手順は次のとおりです。
次の
vllm-llama4-scout-17b-16e.yaml
マニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-llama4-scout-17b-16e.yaml
この例では、
--max-model-len=262144
vLLM オプションを使用してコンテキスト ウィンドウを 256,000 に制限しています。
Llama 4 Scout 17B-16e-it
Llama 4 Scout 17B-16e Instruct 指示用にチューニングされたモデルをデプロイする手順は次のとおりです。
次の
vllm-llama4-scout-17b-16e-instruct.yaml
マニフェストを作成します。次のようにマニフェストを適用します。
kubectl apply -f vllm-llama4-scout-17b-16e-instruct.yaml
この例では、
--max-model-len=1310720
vLLM オプションを使用してコンテキスト ウィンドウを 1.280,000 に制限しています。
Deployment が利用可能になるまで待ちます。
kubectl wait --for=condition=Available --timeout=1800s deployment/llama-deployment
実行中の Deployment のログを表示します。
kubectl logs -f -l app=llama-server
Deployment リソースによってモデルデータがダウンロードされます。この処理には数分かかることがあります。出力は次のようになります。
INFO: Started server process [145]
INFO: Waiting for application startup.
INFO: Application startup complete.
...
INFO 04-07 13:36:29 [async_llm.py:228] Added request chatcmpl-4149ea4cf35e48559f9f819dcdbbb23e.
INFO: 127.0.0.1:44018 - "POST /v1/chat/completions HTTP/1.1" 200 OK
モデルが完全にダウンロードされたことを確認してから、次のセクションに進んでください。
モデルをサービングする
このセクションでは、モデルを操作します。
ポート転送をセットアップする
モデルへのポート転送を設定するには、次のコマンドを実行します。
kubectl port-forward service/llama-service 8080:8000
出力は次のようになります。
Forwarding from 127.0.0.1:8080 -> 7080
curl を使用してモデルを操作する
このセクションでは、基本的なスモークテストを実行して、デプロイされた Llama 指示調整済みモデルを確認する方法について説明します。他のモデルの場合は、meta-llama/Llama-4-Scout-17B-16E
をそれぞれのモデルの名前に付けてください。
この例では、テキストのみの入力で Llama 4 Scout 17B-16E モデルをテストする方法を示します。
新しいターミナル セッションで、curl
を使用してモデルとチャットします。
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "meta-llama/Llama-4-Scout-17B-16E",
"messages": [{"role": "user", "content": "San Francisco is a"}],
"max_tokens": 7,
"temperature": 0
}'
出力は次のようになります。
"message":{"role":"assistant","reasoning_content":null,"content":"San Francisco is a city","tool_calls":[]}
問題のトラブルシューティング
- 「
Empty reply from server
」というメッセージが表示された場合は、コンテナがモデルデータのダウンロードを完了していない可能性があります。モデルのサービング準備ができていることを示す「Connected
」というメッセージがないか、再度 Pod のログを確認します。 Connection refused
メッセージが見つかった場合は、ポート転送が有効であることを確認します。
モデルのパフォーマンスをモニタリングする
モデルのパフォーマンスをモニタリングするには、Cloud Monitoring で vLLM ダッシュボードの統合を使用します。このダッシュボードでは、トークンのスループット、リクエスト レイテンシ、エラー率などの重要なパフォーマンス指標を確認できます。
vLLM ダッシュボードを使用するには、vLLM から指標を収集する Google Cloud Managed Service for Prometheus を GKE クラスタで有効にする必要があります。vLLM の指標はデフォルトで Prometheus 形式によって公開されるため、追加のエクスポーターをインストールする必要はありません。
その後、指標を vLLM ダッシュボードで確認できます。Google Cloud Managed Service for Prometheus を使用してモデルから指標を収集する方法については、Cloud Monitoring のドキュメントで vLLM のオブザーバビリティ ガイダンスをご覧ください。クリーンアップ
このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
デプロイされたリソースを削除する
このガイドで作成したリソースについて Google Cloud アカウントに課金されないようにするには、次のコマンドを実行します。
gcloud container clusters delete CLUSTER_NAME \
--region=REGION
次の値を置き換えます。
REGION
: 使用するアクセラレータ タイプをサポートするリージョン(たとえば、L4 GPU の場合はus-central1
)。CLUSTER_NAME
: クラスタの名前。
次のステップ
- GKE 上の GPU の詳細を確認する。
- GitHub のサンプルコードを表示し、他のアクセラレータ(A100 GPU や H100 GPU など)での Llama と vLLM の使用方法を確認する。
- Autopilot で GPU ワークロードをデプロイする方法を学習する。
- Standard で GPU ワークロードをデプロイする方法を学習する。
- vLLM の GitHub リポジトリとドキュメントを確認する。
- Vertex AI Model Garden を確認する。
- GKE プラットフォームのオーケストレーション機能を使用して、最適化された AI / ML ワークロードを実行する方法を確認する。