翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # kubectl を使用して Amazon S3、Amazon FSx、または Hugging Face Hub からモデルをデプロイする 次のステップでは、kubectl を使用して Amazon S3、Amazon FSx、または Hugging Face Hub に保存されているモデルを Amazon SageMaker HyperPod クラスターにデプロイする方法を示します。 次の手順には、ターミナルで実行するように設計されたコードセルとコマンドが含まれています。これらのコマンドを実行する前に、 AWS 認証情報を使用して環境が設定されていることを確認してください。 ## 前提条件 開始する前に、以下が整っていることを検証します。 + Amazon SageMaker HyperPod クラスターでの推論機能の設定。詳細については、「[モデルデプロイ用の HyperPod クラスターの設定](sagemaker-hyperpod-model-deployment-setup.md)」を参照してください。 + ターミナルに [kubectl](https://kubernetes.io/docs/reference/kubectl/) ユーティリティをインストールしました。 ## セットアップと設定 すべてのプレースホルダー値を実際のリソース識別子に置き換えます。 1. 環境内のリージョンを選択します。 ``` export REGION= ``` 1. クラスター名を初期化します。これにより、モデルがデプロイされる HyperPod クラスターが識別されます。 **注記** クラスター管理者に確認して、このロールまたはユーザーにアクセス許可が付与されていることを確認します。`!aws sts get-caller-identity --query "Arn"` を実行すると、ターミナルで使用しているロールまたはユーザーを確認できます。 ``` # Specify your hyperpod cluster name here 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" ``` 1. クラスター名前空間を初期化します。クラスター管理者は、名前空間に hyperpod-inference サービス アカウントを既に作成しているはずです。 ``` cluster_namespace="" ``` 1. 次のオプションのうち 1 つを使用して新しいスタックを作成します。 ------ #### [ Using Amazon FSx as the model source ] 1. SageMaker エンドポイント名を設定します。 ``` export SAGEMAKER_ENDPOINT_NAME="llama-fsx" ``` 1. 使用する Amazon FSx ファイルシステム ID を設定します。 ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. 以下は、Amazon FSx と Llama モデルを使用してエンドポイントを作成するための yaml ファイルの例です。 **注記** GPU パーティショニングが有効になっているクラスターの場合は、 を などの適切な MIG リソース名`nvidia.com/gpu`に置き換えます`nvidia.com/mig-1g.10gb`。詳細については、「[MIG を使用したタスク送信](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)」を参照してください。 ``` cat < 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" ``` 1. モデルが配置されている Amazon S3 バケットの場所を設定します。 ``` export S3_MODEL_LOCATION="" ``` 1. 以下は、推論ランタイムとして vLLM を使用して Amazon S3 と Llama モデルでエンドポイントを作成するための yaml ファイルの例です。 **注記** GPU パーティショニングが有効になっているクラスターの場合は、 を などの適切な MIG リソース名`nvidia.com/gpu`に置き換えます`nvidia.com/mig-1g.10gb`。詳細については、「[MIG を使用したタスク送信](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)」を参照してください。 ``` cat < 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](https://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 ``` 1. SageMaker エンドポイント名を設定します。 ``` export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf" ``` 1. 以下は、vLLM を推論ランタイムとして使用して Hugging Face Hub から Mistral 7B モデルをデプロイするための YAML ファイルの例です。では`prefetchEnabled: true`、演算子は init コンテナを使用して、推論コンテナが起動する前にモデルをダウンロードします。 **注記** GPU パーティショニングが有効になっているクラスターの場合は、 を などの適切な MIG リソース名`nvidia.com/gpu`に置き換えます`nvidia.com/mig-1g.10gb`。詳細については、「[MIG を使用したタスク送信](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md)」を参照してください。 ``` cat < 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 ``` 1. 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` です。 ------ **注記** パフォーマンスを向上させるために KV キャッシュとインテリジェントルーティングを設定するには、「」を参照してください[KV キャッシュとインテリジェントルーティングを設定する](sagemaker-hyperpod-model-deployment-caching-routing.md#sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route)。 ## Amazon S3、Amazon FSx、または Hugging Face Hub からモデルをデプロイする 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 ``` 1. 次のいずれかのオプションを使用して、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 モデルのデプロイの失敗](sagemaker-hyperpod-model-deployment-ts-huggingface.md)。 ------ ## デプロイのステータスを検証する 1. モデルが正常にデプロイされたかどうかを確認します。 ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. エンドポイントが正常に作成されたことを検証します。 ``` kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. デプロイされたエンドポイントをテストして、適切に動作していることを検証します。このステップでは、モデルが正常にデプロイされ、推論リクエストを処理できることを確認します。 ``` 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 ``` 1. クリーンアップが正常に完了したことを検証します。 ``` # # 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 ``` 1. InferenceEndpointConfig ステータスをチェックして、高レベルのデプロイ状態を確認し、設定の問題がないかを調べます。 ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. すべての Kubernetes オブジェクトのステータスを確認します。名前空間内のすべての関連 Kubernetes リソースの包括的なビューを取得します。これにより、実行中のリソースと不足している可能性のあるリソースの概要を簡単に確認できます。 ``` kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE ```