As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Guia de solução de problemas do Inference Gateway
**Visão geral: ** O HyperPod Inference Gateway roteia o tráfego por meio de três camadas: o Body-Based roteador (BBR), o gateway com `HTTPRoute` e o seletor de endpoint (EPP). A configuração incorreta em qualquer camada pode resultar em solicitações fracassadas, tráfego chegando ao modelo errado ou carga desigual nos pods que servem o modelo. Esta seção aborda problemas com o gateway, o BBR, o gateway e`HTTPRoute`,`InferencePool`, e o EPP, e quaisquer problemas decorrentes deles.
## Diagnosticar o estado do gateway
Use os comandos a seguir para inspecionar o gateway e os recursos que ele gerencia.
Liste todos os `InferenceGatewayConfig` recursos em namespaces:
```
kubectl get inferencegatewayconfig -A
```
Mostre mensagens detalhadas de status, estado de lançamento por agendador e condição para um gateway específico:
```
kubectl describe inferencegatewayconfig -n
```
Verifique o controlador do gateway e os pods Body-Based do roteador:
```
kubectl get pods -n hyperpod-inference-system
```
Verifique os recursos de roteamento downstream gerados pelo controlador:
```
kubectl get httproute,inferencepool,securitypolicy -A
```
Inspecione `status.conditions` o de cada agendador `rolloutState` (`Pending`, `Progressing``Available`, ou`Degraded`). Os motivos de falha acionáveis estão na mensagem de condição correspondente.
## Add-on problemas de instalação
**Problema: os recursos do ** gateway estão ausentes ou eles não `GatewayClass` são aceitos após a instalação do complemento HyperPod Inference Amazon EKS.
**Sintomas e resolução: ** `kubectl get gatewayclass inference-gateway` retorna `NotFound` ou mostra o recurso`ACCEPTED=False`. Isso indica que o complemento não está instalado ou que a instalação não foi concluída. Reinstale ou atualize o complemento:
```
aws eks update-addon --cluster-name $CLUSTER --region $REGION \
--addon-name amazon-sagemaker-hyperpod-inference \
--resolve-conflicts OVERWRITE
```
Em seguida, confirme se o controlador do gateway está em execução:
```
kubectl rollout status deploy/inference-gateway-controller \
-n hyperpod-inference-system --timeout=150s
```
## InferenceGatewayConfig não está se tornando pronto
**Problema: ** Um `InferenceGatewayConfig` é criado, mas seu `status.conditions` show `Accepted=False` or`Ready=False`, ou the `kubectl apply` é totalmente rejeitado pela validação.
**Sintomas e resolução: **
+ **`kubectl apply`falha com`bbr must be enabled when more than one scheduler is defined`. ** O Body-Based roteador é necessário sempre que mais de um agendador é definido. Defina `spec.bbr.enabled` como `true`.
+ **`kubectl apply`falha com`modelName must be unique across schedulers`. ** Dois programadores declaram o mesmo`modelName`. Renomeie um para que cada agendador tenha um diferente. `modelName`
+ **`Accepted=False`,`Reason=InvalidLoraAdapters`. **Um nome de adaptador LoRa declarado em `spec.schedulers[].loraAdapters` é uma duplicata entre os agendadores ou colide com o de um agendador. `modelName` Inspecione a mensagem de condição em busca do nome ofensivo:
```
kubectl describe inferencegatewayconfig -n
```
+ **`Accepted=False`,`Reason=ResourceNamingViolation`. **O nome concatenado `-` excede o limite de 63 caracteres do rótulo do Kubernetes. Reduza o nome da configuração ou do agendador.
+ **`Ready=False`,`Reason=GatewayNotProgrammed`. **O gateway ainda não provisionou o balanceador de carga. Inspecione o gateway principal:
```
kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway -n hyperpod-inference-system
```
+ **`AdmissionBlocked=True`,`Reason=WebhookDenied`. **Um webhook de admissão de cluster está rejeitando o pod do gateway. A mensagem de condição nomeia o webhook ofensivo. Remova ou corrija o webhook e reinicie a implantação do gateway para que o pod seja recriado imediatamente. O nome da implantação é gerado, então consulte-o primeiro:
```
kubectl -n hyperpod-inference-system get deploy \
-l gateway.envoyproxy.io/owning-gateway-name=
```
Em seguida, reinicie-o:
```
kubectl -n hyperpod-inference-system rollout restart deploy/
```
## Per-scheduler fracassos
**Problema: A condição de ** um agendador específico (`BackendsReady`,`LoraSupported`, ou`PoolReady`) indica que o agendador não está totalmente pronto.
**Sintomas e resolução: **
+ **`BackendsReady=False`, `Reason=NoModelPods` ou`Reason=NoReadyModelPods`. ** Nenhum pods coincide ou `spec.schedulers[].modelSelector` os pods correspondentes ainda não estão prontos. Compare os rótulos nos pods que servem o modelo com o seletor do agendador:
```
kubectl get pods -n --show-labels
```
Implante os pods que servem o modelo e espere que estejam prontos antes de aplicar o. `InferenceGatewayConfig`
+ **`BackendsReady=False`,`Reason=InvalidModelSelector`. **A parte `matchExpressions` inferior `matchLabels` ou inferior `modelSelector` está malformada. Corrija o seletor na configuração.
+ **`LoraSupported=False`,`Reason=ModelServerLoraDisabled`. **O servidor modelo que suporta esse agendador não foi iniciado com o suporte LoRa ativado. Ative o sinalizador equivalente no servidor do modelo (por exemplo, `--enable-lora` para vLLM) e reinicie os pods do modelo.
+ **`PoolReady=False`, `Reason=NotFound` ou`Reason=NotAccepted`. ** O `InferencePool` ou seus `HTTPRoute` ainda não foram reconciliados ou aceitos pelo gateway. Inspecione ambos:
```
kubectl get inferencepool,httproute -n
```
Se algum deles ainda estiver ausente alguns minutos após a aplicação da configuração, descreva o Gateway principal para verificar se há erros de admissão:
```
kubectl describe gateway -n hyperpod-inference-system
```
## O Scheduler RolloutState está degradado
**Problema: ** A implantação do Endpoint Picker para um agendador está travada e não se torna disponível.
**Sintomas e resolução: ** A `EPPReady` condição no agendador carrega o motivo acionável. As causas comuns incluem:
+ A imagem do contêiner não pode ser extraída.
+ Os pods estão em loop de falha.
+ O contêiner tem um erro de configuração, como uma variável de ambiente inválida, montagem de volume ou referência secreta.
+ A implantação excedeu seu prazo de progresso.
Use os comandos a seguir para identificar o agendador com falha e inspecionar sua implantação:
```
# 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 após a reinicialização de um pod modelo
**Problema: ** depois que um pod modelo é excluído e um pod substituto fica pronto, o Endpoint Picker continua roteando para o endereço IP do pod excluído. As solicitações retornam HTTP 503 ou a conexão é recusada, e a condição não se recupera sozinha.
**Resolução: ** adicione uma sonda de prontidão ao pod modelo para que o Kubernetes marque o pod NotReady antes que seu IP seja removido do pool e anuncie o pod substituto somente quando ele estiver atendendo totalmente ao tráfego. `port`Defina para o endpoint de integridade do agendador `targetPort` e `path` do seu servidor modelo:
```
readinessProbe:
httpGet:
path: /health
port: 8000
```
**Solução alternativa: ** se você não conseguir reimplantar o pod modelo imediatamente, reinicie o Seletor de Endpoint do agendador para forçá-lo a reconstruir sua lista de endpoints a partir do conjunto de pod atual:
```
kubectl rollout restart deploy -n \
-l inference.sagemaker.aws.amazon.com/scheduler=
```
## A autenticação JWT retorna 401 ou 403
**Problema: ** `spec.auth.jwt` está configurado e as solicitações são rejeitadas antes de chegarem a um modelo, ou o gateway nunca fica pronto depois que a autenticação JWT é ativada.
**Sintomas e resolução: **
+ **HTTP 401. ** O token está ausente, expirou, está malformado ou sua `iss` declaração não corresponde ao provedor configurado. Confirme se o cliente envia um `Authorization: Bearer ` cabeçalho e decodifique o JWT para comparar sua `iss` reivindicação. `spec.auth.jwt.provider.issuer`
+ **HTTP 403. ** A validação da assinatura falhou ou o token corresponde `aud` ou `requiredClaims` não à configuração do provedor. Inspecione a configuração do provedor e confirme o token `aud` e todas as entradas `requiredClaims` correspondentes:
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.auth.jwt.provider}'
```
+ **O gateway nunca fica pronto com o JWT ativado. ** Um gerado não `SecurityPolicy` é aceito pelo gateway. Inspecione os SecurityPolicy recursos pelo motivo da falha:
```
kubectl get securitypolicy -A
kubectl describe securitypolicy -n
```
Uma causa comum `spec.auth.jwt.provider.remoteJWKS.uri` é que ela não pode ser acessada pelo gateway. Confirme se o URI resolve e retorna um documento JWKS válido.
## Métricas ausentes nos painéis
**Problema: as métricas ** do Endpoint Picker ou do Body-Based Router não aparecem em seu painel de monitoramento.
**Sintomas e resolução: a coleta de ** métricas é ativada por padrão, então o sidecar OpenTelemetry Collector normalmente está presente. Confirme se o sidecar está sendo executado nos dois tipos de pod e se as métricas foram explicitamente desativadas.
Verifique o sidecar nos pods Body-Based do roteador:
```
kubectl -n hyperpod-inference-system get pods \
-o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```
Verifique o sidecar nos pods do Endpoint Picker:
```
kubectl -n get pods \
-o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```
Verifique se as métricas foram explicitamente desativadas:
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.observability.metrics.enabled}'
```
A saída vazia do último comando significa que o campo não está definido e as métricas estão ativadas. Somente uma opção explícita `false` desativa o sidecar. Se o valor for`false`, defina-o como `true` ou remova o campo, e o controlador injeta o sidecar na próxima reconciliação.
## Falhas na solicitação
**Problema: ** O gateway está pronto, mas as solicitações de inferência falham.
**Sintomas e resolução: **
+ **HTTP 404 para um modelo conhecido. ** O `model` valor no corpo da solicitação não corresponde exatamente ao de nenhum agendador`modelName`, ou o modelo solicitado é servido por meio de um adaptador LoRa que não está declarado em. `spec.schedulers[].loraAdapters` Se nenhum agendador corresponder ao modelo solicitado e não `spec.bbr.defaultBackend` estiver definido, o gateway retornará 404. Verifique os nomes dos modelos e adaptadores configurados:
```
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.schedulers[*].modelName}'
kubectl get inferencegatewayconfig -n \
-o jsonpath='{.spec.schedulers[*].loraAdapters}'
```
+ **As solicitações são suspensas e, em seguida, expiram. ** Model-serving os pods ainda estão carregando pesos do modelo ou não `InferencePool` têm endpoints prontos. Aguarde até que os pods do modelo estejam prontos antes de invocar o endpoint do gateway. Use os `modelSelector` rótulos do seu agendador `InferenceGatewayConfig` como seletor:
```
kubectl get pods -n -l =
kubectl logs -n
```
## Seleção de endpoints de depuração
**Problema: o ** tráfego é distorcido para um pequeno número de modelos de pods ou uma solicitação LoRa é roteada para um pod que não hospeda o adaptador.
**Resolução: aumente ** temporariamente a verbosidade do log do Endpoint Picker para inspecionar suas decisões de pontuação. Defina `logLevel` no agendador:
```
spec:
schedulers:
- name:
logLevel: 4
```
Significados em nível de registro:
+ `1`- Solicite eventos do ciclo de vida.
+ `2`- Padrão. Advertências e rejeições de admissão.
+ `3`- Resumos selecionados do endpoint e por pontuador.
+ `4`- Per-endpoint, pontuações por marcador e totais ponderados.
+ `5`- Protocol-level traço (detalhado).
Inspecione os registros do Endpoint Picker:
```
kubectl logs -n -l app=-epp -c epp --tail=200 -f
```
Retorne `logLevel` ao padrão quando a investigação for concluída para evitar um volume excessivo de registros.
## Ciclo de vida e limpeza
**Problema: ** desinstalar ou atualizar o complemento HyperPod Inference Amazon EKS deixa os recursos órfãos no cluster ou bloqueia uma instalação subsequente.
**Resolução: ** sempre exclua todos os `InferenceGatewayConfig` recursos antes de desinstalar ou atualizar o complemento. A desinstalação do complemento enquanto um ainda `InferenceGatewayConfig` está presente remove o controlador que possui os finalizadores do recurso, o que deixa esses recursos presos. `Terminating`
```
kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A
```
Confirme se o segundo comando não retorna nenhuma linha antes de continuar com a operação adicional.
Depois de reinstalar o complemento, liste os recursos no namespace do gateway e remova qualquer coisa que não seja mais mapeada para uma versão ativa: `InferenceGatewayConfig`
```
kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
-n hyperpod-inference-system
```
Os certificados ACM emitidos pelo controlador não são excluídos por uma desinstalação adicional. Para removê-los, filtre os certificados do ACM na API AWS Resource Groups Tagging pela tag `CreatedBy=HyperPodInference` e exclua os certificados que você não precisa mais.
## Coletar registros
Use os comandos a seguir para recuperar registros de cada componente do 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
```