事前構成されたアーキテクチャを使用して GKE でオープン LLM を提供する

このページでは、事前構成済みの本番環境対応のリファレンス アーキテクチャを使用して、GKE で一般的なオープン大規模言語モデル（LLM）を推論用に迅速にデプロイしてサービングする方法について説明します。このアプローチでは、Infrastructure as Code（IaC）を使用し、CLI スクリプトでラップされた Terraform を使用して、AI 推論ワークロード用に設計された標準化された安全でスケーラブルな GKE 環境を作成します。

このガイドでは、vLLM サービング フレームワークを使用して、GKE のシングルホスト GPU ノードで LLM をデプロイしてサービングします。このガイドでは、次のオープンモデルをデプロイする手順と構成について説明します。

• Google Gemma 3 27B-it
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• OpenAI gpt-oss-20b

このガイドは、推論用のオープンモデルのサービングに Kubernetes コンテナ オーケストレーション機能を使用することに関心のある ML エンジニアとデータおよび AI のスペシャリストを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。

これらのオープンモデルのモデル サービングのパフォーマンスと費用の詳細な分析には、GKE Inference Quickstart ツールも使用できます。詳細については、GKE Inference クイックスタート ガイドと付属の Colab ノートブックをご覧ください。

モデルへのアクセス権を取得する

注: 使用するゲート付きモデル（Gemma や Llama など）のライセンス条項は、それぞれの Hugging Face モデルページで同意する必要があります。

Hugging Face からモデルにアクセスするには、Hugging Face トークンが必要です。

トークンをまだ生成していない場合は、次の手順に沿って生成します。

1. [Your Profile] > [Settings] > [Access Tokens] の順にクリックします。
2. [New Token] を選択します。
3. 任意の名前と、少なくとも Read のロールを指定します。
4. [Generate a token] を選択します。
5. トークンをクリップボードにコピーします。

GKE 推論環境をプロビジョニングする

このセクションでは、モデルをサービングするために必要なインフラストラクチャをデプロイします。

Cloud Shell を起動する

このガイドでは、Cloud Shell を使用してコマンドを実行します。Cloud Shell には、gcloud、kubectl、git など、必要なツールがプリインストールされています。

Google Cloud コンソールで、Cloud Shell インスタンスを起動します。

Cloud Shell を開く

これにより、 Google Cloud コンソールの下部ペインでセッションが起動します。

ベース アーキテクチャをデプロイする

GKE クラスタと Hugging Face からモデルにアクセスするために必要なリソースをプロビジョニングするには、次の操作を行います。

1. Cloud Shell で、次のリポジトリのクローンを作成します。

   git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \
   cd accelerated-platforms && \
   export ACP_REPO_DIR="$(pwd)"
   

2. 環境変数を設定します。

   export TF_VAR_platform_default_project_id=PROJECT_ID
   export HF_TOKEN_READ=HF_TOKEN
   

   次の値を置き換えます。

   • PROJECT_ID: Google Cloudのプロジェクト ID。
   • HF_TOKEN: 先ほど生成した Hugging Face トークン。

3. このガイドでは、Terraform バージョン 1.8.0 以降が必要です。Cloud Shell には、デフォルトで Terraform v1.5.7 がインストールされています。

   Cloud Shell で Terraform のバージョンを更新するには、次のスクリプトを実行します。このスクリプトは、terraform-switcher ツールをインストールし、シェル環境を変更します。

   "${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
   source ~/.bashrc
   

4. 次のデプロイ スクリプトを実行します。デプロイ スクリプトは、必要な Google Cloud API を有効にし、このガイドに必要なインフラストラクチャをプロビジョニングします。これには、新しい VPC ネットワーク、プライベート ノードを含む GKE クラスタ、その他のサポート リソースが含まれます。スクリプトの完了には数分かかることがあります。

   GKE Autopilot クラスタまたは GKE Standard クラスタの GPU を使用してモデルをサービングできます。Autopilot クラスタは、フルマネージドの Kubernetes エクスペリエンスを提供します。ワークロードに最適な GKE のオペレーション モードの選択については、GKE のオペレーション モードについてをご覧ください。

   Autopilot

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-ap.sh"
   

   標準

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-standard.sh"
   

   このスクリプトが完了すると、推論ワークロード用の GKE クラスタが準備されます。

5. 次のコマンドを実行して、共有構成から環境変数を設定します。

   source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
   

6. デプロイ スクリプトは、Hugging Face トークンを保存する Secret Manager にシークレットを作成します。クラスタをデプロイする前に、このシークレットにトークンを手動で追加する必要があります。Cloud Shell で次のコマンドを実行して、トークンを Secret Manager に追加します。

   echo ${HF_TOKEN_READ} | gcloud secrets versions add ${huggingface_hub_access_token_read_secret_manager_secret_name} \
       --data-file=- \
       --project=${huggingface_secret_manager_project_id}
   

オープンモデルをデプロイする

これで、モデルをダウンロードしてデプロイする準備が整いました。

1. デプロイするモデルの環境変数を設定します。

   Gemma 3 27B-it

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="google/gemma-3-27b-it"
   

   Llama 4 Scout 17B-16E-Instruct

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="meta-llama/llama-4-scout-17b-16e-instruct"
   

   Qwen3 32B

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="qwen/qwen3-32b"
   

   gpt-oss 20B

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="openai/gpt-oss-20b"
   

   他のモデル バリアントや GPU タイプなど、その他の構成については、accelerated-platforms GitHub リポジトリで入手可能なマニフェストをご覧ください。

2. デプロイから環境変数を取得します。これらの環境変数には、プロビジョニングしたインフラストラクチャから必要な構成の詳細が含まれています。

   source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
   

3. 次のスクリプトを実行して、モデルを Cloud Storage にダウンロードする Kubernetes Job を構成します。

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"
   

4. モデル ダウンロード Job をデプロイします。

   kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"
   

5. ダウンロードが完了するまで待ちます。ジョブのステータスをモニタリングし、COMPLETIONS が 1/1 の場合は Ctrl+C を押して終了します。

   watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs
   

6. 推論ワークロードを GKE クラスタにデプロイします。

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/configure_deployment.sh"
   
   kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

デプロイをテストする

1. 推論サーバー Pod の準備が整うまで待ちます。READY 列が 1/1 の場合は、Ctrl+C を押して終了します。

   watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

2. 次のスクリプトを実行して、ポート転送を設定し、モデルにサンプル リクエストを送信します。この例では、Gemma 3 27b-it モデルのペイロード形式を使用します。

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
   PF_PID=$!
   curl http://127.0.0.1:8000/v1/chat/completions \
     --data '{
       "model": "/gcs/'${HF_MODEL_ID}'",
       "messages": [ { "role": "user", "content": "What is GKE?" } ]
     }' \
     --header "Content-Type: application/json" \
     --request POST \
     --show-error \
     --silent | jq
   kill -9 ${PF_PID}
   

   モデルから質問に回答する JSON レスポンスが表示されます。

クリーンアップ

課金されないようにするには、作成したすべてのリソースを削除します。

1. 推論ワークロードを削除します。

   kubectl delete --ignore-not-found --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

2. 基盤となる GKE クラスタを削除します。

   Autopilot

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-ap.sh"
   

   標準

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-standard.sh"
   

次のステップ

• GKE での AI/ML モデル推論の詳細を確認する。
• GKE Inference Quickstart ツールを使用して、モデル推論のパフォーマンスと費用を分析します。
• このアーキテクチャに基づいて構築されたGitHub の他のユースケースとパターンをご覧ください。