kubectl을 사용하여 Amazon S3, Amazon FSx 또는 Hugging Face Hub에서 모델 배포

1. 환경에서 리전을 선택합니다.

   export REGION=<region>

2. 클러스터 이름을 초기화합니다. 그러면 모델이 배포될 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.8xlarge for deepseek-r1 1.5b model which has sufficient memory and GPU
   instance_type="ml.g5.8xlarge"

3. 클러스터 네임스페이스를 초기화합니다. 클러스터 관리자가 네임스페이스에 하이퍼포드 추론 서비스 계정을 이미 생성했어야 합니다.

   cluster_namespace="<namespace>"

4. 다음 옵션 중 하나를 사용하여 CRD를 생성합니다.

   Using Amazon FSx as the model source

   1. SageMaker 엔드포인트 이름을 설정합니다.

      export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx"

   2. 사용할 Amazon FSx 파일 시스템 ID를 구성합니다.

      export FSX_FILE_SYSTEM_ID="fs-1234abcd"

   3. 다음은 Amazon FSx 및 DeepSeek 모델을 사용하여 엔드포인트를 생성하기 위한 예시 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: 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"

   2. 모델이 위치한 Amazon S3 버킷 위치를 구성합니다.

      export S3_MODEL_LOCATION="deepseek-qwen-1-5b"

   3. 다음은 Amazon S3 및 DeepSeek 모델을 사용하여 엔드포인트를 생성하기 위한 예시 yaml 파일입니다.

      참고

      GPU 파티셔닝이 활성화된 클러스터의 경우를 nvidia.com/gpu와 같은 적절한 MIG 리소스 이름으로 바꿉니다nvidia.com/mig-1g.10gb. 자세한 내용은 MIG를 사용한 작업 제출 단원을 참조하십시오.

      cat <<EOF> 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"

   2. 모델이 위치한 Amazon S3 버킷 위치를 구성합니다.

      export S3_MODEL_LOCATION="deepseek-qwen-1-5b"

   3. 다음은 Amazon S3 및 DeepSeek 모델을 사용하여 엔드포인트를 생성하기 위한 예시 yaml 파일입니다.

      cat <<EOF> 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 보안 암호를 생성합니다. 이 토큰은 게이트 모델에 필요하며 모든 다운로드에 권장됩니다. huggingface.co/settings/tokens 토큰을 생성할 수 있습니다.

      중요

      Hugging Face Hub에서 모델을 배포하려면 클러스터 노드에서 *.huggingface.co 및를 포함한 Hugging Face 도메인으로의 아웃바운드 인터넷 액세스가 필요합니다*.hf.co. VPC 네트워킹 구성(NAT 게이트웨이, 보안 그룹 및 네트워크 ACLs)이 이러한 도메인으로 HTTPS 송신을 허용하는지 확인합니다. 인터넷 액세스가 없으면 모델 다운로드가 실패합니다.

      참고

      프로덕션 환경의 경우 Hugging Face Hub 대신 Amazon S3 또는 Amazon FSx를 모델 소스로 사용하는 것이 좋습니다. 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

   2. SageMaker 엔드포인트 이름을 설정합니다.

      export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

   3. 다음은 vLLM을 추론 런타임으로 사용하여 Hugging Face Hub에서 Mistral 7B 모델을 배포하기 위한 YAML 파일의 예입니다. prefetchEnabled: true를 사용하면 연산자는 추론 컨테이너가 시작되기 전에 init 컨테이너를 사용하여 모델을 다운로드합니다.

      참고

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

   4. 주요 Hugging Face 구성 필드는 다음과 같습니다.

      • modelSourceType (필수) -를 로 설정합니다huggingface.

      • huggingFaceModel.modelId (필수) - org/model 형식의 Hugging Face Hub 모델 식별자입니다(예: mistralai/Mistral-7B-Instruct-v0.3).

      • huggingFaceModel.commitSHA (선택 사항) - 특정 모델 버전을 고정하기 위해 40자 Git 커밋 SHA입니다. 생략하면 브main랜치가 기본값으로 설정됩니다.

      • huggingFaceModel.tokenSecretRef (선택 사항) - Hugging Face API 토큰이 포함된 Kubernetes 보안 암호에 대한 참조입니다. 게이트된 모델에 필요합니다. 토큰은 모델 다운로드 중에만 사용되며 추론 컨테이너에 노출되지 않습니다.

      • prefetchEnabled (선택 사항) - 이면 추론 컨테이너가 시작되기 전에 trueinit 컨테이너가 모델을 다운로드합니다. false인 경우 추론 런타임(vLLM, TGI, SGLang)은 시작 시 기본적으로 모델을 다운로드합니다. 기본값은 false입니다.

1. enableL1Cache 및를 enableL2Cache로 설정하여 KV 캐싱을 활성화합니다true. 그런 다음 l2CacheSpec를 로 설정하고 Redis 클러스터 URLl2CacheLocalUrl로 redis 업데이트합니다.

     kvCacheSpec:
       enableL1Cache: true
       enableL2Cache: true
       l2CacheSpec:
         l2CacheBackend: <redis | tieredstorage>
         l2CacheLocalUrl: <redis cluster URL if l2CacheBackend is redis >

   참고

   redis 클러스터가 HyperPod 클러스터와 동일한 Amazon VPC 내에 있지 않은 경우 전송 중인 데이터에 대한 암호화가 보장되지 않습니다.

   참고

   계층형 스토리지를 선택한 경우 l2CacheLocalUrl이 필요하지 않습니다.

2. true에서를 로 설정하여 지능형 라우팅enabled을 활성화합니다intelligentRoutingSpec. 에서 사용할 라우팅 전략을 지정할 수 있습니다routingStrategy. 라우팅 전략이 지정되지 않은 경우 기본값은 입니다prefixaware.

   intelligentRoutingSpec:
       enabled: true
       routingStrategy: <routing strategy to use>

3. true에서를 로 설정하여 라우터 지표 및 캐싱 지표enabled를 활성화합니다metrics. port 값은 아래의 containerPort 값과 동일해야 합니다modelInvocationPort.

   metrics:
       enabled: true
       modelMetrics:
         port: <port value>
       ...
       modelInvocationPort:
         containerPort: <port value>

1. kubectl 인증을 위해 HyperPod 클러스터 ARN에서 Amazon EKS 클러스터 이름을 가져옵니다.

   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

2. 다음 옵션 중 하나를 사용하여 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 모델 배포 실패.

1. 모델이 성공적으로 배포되었는지 확인합니다.

   kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

2. 엔드포인트가 성공적으로 생성되었는지 확인합니다.

   kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

3. 배포된 엔드포인트를 테스트하여 올바르게 작동하는지 확인합니다. 이 단계에서는 모델이 성공적으로 배포되었으며 추론 요청을 처리할 수 있는지 확인합니다.

   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

2. 정리가 성공적으로 완료되었는지 확인합니다.

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

2. InferenceEndpointConfig 상태를 확인하여 개괄적인 배포 상태와 구성 문제를 확인합니다.

   kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

3. 모든 Kubernetes 객체의 상태를 확인합니다. 네임스페이스의 모든 관련 Kubernetes 리소스를 포괄적으로 볼 수 있습니다. 이를 통해 실행 중인 항목과 누락된 항목에 대한 간략한 개요를 확인할 수 있습니다.

   kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE