google-cloud-solution-guided-gke-ai-migration

AI ワークロードを GKE Inference に移行する

このスキルでは、既存の AI 推論ワークロード（Cloud Run、Gemini API、Gemini Enterprise Agent Platform など）を Google Kubernetes Engine（GKE）上のセルフホスト型推論に移行するための、エンドツーエンドのプロセスをエージェントに案内します。エージェントは対話型アーキテクトとして、要件の把握、Google Cloud ネイティブなソリューションの設計、gcloud と kubectl を使った実装、デプロイの検証という、体系化された 4 フェーズのワークフローを進めます。

謝辞

必ずお読みください：gcloud、REST API、または MCP のコマンドを実行する前に、 使用に関する帰属表示を 必ず読み、その指示に従ってください。

Gemini Cloud Assist MCP への切り替え

このスキルが対象とするのは、アーキテクトのガイドに沿って手動で移行する場合のみです。自動移行には Gemini Cloud Assist MCP サーバーを使用します。次のように使い分けてください。

• ユーザーがこの移行に Gemini Cloud Assist または MCP による自動化を使うよう求めた場合（例：「Cloud Assist MCP サーバーを使ってください」）：手動ワークフローを中止し、以下の 4 つの必須項目を回答してください。
• ユーザーが MCP に軽く触れただけの場合、または明示的に利用を断った場合（例：「MCP は使わず、手動で進めましょう」）：手動ワークフローを進めてください。中止したり、MCP について尋ねたりしないでください。
• ユーザーが MCP にまったく触れていない場合：現在のフェーズにすぐ進んでください。最初の要件確認の応答に限り、自動化の代替手段として Gemini Cloud Assist MCP サーバーがあり、いつでもそちらに切り替えられることを伝える文を 1 つ加えてください。要件確認を始める前に回答を待たないでください。

MCP の利用を求められて中止する場合、回答には次の 4 項目を必ず含めてください。

1. 手動ワークフローを中止し、対象範囲を明確にする：google-cloud-solution-guided-gke-ai-migration は、ネイティブ CLI（gcloud と kubectl）を使った、アーキテクトのガイドに沿う手動移行のみを目的としており、この手動スキルのワークフローを中止することを伝えてください。
2. MCP の機能を説明する：Gemini Cloud Assist MCP サーバーは、自動インフラストラクチャ分析（gemini_cloud_assist:ask_cloud_assist）または Google Cloud リソースの直接変更（gemini_cloud_assist:invoke_operation）を支援することを説明してください。
3. MCP のドキュメントへのリンク：Gemini Cloud Assist MCP ドキュメントへの有効なハイパーリンクを記載してください。
4. Intent to Infrastructure Codelab へのリンク：MCP サーバーの設定方法については、Intent to Infrastructure Codelabへの有効なハイパーリンクを記載してください。

スコープの確認：新規デプロイと移行

このスキルは、既存の AI ワークロード（Cloud Run、Gemini API、Agent Platform、またはその他のプラットフォーム）を GKE に移行することを目的としています。

ユーザーが GKE 上に新しい AI モデルサーバーをゼロからデプロイしたいと考えており、移行対象となる既存のデプロイがない場合は、中止し、代わりに gke-inference スキルを使うよう案内してください。google-cloud-solution-guided-gke-ai-migration は、移行ワークフロー（既存の Cloud Run／Agent Platform の設定の確認、トラフィックの切り替えなど）に重点を置いている一方、gke-inference は AI プロファイルとゴールデンパスマニフェストを使った、GKE への新規 AI モデルサーバーのデプロイに最適化されていることを説明してください。

主なアーキテクチャ原則（「ゴールデンパス」）

ソリューションを設計する際は、常に最新の GKE AI のベストプラクティスを優先してください。

• 実行：
  • 実行ポリシー（コマンドを実行するのは誰か）：
    • フェーズ 1（調査）： ユーザーから許可を得た後、読み取り専用の gcloud 検査コマンド（list、describe）を直接実行し、結果を要約します。
    • フェーズ 2～4： マニフェストをディスクに書き込み、ユーザーが実行する正確な gcloud および kubectl コマンドを提示します。ユーザーから明示的に実行を依頼されない限り、変更を加えるコマンド（apply、create、delete、クラスターや IAM の変更）は実行しません。明示的に依頼された場合は実行し、各コマンドの実際の出力を報告します。
    • 情報提供やトラブルシューティングに関する質問： Markdown のガイダンス、マニフェスト、推奨コマンドのみを回答し、何も実行しません。
  • 生の Kubernetes マニフェスト、ネイティブ CLI（インフラストラクチャには gcloud、ワークロードには kubectl）、および意見を反映したテンプレートを優先します。
  • YAML ファイルをユーザーの現在のディレクトリに保存し、kubectl を使って適用します。
  • 必要不可欠な場合に限り、VRAM の計算などのアドホックスクリプトを作成します。
• ノードのプロビジョニング：
  • アクセラレータを確保できる可能性を最大化するため、**Custom Compute Classes（CCC）**を活用します（例：スポットとオンデマンド、または特定の GPU プロファイルを動的に選択）。
  • GKE のマネージド GPU ドライバーインストールを使用します。
  • 適切なノードトポロジーを選択します。単純なジョブには静的プール内の単一ノードを、大規模なジョブには LWS／CCC を使用した複数ノードを使用します。
• 推論スタックとバージョン管理：
  • LLM の標準サービングエンジンには、デフォルトで vLLM（vllm/vllm-openai）を使用します。Vertex AI から移行する場合は、ユーザーが Vertex AI Model Garden のイメージ（例：pytorch-vllm-serve）を引き続き使用することもできます。
  • エントリーポイントの明示的な上書き： 選択したイメージにかかわらず、vLLM Deployment では command: ["python", "-m", "vllm.entrypoints.openai.api_server"] を必ず明示的に設定し、標準の vLLM 引数を渡すとクラッシュする可能性のあるエントリーポイントスクリプト（Vertex AI イメージ内の gcs_download_launcher.sh など）を回避します。
  • 明示的で安定した vLLM イメージタグを必ず固定し、:latest は使用しません。設計時に現在の安定版リリースを確認し（vLLM のリリースページを確認するか、gcloud container ai profiles manifests create の出力からタグを取得）、migration-state.md に記録します。以前の移行時に記憶したタグや、ドキュメントの例に記載されたタグを再利用しないでください。
  • GKE Gateway API を通じてサービスを公開します。デフォルトではリージョナル内部 Application Load Balancer（gatewayClassName: gke-l7-rilb）を使用し、assets/gke-inference-gateway.yaml.tmpl に基づいて、/v1 リクエストを vLLM の ClusterIP サービス（{workload_name}-vllm-svc）のポート 8000 に送信する HTTPRoute を設定します。
  • KV キャッシュの使用率、キューの深さ、LoRA アダプターの配置に基づくルーティングなど、LLM を考慮したロードバランシングが必要な場合は、アップグレードとして GKE Inference Gateway を提案します。HTTPRoute のバックエンドには Service ではなく InferencePool リソースが必要で、対応する GatewayClass は gke-l7-rilb と gke-l7-regional-external-managed のみです。InferencePool マニフェストを生成する前に、GKE Inference Gateway についてを取得してください。記憶を頼りに作成してはいけません。
  • マルチノードモデルには **LeaderWorkerSet（LWS）**と vLLM を使用します。
• セキュリティとアクセス：
  • Google Cloud API にアクセスする際は、必ず GKE Workload Identity を使用します。
  • ゲート付きモデルのシークレットのセキュリティ： Hugging Face トークン（HF_TOKEN）が必要なゲート付きモデル（例：Llama 3、Gemma）では、以下を守ります。
    • Deployment または Pod の仕様にトークン値を直接記述してはいけません。env.valueFrom.secretKeyRef を使って、シークレットを安全に参照します（例：hf-secret を参照）。
    • 機密性の高い API トークンをプレーンテキストのプロンプトやマニフェストファイルに公開するリスクについて、必ずユーザーに警告します。
    • Kubernetes の Secret マニフェストをディスクに書き込んではいけません。また、テンプレートにも含めないでください。その代わり、他のマニフェストを適用する前に、ユーザー自身が CLI から直接 Secret を作成するよう明示的に指示します。コマンドは kubectl create secret generic hf-secret --namespace={namespace} --from-literal=hf_api_token=<YOUR_HF_TOKEN> とし、実際の値はユーザー自身が入力します。
    • ユーザーがすでに会話にトークンを貼り付けている場合、そのトークンは漏えいしたものとして扱います。作成するすべてのコマンドとマニフェストで <YOUR_HF_TOKEN> プレースホルダーを使用し、移行完了後に https://huggingface.co/settings/tokens でトークンを失効させ、新しく発行するようユーザーに助言します。
  • エンドポイントの公開： デフォルトでは Gateway に内部クラス（gke-l7-rilb）を使用します。vLLM の OpenAI 互換エンドポイントには認証機能が組み込まれていません。外部公開が必要な場合は、認証されていない外部リスナーは GPU の料金が発生するオープンな推論 API になることを明示的に警告します。また、外部公開用の Gateway マニフェストを生成する前に、ユーザーの明示的な決定と、前段に配置するアクセス制御（IAP、認証機能付き API ゲートウェイ、または厳格なクライアント許可リスト）を必須とします。
• モデルストレージとコールドスタート：
  • 選択したモデルを Cloud Storage バケットにステージングし、ダウンロードを一度で済ませます。
  • クラスター上の Job でステージングを実行： クラスターの Job を使って重みをステージングすると、重い重みをローカルのワークステーションにダウンロードせずに済み、コンテナが再起動するたびにダウンロードし直す必要もなくなることをユーザーに説明します。ステージングマニフェストは必ず model-staging-job.yaml として保存し、kubectl apply -f model-staging-job.yaml を実行するようユーザーに指示します。
  • ソース／ターゲットに応じたステージング方法：
    • ソースが Hugging Face（gCS FUSE または Lustre のターゲット）： ステージング Job を使って重みを PVC に直接ダウンロードします。
    • ソースが GCS（GCS FUSE のターゲット）： ステージング Job は任意です。PVC が FUSE を介して GCS バケットを直接マウントする場合、重みにはすでにアクセスできるため、ステージングは不要です。
    • ソースが GCS（Lustre のターゲット）： ステージング Job を使って、ソースの GCS バケットから Lustre PVC に重みをコピーします（例：gcloud storage cp）。
  • ほとんどのワークロードでは Cloud Storage FUSE による Cloud Storage のステージングを優先し、超低レイテンシや PiB 規模のニーズには Managed Lustre を使用します。
  • Cloud Storage FUSE ボリュームをマウントするすべての Pod には、Pod アノテーション gke-gcsfuse/volumes: "true" を必ず付与します（これにより FUSE サイドカーが挿入されます）。また、Workload Identity を介してモデルバケットに対する roles/storage.objectUser が付与された Google サービスアカウントにバインドされている Kubernetes ServiceAccount として、必ず実行します。どちらか一方でも欠けると、マウントに失敗するか、読み取りに失敗します。ストレージに関する他のトラブルシューティングを行う前に、両方を確認してください。
• オブザーバビリティ：
  • GPU を詳細に可視化するため、デフォルトで DCGM メトリクスを使用する Google Cloud Managed Service for Prometheus を利用します。
• オートスケーリング：
  • ユーザーが Horizontal Pod Autoscaling（HPA）を望んでいると決めつけてはいけません。調査時に必ず確認します。
  • HPA が不要な場合は、オートスケーリング関連のマニフェストをすべて省きます。
  • HPA を希望する場合は、LLM オートスケーリングの落とし穴について警告します。vLLM は KV キャッシュ用に VRAM を事前確保するため、CPU、メモリ、GPU メモリの標準的な使用率メトリクスは信頼できず、常に高使用率のように見えます。
  • 実際の同時実行数やキューの深さ（例：vllm:num_requests_waiting またはバッチサイズ）を示すカスタムサーバーメトリクスに基づくスケーリングを推奨します。
  • ユーザーが別のメトリクスを指定しない限り、妥当なデフォルトとしてキューサイズを含めます。
  • 実装には GKE Custom Metrics（Stackdriver Adapter）または KEDA を使用できます。

ワークフロー

ソリューションの設計および実装ワークフローは、次の4つのフェーズで構成されます。

• フェーズ 1：調査： gcloud を使用して既存のインフラストラクチャを調査し、モデルやトラフィックの要件を収集します。
• フェーズ 2：ソリューション設計： VRAM 要件を計算し、ハードウェアとストレージを選定して、Kubernetes マニフェストを生成します。
• フェーズ 3：実装： リソースをプロビジョニングし、一時的なポッドを介してモデルの重みを配置し、kubectl を使用してワークロードのマニフェストを適用します。
• フェーズ 4：検証と切り替え： ポッドの健全性とエンドポイントでの推論を確認し、その後、トラフィックの移行方法を案内します。

すべてのアーキテクチャに関する回答の冒頭に、ユーザーとモデルの双方が現在のフェーズを把握できるよう、簡潔な進捗インジケーターを1行で表示します。

**Migration Progress:** [● Discovery] ➔ [○ Solution Design] ➔ [○ Implementation] ➔ [○ Validation]

(現在のアクティブなフェーズを示すために ● を更新します。たとえば、フェーズ 2 では [● ソリューション設計] とします。)

フェーズの振り分けルール

ユーザーのプロンプトの内容に基づいて、アクティブなフェーズを判断します。

現在のディレクトリに migration-state.md がある場合は、ほかの作業をする前にそれを読み、記録された値を使って記録されたフェーズから再開します。値がファイルに記録されていない場合、またはユーザーのプロンプトと矛盾している場合に限り、調査に関する質問を再度行ってください。

• フェーズ 1（調査）： 事前の調査を行っていない、新規の移行依頼に使用します。
• フェーズ 2（ソリューション設計）： 調査が完了したことをプロンプトが示している場合、またはアーキテクチャの設計や YAML マニフェストの生成を求めている場合に使用します。
• フェーズ 3（実装）： モデルの重みが配置済みであることをプロンプトが示している場合、またはデプロイ手順やコマンドを直接求めている場合に使用します。進捗インジケーター：**移行の進捗：** [○ 調査] ➔ [○ ソリューション設計] ➔ [● 実装] ➔ [○ 検証]。
• フェーズ 4（検証）： ワークロードが実行中であることをプロンプトが示している場合、または健全性チェックやテスト手順を求めている場合に使用します。

フェーズ 1：調査

フェーズ 1 の目標は、ターゲットとなる GKE 推論インフラストラクチャの設計と構築に必要な、すべてのワークロード仕様を把握することです。

フェーズ 1 の回答要件： フェーズ 1 のすべての回答は、必ず次の視覚的な進捗インジケーターから始めてください：**移行の進捗：** [● 調査] ➔ [○ ソリューション設計] ➔ [○ 実装] ➔ [○ 検証]。

検出チェックリスト（特定すべき属性）

エージェントは、次の6つの主要な属性カテゴリを特定するか、確認する必要があります。

• ソースプラットフォームとサービス構成：

  • ソースプラットフォーム（Cloud Run、Gemini API、Gemini Enterprise Agent Platform、カスタム VM）。
  • コンテナイメージタグ、環境変数、CPU／RAM の割り当て、シークレットのバインド。

• モデルの仕様：

  • モデル名とパラメータ数（例：Gemma 2 9B、Llama 3 70B）。
  • 目標精度と量子化の許容範囲（FP16／BF16 と INT8／INT4 AWQ のどちらか）。検出時に量子化の許容範囲について必ず確認してください。
  • ゲート付きモデルかどうか（Hugging Face のトークン HF_TOKEN によるアクセスが必要かどうか）。
  • モデル固有のアーキテクチャ要件： モデルカード（例：Hugging Face 上）または config.json を確認し、カスタム構成要件を明示的にチェックしてください。たとえば、アーキテクチャで --trust-remote-code（Qwen モデルなど）、特定の rope scaling 引数、その他のカスタムフラグが必要かどうかを特定してください。

• ターゲット GKE とハードウェアインフラストラクチャ：

  • ターゲット GKE クラスター名とリージョン（または、新しいクラスターを作成するかどうかの確認）。
  • アクセラレーターの希望（L4、A100、H100、TPU v5e）とプロビジョニングモデル（Spot／CCC またはオンデマンド）。
  • リクエストされた GPU／TPU のリージョン別クォータの利用可能状況。

• モデルのストレージとステージング：

  • モデルの重みの現在の保存場所（GCS バケット、Hugging Face Hub、外部 URL）。
  • 希望するストレージ統合方式（Cloud Storage FUSE または Managed Lustre）。

• トラフィックプロファイルとロードバランシング：

  • 想定されるトラフィック量、同時実行数、リクエストパターン（急増型または一定のベースライン）。
  • ロードバランシングの要件（GKE Inference Gateway、標準の Ingress／Service）。
  • 自動スケーリングの要件： Horizontal Pod Autoscaling（HPA）が必要かどうかをユーザーに確認してください。必要だと決めつけてはいけません。必要な場合は、目標メトリクス（デフォルトは Queue Size）を特定し、LLM 自動スケーリングの落とし穴について説明してください。

• モデルの同等性（Gemini API／Agent Platform がソースの場合のみ）：

  • 使用中の Gemini モデルと API 機能（関数呼び出し、システム指示、コンテキスト長、マルチモーダル入力）。
  • 置き換え先となるオープンウェイトモデルと、切り替え前に現在のシステムと比較して出力品質を評価する方法。
  • クライアントへの影響：vLLM エンドポイントは OpenAI 互換であり、Gemini API 互換ではありません。変更が必要なクライアントコードと SDK 呼び出しを特定してください。

検出の実行（自動および対話型）

• インフラへのアクセスと権限を最初にリクエストする： 検出コマンドを実行する前に、CLI コマンド（gcloud run services list や gcloud run services describe など）を使って既存の環境リソースを調査する許可を、必ずユーザーに明示的に求めてください。
• 承認後に調査する： ユーザーから許可を得たら、gcloud CLI コマンドを実行し、環境変数を調べ、ローカルワークスペースのファイルを確認して、チェックリスト項目を自動的に入力します。
  • Cloud Run ワークロード： gcloud run services list --format="table(metadata.name,status.url,status.latestReadyRevisionName)" を実行してサービスを列挙し、次に gcloud run services describe {service_name} --format="yaml(spec.template.spec.containers,spec.template.metadata.annotations,spec.template.spec.serviceAccountName,spec.template.spec.containerConcurrency)" を実行して、コンテナーイメージ、環境変数、リソース制限、同時実行数、シークレットのバインディングのみを抽出します。検出コマンドではすべて --format フィルターを優先し、フィルターなしでリソースの説明全体を会話に取り込まないでください。
  • 既存の GKE クラスター： gcloud container clusters list と gcloud container clusters describe {cluster_name} を実行して、アクティブなクラスター設定、Workload Identity のセットアップ、利用可能なアクセラレータープールを調査します。
  • Vertex AI／ストレージ： gcloud ai endpoints list または gcloud storage buckets list を実行して、モデルアーティファクトとストレージバケットを特定します。
  • ワークスペースと環境： アクティブなワークスペースディレクトリ内のローカル設定ファイルまたは環境変数を調査します。
• 要約し、不足項目を確認して、承認を得る： 検出した設定データをまとめて提示し、残っている不足属性についてユーザーに確認します。チェックリスト項目に未解決または曖昧なものがある場合は、フェーズ 2 に進む前にユーザーから明示的な確認を得てください。すべてのチェックリスト項目が曖昧さなく解決済みの場合は、検出結果の要約とフェーズ 2 のソリューション設計を、単一の承認ゲートのもとで同じ応答内に提示してもかまいません。この場合、設計への承認は両方を対象とします。
• 検出状態を保存する： ユーザーが検出結果の要約を確認した後、確認済みの値をチェックリストのカテゴリごとに 1 つのセクションにまとめ、最後の行に Current phase: <phase name> を記した内容を、現在のディレクトリにある migration-state.md に書き込みます。ワークフローが次のフェーズに進むたびに、Current phase: の行を更新してください。

フェーズ 2：ソリューション設計

検出フェーズの結果に基づき、移行を実現するために必要なアーキテクチャとマニフェストを設計します。

フェーズ 2 の応答要件： フェーズ 2 でのすべての応答は、視覚的な進行状況インジケーター **Migration Progress:** [○ Discovery] ➔ [● Solution Design] ➔ [○ Implementation] ➔ [○ Validation] で始めてください。

必要に応じたコンテキストの読み込み： 以下の特定のアーキテクチャ上の選択肢（ストレージオプション、ロードバランシング、自動スケーリングなど）を評価する際は、必要に応じて Supporting links セクションの関連するリファレンスドキュメントを取得して読みます。

1. コンポーネントと代替案の整理： 負荷分散、自動スケーリング、シングルノードとマルチノードなど、主要な各コンポーネントについて、推奨する「ゴールデンパス」の選択肢と代替案を提示します。ユーザーが HPA をリクエストした場合は、設計で LLM の自動スケーリングの落とし穴に対処し、カスタムメトリクス（デフォルトはキューサイズ）を推奨してください。
2. アクセラレータの選択： GPU プラットフォームまたは GKE での TPU 構成の計画を参照して、対象モデルに最適なアクセラレータを推奨します。 （注：assets/ のマニフェストテンプレートは GPU 専用です。ユーザーが Cloud TPU を選択した場合は、その旨を明記し、このスキルのテンプレートではなく、GKE の TPU サービングドキュメントに基づいてサービング用マニフェストを作成してください。）
3. ストレージの選択： GCP AI ストレージの選択肢を参照して、モデルのステージングとサービングに最適なストレージソリューションを推奨します。
4. ハードウェアと VRAM のサイジング： 下記の決定論的 VRAM サイジング式を使用して、パラメーター、コンテキストウィンドウ、量子化に基づき、VRAM を正確に計算します。適切な GPU（L4、A100、H100）を選定します。
5. クラスターとノードの設定： タスクに適したクラスターを設計します。Custom Compute Classes（CCC）を使用して、タスクに適したサイズのノードを追加します。必要に応じて Workload Identity を設計します。vLLM Deployment では、ワークロードが実際に ComputeClass 経由でスケジュールされるよう、nodeSelector: cloud.google.com/compute-class: {compute_class_name} を必ず指定してください。ユーザーが CCC を使用せず、オンデマンドノードのみを希望する場合は、このセレクターを cloud.google.com/gke-accelerator: {accelerator_type} に置き換え、ccc-profile.yaml は一切適用しないでください。どのワークロードからも参照されない ComputeClass を適用してはいけません。
6. モデルのステージング設計： モデルの重みの取得元と対象のストレージソリューションに基づき、ステージング Job が必要かどうかを判断します。取得元が Hugging Face の場合、または対象が Lustre で取得元が GCS の場合は、重みをダウンロード／コピーする Job を計画します。取得元が GCS で、対象が GCS FUSE の場合は、ステージングを省略します。Cloud Storage FUSE または Lustre CSI を使用して、このストレージをワークロードにマウントする方法を計画します。
7. ソリューションアーキテクチャとマニフェストの作成： assets/ のマニフェストテンプレート（assets/vllm-deployment.yaml.tmpl、assets/ccc-profile.yaml.tmpl、assets/gke-inference-gateway.yaml.tmpl、assets/storage-config.yaml.tmpl、assets/model-staging-job.yaml.tmpl）を読み込み、フェーズ 1 で確認したパラメーターを反映して、生成した YAML マニフェスト（vllm-deployment.yaml、ccc-profile.yaml、gke-inference-gateway.yaml、storage-config.yaml、model-staging-job.yaml）を現在のディレクトリに保存します。vllm-deployment.yaml の作成時には、フェーズ 1 で確認したモデル固有のアーキテクチャフラグ（例：--trust-remote-code）を、コンテナの args 配列に必ず追加します。gke-inference-gateway.yaml の作成時には、assets/gke-inference-gateway.yaml.tmpl に基づいて作成します。ユーザーが外部公開または InferencePool ベースの GKE Inference Gateway を明示的に選択していない限り、Gateway リソースでは gatewayClassName: gke-l7-rilb を使用し、HTTPRoute リソースでは /v1 のトラフィックを vLLM の ClusterIP サービス（ポート 8000 の {workload_name}-vllm-svc）にルーティングします。ストレージクラスに gcsfuse-csi 以外（例：lustre-csi）を使用する場合は、storage-config.yaml から gcsfuse.cloud.google.com のアノテーションを削除します。
8. レビューの依頼と反復： 生成したソリューションアーキテクチャと図をユーザーに提示し、フィードバックを求めます。フェーズ 3 に進む前に、ユーザーの承認が得られるまで設計を反復します。

決定論的なVRAMサイジング計算式

モデルのサービング／推論に必要なVRAMを正確に計算するには、以下の決定論的な計算式を使用してください。

ハードウェアとサイジングの推奨要件： VRAMのサイジングやハードウェアの推奨を行う場合：

• 以下の計算式を使って、VRAMの計算方法（パラメーターサイズ、KVキャッシュ、20％の安全マージン）を明示してください。
• 特定のアクセラレーターの種類を推奨してください（例：FP16／BF16の8Bモデルには、VRAM 24 GBのNVIDIA L4）。
• アクセラレーターを確保しやすくするため、Custom Compute Classes (CCC) の使用を推奨してください。
• ディスカバリーフェーズで、ユーザーに量子化の許容範囲（FP16／BF16とINT8／INT4のどちらか）を確認するか、すでに確認済みか確かめてください。

$$VRAM_{\text{total}} = \left( \frac{\text{Parameters} \times 2}{\text{Quantization}} + KV_Cache_Overhead \right) \times 1.2$$

ここで：

• Parameters：モデルのパラメーター数（単位：10億）。例：8Bの場合は8、70Bの場合は70。
• Quantization：16ビット（FP16／BF16）を基準とした、対象の精度に応じた除数：
  • 1：16ビット（FP16／BF16、1パラメーターあたり2バイト）
  • 2：8ビット（FP8／INT8、1パラメーターあたり1バイト）
  • 4：4ビット（INT4／AWQ／GPTQ、1パラメーターあたり0.5バイト）
• $KV_Cache_Overhead$：生成中のキー・バリューキャッシュ用に確保するメモリー（GB）： $$KV_Cache_Overhead ,(GB) = \frac{2 \times n_{\text{layers}} \times n_{\text{kv_heads}} \times d_{\text{head}} \times \text{Context Length} \times \text{Batch Size} \times \text{Precision Bytes}}{10^9}$$ (経験則：モデルのレイヤー構成の詳細が不明な場合は、$KV_Cache_Overhead \approx 0.2 \times \text{Model Weight Memory}$と見積もります。)
• 1.2の乗数：CUDAコンテキスト、アクティベーションメモリー、サービングエンジンのオーバーヘッドに対する20％の安全マージンです。

計算結果をアクセラレーターに当てはめる際は、--gpu-memory-utilizationによって割り引かれたメモリーではなく、カードの総メモリー（例：L4の場合は24 GB）と$VRAM_{\text{total}}$を比較してください。1.2の乗数とvLLMの使用率上限は、同じオーバーヘッドに対する余裕を確保します。両方を適用するとマージンを二重に計上し、必要なアクセラレーターのグレードを一段階引き上げてしまいます。

フェーズ 3：実装

実行ポリシーに従って承認済みの設計を実施します。以下のコマンドを生成し、ユーザーに提示するか、ユーザーから実行するよう依頼された場合は実行して出力を報告します。

1. デプロイの前提条件を確認する： 請求先、API、IAM 権限が整っていることを確認します。
2. インフラストラクチャのプロビジョニング： ストレージとクラスターの前提条件をプロビジョニングする明示的な gcloud コマンド（Cloud Storage FUSE CSI ドライバーの有効化など）を提示し、Workload Identity の IAM バインディングを構成します。Gateway API の事前確認： クラスターで Gateway API が有効になっていることをユーザーに明示的に確認するよう指示します。ルーティングマニフェストを適用する前に CRD-not-found エラーを防ぐため、gcloud container clusters update <CLUSTER_NAME> --gateway-api=standard の実行を推奨します。
3. ストレージのプロビジョニング： 必要なストレージリソース（Cloud Storage バケットまたは Managed Lustre ファイルシステム）を作成します。
4. モデルのステージング： フェーズ 2 の設計に基づいて条件分岐を適用します。
   • スキップ： モデルがすでに GCS にあり、GCS FUSE を使用している場合は、ステップ 5 に進みます。
   • Hugging Face ソース： ゲート付きモデル（Llama 3、Gemma など）を使用する場合は、ジョブまたはデプロイを適用する前に、ユーザーがローカルで kubectl create secret generic hf-secret ... コマンドを実行するよう明示的に指示します（ゲート付きモデルのシークレットセキュリティルールを参照）。シークレットの作成後、kubectl apply -f model-staging-job.yaml を実行するよう指示します。
   • GCS から Lustre へのソース： kubectl apply -f model-staging-job.yaml を実行するよう指示します（gcloud storage cp などを使用するよう構成します）。
   • 完了ゲート： ステージングジョブが実行された場合は、kubectl wait --for=condition=complete job/{workload_name}-model-staging --timeout=90m で完了を確認します（タイムアウトはモデルサイズに合わせて調整します）。ジョブが失敗した場合は、再試行する前に kubectl logs job/{workload_name}-model-staging で調査します。クラスター内のジョブでステージングすることで、ユーザーのワークステーションへの大容量の重みのダウンロードを避け、コンテナを再起動するたびに再ダウンロードすることも避けられると説明します。
5. ワークロードのデプロイ： ストレージ設定（kubectl apply -f storage-config.yaml）、ComputeClass（kubectl apply -f ccc-profile.yaml）、vLLM デプロイ（kubectl apply -f vllm-deployment.yaml）、Inference Gateway（kubectl apply -f gke-inference-gateway.yaml）をデプロイする明示的な kubectl apply コマンドを提示します。vLLM のデプロイ仕様で、PVC からステージング済みのモデルの重みを /models にマウントするようにします。ゲート付きモデル用のシークレットを作成した場合は、そのシークレットがデプロイマニフェストで正しく参照されるようにします。vLLM の --model フラグには、ステージング済みのローカルパス（/models/{model_name}）を設定し、Hugging Face のリポジトリ ID は絶対に指定しないでください。リポジトリ ID を指定すると、vLLM はポッドの起動ごとに重み全体を再ダウンロードし、ステージング手順の効果が気付かれないまま失われます。API クライアント向けにモデルの公開名を維持するには、--served-model-name={model_id} を指定します。
6. ロールアウトを検証する： kubectl rollout status deployment/{workload_name}-vllm --timeout=30m および kubectl get pods -l app={workload_name}-vllm -o wide で成功を確認します。ロールアウトに失敗した場合、またはタイムアウトした場合は、確認されたエラーを添えて直ちにトラブルシューティングのガイダンスに進みます。コマンド出力ですでに結果が分かる場合は、デプロイが成功したかどうかをユーザーに尋ねないでください。クラスターでは確認できない結果（たとえば、応答品質がソースシステムと一致しているかどうか）についてのみ、ユーザーに尋ねます。

フェーズ 4：検証と切り替え

デプロイしたインフラストラクチャがワークロードの要件を満たしていることを検証し、トラフィックを移行する手順を提示します。

フェーズ 4 の応答要件： フェーズ 4 中のすべての応答は、必ず次の進捗インジケーターで始めてください：**Migration Progress:** [○ Discovery] ➔ [○ Solution Design] ➔ [○ Implementation] ➔ [● Validation]。

1. ヘルスチェック： Pod、ノード、ゲートウェイの状態を検証するため、具体的なヘルスチェックコマンド（kubectl get pods、kubectl get nodes、kubectl get gateway）を推奨してください。
2. 推論テスト： サービスがモデルを提供していることを検証します。kubectl port-forward コマンド（kubectl port-forward svc/{workload_name}-vllm-svc 8000:8000）と、エンドポイントの推論をテストするための /v1/chat/completions への curl リクエスト例を提示してください。該当する場合は、以前のインフラストラクチャでの応答と比較してください。
3. トラフィック切り替えのガイダンス： トラフィックの移行を自動で実装しないでください。代わりに、次の内容を提示してください。
   • トラフィックを受け入れる準備ができている内部 GKE エンドポイントを提示します。
   • 関連するコードベースがある場合は、それに基づいてトラフィックを移行する方法を提案します。
   • 高度なカナリアテストやブルー／グリーンデプロイではなく、既存のデプロイメントマニフェストを更新して新しいサービスを参照するなど、標準的な GKE ロールアウトを提案します。
   • ユーザーが明示的に求めた場合にのみ、より高度なトラフィック移行の選択肢を提示します。
4. ロールバックの準備： トラフィックを移行する前に、ユーザーが選択した期間にわたり GKE エンドポイントが本番トラフィックを処理するまで、ソースサービスをデプロイした状態に維持することを確認してください（スケールダウンは問題ありませんが、削除してはいけません）。ソースにトラフィックを戻す単一のコマンドまたは設定変更を提示してください。ユーザーが移行の安定を宣言した後に限り、ソースサービスを廃止するコマンドを提示してください。
5. 検証レポートの作成と最終承認の依頼： すべてのヘルスチェックの結果と推論テストの結果をまとめた検証レポートを作成してください。移行ワークフローを完了して確定するため、ユーザーに最終承認を明示的に求めてください。

トラブルシューティングのガイダンス

Pod が作成されるものの推論エンドポイントが応答しないという問題がユーザーから報告された場合（またはトラブルシューティングの支援を求められた場合）は、次の対応を行ってください。

1. 具体的な診断コマンドを推奨してください。コンテナの起動ログを確認するには kubectl logs {pod_name}、Pod の初期化状態を調べるには kubectl describe pod {pod_name} を使用します。
2. 必要なリソースをプロビジョニングできるよう、対象リージョンの Google Cloud アクセラレータ（GPU／TPU）のクォータを確認するよう提案してください。
3. JIT コンパイル／起動遅延を確認する： curl が Connection refused を返しても Pod が Running の場合、サービングエンジン（vLLM など）が JIT コンパイル（Triton PTX や Torch Inductor など）または CUDA グラフのキャプチャを実行中の可能性があります。これはモデルの重みをロードした後も数分かかることがあります。ネットワークの問題だと判断する前に、kubectl logs {pod_name} を確認し、Uvicorn running on http://0.0.0.0:8000（または同等の）ログメッセージが出るまで明示的に待つようユーザーに案内してください。
4. GKE Workload Identity のバインディング、PVC のマウント状態（Cloud Storage FUSE）、GKE Inference Gateway のリスナー設定を確認するよう推奨してください。

参考リンク

設計上の判断の根拠として、ユーザーの質問への回答や実装マニフェストの生成に、必要に応じて以下の資料を参照してください。

• GPU プラットフォーム
• GKE で TPU 構成を計画する
• Gemini Cloud Assist MCP ドキュメント
• GKE での AI/ML モデル推論について
• GKE での AI/ML モデル推論に適したロードバランシング戦略を選択する
• Google Kubernetes Engine で GPU を使用した大規模言語モデル推論ワークロードを自動スケーリングするためのベストプラクティス
• Google Cloud の AI ストレージ オプション
• Cloud Storage FUSE で AI/ML ワークロードを最適化する
• Managed Lustre で AI/ML ワークロードを最適化する