kubectl을 사용하여 Amazon S3 및 Amazon FSx에서 사용자 지정 미세 조정 모델 배포 - Amazon SageMaker AI
사전 조건설정 및 구성성능 향상을 위한 KV 캐싱 및 지능형 라우팅 구성Amazon S3 또는 Amazon FSx에서 모델 배포배포 상태 확인배포 관리

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

kubectl을 사용하여 Amazon S3 및 Amazon FSx에서 사용자 지정 미세 조정 모델 배포

다음 단계에서는 kubectl을 사용하여 Amazon S3 또는 Amazon FSx에 저장된 모델을 Amazon SageMaker HyperPod 클러스터에 배포하는 방법을 보여줍니다.

다음 지침에는 터미널에서 실행되도록 설계된 코드 셀과 명령이 포함되어 있습니다. 이러한 명령을 실행하기 전에 자격 AWS증명으로 환경을 구성했는지 확인합니다.

사전 조건

시작하기 전에 다음을 수행했는지 확인합니다.

설정 및 구성

모든 자리 표시자 값을 실제 리소스 식별자로 바꿉니다.

  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

성능 향상을 위한 KV 캐싱 및 지능형 라우팅 구성

  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>

Amazon S3 또는 Amazon FSx에서 모델 배포

  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

배포 상태 확인

  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