Diagnosi dello stato del gateway Add-on problemi di installazione InferenceGatewayConfig non diventando Pronto Per-scheduler guasti Scheduler RolloutState è danneggiato Endpoint obsoleto dopo il riavvio del pod del modello L'autenticazione JWT restituisce 401 o 403 Metriche mancanti nelle dashboard Errori nella richiesta Selezione degli endpoint per il debug Ciclo di vita e pulizia Raccogli i log

Guida alla risoluzione dei problemi di Inference Gateway

Panoramica: HyperPod Inference Gateway indirizza il traffico attraverso tre livelli: il Body-Based router (BBR), il gateway con e l'Endpoint HTTPRoute Picker (EPP). Una configurazione errata a qualsiasi livello può causare richieste non riuscite, traffico che raggiunge il modello sbagliato o carico irregolare tra i pod che servono i modelli. Questa sezione tratta i problemi relativi al gateway, al BBR, al gateway e HTTPRouteInferencePool, e all'EPP e tutti i problemi che ne derivano.

Diagnosi dello stato del gateway

Utilizzate i seguenti comandi per ispezionare il gateway e le risorse che gestisce.

Elenca tutte le InferenceGatewayConfig risorse nei namespace:


kubectl get inferencegatewayconfig -A

Mostra messaggi dettagliati sullo stato, sullo stato di implementazione per scheduler e sulle condizioni per un gateway specifico:


kubectl describe inferencegatewayconfig <name> -n <namespace>

Controlla il controller del gateway e i pod del router: Body-Based


kubectl get pods -n hyperpod-inference-system

Controlla le risorse di routing downstream generate dal controller:


kubectl get httproute,inferencepool,securitypolicy -A

Ispeziona status.conditions e ogni scheduler rolloutState (Pending,Progressing, Available o). Degraded I motivi attuabili dell'errore sono indicati nel messaggio di condizione corrispondente.

Add-on problemi di installazione

Problema: le risorse del gateway mancano o non GatewayClass vengono accettate dopo l'installazione del componente aggiuntivo HyperPod Inference Amazon EKS.

Sintomi e risoluzione: kubectl get gatewayclass inference-gateway restituisce NotFound o viene visualizzata la risorsa. ACCEPTED=False Ciò indica che il componente aggiuntivo non è installato o che l'installazione non è stata completata. Reinstalla o aggiorna il componente aggiuntivo:


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

Quindi conferma che il controller del gateway sia in esecuzione:


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

InferenceGatewayConfig non diventando Pronto

Problema: InferenceGatewayConfig viene creato un file, ma il suo status.conditions show Accepted=False o Ready=False the kubectl apply viene rifiutato definitivamente mediante convalida.

Sintomi e risoluzione:

kubectl applyfallisce conbbr must be enabled when more than one scheduler is defined. Il Body-Based Router è richiesto ogni volta che viene definito più di uno scheduler. Imposta spec.bbr.enabled su true.
kubectl applyfallisce conmodelName must be unique across schedulers. Due programmatori dichiarano la stessa cosa. modelName Rinominane uno in modo che ogni scheduler ne abbia uno distinto. modelName
Accepted=False,. Reason=InvalidLoraAdapters Il nome di un adattatore LoRa dichiarato sotto spec.schedulers[].loraAdapters è un duplicato tra gli scheduler o si scontra con quello di uno scheduler. modelName Ispeziona il messaggio di condizione per il nome incriminato:
```
kubectl describe inferencegatewayconfig <name> -n <namespace>
```
Accepted=False,. Reason=ResourceNamingViolation Il nome concatenato <config-name>-<scheduler-name> supera il limite di 63 caratteri dell'etichetta Kubernetes. Abbrevia il nome della configurazione o dello scheduler.
Ready=False,Reason=GatewayNotProgrammed. Il gateway non ha ancora effettuato il provisioning del load balancer. Ispeziona il gateway principale:
```
kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway <name> -n hyperpod-inference-system
```
AdmissionBlocked=True,Reason=WebhookDenied. Un webhook di ammissione al cluster sta rifiutando il gateway pod. Il messaggio di condizione indica il nome del webhook incriminato. Rimuovi o correggi il webhook, quindi riavvia il gateway Deployment in modo che il pod venga ricreato immediatamente. Il nome della distribuzione viene generato, quindi cercalo prima:
```
kubectl -n hyperpod-inference-system get deploy \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>
```
Quindi riavvialo:
```
kubectl -n hyperpod-inference-system rollout restart deploy/<gateway-deployment>
```

Per-scheduler guasti

Problema: una condizione specifica dello scheduler (BackendsReady,LoraSupported, oPoolReady) indica che lo scheduler non è completamente pronto.

Sintomi e risoluzione:

BackendsReady=False, Reason=NoModelPods oReason=NoReadyModelPods. Nessun pod corrisponde o spec.schedulers[].modelSelector i pod corrispondenti non sono ancora pronti. Confronta le etichette sui pod che servono i modelli con il selettore dello scheduler:
```
kubectl get pods -n <namespace> --show-labels
```
Distribuisci i pod per il modellamento e attendi che diventino pronti prima di applicare il. InferenceGatewayConfig
BackendsReady=False,Reason=InvalidModelSelector. La parte matchExpressions inferiore matchLabels o inferiore modelSelector è malformata. Correggi il selettore nella configurazione.
LoraSupported=False,. Reason=ModelServerLoraDisabled Il server modello che supporta questo scheduler non è stato avviato con il supporto LoRa abilitato. Abilita il flag equivalente sul server del modello (ad esempio, --enable-lora per vLLM) e riavvia i pod del modello.
PoolReady=False, oppure. Reason=NotFound Reason=NotAccepted Il InferencePool o i suoi HTTPRoute non sono ancora stati riconciliati o accettati dal gateway. Ispeziona entrambi:
```
kubectl get inferencepool,httproute -n <namespace>
```
Se uno dei due è ancora mancante diversi minuti dopo l'applicazione della configurazione, descrivi il Gateway principale per verificare la presenza di errori di ammissione:
```
kubectl describe gateway -n hyperpod-inference-system
```

Scheduler RolloutState è danneggiato

Problema: la distribuzione di Endpoint Picker per uno scheduler è bloccata e non diventa disponibile.

Sintomi e risoluzione: la EPPReady condizione sullo scheduler riporta il motivo perseguibile. Le cause più comuni includono:

L'immagine del contenitore non può essere estratta.
I pod si bloccano in modo anomalo.
Il contenitore presenta un errore di configurazione, ad esempio una variabile di ambiente non valida, un volume di montaggio o un riferimento segreto.
La distribuzione ha superato la scadenza di avanzamento.

Utilizza i seguenti comandi per identificare lo scheduler in errore e controllarne la distribuzione:


# 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 obsoleto dopo il riavvio del pod del modello

Problema: dopo l'eliminazione di un pod modello e il pod sostitutivo diventa pronto, l'Endpoint Picker continua a indirizzare l'indirizzo IP del pod eliminato. Le richieste restituiscono HTTP 503 o la connessione è rifiutata e la condizione non si ripristina da sola.

Risoluzione: aggiungi una sonda di disponibilità al pod modello in modo che Kubernetes contrassegni il pod NotReady prima che il suo IP venga rimosso dal pool e pubblicizzi il pod sostitutivo solo quando il traffico è completo. Imposta sull'portendpoint di integrità dello scheduler targetPort e del tuo server modellopath:


readinessProbe:
  httpGet:
    path: /health
    port: 8000

Soluzione alternativa: se non è possibile ridistribuire immediatamente il pod del modello, riavvia l'Endpoint Picker dello scheduler per forzarlo a ricostruire l'elenco degli endpoint dal set di pod corrente:


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

L'autenticazione JWT restituisce 401 o 403

Problema: spec.auth.jwt è configurato e le richieste vengono rifiutate prima di raggiungere un modello, oppure il gateway non diventa mai pronto dopo l'abilitazione dell'autenticazione JWT.

Sintomi e risoluzione:

HTTP 401. Il token è mancante, scaduto, non valido o il suo iss claim non corrisponde al provider configurato. Conferma che il client invii un'Authorization: Bearer <token>intestazione e decodifica il JWT con cui confrontare la richiesta. iss spec.auth.jwt.provider.issuer
HTTP 403. La convalida della firma non è riuscita oppure il token aud o requiredClaims non corrisponde alla configurazione del provider. Ispeziona la configurazione del provider e conferma che il token aud e tutti i dati inseriti corrispondanorequiredClaims:
```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.auth.jwt.provider}'
```
Il gateway non diventa mai pronto con JWT abilitato. Un generato non SecurityPolicy è accettato dal gateway. Ispeziona le SecurityPolicy risorse per individuare il motivo dell'errore:
```
kubectl get securitypolicy -A
kubectl describe securitypolicy <name> -n <namespace>
```
Una causa comune spec.auth.jwt.provider.remoteJWKS.uri è l'irraggiungibile dal gateway. Conferma che l'URI si risolve e restituisca un documento JWKS valido.

Metriche mancanti nelle dashboard

Problema: le metriche di Endpoint Picker o Body-Based Router non vengono visualizzate nella dashboard di monitoraggio.

Sintomi e risoluzione: la raccolta delle metriche è abilitata per impostazione predefinita, quindi il sidecar OpenTelemetry Collector è normalmente presente. Verifica se il sidecar è in esecuzione su entrambi i tipi di pod e se le metriche sono state esplicitamente disabilitate.

Controlla il sidecar sui pod del router: Body-Based


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

Controlla il sidecar sui pod Endpoint Picker:


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

Verifica se le metriche sono state disattivate esplicitamente:


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

L'output vuoto dell'ultimo comando indica che il campo non è impostato e le metriche sono abilitate. Solo un valore esplicito false disabilita il sidecar. Se il valore èfalse, impostalo true o rimuovi il campo e il controller inietta il sidecar alla riconciliazione successiva.

Errori nella richiesta

Problema: il gateway è pronto, ma le richieste di inferenza hanno esito negativo.

Sintomi e risoluzione:

HTTP 404 per un modello noto. Il model valore nel corpo della richiesta non corrisponde esattamente a quello di modelName nessuno scheduler oppure il modello richiesto viene servito tramite un adattatore LoRa che non è dichiarato in. spec.schedulers[].loraAdapters Se nessuno scheduler corrisponde al modello richiesto e non spec.bbr.defaultBackend è impostato, il gateway restituisce 404. Verifica i nomi dei modelli e degli adattatori configurati:
```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].modelName}'

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].loraAdapters}'
```
Le richieste si bloccano e quindi scadono. Model-serving i pod stanno ancora caricando i pesi del modello o non InferencePool hanno endpoint Ready. Attendi che i pod del modello diventino pronti prima di richiamare l'endpoint del gateway. Usa le modelSelector etichette dello scheduler inserite nel tuo InferenceGatewayConfig selettore:
```
kubectl get pods -n <namespace> -l <key>=<value>
kubectl logs <pod> -n <namespace>
```

Selezione degli endpoint per il debug

Problema: il traffico viene deviato verso un numero limitato di pod modello oppure una richiesta LoRa viene indirizzata a un pod che non ospita l'adattatore.

Risoluzione: aumenta temporaneamente la verbosità del registro di Endpoint Picker per controllarne le decisioni relative al punteggio. Impostato sullo schedulerlogLevel:


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

Significati a livello di registro:

1- Richiedi eventi del ciclo di vita.
2- Impostazione predefinita. Avvertenze e respingimenti all'ammissione.
3- Riepiloghi degli endpoint e dei punteggi selezionati.
4- Per-endpoint, punteggi per marcatore e totali ponderati.
5- Protocol-level traccia (dettagliata).

Ispeziona i log di Endpoint Picker:


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

Ritorna logLevel ai valori predefiniti una volta completata l'indagine per evitare un volume di log eccessivo.

Ciclo di vita e pulizia

Problema: la disinstallazione o l'aggiornamento del componente aggiuntivo HyperPod Inference Amazon EKS lascia risorse orfane nel cluster o blocca un'installazione successiva.

Risoluzione: elimina sempre tutte le InferenceGatewayConfig risorse prima di disinstallare o aggiornare il componente aggiuntivo. La disinstallazione del componente aggiuntivo mentre InferenceGatewayConfig è ancora presente rimuove il controller che possiede i finalizzatori della risorsa, il che lascia tali risorse bloccate. Terminating


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

Verificate che il secondo comando non restituisca alcuna riga prima di continuare con l'operazione del componente aggiuntivo.

Dopo aver reinstallato il componente aggiuntivo, elenca le risorse nel namespace del gateway e rimuovi tutto ciò che non è più associato a un live: InferenceGatewayConfig


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

I certificati ACM emessi dal controller non vengono eliminati dalla disinstallazione di un componente aggiuntivo. Per rimuoverli, filtra i certificati ACM nell'API AWS Resource Groups Tagging in base al tag CreatedBy=HyperPodInference ed elimina i certificati che non ti servono più.

Raccogli i log

Utilizza i seguenti comandi per recuperare i log da ogni componente del gateway:


# 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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Problemi di distribuzione di Disaggregated Prefill and Decode (DPD)

Pesi dei modelli e memorizzazione nella cache delle immagini