前提条件セットアップと設定パフォーマンスを向上させるために KV キャッシュとインテリジェントルーティングを設定する Amazon S3 または Amazon FSx からモデルをデプロイするデプロイのステータスを検証するデプロイを管理する

kubectl を使用して Amazon S3 および Amazon FSx からカスタムのファインチューニングされたモデルをデプロイする

次の手順では、kubectl を使用して Amazon S3 または Amazon FSx に保存されているモデルを Amazon SageMaker HyperPod クラスターにデプロイする方法を説明します。

次の手順には、ターミナルで実行するように設計されたコードセルとコマンドが含まれています。これらのコマンドを実行する前に、 AWS認証情報を使用して環境が設定されていることを確認してください。

前提条件

開始する前に、以下が整っていることを検証します。

Amazon SageMaker HyperPod クラスターでの推論機能の設定。詳細については、「モデルデプロイ用の HyperPod クラスターの設定」を参照してください。
kubectl ユーティリティのインストールとターミナルでの jq の設定

セットアップと設定

すべてのプレースホルダー値を実際のリソース識別子に置き換えます。

環境内のリージョンを選択します。
```
export REGION=<region>
```
クラスター名を初期化します。これにより、モデルがデプロイされる 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"
```
クラスター名前空間を初期化します。クラスター管理者は、名前空間に hyperpod-inference サービスアカウントを既に作成しているはずです。
```
cluster_namespace="<namespace>"
```

次のオプションのうち 1 つを使用して新しいスタックを作成します。

Using Amazon FSx as the model source

SageMaker エンドポイント名を設定します。
```
export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx"
```
使用する Amazon FSx ファイルシステム ID を設定します。
```
export FSX_FILE_SYSTEM_ID="fs-1234abcd"
```

以下は、Amazon FSx と DeepSeek モデルを使用してエンドポイントを作成するための yaml ファイルの例です。

注記

GPU パーティショニングが有効になっているクラスターの場合は、をなどの適切な MIG リソース名nvidia.com/gpuに置き換えます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

SageMaker エンドポイント名を設定します。
```
export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"
```
モデルが配置されている Amazon S3 バケットの場所を設定します。
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

以下は、Amazon S3 と DeepSeek モデルを使用してエンドポイントを作成するための yaml ファイルの例です。

注記

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

SageMaker エンドポイント名を設定します。
```
export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"
```
モデルが配置されている Amazon S3 バケットの場所を設定します。
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

以下は、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 キャッシュとインテリジェントルーティングを設定する

enableL1Cache と enableL2Cacheをに設定して KV キャッシュを有効にしますtrue。次に、 l2CacheSpecをに設定redisし、Redis クラスター URL l2CacheLocalUrlで更新します。
```
  kvCacheSpec:
    enableL1Cache: true
    enableL2Cache: true
    l2CacheSpec:
      l2CacheBackend: <redis | tieredstorage>
      l2CacheLocalUrl: <redis cluster URL if l2CacheBackend is redis >
```
注記
redis クラスターが HyperPod クラスターと同じ Amazon VPC 内にない場合、転送中のデータの暗号化は保証されません。

注記
階層型ストレージが選択されている場合は、l2CacheLocalUrl は必要ありません。
true で enabled をに設定して、インテリジェントルーティングを有効にしますintelligentRoutingSpec。で使用するルーティング戦略をで指定できますroutingStrategy。ルーティング戦略が指定されていない場合、デフォルトでになりますprefixaware。
```
intelligentRoutingSpec:
    enabled: true
    routingStrategy: <routing strategy to use>
```
true で enabledをに設定して、ルーターメトリクスとキャッシュメトリクスを有効にしますmetrics。port 値は、 containerPortの値と同じである必要がありますmodelInvocationPort。
```
metrics:
    enabled: true
    modelMetrics:
      port: <port value>
    ...
    modelInvocationPort:
      containerPort: <port value>
```

Amazon S3 または Amazon FSx からモデルをデプロイする

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

次のいずれかのオプションを使用して、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
```

デプロイのステータスを検証する

モデルが正常にデプロイされたかどうかを確認します。


kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

エンドポイントが正常に作成されたことを検証します。


kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

デプロイされたエンドポイントをテストして、適切に動作していることを検証します。このステップでは、モデルが正常にデプロイされ、推論リクエストを処理できることを確認します。
```
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
```

デプロイを管理する

デプロイのテストが完了したら、次のコマンドを使用してリソースをクリーンアップします。

注記

続行する前に、デプロイされたモデルや保存されたデータが不要になったことを検証します。

リソースのクリーンアップ

推論デプロイと関連する Kubernetes リソースを削除します。これにより、実行中のモデルコンテナが停止し、SageMaker エンドポイントが削除されます。
```
kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```

クリーンアップが正常に完了したことを検証します。


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

トラブルシューティング

デプロイが想定どおりに機能しない場合は、これらのデバッグコマンドを使用します。

Kubernetes デプロイのステータスを確認します。


kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

InferenceEndpointConfig ステータスをチェックして、高レベルのデプロイ状態を確認し、設定の問題がないかを調べます。
```
kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```
すべての Kubernetes オブジェクトのステータスを確認します。名前空間内のすべての関連 Kubernetes リソースの包括的なビューを取得します。これにより、実行中のリソースと不足している可能性のあるリソースの概要を簡単に確認できます。
```
kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE
```

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

kubectl を使用して JumpStart からモデルをデプロイする

自動スケーリング