Utiliser AI Explanations avec AI Platform Prediction

Ce guide général explique comment déployer et utiliser un modèle sur AI Platform Prediction à l'aide d'AI Explanations.

Avant de commencer

Vous devez effectuer plusieurs opérations avant de pouvoir entraîner et déployer un modèle dans AI Platform :

• Configurer l'environnement de développement local
• Configurer un projet GCP avec la facturation et les API nécessaires activées.
• Créer un bucket Cloud Storage pour stocker le package d'entraînement et le modèle entraîné

Pour configurer votre projet GCP, suivez les instructions fournies dans les exemples de notebooks.

Enregistrer un modèle

TensorFlow 1.15, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10 et 2.11 sont compatibles. Utilisez tf.saved_model.save pour enregistrer des modèles dans TensorFlow 2.11, mais ne l'utilisez pas pour TensorFlow 1.15.

Découvrez comment enregistrer des modèles à utiliser avec AI Explanations et comment utiliser le SDK Explainable AI.

Fichier de métadonnées d'explications

Avant de déployer votre modèle, vous devez envoyer un fichier de métadonnées contenant les informations associées à vos entrées, vos sorties et vos valeurs de référence du modèle afin qu'AI Explanations fournisse des explications sur les parties correctes de votre modèle.

Nous vous recommandons d'utiliser le SDK Explainable AI pour découvrir automatiquement les entrées et les sorties de votre modèle. Dans la plupart des cas, cet outil permet de gagner du temps et de l'énergie, car le SDK Explainable AI crée et importe le fichier de métadonnées des explications pour vous.

Créer le fichier de métadonnées d'explications manuellement

Dans le cas d'un cas d'utilisation avancé, il peut être préférable de spécifier manuellement les entrées et les sorties du modèle. Pour créer manuellement votre fichier de métadonnées d'explications, procédez comme suit :

• Identifiez les noms des Tensors d'entrée et de sortie pour lesquels vous souhaitez obtenir des explications. Consultez la section ci-dessous sur la localisation des noms de Tensors d'entrée et de sortie manuellement. Découvrez comment identifier vos Tensors d'entrée et de sortie.
• Créez une référence appropriée et spécifiez-la dans input_baselines.
• Spécifiez "tensorflow" pour votre framework.
• Nommez le fichier explanation_metadata.json.
• Importez le fichier explanation_metadata.json dans le même bucket Cloud Storage servant à stocker votre modèle SavedModel.

L'exemple suivant montre à quoi ressemble un fichier explanation_metadata.json :

{
    "inputs": {
      "data": {
        "input_tensor_name": "YOUR_INPUT_TENSOR_NAME"
        "input_baselines": [0]
      }
    },
    "outputs": {
      "duration": {
        "output_tensor_name": "YOUR_OUTPUT_TENSOR_NAME"
      }
    },
    "framework": "tensorflow"
}

Dans cet exemple, "data" et "duration" sont des noms explicites pour les Tensors d'entrée et de sortie que vous pouvez attribuer dans le processus de création et d'entraînement du modèle. Les noms de Tensors d'entrée et de sortie réels sont au format name:index. Par exemple, x:0 ou Placeholder:0.

Pour input_baselines, vous pouvez commencer par spécifier une valeur de référence. Dans cet exemple, [0] représente une image entièrement noire. Vous pouvez spécifier plusieurs références pour fournir des informations supplémentaires. En savoir plus sur l'ajustement des valeurs de référence.

Localiser manuellement les noms des Tensors d'entrée et de sortie

Dans la plupart des cas, vous pouvez utiliser le SDK Explainable AI afin de générer les entrées et les sorties de votre modèle. Vous ne devez rechercher manuellement les noms des Tensors d'entrée et de sortie que si vous utilisez un modèle TensorFlow 1.15 pré-entraîné.

La meilleure façon de trouver les noms des Tensors d'entrée et de sortie dépend des types de vos données d'entrée et de sortie, ainsi que de la manière dont vous créez votre modèle. Pour une explication plus détaillée de chaque cas, et des exemples, consultez le guide sur la l'[interprétation des entrées et des sorties][interprétation des entrées et des sorties].

Déployer des modèles et des versions

AI Platform Prediction organise vos modèles entraînés à l'aide de ressources de modèle et de version. Un modèle AI Platform Prediction est un conteneur pour les versions de votre modèle de machine learning.

Pour déployer un modèle, vous créez une ressource de modèle dans AI Platform Prediction, vous créez ensuite une version de ce modèle, puis vous associez la version du modèle au fichier de modèle stocké dans Cloud Storage.

Créer une ressource de modèle

AI Platform Prediction organise les différentes versions de votre modèle à l'aide de ressources de modèle.

Créez une ressource de modèle pour les versions de votre modèle. Dans la commande Google Cloud CLI suivante, remplacez MODEL_NAME par le nom souhaité pour votre modèle. Le nom du modèle doit commencer par une lettre et ne contenir que des lettres, des chiffres et des traits de soulignement.

Pour pouvoir utiliser AI Explanations, vous devez créer votre modèle sur un point de terminaison régional.

gcloud ai-platform models create MODEL_NAME \
  --region us-central1

Reportez-vous à la page API du modèle AI Platform Prediction pour plus d'informations.

Créer une version de modèle

Vous êtes prêt à créer une version de modèle avec le modèle entraîné que vous avez importé tout à l'heure dans Cloud Storage. Lorsque vous créez une version, spécifiez les paramètres suivants :

• name : doit être unique dans le modèle AI Platform Prediction.
• deploymentUri : chemin d'accès à votre répertoire SavedModel dans Cloud Storage.
• framework (obligatoire) : tensorflow uniquement
• runtimeVersion: utilisez l'une des versions d'exécution suivantes compatibles avec AI Explanations: 1.15, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10 et 2.11.
• pythonVersion : utilisez "3.7" pour les versions d'exécution 1.15 et ultérieures.
• machineType (obligatoire) : type de machine virtuelle utilisé par AI Platform Prediction pour les nœuds qui diffusent des prédictions et des explications. Sélectionnez un type de machine compatible avec AI Explanations.
• explanation-method : type de méthode d'attribution des caractéristiques à utiliser : "Échantillonnage des valeurs de Shapley", "Gradients intégrés" ou "XRAI".
• Chemins ou étapes : utilisez --num-paths pour l'échantillonnage des valeurs de Shapley et --num-integral-steps pour les gradients intégrés ou XRAI.

Pour en savoir plus sur chacun de ces paramètres, consultez la page sur l'API AI Platform Training and Prediction.

1. Définissez des variables d'environnement pour stocker le chemin d'accès au répertoire Cloud Storage dans lequel se trouve le modèle SavedModel, le nom du modèle, le nom de la version et le framework de votre choix.

   MODEL=your_model_name
   MODEL_DIR="gs://your_bucket_name/"
   VERSION=your_version_name
   FRAMEWORK=tensorflow
   

2. Créez la version :

   EXPLAIN_METHOD="integrated-gradients"
   gcloud beta ai-platform versions create $VERSION \
   --model $MODEL \
   --origin $MODEL_DIR \
   --runtime-version 1.15 \
   --framework $FRAMEWORK \
   --python-version 3.7 \
   --machine-type n1-standard-4 \
   --explanation-method $EXPLAIN_METHOD \
   --num-integral-steps 25 \
   --region us-central1
   

   La création de la version prend quelques minutes. Une fois la version prête, vous devez obtenir le résultat suivant :

   Creating version (this might take a few minutes)......done.

3. Vérifiez l'état du déploiement de votre modèle et assurez-vous qu'il est correctement déployé :

   gcloud ai-platform versions describe $VERSION_NAME \
     --model $MODEL_NAME \
     --region us-central1
   

   Vérifiez que l'état est READY. Le résultat doit ressembler à ce qui suit :

   createTime: '2018-02-28T16:30:45Z'
   deploymentUri: gs://your_bucket_name
   framework: TENSORFLOW
   machineType: n1-standard-4
   name: projects/your_project_id/models/your_model_name/versions/your_version_name
   pythonVersion: '3.7'
   runtimeVersion: '1.15'
   state: READY

Types de machines compatibles pour les explications

Pour les requêtes AI Explanations, vous devez déployer votre version de modèle avec l'un des types de machines suivants. Si vous ne spécifiez pas de type de machine, le déploiement échoue.

Le tableau suivant compare les types de machines disponibles :

Ces types de machines ne sont disponibles que sur les points de terminaison régionaux. En savoir plus sur leur compatibilité avec les autres fonctionnalités AI Platform Prediction.

Apprenez-en plus sur la tarification des différents types de machines. Pour obtenir les spécifications détaillées des types de machines Compute Engine (N1), consultez la documentation Compute Engine.

Mettre en forme les données d'entrée

Le format de base pour la prédiction en ligne est une liste d'instances de données. Il peut s'agir de simples listes de valeurs ou de membres d'un objet JSON, selon la configuration des entrées dans l'application d'entraînement. Découvrez comment mettre en forme des entrées complexes et des données binaires pour la prédiction.

Cet exemple illustre un Tensor d’entrée et une clé d’instance pour un modèle TensorFlow :

{"values": [1, 2, 3, 4], "key": 1}

La composition de la chaîne JSON peut être complexe tant qu'elle suit les règles suivantes :

• Le premier niveau des données d'instance doit être un objet JSON, soit un dictionnaire de paires clé/valeur.

• Les valeurs individuelles dans un objet d'instance peuvent être des chaînes, des nombres ou des listes. Vous ne pouvez pas intégrer d'objets JSON.

• Les listes doivent contenir uniquement des éléments du même type (y compris d'autres listes). Vous ne pouvez pas mélanger des valeurs numériques et des chaînes.

Vous devez transmettre les instances d'entrée pour la prédiction en ligne en tant que corps de message pour l'appel projects.explain. Apprenez-en plus sur les exigences de mise en forme du corps de la requête de prédiction.

1. Pour envoyer votre requête à l'aide de gcloud, assurez-vous que votre fichier d'entrée est un fichier JSON délimité par des retours à la ligne, chaque instance incluse étant un objet JSON (une instance par ligne).

   {"values": [1, 2, 3, 4], "key": 1}
   {"values": [5, 6, 7, 8], "key": 2}
   

Demander des prédictions et des explications

Demandez vos prédictions et explications :

gcloud beta ai-platform explain \
  --model $MODEL \
  --version $VERSION \
  --json-instances='your-data.txt' \
  --region us-central1

Comprendre la réponse des explications

Après avoir déployé votre modèle, vous pouvez utiliser le SDK Explainable AI pour demander des explications et visualiser les résultats de l'attribution de caractéristiques pour les données tabulaires et d'images :

import explainable_ai_sdk

m = explainable_ai_sdk.load_model_from_ai_platform(PROJECT_ID, MODEL_NAME, VERSION, region=REGION)
explanations = m.explain([instance_dict])
explanations[0].visualize_attributions()

Pour les modèles tabulaires, les attributions sont représentées dans un graphique à barres. Pour les modèles d'images, les attributions sont affichées sur l'image d'entrée, en utilisant les mêmes paramètres de visualisation que ceux que vous avez spécifiés lors du déploiement du modèle.

Pour en savoir plus sur chaque champ de la réponse d'explications, reportez-vous à l'exemple de réponse complet dans la documentation de référence de l'API.

Découvrez comment analyser la réponse des explications en vous reportant aux exemples de notebooks :

TensorFlow 2 :

• Exemple de notebook pour les données tabulaires
• Exemple de notebook pour les données d'image

TensorFlow 1.15 :

• Exemple de notebook pour les données tabulaires
• Exemple de notebook pour les données d'image

Vérifier vos explications

L'exemple de code suivant vous permet de vérifier un lot d'explications et d'examiner s'il convient d'ajuster vos valeurs de référence.

Dans le code, il vous suffit de mettre à jour la valeur de clé d'entrée en fonction des valeurs spécifiées dans votre fichier explanation_metadata.json.

{
    "inputs": {
      "YOUR_INPUT_KEY_VALUE": {
        "input_tensor_name": "YOUR_INPUT_TENSOR_NAME"
        "input_baselines": [0]
      }
    ...
}

Par exemple, si la valeur de clé d'entrée était "data", la même valeur sera "data" dans la ligne 4 de l'extrait de code suivant :

def check_explanations(example, mean_tgt_value=None, variance_tgt_value=None):
  passed_test = 0
  total_test = 1
  attribution_vals = example['attributions_by_label'][0]['attributions']['YOUR-INPUT-KEY-VALUE']

  baseline_score = example['attributions_by_label'][0]['baseline_score']
  sum_with_baseline = np.sum(attribution_vals) + baseline_score
  predicted_val = example['attributions_by_label'][0]['example_score']

  # Check 1
  # The prediction at the input is equal to that at the baseline.
  #  Please use a different baseline. Some suggestions are: random input, training
  #  set mean.
  if abs(predicted_val - baseline_score) <= 0.05:
    print('Warning: example score and baseline score are too close.')
    print('You might not get attributions.')
  else:
    passed_test += 1

  # Check 2 (only for models using Integrated Gradient explanations)
  # Ideally, the sum of the integrated gradients must be equal to the difference
  # in the prediction probability at the input and baseline. Any discrepancy in
  # these two values is due to the errors in approximating the integral.
  if explain_method == 'integrated-gradients':
    total_test += 1
    want_integral = predicted_val - baseline_score
    got_integral = sum(attribution_vals)
    if abs(want_integral-got_integral)/abs(want_integral) > 0.05:
        print('Warning: Integral approximation error exceeds 5%.')
        print('Please try increasing the number of integrated gradient steps.')
    else:
        passed_test += 1

  print(passed_test, ' out of ', total_test, ' sanity checks passed.')

Lorsque vous analysez vos explications, vous pouvez effectuer ces vérifications sur chaque attribution que vous avez reçue :

for i in attributions_resp['explanations']:
  check_explanations(i)

Utiliser l'erreur d'approximation pour améliorer les résultats

Les méthodes d'attribution des caractéristiques d'AI Explanations (échantillonnage des valeurs de Shapley, gradients intégrés et XRAI) reposent toutes sur des variantes des valeurs de Shapley. Les valeurs de Shapley étant très coûteuses en calcul, AI Explanations fournit des approximations au lieu de valeurs exactes. En plus des résultats d'attribution des caractéristiques, AI Explanations renvoie également une erreur d'approximation. Si votre erreur d'approximation dépasse 0,05, pensez à ajuster vos entrées pour réduire l'erreur.

Vous pouvez réduire l'erreur d'approximation et vous rapprocher des valeurs exactes en modifiant les entrées suivantes :

• Augmentez le nombre d'étapes d'intégration ou de chemins.
• Modifiez les références en entrée sélectionnées.
• Ajoutez d'autres références en entrée. Avec les méthodes des gradients intégrés et XRAI, l'utilisation de références supplémentaires augmente la latence. L'utilisation de références supplémentaires avec la méthode d'échantillonnage des valeurs de Shapley n'augmente pas la latence.

Augmenter le nombre d'étapes ou de chemins

Pour réduire l'erreur d'approximation, vous pouvez augmenter :

• le nombre de chemins pour l'échantillonnage des valeurs de Shapley ;
• le nombre d'étapes d'intégration pour les gradients intégrés ou XRAI.

Vous devez définir ces paramètres lorsque vous créez une ressource de version lors du déploiement du modèle.

Ajuster les références

Vous pouvez définir input_baselines dans votre fichier explanation_metadata.json. Cette section fournit des exemples de données tabulaires et de données d'image. Les références en entrée peuvent représenter des valeurs médianes, minimales, maximales ou aléatoires par rapport à vos données d'entraînement.

En général :

• Commencez par une référence représentant les valeurs médianes.
• Remplacez cette référence par une valeur aléatoire.
• Essayez deux références représentant les valeurs minimales et maximales.
• Ajoutez une autre référence représentant des valeurs aléatoires.

Exemple de données tabulaires

Le code Python suivant crée le contenu d'un fichier de métadonnées d'explications pour les données tabulaires. Vous pouvez utiliser l'échantillonnage des valeurs de Shapley et des gradients intégrés pour obtenir des attributions de caractéristiques pour les données tabulaires. Ce code fait partie de l'exemple de notebook pour les données tabulaires.

Notez que input_baselines correspond à une liste dans laquelle vous pouvez spécifier plusieurs références. Cet exemple définit une seule référence. La référence correspond à une liste de valeurs médianes pour les données d'entraînement (train_data dans cet exemple).

explanation_metadata = {
    "inputs": {
      "data": {
        "input_tensor_name": model.input.name,
        "input_baselines": [train_data.median().values.tolist()],
        "encoding": "bag_of_features",
        "index_feature_mapping": train_data.columns.tolist()
      }
    },
    "outputs": {
      "duration": {
        "output_tensor_name": model.output.name
      }
    },
  "framework": "tensorflow"
  }

Pour définir deux références représentant des valeurs minimales et maximales, définissez input_baselines comme suit : [train_data.min().values.tolist(), train_data.max().values.tolist()]

Exemple de données d'image

Le code Python suivant crée le contenu d'un fichier de métadonnées d'explications pour les données d'image. Vous pouvez utiliser des gradients intégrés pour obtenir des attributions de caractéristiques pour les données d'image. Ce code fait partie de l'exemple de notebook pour les données d'image.

Notez que input_baselines correspond à une liste dans laquelle vous pouvez spécifier plusieurs références. Cet exemple définit une seule référence. La référence correspond à une liste de valeurs aléatoires. L'utilisation de valeurs aléatoires pour une référence d'image est une bonne approche si les images de votre ensemble de données d'entraînement contiennent beaucoup de zones en noir et blanc.

Sinon, définissez input_baselines sur [0, 1] pour représenter les images en noir et blanc.

random_baseline = np.random.rand(192,192,3)

explanation_metadata = {
    "inputs": {
      "data": {
        "input_tensor_name": "input_pixels:0",
        "modality": "image",
        "input_baselines": [random_baseline.tolist()]
      }
    },
    "outputs": {
      "probability": {
        "output_tensor_name": "dense/Softmax:0"
      }
    },
  "framework": "tensorflow"
  }

Étape suivante

• En savoir plus sur les limitations de l'attribution de caractéristiques
• Pour visualiser vos explications, vous pouvez utiliser l'outil de simulation What-If. Reportez-vous aux exemples de notebooks pour en savoir plus.
• Reportez-vous au SDK AI Explanations.