Conditions préalables Installation et configuration Configurez la mise en cache KV et le routage intelligent pour améliorer les performances Déployez votre modèle depuis Amazon S3, Amazon FSx ou Hugging Face Hub Vérification du statut de votre déploiement Gestion de votre déploiement

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.
Vous avez installé l’utilitaire kubectl et configuré jq dans votre terminal.

Installation et configuration

Remplacez toutes les valeurs d’espace réservé par vos identifiants de ressources réels.

Sélectionnez votre région dans votre environnement.
```
export REGION=<region>
```
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="<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"
```
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="<namespace>"
```

Créez un CRD en utilisant l’une des options suivantes :

Using Amazon FSx as the model source

Définissez un nom de point de SageMaker terminaison.
```
export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx"
```
Configurez l’ID du système de fichiers Amazon FSx à utiliser.
```
export FSX_FILE_SYSTEM_ID="fs-1234abcd"
```

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.

cat <<EOF> 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

Définissez un nom de point de SageMaker terminaison.
```
export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"
```
Configurez l’emplacement du compartiment Amazon S3 où se trouve le modèle.
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon S3 et un DeepSeek modèle.

Note

cat <<EOF> 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

Définissez un nom de point de SageMaker terminaison.
```
export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"
```
Configurez l’emplacement du compartiment Amazon S3 où se trouve le modèle.
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon S3 et un DeepSeek modèle.

cat <<EOF> 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

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.

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
```
Définissez un nom de point de SageMaker terminaison.
```
export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"
```

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. AvecprefetchEnabled: 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

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.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

Les principaux champs de configuration de Hugging Face sont les suivants :
- modelSourceType(obligatoire) — Réglé surhuggingface.
- huggingFaceModel.modelId(obligatoire) — L'identifiant du modèle Hugging Face Hub org/model au format (par exemplemistralai/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. Lorsquefalse, 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

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: <redis | tieredstorage>
      l2CacheLocalUrl: <redis cluster URL if l2CacheBackend is redis >
```
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é.
Activez le routage intelligent en enabled réglant sur true moinsintelligentRoutingSpec. Vous pouvez spécifier la stratégie de routage à utiliser dans le cadre de cette sectionroutingStrategy. Si aucune stratégie de routage n'est spécifiée, la valeur par défaut est. prefixaware
```
intelligentRoutingSpec:
    enabled: true
    routingStrategy: <routing strategy to use>
```
Activez les métriques du routeur et les métriques de mise en cache en les réglant enabled sur true moinsmetrics. La port valeur doit être identique à la containerPort valeur inférieuremodelInvocationPort.
```
metrics:
    enabled: true
    modelMetrics:
      port: <port value>
    ...
    modelInvocationPort:
      containerPort: <port value>
```

Déployez votre modèle depuis Amazon S3, Amazon FSx ou Hugging Face Hub

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

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, consultezDéfaillances du déploiement du modèle Hugging Face Hub.

Vérification du statut de votre déploiement

Vérifiez si le modèle a été correctement déployé.


kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

Vérifiez que le point de terminaison est correctement créé.


kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

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

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
```

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.

Vérifiez le statut du déploiement de Kubernetes.


kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

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
```
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
```

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Déployez des modèles à l' JumpStart aide de kubectl

Déployez des modèles à partir d'un stockage NVMe local à l'aide de kubectl

Déployez des modèles depuis Amazon S3, Amazon FSx ou Hugging Face Hub à l'aide de kubectl

Conditions préalables

Installation et configuration

Note

Note

Note

Important

Note

Note

Configurez la mise en cache KV et le routage intelligent pour améliorer les performances

Note

Note

Déployez votre modèle depuis Amazon S3, Amazon FSx ou Hugging Face Hub

Vérification du statut de votre déploiement

Gestion de votre déploiement

Note

Nettoyage de vos ressources

Résolution des problèmes