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.24xlarge for Llama 3.1 8B model which has sufficient memory and GPU
   instance_type="ml.g5.24xlarge"

3. クラスター名前空間を初期化します。クラスター管理者は、名前空間に hyperpod-inference サービス アカウントを既に作成しているはずです。

   cluster_namespace="<namespace>"

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

   Using Amazon FSx as the model source

   1. SageMaker エンドポイント名を設定します。

      export SAGEMAKER_ENDPOINT_NAME="llama-fsx"

   2. 使用する Amazon FSx ファイルシステム ID を設定します。

      export FSX_FILE_SYSTEM_ID="fs-1234abcd"

   3. 以下は、Amazon FSx と Llama モデルを使用してエンドポイントを作成するための 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: $SAGEMAKER_ENDPOINT_NAME
        namespace: $CLUSTER_NAMESPACE
      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: Llama-3.1-8B-Instruct
          modelSourceType: fsx
        worker:
          image: vllm/vllm-openai:v0.19.1
          modelInvocationPort:
            containerPort: 8000
            name: http
          modelVolumeMount:
            mountPath: /opt/ml/model
            name: model-weights
          resources:
            limits:
              nvidia.com/gpu: 4
            requests:
              cpu: 30000m
              memory: 100Gi
              nvidia.com/gpu: 4
          args:
            - "--model"
            - "/opt/ml/model"
            - "--port"
            - "8000"
            - "--tensor-parallel-size"
            - "4"
            - "--served-model-name"
            - "Llama-3.1-8B-Instruct"
          environmentVariables:
            - name: VLLM_REQUEST_TIMEOUT
              value: "600"
      EOF

   Using Amazon S3 as the model source

   1. SageMaker エンドポイント名を設定します。

      export SAGEMAKER_ENDPOINT_NAME="llama-s3"

   2. モデルが配置されている Amazon S3 バケットの場所を設定します。

      export S3_MODEL_LOCATION="<your-s3-bucket-name>"

   3. 以下は、推論ランタイムとして vLLM を使用して Amazon S3 と Llama モデルでエンドポイントを作成するための yaml ファイルの例です。

      注記

      GPU パーティショニングが有効になっているクラスターの場合は、 を などの適切な MIG リソース名nvidia.com/gpuに置き換えますnvidia.com/mig-1g.10gb。詳細については、「MIG を使用したタスク送信」を参照してください。

      cat <<EOF> deploy_s3_inference.yaml
      ---
      apiVersion: inference.sagemaker.aws.amazon.com/v1
      kind: InferenceEndpointConfig
      metadata:
        name: $SAGEMAKER_ENDPOINT_NAME
        namespace: $CLUSTER_NAMESPACE
      spec:
        modelName: Llama-3.1-8B-Instruct
        instanceType: ml.g5.24xlarge
        invocationEndpoint: v1/chat/completions
        replicas: 2
        modelSourceConfig:
          modelSourceType: s3
          s3Storage:
            bucketName: $S3_MODEL_LOCATION
            region: $REGION
          modelLocation: Llama-3.1-8B-Instruct
          prefetchEnabled: true
        worker:
          image: vllm/vllm-openai:v0.19.1
          modelInvocationPort:
            containerPort: 8000
            name: http
          modelVolumeMount:
            name: model-weights
            mountPath: /opt/ml/model
          resources:
            limits:
              nvidia.com/gpu: 4
            requests:
              cpu: 30000m
              memory: 100Gi
              nvidia.com/gpu: 4
          args:
            - "--model"
            - "/opt/ml/model"
            - "--port"
            - "8000"
            - "--tensor-parallel-size"
            - "4"
            - "--served-model-name"
            - "Llama-3.1-8B-Instruct"
          environmentVariables:
            - name: VLLM_REQUEST_TIMEOUT
              value: "600"
      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 パーティショニングが有効になっているクラスターの場合は、 を などの適切な MIG リソース名nvidia.com/gpuに置き換えます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.19.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 (オプション) — の場合true、init コンテナは推論コンテナの開始前にモデルをダウンロードします。の場合false、推論ランタイム (vLLM、TGI、SGLang) は起動時にモデルをネイティブにダウンロードします。デフォルトは false です。

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