Obtenir des explications

Ce guide explique comment obtenir des explications sur une ressource Model sur Vertex AI. Vous pouvez obtenir des explications de deux façons:

Explications en ligne:requêtes synchrone adressées à l'API Vertex AI, semblables aux prédictions en ligne qui renvoient des prédictions avec attribution de caractéristiques.
Explications par lots:requêtes asynchrones adressées à l'API Vertex AI qui renvoient des prédictions avec attribution de caractéristiques. Les explications par lots constituent une partie facultative des requêtes de prédiction par lot.

Avant de commencer

Avant d'obtenir des explications, vous devez effectuer les opérations suivantes:

Cette étape varie en fonction du type de modèle de machine learning que vous utilisez:
- Si vous souhaitez obtenir des explications à partir d'un modèle entraîné personnalisé, suivez les instructions de la page Configurer des explications basées sur des exemples ou de la page Configurer des explications basées sur les caractéristiques pour créer un Model compatible avec Vertex Explainable AI.
- Si vous souhaitez obtenir des explications à partir d'un modèle de classification ou de régression tabulaire AutoML, entraînez un modèle AutoML sur un ensemble de données tabulaire. Aucune configuration spécifique n'est requise pour utiliser Vertex Explainable AI. Les explications pour les modèles de prévision ne sont pas prises en charge.
- Si vous souhaitez obtenir des explications à partir d'un modèle de classification d'images AutoML, entraînez un modèle AutoML sur un ensemble de données d'images, puis activez les explications lorsque vous déployez le modèle. Aucune configuration spécifique n'est requise pour utiliser Vertex Explainable AI. Les explications pour les modèles de détection d'objets ne sont pas acceptées.
Pour obtenir des explications en ligne, déployez le Model que vous avez créé à l'étape précédente sur une ressource Endpoint.

Obtenir des explications en ligne

Pour obtenir des explications en ligne, suivez la plupart des étapes que vous effectuez pour obtenir des prédictions en ligne. Cependant, au lieu d'envoyer une requête projects.locations.endpoints.predict à l'API Vertex AI, envoyez une requête projects.locations.endpoints.explain.

Les guides suivants fournissent des instructions détaillées pour préparer et envoyer des requêtes d'explication en ligne:

Pour les modèles de classification d'images AutoML, consultez la page Obtenir des prédictions en ligne à partir de modèles AutoML.
Pour les modèles de classification et de régression tabulaire AutoML, consultez la section Obtenir des prédictions en ligne à partir de modèles AutoML.
Pour les modèles personnalisés,consultez la section Obtenir des prédictions en ligne à partir de modèles personnalisés.

Obtenir des explications par lots

Seules les explications par lots basées sur les caractéristiques sont acceptées. Vous ne pouvez pas obtenir d'explications par lot basées sur des exemples.

Pour obtenir des explications par lots, définissez le champ generateExplanation sur true lorsque vous créez une tâche de prédiction par lot.

Pour obtenir des instructions détaillées sur la préparation et la création de tâches de prédiction par lot, consultez la section Obtenir des prédictions par lot.

Obtenir des explications localement dans les notebooks gérés par l'utilisateur Vertex AI Workbench

Dans les notebooks gérés par l'utilisateur Vertex AI Workbench, vous pouvez générer des explications pour votre modèle personnalisé en exécutant Vertex Explainable AI dans le noyau ou l'environnement d'exécution local de votre notebook, sans déployer le modèle sur Vertex AI. Les explications locales vous permettent d'essayer différents paramètres de Vertex Explainable AI, sans ajuster votre déploiement de modèles Vertex AI pour chaque modification. Cela permet d'évaluer plus facilement et plus rapidement l'impact de l'utilisation de différentes références, en essayant différents paramètres de visualisation pour vos explications, ou en ajustant le nombre d'étapes ou de chemins utilisés pour votre algorithme.

Les explications locales ne sont disponibles que dans les notebooks gérés par l'utilisateur. Par conséquent, cette fonctionnalité ne fonctionne pas dans les notebooks Jupyter exécutés en dehors de notebooks gérés par l'utilisateur.

Pour générer des explications localement dans une instance de notebook gérée par l'utilisateur, procédez comme suit :

Créez une instance de notebooks gérés par l'utilisateur
Démarrez l'environnement JupyterLab à partir de votre instance de notebook gérée par l'utilisateur, puis créez ou importez un notebook.
Enregistrez l'artefact de modèle dans l'environnement local de votre notebook ou dans un bucket Cloud Storage.
Générez et enregistrez des métadonnées pour décrire votre modèle et configurer votre requête d'explications.

Obtenir des explications simultanées

Explainable AI est compatible avec les explications simultanées. Les explications simultanées vous permettent de demander des explications basées sur des caractéristiques et sur des exemples à partir du même point de terminaison de modèle déployé, sans avoir à déployer votre modèle séparément pour chaque méthode d'explication.

Pour obtenir des explications simultanées, importez votre modèle et configurez des explications basées sur des exemples ou basées sur des caractéristiques. Déployez ensuite votre modèle comme d'habitude.

Une fois le modèle déployé, vous pouvez demander les explications configurées comme d'habitude. En outre, vous pouvez demander des explications simultanées en spécifiant concurrent_explanation_spec_override.

Tenez compte des points suivants lorsque vous utilisez des explications simultanées :

Les explications simultanées ne sont disponibles que dans la version v1beta1 de l'API. Si vous utilisez le SDK Vertex pour Python, vous devez utiliser le modèle preview pour utiliser des explications simultanées.
Vous ne pouvez pas demander d'explications basées sur des exemples après avoir effectué un déploiement à l'aide d'explications basées sur les caractéristiques. Si vous souhaitez obtenir des explications basées sur des exemples et des explications basées sur des caractéristiques, déployez votre modèle en utilisant des explications basées sur des exemples et demandez des explications basées sur les caractéristiques en utilisant le champ d'explication simultanée.
Les explications par lots ne sont pas compatibles avec les explications simultanées. Les explications en ligne sont le seul moyen d'utiliser cette fonctionnalité.

Utiliser le SDK Explainable AI dans les notebooks gérés par l'utilisateur

Le SDK Explainable AI est préinstallé dans les instances de notebook gérées par l'utilisateur. Dans votre notebook, vous pouvez utiliser le SDK Explainable AI pour enregistrer l'artefact de votre modèle et identifier automatiquement les métadonnées des entrées et des sorties de votre modèle pour la requête d'explications. Vous pouvez également spécifier d'autres paramètres pour configurer votre requête d'explications, puis visualiser les résultats de l'explication.

Vous pouvez enregistrer des modèles et des métadonnées dans l'environnement local de votre notebook, ou bien dans un bucket Cloud Storage. Si vous utilisez TensorFlow, vous pouvez utiliser la méthode save_model_with_metadata() pour déduire les entrées et les sorties de votre modèle, et enregistrer ces métadonnées d'explications avec votre modèle.

Ensuite, chargez le modèle dans le SDK Explainable AI à l'aide de load_model_from_local_path(). Si nécessaire, vous pouvez ajuster la configuration de l'algorithme Vertex Explainable AI spécifique. Par exemple, vous pouvez modifier le nombre de chemins à utiliser pour l'échantillonnage des valeurs de Shapley ou le nombre d'étapes à utiliser pour la méthode des gradients intégrés ou la méthode XRAI.

Enfin, appelez explain() avec des instances de données, et visualisez les attributions de caractéristiques.

Vous pouvez utiliser l'exemple de code suivant pour obtenir des explications locales sur un modèle TensorFlow 2 au sein d'une instance de notebooks gérée par l'utilisateur :

# This sample code only works within a user-managed notebooks instance.
import explainable_ai_sdk
from explainable_ai_sdk.metadata.tf.v2 import SavedModelMetadataBuilder

metadata_and_model_builder = SavedModelMetadataBuilder('LOCAL_PATH_TO_MODEL')
metadata_and_model_builder.save_model_with_metadata('LOCAL_PATH_TO_SAVED_MODEL_ARTIFACT')

# Load the model and adjust the configuration for Explainable AI parameters
num_paths = 20
model_artifact_with_metadata = explainable_ai_sdk.load_model_from_local_path(
    'LOCAL_PATH_TO_SAVED_MODEL_ARTIFACT',
    explainable_ai_sdk.SampledShapleyConfig(num_paths))

# Explainable AI supports generating explanations for multiple predictions
instances = [{feature_a: 10, feature_2: 100,...}, ... ]
explanations = model_artifact_with_metadata.explain(instances)
explanations[0].visualize_attributions()

Pour en savoir plus sur le SDK Explainable AI, y compris sur les différentes configurations et paramètres, consultez le fichier config.py du SDK sur GitHub. Apprenez-en plus sur les notebooks Vertex AI Workbench gérés par l'utilisateur.

Dépannage

Cette section décrit les étapes de dépannage qui peuvent vous être utiles si vous rencontrez des problèmes lors de l'obtention d'explications.

Erreur : index de liste en dehors de la plage

Si le message d'erreur suivant s'affiche lorsque vous demandez des explications :

"error": "Explainability failed with exception: listindex out of range"

Assurez-vous de ne pas transmettre un tableau vide dans un champ qui attend un tableau d'objets. Par exemple, si field1 accepte un tableau d'objets, le corps de requête suivant peut entraîner une erreur :

{
  "instances": [
    {
      "field1": [],
    }
  ]
}

Assurez-vous plutôt que le tableau n'est pas vide, par exemple :

{
  "instances": [
    {
      "field1": [
        {}
      ],
    }
  ]
}

Étapes suivantes

Sur la base des explications que vous recevez, découvrez comment ajuster votre Model pour améliorer les explications.
Testez un exemple de notebook montrant le fonctionnement de Vertex Explainable AI sur des données tabulaires ou des données d'image.