HyperPod 推理疑难解答 - 亚马逊 SageMaker AI
由于缺少 CSI 驱动程序，推理插件安装失败模型部署期间缺少推理自定义资源定义由于缺少证书管理器，推理插件安装失败由于缺少 ALB 控制器，推理插件安装失败由于缺少 KEDA 操作员，推理插件安装失败证书下载超时模型部署停留在待处理状态模型部署失败状态疑难解答检查模型部署进度VPC 弹性网卡权限问题IAM 信任关系问题缺少英伟达 GPU 插件错误推理运算符无法启动

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

HyperPod 推理疑难解答

本疑难解答指南解决了 Amazon SageMaker HyperPod 推理部署和操作期间可能出现的常见问题。这些问题通常涉及 VPC 网络配置、IAM 权限、Kubernetes 资源管理和操作员连接问题，这些问题可能会阻碍成功部署模型或导致部署失败或保持待处理状态。

本故障排除指南使用以下术语：故障排除步骤是识别和调查问题的诊断程序，解决方案提供修复已发现问题的具体操作，验证确认解决方案是否正常运行。

快速参考：找到你的问题

使用以下类别快速找到与您的问题相关的疑难解答部分：

由于缺少 CSI 驱动程序，推理插件安装失败

问题：推理运算符插件创建失败，因为 EKS 集群上未安装所需的 CSI 驱动程序依赖项。

症状和诊断

错误消息：

插件创建日志或推理操作员日志中出现以下错误：

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.

诊断步骤：

  1. 检查是否安装了 CSI 驱动程序：

    # 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

  2. 检查 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"

  3. 检查推理运算符插件状态：

    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 步：安装缺失的 S3 CSI 驱动程序

  1. 为 S3 CSI 驱动程序创建 IAM 角色（如果尚未创建）：

    # 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"

  2. 安装 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

  3. 验证 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

第 2 步：安装缺失的 FSx CSI 驱动程序

  1. 为 FSx CSI 驱动程序创建 IAM 角色（如果尚未创建）：

    # 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"

  2. 安装 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

验证所有依赖关系

安装缺少的依赖项后，在重试推理运算符安装之前，请先验证它们是否正常运行：

# 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

模型部署期间缺少推理自定义资源定义

问题：尝试创建模型部署时缺少自定义资源定义 (CRDs)。如果您之前安装并删除了推理插件，但没有清理包含终结器的模型部署，则会出现此问题。

症状和诊断

根本原因：

如果您删除推理插件而不先移除所有模型部署，则带有终结器的自定义资源仍保留在集群中。必须先完成这些终结器才能删除。 CRDs插件删除过程不会等待 CRD 删除完成，这会使它们保持终止状态并阻止新安装。 CRDs

诊断此问题

  1. 检查是否 CRDs 存在。

    kubectl get crd | grep inference.sagemaker.aws.amazon.com

  2. 检查是否有卡住的自定义资源。

    # Check for JumpStartModel resources
kubectl get jumpstartmodels -A

# Check for InferenceEndpointConfig resources
kubectl get inferenceendpointconfigs -A

  3. 检查资源卡住的终结器。

    # Example for a specific JumpStartModel
kubectl get jumpstartmodels <model-name> -n <namespace> -o jsonpath='{.metadata.finalizers}'

# Example for a specific InferenceEndpointConfig
kubectl get inferenceendpointconfigs <config-name> -n <namespace> -o jsonpath='{.metadata.finalizers}'

解决方案

从所有模型部署中手动移除在移除推理插件时未删除的终结器。为每个卡住的自定义资源完成以下步骤。

从资源中移除终结器 JumpStartModel

  1. 列出所有命名空间中的所有 JumpStartModel 资源。

    kubectl get jumpstartmodels -A

  2. 对于每个 JumpStartModel 资源，通过修补资源来移除终结器，将 metadata.finalizers 设置为空数组。

    kubectl patch jumpstartmodels <model-name> -n <namespace> -p '{"metadata":{"finalizers":[]}}' --type=merge

    以下示例说明如何修补名为 kv-l1-only 的资源。

    kubectl patch jumpstartmodels kv-l1-only -n default -p '{"metadata":{"finalizers":[]}}' --type=merge

  3. 验证模型实例是否已删除。

    kubectl get jumpstartmodels -A

    清理完所有资源后，您应该会看到以下输出。

    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)

  4. 验证 JumpStartModel CRD 是否已被移除。

    kubectl get crd | grep jumpstartmodels.inference.sagemaker.aws.amazon.com

    如果成功删除 CRD，则此命令不返回任何输出。

从资源中移除终结器 InferenceEndpointConfig

  1. 列出所有命名空间中的所有 InferenceEndpointConfig 资源。

    kubectl get inferenceendpointconfigs -A

  2. 对于每种 InferenceEndpointConfig 资源，移除终结器。

    kubectl patch inferenceendpointconfigs <config-name> -n <namespace> -p '{"metadata":{"finalizers":[]}}' --type=merge

    以下示例说明如何修补名为的资源 my-inference-config。

    kubectl patch inferenceendpointconfigs my-inference-config -n default -p '{"metadata":{"finalizers":[]}}' --type=merge

  3. 确认配置实例已删除。

    kubectl get inferenceendpointconfigs -A

    清理完所有资源后，您应该会看到以下输出。

    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)

  4. 验证 InferenceEndpointConfig CRD 是否已被移除。

    kubectl get crd | grep inferenceendpointconfigs.inference.sagemaker.aws.amazon.com

    如果成功删除 CRD，则此命令不返回任何输出。

重新安装推理插件

清理所有卡住的资源并确认 CRDs 它们已被移除后，重新安装推理插件。有关更多信息，请参阅 使用 EKS 附加组件安装推理运算符。

验证

  1. 确认推理插件已成功安装。

    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

    状态应为 “活跃”，“健康” 应为 “健康”。

  2. 验证 CRDs 是否已正确安装。

    kubectl get crd | grep inference.sagemaker.aws.amazon.com

    您应该会在输出中看到与推理相关的 CRDs 内容。

  3. 测试创建新模型部署以确认问题已得到解决。

    # Create a test deployment using your preferred method
kubectl apply -f <your-model-deployment.yaml>

预防措施

为防止出现此问题，请在卸载推理插件之前完成以下步骤。

  1. 删除所有模型部署。

    # 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

  2. 确认所有自定义资源都已删除。

  3. 确认所有资源都已清理完毕后，删除推理插件。

由于缺少证书管理器，推理插件安装失败

问题：由于未安装证书管理器 EKS 附加组件，推理运算符插件创建失败，从而导致缺少自定义资源定义 ()。CRDs

症状和诊断

错误消息：

插件创建日志或推理操作员日志中出现以下错误：

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.

诊断步骤：

  1. 检查证书管理器是否已安装：

    # 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"

  2. 检查推理运算符插件状态：

    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：安装证书管理器插件

  1. 安装证书管理器 EKS 附加组件：

    aws eks create-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name cert-manager \
    --addon-version v1.18.2-eksbuild.2 \
    --region $REGION

  2. 验证证书管理器的安装：

    # 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

步骤 2：重试推理运算符安装

  1. 安装证书管理器后，请重试推理运算符的安装：

    # 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

  2. 监视安装：

    # 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

由于缺少 ALB 控制器，推理插件安装失败

问题：推理运算符插件创建失败，因为未安装 Loa AWS d Balancer Controller 或者没有为推理插件正确配置。

症状和诊断

错误消息：

插件创建日志或推理操作员日志中出现以下错误：

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.

诊断步骤：

  1. 检查是否安装了 ALB 控制器：

    # 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"

  2. 检查推理运算符插件配置：

    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

解决方案

根据您的设置选择以下选项之一：

选项 1：让推理插件安装 ALB 控制器（推荐）

  • 确保在您的插件配置中创建并正确配置 ALB 角色：

    # 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

选项 2：使用现有的 ALB 控制器安装

  • 如果您已经安装了 ALB Controller，请将插件配置为使用现有安装：

    # 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

步骤 3：重试推理运算符安装

  1. 使用更新后的配置重新安装推理运算符插件：

    # 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

  2. 验证 ALB 控制器是否正常工作：

    # 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

由于缺少 KEDA 操作员，推理插件安装失败

问题：推理运算符插件创建失败，原因是推理插件未安装 KEDA（Kubernetes 事件驱动的自动扩缩器）运算符或配置不正确。

症状和诊断

错误消息：

插件创建日志或推理操作员日志中出现以下错误：

KEDA operator not installed (missing keda-operator pods). 
KEDA can be installed separately in any namespace or via the Inference addon.

诊断步骤：

  1. 检查是否安装了 KEDA 操作员：

    # 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"

  2. 检查推理运算符插件配置：

    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

解决方案

根据您的设置选择以下选项之一：

选项 1：让推理插件安装 KEDA（推荐）

  • 确保在插件配置中创建并正确配置 KEDA 角色：

    # 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

选项 2：使用现有的 KEDA 安装

  • 如果您已经安装了 KEDA，请将插件配置为使用现有安装：

    # 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

步骤 3：重试推理运算符安装

  1. 使用更新后的配置重新安装推理运算符插件：

    # 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

  2. 验证 KEDA 是否正常工作：

    # 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

证书下载超时

部署 A SageMaker I 终端节点时，由于无法在 VPC 环境中下载证书颁发机构 (CA) 证书，创建过程失败。有关详细的配置步骤，请参阅《管理员指南》。

错误消息：

SageMaker AI 终端节点 CloudWatch 日志中出现以下错误：

Error downloading CA certificate: Connect timeout on endpoint URL: "https://****.s3.<REGION>.amazonaws.com/****/***.pem"

根本原因：

  • 当推理操作员无法访问您的 VPC 中的 Amazon S3 中的自签名证书时，就会出现此问题

  • 正确配置 Amazon S3 VPC 终端节点对于访问证书至关重要

解决方法：

  1. 如果您没有 Amazon S3 VPC 终端节点：

    • 按照管理员指南第 5.3 节中的配置创建 Amazon S3 VPC 终端节点。

  2. 如果您已经有一个 Amazon S3 VPC 终端节点：

    • 确保将子网路由表配置为指向 VPC 终端节点（如果使用网关终端节点），或者已为接口终端节点启用私有 DNS。

    • Amazon S3 VPC 终端节点应与第 5.3 节终端节点创建步骤中提到的配置类似

模型部署停留在待处理状态

部署模型时，部署将在很长一段时间内保持 “待定” 状态。这表明推理运算符无法在您的 HyperPod 集群中启动模型部署。

受影响的组件：

在正常部署期间，推理运算符应：

  • 部署模型 pod

  • 创建负载均衡器

  • 创建 SageMaker AI 端点

故障排除步骤：

  1. 检查推理运算符 pod 状态：

    kubectl get pods -n hyperpod-inference-system

    预期输出示例：

    NAME                                                           READY   STATUS    RESTARTS   AGE
hyperpod-inference-operator-controller-manager-65c49967f5-894fg   1/1     Running   0         6d13h

  2. 查看推理运算符日志并检查操作员日志中是否有错误消息：

    kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system

要找什么：

  • 操作员日志中的错误消息

  • 操作员窗格的状态

  • 任何与部署相关的警告或故障

注意

健康的部署应在合理的时间内超过 “待处理” 状态。如果问题仍然存在，请查看推理运算符日志以了解特定的错误消息以确定根本原因。

模型部署失败状态疑难解答

当模型部署进入 “失败” 状态时，以下三个组件之一可能会出现故障：

  • 模型 pod 部署

  • 创建负载均衡器

  • SageMaker 创建 AI 端点

故障排除步骤：

  1. 检查推理运算符状态：

    kubectl get pods -n hyperpod-inference-system

    预期输出：

    NAME                                                           READY   STATUS    RESTARTS   AGE
hyperpod-inference-operator-controller-manager-65c49967f5-894fg   1/1     Running   0         6d13h

  2. 查看操作员日志：

    kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system

要找什么：

操作员日志将显示哪个组件出现故障：

  • 模型 pod 部署失败

  • 负载均衡器创建问题

  • SageMaker AI 端点错误

检查模型部署进度

要监控模型部署进度并识别潜在问题，您可以使用 kubectl 命令检查各种组件的状态。这有助于确定部署是正常进行，还是在模型容器创建、负载均衡器设置或 SageMaker AI 端点配置阶段遇到问题。

方法 1：检查 JumpStart 模型状态

kubectl describe jumpstartmodel.inference.sagemaker.aws.amazon.com/<model-name> -n <namespace>

要监控的关键状态指标：

  1. 部署状态

    • 寻找Status.State：应该显示 DeploymentComplete

    • 查看 Status.Deployment Status.Available Replicas

    • 监控Status.Conditions部署进度

  2. SageMaker AI 端点状态

    • 勾选Status.Endpoints.Sagemaker.State：应该显示 CreationCompleted

    • 验证 Status.Endpoints.Sagemaker.Endpoint Arn

  3. TLS 证书状态

    • 查看Status.Tls Certificate详情

    • 在中查看证书到期时间 Last Cert Expiry Time

方法 2：检查推理端点配置

kubectl describe inferenceendpointconfig.inference.sagemaker.aws.amazon.com/<deployment_name> -n <namespace>

常见状态状态：

  • DeploymentInProgress: 初始部署阶段

  • DeploymentComplete: 成功部署

  • Failed: 部署失败

注意

监视 “事件” 部分是否存在任何警告或错误。检查副本数量是否与预期配置相符。验证显示的所有条件Status: True以实现正常部署。

VPC 弹性网卡权限问题

SageMaker 由于在 VPC 中创建网络接口的权限不足，AI 终端节点创建失败。

错误消息：

Please ensure that the execution role for variant AllTraffic has sufficient permissions for creating an endpoint variant within a VPC

根本原因：

推理操作员的执行角色缺少在 VPC 中创建网络接口 (ENI) 所需的 Amazon EC2 权限。

解决方法：

向推理运算符的执行角色添加以下 IAM 权限：

{
    "Effect": "Allow",
    "Action": [
        "ec2:CreateNetworkInterfacePermission",
        "ec2:DeleteNetworkInterfacePermission"
     ],
    "Resource": "*"
}

验证：

添加权限后：

  1. 删除失败的端点（如果存在）

  2. 重试创建终端节点

  3. 监控部署状态以成功完成

注意

此权限对于在 VPC 模式下运行的 SageMaker AI 终端节点至关重要。确保执行角色还具有所有其他必要的 VPC 相关权限。

IAM 信任关系问题

HyperPod 推理运算符启动失败， AssumeRoleWithWebIdentity出现 STS 错误，这表明 IAM 信任关系配置存在问题。

错误消息：

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

解决方法：

使用以下配置更新推理运算符的 IAM 执行角色的信任关系。

替换以下占位符：

  • <ACCOUNT_ID>: 您的 AWS 账户 ID

  • <REGION>: 你所在 AWS 的地区

  • <OIDC_ID>: 您的 Amazon EKS 集群的 OIDC 提供商 ID

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
            "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.us-east-2.amazonaws.com/id/<OIDC_ID>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "oidc.eks.us-east-2.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:<namespace>:<service-account-name>",
                    "oidc.eks.us-east-2.amazonaws.com/id/<OIDC_ID>:aud": "sts.amazonaws.com"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "sagemaker.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

验证：

更新信任关系后：

  1. 在 IAM 控制台中验证角色配置

  2. 如有必要，请重新启动推理运算符

  3. 监控操作员日志以成功启动

缺少英伟达 GPU 插件错误

尽管有可用的 GPU 节点，但模型部署失败并出现 GPU 不足错误。当 HyperPod集群中未安装 NVIDIA 设备插件时，就会发生这种情况。

错误消息：

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.

根本原因：

  • 如果没有 NVIDIA 设备插件，Kubernetes 就无法检测 GPU 资源

  • 导致 GPU 工作负载调度失败

解决方法：

通过运行以下命令安装 NVIDIA GPU 插件：

kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/refs/tags/v0.17.1/deployments/static/nvidia-device-plugin.yml

验证步骤：

  1. 检查插件部署状态：

    kubectl get pods -n kube-system | grep nvidia-device-plugin

  2. 验证 GPU 资源现在是否可见：

    kubectl get nodes -o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\\.com/gpu

  3. 重试模型部署

注意

确保在 GPU 节点上安装了 NVIDIA 驱动程序。插件安装是每个集群的一次性设置。可能需要集群管理员权限才能安装。

推理运算符无法启动

推理运算符 pod 无法启动，导致出现以下错误消息。此错误是由于未授权操作员执行角色的权限策略所致sts:AssumeRoleWithWebIdentity。因此，在控制平面上运行的操作员部分无法启动。

错误消息：

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)

根本原因：

  • 推理运算符执行角色的权限策略未设置为访问资源的授权令牌。

解决方法：

为 HyperPod 推理运算符设置以下执行EXECUTION_ROLE_ARN角色策略：

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": "*"
        }
    ]
}

验证步骤：

  1. 更改策略。

  2. 终止 HyperPod 推理运算符 pod。

  3. Pod 将在不引发任何异常的情况下重新启动。