llm-d を搭載した GKE Inference Gateway をデプロイする

このドキュメントでは、GKE Inference Gateway をデプロイする方法について説明します。

このドキュメントは、GKE インフラストラクチャの管理を担当するネットワーク スペシャリストと、AI ワークロードを管理するプラットフォーム管理者を対象としています。

このページを読む前に、次のことをよく理解しておいてください。

GKE Inference Gateway は、Google Kubernetes Engine（GKE）Gateway を拡張して、GKE での生成 AI アプリケーションとワークロードの提供を最適化します。これにより、AI ワークロードの効率的な管理とスケーリングが可能になり、レイテンシなどのワークロード固有のパフォーマンスの目標を実現できます。また、リソース使用率、オブザーバビリティ、AI の安全性が向上します。

始める前に

作業を始める前に、次のタスクが完了していることを確認してください。

  • Google Kubernetes Engine API を有効にする。
    • Google Kubernetes Engine API を有効化
  • このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。gcloud CLI をインストール済みの場合は、gcloud components update コマンドを実行して最新のバージョンを取得します。以前のバージョンの gcloud CLI では、このドキュメントのコマンドを実行できない場合があります。

  • 必要に応じて、Compute Engine API、Kubernetes Engine API、Network Services API、Model Armor API を有効にします。

    API へのアクセスを有効にするに移動し、手順に沿って操作します。

  • プロジェクトに roles/container.admin、roles/iam.serviceAccountAdmin のロールがあることを確認します。

  • H100 GPU 用にプロジェクトに十分な割り当てがあることを確認します。詳細については、GPU 割り当てを計画すると数量に基づく割り当てをご覧ください。

  • Hugging Face アカウントを作成します（まだ作成していない場合）。このチュートリアルのモデルリソースにアクセスするには、次が必要です。

  • Llama 3.1 モデルへのアクセス権をリクエストし、アクセス トークンを生成します。このモデルにアクセスするには、Hugging Face でリクエストが承認されている必要があります。アクセス権が付与されていない場合、デプロイは失敗します。

    • ライセンス同意契約に署名する: Llama 3.1 モデルを使用するには、同意契約に署名する必要があります。Hugging Face でモデルのページに移動し、アカウントを確認して、利用規約に同意します。
    • アクセス トークンを生成する: モデルにアクセスするには、Hugging Face トークンが必要です。Hugging Face アカウントで、[Your Profile] > [Settings] > [Access Tokens] の順に移動し、少なくとも読み取り権限を持つ新しいトークンを作成して、クリップボードにコピーします。

GKE Gateway コントローラの要件

  • GKE バージョン 1.32.3 以降。
  • Google Cloud CLI バージョン 407.0.0 以降。
  • Gateway API は、VPC ネイティブ クラスタでのみサポートされます。
  • プロキシ専用サブネットを有効にする必要があります。
  • クラスタで HttpLoadBalancing アドオンが有効になっている必要があります。
  • Istio を使用している場合は、Istio を次のいずれかのバージョンにアップグレードする必要があります。
    • 1.15.2 以降
    • 1.14.5 以降
    • 1.13.9 以降
  • 共有 VPC を使用している場合は、ホスト プロジェクトで、サービス プロジェクトの GKE サービス アカウントに Compute Network User ロールを割り当てる必要があります。

制限事項

次の制限事項があります。

  • マルチクラスタ Gateway はサポート対象外です。
  • GKE Inference Gateway は、gke-l7-regional-external-managed と gke-l7-rilb の GatewayClass リソースでのみサポートされます。
  • クロスリージョン内部アプリケーション ロードバランサはサポートされていません。
  • InferencePool には最大 8 個の targetPorts を設定できます。

GKE Inference Gateway を構成する

次のような例で GKE Inference Gateway を構成する場合について考えてみましょう。あるチームが vLLM モデルと Llama3 モデルを実行し、2 つの異なる LoRA ファインチューニング アダプタ（food-review と cad-fabricator）を積極的にテストしています。

GKE Inference Gateway を構成するワークフローの概要は次のとおりです。

  1. 環境を準備する: 必要なインフラストラクチャとコンポーネントを設定します。
  2. 推論プールを作成する: InferencePool カスタム リソースを使用して、モデルサーバーのプールを定義します。
  3. 推論目標を指定する: InferenceObjective カスタム リソースを使用して推論目標を指定します。
  4. Gateway を作成する: Gateway API を使用して推論サービスを公開します。
  5. HTTPRoute を作成する: HTTP トラフィックを推論サービスにルーティングする方法を定義します。
  6. 推論リクエストを送信する: デプロイされたモデルにリクエストを送信します。

Gateway を作成する

Gateway リソースは、Kubernetes クラスタへの外部トラフィックのエントリ ポイントです。受信接続を受け入れるリスナーを定義します。

GKE Inference Gateway は、次の Gateway クラスで動作します。

  • gke-l7-rilb: リージョン内部アプリケーション ロードバランサの場合
  • gke-l7-regional-external-managed: リージョン外部アプリケーション ロードバランサの場合

詳細については、Gateway クラスのドキュメントをご覧ください。

Gateway を作成するには、次の操作を行います。

  1. 次のサンプル マニフェストを gateway.yaml として保存します。

    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: GATEWAY_NAME
spec:
  gatewayClassName: GATEWAY_CLASS
  listeners:
    - protocol: HTTP
      port: 80
      name: http

    次のように置き換えます。

    • GATEWAY_NAME: Gateway リソースの一意の名前。例: inference-gateway。
    • GATEWAY_CLASS: 使用する Gateway クラス。例: gke-l7-regional-external-managed。

  2. マニフェストをクラスタに適用します。

    kubectl apply -f gateway.yaml

注: HTTPS で Gateway を保護するように TLS を構成する方法について詳しくは、TLS 構成に関する GKE のドキュメントをご覧ください。

環境を準備する

  1. Helm をインストールします。

  2. GKE クラスタを作成します。

    • バージョン 1.32.3 以降の GKE Autopilot クラスタまたは GKE Standard クラスタを作成します。ワンクリック デプロイのリファレンスの設定については、cluster-toolkit gke-a3-highgpu サンプルをご覧ください。
    • 目的のコンピューティング ファミリーとアクセラレータを使用してノードを構成します。
    • 選択したアクセラレータ、モデル、パフォーマンスのニーズに基づいて事前に構成され、テストされているデプロイ マニフェストについては、GKE Inference クイックスタートをご覧ください。

  3. 必要なカスタム リソース定義（CRD）を GKE クラスタにインストールします。

    • GKE バージョン 1.34.0-gke.1626000 以降の場合、InferencePool CRD はデフォルトで含まれています。したがって、アルファ版の InferenceObjective CRD のみをインストールします。

      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/raw/v1.4.0/config/crd/bases/inference.networking.x-k8s.io_inferenceobjectives.yaml

    • 1.34.0-gke.1626000 より前の GKE バージョンの場合は、v1 InferencePool とアルファ版 InferenceObjective の両方の CRD をインストールします。

      kubectl apply -f  https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v1.4.0/manifests.yaml

      詳細については、互換性マトリックスをご覧ください。

  4. v1.32.2-gke.1182001 より前の GKE バージョンを使用し、GKE Inference Gateway で Model Armor を使用する場合は、トラフィックとルーティングの拡張機能 CRD をインストールする必要があります。

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcproutingextensions.yaml

  5. 次の環境変数を設定します。

    export GAIE_VERSION=v1.5.0
export GUIDE_NAME="optimized-baseline"
export NAMESPACE=llm-d-optimized-baseline
export INFRA_PROVIDER=gke   # gke | base

  6. llm-d エンドポイント選択ツール（EPP）に必要な Gateway API Inference Extension カスタム リソース定義（CRD）をインストールします。

    kubectl apply -k \
  "https://github.com/kubernetes-sigs/gateway-api-inference-extension/config/crd?ref=${GAIE_VERSION}"

  7. ターゲット Namespace を作成します。

    kubectl create namespace ${NAMESPACE}

モデルサーバーとモデルのデプロイメントを作成する

このセクションでは、モデルサーバーとモデルをデプロイする方法について説明します。この例では、vLLM モデルサーバーと Llama3 モデルを使用しています。Deployment に app:vllm-llama3-8b-instruct というラベルが付いています。この Deployment は、Hugging Face の food-review と cad-fabricator という 2 つの LoRA アダプタも使用します。

この例は、独自のモデルサーバー コンテナとモデル、サービング ポート、デプロイ名に適応させることができます。また、Deployment で LoRA アダプタを構成することも、ベースモデルをデプロイすることもできます。次の手順では、必要な Kubernetes リソースを作成する方法について説明します。

  1. Hugging Face トークンを保存する Kubernetes Secret を作成します。このトークンは、ベースモデルと LoRA アダプタにアクセスするために使用されます。

    kubectl create secret generic hf-token --from-literal=token=HF_TOKEN

    HF_TOKEN は、Hugging Face トークンに置き換えます。

  2. llm-d 最適化ベースライン ガイドの GKE 固有の Kustomize オーバーレイを使用して、vLLM モデルサーバーをデプロイします。INFRA_PROVIDER=gke を設定すると、Cloud Monitoring の統合など、GKE 固有の構成が適用されます。

    kubectl apply -n ${NAMESPACE} \
  -k guides/${GUIDE_NAME}/modelserver/gpu/vllm/${INFRA_PROVIDER}/

注: GKE は、デフォルトでアプリケーションの自動モニタリングを提供します。llm-d モニタリング スタックは GKE に必須ではありませんが、必要に応じて使用できます。

モデルサーバーに複数のポートが必要な場合は、コンテナ仕様で各ポートが公開されていることを確認してください。次の例では、コンテナが 3 つのポートを公開する Deployment を定義します。

マルチポート デプロイの例

apiVersion: apps/v1
kind: Deployment
metadata:
  name: multiport-model-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: multiport-model-server
  template:
    metadata:
      labels:
        app: multiport-model-server
    spec:
      containers:
      - name: model-server
        image: your-model-server-image
        ports:
        - containerPort: 8080
        - containerPort: 8081
        - containerPort: 9000

推論プールを作成する

InferencePool Kubernetes カスタム リソースは、共通のベースとなる大規模言語モデル（LLM）とコンピューティング構成を持つ Pod のグループを定義します。selector フィールドには、このプールに属する Pod を指定します。このセレクタのラベルは、モデルサーバー Pod に適用されるラベルと完全に一致している必要があります。targetPorts フィールドは、モデルサーバーが Pod 内で使用するポートを定義します。最大 8 つのポートを指定できます。extensionRef フィールドは、推論プールに追加機能を提供する拡張機能サービスを参照します。InferencePool により、GKE Inference Gateway はモデルサーバー Pod にトラフィックを転送できるようになります。

次の InferencePool マニフェストでは、モデルサーバー Deployment によって公開されるポートに対応する複数の targetPort を指定しています。

Multiport InferencePool の例

apiVersion: inference.networking.k8s.io/v1
kind: InferencePool
metadata:
  name: my-multiport-pool
  namespace: default
spec:
  selector:
    matchLabels:
      app: multiport-model-server
  targetPorts:
    - number: 8080
    - number: 8081
    - number: 9000

InferencePool を作成する前に、InferencePool が選択する Pod がすでに実行されていることを確認します。

Helm を使用して InferencePool を作成する手順は次のとおりです。

helm install ${GUIDE_NAME} \
  -f guides/recipes/scheduler/base.values.yaml \
  -f guides/${GUIDE_NAME}/scheduler/${GUIDE_NAME}.values.yaml \
  --set provider.name=gke \
  --set inferenceExtension.monitoring.gke.enabled=true \
  -n ${NAMESPACE} \
  --version ${GAIE_VERSION} \
  oci://LLM_D_REGISTRY_PATH

次のように置き換えます。

  • GAIE_VERSION: Helm チャートのバージョン。例: v1.5.0
  • LLM_D_REGISTRY_PATH: Helm チャートの OCI レジストリ パス。例: us-central1-docker.pkg.dev/cloud-ai-gke/gke-inference-gateway/charts/inferencepool

次のフィールドを Deployment に合わせて変更します。

  • inferencePool.modelServers.matchLabels.app: モデルサーバー Pod の選択に使用されるラベルのキー。

モニタリングの場合、Google Cloud Managed Service for Prometheus の指標スクレイピングはデフォルトで有効になっています。

  • この機能を無効にするには、コマンドに --set inferenceExtension.monitoring.prometheus.enabled=false フラグを追加します。
  • GKE Autopilot クラスタでデフォルトのモニタリングを使用する場合は、--set provider.gke.autopilot=true フラグも追加する必要があります。

Helm のインストールにより、タイムアウト ポリシー、エンドポイント ピッカー、オブザーバビリティに必要な Pod が自動的にインストールされます。

これにより、Pod 内のモデル エンドポイント サービスを参照する InferencePool オブジェクト vllm-llama3-8b-instruct が作成されます。また、この作成された InferencePool に app:vllm-llama3-8b-instruct-epp という名前のエンドポイント ピッカーの Deployment も作成されます。

HTTPRoute を作成する

HTTPRoute リソースは、GKE Gateway が受信した HTTP リクエストをバックエンド サービス（InferencePool など）に転送する方法を定義します。HTTPRoute リソースには、一致ルール（ヘッダーやパスなど）と、トラフィックを転送するバックエンドを指定します。

  1. HTTPRoute を作成するには、次のサンプル マニフェストを httproute.yaml として保存します。

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: HTTPROUTE_NAME
spec:
  parentRefs:
  - name: GATEWAY_NAME
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: PATH_PREFIX
    backendRefs:
    - name: INFERENCE_POOL_NAME
      group: "inference.networking.k8s.io"
      kind: InferencePool

    次のように置き換えます。

    • HTTPROUTE_NAME: HTTPRoute リソースの一意の名前。例: my-route
    • GATEWAY_NAME: 作成した Gateway リソースの名前。例: inference-gateway
    • PATH_PREFIX: 受信リクエストの照合に使用するパス接頭辞。たとえば、/ はすべてに一致します。
    • INFERENCE_POOL_NAME: トラフィックを転送する InferencePool リソースの名前。例: vllm-llama3-8b-instruct

  2. マニフェストをクラスタに適用します。

    kubectl apply -f httproute.yaml

推論目標を指定する

InferenceObjective カスタム リソースを使用すると、リクエストの優先度を指定できます。

InferenceObjective リソースの metadata.name フィールドには推論目標の名前を指定、Priority フィールドにはサービングの重要度を指定、poolRef フィールドにはモデルが提供される InferencePool を指定します。

apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: NAME
spec:
  priority: VALUE
  poolRef:
    name: INFERENCE_POOL_NAME
    group: "inference.networking.k8s.io"

次のように置き換えます。

  • NAME: 推論目標の名前。例: food-review。
  • VALUE: 推論目標の優先度。これは整数で、値が大きいほどリクエストの重要度が高いことを示します。例: 10。
  • INFERENCE_POOL_NAME: 前の手順で作成した InferencePool の名前。例: vllm-llama3-8b-instruct

InferenceObjective を作成する手順は次のとおりです。

  1. 次のマニフェストを inference-objectives.yaml として保存します。このマニフェストは、2 つの InferenceObjective リソースを作成します。1 つ目は、優先度 10 で vllm-llama3-8b-instruct InferencePool の food-review 推論目標を構成します。2 つ目は、より高い優先度 20 でサービングされるように llama3-base-model 推論目標を構成します。

    apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: food-review
spec:
  priority: 10
  poolRef:
    name: vllm-llama3-8b-instruct
    group: "inference.networking.k8s.io"
---
apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: llama3-base-model
spec:
  priority: 20 # Higher priority
  poolRef:
    name: vllm-llama3-8b-instruct

  2. サンプル マニフェストをクラスタに適用します。

    kubectl apply -f inference-objectives.yaml

デプロイを確認する

すべてのコンポーネントが実行されていることを確認するには、次のコマンドを実行します。

kubectl get inferencepool
kubectl get inferenceobjective
kubectl get pods -l app=vllm-llama3-8b-instruct-epp

推論リクエストを送信する

GKE Inference Gateway を構成したら、デプロイされたモデルに推論リクエストを送信できます。これにより、入力プロンプトと指定されたパラメータに基づいてテキストを生成できます。

推論リクエストを送信する手順は次のとおりです。

  1. 次の環境変数を設定します。

    export GATEWAY_NAME=GATEWAY_NAME
export PORT_NUMBER=PORT_NUMBER # Use 80 for HTTP

    次のように置き換えます。

    • GATEWAY_NAME: Gateway リソースの名前。
    • PORT_NUMBER: Gateway で構成したポート番号。

  2. Gateway エンドポイントを取得するには、次のコマンドを実行します。

    echo "Waiting for the Gateway IP address..."
IP=""
while [ -z "$IP" ]; do
  IP=$(kubectl get gateway/${GATEWAY_NAME} -o jsonpath='{.status.addresses[0].value}' 2>/dev/null)
  if [ -z "$IP" ]; then
    echo "Gateway IP not found, waiting 5 seconds..."
    sleep 5
  fi
done

echo "Gateway IP address is: $IP"
PORT=${PORT_NUMBER}

  3. curl を使用して /v1/completions エンドポイントにリクエストを送信するには、次のコマンドを実行します。

    curl -i -X POST ${IP}:${PORT}/v1/completions \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $(gcloud auth application-default print-access-token)' \
-d '{
    "model": "MODEL_NAME",
    "prompt": "PROMPT_TEXT",
    "max_tokens": MAX_TOKENS,
    "temperature": "TEMPERATURE"
}'

    次のように置き換えます。

    • MODEL_NAME: 使用するモデルまたは LoRA アダプタの名前。
    • PROMPT_TEXT: モデルの入力プロンプト。
    • MAX_TOKENS: レスポンスで生成するトークンの最大数。
    • TEMPERATURE: 出力のランダム性を制御します。決定論的出力の場合は値 0 を使用し、より創造的な出力の場合はより大きい値を使用します。

次の例は、GKE Inference Gateway にサンプル リクエストを送信する方法を示しています。

curl -i -X POST ${IP}:${PORT}/v1/completions -H 'Content-Type: application/json' -H 'Authorization: Bearer $(gcloud auth application-default print-access-token)' -d '{
    "model": "food-review-1",
    "prompt": "What is the best pizza in the world?",
    "max_tokens": 2048,
    "temperature": 0
}'

次の動作に注意してください。

  • リクエスト本文: リクエスト本文には、stop や top_p などの追加パラメータを指定できます。オプションの一覧については、OpenAI API 仕様をご覧ください。
  • エラー処理: クライアント コードに適切なエラー処理を実装して、レスポンスで発生する可能性のあるエラーを処理します。たとえば、curl レスポンスの HTTP ステータス コードを確認します。200 以外のステータス コードは通常、エラーを示します。
  • 認証と認可: 本番環境のデプロイでは、認証と認可メカニズムを使用して API エンドポイントを保護します。適切なヘッダー（Authorization など）をリクエストに含めます。

互換性マトリックス

次の表に、Gateway API Inference Extension カスタム リソース定義（CRD）の互換性とサポートのマトリックスを示します。特定のバージョンの要件やインストールに関する注意事項など、オープンソース（OSS）Gateway API Inference Extension プロジェクトと比較して、GKE でサポートされている CustomResourceDefinition バージョンについて詳しく説明しています。

CustomResourceDefinition 名 CustomResourceDefinition API バージョン GKE マネージド サポート OSS（Gateway API Inference Extension）のサポート
V1 InferencePool inference.networking.k8s.io/v1 GKE 1.32.3 以降でサポートされ、GKE 1.34.0-gke.1626000 以降でデフォルトでインストールされる CustomResourceDefinition Gateway API Inference Extension v1.0.0 以降でサポートされています
アルファ版 InferencePool（アルファ版 InferencePool バージョンは非推奨になったため、v1 InferencePool から始めることをおすすめします） inference.networking.x-k8s.io/v1alpha2 GKE 1.32.3 以降でサポートされています。ただし、CustomResourceDefinition は GKE にデフォルトでインストールされていません。ユーザーは、Gateway API Inference Extension から CustomResourceDefinition を手動でインストールする必要があります。 Gateway API Inference Extension v0.2.0 以降でサポートされています
Alpha InferenceObjective inference.networking.x-k8s.io/v1alpha2 GKE は InferenceObjective を管理しません Gateway API Inference Extension v1.0.0 以降でサポートされています
Alpha InferenceModel（InferenceModel は非推奨になったため、InferenceObjective から始めることをおすすめします） inference.networking.x-k8s.io/v1alpha2 GKE は InferenceModel を管理しません Gateway API Inference Extension v0.2.0 以降でサポートされています。

次のステップ