このチュートリアルでは、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 ユーザーのロールとタスクをご覧ください。
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 のドキュメントをご覧ください。
モデルへのアクセス権を取得する
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 gcloud config set billing/quota_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 \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
次の値を置き換えます。
PROJECT_ID
: Google Cloudのプロジェクト ID。CONTROL_PLANE_LOCATION
: クラスタのコントロール プレーンの Compute Engine のリージョン。使用するアクセラレータ タイプをサポートするリージョンを指定します(たとえば、L4 GPU の場合はus-central1
)。CLUSTER_NAME
: クラスタの名前。
GKE は、デプロイされたワークロードからのリクエストに応じた CPU ノードと GPU ノードを持つ Autopilot クラスタを作成します。
Standard
Cloud Shell で、次のコマンドを実行して Standard クラスタを作成します。
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=CONTROL_PLANE_LOCATION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1
次の値を置き換えます。
PROJECT_ID
: Google Cloudのプロジェクト ID。CONTROL_PLANE_LOCATION
: クラスタのコントロール プレーンの Compute Engine の リージョン。使用するアクセラレータ タイプをサポートするリージョンを指定します(たとえば、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
メッセージが見つかった場合は、ポート転送が有効であることを確認します。
モデルのパフォーマンスをモニタリングする
モデルのオブザーバビリティ指標のダッシュボードを表示する手順は次のとおりです。
Google Cloud コンソールで、[デプロイされるモデル] ページに移動します。
特定のデプロイの詳細(指標、ログ、ダッシュボードなど)を表示するには、リスト内のモデル名をクリックします。
モデルの詳細ページで、[オブザーバビリティ] タブをクリックして、次のダッシュボードを表示します。プロンプトが表示されたら、[有効にする] をクリックして、クラスタの指標収集を有効にします。
- [インフラストラクチャの使用量] ダッシュボードには、使用率の指標が表示されます。
- [DCGM] ダッシュボードには、DCGM 指標が表示されます。
- vLLM を使用している場合は、[モデルのパフォーマンス] ダッシュボードが使用可能になり、vLLM モデルのパフォーマンスの指標が表示されます。
Cloud Monitoring の vLLM ダッシュボード統合で指標を表示することもできます。これらの指標は、事前設定されたフィルタを使用することなくすべての vLLM デプロイで集計されます。
Cloud Monitoring でダッシュボードを使用するには、GKE クラスタで Google Cloud Managed Service for Prometheus を有効にする必要があります。これにより、vLLM から指標が収集されるようになります。vLLM はデフォルトで Prometheus 形式の指標を公開するため、追加のエクスポーターをインストールする必要はありません。Google Cloud Managed Service for Prometheus を使用したモデルからの指標の収集については、Cloud Monitoring のドキュメントで vLLM のオブザーバビリティ ガイダンスをご覧ください。