View a markdown version of this page

Leitfaden zur Fehlerbehebung bei Inference Gateway - Amazon SageMaker KI
Diagnose des Gateway-StatusAdd-on Probleme bei der InstallationInferenceGatewayConfig wird nicht bereitPer-scheduler AusfälleScheduler RolloutState ist herabgestuftVeralteter Endpunkt nach einem Neustart des Model-PodsDie JWT-Authentifizierung gibt 401 oder 403 zurückIn den Dashboards fehlen MetrikenFehler bei der AnfrageAuswahl des Debugging-EndpunktsLebenszyklus und BereinigungSammeln Sie Protokolle

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 HTTPRouteInferencePool, 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 <name> -n <namespace>

Ü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 (PendingProgressing,Available, oderDegraded). 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 angezeigtACCEPTED=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 oderReady=False, oder die kubectl apply wird bei der Validierung sofort zurückgewiesen.

Symptome und Lösung:

  • kubectl applyschlägt fehl mitbbr 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 applyschlägt fehl mitmodelName must be unique across schedulers. Zwei Scheduler deklarieren dasselbemodelName. 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 <name> -n <namespace>

  • Accepted=False,Reason=ResourceNamingViolation. Der verkettete Name <config-name>-<scheduler-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 <name> -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=<gateway-name>

    Dann starte es neu:

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

Per-scheduler Ausfälle

Problem: Der Zustand eines bestimmten Schedulers (BackendsReady, oderPoolReady) weist darauf hinLoraSupported, dass der Scheduler nicht vollständig bereit ist.

Symptome und Lösung:

  • BackendsReady=False, Reason=NoModelPods oderReason=NoReadyModelPods. Keine Pods stimmen übereinspec.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 <namespace> --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 <namespace>

    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 <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>

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 <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

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 <token> 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 <name> -n <namespace> \
  -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 <name> -n <namespace>

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

Prüfen Sie, ob Metriken explizit deaktiviert wurden:

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -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 istfalse, 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 SchedulersmodelName, 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 <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].modelName}'

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -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 <namespace> -l <key>=<value>
kubectl logs <pod> -n <namespace>

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 eingestelltlogLevel:

spec:
  schedulers:
    - name: <scheduler-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 <namespace> -l app=<scheduler-name>-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 <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