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

Autopilot Standard

---

このページでは、事前構成済みの本番環境対応のリファレンス アーキテクチャを使用して、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 ユーザーのロールとタスクをご覧ください。

始める前に

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Enable the APIs

• Make sure that you have the following role or roles on the project: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, and roles/serviceusage.serviceUsageAdmin

  Check for the roles

  1. In the Google Cloud console, go to the IAM page.

     Go to IAM
  2. Select the project.

  3. 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.

  4. 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

  1. In the Google Cloud console, go to the IAM page.

     IAM に移動
  2. プロジェクトを選択します。
  3. [ アクセスを許可] をクリックします。

  4. [新しいプリンシパル] フィールドに、ユーザー ID を入力します。 これは通常、Google アカウントのメールアドレスです。

  5. [ロールを選択] リストでロールを選択します。
  6. 追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。
  7. [保存] をクリックします。
  • Hugging Face アカウントを作成します。
  • プロジェクトに十分な GPU 割り当てがあることを確認します。詳細については、割り当てをご覧ください。

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

  注: 使用するゲート付きモデル（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 の他のユースケースとパターンをご覧ください。