Fichiers de configuration d’analyse

Dans le fichier de configuration JSON, vous pouvez spécifier les paramètres suivants.

Les exemples suivants montrent comment configurer l'analyse des biais et de l'explicabilité pour un jeu de données tabulaire au format CSV. Dans ces exemples, le jeu de données entrant comporte quatre colonnes de fonctionnalités et une colonne d'étiquettes binaires, Target. Le contenu du jeu de données est le suivant. Une valeur d’étiquette de 1 indique un résultat positif. Le jeu de données est fourni à la tâche SageMaker Clarify par l’entrée de traitement dataset.

"Target","Age","Gender","Income","Occupation"
0,25,0,2850,2
1,36,0,6585,0
1,22,1,1759,1
0,48,0,3446,1
...

Les sections suivantes montrent comment calculer les métriques de biais de pré-entraînement et de post-entraînement, les valeurs SHAP et les graphiques de dépendance partielle (PDP) indiquant l'importance des fonctionnalités pour un jeu de données au format CSV.

Calcul de toutes les métriques de biais de pré-entraînement

Cet exemple de configuration montre comment mesurer si l'exemple de jeu de données précédent est favorablement biaisé en faveur des échantillons avec une valeur de Gender égale à 0. La configuration d'analyse suivante indique à la tâche de traitement SageMaker Clarify de calculer toutes les métriques de biais de pré-entraînement pour le jeu de données.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

Calcul de toutes les métriques de biais de post-entraînement

Vous pouvez calculer les métriques de biais de pré-entraînement avant l'entraînement. Toutefois, vous devez disposer d'un modèle entraîné pour calculer les métriques de biais de post-entraînement. L'exemple de sortie suivant provient d'un modèle de classification binaire qui fournit en sortie des données au format CSV. Dans cet exemple de sortie, chaque ligne contient deux colonnes. La première colonne contient l'étiquette prédite et la deuxième colonne contient la valeur de probabilité pour cette étiquette.

0,0.028986845165491
1,0.825382471084594
...

L’exemple de configuration suivant indique à la tâche de traitement SageMaker Clarify de calculer tous les indicateurs de biais possibles à l’aide du jeu de données et des prédictions issus de la sortie du modèle. Dans cet exemple, le modèle est déployé sur un point de terminaison SageMaker AI your_endpoint.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "label": 0
    }
}

Calcul des valeurs SHAP

L'exemple de configuration d'analyse suivant indique à la tâche de calculer les valeurs SHAP désignant la colonne Target comme des étiquettes et toutes les autres colonnes comme des fonctionnalités.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

Dans cet exemple, le paramètre SHAP baseline est omis et la valeur du paramètre num_clusters est 1. Cela indique au processeur SageMaker Clarify de calculer un seul échantillon de référence SHAP. Dans cet exemple, la probabilité est définie sur 1. Cela indique à la tâche de traitement SageMaker Clarify d'extraire le score de probabilité de la deuxième colonne de la sortie du modèle (en utilisant une indexation basée sur zéro).

Calcul de graphiques de dépendance partielle (PDP)

L'exemple suivant montre comment visualiser l'importance de la fonctionnalité Income dans le rapport d'analyse à l'aide des graphiques PDP. Le paramètre report indique à la tâche de traitement SageMaker Clarify de générer un rapport. Une fois la tâche terminée, le rapport généré est enregistré en tant que report.pdf à l'emplacement analysis_result. Le paramètre grid_resolution divise la plage de valeurs des caractéristiques en 10 compartiments. Ensemble, les paramètres spécifiés dans l'exemple suivant indiquent à la tâche de traitement SageMaker Clarify de générer un rapport contenant un graphique PDP pour Income avec 10 segments sur l'axe X. L’axe Y montre l’impact marginal de Income sur les prédictions.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "pdp": {
            "features": ["Income"],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    },
}

Calcul simultané des métriques de biais et de l'importance des fonctionnalités

Vous pouvez combiner toutes les méthodes des exemples de configuration précédents dans un fichier de configuration d'analyse unique et les calculer toutes à l'aide d'une seule tâche. L'exemple suivant montre une configuration d'analyse avec toutes les étapes combinées.

Dans cet exemple, le paramètre probability est défini sur 1 pour indiquer que les probabilités sont contenues dans la deuxième colonne (en utilisant une indexation basée sur zéro). Toutefois, comme l'analyse des biais nécessite une étiquette prédite, le paramètre probability_threshold est défini sur 0.5 pour convertir le score de probabilité en étiquette binaire. Dans cet exemple, le paramètre top_k_features de la méthode pdp des graphiques de dépendance partielle est défini sur 2. Cela indique à la tâche de traitement SageMaker Clarify de calculer les graphiques de dépendance partielle (PDP) pour les 2 fonctionnalités principales dotées des valeurs SHAP globales les plus élevées.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

Au lieu de déployer le modèle sur un point de terminaison, vous pouvez fournir le nom de votre modèle SageMaker AI à la tâche de traitement SageMaker Clarify à l’aide du paramètre model_name. L’exemple suivant montre comment spécifier un modèle nommé your_model. La tâche de traitement SageMaker Clarify créera un point de terminaison miroir à l'aide de la configuration.

{
     ...
    "predictor": {
        "model_name": "your_model",
        "initial_instance_count": 1,
        "instance_type": "ml.m5.large",
        "probability": 1
    }
}

Les exemples suivants montrent comment configurer l’analyse des biais et l’analyse de l’explicabilité pour un jeu de données tabulaire au format JSON Lines. Dans ces exemples, le jeu de données entrant contient les mêmes données que dans la section précédente, mais elles sont au format dense JSON Lines de SageMaker AI. Chaque ligne est un objet JSON valide. La clé "Features" pointe sur un tableau de valeurs de fonctionnalités, et la clé "Label" pointe sur l'étiquette de vérité terrain. Le jeu de données est fourni à la tâche SageMaker Clarify par l’entrée de traitement "dataset". Pour plus d’informations sur les lignes JSON, consultez Format de demande JSONLINES.

{"Features":[25,0,2850,2],"Label":0}
{"Features":[36,0,6585,0],"Label":1}
{"Features":[22,1,1759,1],"Label":1}
{"Features":[48,0,3446,1],"Label":0}
...

Les sections suivantes montrent comment calculer les indicateurs de biais de pré-entraînement et de post-entraînement, les valeurs SHAP et les graphiques de dépendance partielle (PDP) indiquant l’importance des caractéristiques pour un jeu de données au format JSON Lines.

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

Spécifiez l'étiquette, les fonctionnalités, le format et les méthodes pour mesurer les métriques de biais de pré-entraînement pour une valeur Gender de 0. Dans l'exemple suivant, le paramètre headers fournit d'abord les noms des fonctionnalités. Le nom d'étiquette est fourni en dernier. Par convention, le dernier en-tête est l'en-tête d'étiquette.

Le paramètre features est défini sur l'expression JMESPath "Features" afin que la tâche de traitement SageMaker Clarify puisse extraire le tableau de fonctionnalités de chaque enregistrement. Le paramètre label est défini sur l'expression JMESPath "Label" afin que la tâche de traitement SageMaker Clarify puisse extraire l'étiquette de vérité terrain de chaque enregistrement. Utilisez un nom de facette pour spécifier l'attribut sensible, comme suit.

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

Calcul de toutes les métriques de biais

Vous devez disposer d'un modèle entraîné pour calculer les métriques de biais de post-entraînement. L'exemple suivant provient d'un modèle de classification binaire qui fournit en sortie des données JSON Lines dans le format de l'exemple. Chaque ligne de la sortie du modèle est un objet JSON valide. La clé predicted_label pointe vers l’étiquette prédite et la clé probability pointe vers la valeur de probabilité.

{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...

Vous pouvez déployer le modèle sur un point de terminaison SageMaker AI nommé your_endpoint. L’exemple de configuration d’analyse suivant indique à la tâche de traitement SageMaker Clarify de calculer tous les indicateurs de biais possibles pour le jeu de données et le modèle. Dans cet exemple, les paramètres content_type et accept_type ne sont pas définis. Par conséquent, ils sont définis automatiquement sur la valeur du paramètre dataset_type, qui est application/jsonlines. La tâche de traitement SageMaker Clarify utilise le paramètre content_template pour composer l'entrée du modèle, en remplaçant l'espace réservé $features par un tableau de fonctionnalités.

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "label": "predicted_label"
    }
}

Calcul des valeurs SHAP

Comme l'analyse SHAP ne nécessite pas d'étiquette de vérité terrain, le paramètre label est omis. Dans cet exemple, le paramètre headers est également omis. Par conséquent, la tâche de traitement SageMaker Clarify doit générer des espaces réservés en utilisant des noms génériques tels que column_0 ou column_1 pour les en-têtes de fonctionnalités, et label0 pour un en-tête d'étiquette. Vous pouvez spécifier des valeurs pour headers et pour label afin d'améliorer la lisibilité du résultat de l'analyse. Le paramètre de probabilité étant défini sur l'expression JMESpath probability, la valeur de probabilité sera extraite de la sortie du modèle. Voici un exemple de calcul des valeurs SHAP.

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

Calcul de graphiques de dépendance partielle (PDP)

L'exemple suivant montre comment visualiser l'importance de "Income" (revenus) sur un graphique PDP. Dans cet exemple, les en-têtes des fonctionnalités ne sont pas fournis. Par conséquent, le paramètre features de la méthode pdp doit utiliser un index basé sur zéro pour faire référence à l’emplacement de la colonne de caractéristiques. Le paramètre grid_resolution divise la plage de valeurs des caractéristiques en 10 compartiments. Ensemble, les paramètres de cet exemple indiquent à la tâche de traitement SageMaker Clarify de générer un rapport contenant un graphique PDP pour Income avec 10 segments sur l'axe X. L'axe Y montre l'impact marginal de Income sur les prédictions.

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

Calcul simultané des métriques de biais et de l'importance des fonctionnalités

Vous pouvez combiner toutes les méthodes précédentes dans un fichier de configuration d'analyse unique et les calculer toutes à l'aide d'une seule tâche. L'exemple suivant montre une configuration d'analyse avec toutes les étapes combinées. Dans cet exemple, le paramètre probability est défini. Cependant, comme l'analyse des biais nécessite une étiquette prédite, le paramètre probability_threshold est défini sur 0.5 pour convertir le score de probabilité en étiquette binaire. Dans cet exemple, le paramètre top_k_features de la méthode pdp est défini sur 2. Cela indique à la tâche de traitement SageMaker Clarify de calculer les graphiques PDP pour les 2 fonctionnalités principales dotées des valeurs SHAP globales les plus élevées.

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

Les exemples suivants montrent comment configurer l’analyse des biais et de l’explicabilité pour un jeu de données tabulaire au format JSON. Dans ces exemples, le jeu de données entrant contient les mêmes données que dans la section précédente, mais elles sont au format dense JSON de SageMaker AI. Pour plus d’informations sur les lignes JSON, consultez Format de demande JSONLINES.

L’ensemble de la demande en entrée est une demande JSON valide où la structure externe est une liste et chaque élément correspond aux données d’un enregistrement. Dans chaque enregistrement, la clé Features pointe sur un tableau de valeurs de fonctionnalités et la clé Label pointe sur l'étiquette de vérité terrain. Le jeu de données est fourni à la tâche SageMaker Clarify par l'entrée de traitement dataset.

[
    {"Features":[25,0,2850,2],"Label":0},
    {"Features":[36,0,6585,0],"Label":1},
    {"Features":[22,1,1759,1],"Label":1},
    {"Features":[48,0,3446,1],"Label":0},
    ...
]

Les sections suivantes montrent comment calculer les métriques de biais de pré-entraînement et de post-entraînement, les valeurs SHAP et les graphiques de dépendance partielle (PDP) qui indiquent l'importance des fonctionnalités pour un jeu de données au format JSON Lines.

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

Spécifiez l'étiquette, les fonctionnalités, le format et les méthodes pour mesurer les métriques de biais de pré-entraînement pour une valeur Gender de 0. Dans l'exemple suivant, le paramètre headers fournit d'abord les noms des fonctionnalités. Le nom d'étiquette est fourni en dernier. Pour les jeux de données JSON, le dernier en-tête est l'en-tête d'étiquette.

Le paramètre features est défini sur l'expression JMESpath qui extrait un tableau ou une matrice 2D. Chaque ligne de cette matrice doit contenir la liste de Features pour chaque enregistrement. Le paramètre label est défini sur l'expression JMESPath qui extrait la liste des étiquettes de vérité terrain. Chaque élément de cette liste doit contenir l'étiquette d'un enregistrement.

Utilisez un nom de facette pour spécifier l'attribut sensible, comme suit.

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

Calcul de toutes les métriques de biais

Vous devez disposer d'un modèle entraîné pour calculer les métriques de biais de post-entraînement. L'exemple de code suivant provient d'un modèle de classification binaire qui fournit en sortie des données JSON dans le format de l'exemple. Dans cet exemple, chaque élément sous predictions est la sortie de prédiction d'un enregistrement. Cet exemple de code contient la clé predicted_label, qui pointe vers l’étiquette prédite, et la clé probability pointe vers la valeur de probabilité.

{
    "predictions": [
        {"predicted_label":0,"probability":0.028986845165491},
        {"predicted_label":1,"probability":0.825382471084594},
        ...
    ]
}

Vous pouvez déployer le modèle sur un point de terminaison SageMaker AI nommé your_endpoint.

Dans l’exemple suivant, les paramètres content_type et accept_type ne sont pas définis. Par conséquent, content_type et accept_type sont définis automatiquement pour utiliser la valeur du paramètre dataset_type, qui est application/json. La tâche de traitement SageMaker Clarify utilise ensuite le paramètre content_template pour composer l'entrée du modèle.

Dans l'exemple suivant, l'entrée du modèle est composée en remplaçant l'espace réservé $records par un tableau d'enregistrements. Le paramètre record_template compose ensuite la structure JSON de chaque enregistrement et remplace l'espace réservé $features par le tableau de fonctionnalités de chaque enregistrement.

L'exemple de configuration d'analyse suivant indique à la tâche de traitement SageMaker Clarify de calculer toutes les métriques de biais possibles pour le jeu de données et le modèle.

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "label": "predictions[*].predicted_label"
    }
}

Calcul des valeurs SHAP

Vous n'avez pas besoin de spécifier d'étiquette pour l'analyse SHAP. Dans l'exemple suivant, le paramètre headers n'est pas spécifié. Par conséquent, la tâche de traitement SageMaker Clarify génère des espaces réservés en utilisant des noms génériques tels que column_0 ou column_1 pour les en-têtes de fonctionnalités, et label0 pour un en-tête d'étiquette. Vous pouvez spécifier des valeurs pour headers et pour label afin d'améliorer la lisibilité du résultat de l'analyse.

Dans l'exemple de configuration suivant, le paramètre de probabilité est défini sur une expression JMESpath qui extrait les probabilités de chaque prédiction pour chaque enregistrement. Voici un exemple de calcul des valeurs SHAP.

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

Calcul de graphiques de dépendance partielle (PDP)

L'exemple suivant vous montre comment visualiser l'importance d'une fonctionnalité dans les graphiques PDP. Dans cet exemple, les en-têtes des fonctionnalités ne sont pas fournis. Par conséquent, le paramètre features de la méthode pdp doit utiliser un index basé sur zéro pour faire référence à l'emplacement de la colonne de fonctionnalités. Le paramètre grid_resolution divise la plage des valeurs des fonctionnalités en 10 compartiments.

Ensemble, les paramètres de l'exemple suivant indiquent à la tâche de traitement SageMaker Clarify de générer un rapport contenant un graphique PDP pour Income avec 10 segments sur l'axe X. L'axe Y montre l'impact marginal de Income sur les prédictions.

L'exemple de configuration suivant montre comment visualiser l'importance des revenus (Income) sur les graphiques PDP.

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

Calcul simultané des métriques de biais et de l'importance des fonctionnalités

Vous pouvez combiner toutes les méthodes de configuration précédentes dans un fichier de configuration d'analyse unique et les calculer toutes à l'aide d'une seule tâche. L'exemple suivant montre une configuration d'analyse avec toutes les étapes combinées.

Dans cet exemple, le paramètre probability est défini. Comme l'analyse des biais nécessite une étiquette prédite, le paramètre probability_threshold est défini sur 0.5 et est utilisé pour convertir le score de probabilité en étiquette binaire. Dans cet exemple, le paramètre top_k_features de la méthode pdp est défini sur 2. Cela indique à la tâche de traitement SageMaker Clarify de calculer les graphiques PDP pour les 2 fonctionnalités principales dotées des valeurs SHAP globales les plus élevées.

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

L'exemple suivant montre un fichier de configuration d'analyse permettant de calculer l'importance des fonctionnalités pour le traitement du langage naturel (NLP). Dans cet exemple, le jeu de données entrant est un jeu de données tabulaire au format CSV, avec une seule colonne d'étiquettes binaires et deux colonnes de fonctionnalités, comme suit. Le jeu de données est fourni à la tâche SageMaker Clarify par le paramètre d’entrée de traitement dataset.

0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...

Dans cet exemple, un modèle de classification binaire a été entraîné sur le jeu de données précédent. Le modèle accepte les données CSV et produit un score unique compris entre 0 et 1, comme suit.

0.491656005382537
0.569582343101501
...

Le modèle est utilisé pour créer un modèle SageMaker AI nommé « your_model ». La configuration d’analyse suivante montre comment exécuter une analyse d’explicabilité par jeton à l’aide du modèle et du jeu de données. Le paramètre text_config active l'analyse d'explicabilité du NLP. Le paramètre granularity indique que l’analyse doit analyser les jetons.

En anglais, chaque jeton est un mot. L'exemple suivant montre également comment fournir une instance "baseline" SHAP sur place en utilisant une note ("Rating") moyenne de 4. Un jeton de masque spécial "[MASK]" est utilisé pour remplacer un jeton (mot) dans les commentaires ("Comments"). Cet exemple utilise également un type d'instance de point de terminaison GPU pour accélérer l'inférence.

{
    "dataset_type": "text/csv",
    "headers": ["Target","Rating","Comments"]
    "label": "Target",
    "methods": {
        "shap": {
            "text_config": {
                "granularity": "token",
                "language": "english"
            }
            "baseline": [[4,"[MASK]"]],
        }
    },
    "predictor": {
        "model_name": "your_nlp_model",
        "initial_instance_count": 1,
        "instance_type": "ml.g4dn.xlarge"
    }
}

L'exemple suivant montre un fichier de configuration d'analyse calculant l'importance des fonctionnalités pour la vision par ordinateur. Dans cet exemple, le jeu de données en entrée est constitué d'images JPEG. Le jeu de données est fourni à la tâche SageMaker Clarify par le paramètre d'entrée de traitement dataset. L'exemple montre comment configurer une analyse d'explicabilité à l'aide d'un modèle de classification d'image SageMaker. Dans cet exemple, un modèle nommé your_cv_ic_model a été entraîné pour classer les animaux sur les images JPEG en entrée.

{
    "dataset_type": "application/x-image",
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "IMAGE_CLASSIFICATION",
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_ic_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

Pour plus d’informations sur la classification des images, consultez Classification des images – MXNet.

Dans cet exemple, un modèle de détection d’objet SageMaker AI, your_cv_od_model, est entraîné sur les mêmes images JPEG afin d’identifier les animaux qui y figurent. L’exemple suivant montre comment configurer une analyse d’explicabilité pour le modèle de détection d’objet.

{
    "dataset_type": "application/x-image",
    "probability_threshold": 0.5,
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "OBJECT_DETECTION",
                 "max_objects": 3,
                "context": 1.0,
                "iou_threshold": 0.5,
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_od_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

L’exemple suivant montre un fichier de configuration d’analyse pour le calcul de l’importance des caractéristiques pour une série temporelle (TS). Dans cet exemple, le jeu de données entrant est un jeu de données de séries temporelles au format JSON avec un jeu de caractéristiques de covariables dynamiques et statiques. Le jeu de données est fourni à la tâche SageMaker Clarify par le paramètre d’entrée de traitement dataset_uri du jeu de données.

[
    {
        "item_id": "item1",
        "timestamp": "2019-09-11",
        "target_value": 47650.3,
        "dynamic_feature_1": 0.4576,
        "dynamic_feature_2": 0.2164,
        "dynamic_feature_3": 0.1906,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item1",
        "timestamp": "2019-09-12",
        "target_value": 47380.3,
        "dynamic_feature_1": 0.4839,
        "dynamic_feature_2": 0.2274,
        "dynamic_feature_3": 0.1889,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item2",
        "timestamp": "2020-04-23",
        "target_value": 35601.4,
        "dynamic_feature_1": 0.5264,
        "dynamic_feature_2": 0.3838,
        "dynamic_feature_3": 0.4604,
        "static_feature_1": 1,
        "static_feature_2": 2
    },
]

Les sections suivantes expliquent comment calculer les attributions de caractéristiques pour un modèle de prévision à l’aide de l’algorithme de valeurs de Shapley asymétriques pour un jeu de données JSON.

Calcul des explications pour les modèles de prévision de séries temporelles

L’exemple de configuration d’analyse suivant affiche les options utilisées par la tâche pour calculer les explications pour les modèles de prévision des séries temporelles.

{
    'dataset_type': 'application/json',
    'dataset_uri': 'DATASET_URI',
    'methods': {
        'asymmetric_shapley_value': {
            'baseline': {
                "related_time_series": "zero",
                "static_covariates": {
                    "item1": [0, 0], "item2": [0, 0]
                },
                "target_time_series": "zero"
            },
            'direction': 'chronological',
            'granularity': 'fine_grained',
            'num_samples': 10
        },
        'report': {'name': 'report', 'title': 'Analysis Report'}
    },
    'predictor': {
        'accept_type': 'application/json',
        'content_template': '{"instances": $records}',
        'endpoint_name': 'ENDPOINT_NAME', 
        'content_type': 'application/json',              
        'record_template': '{
            "start": $start_time, 
            "target": $target_time_series, 
            "dynamic_feat": $related_time_series, 
            "cat": $static_covariates
        }',
        'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
    },
    'time_series_data_config': {
        'dataset_format': 'timestamp_records',
        'item_id': '[].item_id',
        'related_time_series': ['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
        'static_covariates': ['[].static_feature_1', '[].static_feature_2'],
        'target_time_series': '[].target_value',
        'timestamp': '[].timestamp'
    }
}

Configuration de l’explicabilité des séries temporelles

L’exemple précédent utilise asymmetric_shapley_value dans methods pour définir les arguments d’explicabilité des séries temporelles tels que la référence, la direction, la granularité et le nombre d’échantillons. Les valeurs de référence sont définies pour les trois types de données : séries temporelles associées, covariables statiques et séries temporelles cibles. Ces champs indiquent au processeur SageMaker Clarify de calculer les attributions de caractéristiques pour un seul élément à la fois.

Configuration du prédicteur

Vous pouvez contrôler entièrement la structure de données utiles envoyée par le processeur SageMaker Clarify à l’aide de la syntaxe JMESPath. Dans l’exemple précédent, la configuration predictor indique à Clarify d’agréger les enregistrements dans '{"instances": $records}', chaque enregistrement étant défini avec les arguments donnés pour record_template dans l’exemple. Notez que $start_time, $target_time_series, $related_time_series et $static_covariates sont des jetons internes utilisés pour mapper les valeurs du jeu de données aux valeurs des demandes de point de terminaison.

De même, l’attribut forecast dans time_series_predictor_config est utilisé pour extraire la prévision du modèle à partir de la réponse du point de terminaison. Par exemple, la réponse par lots de votre point de terminaison peut être la suivante :

{
    "predictions": [
        {"mean": [13.4, 3.6, 1.0]}, 
        {"mean": [23.0, 4.7, 3.0]}, 
        {"mean": [3.4, 5.6, 2.0]}
    ]
}

Supposons que vous spécifiez la configuration du prédicteur de série temporelle suivante :

'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}

La valeur de prévision est analysée comme suit :

[
    [13.4, 3.6],
    [23.0, 4.7],
    [3.4, 5.6]
]

Configuration des données

Utilisez l’attribut time_series_data_config pour indiquer au processeur SageMaker Clarify d’analyser correctement les données à partir des données transmises sous forme d’URI S3 dans dataset_uri.