kubectl を使用して Amazon S3 および Amazon FSx からカスタム微調整モデルをデプロイする

1. クラスター名を初期化します。これにより、モデルがデプロイされる HyperPod クラスターが識別されます。

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

2. クラスター名前空間を初期化します。クラスター管理者は、名前空間にハイパーポッド推論サービスアカウントを既に作成している必要があります。

   cluster_namespace="<namespace>"

3. デプロイ用の YAML ファイルを作成するヘルパーメソッドを定義する

   次のヘルパー関数は、モデルのデプロイに必要な Kubernetes YAML 設定ファイルを生成します。この関数は、モデルが Amazon S3 に保存されているか Amazon FSx に保存されているかに応じて異なる YAML 構造を作成し、ストレージ固有の設定を自動的に処理します。次のセクションでこの関数を使用して、選択したストレージバックエンドのデプロイファイルを生成します。

   def generate_inferenceendpointconfig_yaml(deployment_name, model_id, namespace, instance_type, output_file_path, region, tls_certificate_s3_location, model_location, sagemaker_endpoint_name, fsxFileSystemId="", isFsx=False, s3_bucket=None):
       """
       Generate a InferenceEndpointConfig YAML file for S3 storage with the provided parameters.
   
       Args:
           deployment_name (str): The deployment name
           model_id (str): The model ID
           namespace (str): The namespace
           instance_type (str): The instance type
           output_file_path (str): Path where the YAML file will be saved
           region (str): Region where bucket exists
           tls_certificate_s3_location (str): S3 location for TLS certificate
           model_location (str): Location of the model
           sagemaker_endpoint_name (str): Name of the SageMaker endpoint
           fsxFileSystemId (str): FSx filesystem ID (optional)
           isFsx (bool): Whether to use FSx storage (optional)
           s3_bucket (str): S3 bucket where model exists (optional, only needed when isFsx is False)
       """
   
       # Create the YAML structure
       model_config = {
           "apiVersion": "inference.sagemaker.aws.amazon.com/v1alpha1",
           "kind": "InferenceEndpointConfig",
           "metadata": {
               "name": deployment_name,
               "namespace": namespace
           },
           "spec": {
               "modelName": model_id,
               "endpointName": sagemaker_endpoint_name,  
               "invocationEndpoint": "invocations",
               "instanceType": instance_type,
               "modelSourceConfig": {},
               "worker": {
                   "resources": {
                       "limits": {
                           "nvidia.com/gpu": 1,
                       },
                       "requests": {
                           "nvidia.com/gpu": 1,
                           "cpu": "30000m",
                           "memory": "100Gi"
                       }
                   },
                   "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": {
                       "name": "model-weights",
                       "mountPath": "/opt/ml/model"
                   },
                   "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",
                       }
                   ]
               },
               "tlsConfig": {
                   "tlsCertificateOutputS3Uri": tls_certificate_s3_location,
               }
           },
       }
   
       if (not isFsx):
           if s3_bucket is None:
               raise ValueError("s3_bucket is required when isFsx is False")
           model_config["spec"]["modelSourceConfig"] = {
               "modelSourceType": "s3",
               "s3Storage": {
                   "bucketName": s3_bucket,
                   "region": region,
               },
               "modelLocation": model_location
           }
       else:
           model_config["spec"]["modelSourceConfig"] = {
               "modelSourceType": "fsx",
               "fsxStorage": {
                   "fileSystemId": fsxFileSystemId,
               },
               "modelLocation": model_location
           }
       
   
       # Write to YAML file
       with open(output_file_path, 'w') as file:
           yaml.dump(model_config, file, default_flow_style=False)
   
       print(f"YAML file created successfully at: {output_file_path}")

クラスターにモデルをデプロイする

1. kubectl 認証用の HyperPod クラスター ARN から Amazon EKS クラスター名を取得します。

   cluster_arn = !aws sagemaker describe-cluster --cluster-name $hyperpod_cluster_name --query "Orchestrator.Eks.ClusterArn" --region $region_name
   cluster_name = cluster_arn[0].strip('"').split('/')[-1]
   print(cluster_name)

2. AWS 認証情報を使用して Hyperpod EKS クラスターで認証するように kubectl を設定する

   !aws eks update-kubeconfig --name $cluster_name --region $region_name

3. InferenceEndpointConfig モデルをデプロイします。

   !kubectl apply -f $INFERENCE_ENDPOINT_CONFIG_YAML_FILE_PATH

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

   !kubectl describe InferenceEndpointConfig $deployment_name -n $cluster_namespace

   このコマンドにより、以下のような出力が返されます。

   Name:                             deepseek15b-20250624043033
   Reason:                           NativeDeploymentObjectFound
   Status:
     Conditions:
       Last Transition Time:  2025-07-10T18:39:51Z
       Message:               Deployment, ALB Creation or SageMaker endpoint registration creation for model is in progress
       Reason:                InProgress
       Status:                True
       Type:                  DeploymentInProgress
       Last Transition Time:  2025-07-10T18:47:26Z
       Message:               Deployment and SageMaker endpoint registration for model have been created successfully
       Reason:                Success
       Status:                True
       Type:                  DeploymentComplete

2. エンドポイントが正常に作成されたことを確認します。

   !kubectl describe SageMakerEndpointRegistration $sagemaker_endpoint_name -n $cluster_namespace

   このコマンドにより、以下のような出力が返されます。

   Name:         deepseek15b-20250624043033
   Namespace:    ns-team-a
   Kind:         SageMakerEndpointRegistration
   
   Status:
     Conditions:
       Last Transition Time:  2025-06-24T04:33:42Z
       Message:               Endpoint created.
       Status:                True
       Type:                  EndpointCreated
       State:                 CreationCompleted

3. デプロイされたエンドポイントをテストして、正しく動作していることを確認します。このステップでは、モデルが正常にデプロイされ、推論リクエストを処理できることを確認します。

   import boto3
   
   prompt = "{\"inputs\": \"How tall is Mt Everest?\"}}"
   
   runtime_client = boto3.client('sagemaker-runtime', region_name=region_name, config=boto3_config)
   response = runtime_client.invoke_endpoint(
       EndpointName=sagemaker_endpoint_name,
       ContentType="application/json",
       Body=prompt
   )
   print(response["Body"].read().decode())

   [{"generated_text":"As of the last update in July 2024, Mount Everest stands at a height of **8,850 meters** (29,029 feet) above sea level. The exact elevation can vary slightly due to changes caused by tectonic activity and the melting of ice sheets."}]

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

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

   !kubectl delete inferenceendpointconfig.inference.sagemaker.aws.amazon.com/$deployment_name

2. （オプション) FSx ボリュームを削除します。

   try:
       # Delete the file system
       response = fsx.delete_file_system(
           FileSystemId=file_system_id
       )
       
       print(f"Deleting FSx filesystem: {file_system_id}")
       
       # Optional: Wait for deletion to complete
       while True:
           try:
               response = fsx.describe_file_systems(FileSystemIds=[file_system_id])
               status = response['FileSystems'][0]['Lifecycle']
               print(f"Current status: {status}")
               time.sleep(30)
           except fsx.exceptions.FileSystemNotFound:
               print("File system deleted successfully")
               break
               
   except Exception as e:
       print(f"Error deleting file system: {str(e)}")

3. クリーンアップが正常に完了したことを確認します。

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

トラブルシューティング

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

   !kubectl describe deployment $deployment_name -n $cluster_namespace

2. InferenceEndpointConfig のステータスをチェックして、高レベルのデプロイ状態と設定の問題を確認します。

   kubectl describe InferenceEndpointConfig $deployment_name -n $cluster_namespace

3. すべての Kubernetes オブジェクトのステータスを確認します。名前空間内のすべての関連 Kubernetes リソースの包括的なビューを取得します。これにより、実行中のものと不足している可能性のあるものの概要を簡単に確認できます。

   !kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $cluster_namespace