本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 kubectl 部署来自亚马逊 S3、亚马逊 FSx 或 Hugging Face Hub 的模型 以下步骤向您展示了如何使用 kubectl 将存储在 Amazon S3、Amazon FSx 或 Hugging Face Hub 上的模型部署到 SageMaker HyperPod 亚马逊集群。 以下说明包含代码单元以及设计为在终端运行的命令。在执行这些命令之前，请确保您已使用 AWS 凭据配置您的环境。 ## 先决条件 在开始之前，请确认您已经： + 在您的 Amazon SageMaker HyperPod 集群上设置推理功能。有关更多信息，请参阅 [设置 HyperPod 集群以进行模型部署](sagemaker-hyperpod-model-deployment-setup.md)。 + 已在您的终端中安装了 [kubectl](https://kubernetes.io/docs/reference/kubectl/) 实用程序。 ## 设置和配置 将所有占位符值替换为实际的资源标识符。 1. 在环境中选择您的区域。 ``` export REGION= ``` 1. 初始化集群名称。这标识了您的模型将在哪个 HyperPod 集群中部署。 **注意** 请与您的集群管理员核实，确保已为该角色或用户授予权限。您可以运行 `!aws sts get-caller-identity --query "Arn"` 来检查您在终端使用的角色或用户。 ``` # Specify your hyperpod cluster name here 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" ``` 1. 初始化集群命名空间。您的集群管理员应已在命名空间中创建一个 hyperpod-inference 服务账户。 ``` cluster_namespace="" ``` 1. 使用下列选项之一创建 CRD： ------ #### [ Using Amazon FSx as the model source ] 1. 设置 SageMaker 终端节点名称。 ``` export SAGEMAKER_ENDPOINT_NAME="llama-fsx" ``` 1. 配置要使用的 Amazon FSx 文件系统 ID。 ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. 以下是使用 Amazon FSx 和 Llama 模型创建终端节点的 yaml 文件示例。 **注意** 对于启用了 GPU 分区的集群，请`nvidia.com/gpu`替换为相应的 MIG 资源名称，例如。`nvidia.com/mig-1g.10gb`有关更多信息，请参阅 [使用 MIG 提交任务](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)。 ``` cat < 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 ] 1. 设置 SageMaker 终端节点名称。 ``` export SAGEMAKER_ENDPOINT_NAME="llama-s3" ``` 1. 配置模型所在的 Amazon S3 存储桶位置。 ``` export S3_MODEL_LOCATION="" ``` 1. 以下是使用 Amazon S3 创建终端节点的 yaml 文件示例，以及使用 vLLM 作为推理运行时的 Llama 模型创建终端节点。 **注意** 对于启用了 GPU 分区的集群，请`nvidia.com/gpu`替换为相应的 MIG 资源名称，例如。`nvidia.com/mig-1g.10gb`有关更多信息，请参阅 [使用 MIG 提交任务](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)。 ``` cat < 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 ] 1. 创建一个包含你的 Hugging Face API 令牌的 Kubernetes 密钥。门控模型需要此令牌，建议所有下载都使用此令牌。你可以在 [huggingface 上生成一个代币。 co/settings/代币](https://huggingface.co/settings/tokens)。 **重要** 从 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 ``` 1. 设置 SageMaker 终端节点名称。 ``` export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf" ``` 1. 以下是使用 vLLM 作为推理运行时从 Hugging Face Hub 部署 Mistral 7B 模型的示例 YAML 文件。使用`prefetchEnabled: true`，操作员使用初始化容器在推理容器启动之前下载模型。 **注意** 对于启用了 GPU 分区的集群，请`nvidia.com/gpu`替换为相应的 MIG 资源名称，例如。`nvidia.com/mig-1g.10gb`有关更多信息，请参阅 [使用 MIG 提交任务](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)。 ``` cat < 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 ``` 1. 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 缓存和智能路由](sagemaker-hyperpod-model-deployment-caching-routing.md#sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route)。 ## 从 Amazon S3、亚马逊 FSx 或 Hugging Face Hub 部署模型 1. 从集群 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 ``` 1. 使用以下选项之一部署 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 模型部署失败](sagemaker-hyperpod-model-deployment-ts-huggingface.md)。 ------ ## 确认部署状态 1. 检查是否已成功部署模型。 ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 检查是否已成功创建端点。 ``` kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 测试已部署的端点以验证其是否正常工作。此步骤可确认模型已部署成功且能处理推理请求。 ``` 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 ``` ## 管理您的部署 测试完部署后，使用以下命令清理资源。 **注意** 确认您不再需要已部署的模型或存储的数据，然后再继续操作。 **清除资源** 1. 删除推理部署和关联的 Kubernetes 资源。这将停止正在运行的模型容器并移除 SageMaker端点。 ``` kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 确认已成功完成清理。 ``` # # 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 ``` **问题排查** 如果部署无法按预期工作，请使用以下调试命令。 1. 检查 Kubernetes 部署状态。 ``` kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 检查 InferenceEndpointConfig 状态以查看高级部署状态和任何配置问题。 ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 检查所有 Kubernetes 对象的状态。全面了解命名空间中所有相关的 Kubernetes 资源。这可让您快速了解当前正在运行的内容以及可能缺失的内容。 ``` kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE ```