Configurer des tâches de traitement Amazon SageMaker Clarify à des fins d'équité et d'explicabilité - Amazon SageMaker

Configurer des tâches de traitement Amazon SageMaker Clarify à des fins d'équité et d'explicabilité

Cette rubrique décrit la configuration d'une tâche de traitement Amazon SageMaker Clarify permettant de calculer des métriques de biais et des attributions de fonctionnalités à des fins d'explicabilité. La tâche est mise en œuvre à l'aide d'une image de conteneur SageMaker Clarify spécialisée. Des instructions sont fournies sur la façon de trouver et télécharger l'une de ces images de conteneur. Une présentation du fonctionnement de SageMaker Clarify est esquissée. Les paramètres nécessaires à la configuration de la tâche de traitement et du type d'analyse sont décrits. Les prérequis sont décrits, et des conseils sur les ressources de calcul utilisées par la tâche de traitement SageMaker Clarify sont fournis.

Prerequisites

Avant de commencer, vérifiez que les prérequis suivants sont remplis :

  • Fourniture d'un jeu de données d'entrée sous forme de fichiers tabulaires au format CSV ou JSONLines. Le jeu de données d'entrée doit inclure une colonne d'étiquette pour l'analyse de biais. Le jeu de données doit être préparé pour le machine learning avec tout le pré-traitement nécessaire déjà accompli, comme le nettoyage de données ou l'ingénierie des fonctionnalités.

  • Fourniture d'un artefact de modèle prenant en charge le format de fichier CSV ou JSONLines comme l'une de ses entrées de type de contenu. Concernant les métriques de biais post-entraînement et l'explicabilité, nous utilisons le jeu de données pour faire des inférences avec l'artefact du modèle. Chaque ligne, moins la colonne étiquette, doit être prête à être utilisée comme charge utile pour les inférences.

  • Pour créer des tâches de traitement à l'aide de l'image du conteneur SageMaker, vous avez besoin des éléments suivants :

    • L'isolement réseau doit être désactivé pour la tâche de traitement.

    • Si le modèle se trouve dans un VPC, la tâche de traitement doit se trouver dans le même VPC que le modèle.

    • L'utilisateur/rôle IAM de l'appelant doit disposer des autorisations pour les API SageMaker. Nous vous recommandons d'utiliser la politique gérée “arn:aws:iam::aws:policy/AmazonSageMakerFullAccess”.

Mise en route avec un conteneur SageMaker Clarify

Amazon SageMaker fournit des images de conteneur SageMaker Clarify prédéfinies qui incluent les bibliothèques et autres dépendances nécessaires pour calculer les métriques de biais et les attributions de fonctionnalités à des fins d'explicabilité. Cette image a été activée pour exécuter SageMaker Traiter des données dans votre compte.

Les URI d'image pour les conteneurs se présentent sous la forme suivante :

<ACCOUNT_ID>.dkr.ecr.<REGION_NAME>.amazonaws.com/sagemaker-clarify-processing:1.0

Par exemple :

205585389593.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0

Le tableau ci-après répertorie les adresses par région AWS.

Images Docker pour des tâches de traitement Clarify
Région Adresse de l'image
us-east-1 205585389593.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
us-east-2 211330385671.dkr.ecr.us-east-2.amazonaws.com/sagemaker-clarify-processing:1.0
us-west-1 740489534195.dkr.ecr.us-west-1.amazonaws.com/sagemaker-clarify-processing:1.0
us-west-2 306415355426.dkr.ecr.us-west-2.amazonaws.com/sagemaker-clarify-processing:1.0
ap us-east-1 098760798382.dkr.ecr.ap-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
ap-south-1 452307495513.dkr.ecr.ap-south-1.amazonaws.com/sagemaker-clarify-processing:1.0
ap-northeast-2 263625296855.dkr.ecr.ap-northeast-2.amazonaws.com/sagemaker-clarify-processing:1.0
ap-southeast-1 834264404009.dkr.ecr.ap-southeast-1.amazonaws.com/sagemaker-clarify-processing:1.0
ap-southeast-2 007051062584.dkr.ecr.ap-southeast-2.amazonaws.com/sagemaker-clarify-processing:1.0
ap-northeast-1 377024640650.dkr.ecr.ap-northeast-1.amazonaws.com/sagemaker-clarify-processing:1.0
ca-central-1 675030665977.dkr.ecr.ca-central-1.amazonaws.com/sagemaker-clarify-processing:1.0
eu-central-1 017069133835.dkr.ecr.eu-central-1.amazonaws.com/sagemaker-clarify-processing:1.0
eu-west-1 131013547314.dkr.ecr.eu-west-1.amazonaws.com/sagemaker-clarify-processing:1.0
eu-west-2 440796970383.dkr.ecr.eu-west-2.amazonaws.com/sagemaker-clarify-processing:1.0
eu-west-3 341593696636.dkr.ecr.eu-west-3.amazonaws.com/sagemaker-clarify-processing:1.0
eu-north-1 763603941244.dkr.ecr.eu-north-1.amazonaws.com/sagemaker-clarify-processing:1.0
me-south-1 835444307964.dkr.ecr.me-south-1.amazonaws.com/sagemaker-clarify-processing:1.0
sa-east-1 520018980103.dkr.ecr.sa-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
af-south-1 811711786498.dkr.ecr.af-south-1.amazonaws.com/sagemaker-clarify-processing:1.0
eu-south-1 638885417683.dkr.ecr.eu-south-1.amazonaws.com/sagemaker-clarify-processing:1.0
cn-north-1 122526803553.dkr.ecr.cn-north-1.amazonaws.com.cn/sagemaker-clarify-processing:1.0
cn-northwest-1 122578899357.dkr.ecr.cn-northwest-1.amazonaws.com.cn/sagemaker-clarify-processing:1.0

Fonctionnement

Une tâche de traitement SageMaker utilise le conteneur SageMaker Clarify à plusieurs étapes du cycle de vie du flux de machine learning. Vous pouvez utiliser le conteneur SageMaker Clarify avec vos jeux de données et modèles pour calculer les types d'analyse suivants :

  • métriques de biais pré-entraînement

  • métriques de biais post-entraînement

  • valeurs SHAP à des fins d'explicabilité

Vous pouvez contrôler les analyses qui seront calculées, lors de la configuration de la tâche de traitement. Pour les métriques de biais de pré-entraînement, vous devez fournir le jeu de données. Vous pouvez calculer les métriques de biais post-entraînement et l'explicabilité consécutivement à l'entraînement de votre modèle, en fournissant le jeu de données et le nom du modèle. Vous devez configurer les paramètres nécessaires sous la forme d'un fichier de configuration JSON et le fournir en tant qu'entrée pour la tâche de traitement.

Une fois la tâche de traitement terminée, le résultat des analyses est enregistré à l'emplacement de sortie spécifié dans les paramètres ProcessingOutput de la tâche de traitement. Vous pouvez ensuite le télécharger à partir de là et afficher les sorties, ou afficher les résultats dans Studio si vous y avez exécuté un bloc-notes.

Afin de calculer les métriques de biais post-entraînement et les valeurs SHAP, le calcul doit obtenir des inférences pour le nom de modèle fourni. Pour ce faire, la tâche de traitement crée un point de terminaison éphémère avec le nom du modèle, appelé shadow endpoint (point de terminaison fantôme). Une fois les calculs terminés, la tâche de traitement supprime le point de terminaison fantôme.

À un niveau élevé, la tâche de traitement effectue les actions suivantes :

  1. Validation des entrées et des paramètres.

  2. Création du point de terminaison fantôme.

  3. Calcul des métriques de biais pré-entraînement.

  4. Calcul des métriques de biais post-entraînement.

  5. Calcul des attributions de fonctions locales et mondiales.

  6. Suppression du point de terminaison fantôme.

  7. Génération des fichiers de sortie.

Configurer les paramètres d'entrée et de sortie d'un conteneur de tâche de traitement

La tâche de traitement exige que vous spécifiez les paramètres d'entrée suivants : un fichier de jeu de données avec le nom d'entrée "dataset" en tant qu'objet S3 ou préfixe, et un fichier de configuration d'analyse avec le nom d'entrée "analysis_config" en tant qu'objet S3. La tâche exige également un paramètre de sortie : l'emplacement de sortie en tant que préfixe S3.

Vous pouvez créer et exécuter une tâche de traitement avec l'API SageMaker CreateProcessingJob à l'aide du kit SDK AWS, de la CLI ou du kit SDK Python SageMaker.

À l'aide du kit SDK Python SageMaker, créez un Processor avec l'URI d'image de conteneur SageMaker Clarify :

from sagemaker import clarify clarify_processor = clarify.SageMakerClarifyProcessor(role=role, instance_count=1, instance_type='ml.c5.xlarge', max_runtime_in_seconds=1200, volume_size_in_gb=100)

Ensuite, vous devez également fournir les paramètres d'entrée et de sortie pour le SageMakerClarifyProcessor. Si vous fournissez le "dataset_uri", l'entrée du jeu de données est facultative.

dataset_path = "s3://my_bucket/my_folder/train.csv" analysis_config_path = "s3://my_bucket/my_folder/analysis_config.json" analysis_result_path = "s3://my_bucket/my_folder/output" analysis_config_input = ProcessingInput( input_name="analysis_config", source=analysis_config_path, destination="/opt/ml/processing/input/config", s3_data_type="S3Prefix", s3_input_mode="File", s3_compression_type="None") dataset_input = ProcessingInput( input_name="dataset", source=dataset_path, destination="/opt/ml/processing/input/data", s3_data_type="S3Prefix", s3_input_mode="File", s3_compression_type="None") analysis_result_output = ProcessingOutput( source="/opt/ml/processing/output", destination=analysis_result_path, output_name="analysis_result", s3_upload_mode="EndOfJob")

Configurer l'analyse

Les paramètres de configuration de l'analyse doivent être fournis dans un fichier JSON nommé « analysis_config.json ». Le chemin doit être fourni dans le paramètre ProcessingInput nommé « analysis_config ». Vous trouverez ci-dessous des exemples de fichiers de configuration d'analyse. Dans ce fichier de configuration JSON, vous spécifiez les paramètres suivants :

  • "version" - (Facultatif) Version de schéma du fichier de configuration. La dernière version prise en charge est utilisée si elle n'est pas fournie.

  • "dataset_type" - Format du jeu de données. Les valeurs valides sont "text/csv" pour CSV et "application/jsonlines" pour JSONLines.

  • "dataset_uri" - (Facultatif) URI de préfixe/objet S3 de jeu de données (si elle n'est pas fournie en tant que ProcessingInput). S'il s'agit d'un préfixe, la tâche de traitement collecte tous les fichiers S3 de façon récursive sous le préfixe.

  • "headers" - (Facultatif) Liste des noms de colonnes dans le jeu de données. Si le dataset_type est "application/jsonlines" et que "label" est spécifié, alors le dernier en-tête doit être l'en-tête de la colonne étiquette.

  • "label" - (Facultatif) Attribut cible du modèle à utiliser pour les métriques de bias spécifié en tant que nom de colonne ou index si le format du jeu de données est CSV, ou JSONPath si le format du jeu de données est JSONLines.

  • "probability_threshold" - (Facultatif) Valeur flottante pour indiquer le seuil de sélection de l'étiquette binaire dans le cas d'une classification binaire. La valeur par défaut est 0,5.

  • "features" - (Facultatif) JSONPath pour localiser les colonnes de fonctions pour les métriques de biais si le format du jeu de données est JSONLines.

  • "label_values_or_threshold" - (Facultatif) Liste des valeurs d'étiquette ou des seuils pour indiquer les résultats positifs utilisés pour les métriques de biais.

  • "facet" - (Facultatif) Liste des fonctions qui sont des attributs sensibles, appelées facettes, à utiliser pour les métriques de biais sous forme de paires afin d'inclure les éléments suivants :

    • "name_or_index" - Nom ou index de la colonne facette.

    • "value_or_threshold" - (Facultatif) Liste des valeurs ou des seuils que la colonne facette peut prendre, et qui indique le groupe sensible, c'est-à-dire le groupe utilisé pour mesurer le biais. Si elles ne sont pas fournies, les métriques de biais sont calculées comme un groupe « vs all » pour chaque valeur unique. Si la colonne facette est numérique, cette valeur de seuil sert de limite inférieure pour sélectionner le groupe sensible.

  • "group_variable" - (Facultatif) Nom de colonne ou index pour indiquer la variable de groupe à utiliser pour la métrique de biais Disparité démographique conditionnelle.

  • "methods" - Liste des méthodes et de leurs paramètres pour les analyses et les rapports. Si une section est omise, elle n'est pas calculée.

    • "pre_training_bias" - (Facultatif) Section sur les métriques de biais de pré-entraînement.

      • "methods" - Liste des métriques de pré-entraînement à calculer.

    • "post_training_bias" - (Facultatif) Section sur les métriques de biais post-entraînement.

      • "methods" - Liste des métriques de post-entraînement à calculer.

    • "shap" - (Facultatif) Section sur le calcul de la valeur SHAP.

      • "baseline" - (Facultatif) Liste de lignes (au moins une) ou URI d'objet S3 à utiliser comme jeu de données de référence (également appelé jeu de données d'arrière-plan) dans l'algorithme SHAP du noyau. Le format doit être identique au format du jeu de données. Chaque ligne doit contenir uniquement les colonnes/valeurs de fonctions et omettre les colonnes/valeurs d'étiquette

      • "num_samples" - Nombre d'échantillons à utiliser dans l'algorithme SHAP du noyau. Ce nombre détermine la taille du jeu de données synthétique généré pour calculer les valeurs SHAP.

      • "agg_method" - Méthode d'agrégation pour les valeurs SHAP globales. Les valeurs valides sont les suivantes :

        • "mean_abs" - Moyenne des valeurs SHAP absolues pour toutes les instances.

        • "median" - Médiane des valeurs SHAP pour toutes les instances.

        • "mean_sq" - Moyenne des valeurs SHAP au carré pour toutes les instances.

      • "use_logit" - (Facultatif) Valeur booléenne pour indiquer si la fonction logit doit être appliquée aux prédictions du modèle. La valeur par défaut est « FAUX ». Si « use_logit » est "true", les valeurs SHAP ont alors des unités log-odds.

      • "save_local_shap_values" - (Facultatif) Valeur booléenne pour indiquer si les valeurs SHAP locales doivent être enregistrées à l'emplacement en sortie. La valeur par défaut est false.

  • "predictor" - (Facultatif) Section sur les paramètres du modèle, obligatoire si les sections "shap" et "post_training_bias" sont présentes.

    • "model_name" - Nom de modèle (tel que créé par l'API CreateModel avec le mode conteneur en tant que SingleModel).

    • "instance_type" - Type d'instance pour le point de terminaison fantôme.

    • "initial_instance_count" - Nombre d'instances pour le point de terminaison fantôme.

    • "content_type" - (Facultatif) Format d'entrée de modèle à utiliser pour obtenir des inférences avec le point de terminaison fantôme. Les valeurs valides sont "text/csv" pour CSV et "application/jsonlines". La valeur par défaut est identique au format du jeu de données.

    • "accept_type" - (Facultatif) Modèle output (sortie) à utiliser pour obtenir des inférences avec le point de terminaison fantôme. Les valeurs valides sont "text/csv" pour CSV et "application/jsonlines". La valeur par défaut est la même que content_type.

    • "label" - (Facultatif) Emplacement d'index ou de JSONPath dans la sortie du modèle pour l'attribut cible à utiliser pour les métriques de biais. Dans le cas accept_type CSV, si la sortie du modèle n'est pas fournie, supposez qu'elle est une valeur numérique unique correspondant au score ou à la probabilité.

    • "probability" - (Facultatif) Emplacement d'index ou de JSONPath dans la sortie du modèle pour les probabilités ou les scores à utiliser pour l'explicabilité. Par exemple, si la sortie du modèle est JSONLines avec une liste d'étiquettes et de probabilités, alors, pour les méthodes de biais, l'étiquette qui correspond à la probabilité maximale est sélectionnée pour les calculs de biais. Pour la méthode d'explicabilité, toutes les probabilités sont actuellement expliquées.

    • "label_headers" - (Facultatif) Liste de valeurs prises par "label" dans le jeu de données, et qui décrivent la valeur d'étiquette à laquelle correspond chacun des scores renvoyés par le point de terminaison du modèle. Elle sert à extraire la valeur d'étiquette avec le score le plus élevé comme étiquette prédite pour les calculs de biais.

    • "content_template" - (Facultatif) Chaîne de modèle à utiliser pour créer l'entrée de modèle à partir d'instances du jeu de données. Elle est utilisée uniquement si "content_type" est "application/jsonlines". Le modèle doit avoir un seul espace réservé, $features, qui est remplacé par une liste des fonctions lors de l'exécution. Par exemple, étant donné "content_template":"{\"myfeatures\":$features}", si une instance (sans étiquette) est 1,2,3, l'entrée du modèle devient alors JSOnline '{"myfeatures":[1,2,3]}'.

  • "report" - (Facultatif) Section sur les paramètres du rapport. Un rapport est généré si cette section est présente.

    • "name" - (Facultatif) Préfixe de nom de fichier pour le bloc-notes de rapport et le fichier PDF. Le nom par défaut est "report".

    • "title" - (Facultatif) Chaîne de titre pour le bloc-notes de rapport et le fichier PDF. Le titre par défaut est "SageMaker Analysis Report".

Exemple de fichier JSON de configuration d'analyse pour un jeu de données CSV

{ "dataset_type": "text/csv", "headers": [ "feature_0", "feature_1", "feature_2", "feature_3", "target" ], "label": "target", "label_values_or_threshold": [1], "probability_threshold" : 0.7, "facet": [ { "name_or_index" : "feature_1", "value_or_threshold": [1] }, { "name_or_index" : "feature_2", "value_or_threshold": [0.7] } ], "group_variable": "feature_3", "methods": { "shap": { "baseline": [ [ "yes", 3, 0.9, 1 ] ], "num_samples": 1000, "agg_method": "mean", "use_logit": true, "save_local_shap_values": true }, "pre_training_bias": { "methods": "all" }, "post_training_bias": { "methods": "all" }, "report": { "name": "report", "title": "Analysis Report" } }, "predictor": { "model_name": "my_model", "instance_type": "ml.m5.xlarge", "initial_instance_count": 1, "content_type": "text/csv", "accept_type": "text/csv", "label": 0, "probability": 1 } }

La sortie du modèle CSV est la suivante :

Current,"[0.028986845165491104, 0.8253824710845947, 0.028993206098675728, 0.02898673340678215, 0.029557107016444206, 0.0290389321744442, 0.02905467338860035]"

La configuration correspondante du prédicteur est la suivante :

"predictor": { ..., "accept_type": "text/csv", "label": 0, "probability": 1, ... }

Exemple de fichier JSON de configuration d'analyse pour un jeu de données JSONLines

{ "dataset_type": "application/jsonlines", "dataset_uri": "s3://my_bucket/my_folder/dataset.jsonl", "headers": ["Label", "Feature1", "Feature2"], "label": "data.label", "features": "data.features.values", "facet":[ { "name_or_index": "Feature1", "value_or_threshold": [1,5] }, { "name_or_index": "Feature2", "value_or_threshold": [2,6] } ], "methods": { "shap": { "baseline": [ {"data":{"features":{"values":[9,10]},"label":0}}, {"data":{"features":{"values":[11,12]},"label":1}} ] } }, "predictor": { "model_name": "my_jsonl_model", "instance_type": "ml.m5.xlarge", "initial_instance_count": 1 } }

Le jeu de données en tant que préfixe S3 est le suivant :

"dataset_uri": "s3://my_bucket/my_folder"

Le jeu de données en tant qu'objet S3 est le suivant :

"dataset_uri": "s3://my_bucket/my_folder/train.csv"

La ligne de base en tant qu'objet S3 est la suivante :

"baseline": "s3://my_bucket/my_folder/baseline.csv"

La sortie du modèle en tant que JsonLines est la suivante :

{"predicted_label": "Current", "score": "[0.028986845165491104, 0.8253824710845947, 0.028993206098675728, 0.02898673340678215, 0.029557107016444206, 0.0290389321744442, 0.02905467338860035]"}

La configuration correspondante du prédicteur est la suivante :

"predictor": { ..., "accept_type": "application/jsonlines", "label": "predicted_label", "probability": "score", ... }