Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# 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 `HTTPRoute``InferencePool`, 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 -n
```
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 apply`fallisce con`bbr 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 apply`fallisce con`modelName 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 -n
```
+ **`Accepted=False`,. `Reason=ResourceNamingViolation` **Il nome concatenato `-` 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 -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=
```
Quindi riavvialo:
```
kubectl -n hyperpod-inference-system rollout restart deploy/
```
## Per-scheduler guasti
**Problema: ** una condizione specifica dello scheduler (`BackendsReady`,`LoraSupported`, o`PoolReady`) indica che lo scheduler non è completamente pronto.
**Sintomi e risoluzione: **
+ **`BackendsReady=False`, `Reason=NoModelPods` o`Reason=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 --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
```
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 -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 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'`port`endpoint di integrità dello scheduler `targetPort` e del tuo server modello`path`:
```
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 \
-l inference.sagemaker.aws.amazon.com/scheduler=
```
## 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 `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 corrispondano`requiredClaims`:
```
kubectl get inferencegatewayconfig -n \
-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 -n
```
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 get pods \
-o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```
Verifica se le metriche sono state disattivate esplicitamente:
```
kubectl get inferencegatewayconfig -n \
-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 -n \
-o jsonpath='{.spec.schedulers[*].modelName}'
kubectl get inferencegatewayconfig -n \
-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 -l =
kubectl logs -n
```
## 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 scheduler`logLevel`:
```
spec:
schedulers:
- 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 -l app=-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 -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
```