翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Inference Gateway トラブルシューティングガイド
**概要:** HyperPod Inference Gateway は、本文ベースのルーター (BBR)、 を使用するゲートウェイ`HTTPRoute`、エンドポイントピッカー (EPP) の 3 つのレイヤーを介してトラフィックをルーティングします。レイヤーの設定ミスにより、リクエストの失敗、間違ったモデルへのトラフィックの到達、モデル提供ポッド間の負荷の不均等が発生する可能性があります。このセクションでは、ゲートウェイ、BBR、ゲートウェイ、`HTTPRoute`、、および EPP の問題、`InferencePool`およびそれらから発生する問題について説明します。
## ゲートウェイの状態を診断する
次のコマンドを使用して、ゲートウェイとゲートウェイが管理するリソースを検査します。
名前空間内のすべての`InferenceGatewayConfig`リソースを一覧表示します。
```
kubectl get inferencegatewayconfig -A
```
特定のゲートウェイの詳細ステータス、スケジューラごとのロールアウト状態、および条件メッセージを表示します。
```
kubectl describe inferencegatewayconfig -n
```
ゲートウェイコントローラーと本文ベースのルーターポッドを確認します。
```
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 -n
```
+ **`Accepted=False`、`Reason=ResourceNamingViolation`。** 連結された名前が Kubernetes の 63 文字のラベル制限`-`を超えています。設定またはスケジューラ名を短くします。
+ **`Ready=False`、`Reason=GatewayNotProgrammed`。** ゲートウェイはロードバランサーをまだプロビジョニングしていません。親ゲートウェイを検査します。
```
kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway -n hyperpod-inference-system
```
+ **`AdmissionBlocked=True`、`Reason=WebhookDenied`。** クラスターアドミッションウェブフックがゲートウェイポッドを拒否しています。条件メッセージは、問題のあるウェブフックに名前を付けます。ウェブフックを削除または修正し、ポッドがすぐに再作成されるようにゲートウェイデプロイを再起動します。デプロイ名が生成されるため、最初に検索します。
```
kubectl -n hyperpod-inference-system get deploy \
-l gateway.envoyproxy.io/owning-gateway-name=
```
次に、再起動します。
```
kubectl -n hyperpod-inference-system rollout restart deploy/
```
## スケジューラごとの障害
**問題:** 特定のスケジューラの条件 (`BackendsReady`、`LoraSupported`、または `PoolReady`) は、スケジューラの準備が完了していないことを示します。
**症状と解決策:**
+ **`BackendsReady=False`、、`Reason=NoModelPods`または `Reason=NoReadyModelPods`。**に一致するポッドがないか`spec.schedulers[].modelSelector`、一致するポッドがまだ準備完了ではありません。モデル提供ポッドのラベルをスケジューラのセレクタと比較します。
```
kubectl get pods -n --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
```
設定が適用されてから数分後にいずれかの がまだ欠落している場合は、親ゲートウェイを記述してアドミッションエラーを確認します。
```
kubectl describe gateway -n hyperpod-inference-system
```
## スケジューラの rolloutState がデグレードされました
**問題:** スケジューラの Endpoint Picker デプロイがスタックし、使用可能にならない。
**症状と解決策:** スケジューラ`EPPReady`の条件には実用的な理由があります。一般的な原因には、以下が含まれます。
+ コンテナイメージはプルできません。
+ ポッドはクラッシュループです。
+ コンテナに、無効な環境変数、ボリュームマウント、シークレットリファレンスなどの設定エラーがあります。
+ デプロイが進行期限を超えました。
次のコマンドを使用して、失敗したスケジューラを特定し、デプロイを検査します。
```
# List the schedulers reporting Degraded
kubectl get inferencegatewayconfig -n \
-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 \
-l inference.sagemaker.aws.amazon.com/scheduler=
```
## モデルポッドの再起動後のエンドポイントの古さ
**問題:** モデルポッドが削除され、代替ポッドが準備完了になると、Endpoint Picker は削除されたポッドの IP アドレスに引き続きルーティングされます。リクエストは HTTP 503 を返すか、接続が拒否され、条件自体は回復しません。
**解決策:** 準備状況プローブをモデルポッドに追加して、Kubernetes が IP がプールから削除される前にポッド NotReady をマークし、トラフィックが完全に処理された後にのみ代替ポッドをアドバタイズするようにします。をスケジューラの `port`に設定`targetPort`し、モデルサーバーのヘルスエンドポイント`path`に設定します。
```
readinessProbe:
httpGet:
path: /health
port: 8000
```
**回避策:** モデルポッドをすぐに再デプロイできない場合は、スケジューラの Endpoint Picker を再起動して、現在のポッドセットからエンドポイントリストを強制的に再構築します。
```
kubectl rollout restart deploy -n \
-l inference.sagemaker.aws.amazon.com/scheduler=
```
## JWT 認証が 401 または 403 を返す
**問題:** `spec.auth.jwt` が設定され、モデルに到達する前にリクエストが拒否されるか、JWT 認証が有効になった後にゲートウェイが準備完了になることはありません。
**症状と解決策:**
+ **HTTP 401。**トークンが欠落しているか、期限切れであるか、形式が正しくないか、その`iss`クレームが設定されたプロバイダーと一致しません。クライアントが `Authorization: Bearer `ヘッダーを送信し、JWT をデコードして`iss`クレームを と比較します`spec.auth.jwt.provider.issuer`。
+ **HTTP 403。**署名の検証が失敗したか、トークンの `aud`または がプロバイダー設定と一致し`requiredClaims`ません。プロバイダー設定を検査し、トークン`aud`と のすべてのエントリ`requiredClaims`が一致していることを確認します。
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.auth.jwt.provider}'
```
+ **JWT を有効にしてゲートウェイが準備完了になることはありません。**生成された `SecurityPolicy`はゲートウェイによって受け入れられません。SecurityPolicy リソースで障害の理由を確認します。
```
kubectl get securitypolicy -A
kubectl describe securitypolicy -n
```
一般的な原因は、 `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 get pods \
-o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```
メトリクスが明示的に無効になっているかどうかを確認します。
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.observability.metrics.enabled}'
```
最後のコマンドの空の出力は、 フィールドが設定されておらず、メトリクスが有効になっていることを意味します。明示的な のみがサイドカーを`false`無効にします。値が の場合`false`、 に設定する`true`か、 フィールドを削除すると、コントローラーは次の調整時にサイドカーを挿入します。
## リクエストの失敗
**問題:** ゲートウェイは準備完了ですが、推論リクエストは失敗します。
**症状と解決策:**
+ **既知のモデルの HTTP 404。**リクエスト本文の`model`値がスケジューラの と完全に一致しないか`modelName`、リクエストされたモデルが で宣言されていない LoRA アダプターを介して提供されます`spec.schedulers[].loraAdapters`。リクエストされたモデルに一致するスケジューラがなく、設定されていない場合、ゲートウェイ`spec.bbr.defaultBackend`は 404 を返します。設定されたモデル名とアダプター名を確認します。
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.schedulers[*].modelName}'
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.schedulers[*].loraAdapters}'
```
+ **リクエストがハングしてからタイムアウトします。**モデル提供ポッドはモデルの重みをまだロードしているか、 `InferencePool`に準備完了エンドポイントがありません。モデルポッドが準備完了になるまで待ってから、ゲートウェイエンドポイントを呼び出します。のスケジューラの`modelSelector`ラベルをセレクタ`InferenceGatewayConfig`として使用します。
```
kubectl get pods -n -l =
kubectl logs -n
```
## エンドポイント選択のデバッグ
**問題:** トラフィックが少数のモデルポッドに歪んでいるか、LoRA リクエストがアダプターをホストしないポッドにルーティングされます。
**解決策:** Endpoint Picker のログの詳細度を一時的に上げて、スコアリングの決定を検査します。スケジューラ`logLevel`で を設定します。
```
spec:
schedulers:
- name:
logLevel: 4
```
ログレベルの意味:
+ `1` - ライフサイクルイベントをリクエストします。
+ `2` - デフォルト。警告と承認の拒否。
+ `3` - 選択したエンドポイントとスコアラーごとの概要。
+ `4` - エンドポイントごと、スコアごとのスコア、加重合計。
+ `5` - プロトコルレベルのトレース (詳細）。
Endpoint Picker ログを検査します。
```
kubectl logs -n -l app=-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 -bbr)
kubectl logs -n hyperpod-inference-system deploy/-bbr -c bbr
# Endpoint Picker for a specific scheduler
kubectl logs -n -l app=-epp -c epp
```