기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 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 Hub에서 `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. Amazon EKS에 의해 오케스트레이션된 HyperPod 클러스터에 연결하도록 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. 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 배포 객체를 검사합니다. 포드 예약, 리소스 할당 및 컨테이너 시작 문제를 해결하는 데 사용합니다.

   ```
   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 리소스에 대한 포괄적인 개요를 제공합니다. 모델 배포와 관련된 포드, 서비스, 배포 및 사용자 지정 리소스의 전반적인 상태를 빠르게 확인하는 데 사용합니다.

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