HyperPod 推理疑难解答 - 亚马逊 SageMaker AI
证书下载超时模型部署停留在待处理状态模型部署失败状态疑难解答检查模型部署进度VPC 弹性网卡权限问题IAM 信任关系问题缺少英伟达 GPU 插件错误推理运算符无法启动
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

HyperPod 推理疑难解答

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

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

证书下载超时

部署 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>: 您的Amazon账户 ID

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

  • <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 将在不引发任何异常的情况下重新启动。