翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 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/) ユーティリティのインストールとターミナルでの [jq](https://jqlang.org/) の設定 ## セットアップと設定 すべてのプレースホルダー値を実際のリソース識別子に置き換えます。 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.8xlarge for deepseek-r1 1.5b model which has sufficient memory and GPU instance_type="ml.g5.8xlarge" ``` 1. クラスター名前空間を初期化します。クラスター管理者は、名前空間に hyperpod-inference サービス アカウントを既に作成しているはずです。 ``` cluster_namespace="" ``` 1. 次のオプションのうち 1 つを使用して新しいスタックを作成します。 ------ #### [ Using Amazon FSx as the model source ] 1. SageMaker エンドポイント名を設定します。 ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx" ``` 1. 使用する Amazon FSx ファイルシステム ID を設定します。 ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. 以下は、Amazon FSx と DeepSeek モデルを使用してエンドポイントを作成するための 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: 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" ``` 1. モデルが配置されている Amazon S3 バケットの場所を設定します。 ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. 以下は、Amazon S3 と DeepSeek モデルを使用してエンドポイントを作成するための 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/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" ``` 1. モデルが配置されている Amazon S3 バケットの場所を設定します。 ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. 以下は、Amazon S3 と DeepSeek モデルを使用してエンドポイントを作成するための yaml ファイルの例です。 ``` cat < 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 ``` ------ #### [ 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.10.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 キャッシュとインテリジェントルーティングを設定する 1. `enableL1Cache` と `enableL2Cache`を に設定して KV キャッシュを有効にします`true`。次に、 `l2CacheSpec`を に設定`redis`し、Redis クラスター URL `l2CacheLocalUrl`で更新します。 ``` kvCacheSpec: enableL1Cache: true enableL2Cache: true l2CacheSpec: l2CacheBackend: l2CacheLocalUrl: ``` **注記** redis クラスターが HyperPod クラスターと同じ Amazon VPC 内にない場合、転送中のデータの暗号化は保証されません。 **注記** 階層型ストレージが選択されている場合は、l2CacheLocalUrl は必要ありません。 1. `true` で `enabled` を に設定して、インテリジェントルーティングを有効にします`intelligentRoutingSpec`。で使用するルーティング戦略を で指定できます`routingStrategy`。ルーティング戦略が指定されていない場合、デフォルトで になります`prefixaware`。 ``` intelligentRoutingSpec: enabled: true routingStrategy: ``` 1. `true` で `enabled`を に設定して、ルーターメトリクスとキャッシュメトリクスを有効にします`metrics`。`port` 値は、 `containerPort`の値と同じである必要があります`modelInvocationPort`。 ``` metrics: enabled: true modelMetrics: port: ... modelInvocationPort: containerPort: ``` ## 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 ```