Résolution des problèmes de déploiement de modèle distant

Découvrez comment dépanner, résoudre ou contourner les erreurs courantes que vous pouvez rencontrer lors du déploiement d’un modèle sur Azure Container Instances (ACI) et Azure Kubernetes Service (AKS) à l’aide d’Azure Machine Learning.

Prérequis

• Un abonnement Azure. Essayez la version gratuite ou payante d’Azure Machine Learning.

• Le Kit de développement logiciel (SDK) Azure Machine Learning.

• Interface de ligne de commande Azure.

• L’Extension CLI v1 pour Azure Machine Learning.

  Important

  Certaines des commandes Azure CLI de cet article utilisent l’extension azure-cli-ml, ou v1, pour Azure Machine Learning. La prise en charge de l’extension v1 se termine le 30 septembre 2025. Vous pourrez installer et utiliser l’extension v1 jusqu’à cette date.

  Nous vous recommandons de passer à l’extension ml, ou v2, avant le 30 septembre 2025. Pour plus d’informations sur l’extension v2, consultez Extension Azure ML CLI et le SDK Python v2.

Étapes pour le déploiement Docker des modèles Machine Learning

Lorsque vous déployez un modèle vers un calcul non local dans Azure Machine Learning, les événements suivants se produisent :

1. Le Dockerfile que vous avez spécifié dans votre objet Environments dans votre InferenceConfig est envoyé au cloud, ainsi que le contenu de votre répertoire source.
2. Si une image construite précédemment n'est pas disponible dans votre registre de conteneurs, une nouvelle image Docker est construite dans le nuage et stockée dans le registre de conteneurs par défaut de votre espace de travail.
3. L’image Docker de votre registre de conteneurs est téléchargée sur votre cible de calcul.
4. Le magasin d’objets blob par défaut de votre espace de travail est monté sur votre cible de calcul, ce qui vous donne accès aux modèles inscrits.
5. Votre serveur web est initialisé en exécutant la fonction init() de votre script d’entrée.
6. Lorsque votre modèle déployé reçoit une requête, votre fonction run() la gère.

La principale différence lors d’un déploiement local est que l’image conteneur est générée sur votre ordinateur local, ce qui explique pourquoi Docker doit être installé pour un déploiement local.

La compréhension de ces étapes doit vous aider à comprendre où se produisent les erreurs.

Obtenir les journaux de déploiement

La première étape du débogage des erreurs consiste à obtenir vos journaux de déploiement. Tout d’abord, suivez les instructions ici pour vous connecter à votre espace de travail.

az ml service get-logs --verbose --workspace-name <my workspace name> --name <service name>

print(ws.webservices)

# Choose the webservice you are interested in

from azureml.core import Webservice

service = Webservice(ws, '<insert name of webservice>')
print(service.get_logs())

Déboguer en local

Si vous rencontrez des problèmes lors du déploiement d'un modèle sur ACI ou AKS, déployez-le en tant que service web local. L’utilisation d’un service web local facilite la résolution des problèmes. Pour résoudre les problèmes d’un déploiement localement, consultez cet article.

Serveur HTTP d’inférence Azure Machine Learning

Le serveur d’inférence local vous permet de déboguer rapidement votre script d’entrée (score.py). Si un bogue affecte le script de scoring sous-jacent, le serveur ne peut pas initialiser ou traiter le modèle. Au lieu de cela, il lève une exception et là où les problèmes se sont produits. Apprenez-en davantage sur le serveur HTTP d’inférence Azure Machine Learning

1. Installez le package azureml-inference-server-http à partir du flux pypi :

   python -m pip install azureml-inference-server-http
   

2. Démarrez le serveur et définissez score.py comme script d’entrée :

   azmlinfsrv --entry_script score.py
   

3. Envoyez une requête de scoring au serveur à l’aide de curl :

   curl -p 127.0.0.1:5001/score
   

Impossible de planifier le conteneur

Lorsque vous déployez un service sur une cible de calcul Azure Kubernetes Service, Azure Machine Learning tente de planifier le service avec la quantité de ressources demandée. Si, au bout de cinq minutes, aucun nœud n'est disponible dans le cluster avec suffisamment de ressources, le déploiement échoue. Le message d'échec est le suivant : Couldn't Schedule because the kubernetes cluster didn't have available resources after trying for 00:05:00. Vous pouvez corriger cette erreur en ajoutant des nœuds supplémentaires, en modifiant la référence SKU de vos nœuds ou en changeant les besoins en ressources de votre service.

Le message d’erreur indique généralement la ressource insuffisante. Par exemple, un message d’erreur qui indique 0/3 nodes are available: 3 Insufficient nvidia.com/gpu signifie que le service réclame des GPU et qu’il y a trois nœuds dans le cluster qui n’ont pas de GPU disponibles. Pour résoudre cette erreur, vous pouvez ajouter d’autres nœuds si vous utilisez une référence SKU de GPU, basculer sur une référence SKU compatible GPU sinon ou modifier votre environnement de sorte qu’il ne réclame pas de GPU.

Échec du lancement du service

Une fois l’image correctement générée, le système tente de démarrer un conteneur à l’aide de la configuration du déploiement. Dans le cadre du processus de démarrage du conteneur, la fonction init() dans votre script de scoring est appelée par le système. Si la fonction init() comprend des exceptions non interceptées, l’erreur CrashLoopBackOff apparaît peut-être dans le message d’erreur.

Utilisez les informations de l’article Examiner le journal Docker.

Échec du lancement du conteneur azureml-fe-aci

Lors du déploiement d’un service sur une cible de calcul Azure Container Instance, Azure Machine Learning tente de créer un conteneur front-end qui porte le nom azureml-fe-aci pour la demande d’inférence. Si azureml-fe-aci plante, vous pouvez voir les journaux en exécutant az container logs --name MyContainerGroup --resource-group MyResourceGroup --subscription MySubscription --container-name azureml-fe-aci. Vous pouvez suivre le message d’erreur dans les journaux pour résoudre le problème.

L’échec le plus courant de azureml-fe-aci est que la clé ou le certificat SSL fourni n’est pas valide.

Échec de la fonction : get_model_path()

Souvent, dans la fonction init() du script de scoring, la fonction Model.get_model_path() est appelée pour rechercher un fichier de modèle ou un dossier de fichiers de modèle dans le conteneur. Si un fichier ou le dossier de modèle est introuvable, la fonction échoue. Le moyen le plus simple de déboguer cette erreur consiste à exécuter le code Python ci-dessous dans l’interpréteur de commandes du conteneur :

S’APPLIQUE À : SDK Python azureml v1

from azureml.core.model import Model
import logging
logging.basicConfig(level=logging.DEBUG)
print(Model.get_model_path(model_name='my-best-model'))

Cet exemple affiche le chemin local (relatif à /var/azureml-app) sur le conteneur où votre script de scoring est censé trouver le fichier de modèle ou le dossier. Vous pouvez ensuite vérifier si le fichier ou dossier se trouve effectivement à l’emplacement indiqué.

La définition du niveau de journalisation sur DEBUG peut entraîner l’enregistrement d’informations supplémentaires, qui peuvent être utiles pour identifier l’échec.

Échec de la fonction : run(input_data)

Si le service est déployé avec succès, mais qu’il plante quand vous publiez des données sur le point de terminaison de scoring, vous pouvez ajouter une instruction d’interception d’erreur dans votre fonction run(input_data) afin qu’elle retourne un message d’erreur détaillé. Par exemple :

def run(input_data):
    try:
        data = json.loads(input_data)['data']
        data = np.array(data)
        result = model.predict(data)
        return json.dumps({"result": result.tolist()})
    except Exception as e:
        result = str(e)
        # return error message back to the client
        return json.dumps({"error": result})

Remarque : Retournez les messages d’erreur à partir de l’appel run(input_data) exclusivement à des fins de débogage. Pour des raisons de sécurité, vous ne devez pas renvoyer des messages d’erreur de cette façon dans un environnement de production.

Code d’état HTTP 502

Un code d’état 502 indique que le service a levé une exception ou s’est planté dans la méthode run() du fichier score.py. Utilisez les informations de cet article pour déboguer le fichier.

Code d’état HTTP 503

Les déploiements du service Azure Kubernetes prennent en charge la mise à l'échelle automatique, qui permet d'ajouter des répliques pour supporter une charge supplémentaire. L'Autoscaler est conçu pour gérer des changements progressifs de charge. Si vous recevez des pics importants de demandes par seconde, les clients peuvent recevoir un code d’état HTTP 503. Même si la mise à l'échelle automatique réagit rapidement, il faut beaucoup de temps à AKS pour créer d'autres conteneurs.

La décision d’effectuer un scale-up/down est basée sur l’utilisation des réplicas de conteneur actuels. Le nombre de réplicas occupés (qui traitent une demande) divisé par le nombre total de réplicas actuels donne l’utilisation en cours. Si ce nombre dépasse autoscale_target_utilization, d’autres réplicas sont créés. S’il est inférieur, des réplicas sont supprimés. La décision d’ajouter des réplicas est hâtive et rapide (environ 1 seconde). La décision de supprimer des réplicas est prudente (environ 1 minute). Par défaut, l'utilisation de la cible de mise à l'échelle automatique est définie sur 70 % , ce qui signifie que le service peut gérer les pics de demandes par seconde (RPS) jusqu'à 30 % .

Il existe deux mesures permettant d’empêcher les codes d’état 503 :

• Modifiez le niveau d’utilisation auquel la mise à l’échelle automatique crée de nouveaux réplicas. Vous pouvez ajuster la cible de l’utilisation en définissant autoscale_target_utilization sur une valeur inférieure.

  Important

  Cette modification n’entraîne pas la création de réplicas plus rapidement. Ils sont créés à un seuil d’utilisation inférieur. Au lieu d’attendre jusqu’à ce que le service soit utilisé à 70 %, la modification de la valeur sur 30 % provoque la création de réplicas lors d’une utilisation à 30 %.

  Si le service web utilise déjà les réplicas maximum actuels et que des codes d’état 503 subsistent, augmentez la valeur autoscale_max_replicas pour augmenter le nombre maximal de réplicas.

• Modifiez le nombre minimal de réplicas. L’augmentation du nombre minimal de réplicas offre un plus grand pool pour gérer les pics entrants.

  Pour augmenter le nombre minimal de réplicas, définissez autoscale_min_replicas sur une valeur plus élevée. Vous pouvez calculer les réplicas requis en utilisant le code suivant, en remplaçant les valeurs par des valeurs spécifiques de votre projet :

  from math import ceil
  # target requests per second
  targetRps = 20
  # time to process the request (in seconds)
  reqTime = 10
  # Maximum requests per container
  maxReqPerContainer = 1
  # target_utilization. 70% in this example
  targetUtilization = .7
  
  concurrentRequests = targetRps * reqTime / targetUtilization
  
  # Number of container replicas
  replicas = ceil(concurrentRequests / maxReqPerContainer)
  

  Notes

  Si vous recevez des pics de demande supérieurs au nouveau nombre minimal pouvant être géré par les réplicas, il se peut que des codes d’état 503 réapparaissent. Par exemple, si le trafic vers votre service augmente, vous devrez peut-être augmenter le nombre minimal de réplicas.

Pour plus d’informations sur la configuration de autoscale_target_utilization, autoscale_max_replicas, et autoscale_min_replicas, consultez les informations de référence sur le module AksWebservice.

Code d’état HTTP 504

Un code d’état 504 indique que la requête a expiré. Le délai d’expiration par défaut est de une minute.

Vous pouvez augmenter le délai d’expiration ou essayer d’accélérer le service en modifiant le fichier score.py pour supprimer les appels inutiles. Si ces actions ne corrigent pas le problème, utilisez les informations de cet article pour déboguer le fichier score.py. Le code peut être dans un état sans réponse ou une boucle infinie.

Autres messages d’erreur

Effectuez ces actions pour les erreurs suivantes :

Débogage avancé

Vous pouvez être amené à déboguer interactivement le code Python contenu dans votre modèle de déploiement. Par exemple, si le script d'entrée échoue et que la raison ne peut être déterminée par une journalisation supplémentaire. À l’aide de Visual Studio Code et de debugpy, vous pouvez attacher au code qui s’exécute dans le conteneur Docker.

Pour plus d’informations, consultez le guide de débogage interactif dans VS Code.

Forum utilisateurs sur le déploiement de modèle

Étapes suivantes

Pour en savoir plus sur le déploiement :

• Où et comment effectuer un déploiement
• Comment exécuter et déboguer des expériences localement