事前構成されたアーキテクチャで TPU を使用して、GKE でオープン LLM をサービングする

Autopilot Standard

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

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

• Google Gemma 3 1B-it
• Google Gemma 3 4B-it
• Google Gemma 3 27B-it

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

このガイドは、推論用のオープンモデルのサービングに 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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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 アカウントを作成します。
  • プロジェクトに十分な TPU 割り当て（GKE Standard）または TPU 割り当て（GKE Autopilot）があることを確認します。詳細については、GKE で TPU を計画するをご覧ください。

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

  それぞれの Hugging Face モデルページで、使用するゲート付きモデル（Gemma など）に対して、ライセンス条項に同意します。

  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-vllm-tpu-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 のバージョンを更新するには、次のスクリプトを実行します。このスクリプトは、tfswitch ツールをインストールし、ホーム ディレクトリに Terraform v1.8.0 をインストールします。スクリプトの指示に従って、必要な環境変数を設定するか、--modify-rc-file フラグをスクリプトに渡します。

     "${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
     export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
     

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

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

     Autopilot

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

     Standard

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-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 1B-it

     export ACCELERATOR_TYPE="v5e"
     export HF_MODEL_ID="google/gemma-3-1b-it"
     

     Gemma 3 4B-it

     export ACCELERATOR_TYPE="v5e"
     export HF_MODEL_ID="google/gemma-3-4b-it"
     

     Gemma 3 27B-it

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

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

  モデルをダウンロードする

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

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

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

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

  3. Hugging Face モデルのダウンロード リソースを適用します。

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

  4. Hugging Face モデルのダウンロード ジョブが完了するまでモニタリングします。

     until kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} wait job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --for=condition=complete --timeout=10s >/dev/null; do
         clear
         kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
         echo -e "\nhf-model-to-gcs logs(last 10 lines):"
         kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} logs job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --container=hf-model-to-gcs --tail 10
     done
     

  5. Hugging Face モデルのダウンロード ジョブが完了したことを確認します。

     kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
     

  6. Hugging Face モデルのダウンロード リソースを削除します。

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

  モデルをデプロイする

  1. デプロイから環境変数を取得します。

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

  2. Hugging Face モデル名が設定されていることを確認します。

     echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
     

  3. vLLM リソースを構成します。

     "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-tpu/vllm/configure_vllm.sh"
     

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

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

  デプロイをテストする

  1. 推論ワークロードのデプロイが使用可能になるまでモニタリングします。

     until kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
         clear
         kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
         echo -e "\nfetch-safetensors logs(last 10 lines):"
         kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
         echo -e "\ninference-server logs(last 10 lines):"
         kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
     done
     

  2. 推論ワークロードのデプロイが利用可能であることを確認します。

     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
     echo -e "\nfetch-safetensors logs(last 10 lines):"
     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
     echo -e "\ninference-server logs(last 10 lines):"
     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
     

  3. 次のスクリプトを実行してポート転送を設定し、モデルにサンプル リクエストを送信します。

     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
     PF_PID=$!
     while ! echo -e '\x1dclose\x0d' | telnet localhost 8000 >/dev/null 2>&1; do
         sleep 0.1
     done
     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-tpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  2. リソースをクリーンアップします。

     Autopilot

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

     Standard

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

  次のステップ

  • GKE での AI / ML モデル推論について詳細を確認する。
  • GKE Inference Quickstart ツールを使用してモデル推論のパフォーマンスと費用を分析する。
  • このアーキテクチャの構築に使用される accelerated-platforms GitHub リポジトリを確認する。