先决条件设置和配置从 Amazon S3、亚马逊 FSx 或 Hugging Face Hub 部署模型确认部署状态管理您的部署

使用 kubectl 部署来自亚马逊 S3、亚马逊 FSx 或 Hugging Face Hub 的模型

以下步骤向您展示了如何使用 kubectl 将存储在 Amazon S3、Amazon FSx 或 Hugging Face Hub 上的模型部署到 SageMaker HyperPod 亚马逊集群。

以下说明包含代码单元以及设计为在终端运行的命令。在执行这些命令之前，请确保您已使用 AWS 凭据配置您的环境。

先决条件

在开始之前，请确认您已经：

在您的 Amazon SageMaker HyperPod 集群上设置推理功能。有关更多信息，请参阅设置 HyperPod 集群以进行模型部署。
已在您的终端中安装了 kubectl 实用程序。

设置和配置

将所有占位符值替换为实际的资源标识符。

在环境中选择您的区域。
```
export REGION=<region>
```
初始化集群名称。这标识了您的模型将在哪个 HyperPod 集群中部署。

注意
请与您的集群管理员核实，确保已为该角色或用户授予权限。您可以运行 !aws sts get-caller-identity --query "Arn" 来检查您在终端使用的角色或用户。
```
# Specify your hyperpod cluster name here
HYPERPOD_CLUSTER_NAME="<Hyperpod_cluster_name>"

# NOTE: For sample deployment, we use g5.24xlarge for Llama 3.1 8B model which has sufficient memory and GPU
instance_type="ml.g5.24xlarge"
```
初始化集群命名空间。您的集群管理员应已在命名空间中创建一个 hyperpod-inference 服务账户。
```
cluster_namespace="<namespace>"
```

使用下列选项之一创建 CRD：

Using Amazon FSx as the model source

设置 SageMaker 终端节点名称。


export SAGEMAKER_ENDPOINT_NAME="llama-fsx"

配置要使用的 Amazon FSx 文件系统 ID。
```
export FSX_FILE_SYSTEM_ID="fs-1234abcd"
```

以下是使用 Amazon FSx 和 Llama 模型创建终端节点的 yaml 文件示例。

注意

对于启用了 GPU 分区的集群，请nvidia.com/gpu替换为相应的 MIG 资源名称，例如。nvidia.com/mig-1g.10gb有关更多信息，请参阅使用 MIG 提交任务。

cat <<EOF> deploy_fsx_cluster_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
spec:
  modelName: Llama-3.1-8B-Instruct
  instanceType: ml.g5.24xlarge
  invocationEndpoint: v1/chat/completions
  replicas: 2
  modelSourceConfig:
    fsxStorage:
      fileSystemId: $FSX_FILE_SYSTEM_ID
    modelLocation: Llama-3.1-8B-Instruct
    modelSourceType: fsx
  worker:
    image: vllm/vllm-openai:v0.19.1
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      mountPath: /opt/ml/model
      name: model-weights
    resources:
      limits:
        nvidia.com/gpu: 4
      requests:
        cpu: 30000m
        memory: 100Gi
        nvidia.com/gpu: 4
    args:
      - "--model"
      - "/opt/ml/model"
      - "--port"
      - "8000"
      - "--tensor-parallel-size"
      - "4"
      - "--served-model-name"
      - "Llama-3.1-8B-Instruct"
    environmentVariables:
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

Using Amazon S3 as the model source

设置 SageMaker 终端节点名称。


export SAGEMAKER_ENDPOINT_NAME="llama-s3"

配置模型所在的 Amazon S3 存储桶位置。
```
export S3_MODEL_LOCATION="<your-s3-bucket-name>"
```

以下是使用 Amazon S3 创建终端节点的 yaml 文件示例，以及使用 vLLM 作为推理运行时的 Llama 模型创建终端节点。

注意

对于启用了 GPU 分区的集群，请nvidia.com/gpu替换为相应的 MIG 资源名称，例如。nvidia.com/mig-1g.10gb有关更多信息，请参阅使用 MIG 提交任务。

cat <<EOF> deploy_s3_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
spec:
  modelName: Llama-3.1-8B-Instruct
  instanceType: ml.g5.24xlarge
  invocationEndpoint: v1/chat/completions
  replicas: 2
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: $S3_MODEL_LOCATION
      region: $REGION
    modelLocation: Llama-3.1-8B-Instruct
    prefetchEnabled: true
  worker:
    image: vllm/vllm-openai:v0.19.1
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: 4
      requests:
        cpu: 30000m
        memory: 100Gi
        nvidia.com/gpu: 4
    args:
      - "--model"
      - "/opt/ml/model"
      - "--port"
      - "8000"
      - "--tensor-parallel-size"
      - "4"
      - "--served-model-name"
      - "Llama-3.1-8B-Instruct"
    environmentVariables:
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

Using Hugging Face Hub as the model source

创建一个包含你的 Hugging Face API 令牌的 Kubernetes 密钥。门控模型需要此令牌，建议所有下载都使用此令牌。你可以在 huggingface 上生成一个代币。 co/settings/代币。

重要
从 Hugging Face Hub 部署模型需要从集群节点出站互联网访问到 Hugging Face 域，包括和。*.huggingface.co *.hf.co确保您的 VPC 网络配置（NAT 网关、安全组和网络 ACL）允许 HTTPS 输出到这些域。如果没有互联网接入，模型下载将失败。

注意
对于生产环境，我们建议使用亚马逊 S3 或亚马逊 FSx 作为模型来源，而不是 Hugging Face Hub。借助 Amazon S3 和 Amazon FSx，模型工件存储在您的 AWS 账户中，从而消除了对外部互联网连接的依赖，并提供了更可预测的部署时间。Hugging Face Hub 最适合开发、实验和快速原型制作，在这些环境中，可以方便地直接访问 Hugging Face 模型存储库。
```
kubectl create secret generic hf-token-secret \
  --from-literal=token=hf_YOUR_TOKEN_HERE \
  -n $CLUSTER_NAMESPACE
```

设置 SageMaker 终端节点名称。


export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

以下是使用 vLLM 作为推理运行时从 Hugging Face Hub 部署 Mistral 7B 模型的示例 YAML 文件。使用prefetchEnabled: true，操作员使用初始化容器在推理容器启动之前下载模型。

注意

对于启用了 GPU 分区的集群，请nvidia.com/gpu替换为相应的 MIG 资源名称，例如。nvidia.com/mig-1g.10gb有关更多信息，请参阅使用 MIG 提交任务。

cat <<EOF> deploy_hf_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
spec:
  modelName: mistral-7b
  modelSourceConfig:
    modelSourceType: huggingface
    prefetchEnabled: true
    huggingFaceModel:
      modelId: "mistralai/Mistral-7B-Instruct-v0.3"
      tokenSecretRef:
        name: hf-token-secret
        key: token
  instanceType: "ml.g5.24xlarge"
  invocationEndpoint: v1/chat/completions
  worker:
    image: "vllm/vllm-openai:v0.19.1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      requests:
        nvidia.com/gpu: "4"
        memory: "96Gi"
        cpu: "16"
      limits:
        nvidia.com/gpu: "4"
        memory: "96Gi"
        cpu: "16"
    args:
      - "--model"
      - "/opt/ml/model"
      - "--port"
      - "8000"
      - "--tensor-parallel-size"
      - "4"
      - "--served-model-name"
      - "mistralai/Mistral-7B-Instruct-v0.3"
    environmentVariables:
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

Hugging Face 的关键配置字段是：
- modelSourceType（必填）-设置为huggingface。
- huggingFaceModel.modelId（必填）— Hugging Face Hub 模型标识符org/model的格式（例如mistralai/Mistral-7B-Instruct-v0.3）。
- huggingFaceModel.commitSHA（可选）— 一个 40 个字符的 Git 提交 SHA，用于固定特定的模型版本。如果省略，则默认为分main支。
- huggingFaceModel.tokenSecretRef（可选）— 引用包含你的 Hugging Face API 令牌的 Kubernetes 密钥。门控模型是必需的。该令牌仅在模型下载期间使用，不会暴露在推理容器中。
- prefetchEnabled（可选）— 何时true，初始化容器在推理容器启动之前下载模型。何时false，推理运行时（vlLM、TGI、sgLang）会在启动时以原生方式下载模型。默认值为 false。

注意

要配置 KV 缓存和智能路由以提高性能，请参阅配置 KV 缓存和智能路由。

从 Amazon S3、亚马逊 FSx 或 Hugging Face Hub 部署模型

从集群 ARN 中获取用于 kubectl 身份验证的 Amazon EKS HyperPod 集群名称。


export EKS_CLUSTER_NAME=$(aws --region $REGION sagemaker describe-cluster --cluster-name $HYPERPOD_CLUSTER_NAME \
  --query 'Orchestrator.Eks.ClusterArn' --output text | \
  cut -d'/' -f2)
aws eks update-kubeconfig --name $EKS_CLUSTER_NAME --region $REGION

使用以下选项之一部署 InferenceEndpointConfig 模型：
Deploy with Amazon FSx as a source
```
kubectl apply -f deploy_fsx_luster_inference.yaml
```
Deploy with Amazon S3 as a source
```
kubectl apply -f deploy_s3_inference.yaml
```
Deploy with Hugging Face Hub as a source
```
kubectl apply -f deploy_hf_inference.yaml
```
如果部署失败，请检查 InferenceEndpointConfig 事件以获取诊断信息。有关令牌错误、网络连接和未找到模型等常见问题，请参阅Hugging Face Hub 模型部署失败。

确认部署状态

检查是否已成功部署模型。


kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

检查是否已成功创建端点。


kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

测试已部署的端点以验证其是否正常工作。此步骤可确认模型已部署成功且能处理推理请求。


aws sagemaker-runtime invoke-endpoint \
  --endpoint-name $SAGEMAKER_ENDPOINT_NAME \
  --content-type "application/json" \
  --body '{"inputs": "What is AWS SageMaker?"}' \
  --region $REGION \
  --cli-binary-format raw-in-base64-out \
  /dev/stdout

管理您的部署

测试完部署后，使用以下命令清理资源。

注意

确认您不再需要已部署的模型或存储的数据，然后再继续操作。

清除资源

删除推理部署和关联的 Kubernetes 资源。这将停止正在运行的模型容器并移除 SageMaker端点。
```
kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```

确认已成功完成清理。


# # Check that Kubernetes resources are removed
kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE


# Verify SageMaker endpoint is deleted (should return error or empty)
aws sagemaker describe-endpoint --endpoint-name $SAGEMAKER_ENDPOINT_NAME --region $REGION

问题排查

如果部署无法按预期工作，请使用以下调试命令。

检查 Kubernetes 部署状态。


kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

检查 InferenceEndpointConfig 状态以查看高级部署状态和任何配置问题。
```
kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```
检查所有 Kubernetes 对象的状态。全面了解命名空间中所有相关的 Kubernetes 资源。这可让您快速了解当前正在运行的内容以及可能缺失的内容。
```
kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE
```

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

JumpStart 使用 kubectl 部署模型

使用 kubectl 从本地 NVMe 存储中部署模型

使用 kubectl 部署来自亚马逊 S3、亚马逊 FSx 或 Hugging Face Hub 的模型

先决条件

设置和配置

注意

注意

注意

重要

注意

注意

注意

从 Amazon S3、亚马逊 FSx 或 Hugging Face Hub 部署模型

确认部署状态

管理您的部署

注意

清除资源

问题排查