本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 kubectl 從 JumpStart 部署模型
<a name="sagemaker-hyperpod-model-deployment-deploy-js-kubectl"></a>

下列步驟向您展示如何使用 kubectl 將 JumpStart 模型部署至 HyperPod 叢集。

下列指示包含設計在終端機中執行的程式碼儲存格和命令。執行這些命令之前，請確定您已使用 AWS 登入資料設定環境。

## 先決條件
<a name="kubectl-prerequisites"></a>

開始之前，請確認您已：
+ 在 Amazon SageMaker HyperPod 叢集上設定推論功能。如需詳細資訊，請參閱[設定 HyperPod 叢集以進行模型部署](sagemaker-hyperpod-model-deployment-setup.md)。
+ 在終端機中安裝 [kubectl](https://kubernetes.io/docs/reference/kubectl/) 公用程式並設定 [jq](https://jqlang.org/)。

## 設定與組態
<a name="kubectl-prerequisites-setup-and-configuration"></a>

1. 選擇您的區域。

   ```
   export REGION=<region>
   ```

1. 檢視所有 SageMaker 公有中樞模型和 HyperPod 叢集。

1. 從 JumpstartPublic 中樞選取 `JumpstartModel`。JumpstartPublic 中樞有大量可用的模型，因此您可以使用 `NextToken` 迭代列出公有中樞中的所有可用模型。

   ```
   aws sagemaker list-hub-contents --hub-name SageMakerPublicHub --hub-content-type Model --query '{Models: HubContentSummaries[].{ModelId:HubContentName,Version:HubContentVersion}, NextToken: NextToken}' --output json
   ```

   ```
   export MODEL_ID="deepseek-llm-r1-distill-qwen-1-5b"
   export MODEL_VERSION="2.0.4"
   ```

1. 設定您在下列變數中選取的模型 ID 和叢集名稱。
**注意**  
請洽詢您的叢集管理員，確保已為此角色或使用者授與許可。您可以執行 `!aws sts get-caller-identity --query "Arn"` 來檢查您在終端機中使用的角色或使用者。

   ```
   aws sagemaker list-clusters --output table
   
   # Select the cluster name where you want to deploy the model.
   export HYPERPOD_CLUSTER_NAME="<insert cluster name here>"
   
   # Select the instance that is relevant for your model deployment and exists within the selected cluster.
   # List availble instances in your HyperPod cluster
   aws sagemaker describe-cluster --cluster-name=$HYPERPOD_CLUSTER_NAME --query "InstanceGroups[].{InstanceType:InstanceType,Count:CurrentCount}" --output table
   
   # List supported instance types for the selected model
   aws sagemaker describe-hub-content --hub-name SageMakerPublicHub --hub-content-type Model --hub-content-name "$MODEL_ID" --output json | jq -r '.HubContentDocument | fromjson | {Default: .DefaultInferenceInstanceType, Supported: .SupportedInferenceInstanceTypes}'
   
   
   # Select and instance type from the cluster that is compatible with the model. 
   # Make sure that the selected instance is either default or supported instance type for the jumpstart model 
   export INSTANCE_TYPE="<Instance_type_In_cluster"
   ```

1. 與叢集管理員確認您被允許使用哪個命名空間。管理員應該已在您的命名空間中建立 `hyperpod-inference`。服務帳戶。

   ```
   export CLUSTER_NAMESPACE="default"
   ```

1. 為要建立的端點和自訂物件設定名稱。

   ```
   export SAGEMAKER_ENDPOINT_NAME="deepsek-qwen-1-5b-test"
   ```

1. 以下是來自 Jumpstart 的 `deepseek-llm-r1-distill-qwen-1-5b` 模型部署範例。根據上述步驟中選取的模型建立類似的部署 yaml 檔案。
**注意**  
如果您的叢集搭配 MIG 使用 GPU 分割，您可以將 `acceleratorPartitionType` 欄位新增至伺服器規格，以請求特定的 MIG 設定檔。如需詳細資訊，請參閱[使用 MIG 提交任務](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)。

   ```
   cat << EOF > jumpstart_model.yaml
   ---
   apiVersion: inference.sagemaker.aws.amazon.com/v1
   kind: JumpStartModel
   metadata:
     name: $SAGEMAKER_ENDPOINT_NAME
     namespace: $CLUSTER_NAMESPACE 
   spec:
     sageMakerEndpoint:
       name: $SAGEMAKER_ENDPOINT_NAME
     model:
       modelHubName: SageMakerPublicHub
       modelId: $MODEL_ID
       modelVersion: $MODEL_VERSION
     server:
       instanceType: $INSTANCE_TYPE
       # Optional: Specify GPU partition profile for MIG-enabled instances
       # acceleratorPartitionType: "1g.10gb"
     metrics:
       enabled: true
     environmentVariables:
       - name: SAMPLE_ENV_VAR
         value: "sample_value"
     maxDeployTimeInSeconds: 1800
     autoScalingSpec:
       cloudWatchTrigger:
         name: "SageMaker-Invocations"
         namespace: "AWS/SageMaker"
         useCachedMetrics: false
         metricName: "Invocations"
         targetValue: 10
         minValue: 0.0
         metricCollectionPeriod: 30
         metricStat: "Sum"
         metricType: "Average"
         dimensions:
           - name: "EndpointName"
             value: "$SAGEMAKER_ENDPOINT_NAME"
           - name: "VariantName"
             value: "AllTraffic"
   EOF
   ```

## 部署模型
<a name="kubectl-deploy-your-model"></a>

**更新您的 kubernetes 組態並部署您的模型**

1. 設定 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. 部署您的 JumpStart 模型。

   ```
   kubectl apply -f jumpstart_model.yaml
   ```

**監控模型部署的狀態**

1. 驗證是否已成功部署模型。

   ```
   kubectl describe JumpStartModel $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
   ```

1. 驗證是否已成功建立端點。

   ```
   aws sagemaker describe-endpoint --endpoint-name=$SAGEMAKER_ENDPOINT_NAME --output table
   ```

1. 調用您的模型端點。您可以透過程式設計方式從 `JumpStartModel` 物件擷取範例承載。

   ```
   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
   ```

## 管理您的部署
<a name="kubectl-manage-your-deployment"></a>

一旦您不再需要 JumpStart 模型部署，請將其刪除。

```
kubectl delete JumpStartModel $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```

**疑難排解**

如果您的部署未如預期般運作，請使用這些偵錯命令。

1. 檢查 Kubernetes 部署的狀態。此命令會檢查基礎 Kubernetes 部署物件，此物件會管理執行您模型的 Pod。使用此功能，針對 Pod 排程、資源配置和容器啟動問題進行疑難排解。

   ```
   kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
   ```

1. 檢查 JumpStart 模型資源的狀態。此命令會檢查管理高階模型組態和部署生命週期的自訂 `JumpStartModel` 資源。使用此功能，針對模型特定問題進行疑難排解，例如組態錯誤或 SageMaker AI 端點建立問題。

   ```
   kubectl describe JumpStartModel $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
   ```

1. 檢查所有 Kubernetes 物件的狀態。此命令提供命名空間中所有相關 Kubernetes 資源的全面概觀。使用此功能進行快速運作狀態檢查，以查看與模型部署相關聯之 Pod、服務、部署和自訂資源的整體狀態。

   ```
   kubectl get pods,svc,deployment,JumpStartModel,sagemakerendpointregistration -n $CLUSTER_NAMESPACE
   ```