Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Guide de dépannage d'Inference Gateway
**Présentation : ** La passerelle d' HyperPod inférence achemine le trafic via trois couches : le Body-Based routeur (BBR), la passerelle avec `HTTPRoute` et le Endpoint Picker (EPP). Une mauvaise configuration à n'importe quelle couche peut entraîner l'échec des requêtes, le trafic atteignant le mauvais modèle ou une charge inégale entre les pods servant des modèles. Cette section couvre les problèmes liés à la passerelle, au BBR, à la passerelle et `HTTPRoute` à EPP, ainsi que tous les problèmes qui en découlent. `InferencePool`
## Diagnostiquer l'état de la
Utilisez les commandes suivantes pour inspecter la passerelle et les ressources qu'elle gère.
Répertoriez toutes les `InferenceGatewayConfig` ressources dans les espaces de noms :
```
kubectl get inferencegatewayconfig -A
```
Afficher l'état détaillé, l'état de déploiement par planificateur et les messages de condition pour une passerelle spécifique :
```
kubectl describe inferencegatewayconfig -n
```
Vérifiez le contrôleur de passerelle et les modules Body-Based du routeur :
```
kubectl get pods -n hyperpod-inference-system
```
Vérifiez les ressources de routage en aval générées par le contrôleur :
```
kubectl get httproute,inferencepool,securitypolicy -A
```
Inspectez `status.conditions` et vérifiez celui de chaque planificateur `rolloutState` (`Pending``Progressing`,`Available`, ou`Degraded`). Les raisons de défaillance exploitables figurent dans le message de condition correspondant.
## Add-on problèmes d'installation
**Problème : des ressources de ** passerelle sont manquantes ou ne `GatewayClass` sont pas acceptées après l'installation du module complémentaire HyperPod Inference Amazon EKS.
**Symptômes et résolution : ** `kubectl get gatewayclass inference-gateway` renvoie `NotFound` ou affiche la ressource`ACCEPTED=False`. Cela indique que le module complémentaire n'est pas installé ou que l'installation n'est pas terminée. Réinstallez ou mettez à jour le module complémentaire :
```
aws eks update-addon --cluster-name $CLUSTER --region $REGION \
--addon-name amazon-sagemaker-hyperpod-inference \
--resolve-conflicts OVERWRITE
```
Vérifiez ensuite que le contrôleur de passerelle est en cours d'exécution :
```
kubectl rollout status deploy/inference-gateway-controller \
-n hyperpod-inference-system --timeout=150s
```
## InferenceGatewayConfig ne pas être prêt
**Problème : ** Un `InferenceGatewayConfig` est créé, mais son `status.conditions` affichage `Accepted=False` ou`Ready=False`, ou le, `kubectl apply` est purement et simplement rejeté par validation.
**Symptômes et résolution : **
+ **`kubectl apply`échoue avec`bbr must be enabled when more than one scheduler is defined`. ** Le Body-Based routeur est requis chaque fois que plus d'un planificateur est défini. Définissez `spec.bbr.enabled` sur `true`.
+ **`kubectl apply`échoue avec`modelName must be unique across schedulers`. ** Deux planificateurs déclarent la même chose. `modelName` Renommez-en un pour que chaque planificateur ait un nom distinct. `modelName`
+ **`Accepted=False`,`Reason=InvalidLoraAdapters`. **Le nom d'un adaptateur LoRa déclaré sous `spec.schedulers[].loraAdapters` est un doublon entre les planificateurs ou entre en collision avec celui d'un planificateur. `modelName` Vérifiez le message de condition pour détecter le nom incriminé :
```
kubectl describe inferencegatewayconfig -n
```
+ **`Accepted=False`,`Reason=ResourceNamingViolation`. **Le nom concaténé `-` dépasse la limite de 63 caractères des libellés de Kubernetes. Raccourcissez le nom de la configuration ou du planificateur.
+ **`Ready=False`,`Reason=GatewayNotProgrammed`. **La passerelle n'a pas encore provisionné l'équilibreur de charge. Inspectez la passerelle parent :
```
kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway -n hyperpod-inference-system
```
+ **`AdmissionBlocked=True`,`Reason=WebhookDenied`. **Un webhook d'admission au cluster rejette le module de passerelle. Le message de condition nomme le webhook incriminé. Supprimez ou corrigez le webhook, puis redémarrez le déploiement de la passerelle afin que le pod soit recréé immédiatement. Le nom du déploiement est généré, recherchez-le d'abord :
```
kubectl -n hyperpod-inference-system get deploy \
-l gateway.envoyproxy.io/owning-gateway-name=
```
Puis redémarrez-le :
```
kubectl -n hyperpod-inference-system rollout restart deploy/
```
## Per-scheduler échecs
**Problème : la condition ** d'un planificateur spécifique (`BackendsReady``LoraSupported`, ou`PoolReady`) indique que le planificateur n'est pas complètement prêt.
**Symptômes et résolution : **
+ **`BackendsReady=False`, `Reason=NoModelPods` ou`Reason=NoReadyModelPods`. ** Aucune capsule ne correspond`spec.schedulers[].modelSelector`, ou la capsule correspondante n'est pas encore prête. Comparez les étiquettes des capsules servant les modèles à celles du sélecteur du planificateur :
```
kubectl get pods -n --show-labels
```
Déployez les modules servant le modèle et attendez qu'ils soient prêts avant d'appliquer le. `InferenceGatewayConfig`
+ **`BackendsReady=False`,`Reason=InvalidModelSelector`. **Le `matchLabels` ou le `matchExpressions` dessous `modelSelector` est mal formé. Corrigez le sélecteur dans la configuration.
+ **`LoraSupported=False`,`Reason=ModelServerLoraDisabled`. **Le serveur modèle qui soutient ce planificateur n'a pas été démarré avec la prise en charge de LoRa activée. Activez l'indicateur équivalent sur le serveur de modèles (par exemple, `--enable-lora` pour vLLM) et redémarrez les pods de modèle.
+ **`PoolReady=False`, `Reason=NotFound` ou`Reason=NotAccepted`. ** Le `InferencePool` ou ses éléments `HTTPRoute` n'ont pas encore été réconciliés ou acceptés par la passerelle. Inspectez les deux :
```
kubectl get inferencepool,httproute -n
```
Si l'une ou l'autre est toujours manquante plusieurs minutes après l'application de la configuration, décrivez la passerelle parent pour vérifier les erreurs d'admission :
```
kubectl describe gateway -n hyperpod-inference-system
```
## L'état de déploiement du planificateur est dégradé
**Problème : ** le déploiement d'Endpoint Picker pour un planificateur est bloqué et n'est pas disponible.
**Symptômes et résolution : ** la `EPPReady` condition sur le planificateur comporte une raison justifiant l'action. Les causes courantes incluent :
+ L'image du conteneur ne peut pas être extraite.
+ Les pods s'écrasent en boucle.
+ Le conteneur présente une erreur de configuration, telle qu'une variable d'environnement, un montage de volume ou une référence secrète non valide.
+ Le déploiement a dépassé sa date limite de progression.
Utilisez les commandes suivantes pour identifier le planificateur défaillant et inspecter son déploiement :
```
# 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=
```
## Point de terminaison obsolète après le redémarrage d'un module modèle
**Problème : Une ** fois qu'un module modèle est supprimé et qu'un module de remplacement est devenu prêt, Endpoint Picker continue à acheminer vers l'adresse IP du module supprimé. Les requêtes renvoient le protocole HTTP 503 ou la connexion est refusée, et la condition ne se rétablit pas d'elle-même.
**Résolution : ** ajoutez une sonde de préparation au module modèle afin que Kubernetes le marque NotReady avant que son adresse IP ne soit supprimée du pool, et n'annonce le module de remplacement que lorsqu'il dessert l'intégralité du trafic. `port`Réglez sur le point de terminaison de santé du planificateur `targetPort` et `path` de votre serveur modèle :
```
readinessProbe:
httpGet:
path: /health
port: 8000
```
**Solution : ** si vous ne pouvez pas redéployer le module modèle immédiatement, redémarrez le sélecteur de points de terminaison du planificateur pour le forcer à reconstruire sa liste de points de terminaison à partir de l'ensemble de modules actuel :
```
kubectl rollout restart deploy -n \
-l inference.sagemaker.aws.amazon.com/scheduler=
```
## L'authentification JWT renvoie 401 ou 403
**Problème : ** `spec.auth.jwt` est configuré et les demandes sont rejetées avant d'atteindre un modèle, ou la passerelle ne devient jamais prête une fois l'authentification JWT activée.
**Symptômes et résolution : **
+ **HTTP 401. ** Le jeton est manquant, a expiré, est mal formé ou sa `iss` réclamation ne correspond pas au fournisseur configuré. Vérifiez que le client envoie un `Authorization: Bearer ` en-tête et décodez le JWT pour comparer sa `iss` réclamation. `spec.auth.jwt.provider.issuer`
+ **HTTP 403. ** La validation de la signature a échoué, `aud` ou le jeton `requiredClaims` ne correspond pas à la configuration du fournisseur. Inspectez la configuration du fournisseur et confirmez que le jeton `aud` et chaque entrée `requiredClaims` correspondent :
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.auth.jwt.provider}'
```
+ **Gateway ne devient jamais prête lorsque JWT est activé. ** Un produit généré n'`SecurityPolicy`est pas accepté par la passerelle. Inspectez les SecurityPolicy ressources pour déterminer la raison de la panne :
```
kubectl get securitypolicy -A
kubectl describe securitypolicy -n
```
Une cause fréquente est qu'il `spec.auth.jwt.provider.remoteJWKS.uri` est inaccessible depuis la passerelle. Vérifiez que l'URI est résolu et renvoie un document JWKS valide.
## Métriques absentes des tableaux de bord
**Problème : les métriques ** Endpoint Picker ou Body-Based Router n'apparaissent pas dans votre tableau de bord de surveillance.
**Symptômes et résolution : la collecte de ** métriques est activée par défaut, le side-car OpenTelemetry Collector est donc normalement présent. Vérifiez si le side-car fonctionne sur les deux types de pods et si les métriques ont été explicitement désactivées.
Vérifiez le sidecar sur les modules Body-Based Router :
```
kubectl -n hyperpod-inference-system get pods \
-o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```
Vérifiez le sidecar sur les pods Endpoint Picker :
```
kubectl -n get pods \
-o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```
Vérifiez si les métriques ont été explicitement désactivées :
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.observability.metrics.enabled}'
```
La sortie vide de la dernière commande signifie que le champ n'est pas défini et que les métriques sont activées. Seule une option explicite `false` désactive le sidecar. Si la valeur est`false`, définissez-la sur le champ `true` ou supprimez le champ, et le contrôleur injecte le side-car lors de la prochaine réconciliation.
## Échec des demandes
**Problème : ** la passerelle est prête, mais les demandes d'inférence échouent.
**Symptômes et résolution : **
+ **HTTP 404 pour un modèle connu. ** La `model` valeur dans le corps de la demande ne correspond exactement à celle d'aucun planificateur`modelName`, ou le modèle demandé est servi via un adaptateur LoRa qui n'est pas déclaré sous. `spec.schedulers[].loraAdapters` Si aucun planificateur ne correspond au modèle demandé et n'`spec.bbr.defaultBackend`est pas défini, la passerelle renvoie 404. Vérifiez les noms de modèle et les noms d'adaptateurs configurés :
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.schedulers[*].modelName}'
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.schedulers[*].loraAdapters}'
```
+ **Les demandes sont bloquées puis expirent. ** Model-serving les pods chargent toujours les poids du modèle ou n'`InferencePool`ont aucun point de terminaison Ready. Attendez que les modules du modèle soient prêts avant d'appeler le point de terminaison de la passerelle. Utilisez les `modelSelector` étiquettes du planificateur `InferenceGatewayConfig` que vous avez sélectionnées comme sélecteur :
```
kubectl get pods -n -l =
kubectl logs -n
```
## Sélection du point de terminaison de débogage
**Problème : ** le trafic est biaisé vers un petit nombre de modules modèles, ou une requête LoRa est acheminée vers un module qui n'héberge pas l'adaptateur.
**Solution : augmentez ** temporairement la verbosité du journal du Endpoint Picker pour inspecter ses décisions de notation. Définissez `logLevel` sur le planificateur :
```
spec:
schedulers:
- name:
logLevel: 4
```
Signification des niveaux de journalisation :
+ `1`- Demandez des événements du cycle de vie.
+ `2`- Par défaut. Avertissements et refus d'admission.
+ `3`- Résumés des résultats sélectionnés et par scoreur.
+ `4`- Per-endpoint, les scores par buteur et les totaux pondérés.
+ `5`- Protocol-level trace (verbeux).
Inspectez les journaux Endpoint Picker :
```
kubectl logs -n -l app=-epp -c epp --tail=200 -f
```
Revenez `logLevel` à sa valeur par défaut lorsque l'enquête est terminée pour éviter un volume de log excessif.
## Cycle de vie et nettoyage
**Problème : la ** désinstallation ou la mise à niveau du module complémentaire HyperPod Inference Amazon EKS laisse des ressources orphelines dans le cluster ou bloque une installation ultérieure.
**Solution : supprimez ** toujours toutes les `InferenceGatewayConfig` ressources avant de désinstaller ou de mettre à niveau le module complémentaire. La désinstallation du module complémentaire alors qu'un `InferenceGatewayConfig` est toujours présent supprime le contrôleur qui possède les finaliseurs de la ressource, ce qui laisse ces ressources bloquées. `Terminating`
```
kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A
```
Vérifiez que la deuxième commande ne renvoie aucune ligne avant de poursuivre l'opération du module complémentaire.
Après avoir réinstallé le module complémentaire, répertoriez les ressources dans l'espace de noms de la passerelle et supprimez tout ce qui ne correspond plus à un live : `InferenceGatewayConfig`
```
kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
-n hyperpod-inference-system
```
Les certificats ACM émis par le contrôleur ne sont pas supprimés par la désinstallation d'un module complémentaire. Pour les supprimer, filtrez les certificats ACM dans l'API de balisage AWS des groupes de ressources en fonction de la balise `CreatedBy=HyperPodInference` et supprimez les certificats dont vous n'avez plus besoin.
## Collectez les journaux
Utilisez les commandes suivantes pour récupérer les journaux de chaque composant de passerelle :
```
# 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
```