Partage via

Résoudre les problèmes liés aux points de terminaison de traitement de lots

  • Article

S’APPLIQUE À :Extension Azure CLI v2 (actuelle)Kit de développement logiciel (SDK) Python azure-ai-ml v2 (version actuelle)

Cet article fournit des conseils pour résoudre les erreurs courantes lors de l’utilisation de points de terminaison de lot pour le scoring par lots dans Azure Machine Learning. Les sections suivantes décrivent comment analyser les journaux de scoring par lots pour identifier les problèmes possibles et les scénarios non pris en charge. Vous pouvez également consulter les solutions recommandées pour résoudre les erreurs courantes.

Obtenir les journaux pour les travaux de scoring par lots

Après avoir appelé un point de terminaison de lot à l’aide d’Azure CLI ou de l’API REST, le travail de scoring par lots s’exécute de façon asynchrone. Il existe deux options pour obtenir les journaux d’un travail de scoring par lot :

  • Option 1 : diffuser en continu les journaux des travaux vers une console locale. Seuls les journaux du dossier azureml-logs sont diffusés en continu.

    Exécutez la commande suivante pour diffuser en continu les journaux générés par le système à votre console. Remplacez le paramètre <job_name> par le nom de votre travail de scoring par lots :

    az ml job stream --name <job_name>

  • Option 2 : afficher les journaux des travaux dans Azure Machine Learning studio.

    Exécutez la commande suivante pour obtenir le lien de travail à utiliser dans le studio. Remplacez le paramètre <job_name> par le nom de votre travail de scoring par lots :

    az ml job show --name <job_name> --query services.Studio.endpoint -o tsv

    1. Ouvrez le lien de travail dans le studio.

    2. Dans le graphique du travail, sélectionnez l’étape de scoring par lots.

    3. Sous l’onglet Sorties + journaux, sélectionnez au moins un journal à examiner.

Examiner les fichiers journaux

Azure Machine Learning fournit plusieurs types de fichiers journaux et d’autres fichiers de données que vous pouvez utiliser pour résoudre les problèmes de votre travail de scoring par lots.

Les deux dossiers de niveau supérieur pour les journaux de scoring par lots sont azureml-logs et logs. Les informations du contrôleur qui lance le script de scoring sont stockées dans le fichier ~/azureml-logs/70_driver_log.txt.

Examiner les informations générales

En raison de la nature distribuée des travaux de scoring par lots, les journaux proviennent de différentes sources, mais deux fichiers combinés fournissent des informations de haut niveau :

Fichier Description
~/logs/job_progress_overview.txt Fournit des informations générales sur le nombre actuel de mini-lots (également appelés tâches) créés et le nombre actuel de mini-lots traités. À mesure que le traitement des mini-lots se termine, le journal enregistre les résultats du travail. Si le travail échoue, le journal présente le message d’erreur en indiquant où débuter la résolution des problèmes.
~/logs/sys/master_role.txt Fournit la vue du nœud principal (également connu sous le nom d’orchestrateur) du travail en cours d’exécution. Ce journal inclut des informations sur la création de tâches, la supervision de la progression et le résultat du travail.

Examiner les données d’arborescence des appels de procédure à la recherche d’erreurs

D’autres fichiers fournissent des informations sur les erreurs possibles dans votre script :

Fichier Description
~/logs/user/error.txt Fournit un résumé des erreurs dans votre script.
~/logs/user/error/* Fournit les traces de la pile complète d’exceptions levées pendant le chargement et l’exécution du script d’entrée.

Examiner les journaux de processus par nœud

Pour une compréhension complète de la façon dont chaque nœud exécute votre script de score, examinez les journaux de processus individuels pour chaque nœud. Les journaux de processus sont stockés dans le dossier ~/logs/sys/node et regroupés par nœuds Worker.

Le dossier contient un sous-dossier <ip_address>/ qui contient un fichier <process_name>.txt avec des informations détaillées sur chaque mini-lot. Le contenu du dossier est mis à jour lorsqu’un Worker sélectionne ou termine le mini-lot. Pour chaque mini-lot, le fichier journal comprend les éléments suivants :

  • L’adresse IP et l’ID du processus (PID) Worker.
  • Le nombre total d’éléments, le nombre d’éléments traités avec succès et le nombre d’élément ayant échoué.
  • L’heure de début, la durée, le temps de traitement et la durée de la méthode d’exécution.

Examiner les vérifications périodiques par nœud

Vous pouvez également voir les résultats de vérifications périodiques de l’utilisation de ressources pour chaque nœud. Les fichiers journaux et d’installation sont stockés dans le dossier ~/logs/perf.

Utilisez le paramètre --resource_monitor_interval pour modifier l’intervalle de vérification en secondes :

  • Utiliser la valeur par défaut : l’intervalle par défaut est de 600 secondes (environ 10 minutes).
  • Arrêter les vérifications : définissez la valeur sur 0 pour arrêter l’exécution des vérifications sur le nœud.

Le dossier contient un sous-dossier <ip_address>/ sur chaque mini-lot. Le contenu du dossier est mis à jour lorsqu’un Worker sélectionne ou termine le mini-lot. Pour chaque mini-lot, le dossier comprend les éléments suivants :

Fichier ou dossier Description
os/ Stocke les informations sur tous les processus en cours d’exécution dans le nœud. Une vérification exécute une commande du système d’exploitation et enregistre le résultat dans un fichier. Sous Linux, la commande est ps. Le dossier contient les éléments suivants :
- %Y%m%d%H : sous-dossier qui contient un ou plusieurs fichiers de vérification de processus. Le nom du sous-dossier est la date et l’heure de création de la vérification (année, mois, jour, heure).
processes_%M : fichier dans le sous-dossier. Le fichier affiche des détails sur la vérification du processus. Le nom de fichier se termine par l’heure de vérification (minute) par rapport à l’heure de création de la vérification.
node_disk_usage.csv Affiche l’utilisation détaillée du disque du nœud.
node_resource_usage.csv Fournit la vue d’ensemble de l’utilisation des ressources du nœud.
processes_resource_usage.csv Fournit une vue d’ensemble de l’utilisation des ressources de chaque processus.

Ajouter la journalisation au script de scoring

Vous pouvez utiliser la journalisation Python dans votre script de scoring. Ces journaux sont stockés dans le fichier logs/user/stdout/<node_id>/process<number>.stdout.txt.

Le code suivant montre comment ajouter la journalisation dans votre script :

import argparse
import logging

# Get logging_level
arg_parser = argparse.ArgumentParser(description="Argument parser.")
arg_parser.add_argument("--logging_level", type=str, help="logging level")
args, unknown_args = arg_parser.parse_known_args()
print(args.logging_level)

# Initialize Python logger
logger = logging.getLogger(__name__)
logger.setLevel(args.logging_level.upper())
logger.info("Info log statement")
logger.debug("Debug log statement")

Résoudre les erreurs courantes

Les sections suivantes décrivent les erreurs courantes qui peuvent se produire pendant le développement et la consommation de points de terminaison de lot, ainsi que les étapes de résolution.

Aucun module nommé azureml

Le déploiement par lots Azure Machine Learning nécessite le package azureml-core dans l’installation.

Message journalisé : « No module named azureml ».

Motif : le package azureml-core semble manquant dans l’installation.

Solution : ajoutez le package azureml-core à votre fichier de dépendances conda.

Aucune sortie dans le fichier de prédictions

Le déploiement par lots s’attend à ce qu’un dossier vide stocke le fichier predictions.csv. Lorsque le déploiement rencontre un fichier existant dans le dossier spécifié, le processus ne remplace pas le contenu du fichier par la nouvelle sortie ou crée un fichier contenant les résultats.

Message journalisé : aucun message spécifique.

Motif : le déploiement par lots ne peut pas remplacer un fichier predictions.csv existant.

Solution : si le processus spécifie un emplacement de dossier de sortie pour les prédictions, vérifiez que le dossier ne contient pas de fichier predictions.csv existant.

Le processus de traitement par lots expire

Le déploiement par lots utilise une valeur timeout pour déterminer le délai pendant lequel le déploiement doit attendre la fin de chaque processus de traitement par lots. Lorsque l’exécution d’un lot dépasse le délai d’expiration spécifié, le déploiement par lots abandonne le processus.

Les processus abandonnés sont retentés jusqu’au nombre maximal de tentatives spécifié dans la valeur max_retries. Si l’erreur d’expiration du délai d’attente se produit lors de chaque nouvelle tentative, le travail de déploiement échoue.

Vous pouvez configurer les propriétés timeout et max_retries de chaque déploiement avec le paramètre retry_settings.

Message journalisé : « No progress update in [nombre] seconds. No progress update in this check. Wait [nombre] seconds since last update. »

Motif : l’exécution du lot dépasse le délai d’attente spécifié et le nombre maximal de tentatives. Cette action correspond à l’échec de la fonction run() dans le script d’entrée.

Solution : augmentez la valeur timeout de votre déploiement. Par défaut, la valeur timeout est 30 et la valeur max_retries est 3. Pour déterminer une valeur timeout appropriée pour votre déploiement, tenez compte du nombre de fichiers à traiter sur chaque lot et de la taille des fichiers. Vous pouvez réduire le nombre de fichiers à traiter et générer des mini-lots de plus petite taille. Cette approche permet une exécution plus rapide.

Exception dans ScriptExecution.StreamAccess.Authentication

Pour que le déploiement par lots réussisse, l’identité managée du cluster de calcul doit avoir l’autorisation de monter le stockage des ressources de données. Lorsque l’identité managée dispose d’autorisations insuffisantes, le script provoque une exception. Cet échec peut également empêcher le montant du stockage des ressources de données.

Message journalisé : « ScriptExecutionException a été provoqué par StreamAccessException.ScriptExecutionException was caused by StreamAccessException. StreamAccessException a été provoqué par AuthenticationException. »

Motif : Le cluster de calcul sur lequel le déploiement s’exécute ne peut pas monter le stockage où se trouve la ressource de données. L’identité managée du calcul ne dispose pas des autorisations nécessaires pour effectuer le montage.

Solution : vérifiez que l’identité managée associée au cluster de calcul sur lequel votre déploiement s’exécute dispose au moins de l’accès Lecteur des données BLOB du stockage au compte de stockage. Seuls les propriétaires de comptes de stockage Azure peuvent modifier le niveau d’accès dans le Portail Azure.

Échec de l’initialisation du jeu de données, impossible de monter le jeu de données

Le processus de déploiement par lots nécessite un stockage monté pour la ressource de données. Lorsque le stockage ne se monte pas, le jeu de données ne peut pas être initialisé.

Message journalisé : « Dataset initialization failed: UserErrorException: Message: Can't mount Dataset(ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None). Source of the dataset is either not accessible or doesn't contain any data. »

Motif : Le cluster de calcul sur lequel le déploiement s’exécute ne peut pas monter le stockage où se trouve la ressource de données. L’identité managée du calcul ne dispose pas des autorisations nécessaires pour effectuer le montage.

Solution : vérifiez que l’identité managée associée au cluster de calcul sur lequel votre déploiement s’exécute dispose au moins de l’accès Lecteur des données BLOB du stockage au compte de stockage. Seuls les propriétaires de comptes de stockage Azure peuvent modifier le niveau d’accès dans le Portail Azure.

dataset_param n’a pas de valeur spécifiée ni de valeur par défaut

Pendant le déploiement par lots, le nœud du jeu de données fait référence au paramètre dataset_param. Pour que le déploiement continue, le paramètre doit avoir une valeur affectée ou une valeur par défaut spécifiée.

Message journalisé : « Data set node [code] references parameter dataset_param, which doesn't have a specified value or a default value. »

Motif : La ressource de données d’entrée fournie au point de terminaison de traitement par lots n’est pas prise en charge.

Solution : vérifiez que le script de déploiement fournit une entrée de données prise en charge pour les points de terminaison de lot.

Échec du programme utilisateur, échec de l’exécution

Pendant l’exécution du script pour le déploiement par lots, si la fonction init() ou run() rencontre une erreur, le programme utilisateur ou l’exécution peut échouer. Vous pouvez consulter les détails de l’erreur dans le fichier journal généré.

Message journalisé : « User program failed with Exception: Run failed. Please check logs for details. You can check logs/readme.txt for the layout of logs. »

Motif : la fonction init() ou run() génère une erreur pendant l’exécution du script de scoring.

Solution : procédez comme suit pour rechercher des détails sur les échecs de fonction :

  1. Dans Azure Machine Learning studio, accédez à l’exécution du travail de déploiement par lots ayant échoué, puis sélectionnez l’onglet Sorties + journaux.

  2. Ouvrez le fichier logs>user>error><node_identifier>>process<number>.txt.

  3. Recherchez le message d’erreur généré par la fonction init() ou run().

ValueError : aucun objet à concaténer

Pour que le déploiement par lots réussisse, chaque fichier d’un mini-lot doit être valide et implémenter un type de fichier pris en charge. N’oubliez pas que les modèles MLflow prennent uniquement en charge un sous-ensemble de types de fichiers. Pour plus d’informations, consultez Considérations relatives au déploiement sur l’inférence par lots.

Message journalisé : « ValueError: No objects to concatenate. »

Motif : tous les fichiers du mini-lot généré sont des types de fichiers endommagés ou non pris en charge.

Solution : procédez comme suit pour rechercher des détails sur les fichiers ayant échoué :

  1. Dans Azure Machine Learning studio, accédez à l’exécution du travail de déploiement par lots ayant échoué, puis sélectionnez l’onglet Sorties + journaux.

  2. Ouvrez le fichier logs>user>stdout><node_identifier>>process<number>.txt.

  3. Recherchez les entrées qui décrivent l’échec d’entrée de fichier, par exemple « ERROR:azureml:Error processing input file ».

Si le type de fichier n’est pas pris en charge, consultez la liste des fichiers pris en charge. Vous devrez peut-être modifier le type de fichier des données d’entrée ou personnaliser le déploiement en fournissant un script de scoring. Pour plus d’informations, consultez Utilisation de modèles MLflow avec un script de scoring.

Aucun mini-lot réussi

Le processus de déploiement par lots nécessite des points de terminaison de lot pour fournir des données au format attendu par la fonction run(). Si les fichiers d’entrée sont endommagés ou incompatibles avec la signature du modèle, la fonction run() ne retourne pas un mini-lot réussi.

Message journalisé : « No succeeded mini batch item returned from run(). Please check 'response: run()' in https://aka.ms/batch-inference-documentation. »

Motif : le point de terminaison de lot n’a pas pu fournir de données à la fonction run() au format attendu. Ce problème peut être dû à des fichiers endommagés en cours de lecture ou à une incompatibilité des données d’entrée avec la signature du modèle (MLflow).

Solution : procédez comme suit pour rechercher des détails sur le mini-lot ayant échoué :

  1. Dans Azure Machine Learning studio, accédez à l’exécution du travail de déploiement par lots ayant échoué, puis sélectionnez l’onglet Sorties + journaux.

  2. Ouvrez le fichier logs>user>stdout><node_identifier>>process<number>.txt.

  3. Recherchez les entrées qui décrivent l’échec du fichier d’entrée pour le mini-lot, par exemple « Error processing input file ». Les détails doivent décrire pourquoi le fichier d’entrée ne peut pas être lu correctement.

Audience ou service non autorisé

Les jetons Microsoft Entra sont émis pour des actions spécifiques qui identifient les utilisateurs autorisés (l’audience), le service et les ressources. Le jeton d’authentification de l’API REST de point de terminaison de lot doit définir le paramètre resource sur https://ml.azure.com.

Message journalisé : aucun message spécifique.

Motif : vous tentez d’appeler l’API REST pour le point de terminaison de lot et le déploiement avec un jeton émis pour un autre public ou service.

Solution : procédez comme suit pour résoudre ce problème d’authentification :

  1. Lorsque vous générez un jeton d’authentification pour l’API REST du point de terminaison de lot, définissez le paramètre resource sur https://ml.azure.com.

    Notez que cette ressource est différente de la ressource que vous utilisez pour gérer le point de terminaison à partir de l’API REST. Toutes les ressources Azure (y compris les points de terminaison de lot) utilisent la ressource https://management.azure.com pour la gestion.

  2. Lorsque vous appelez l’API REST pour un point de terminaison de lot et un déploiement, veillez à utiliser le jeton émis pour l’API REST du point de terminaison de lot et non un jeton émis pour un autre public ou service. Dans chacun des cas, vérifiez que vous utilisez l’URI de ressource approprié.

Si vous souhaitez utiliser l’API de gestion et l’API d’appel de travail en même temps, vous avez besoin de deux jetons. Pour plus d’informations, consultez Autorisation sur les points de terminaison de lot (REST).

Aucun déploiement valide à acheminer

Pour que le déploiement par lots réussisse, le point de terminaison de lot doit avoir au moins un itinéraire de déploiement valide. La méthode standard consiste à définir le déploiement par lots par défaut à l’aide du paramètre defaults.deployment_name.

Message journalisé : « No valid deployments to route to. Please check that the endpoint has at least one deployment with positive weight values or use a deployment specific header to route. »

Motif : le déploiement par lots par défaut n’est pas défini correctement.

Solution : utilisez l’une des méthodes suivantes pour résoudre le problème de routage :

  • Vérifiez que le paramètre defaults.deployment_name définit le déploiement par lots par défaut approprié. Pour plus d’informations, consultez Mettre à jour le déploiement par lots par défaut.

  • Définissez l’itinéraire avec un en-tête spécifique au déploiement.

Limitations et scénarios non pris en charge

Lorsque vous concevez des solutions de déploiement Machine Learning qui s’appuient sur des points de terminaison de lot, gardez à l’esprit que certaines configurations et scénarios ne sont pas pris en charge. Les sections suivantes identifient les espaces de travail et les ressources de calcul non pris en charge et les types non valides pour les fichiers d’entrée.

Configurations d’espace de travail non prises en charge

Les configurations d’espace de travail suivantes ne sont pas prises en charge pour le déploiement par lots :

  • Espaces de travail configurés avec Azure Container Registries avec la fonctionnalité Quarantaine activée
  • Espaces de travail avec des clés gérées par le client

Configurations de calcul non prises en charge

Les configurations de calcul suivantes ne sont pas prises en charge pour le déploiement par lots :

  • Clusters Kubernetes Azure ARC
  • Demande de ressource granulaire (mémoire, processeur virtuel, GPU) pour les clusters Azure Kubernetes (seul le nombre d’instances peut être demandé)

Types de fichiers d’entrée non pris en charge

Les types de fichiers d’entrée suivants ne sont pas pris en charge pour le déploiement par lots :

  • Jeux de données tabulaires (V1)
  • Dossiers et jeux de données de fichiers (V1)
  • MLtable (V2)

Contenu connexe