Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Leitfaden zur Fehlerbehebung bei Inference Gateway **Überblick: ** Das HyperPod Inference Gateway leitet den Datenverkehr durch drei Ebenen weiter: den Body-Based Router (BBR), das Gateway mit `HTTPRoute` und den Endpoint Picker (EPP). Eine Fehlkonfiguration auf jeder Ebene kann dazu führen, dass Anfragen fehlschlagen, der Datenverkehr das falsche Modell erreicht oder dass die Pods, die das Modell bereitstellen, ungleichmäßig ausgelastet sind. In diesem Abschnitt werden Probleme mit dem Gateway, BBR, Gateway und EPP sowie alle Probleme `HTTPRoute``InferencePool`, die sich daraus ergeben, behandelt. ## Diagnose des Gateway-Status Verwenden Sie die folgenden Befehle, um das Gateway und die von ihm verwalteten Ressourcen zu überprüfen. Listet alle `InferenceGatewayConfig` Ressourcen in allen Namespaces auf: ``` kubectl get inferencegatewayconfig -A ``` Zeigt detaillierte Status-, Rollout-Status- und Zustandsmeldungen pro Scheduler für ein bestimmtes Gateway an: ``` kubectl describe inferencegatewayconfig -n ``` Überprüfen Sie den Gateway-Controller und Body-Based die Router-Pods: ``` kubectl get pods -n hyperpod-inference-system ``` Überprüfen Sie die vom Controller generierten Downstream-Routing-Ressourcen: ``` kubectl get httproute,inferencepool,securitypolicy -A ``` Überprüfen Sie `status.conditions` die Werte jedes einzelnen Schedulers `rolloutState` (`Pending``Progressing`,`Available`, oder`Degraded`). Umsetzbare Fehlerursachen finden Sie in der entsprechenden Zustandsmeldung. ## Add-on Probleme bei der Installation **Problem: ** Gateway-Ressourcen fehlen oder sie werden nach der `GatewayClass` Installation des HyperPod Inference Amazon EKS-Add-ons nicht akzeptiert. **Symptome und Lösung: ** `kubectl get gatewayclass inference-gateway` kehrt zurück `NotFound` oder die Ressource wird angezeigt`ACCEPTED=False`. Dies weist darauf hin, dass das Add-on nicht installiert ist oder dass die Installation nicht abgeschlossen wurde. Installieren Sie das Add-on erneut oder aktualisieren Sie es: ``` aws eks update-addon --cluster-name $CLUSTER --region $REGION \ --addon-name amazon-sagemaker-hyperpod-inference \ --resolve-conflicts OVERWRITE ``` Vergewissern Sie sich dann, dass der Gateway-Controller läuft: ``` kubectl rollout status deploy/inference-gateway-controller \ -n hyperpod-inference-system --timeout=150s ``` ## InferenceGatewayConfig wird nicht bereit **Problem: ** Eine `InferenceGatewayConfig` wird erstellt, aber ihre `status.conditions` Anzeige `Accepted=False` oder`Ready=False`, oder die `kubectl apply` wird bei der Validierung sofort zurückgewiesen. **Symptome und Lösung: ** + **`kubectl apply`schlägt fehl mit`bbr must be enabled when more than one scheduler is defined`. ** Der Body-Based Router ist immer dann erforderlich, wenn mehr als ein Scheduler definiert ist. Setzen Sie `spec.bbr.enabled` auf `true`. + **`kubectl apply`schlägt fehl mit`modelName must be unique across schedulers`. ** Zwei Scheduler deklarieren dasselbe`modelName`. Benennen Sie einen um, sodass jeder Scheduler einen eigenen hat. `modelName` + **`Accepted=False`,`Reason=InvalidLoraAdapters`. **Ein unter deklarierter LoRa-Adaptername `spec.schedulers[].loraAdapters` ist in allen Schedulern doppelt vorhanden oder kollidiert mit dem eines Schedulers. `modelName` Prüfen Sie die Bedingungsmeldung auf den fehlerhaften Namen: ``` kubectl describe inferencegatewayconfig -n ``` + **`Accepted=False`,`Reason=ResourceNamingViolation`. **Der verkettete Name `-` überschreitet das 63-Zeichen-Labellimit von Kubernetes. Kürzen Sie den Namen der Konfiguration oder des Schedulers. + **`Ready=False`,`Reason=GatewayNotProgrammed`. **Das Gateway hat den Load Balancer noch nicht bereitgestellt. Überprüfen Sie das übergeordnete Gateway: ``` kubectl get gateway -n hyperpod-inference-system kubectl describe gateway -n hyperpod-inference-system ``` + **`AdmissionBlocked=True`,`Reason=WebhookDenied`. **Ein Webhook mit Clusterzugang lehnt den Gateway-Pod ab. In der Bedingungsnachricht wird der fehlerhafte Webhook benannt. Entfernen oder korrigieren Sie den Webhook und starten Sie dann das Gateway-Deployment neu, sodass der Pod sofort neu erstellt wird. Der Deployment-Name wird generiert. Schlagen Sie ihn also zuerst nach: ``` kubectl -n hyperpod-inference-system get deploy \ -l gateway.envoyproxy.io/owning-gateway-name= ``` Dann starte es neu: ``` kubectl -n hyperpod-inference-system rollout restart deploy/ ``` ## Per-scheduler Ausfälle **Problem: Der Zustand ** eines bestimmten Schedulers (`BackendsReady`, oder`PoolReady`) weist darauf hin`LoraSupported`, dass der Scheduler nicht vollständig bereit ist. **Symptome und Lösung: ** + **`BackendsReady=False`, `Reason=NoModelPods` oder`Reason=NoReadyModelPods`. ** Keine Pods stimmen überein`spec.schedulers[].modelSelector`, oder passende Pods sind noch nicht bereit. Vergleichen Sie die Labels auf den Pods, die das Modell bereitstellen, mit dem Selektor des Schedulers: ``` kubectl get pods -n --show-labels ``` Stellen Sie die Pods bereit, die das Modell bereitstellen, und warten Sie, bis sie bereit sind, bevor Sie die anwenden. `InferenceGatewayConfig` + **`BackendsReady=False`,. `Reason=InvalidModelSelector` **Das `matchLabels` oder `matchExpressions` darunter `modelSelector` ist falsch geformt. Korrigieren Sie den Selektor in der Konfiguration. + **`LoraSupported=False`,`Reason=ModelServerLoraDisabled`. **Der Modellserver, der diesen Scheduler unterstützt, wurde nicht mit aktivierter LoRa-Unterstützung gestartet. Aktivieren Sie das entsprechende Flag auf dem Modellserver (z. B. `--enable-lora` für vLLM) und starten Sie die Modell-Pods neu. + **`PoolReady=False`, `Reason=NotFound` oder. `Reason=NotAccepted` ** Das `InferencePool` oder es `HTTPRoute` wurde noch nicht vom Gateway abgeglichen oder akzeptiert. Untersuchen Sie beide: ``` kubectl get inferencepool,httproute -n ``` Wenn eines der beiden Gateways mehrere Minuten nach der Anwendung der Konfiguration immer noch fehlt, beschreiben Sie das übergeordnete Gateway, um nach Zulassungsfehlern zu suchen: ``` kubectl describe gateway -n hyperpod-inference-system ``` ## Scheduler RolloutState ist herabgestuft **Problem: ** Die Endpoint Picker-Bereitstellung für einen Scheduler steckt fest und wird nicht verfügbar. **Symptome und Lösung: ** Die `EPPReady` Störung auf dem Scheduler hat den umsetzbaren Grund. Zu den häufigsten Ursachen gehören: + Das Container-Image kann nicht abgerufen werden. + Die Pods laufen in einer Crash-Schleife. + Der Container weist einen Konfigurationsfehler auf, z. B. eine ungültige Umgebungsvariable, ein ungültiges Volume Mount oder eine geheime Referenz. + Die Frist für den Fortschritt der Bereitstellung wurde überschritten. Verwenden Sie die folgenden Befehle, um den fehlerhaften Scheduler zu identifizieren und seine Bereitstellung zu überprüfen: ``` # 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= ``` ## Veralteter Endpunkt nach einem Neustart des Model-Pods **Problem: ** Nachdem ein Modell-Pod gelöscht wurde und ein Ersatz-Pod bereit ist, leitet der Endpoint Picker weiter an die IP-Adresse des gelöschten Pods weiter. Anfragen geben HTTP 503 zurück oder die Verbindung wurde abgelehnt, und der Zustand wird nicht von selbst wiederhergestellt. **Lösung: ** Fügen Sie dem Modell-Pod eine Bereitschaftsprüfung hinzu, sodass Kubernetes den Pod markiert, NotReady bevor seine IP aus dem Pool entfernt wird, und den Ersatz-Pod erst ankündigt, wenn er den Datenverkehr vollständig bedient. Stellen Sie `port` den Health-Endpunkt des Schedulers `targetPort` und `path` Ihres Modellservers ein: ``` readinessProbe: httpGet: path: /health port: 8000 ``` **Problemumgehung: ** Wenn Sie den Modell-Pod nicht sofort erneut bereitstellen können, starten Sie den Endpoint Picker des Schedulers neu, um ihn zu zwingen, seine Endpunktliste anhand des aktuellen Pod-Sets neu zu erstellen: ``` kubectl rollout restart deploy -n \ -l inference.sagemaker.aws.amazon.com/scheduler= ``` ## Die JWT-Authentifizierung gibt 401 oder 403 zurück **Problem: ** `spec.auth.jwt` ist konfiguriert und Anfragen werden abgelehnt, bevor sie ein Modell erreichen, oder das Gateway wird nie bereit, nachdem die JWT-Authentifizierung aktiviert wurde. **Symptome und Lösung: ** + **HTTP 401. ** Das Token fehlt, ist abgelaufen, falsch formatiert oder sein `iss` Anspruch entspricht nicht dem konfigurierten Anbieter. Bestätigen Sie, dass der Client einen `Authorization: Bearer ` Header sendet, und dekodieren Sie das JWT, um seinen `iss` Anspruch damit zu vergleichen. `spec.auth.jwt.provider.issuer` + **HTTP 403. ** Die Signaturvalidierung ist fehlgeschlagen, oder die Tokens `aud` oder stimmen `requiredClaims` nicht mit der Anbieterkonfiguration überein. Überprüfen Sie die Anbieterkonfiguration und bestätigen Sie, dass die Tokens `aud` und alle Einträge `requiredClaims` übereinstimmen: ``` kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.auth.jwt.provider}' ``` + **Das Gateway wird nie Ready, wenn JWT aktiviert ist. ** Ein generiertes `SecurityPolicy` wird vom Gateway nicht akzeptiert. Untersuchen Sie die SecurityPolicy Ressourcen auf den Grund des Fehlers: ``` kubectl get securitypolicy -A kubectl describe securitypolicy -n ``` Eine häufige Ursache `spec.auth.jwt.provider.remoteJWKS.uri` ist, dass sie vom Gateway aus nicht erreichbar ist. Stellen Sie sicher, dass der URI aufgelöst wird und ein gültiges JWKS-Dokument zurückgibt. ## In den Dashboards fehlen Metriken **Problem: ** Endpoint Picker- oder Body-Based Router-Metriken werden nicht in Ihrem Monitoring-Dashboard angezeigt. **Symptome und Lösung: Die Erfassung von ** Metriken ist standardmäßig aktiviert, sodass das OpenTelemetry Collector-Sidecar normalerweise vorhanden ist. Vergewissern Sie sich, ob der Sidecar auf beiden Pod-Typen läuft und ob Metriken explizit deaktiviert wurden. Überprüfe den Sidecar auf den Router-Pods: Body-Based ``` kubectl -n hyperpod-inference-system get pods \ -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel ``` Überprüfen Sie den Sidecar auf den Endpoint Picker-Pods: ``` kubectl -n get pods \ -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel ``` Prüfen Sie, ob Metriken explizit deaktiviert wurden: ``` kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.observability.metrics.enabled}' ``` Eine leere Ausgabe des letzten Befehls bedeutet, dass das Feld nicht gesetzt ist und Metriken aktiviert sind. Nur ein Explizit `false` deaktiviert den Sidecar. Wenn der Wert gleich ist`false`, setzen Sie ihn auf das Feld `true` oder entfernen Sie es, und der Controller fügt das Sidecar beim nächsten Abgleich ein. ## Fehler bei der Anfrage **Problem: ** Das Gateway ist bereit, aber Inferenzanforderungen schlagen fehl. **Symptome und Lösung: ** + **HTTP 404 für ein bekanntes Modell. ** Der `model` Wert im Anforderungstext entspricht nicht genau dem eines Schedulers`modelName`, oder das angeforderte Modell wird über einen LoRa-Adapter bereitgestellt, der nicht unter deklariert ist. `spec.schedulers[].loraAdapters` Wenn kein Scheduler dem angeforderten Modell entspricht und nicht gesetzt `spec.bbr.defaultBackend` ist, gibt das Gateway 404 zurück. Überprüfen Sie die konfigurierten Modell- und Adapternamen: ``` kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.schedulers[*].modelName}' kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.schedulers[*].loraAdapters}' ``` + **Anfragen hängen und es kommt zu einem Timeout. ** Model-serving Die Pods laden immer noch Modellgewichte, oder der `InferencePool` hat keine Ready-Endpunkte. Warten Sie, bis die Model-Pods bereit sind, bevor Sie den Gateway-Endpunkt aufrufen. Verwenden Sie die `modelSelector` Beschriftungen des Schedulers von Ihnen `InferenceGatewayConfig` als Selektor: ``` kubectl get pods -n -l = kubectl logs -n ``` ## Auswahl des Debugging-Endpunkts **Problem: ** Der Datenverkehr wird zu einer kleinen Anzahl von Modell-Pods verschoben, oder eine LoRa-Anfrage wird an einen Pod weitergeleitet, der den Adapter nicht hostet. **Lösung: Erhöhen Sie ** vorübergehend die Log-Ausführlichkeit des Endpoint Pickers, um seine Bewertungsentscheidungen zu überprüfen. Im Scheduler eingestellt`logLevel`: ``` spec: schedulers: - name: logLevel: 4 ``` Bedeutungen auf Protokollebene: + `1`- Lifecycle-Ereignisse anfordern. + `2`- Standard. Verwarnungen und Zulassungsverweigerungen. + `3`— Zusammenfassungen der ausgewählten Endpunkte und der Ergebnisse pro Punktezähler. + `4`- Per-endpoint, Ergebnisse pro Punktezähler und gewichtete Gesamtwerte. + `5`- Protocol-level verfolgen (ausführlich). Überprüfen Sie die Endpoint Picker-Protokolle: ``` kubectl logs -n -l app=-epp -c epp --tail=200 -f ``` Kehren `logLevel` Sie nach Abschluss der Untersuchung zur Standardeinstellung zurück, um ein übermäßiges Protokollvolumen zu vermeiden. ## Lebenszyklus und Bereinigung **Problem: Bei der ** Deinstallation oder Aktualisierung des HyperPod Inference Amazon EKS-Add-ons verbleiben verwaiste Ressourcen im Cluster oder eine nachfolgende Installation wird blockiert. **Lösung: Löschen Sie ** immer alle `InferenceGatewayConfig` Ressourcen, bevor Sie das Add-on deinstallieren oder aktualisieren. Bei der Deinstallation des Add-ons, solange ein noch vorhanden `InferenceGatewayConfig` ist, wird der Controller entfernt, dem die Finalizer der Ressource gehören, sodass diese Ressourcen hängen bleiben. `Terminating` ``` kubectl delete inferencegatewayconfig --all -A kubectl get inferencegatewayconfig -A ``` Bestätigen Sie, dass der zweite Befehl keine Zeilen zurückgibt, bevor Sie mit dem Add-On-Vorgang fortfahren. Listen Sie nach der Neuinstallation des Add-ons die Ressourcen im Gateway-Namespace auf und entfernen Sie alles, was keiner Live-Datei mehr entspricht: `InferenceGatewayConfig` ``` kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \ -n hyperpod-inference-system ``` Vom Controller ausgestellte ACM-Zertifikate werden bei einer Deinstallation des Add-Ons nicht gelöscht. Um sie zu entfernen, filtern Sie ACM-Zertifikate in der AWS Resource Groups Tagging API nach dem Tag `CreatedBy=HyperPodInference` und löschen Sie die Zertifikate, die Sie nicht mehr benötigen. ## Sammeln Sie Protokolle Verwenden Sie die folgenden Befehle, um Protokolle von jeder Gateway-Komponente abzurufen: ``` # 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 ```