View a markdown version of this page

Déployez des modèles depuis Amazon S3, Amazon FSx ou Hugging Face Hub à l'aide de kubectl - Amazon SageMaker AI
Conditions préalablesInstallation et configurationDéployez votre modèle depuis Amazon S3, Amazon FSx ou Hugging Face HubVérification du statut de votre déploiementGestion de votre déploiement

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 :

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=<region>

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

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

  4. 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="llama-fsx"

    2. Configurez l’ID du système de fichiers Amazon FSx à utiliser.

      export FSX_FILE_SYSTEM_ID="fs-1234abcd"

    3. Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon FSx et un modèle Llama.

      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: $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. Définissez un nom de point de SageMaker terminaison.

      export SAGEMAKER_ENDPOINT_NAME="llama-s3"

    2. Configurez l’emplacement du compartiment Amazon S3 où se trouve le modèle.

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

    3. Voici un exemple de fichier yaml permettant de créer un point de terminaison avec Amazon S3 et un modèle Llama utilisant vLLM comme environnement 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.

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

    2. Définissez un nom de point de SageMaker terminaison.

      export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

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

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

Pour configurer la mise en cache KV et le routage intelligent afin d'améliorer les performances, voir. Configuration de la mise en cache KV et du routage intelligent

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

  2. Déployez votre InferenceEndpointConfig modèle à l'aide de 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

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

    kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

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

    kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

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

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

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

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