Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Déployez des modèles depuis Amazon S3, Amazon FSx ou Hugging Face Hub à l'aide de kubectl Les étapes suivantes vous montrent comment déployer des modèles stockés sur Amazon S3, Amazon FSx ou Hugging Face Hub sur un cluster SageMaker HyperPod Amazon à l'aide de kubectl. Les instructions suivantes contiennent des cellules de code et des commandes conçues pour être exécutées dans un terminal. Assurez-vous d'avoir configuré votre environnement avec des AWS informations d'identification avant d'exécuter ces commandes. ## Conditions préalables Avant de commencer, vérifiez les points suivants : + Configurez des fonctionnalités d'inférence sur vos SageMaker HyperPod clusters Amazon. Pour de plus amples informations, veuillez consulter [Configuration de vos HyperPod clusters pour le déploiement de modèles](sagemaker-hyperpod-model-deployment-setup.md). + Vous avez installé l’utilitaire [kubectl](https://kubernetes.io/docs/reference/kubectl/) et configuré [jq](https://jqlang.org/) dans votre terminal. ## Installation et configuration Remplacez toutes les valeurs d’espace réservé par vos identifiants de ressources réels. 1. Sélectionnez votre région dans votre environnement. ``` export REGION= ``` 1. Initialisez le nom de votre cluster. Cela permet d'identifier le HyperPod cluster dans lequel votre modèle sera déployé. **Note** Vérifiez auprès de l’administrateur de votre cluster que les autorisations sont accordées pour ce rôle ou cet utilisateur. Vous pouvez exécuter `!aws sts get-caller-identity --query "Arn"` pour vérifier le rôle ou l’utilisateur que vous utilisez sur votre terminal. ``` # 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. Initialisez l’espace de noms de votre cluster. L’administrateur de votre cluster doit déjà avoir créé un compte de service d’inférence Hyperpod dans votre espace de noms. ``` cluster_namespace="" ``` 1. Créez un CRD en utilisant l’une des options suivantes : ------ #### [ Using Amazon FSx as the model source ] 1. Définissez un nom de point de SageMaker terminaison. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx" ``` 1. Configurez l’ID du système de fichiers Amazon FSx à utiliser. ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon FSx et DeepSeek un modèle. **Note** Pour les clusters sur lesquels le partitionnement du GPU est activé, remplacez-le `nvidia.com/gpu` par le nom de ressource MIG approprié, tel que. `nvidia.com/mig-1g.10gb` Pour de plus amples informations, veuillez consulter [Soumission de tâches avec 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. Définissez un nom de point de SageMaker terminaison. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. Configurez l’emplacement du compartiment Amazon S3 où se trouve le modèle. ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon S3 et un DeepSeek modèle. **Note** Pour les clusters sur lesquels le partitionnement du GPU est activé, remplacez-le `nvidia.com/gpu` par le nom de ressource MIG approprié, tel que. `nvidia.com/mig-1g.10gb` Pour de plus amples informations, veuillez consulter [Soumission de tâches avec 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. Définissez un nom de point de SageMaker terminaison. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. Configurez l’emplacement du compartiment Amazon S3 où se trouve le modèle. ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon S3 et un DeepSeek modèle. ``` 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. Créez un secret Kubernetes contenant votre jeton d'API Hugging Face. Ce jeton est obligatoire pour les modèles sécurisés et recommandé pour tous les téléchargements. Vous pouvez générer un jeton sur [Huggingface. co/settings/jetons.](https://huggingface.co/settings/tokens) **Important** Le déploiement de modèles depuis Hugging Face Hub nécessite un accès Internet sortant depuis les nœuds de votre cluster vers les domaines Hugging Face, y compris et. `*.huggingface.co` `*.hf.co` Assurez-vous que la configuration réseau de votre VPC (passerelle NAT, groupes de sécurité et ACL réseau) autorise la sortie HTTPS vers ces domaines. Sans accès à Internet, le téléchargement du modèle échouera. **Note** Pour les environnements de production, nous recommandons d'utiliser Amazon S3 ou Amazon FSx comme source du modèle plutôt que Hugging Face Hub. Avec Amazon S3 et Amazon FSx, les artefacts du modèle sont stockés dans votre AWS compte, éliminant ainsi la dépendance à l'égard de la connectivité Internet externe et garantissant des délais de déploiement plus prévisibles. Hugging Face Hub convient parfaitement au développement, à l'expérimentation et au prototypage rapide pour lesquels l'accès direct au référentiel de modèles Hugging Face est pratique. ``` kubectl create secret generic hf-token-secret \ --from-literal=token=hf_YOUR_TOKEN_HERE \ -n $CLUSTER_NAMESPACE ``` 1. Définissez un nom de point de SageMaker terminaison. ``` export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf" ``` 1. Voici un exemple de fichier YAML pour déployer un modèle Mistral 7B à partir de Hugging Face Hub en utilisant vLLM comme environnement d'inférence. Avec`prefetchEnabled: true`, l'opérateur utilise un conteneur d'initialisation pour télécharger le modèle avant le démarrage du conteneur d'inférence. **Note** Pour les clusters sur lesquels le partitionnement du GPU est activé, remplacez-le `nvidia.com/gpu` par le nom de ressource MIG approprié, tel que. `nvidia.com/mig-1g.10gb` Pour de plus amples informations, veuillez consulter [Soumission de tâches avec 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. Les principaux champs de configuration de Hugging Face sont les suivants : + `modelSourceType`(obligatoire) — Réglé sur`huggingface`. + `huggingFaceModel.modelId`(obligatoire) — L'identifiant du modèle Hugging Face Hub `org/model` au format (par exemple`mistralai/Mistral-7B-Instruct-v0.3`,). + `huggingFaceModel.commitSHA`(facultatif) — Un SHA de 40 caractères de validation Git pour épingler une version de modèle spécifique. En cas d'omission, c'est la `main` branche par défaut. + `huggingFaceModel.tokenSecretRef`(facultatif) — Référence à un secret Kubernetes contenant votre jeton d'API Hugging Face. Nécessaire pour les modèles à portail. Le jeton est uniquement utilisé lors du téléchargement du modèle et n'est pas exposé au conteneur d'inférence. + `prefetchEnabled`(facultatif) — Quand un conteneur `true` d'initialisation télécharge le modèle avant le démarrage du conteneur d'inférence. Lorsque`false`, le moteur d'inférence (VLLm, TGI, SGlang) télécharge le modèle de manière native au démarrage. La valeur par défaut est `false` . ------ ## Configurez la mise en cache KV et le routage intelligent pour améliorer les performances 1. Activez la mise en cache KV en définissant `enableL1Cache` et en `enableL2Cache` sélectionnant `true` .Ensuite, définissez `redis` et mettez `l2CacheSpec` à jour `l2CacheLocalUrl` avec l'URL du cluster Redis. ``` kvCacheSpec: enableL1Cache: true enableL2Cache: true l2CacheSpec: l2CacheBackend: l2CacheLocalUrl: ``` **Note** Si le cluster Redis ne fait pas partie du même Amazon VPC que HyperPod le cluster, le chiffrement des données en transit n'est pas garanti. **Note** Vous n'avez pas besoin de l2 CacheLocalUrl si le stockage hiérarchisé est sélectionné. 1. Activez le routage intelligent en `enabled` réglant sur `true` moins`intelligentRoutingSpec`. Vous pouvez spécifier la stratégie de routage à utiliser dans le cadre de cette section`routingStrategy`. Si aucune stratégie de routage n'est spécifiée, la valeur par défaut est. `prefixaware` ``` intelligentRoutingSpec: enabled: true routingStrategy: ``` 1. Activez les métriques du routeur et les métriques de mise en cache en les réglant `enabled` sur `true` moins`metrics`. La `port` valeur doit être identique à la `containerPort` valeur inférieure`modelInvocationPort`. ``` metrics: enabled: true modelMetrics: port: ... modelInvocationPort: containerPort: ``` ## Déployez votre modèle depuis Amazon S3, Amazon FSx ou Hugging Face Hub 1. Obtenez le nom du cluster Amazon EKS à partir de l'ARN du HyperPod cluster pour l'authentification kubectl. ``` 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. Déployez votre InferenceEndpointConfig modèle avec l'une des options suivantes : ------ #### [ 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 ``` Si le déploiement échoue, vérifiez les InferenceEndpointConfig événements pour obtenir des informations de diagnostic. Pour les problèmes courants tels que les erreurs liées aux jetons, la connectivité réseau et l'impossibilité de trouver un modèle, consultez[Défaillances du déploiement du modèle Hugging Face Hub](sagemaker-hyperpod-model-deployment-ts-huggingface.md). ------ ## Vérification du statut de votre déploiement 1. Vérifiez si le modèle a été correctement déployé. ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Vérifiez que le point de terminaison est correctement créé. ``` kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Testez le point de terminaison déployé pour vérifier qu’il fonctionne correctement. Cette étape confirme que votre modèle est correctement déployé et qu’il peut traiter les demandes d’inférence. ``` 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 ``` ## Gestion de votre déploiement Lorsque vous n’avez plus besoin de tester votre déploiement, utilisez les commandes suivantes pour nettoyer vos ressources. **Note** Vérifiez que vous n’avez plus besoin du modèle déployé ou des données stockées avant de continuer. **Nettoyage de vos ressources** 1. Supprimez le déploiement d’inférence et les ressources Kubernetes associées. Cela arrête les conteneurs de modèles en cours d'exécution et supprime le SageMaker point de terminaison. ``` kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Vérifiez que le nettoyage a été effectué avec succès. ``` # # 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 ``` **Résolution des problèmes** Utilisez ces commandes de débogage si votre déploiement ne fonctionne pas comme prévu. 1. Vérifiez le statut du déploiement de Kubernetes. ``` kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Vérifiez le InferenceEndpointConfig statut pour connaître l'état de déploiement de haut niveau et les éventuels problèmes de configuration. ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Vérifiez le statut de tous les objets Kubernetes. Bénéficiez d’une vue complète de toutes les ressources Kubernetes associées dans votre espace de noms. Cela vous donne un aperçu rapide de ce qui est en cours d’exécution et de ce qui pourrait manquer. ``` kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE ```