本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 kubectl 從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署模型 下列步驟說明如何使用 kubectl，將存放在 Amazon S3、Amazon FSx 或 Hugging Face Hub 上的模型部署至 Amazon SageMaker HyperPod 叢集。 下列指示包含設計在終端機中執行的程式碼儲存格和命令。執行這些命令之前，請確定您已使用 AWS 登入資料設定環境。 ## 先決條件 開始之前，請確認您已： + 在 Amazon SageMaker HyperPod 叢集上設定推論功能。如需詳細資訊，請參閱[設定 HyperPod 叢集以進行模型部署](sagemaker-hyperpod-model-deployment-setup.md)。 + 在終端機中安裝 [kubectl](https://kubernetes.io/docs/reference/kubectl/) 公用程式並設定 [jq](https://jqlang.org/)。 ## 設定與組態 將所有預留位置值取代為您的實際資源識別碼。 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.8xlarge for deepseek-r1 1.5b model which has sufficient memory and GPU instance_type="ml.g5.8xlarge" ``` 1. 初始化您的叢集命名空間。您的叢集管理員應該已在命名空間中建立 Hyperpod-inference 服務帳戶。 ``` cluster_namespace="" ``` 1. 請使用下列其中一個選項建立 CRD： ------ #### [ Using Amazon FSx as the model source ] 1. 設定 SageMaker 端點名稱。 ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx" ``` 1. 設定要使用的 Amazon FSx 檔案系統 ID。 ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. 下列是使用 Amazon FSx 和 DeepSeek 模型建立端點的範例 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: lmcache-test namespace: inf-update 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: deepseek-1-5b modelSourceType: fsx worker: environmentVariables: - name: HF_MODEL_ID value: /opt/ml/model - name: SAGEMAKER_PROGRAM value: inference.py - name: SAGEMAKER_SUBMIT_DIRECTORY value: /opt/ml/model/code - name: MODEL_CACHE_ROOT value: /opt/ml/model - name: SAGEMAKER_ENV value: '1' image: 763104351884.dkr.ecr.us-east-2.amazonaws.com/huggingface-pytorch-tgi-inference:2.4.0-tgi2.3.1-gpu-py311-cu124-ubuntu22.04-v2.0 modelInvocationPort: containerPort: 8080 name: http modelVolumeMount: mountPath: /opt/ml/model name: model-weights resources: limits: nvidia.com/gpu: 1 # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1 requests: cpu: 30000m memory: 100Gi nvidia.com/gpu: 1 # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1 EOF ``` ------ #### [ Using Amazon S3 as the model source ] 1. 設定 SageMaker 端點名稱。 ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. 設定模型所在的 Amazon S3 儲存貯體位置。 ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. 下列是使用 Amazon S3 和 DeepSeek 模型建立端點的範例 yaml 檔案。 **注意** 對於已啟用 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/v1alpha1 kind: InferenceEndpointConfig metadata: name: $SAGEMAKER_ENDPOINT_NAME namespace: $CLUSTER_NAMESPACE spec: modelName: deepseek15b endpointName: $SAGEMAKER_ENDPOINT_NAME instanceType: ml.g5.8xlarge invocationEndpoint: invocations modelSourceConfig: modelSourceType: s3 s3Storage: bucketName: $S3_MODEL_LOCATION region: $REGION modelLocation: deepseek15b prefetchEnabled: true worker: resources: limits: nvidia.com/gpu: 1 # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1 requests: nvidia.com/gpu: 1 # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1 cpu: 25600m memory: 102Gi image: 763104351884.dkr.ecr.us-east-2.amazonaws.com/djl-inference:0.32.0-lmi14.0.0-cu124 modelInvocationPort: containerPort: 8000 name: http modelVolumeMount: name: model-weights mountPath: /opt/ml/model environmentVariables: - name: PYTHONHASHSEED value: "123" - name: OPTION_ROLLING_BATCH value: "vllm" - name: SERVING_CHUNKED_READ_TIMEOUT value: "480" - name: DJL_OFFLINE value: "true" - name: NUM_SHARD value: "1" - name: SAGEMAKER_PROGRAM value: "inference.py" - name: SAGEMAKER_SUBMIT_DIRECTORY value: "/opt/ml/model/code" - name: MODEL_CACHE_ROOT value: "/opt/ml/model" - name: SAGEMAKER_MODEL_SERVER_WORKERS value: "1" - name: SAGEMAKER_MODEL_SERVER_TIMEOUT value: "3600" - name: OPTION_TRUST_REMOTE_CODE value: "true" - name: OPTION_ENABLE_REASONING value: "true" - name: OPTION_REASONING_PARSER value: "deepseek_r1" - name: SAGEMAKER_CONTAINER_LOG_LEVEL value: "20" - name: SAGEMAKER_ENV value: "1" - name: MODEL_SERVER_TYPE value: "vllm" - name: SESSION_KEY value: "x-user-id" EOF ``` ------ #### [ Using Amazon S3 as the model source ] 1. 設定 SageMaker 端點名稱。 ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. 設定模型所在的 Amazon S3 儲存貯體位置。 ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. 下列是使用 Amazon S3 和 DeepSeek 模型建立端點的範例 yaml 檔案。 ``` cat < deploy_s3_inference.yaml --- apiVersion: inference.sagemaker.aws.amazon.com/v1 kind: InferenceEndpointConfig metadata: name: lmcache-test namespace: inf-update spec: modelName: Llama-3.1-8B-Instruct instanceType: ml.g5.24xlarge invocationEndpoint: v1/chat/completions replicas: 2 modelSourceConfig: modelSourceType: s3 s3Storage: bucketName: bugbash-ada-resources region: us-west-2 modelLocation: models/Llama-3.1-8B-Instruct prefetchEnabled: false kvCacheSpec: enableL1Cache: true # enableL2Cache: true # l2CacheSpec: # l2CacheBackend: redis/sagemaker # l2CacheLocalUrl: redis://redis.redis-system.svc.cluster.local:6379 intelligentRoutingSpec: enabled: true tlsConfig: tlsCertificateOutputS3Uri: s3://sagemaker-lmcache-fceb9062-tls-6f6ee470 metrics: enabled: true modelMetrics: port: 8000 loadBalancer: healthCheckPath: /health worker: resources: limits: nvidia.com/gpu: "4" requests: cpu: "6" memory: 30Gi nvidia.com/gpu: "4" image: lmcache/vllm-openai:latest args: - "/opt/ml/model" - "--max-model-len" - "20000" - "--tensor-parallel-size" - "4" modelInvocationPort: containerPort: 8000 name: http modelVolumeMount: name: model-weights mountPath: /opt/ml/model environmentVariables: - name: PYTHONHASHSEED value: "123" - name: OPTION_ROLLING_BATCH value: "vllm" - name: SERVING_CHUNKED_READ_TIMEOUT value: "480" - name: DJL_OFFLINE value: "true" - name: NUM_SHARD value: "1" - name: SAGEMAKER_PROGRAM value: "inference.py" - name: SAGEMAKER_SUBMIT_DIRECTORY value: "/opt/ml/model/code" - name: MODEL_CACHE_ROOT value: "/opt/ml/model" - name: SAGEMAKER_MODEL_SERVER_WORKERS value: "1" - name: SAGEMAKER_MODEL_SERVER_TIMEOUT value: "3600" - name: OPTION_TRUST_REMOTE_CODE value: "true" - name: OPTION_ENABLE_REASONING value: "true" - name: OPTION_REASONING_PARSER value: "deepseek_r1" - name: SAGEMAKER_CONTAINER_LOG_LEVEL value: "20" - name: SAGEMAKER_ENV value: "1" - name: MODEL_SERVER_TYPE value: "vllm" - name: SESSION_KEY value: "x-user-id" EOF ``` ------ #### [ Using Hugging Face Hub as the model source ] 1. 建立包含 Hugging Face API 權杖的 Kubernetes 秘密。門控模型需要此字符，並建議所有下載使用。您可以在 https：//[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) 產生字符。 **重要** 從 Hugging Face Hub 部署模型需要從叢集節點到 Hugging Face 網域的傳出網際網路存取，包括 `*.huggingface.co`和 `*.hf.co`。確保您的 VPC 聯網組態 (NAT 閘道、安全群組和網路 ACLs) 允許 HTTPS 輸出到這些網域。如果沒有網際網路存取，模型下載將會失敗。 **注意** 對於生產環境，建議使用 Amazon S3 或 Amazon 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.10.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 快取和智慧型路由以提升效能 1. 透過將 `enableL1Cache`和 設定為 `enableL2Cache`來啟用 KV 快取`true`。然後，將 `l2CacheSpec` 設定為 `redis`並使用 `l2CacheLocalUrl` Redis 叢集 URL 更新。 ``` kvCacheSpec: enableL1Cache: true enableL2Cache: true l2CacheSpec: l2CacheBackend: l2CacheLocalUrl: ``` **注意** 如果 redis 叢集不在與 HyperPod 叢集相同的 Amazon VPC 內，則不保證傳輸中資料的加密。 **注意** 如果選取分層儲存，則不需要 l2CacheLocalUrl。 1. 透過將 `enabled`設定為 `true`下的 來啟用智慧型路由`intelligentRoutingSpec`。您可以在 下指定要使用的路由策略`routingStrategy`。如果未指定路由策略，則預設為 `prefixaware`。 ``` intelligentRoutingSpec: enabled: true routingStrategy: ``` 1. 在 `true`下將 `enabled`設定為 ，以啟用路由器指標和快取指標`metrics`。該`port`值必須與 下`containerPort`的值相同`modelInvocationPort`。 ``` metrics: enabled: true modelMetrics: port: ... modelInvocationPort: containerPort: ``` ## 從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署您的模型 1. 從 HyperPod 叢集 ARN 取得 Amazon EKS 叢集名稱，以進行 kubectl 驗證。 ``` 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 ```