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á. # HyperPod solução de problemas de inferência Este guia de solução de problemas aborda problemas comuns que podem ocorrer durante a implantação e operação do Amazon SageMaker HyperPod Inference. Esses problemas geralmente envolvem configuração de rede VPC, permissões de IAM, gerenciamento de recursos do Kubernetes e problemas de conectividade do operador que podem impedir a implantação bem-sucedida do modelo ou fazer com que as implantações falhem ou permaneçam em estados pendentes. Este guia de solução de problemas usa a seguinte terminologia: As **etapas de solução** de problemas são procedimentos de diagnóstico para identificar e investigar problemas, a **Resolução** fornece as ações específicas para corrigir os problemas identificados e a **Verificação** confirma se a solução funcionou corretamente. **Topics** + [Inferir falhas na instalação do operador por meio do console de SageMaker IA](sagemaker-hyperpod-model-deployment-ts-console-cfn-failures.md) + [Falhas de instalação do operador de inferência por meio da CLI AWS](sagemaker-hyperpod-model-deployment-ts-cli.md) + [Tempo limite de download do certificado](sagemaker-hyperpod-model-deployment-ts-certificate.md) + [Problemas de implantação do modelo](sagemaker-hyperpod-model-deployment-ts-deployment-issues.md) + [Problema de permissão VPC ENI](sagemaker-hyperpod-model-deployment-ts-permissions.md) + [Problema de relacionamento de confiança do IAM](sagemaker-hyperpod-model-deployment-ts-trust.md) + [Erro ausente do plug-in da GPU NVIDIA](sagemaker-hyperpod-model-deployment-ts-gpu.md) + [O operador de inferência falha ao iniciar](sagemaker-hyperpod-model-deployment-ts-startup.md) # Inferir falhas na instalação do operador por meio do console de SageMaker IA **Visão geral:** ao instalar o operador de inferência por meio do console de SageMaker IA usando a instalação rápida ou a instalação personalizada, as CloudFormation pilhas subjacentes podem falhar devido a vários problemas. Esta seção aborda cenários de falha comuns e suas resoluções. ## Falha na instalação do complemento do operador de inferência por meio da instalação rápida ou personalizada **Problema:** a criação do HyperPod cluster é concluída com êxito, mas a instalação do complemento do operador de inferência falha. **Causas comuns:** + Os limites de capacidade do pod foram excedidos nos nós do cluster. A instalação do operador de inferência requer um mínimo de 13 pods. O tipo mínimo de instância recomendado é`ml.c5.4xlarge`. + Problemas de permissão do IAM + Restrições de cota de recursos + Problemas de configuração de rede ou VPC ### Sintomas e diagnóstico **Sintomas:** + O complemento do operador de inferência mostra o status CREATE\$1FAILED ou DEGRADED no console + CloudFormation a pilha associada ao complemento está no estado CREATE\$1FAILED + O progresso da instalação é interrompido ou mostra mensagens de erro **Etapas de diagnóstico:** 1. Verifique o status do complemento do operador de inferência: ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health,Issues:issues}" \ --output json ``` 1. Verifique se há problemas de limite de pods: ``` # Check current pod count per node kubectl get nodes -o json | jq '.items[] | {name: .metadata.name, allocatable: .status.allocatable.pods, capacity: .status.capacity.pods}' # Check pods running on each node kubectl get pods --all-namespaces -o wide | awk '{print $8}' | sort | uniq -c # Check for pod evictions or failures kubectl get events --all-namespaces --sort-by='.lastTimestamp' | grep -i "pod\|limit\|quota" ``` 1. Verifique o status da CloudFormation pilha (se estiver usando a instalação do console): ``` # List CloudFormation stacks related to the cluster aws cloudformation list-stacks \ --region $REGION \ --query "StackSummaries[?contains(StackName, '$EKS_CLUSTER_NAME') && StackStatus=='CREATE_FAILED'].{Name:StackName,Status:StackStatus,Reason:StackStatusReason}" \ --output table # Get detailed stack events aws cloudformation describe-stack-events \ --stack-name \ --region $REGION \ --query "StackEvents[?ResourceStatus=='CREATE_FAILED']" \ --output table ``` ### Resolução Para resolver a falha na instalação, salve a configuração atual, exclua o complemento com falha, corrija o problema subjacente e reinstale o operador de inferência por meio do console de SageMaker IA (recomendado) ou da CLI. AWS **Etapa 1: Salvar a configuração atual** + Extraia e salve a configuração do complemento antes da exclusão: ``` # Save the current configuration aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query 'addon.configurationValues' \ --output text > addon-config-backup.json # Verify the configuration was saved cat addon-config-backup.json # Pretty print for readability cat addon-config-backup.json | jq '.' ``` **Etapa 2: excluir o complemento com falha** + Exclua o complemento do operador de inferência: ``` aws eks delete-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION # Wait for deletion to complete echo "Waiting for add-on deletion..." aws eks wait addon-deleted \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION 2>/dev/null || sleep 60 ``` **Etapa 3: corrigir o problema subjacente** Escolha a resolução apropriada com base na causa da falha: Se o problema for que o limite de pods foi excedido: ``` # The inference operator requires a minimum of 13 pods. # The minimum recommended instance type is ml.c5.4xlarge. # # Option 1: Add instance group with higher pod capacity # Different instance types support different maximum pod counts # For example: m5.large (29 pods), m5.xlarge (58 pods), m5.2xlarge (58 pods) aws sagemaker update-cluster \ --cluster-name $HYPERPOD_CLUSTER_NAME \ --region $REGION \ --instance-groups '[{"InstanceGroupName":"worker-group-2","InstanceType":"ml.m5.xlarge","InstanceCount":2}]' # Option 2: Scale existing node group to add more nodes aws eks update-nodegroup-config \ --cluster-name $EKS_CLUSTER_NAME \ --nodegroup-name \ --scaling-config minSize=2,maxSize=10,desiredSize=5 \ --region $REGION # Option 3: Clean up unused pods kubectl delete pods --field-selector status.phase=Failed --all-namespaces kubectl delete pods --field-selector status.phase=Succeeded --all-namespaces ``` **Etapa 4: reinstalar o operador de inferência** Depois de corrigir o problema subjacente, reinstale o operador de inferência usando um dos seguintes métodos: + **SageMaker Console de IA com instalação personalizada (recomendado):** reutilize as funções do IAM e o bucket TLS existentes da sua instalação anterior. Para obter as etapas, consulte [Método 1: instalar o complemento de HyperPod inferência por meio do console de SageMaker IA (recomendado)](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-ui). + **AWS CLI com configuração salva: use a configuração** da qual você fez backup na Etapa 1 para reinstalar o complemento. Para ver as etapas completas de instalação da CLI, consulte. [Método 2: Instalando o operador de inferência usando a CLI AWS](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-addon) ``` aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --addon-version v1.0.0-eksbuild.1 \ --configuration-values file://addon-config-backup.json \ --region $REGION ``` + **SageMaker Console de IA com instalação rápida:** cria automaticamente novas funções do IAM, bucket TLS e complementos de dependência. Para obter as etapas, consulte [Método 1: instalar o complemento de HyperPod inferência por meio do console de SageMaker IA (recomendado)](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-ui). **Etapa 5: verificar se a instalação foi bem-sucedida** ``` # Check add-on status aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health}" \ --output table # Verify pods are running kubectl get pods -n hyperpod-inference-system # Check operator logs kubectl logs -n hyperpod-inference-system deployment/hyperpod-inference-controller-manager --tail=50 ``` ## A instalação do Cert-manager falhou devido ao webhook Kueue não estar pronto **Problema:** A instalação do complemento cert-manager falha com um erro de webhook porque o serviço de webhook do Task Governance (Kueue) não tem endpoints disponíveis. Essa é uma condição de corrida que ocorre quando o cert-manager tenta criar recursos antes que os pods de webhook do Task Governance estejam totalmente em execução. Isso pode acontecer quando o complemento Task Governance está sendo instalado junto com o operador Inference durante a criação do cluster. ### Sintomas e diagnóstico **Mensagem de erro:** ``` AdmissionRequestDenied Internal error occurred: failed calling webhook "mdeployment.kb.io": failed to call webhook: Post "https://kueue-webhook-service.kueue-system.svc:443/mutate-apps-v1-deployment?timeout=10s": no endpoints available for service "kueue-webhook-service" ``` **Causa raiz:** + O complemento Task Governance instala e registra um webhook mutante que intercepta todas as criações de implantação + O complemento Cert-Manager tenta criar recursos de implantação antes que os pods de webhook do Task Governance estejam prontos + O controle de admissão do Kubernetes chama o webhook de Governança de Tarefas, mas ele não tem endpoints (os pods ainda não estão em execução) **Etapa de diagnóstico:** 1. Verifique o status do complemento cert-manager: ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name cert-manager \ --region $REGION \ --query "addon.{Status:status,Health:health,Issues:issues}" \ --output json ``` ### Resolução **Solução: exclua e reinstale o cert-manager** O webhook de Governança de Tarefas fica pronto em 60 segundos. Basta excluir e reinstalar o complemento cert-manager: 1. Exclua o complemento cert-manager com falha: ``` aws eks delete-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name cert-manager \ --region $REGION ``` 1. Aguarde de 30 a 60 segundos para que o webhook de Governança de Tarefas fique pronto e reinstale o complemento cert-manager: ``` sleep 60 aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name cert-manager \ --region $REGION ``` # Falhas de instalação do operador de inferência por meio da CLI AWS **Visão geral:** ao instalar o operador de inferência por meio da AWS CLI, a instalação do complemento pode falhar devido à falta de dependências. Esta seção aborda cenários comuns de falha na instalação da CLI e suas resoluções. ## Falha na instalação do complemento de inferência devido à falta de drivers CSI **Problema:** a criação do complemento do operador de inferência falha porque as dependências necessárias do driver CSI não estão instaladas no cluster EKS. **Sintomas e diagnóstico:** **Mensagens de erro:** Os seguintes erros aparecem nos registros de criação do complemento ou nos registros do operador de inferência: ``` S3 CSI driver not installed (missing CSIDriver s3.csi.aws.com). Please install the required CSI driver and see the troubleshooting guide for more information. FSx CSI driver not installed (missing CSIDriver fsx.csi.aws.com). Please install the required CSI driver and see the troubleshooting guide for more information. ``` **Etapas de diagnóstico:** 1. Verifique se os drivers CSI estão instalados: ``` # Check for S3 CSI driver kubectl get csidriver s3.csi.aws.com kubectl get pods -n kube-system | grep mountpoint # Check for FSx CSI driver kubectl get csidriver fsx.csi.aws.com kubectl get pods -n kube-system | grep fsx ``` 1. Verifique o status do complemento EKS: ``` # List all add-ons aws eks list-addons --cluster-name $EKS_CLUSTER_NAME --region $REGION # Check specific CSI driver add-ons aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-mountpoint-s3-csi-driver --region $REGION 2>/dev/null || echo "S3 CSI driver not installed" aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-fsx-csi-driver --region $REGION 2>/dev/null || echo "FSx CSI driver not installed" ``` 1. Verifique o status do complemento do operador de inferência: ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health,Issues:issues}" \ --output json ``` **Resolução:** **Etapa 1: instalar o driver CSI S3 ausente** 1. Crie a função IAM para o driver CSI do S3 (se ainda não tiver sido criada): ``` # Set up service account role ARN (from installation steps) export S3_CSI_ROLE_ARN=$(aws iam get-role --role-name $S3_CSI_ROLE_NAME --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found") echo "S3 CSI Role ARN: $S3_CSI_ROLE_ARN" ``` 1. Instale o complemento do driver S3 CSI: ``` aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name aws-mountpoint-s3-csi-driver \ --addon-version v1.14.1-eksbuild.1 \ --service-account-role-arn $S3_CSI_ROLE_ARN \ --region $REGION ``` 1. Verifique a instalação do driver S3 CSI: ``` # Wait for add-on to be active aws eks wait addon-active --cluster-name $EKS_CLUSTER_NAME --addon-name aws-mountpoint-s3-csi-driver --region $REGION # Verify CSI driver is available kubectl get csidriver s3.csi.aws.com kubectl get pods -n kube-system | grep mountpoint ``` **Etapa 2: instalar o driver FSx CSI ausente** 1. Crie a função do IAM para o driver FSx CSI (se ainda não tiver sido criada): ``` # Set up service account role ARN (from installation steps) export FSX_CSI_ROLE_ARN=$(aws iam get-role --role-name $FSX_CSI_ROLE_NAME --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found") echo "FSx CSI Role ARN: $FSX_CSI_ROLE_ARN" ``` 1. Instale o complemento do driver FSx CSI: ``` aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name aws-fsx-csi-driver \ --addon-version v1.6.0-eksbuild.1 \ --service-account-role-arn $FSX_CSI_ROLE_ARN \ --region $REGION # Wait for add-on to be active aws eks wait addon-active --cluster-name $EKS_CLUSTER_NAME --addon-name aws-fsx-csi-driver --region $REGION # Verify FSx CSI driver is running kubectl get pods -n kube-system | grep fsx ``` **Etapa 3: verificar todas as dependências** Depois de instalar as dependências ausentes, verifique se elas estão funcionando corretamente antes de tentar novamente a instalação do operador de inferência: ``` # Check all required add-ons are active aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-mountpoint-s3-csi-driver --region $REGION aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-fsx-csi-driver --region $REGION aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name metrics-server --region $REGION aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name cert-manager --region $REGION # Verify all pods are running kubectl get pods -n kube-system | grep -E "(mountpoint|fsx|metrics-server)" kubectl get pods -n cert-manager ``` ## Definições de recursos personalizados de inferência estão ausentes durante a implantação do modelo **Problema:** Faltam definições de recursos personalizados (CRDs) quando você tenta criar implantações de modelo. Esse problema ocorre quando você instalou e excluiu anteriormente o complemento de inferência sem limpar as implantações do modelo que têm finalizadores. **Sintomas e diagnóstico:** **Causa raiz:** Se você excluir o complemento de inferência sem primeiro remover todas as implantações do modelo, os recursos personalizados com finalizadores permanecerão no cluster. Esses finalizadores devem ser concluídos antes que você possa excluir o. CRDs O processo de exclusão do complemento não espera a conclusão da exclusão do CRD, o que faz com que ele permaneça em um estado de encerramento e impede novas instalações. CRDs **Para diagnosticar esse problema** 1. Verifique se CRDs existe. ``` kubectl get crd | grep inference.sagemaker.aws.amazon.com ``` 1. Verifique se há recursos personalizados bloqueados. ``` # Check for JumpStartModel resources kubectl get jumpstartmodels -A # Check for InferenceEndpointConfig resources kubectl get inferenceendpointconfigs -A ``` 1. Inspecione os finalizadores em recursos bloqueados. ``` # Example for a specific JumpStartModel kubectl get jumpstartmodels -n -o jsonpath='{.metadata.finalizers}' # Example for a specific InferenceEndpointConfig kubectl get inferenceendpointconfigs -n -o jsonpath='{.metadata.finalizers}' ``` **Resolução:** Remova manualmente os finalizadores de todas as implantações do modelo que não foram excluídas quando você removeu o complemento de inferência. Conclua as etapas a seguir para cada recurso personalizado bloqueado. **Para remover finalizadores dos recursos JumpStartModel ** 1. Liste todos os JumpStartModel recursos em todos os namespaces. ``` kubectl get jumpstartmodels -A ``` 1. Para cada JumpStartModel recurso, remova os finalizadores corrigindo o recurso para definir metadata.finalizers como uma matriz vazia. ``` kubectl patch jumpstartmodels -n -p '{"metadata":{"finalizers":[]}}' --type=merge ``` O exemplo a seguir mostra como corrigir um recurso chamado kv-l1-only. ``` kubectl patch jumpstartmodels kv-l1-only -n default -p '{"metadata":{"finalizers":[]}}' --type=merge ``` 1. Verifique se a instância do modelo foi excluída. ``` kubectl get jumpstartmodels -A ``` Quando todos os recursos estiverem limpos, você deverá ver o seguinte resultado. ``` Error from server (NotFound): Unable to list "inference.sagemaker.aws.amazon.com/v1, Resource=jumpstartmodels": the server could not find the requested resource (get jumpstartmodels.inference.sagemaker.aws.amazon.com) ``` 1. Verifique se o JumpStartModel CRD foi removido. ``` kubectl get crd | grep jumpstartmodels.inference.sagemaker.aws.amazon.com ``` Se o CRD for removido com sucesso, esse comando não retornará nenhuma saída. **Para remover finalizadores dos recursos InferenceEndpointConfig ** 1. Liste todos os InferenceEndpointConfig recursos em todos os namespaces. ``` kubectl get inferenceendpointconfigs -A ``` 1. Para cada InferenceEndpointConfig recurso, remova os finalizadores. ``` kubectl patch inferenceendpointconfigs -n -p '{"metadata":{"finalizers":[]}}' --type=merge ``` O exemplo a seguir mostra como corrigir um recurso chamado my-inference-config. ``` kubectl patch inferenceendpointconfigs my-inference-config -n default -p '{"metadata":{"finalizers":[]}}' --type=merge ``` 1. Verifique se a instância de configuração foi excluída. ``` kubectl get inferenceendpointconfigs -A ``` Quando todos os recursos estiverem limpos, você deverá ver o seguinte resultado. ``` Error from server (NotFound): Unable to list "inference.sagemaker.aws.amazon.com/v1, Resource=inferenceendpointconfigs": the server could not find the requested resource (get inferenceendpointconfigs.inference.sagemaker.aws.amazon.com) ``` 1. Verifique se o InferenceEndpointConfig CRD foi removido. ``` kubectl get crd | grep inferenceendpointconfigs.inference.sagemaker.aws.amazon.com ``` Se o CRD for removido com sucesso, esse comando não retornará nenhuma saída. **Para reinstalar o complemento de inferência** Depois de limpar todos os recursos bloqueados e verificar se CRDs eles foram removidos, reinstale o complemento de inferência. Para obter mais informações, consulte [Instalando o operador de inferência com o complemento EKS](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-install-inference-operator-addon). **Verificação:** 1. Verifique se o complemento de inferência foi instalado com êxito. ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health}" \ --output table ``` O Status deve ser ATIVO e a Saúde deve ser SAUDÁVEL. 1. Verifique se CRDs estão instalados corretamente. ``` kubectl get crd | grep inference.sagemaker.aws.amazon.com ``` Você deve ver o relacionado à inferência CRDs listado na saída. 1. Teste a criação de uma nova implantação de modelo para confirmar se o problema foi resolvido. ``` # Create a test deployment using your preferred method kubectl apply -f ``` **Prevenção**: Para evitar esse problema, conclua as etapas a seguir antes de desinstalar o complemento de inferência. 1. Exclua todas as implantações do modelo. ``` # Delete all JumpStartModel resources kubectl delete jumpstartmodels --all -A # Delete all InferenceEndpointConfig resources kubectl delete inferenceendpointconfigs --all -A # Wait for all resources to be fully deleted kubectl get jumpstartmodels -A kubectl get inferenceendpointconfigs -A ``` 1. Verifique se todos os recursos personalizados foram excluídos. 1. Depois de confirmar que todos os recursos foram limpos, exclua o complemento de inferência. ## Falha na instalação do complemento de inferência devido à falta do cert-manager **Problema:** a criação do complemento do operador de inferência falha porque o complemento EKS do cert-manager não está instalado, resultando na ausência de definições de recursos personalizados (). CRDs **Sintomas e diagnóstico:** **Mensagens de erro:** Os seguintes erros aparecem nos registros de criação do complemento ou nos registros do operador de inferência: ``` Missing required CRD: certificaterequests.cert-manager.io. The cert-manager add-on is not installed. Please install cert-manager and see the troubleshooting guide for more information. ``` **Etapas de diagnóstico:** 1. Verifique se o cert-manager está instalado: ``` # Check for cert-manager CRDs kubectl get crd | grep cert-manager kubectl get pods -n cert-manager # Check EKS add-on status aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name cert-manager --region $REGION 2>/dev/null || echo "Cert-manager not installed" ``` 1. Verifique o status do complemento do operador de inferência: ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health,Issues:issues}" \ --output json ``` **Resolução:** **Etapa 1: instalar o complemento cert-manager** 1. Instale o complemento cert-manager EKS: ``` aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name cert-manager \ --addon-version v1.18.2-eksbuild.2 \ --region $REGION ``` 1. Verifique a instalação do cert-manager: ``` # Wait for add-on to be active aws eks wait addon-active --cluster-name $EKS_CLUSTER_NAME --addon-name cert-manager --region $REGION # Verify cert-manager pods are running kubectl get pods -n cert-manager # Verify CRDs are installed kubectl get crd | grep cert-manager | wc -l # Expected: Should show multiple cert-manager CRDs ``` **Etapa 2: Repetir a instalação do operador de inferência** 1. Depois que o cert-manager for instalado, tente novamente a instalação do operador de inferência: ``` # Delete the failed add-on if it exists aws eks delete-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION 2>/dev/null || echo "Add-on not found, proceeding with installation" # Wait for deletion to complete sleep 30 # Reinstall the inference operator add-on aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --addon-version v1.0.0-eksbuild.1 \ --configuration-values file://addon-config.json \ --region $REGION ``` 1. Monitore a instalação: ``` # Check installation status aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health}" \ --output table # Verify inference operator pods are running kubectl get pods -n hyperpod-inference-system ``` ## Falha na instalação do complemento de inferência devido à falta do controlador ALB **Problema:** a criação do complemento do operador de inferência falha porque o Load AWS Balancer Controller não está instalado ou não está configurado corretamente para o complemento de inferência. **Sintomas e diagnóstico:** **Mensagens de erro:** Os seguintes erros aparecem nos registros de criação do complemento ou nos registros do operador de inferência: ``` ALB Controller not installed (missing aws-load-balancer-controller pods). Please install the Application Load Balancer Controller and see the troubleshooting guide for more information. ``` **Etapas de diagnóstico:** 1. Verifique se o controlador ALB está instalado: ``` # Check for ALB Controller pods kubectl get pods -n kube-system | grep aws-load-balancer-controller kubectl get pods -n hyperpod-inference-system | grep aws-load-balancer-controller # Check ALB Controller service account kubectl get serviceaccount aws-load-balancer-controller -n kube-system 2>/dev/null || echo "ALB Controller service account not found" kubectl get serviceaccount aws-load-balancer-controller -n hyperpod-inference-system 2>/dev/null || echo "ALB Controller service account not found in inference namespace" ``` 1. Verifique a configuração do complemento do operador de inferência: ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health,ConfigurationValues:configurationValues}" \ --output json ``` **Resolução:** Escolha uma das seguintes opções com base na sua configuração: **Opção 1: deixar o complemento de inferência instalar o controlador ALB (recomendado)** + Verifique se a função ALB foi criada e configurada corretamente em sua configuração complementar: ``` # Verify ALB role exists export ALB_ROLE_ARN=$(aws iam get-role --role-name alb-role --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found") echo "ALB Role ARN: $ALB_ROLE_ARN" # Update your addon-config.json to enable ALB cat > addon-config.json << EOF { "executionRoleArn": "$EXECUTION_ROLE_ARN", "tlsCertificateS3Bucket": "$BUCKET_NAME", "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN", "alb": { "enabled": true, "serviceAccount": { "create": true, "roleArn": "$ALB_ROLE_ARN" } }, "keda": { "auth": { "aws": { "irsa": { "roleArn": "$KEDA_ROLE_ARN" } } } } } EOF ``` **Opção 2: Usar a instalação existente do controlador ALB** + Se você já tiver o ALB Controller instalado, configure o complemento para usar a instalação existente: ``` # Update your addon-config.json to disable ALB installation cat > addon-config.json << EOF { "executionRoleArn": "$EXECUTION_ROLE_ARN", "tlsCertificateS3Bucket": "$BUCKET_NAME", "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN", "alb": { "enabled": false }, "keda": { "auth": { "aws": { "irsa": { "roleArn": "$KEDA_ROLE_ARN" } } } } } EOF ``` **Etapa 3: Repetir a instalação do operador de inferência** 1. Reinstale o complemento do operador de inferência com a configuração atualizada: ``` # Delete the failed add-on if it exists aws eks delete-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION 2>/dev/null || echo "Add-on not found, proceeding with installation" # Wait for deletion to complete sleep 30 # Reinstall with updated configuration aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --addon-version v1.0.0-eksbuild.1 \ --configuration-values file://addon-config.json \ --region $REGION ``` 1. Verifique se o controlador ALB está funcionando: ``` # Check ALB Controller pods kubectl get pods -n hyperpod-inference-system | grep aws-load-balancer-controller kubectl get pods -n kube-system | grep aws-load-balancer-controller # Check service account annotations kubectl describe serviceaccount aws-load-balancer-controller -n hyperpod-inference-system 2>/dev/null kubectl describe serviceaccount aws-load-balancer-controller -n kube-system 2>/dev/null ``` ## Falha na instalação do complemento de inferência devido à falta do operador KEDA **Problema:** a criação do complemento do operador de inferência falha porque o operador KEDA (Kubernetes Event Driven Autoscaler) não está instalado ou não está configurado adequadamente para o complemento de inferência. **Sintomas e diagnóstico:** **Mensagens de erro:** Os seguintes erros aparecem nos registros de criação do complemento ou nos registros do operador de inferência: ``` KEDA operator not installed (missing keda-operator pods). KEDA can be installed separately in any namespace or via the Inference addon. ``` **Etapas de diagnóstico:** 1. Verifique se o operador KEDA está instalado: ``` # Check for KEDA operator pods in common namespaces kubectl get pods -n keda-system | grep keda-operator 2>/dev/null || echo "KEDA not found in keda-system namespace" kubectl get pods -n kube-system | grep keda-operator 2>/dev/null || echo "KEDA not found in kube-system namespace" kubectl get pods -n hyperpod-inference-system | grep keda-operator 2>/dev/null || echo "KEDA not found in inference namespace" # Check for KEDA CRDs kubectl get crd | grep keda 2>/dev/null || echo "KEDA CRDs not found" # Check KEDA service account kubectl get serviceaccount keda-operator -A 2>/dev/null || echo "KEDA service account not found" ``` 1. Verifique a configuração do complemento do operador de inferência: ``` aws eks describe-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION \ --query "addon.{Status:status,Health:health,ConfigurationValues:configurationValues}" \ --output json ``` **Resolução:** Escolha uma das seguintes opções com base na sua configuração: **Opção 1: deixar o complemento de inferência instalar o KEDA (recomendado)** + Verifique se a função KEDA foi criada e configurada corretamente na configuração do complemento: ``` # Verify KEDA role exists export KEDA_ROLE_ARN=$(aws iam get-role --role-name keda-operator-role --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found") echo "KEDA Role ARN: $KEDA_ROLE_ARN" # Update your addon-config.json to enable KEDA cat > addon-config.json << EOF { "executionRoleArn": "$EXECUTION_ROLE_ARN", "tlsCertificateS3Bucket": "$BUCKET_NAME", "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN", "alb": { "serviceAccount": { "create": true, "roleArn": "$ALB_ROLE_ARN" } }, "keda": { "enabled": true, "auth": { "aws": { "irsa": { "roleArn": "$KEDA_ROLE_ARN" } } } } } EOF ``` **Opção 2: Usar a instalação existente do KEDA** + Se você já tem o KEDA instalado, configure o complemento para usar a instalação existente: ``` # Update your addon-config.json to disable KEDA installation cat > addon-config.json << EOF { "executionRoleArn": "$EXECUTION_ROLE_ARN", "tlsCertificateS3Bucket": "$BUCKET_NAME", "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN", "alb": { "serviceAccount": { "create": true, "roleArn": "$ALB_ROLE_ARN" } }, "keda": { "enabled": false } } EOF ``` **Etapa 3: Repetir a instalação do operador de inferência** 1. Reinstale o complemento do operador de inferência com a configuração atualizada: ``` # Delete the failed add-on if it exists aws eks delete-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --region $REGION 2>/dev/null || echo "Add-on not found, proceeding with installation" # Wait for deletion to complete sleep 30 # Reinstall with updated configuration aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name amazon-sagemaker-hyperpod-inference \ --addon-version v1.0.0-eksbuild.1 \ --configuration-values file://addon-config.json \ --region $REGION ``` 1. Verifique se o KEDA está funcionando: ``` # Check KEDA pods kubectl get pods -n hyperpod-inference-system | grep keda kubectl get pods -n kube-system | grep keda kubectl get pods -n keda-system | grep keda 2>/dev/null # Check KEDA CRDs kubectl get crd | grep scaledobjects kubectl get crd | grep scaledjobs # Check KEDA service account annotations kubectl describe serviceaccount keda-operator -n hyperpod-inference-system 2>/dev/null kubectl describe serviceaccount keda-operator -n kube-system 2>/dev/null kubectl describe serviceaccount keda-operator -n keda-system 2>/dev/null ``` # Tempo limite de download do certificado Ao implantar um endpoint de SageMaker IA, o processo de criação falha devido à incapacidade de baixar o certificado da autoridade de certificação (CA) em um ambiente VPC. Para obter etapas detalhadas de configuração, consulte o [Guia do administrador](https://github.com/aws-samples/sagemaker-genai-hosting-examples/blob/main/SageMakerHyperpod/hyperpod-inference/Hyperpod_Inference_Admin_Notebook.ipynb). **Mensagem de erro:** O erro a seguir aparece nos CloudWatch registros do endpoint de SageMaker IA: ``` Error downloading CA certificate: Connect timeout on endpoint URL: "https://****.s3..amazonaws.com/****/***.pem" ``` **Causa raiz:** + Esse problema ocorre quando o operador de inferência não pode acessar o certificado autoassinado no Amazon S3 dentro da sua VPC. + A configuração adequada do endpoint Amazon S3 VPC é essencial para o acesso ao certificado **Resolução:** 1. Se você não tiver um endpoint Amazon S3 VPC: + [Crie um endpoint VPC do Amazon S3 seguindo a configuração na seção 5.3 do Guia do administrador.](https://github.com/aws-samples/sagemaker-genai-hosting-examples/blob/main/SageMakerHyperpod/hyperpod-inference/Hyperpod_Inference_Admin_Notebook.ipynb) 1. Se você já tem um endpoint Amazon S3 VPC: + Certifique-se de que a tabela de rotas da sub-rede esteja configurada para apontar para o endpoint da VPC (se estiver usando o endpoint do gateway) ou que o DNS privado esteja habilitado para o endpoint da interface. + O endpoint VPC do Amazon S3 deve ser semelhante à configuração mencionada na seção 5.3 Etapa de criação do endpoint # Problemas de implantação do modelo **Visão geral:** esta seção aborda problemas comuns que ocorrem durante a implantação do modelo, incluindo estados pendentes, implantações com falha e monitoramento do progresso da implantação. ## Implantação do modelo paralisada em estado pendente Ao implantar um modelo, a implantação permanece em um estado “Pendente” por um longo período. Isso indica que o operador de inferência não consegue iniciar a implantação do modelo em seu HyperPod cluster. **Componentes afetados:** Durante a implantação normal, o operador de inferência deve: + Implemente um pod de modelo + Criar um load balancer + Crie um endpoint de SageMaker IA **Etapas de solução de problemas:** 1. Verifique o status do pod do operador de inferência: ``` kubectl get pods -n hyperpod-inference-system ``` Exemplo de saída esperado: ``` NAME READY STATUS RESTARTS AGE hyperpod-inference-operator-controller-manager-65c49967f5-894fg 1/1 Running 0 6d13h ``` 1. Analise os registros do operador de inferência e examine os registros do operador em busca de mensagens de erro: ``` kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system ``` **O que procurar:** + Mensagens de erro nos registros do operador + Status do pod do operador + Quaisquer avisos ou falhas relacionados à implantação **nota** Uma implantação saudável deve progredir além do estado “Pendente” dentro de um tempo razoável. Se os problemas persistirem, revise os registros do operador de inferência em busca de mensagens de erro específicas para determinar a causa raiz. ## Solução de problemas do estado de falha na implantação do modelo Quando a implantação de um modelo entra no estado “Falha”, a falha pode ocorrer em um dos três componentes: + Implantação de pod modelo + Criação de balanceador de carga + SageMaker Criação de endpoints de IA **Etapas de solução de problemas:** 1. Verifique o status do operador de inferência: ``` kubectl get pods -n hyperpod-inference-system ``` Saída esperada: ``` NAME READY STATUS RESTARTS AGE hyperpod-inference-operator-controller-manager-65c49967f5-894fg 1/1 Running 0 6d13h ``` 1. Revise os registros do operador: ``` kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system ``` **O que procurar:** Os registros do operador indicarão qual componente falhou: + Falhas na implantação do pod de modelo + Problemas de criação do balanceador de carga + SageMaker Erros de endpoint de IA ## Verificando o progresso da implantação do modelo Para monitorar o progresso da implantação do seu modelo e identificar possíveis problemas, você pode usar os comandos kubectl para verificar o status de vários componentes. Isso ajuda a determinar se a implantação está progredindo normalmente ou se encontrou problemas durante a criação do pod de modelo, a configuração do balanceador de carga ou as fases de configuração do endpoint de SageMaker IA. **Método 1: Verificar o status do JumpStart modelo** ``` kubectl describe jumpstartmodel.inference.sagemaker.aws.amazon.com/ -n ``` **Principais indicadores de status a serem monitorados:** 1. Status da implantação + Procure por`Status.State`: Deve mostrar `DeploymentComplete` + Verifique `Status.Deployment Status.Available Replicas` + Monitore `Status.Conditions` o progresso da implantação 1. SageMaker Status do endpoint de IA + Verifique`Status.Endpoints.Sagemaker.State`: Deve aparecer `CreationCompleted` + Verifique `Status.Endpoints.Sagemaker.Endpoint Arn` 1. Status do certificado TLS + Exibir `Status.Tls Certificate` detalhes + Verifique a expiração do certificado em `Last Cert Expiry Time` **Método 2: Verificar a configuração do endpoint de inferência** ``` kubectl describe inferenceendpointconfig.inference.sagemaker.aws.amazon.com/ -n ``` **O status comum afirma:** + `DeploymentInProgress`: Fase inicial de implantação + `DeploymentComplete`: Implantação bem-sucedida + `Failed`: Falha na implantação **nota** Monitore a seção Eventos em busca de avisos ou erros. Verifique se a contagem de réplicas corresponde à configuração esperada. Verifique se todas as condições são exibidas `Status: True` para uma implantação saudável. # Problema de permissão VPC ENI SageMaker A criação de endpoints de IA falha devido a permissões insuficientes para criar interfaces de rede na VPC. **Mensagem de erro:** ``` Please ensure that the execution role for variant AllTraffic has sufficient permissions for creating an endpoint variant within a VPC ``` **Causa raiz:** A função de execução do operador de inferência não tem a permissão necessária do Amazon EC2 para criar interfaces de rede (ENI) na VPC. **Resolução:** Adicione a seguinte permissão do IAM à função de execução do operador de inferência: ``` { "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterfacePermission", "ec2:DeleteNetworkInterfacePermission" ], "Resource": "*" } ``` **Verificação:** Depois de adicionar a permissão: 1. Exclua o endpoint com falha (se existir) 1. Repita a criação do endpoint 1. Monitore o status da implantação para uma conclusão bem-sucedida **nota** Essa permissão é essencial para endpoints de SageMaker IA executados no modo VPC. Certifique-se de que a função de execução também tenha todas as outras permissões necessárias relacionadas à VPC. # Problema de relacionamento de confiança do IAM HyperPod o operador de inferência falha ao iniciar com um AssumeRoleWithWebIdentity erro STS, indicando um problema de configuração do relacionamento de confiança do IAM. **Mensagem de erro:** ``` failed to enable inference watcher for HyperPod cluster *****: operation error SageMaker: UpdateClusterInference, get identity: get credentials: failed to refresh cached credentials, failed to retrieve credentials, operation error STS: AssumeRoleWithWebIdentity, https response error StatusCode: 403, RequestID: ****, api error AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity ``` **Resolução:** Atualize a relação de confiança da função de execução do IAM do operador de inferência com a configuração a seguir. Substitua os seguintes espaços reservados: + ``: ID AWS da sua conta + ``: Sua AWS região + ``: ID do provedor OIDC do seu cluster Amazon EKS ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringLike": { "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::", "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com" } } }, { "Effect": "Allow", "Principal": { "Service": [ "sagemaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` **Verificação:** Depois de atualizar a relação de confiança: 1. Verifique a configuração da função no console do IAM 1. Reinicie o operador de inferência, se necessário 1. Monitore os registros do operador para uma inicialização bem-sucedida # Erro ausente do plug-in da GPU NVIDIA A implantação do modelo falha com erro de insuficiência de GPU, apesar de ter nós de GPU disponíveis. Isso ocorre quando o plug-in do dispositivo NVIDIA não está instalado no HyperPod cluster. **Mensagem de erro:** ``` 0/15 nodes are available: 10 node(s) didn't match Pod's node affinity/selector, 5 Insufficient nvidia.com/gpu. preemption: 0/15 nodes are available: 10 Preemption is not helpful for scheduling, 5 No preemption victims found for incoming pod. ``` **Causa raiz:** + O Kubernetes não consegue detectar recursos de GPU sem o plug-in de dispositivo NVIDIA + Resulta em falhas de agendamento para cargas de trabalho da GPU **Resolução:** Instale o plug-in da GPU NVIDIA executando: ``` kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/refs/tags/v0.17.1/deployments/static/nvidia-device-plugin.yml ``` **Etapas de verificação:** 1. Verifique o status de implantação do plug-in: ``` kubectl get pods -n kube-system | grep nvidia-device-plugin ``` 1. Verifique se os recursos da GPU agora estão visíveis: ``` kubectl get nodes -o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\\.com/gpu ``` 1. Repetir a implantação do modelo **nota** Certifique-se de que os drivers NVIDIA estejam instalados nos nós da GPU. A instalação do plug-in é uma configuração única por cluster. Pode exigir privilégios de administrador do cluster para instalar. # O operador de inferência falha ao iniciar O pod do operador de inferência falhou ao iniciar e está causando a seguinte mensagem de erro. Esse erro ocorre porque a política de permissão da função de execução do operador não está autorizada a ser executada`sts:AssumeRoleWithWebIdentity`. Devido a isso, a peça do operador em execução no plano de controle não é iniciada. **Mensagem de erro:** ``` Warning Unhealthy 5m46s (x22 over 49m) kubelet Startup probe failed: Get "http://10.1.100.59:8081/healthz": context deadline exceeded (Client.Timeout exceeded while awaiting headers) ``` **Causa raiz:** + A política de permissão da função de execução do operador de inferência não está definida para acessar o token de autorização para recursos. **Resolução:** Defina a seguinte política da função de execução de `EXECUTION_ROLE_ARN` para o operador de HyperPod inferência: ``` HyperpodInferenceAccessPolicy-ml-cluster to include all resources ``` ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:PutObject", "s3:GetObject", "s3:DeleteObject" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ecr:GetAuthorizationToken" ], "Resource": "*" } ] } ``` ------ **Etapas de verificação:** 1. Alterar a política. 1. Encerre o pod do operador de HyperPod inferência. 1. O pod será reiniciado sem nenhuma exceção.