View a markdown version of this page

Inference Gateway トラブルシューティングガイド - Amazon SageMaker AI
ゲートウェイの状態を診断するアドオンのインストールの問題InferenceGatewayConfig が準備完了にならないスケジューラごとの障害スケジューラの rolloutState がデグレードされましたモデルポッドの再起動後のエンドポイントの古さJWT 認証が 401 または 403 を返すダッシュボードにメトリクスがないリクエストの失敗エンドポイント選択のデバッグライフサイクルとクリーンアップログの収集

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Inference Gateway トラブルシューティングガイド

概要: HyperPod Inference Gateway は、本文ベースのルーター (BBR)、 を使用するゲートウェイHTTPRoute、エンドポイントピッカー (EPP) の 3 つのレイヤーを介してトラフィックをルーティングします。レイヤーの設定ミスにより、リクエストの失敗、間違ったモデルへのトラフィックの到達、モデル提供ポッド間の負荷の不均等が発生する可能性があります。このセクションでは、ゲートウェイ、BBR、ゲートウェイ、HTTPRoute、、および EPP の問題、InferencePoolおよびそれらから発生する問題について説明します。

ゲートウェイの状態を診断する

次のコマンドを使用して、ゲートウェイとゲートウェイが管理するリソースを検査します。

名前空間内のすべてのInferenceGatewayConfigリソースを一覧表示します。

kubectl get inferencegatewayconfig -A

特定のゲートウェイの詳細ステータス、スケジューラごとのロールアウト状態、および条件メッセージを表示します。

kubectl describe inferencegatewayconfig <name> -n <namespace>

ゲートウェイコントローラーと本文ベースのルーターポッドを確認します。

kubectl get pods -n hyperpod-inference-system

コントローラーによって生成されたダウンストリームルーティングリソースを確認します。

kubectl get httproute,inferencepool,securitypolicy -A

status.conditions と各スケジューラの rolloutState (Pending、Progressing、Available、または ) を検査しますDegraded。実行可能な障害の原因は、対応する条件メッセージにあります。

アドオンのインストールの問題

問題: ゲートウェイリソースがないか、HyperPod Inference Amazon EKS アドオンをインストールした後に GatewayClassが受け入れられません。

症状と解決策: kubectl get gatewayclass inference-gatewayを返すかNotFound、リソースに が表示されますACCEPTED=False。これは、アドオンがインストールされていないか、インストールが完了しなかったことを示します。アドオンを再インストールまたは更新します。

aws eks update-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --resolve-conflicts OVERWRITE

次に、ゲートウェイコントローラーが実行されていることを確認します。

kubectl rollout status deploy/inference-gateway-controller \
  -n hyperpod-inference-system --timeout=150s

InferenceGatewayConfig が準備完了にならない

問題: InferenceGatewayConfigが作成されますが、その status.conditions show Accepted=Falseまたは Ready=False、または kubectl applyは検証によって完全に拒否されます。

症状と解決策:

  • kubectl apply は で失敗しますbbr must be enabled when more than one scheduler is defined。複数のスケジューラが定義されている場合は、常に本文ベースのルーターが必要です。spec.bbr.enabled を true に設定します。

  • kubectl apply は で失敗しますmodelName must be unique across schedulers。2 つのスケジューラが同じ を宣言しますmodelName。スケジューラごとに個別の を持つように名前を 1 つ変更しますmodelName。

  • Accepted=False、Reason=InvalidLoraAdapters。 で宣言された LoRA アダプター名spec.schedulers[].loraAdaptersは、スケジューラ間で重複しているか、スケジューラの と衝突しますmodelName。条件メッセージで問題の名前を確認します。

    kubectl describe inferencegatewayconfig <name> -n <namespace>

  • Accepted=False、Reason=ResourceNamingViolation。 連結された名前が Kubernetes の 63 文字のラベル制限<config-name>-<scheduler-name>を超えています。設定またはスケジューラ名を短くします。

  • Ready=False、Reason=GatewayNotProgrammed。 ゲートウェイはロードバランサーをまだプロビジョニングしていません。親ゲートウェイを検査します。

    kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway <name> -n hyperpod-inference-system

  • AdmissionBlocked=True、Reason=WebhookDenied。 クラスターアドミッションウェブフックがゲートウェイポッドを拒否しています。条件メッセージは、問題のあるウェブフックに名前を付けます。ウェブフックを削除または修正し、ポッドがすぐに再作成されるようにゲートウェイデプロイを再起動します。デプロイ名が生成されるため、最初に検索します。

    kubectl -n hyperpod-inference-system get deploy \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>

    次に、再起動します。

    kubectl -n hyperpod-inference-system rollout restart deploy/<gateway-deployment>

スケジューラごとの障害

問題: 特定のスケジューラの条件 (BackendsReady、LoraSupported、または PoolReady) は、スケジューラの準備が完了していないことを示します。

症状と解決策:

  • BackendsReady=False、、Reason=NoModelPodsまたは Reason=NoReadyModelPods。に一致するポッドがないかspec.schedulers[].modelSelector、一致するポッドがまだ準備完了ではありません。モデル提供ポッドのラベルをスケジューラのセレクタと比較します。

    kubectl get pods -n <namespace> --show-labels

    モデル提供ポッドをデプロイし、それらが準備完了になるまで待ってから を適用しますInferenceGatewayConfig。

  • BackendsReady=False、Reason=InvalidModelSelector。 matchExpressions 以下の matchLabelsまたは modelSelectorの形式が正しくありません。設定のセレクタを修正します。

  • LoraSupported=False、Reason=ModelServerLoraDisabled。 このスケジューラをバックアップしているモデルサーバーは、LoRA サポートを有効にして起動されませんでした。モデルサーバーで同等のフラグ (vLLM の場合など) --enable-lora を有効にし、モデルポッドを再起動します。

  • PoolReady=False、、Reason=NotFoundまたは Reason=NotAccepted。InferencePool またはその HTTPRouteは、ゲートウェイによってまだ調整または承認されていません。両方を検査します。

    kubectl get inferencepool,httproute -n <namespace>

    設定が適用されてから数分後にいずれかの がまだ欠落している場合は、親ゲートウェイを記述してアドミッションエラーを確認します。

    kubectl describe gateway -n hyperpod-inference-system

スケジューラの rolloutState がデグレードされました

問題: スケジューラの Endpoint Picker デプロイがスタックし、使用可能にならない。

症状と解決策: スケジューラEPPReadyの条件には実用的な理由があります。一般的な原因には、以下が含まれます。

  • コンテナイメージはプルできません。

  • ポッドはクラッシュループです。

  • コンテナに、無効な環境変数、ボリュームマウント、シークレットリファレンスなどの設定エラーがあります。

  • デプロイが進行期限を超えました。

次のコマンドを使用して、失敗したスケジューラを特定し、デプロイを検査します。

# List the schedulers reporting Degraded
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{range .status.schedulers[?(@.rolloutState=="Degraded")]}{.name}{"\n"}{end}'

# Describe the scheduler's Endpoint Picker Deployment for pod events and container errors
kubectl describe deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

モデルポッドの再起動後のエンドポイントの古さ

問題: モデルポッドが削除され、代替ポッドが準備完了になると、Endpoint Picker は削除されたポッドの IP アドレスに引き続きルーティングされます。リクエストは HTTP 503 を返すか、接続が拒否され、条件自体は回復しません。

解決策: 準備状況プローブをモデルポッドに追加して、Kubernetes が IP がプールから削除される前にポッド NotReady をマークし、トラフィックが完全に処理された後にのみ代替ポッドをアドバタイズするようにします。をスケジューラの portに設定targetPortし、モデルサーバーのヘルスエンドポイントpathに設定します。

readinessProbe:
  httpGet:
    path: /health
    port: 8000

回避策: モデルポッドをすぐに再デプロイできない場合は、スケジューラの Endpoint Picker を再起動して、現在のポッドセットからエンドポイントリストを強制的に再構築します。

kubectl rollout restart deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

JWT 認証が 401 または 403 を返す

問題: spec.auth.jwt が設定され、モデルに到達する前にリクエストが拒否されるか、JWT 認証が有効になった後にゲートウェイが準備完了になることはありません。

症状と解決策:

  • HTTP 401。トークンが欠落しているか、期限切れであるか、形式が正しくないか、そのissクレームが設定されたプロバイダーと一致しません。クライアントが Authorization: Bearer <token>ヘッダーを送信し、JWT をデコードしてissクレームを と比較しますspec.auth.jwt.provider.issuer。

  • HTTP 403。署名の検証が失敗したか、トークンの audまたは がプロバイダー設定と一致しrequiredClaimsません。プロバイダー設定を検査し、トークンaudと のすべてのエントリrequiredClaimsが一致していることを確認します。

    kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.auth.jwt.provider}'

  • JWT を有効にしてゲートウェイが準備完了になることはありません。生成された SecurityPolicyはゲートウェイによって受け入れられません。SecurityPolicy リソースで障害の理由を確認します。

    kubectl get securitypolicy -A
kubectl describe securitypolicy <name> -n <namespace>

    一般的な原因は、 spec.auth.jwt.provider.remoteJWKS.uriがゲートウェイから到達できないことです。URI が解決され、有効な JWKS ドキュメントが返されることを確認します。

ダッシュボードにメトリクスがない

問題: Endpoint Picker または本文ベースのルーターメトリクスがモニタリングダッシュボードに表示されません。

症状と解決策: メトリクス収集はデフォルトで有効になっているため、OpenTelemetry Collector サイドカーは通常存在します。サイドカーが両方のポッドタイプで実行されているかどうか、およびメトリクスが明示的に無効になっているかどうかを確認します。

ボディベースのルーターポッドのサイドカーを確認します。

kubectl -n hyperpod-inference-system get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

Endpoint Picker ポッドのサイドカーを確認します。

kubectl -n <namespace> get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

メトリクスが明示的に無効になっているかどうかを確認します。

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.observability.metrics.enabled}'

最後のコマンドの空の出力は、 フィールドが設定されておらず、メトリクスが有効になっていることを意味します。明示的な のみがサイドカーをfalse無効にします。値が の場合false、 に設定するtrueか、 フィールドを削除すると、コントローラーは次の調整時にサイドカーを挿入します。

リクエストの失敗

問題: ゲートウェイは準備完了ですが、推論リクエストは失敗します。

症状と解決策:

  • 既知のモデルの HTTP 404。リクエスト本文のmodel値がスケジューラの と完全に一致しないかmodelName、リクエストされたモデルが で宣言されていない LoRA アダプターを介して提供されますspec.schedulers[].loraAdapters。リクエストされたモデルに一致するスケジューラがなく、設定されていない場合、ゲートウェイspec.bbr.defaultBackendは 404 を返します。設定されたモデル名とアダプター名を確認します。

    kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].modelName}'

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].loraAdapters}'

  • リクエストがハングしてからタイムアウトします。モデル提供ポッドはモデルの重みをまだロードしているか、 InferencePoolに準備完了エンドポイントがありません。モデルポッドが準備完了になるまで待ってから、ゲートウェイエンドポイントを呼び出します。のスケジューラのmodelSelectorラベルをセレクタInferenceGatewayConfigとして使用します。

    kubectl get pods -n <namespace> -l <key>=<value>
kubectl logs <pod> -n <namespace>

エンドポイント選択のデバッグ

問題: トラフィックが少数のモデルポッドに歪んでいるか、LoRA リクエストがアダプターをホストしないポッドにルーティングされます。

解決策: Endpoint Picker のログの詳細度を一時的に上げて、スコアリングの決定を検査します。スケジューラlogLevelで を設定します。

spec:
  schedulers:
    - name: <scheduler-name>
      logLevel: 4

ログレベルの意味:

  • 1 - ライフサイクルイベントをリクエストします。

  • 2 - デフォルト。警告と承認の拒否。

  • 3 - 選択したエンドポイントとスコアラーごとの概要。

  • 4 - エンドポイントごと、スコアごとのスコア、加重合計。

  • 5 - プロトコルレベルのトレース (詳細）。

Endpoint Picker ログを検査します。

kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp --tail=200 -f

余分なログボリュームを避けるため、調査が完了するとデフォルトlogLevelに戻ります。

ライフサイクルとクリーンアップ

問題: HyperPod Inference Amazon EKS アドオンをアンインストールまたはアップグレードすると、クラスターに孤立したリソースが残されるか、後続のインストールがブロックされます。

解決策: アドオンをアンインストールまたはアップグレードする前に、必ずすべてのInferenceGatewayConfigリソースを削除してください。がまだ存在する間にアドオンをアンインストールすると、リソースのファイナライザーを所有するコントローラーが削除され、それらのリソースInferenceGatewayConfigは に残りますTerminating。

kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A

アドオンオペレーションを続行する前に、2 番目のコマンドが行を返さないことを確認します。

アドオンを再インストールしたら、ゲートウェイ名前空間のリソースを一覧表示し、ライブ にマッピングされなくなったものをすべて削除しますInferenceGatewayConfig。

kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
  -n hyperpod-inference-system

コントローラーによって発行された ACM 証明書は、アドオンのアンインストールでは削除されません。これらを削除するには、 AWS Resource Groups Tagging API の ACM 証明書を タグでフィルタリングCreatedBy=HyperPodInferenceし、不要になった証明書を削除します。

ログの収集

次のコマンドを使用して、各ゲートウェイコンポーネントからログを取得します。

# Gateway controller
kubectl logs -n hyperpod-inference-system deploy/inference-gateway-controller

# Body-Based Router (deployment name is <gateway-name>-bbr)
kubectl logs -n hyperpod-inference-system deploy/<gateway-name>-bbr -c bbr

# Endpoint Picker for a specific scheduler
kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp