Configurer des explications basées sur les caractéristiques

Pour utiliser Vertex Explainable AI avec un modèle personnalisé, vous devez configurer certaines options lorsque vous créez la ressource Model à partir de laquelle vous prévoyez de demander des explications, ou lorsque vous déployez le modèle ou lorsque vous envoyez une tâche d'explication par lots. Cette page décrit comment configurer ces options.

Si vous souhaitez utiliser Vertex Explainable AI avec un modèle tabulaire AutoML, aucune configuration n'est requise. Vertex AI configure automatiquement le modèle pour Vertex Explainable AI. Ignorez ce document et consultez la page Obtenir des explications.

Où et quand configurer des explications

Vous configurez des explications lorsque vous créez ou importez un modèle. Vous pouvez également configurer des explications sur un modèle que vous avez déjà créé, même si vous n'avez pas configuré d'explications précédemment.

Configurer des explications lors de la création ou l'importation de modèles

Lorsque vous créez ou importez un objet Model, vous pouvez définir une configuration par défaut pour toutes ses explications à l'aide du champ explanationSpec de l'objet Model.

Vous pouvez créer un Model soumis à un entraînement personnalisé dans Vertex AI de différentes manières :

Dans les deux cas, vous pouvez configurer la ressource Model pour qu'elle soit compatible avec Vertex Explainable AI. Les exemples de ce document partent du principe que vous importez une ressource Model. Pour configurer Vertex Explainable AI lorsque vous créez une ressource Model personnalisée à l'aide d'un pipeline d'entraînement (TrainingPipeline), utilisez les paramètres de configuration décrits dans ce document dans le champ modelToUpload de TrainingPipeline.

Configurer des explications lors du déploiement de modèles ou lors de l'obtention de prédictions par lot

Lorsque vous déployez un Model sur une ressource Endpoint, vous pouvez :

  • Configurer les explications, que le modèle ait été configuré ou non pour les explications. Cela est utile si vous n'avez pas prévu d'obtenir des explications (et que vous avez omis le champ explanationSpec lors de la création du modèle), mais que vous décidez ultérieurement d'obtenir des explications sur ce modèle ou de remplacer certains paramètres d'explications.
  • Désactiver les explications. Cela s'avère utile si votre modèle est configuré pour les explications, mais que vous ne prévoyez pas d'obtenir d'explications à partir du point de terminaison. Pour désactiver les explications lors du déploiement du modèle sur un point de terminaison, décochez les options d'explicabilité dans la console Cloud ou définissez DeployedModel.disableExplanations sur true.

De même, lorsque vous obtenez des prédictions par lot à partir d'un Model, vous pouvez configurer des explications en renseignant le champ BatchPredictionJob.explanationSpec ou désactiver les explications en définissant BatchPredictionJob.generateExplanation sur false.

Remplacer la configuration lors de l'obtention d'explications en ligne

Que vous ayez créé ou importé le Model avec des paramètres d'explications, et que vous ayez configuré ou non des paramètres d'explication lors du déploiement, vous pouvez remplacer les paramètres d'explication initiaux de Model lorsque vous obtenez des explications en ligne.

Lorsque vous envoyez une requête explain à Vertex AI, vous pouvez remplacer une partie de la configuration d'explication que vous avez précédemment définie pour Model ou DeployedModel.

Dans la requête explain, vous pouvez remplacer les champs suivants :

Remplacez ces paramètres dans le champ explanationSpecOverride de la requête d'explication.

Importer un modèle avec un champ explanationSpec

Selon que vous diffusiez des prédictions à l'aide d'un conteneur préconfiguré ou d'un conteneur personnalisé, spécifiez des informations légèrement différentes pour ExplanationSpec. Sélectionnez l'onglet correspondant au conteneur que vous utilisez :

Conteneur prédéfini TensorFlow

Vous pouvez utiliser l'une des méthodes d'attribution suivantes pour Vertex Explainable AI. Lisez la comparaison des méthodes d'attribution des caractéristiques et sélectionnez celle qui convient le mieux pour votre Model :

Échantillonnage des valeurs de Shapley

En fonction de l'outil que vous souhaitez utiliser pour créer ou importer le Model, sélectionnez l'un des onglets suivants :

Console

Suivez le guide pour importer un modèle à l'aide de la console Google Cloud. Lorsque vous atteignez l'étape d'explicabilité, procédez comme suit :

  1. Pour votre méthode d'attribution de caractéristiques, sélectionnez Échantillonnage de valeurs de Shapley (pour les modèles tabulaires).

  2. Définissez le nombre de chemins d'accès sur le nombre de permutations de caractéristiques à utiliser pour la méthode d'attribution par échantillonnage de valeurs de Shapley. La valeur doit être un nombre entier compris dans la plage [1, 50].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 25.

  3. Configurez chaque caractéristique d'entrée de votre modèle :

    1. Saisissez le nom de votre caractéristique d'entrée.

    2. Vous pouvez éventuellement ajouter une ou plusieurs valeurs de référence. Sinon, Vertex Explainable AI choisit une référence en entrée par défaut avec des valeurs nulles, qui est une image noire pour les données d'image.

    3. Si vous importez un modèle TensorFlow, vous disposez de champs de saisie supplémentaires :

      1. Renseignez le nom du Tensor d'entrée.

      2. Le cas échéant, renseignez le nom du Tensor d'index et/ou le nom du Tensor de forme dense.

      3. La modalité ne peut pas être mise à jour ici. La valeur est automatiquement définie sur NUMERIC pour les modèles tabulaires ou sur IMAGE pour les modèles d'images.

      4. Le cas échéant, définissez le champ Encodage. Si ce champ n'est pas défini, la valeur par défaut est IDENTITY.

      5. Le cas échéant, définissez le champ Nom du groupe.

  4. Si vous importez un modèle TensorFlow, spécifiez les champs de sortie :

    1. Définissez le nom de sortie de votre caractéristique.
    2. Définissez le nom du Tensor de sortie de votre caractéristique.
    3. Le cas échéant, définissez le mappage des noms d'index à afficher.
    4. Le cas échéant, définissez la clé de mappage des noms à afficher.

  5. Cliquez sur le bouton Importer lorsque vous avez terminé de configurer les paramètres d'explicabilité.

gcloud

  1. Pour TensorFlow 2, le champ ExplanationMetadata est facultatif.

    Écrivez les métadonnées ExplanationMetadata suivantes dans un fichier JSON de votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier explanation-metadata.json.

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Remplacez l'élément suivant :

    • FEATURE_NAME : tout nom facile à mémoriser pour votre caractéristique d'entrée.
    • INPUT_TENSOR_NAME : nom du Tensor d'entrée dans TensorFlow. Pour trouver la valeur correcte pour ce champ, consultez la page Utiliser TensorFlow avec Vertex Explainable AI.
    • OUTPUT_NAME : tout nom facile à mémoriser pour la sortie de votre modèle.
    • OUTPUT_TENSOR_NAME : nom du Tensor de sortie dans TensorFlow. Pour trouver la valeur correcte pour ce champ, consultez la page Utiliser TensorFlow avec Vertex Explainable AI.

    Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

  2. Exécutez la commande suivante pour créer une ressource Model compatible avec Vertex Explainable AI. Les options les plus pertinentes pour Vertex Explainable AI sont mises en surbrillance. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Remplacez l'élément suivant :

    Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les pages upload et Importer des modèles.

Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

Pour les modèles TensorFlow 2, le champ metadata est facultatif. Si cette valeur est omise, Vertex AI déduit automatiquement les valeurs inputs et outputs à partir du modèle.

Méthode HTTP et URL : 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corps JSON de la requête : 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Gradients intégrés

En fonction de l'outil que vous souhaitez utiliser pour créer ou importer le Model, sélectionnez l'un des onglets suivants :

Console

Suivez le guide pour importer un modèle à l'aide de la console Google Cloud. Lorsque vous atteignez l'étape d'explicabilité, procédez comme suit :

  1. Pour votre méthode d'attribution de caractéristiques, sélectionnez gradients intégrés (pour les modèles tabulaires) ou gradients intégrés (pour les modèles de classification d'images), selon celui qui convient le mieux pour votre modèle.

  2. Si vous importez un modèle de classification d'images, procédez comme suit :

    1. Définissez le type de visualisation et la carte de couleurs.

    2. Vous pouvez conserver les options Exclure en dessous de, Exclure au-dessus de, Type de superposition et Nombre d'étapes d'intégration sur leurs paramètres par défaut.

    Découvrez les paramètres de visualisation.

  3. Définissez le nombre d'étapes à utiliser pour estimer l'intégrale de chemin lors de l'attribution des caractéristiques. La valeur doit être un nombre entier compris dans la plage [1, 100].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 50.

  4. Configurez chaque caractéristique d'entrée de votre modèle :

    1. Saisissez le nom de votre caractéristique d'entrée.

    2. Vous pouvez éventuellement ajouter une ou plusieurs valeurs de référence. Sinon, Vertex Explainable AI choisit une référence en entrée par défaut avec des valeurs nulles, qui est une image noire pour les données d'image.

    3. Si vous importez un modèle TensorFlow, vous disposez de champs de saisie supplémentaires :

      1. Renseignez le nom du Tensor d'entrée.

      2. Le cas échéant, renseignez le nom du Tensor d'index et/ou le nom du Tensor de forme dense.

      3. La modalité ne peut pas être mise à jour ici. La valeur est automatiquement définie sur NUMERIC pour les modèles tabulaires ou sur IMAGE pour les modèles d'images.

      4. Le cas échéant, définissez le champ Encodage. Si ce champ n'est pas défini, la valeur par défaut est IDENTITY.

      5. Le cas échéant, définissez le champ Nom du groupe.

  5. Si vous importez un modèle TensorFlow, spécifiez les champs de sortie :

    1. Définissez le nom de sortie de votre caractéristique.
    2. Définissez le nom du Tensor de sortie de votre caractéristique.
    3. Le cas échéant, définissez le mappage des noms d'index à afficher.
    4. Le cas échéant, définissez la clé de mappage des noms à afficher.

  6. Cliquez sur le bouton Importer lorsque vous avez terminé de configurer les paramètres d'explicabilité.

gcloud

  1. Pour TensorFlow 2, le champ ExplanationMetadata est facultatif.

    Écrivez les métadonnées ExplanationMetadata suivantes dans un fichier JSON de votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier explanation-metadata.json.

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "MODALITY",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Remplacez l'élément suivant :

    • FEATURE_NAME : tout nom facile à mémoriser pour votre caractéristique d'entrée.
    • INPUT_TENSOR_NAME : nom du Tensor d'entrée dans TensorFlow. Pour trouver la valeur correcte pour ce champ, consultez la page Utiliser TensorFlow avec Vertex Explainable AI.
    • MODALITY : image si Model accepte les images en entrée, ou numeric si Model accepte les données tabulaires en entrée. La valeur par défaut est numeric.

    • VIZUALIZATION_OPTIONS : options permettant de visualiser les explications. Pour savoir comment renseigner ce champ, consultez la page Configurer les paramètres de visualisation des données d'image.

      Si vous omettez le champ modality ou définissez le champ modality sur numeric, omettez complètement le champ visualization.

    • OUTPUT_NAME : tout nom facile à mémoriser pour la sortie de votre modèle.
    • OUTPUT_TENSOR_NAME : nom du Tensor de sortie dans TensorFlow. Pour trouver la valeur correcte pour ce champ, consultez la page Utiliser TensorFlow avec Vertex Explainable AI.

    Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

  2. Exécutez la commande suivante pour créer une ressource Model compatible avec Vertex Explainable AI. Les options les plus pertinentes pour Vertex Explainable AI sont mises en surbrillance. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=integrated-gradients \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Remplacez l'élément suivant :

    Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

    Vous pouvez éventuellement ajouter des indicateurs pour configurer l'approximation SmoothGrad des dégradés.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • IMAGE_URI : URI d'un conteneur prédéfini TensorFlow pour la diffusion des prédictions.
  • STEP_COUNT : nombre d'étapes à utiliser pour estimer l'intégrale de chemin lors de l'attribution des caractéristiques. La valeur doit être un nombre entier compris dans la plage [1, 100].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 50.

  • FEATURE_NAME : tout nom facile à mémoriser pour votre caractéristique d'entrée.
  • INPUT_TENSOR_NAME : nom du Tensor d'entrée dans TensorFlow. Pour trouver la valeur correcte pour ce champ, consultez la page Utiliser TensorFlow avec Vertex Explainable AI.
  • MODALITY : image si Model accepte les images en entrée, ou numeric si Model accepte les données tabulaires en entrée. La valeur par défaut est numeric.

  • VIZUALIZATION_OPTIONS : options permettant de visualiser les explications. Pour savoir comment renseigner ce champ, consultez la page Configurer les paramètres de visualisation des données d'image.

    Si vous omettez le champ modality ou définissez le champ modality sur numeric, omettez complètement le champ visualization.

  • OUTPUT_NAME : tout nom facile à mémoriser pour la sortie de votre modèle.
  • OUTPUT_TENSOR_NAME : nom du Tensor de sortie dans TensorFlow. Pour trouver la valeur correcte pour ce champ, consultez la page Utiliser TensorFlow avec Vertex Explainable AI.

Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les pages upload et Importer des modèles.

Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

Vous pouvez éventuellement ajouter des champs pour configurer l'approximation SmoothGrad des gradients dans ExplanationParameters.

Pour les modèles TensorFlow 2, le champ metadata est facultatif. Si cette valeur est omise, Vertex AI déduit automatiquement les valeurs inputs et outputs à partir du modèle.

Méthode HTTP et URL : 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corps JSON de la requête : 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

En fonction de l'outil que vous souhaitez utiliser pour créer ou importer le Model, sélectionnez l'un des onglets suivants :

Console

Suivez le guide pour importer un modèle à l'aide de la console Google Cloud. Lorsque vous atteignez l'étape d'explicabilité, procédez comme suit :

  1. Pour votre méthode d'attribution de caractéristiques, sélectionnez XRAI (pour les modèles de classification d'images).

  2. Définissez les options de visualisation suivantes :

    1. Définissez la carte de couleurs.

    2. Vous pouvez conserver les options Exclure en dessous de, Exclure au-dessus de, Type de superposition et Nombre d'étapes d'intégration sur leurs paramètres par défaut.

      Découvrez les paramètres de visualisation.

  3. Définissez le nombre d'étapes à utiliser pour estimer l'intégrale de chemin lors de l'attribution des caractéristiques. La valeur doit être un nombre entier compris dans la plage [1, 100].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 50.

  4. Configurez chaque caractéristique d'entrée de votre modèle :

    1. Saisissez le nom de votre caractéristique d'entrée.

    2. Vous pouvez éventuellement ajouter une ou plusieurs valeurs de référence. Sinon, Vertex Explainable AI choisit une référence en entrée par défaut avec des valeurs nulles, qui est une image noire pour les données d'image.

    3. Si vous importez un modèle TensorFlow, vous disposez de champs de saisie supplémentaires :

      1. Renseignez le nom du Tensor d'entrée.

      2. Le cas échéant, renseignez le nom du Tensor d'index et/ou le nom du Tensor de forme dense.

      3. La modalité ne peut pas être mise à jour ici. La valeur est automatiquement définie sur NUMERIC pour les modèles tabulaires ou sur IMAGE pour les modèles d'images.

      4. Le cas échéant, définissez le champ Encodage. Si ce champ n'est pas défini, la valeur par défaut est IDENTITY.

      5. Le cas échéant, définissez le champ Nom du groupe.

  5. Si vous importez un modèle TensorFlow, spécifiez les champs de sortie :

    1. Définissez le nom de sortie de votre caractéristique.
    2. Définissez le nom du Tensor de sortie de votre caractéristique.
    3. Le cas échéant, définissez le mappage des noms d'index à afficher.
    4. Le cas échéant, définissez la clé de mappage des noms à afficher.

  6. Cliquez sur le bouton Importer lorsque vous avez terminé de configurer les paramètres d'explicabilité.

gcloud

  1. Pour TensorFlow 2, le champ ExplanationMetadata est facultatif.

    Écrivez les métadonnées ExplanationMetadata suivantes dans un fichier JSON de votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier explanation-metadata.json.

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "image",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Remplacez l'élément suivant :

    Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

  2. Exécutez la commande suivante pour créer une ressource Model compatible avec Vertex Explainable AI. Les options les plus pertinentes pour Vertex Explainable AI sont mises en surbrillance. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=xrai \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Remplacez l'élément suivant :

    Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

    Vous pouvez éventuellement ajouter des indicateurs pour configurer l'approximation SmoothGrad des dégradés.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les pages upload et Importer des modèles.

Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

Vous pouvez éventuellement ajouter des champs pour configurer l'approximation SmoothGrad des gradients dans ExplanationParameters.

Pour les modèles TensorFlow 2, le champ metadata est facultatif. Si cette valeur est omise, Vertex AI déduit automatiquement les valeurs inputs et outputs à partir du modèle.

Méthode HTTP et URL : 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corps JSON de la requête : 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Conteneurs préconfigurés scikit-learn et XGBoost

Si votre Model accepte des données tabulaires en entrée et diffuse les prédictions à l'aide d'un conteneur scikit-learn ou XGBoost préconfiguré pour la prédiction, vous pouvez le configurer pour qu'il utilisezla méthode d'attribution par échantillonnage de valeurs de Shapley pour obtenir des explications.

En fonction de l'outil que vous souhaitez utiliser pour créer ou importer le Model, sélectionnez l'un des onglets suivants :

Console

Suivez le guide pour importer un modèle à l'aide de la console Google Cloud. Lorsque vous atteignez l'étape d'explicabilité, procédez comme suit :

  1. Pour votre méthode d'attribution de caractéristiques, sélectionnez Échantillonnage de valeurs de Shapley (pour les modèles tabulaires).

  2. Définissez le nombre de chemins d'accès sur le nombre de permutations de caractéristiques à utiliser pour la méthode d'attribution par échantillonnage de valeurs de Shapley. La valeur doit être un nombre entier compris dans la plage [1, 50].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 25.

  3. Configurez chaque caractéristique d'entrée de votre modèle :

    1. Saisissez le nom de votre caractéristique d'entrée.

      Si vos artefacts de modèle n'incluent pas de noms de fonctionnalités, Vertex AI ne peut pas mapper les noms de fonctionnalités d'entrée spécifiés sur le modèle. Dans ce cas, vous ne devez fournir qu'une seule caractéristique d'entrée avec un nom aléatoire et facile à utiliser, tel que input_features. Dans la réponse d'explication, vous obtiendrez une liste d'attributions à N dimensions, où N est le nombre de caractéristiques du modèle et où les éléments de la liste apparaissent dans le même ordre que l'ensemble de données d'entraînement.

    2. Vous pouvez éventuellement ajouter une ou plusieurs valeurs de référence. Sinon, Vertex Explainable AI choisit une référence en entrée par défaut avec des valeurs nulles, qui est une image noire pour les données d'image.

  4. Définissez le nom de sortie de votre caractéristique.

  5. Cliquez sur le bouton Importer lorsque vous avez terminé de configurer les paramètres d'explicabilité.

gcloud

  1. Écrivez les métadonnées ExplanationMetadata suivantes dans un fichier JSON de votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier explanation-metadata.json.

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
    }
  }
}

    Remplacez l'élément suivant :

    • FEATURE_NAME : tout nom facile à mémoriser pour votre caractéristique d'entrée.
    • OUTPUT_NAME : tout nom facile à mémoriser pour la sortie de votre modèle.

    Si vous spécifiez des valeurs de référence, assurez-vous qu'elles correspondent à l'entrée de votre modèle, généralement une liste de matrices 2D. Sinon, la valeur de référence par défaut est une matrice 2D de valeur 0 de la forme d'entrée.

  2. Exécutez la commande suivante pour créer une ressource Model compatible avec Vertex Explainable AI. Les options les plus pertinentes pour Vertex Explainable AI sont mises en surbrillance. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Remplacez les éléments suivants :

    Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

Si vous spécifiez des valeurs de référence, assurez-vous qu'elles correspondent à l'entrée de votre modèle, généralement une liste de matrices 2D. Sinon, la valeur de référence par défaut est une matrice 2D de valeur 0 de la forme d'entrée.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corps JSON de la requête : 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Conteneur personnalisé

Si votre Model accepte des données tabulaires en entrée et diffuse des prédictions à l'aide d'un conteneur personnalisé, vous pouvez le configurer pour utiliser la méthode d'attribution Sampled Shapley pour obtenir des explications.

Déterminer les noms des caractéristiques et des résultats

Dans les étapes suivantes, vous devez fournir à Vertex AI les noms des caractéristiques que votre Model attend en entrée. Vous devez également spécifier la clé utilisée pour les sorties dans les prédictions de la ressource Model.

Déterminer les noms des caractéristiques

Si votre Model s'attend à ce que chaque instance d'entrée possède certaines clés de niveau supérieur, ces clés sont vos noms de caractéristiques.

Par exemple, considérons un Model qui s'attend à ce que chaque instance d'entrée soit au format suivant :

{
  "length": <value>,
  "width": <value>
}

Dans ce cas, les noms des caractéristiques sont length et width. Même si les valeurs de ces champs contiennent des listes ou des objets imbriqués, length et width sont les seules clés dont vous avez besoin pour les étapes suivantes. Lorsque vous demandez des explications, Vertex Explainable AI fournit des attributions pour chaque élément imbriqué de vos caractéristiques.

Si votre Model attend une entrée sans clé, Vertex Explainable AI considère que Model dispose d'une seule caractéristique. Vous pouvez utiliser n'importe quelle chaîne mémorable pour le nom de la caractéristique.

Par exemple, considérons un Model qui s'attend à ce que chaque instance d'entrée soit au format suivant :

[
  <value>,
  <value>
]

Dans ce cas, fournissez à vertex Explainable AI un nom de caractéristique unique de votre choix, tel que dimensions.

Déterminer le nom des sorties

Si votre Model renvoie chaque instance de prédiction en ligne avec une sortie en clé, cette clé est votre nom de sortie.

Prenons l'exemple d'un objet Model qui renvoie chaque prédiction au format suivant :

{
  "scores": <value>
}

Dans ce cas, le nom de la sortie est scores. Si la valeur du champ scores est un tableau, alors, lorsque vous obtenez des explications, Vertex Explainable AI renvoie des attributions de caractéristiques pour l'élément ayant la valeur la plus élevée dans chaque prédiction. Pour configurer Vertex Explainable AI de manière à fournir des attributions de caractéristiques pour d'autres éléments du champ de sortie, vous pouvez spécifier les champs topK ou outputIndices de ExplanationParameters. Toutefois, les exemples de ce document ne présentent pas ces options.

Si votre Model renvoie des prédictions sans clé, vous pouvez utiliser n'importe quelle chaîne mémorable pour le nom de la sortie. Cela s'applique par exemple si votre ressource Model renvoie un tableau ou une valeur scalaire pour chaque prédiction.

Créer le Model

En fonction de l'outil que vous souhaitez utiliser pour créer ou importer le Model, sélectionnez l'un des onglets suivants :

Console

Suivez le guide pour importer un modèle à l'aide de la console Google Cloud. Lorsque vous atteignez l'étape d'explicabilité, procédez comme suit :

  1. Pour votre méthode d'attribution de caractéristiques, sélectionnez Échantillonnage de valeurs de Shapley (pour les modèles tabulaires).

  2. Définissez le nombre de chemins d'accès sur le nombre de permutations de caractéristiques à utiliser pour la méthode d'attribution par échantillonnage de valeurs de Shapley. La valeur doit être un nombre entier compris dans la plage [1, 50].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 25.

  3. Configurez chaque caractéristique d'entrée de votre modèle :

    1. Saisissez le nom de votre caractéristique d'entrée.

      Si vos artefacts de modèle n'incluent pas de noms de fonctionnalités, Vertex AI ne peut pas mapper les noms de fonctionnalités d'entrée spécifiés sur le modèle. Dans ce cas, vous ne devez fournir qu'une seule caractéristique d'entrée avec un nom aléatoire et facile à utiliser, tel que input_features. Dans la réponse d'explication, vous obtiendrez une liste d'attributions à N dimensions, où N est le nombre de caractéristiques du modèle et où les éléments de la liste apparaissent dans le même ordre que l'ensemble de données d'entraînement.

    2. Vous pouvez éventuellement ajouter une ou plusieurs valeurs de référence. Sinon, Vertex Explainable AI choisit une référence en entrée par défaut avec des valeurs nulles, qui est une image noire pour les données d'image.

  4. Définissez le nom de sortie de votre caractéristique.

  5. Cliquez sur le bouton Importer lorsque vous avez terminé de configurer les paramètres d'explicabilité.

gcloud

  1. Écrivez les métadonnées ExplanationMetadata suivantes dans un fichier JSON de votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier explanation-metadata.json.

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {}
  },
  "outputs": {
    "OUTPUT_NAME": {}
  }
}

    Remplacez l'élément suivant :

    • FEATURE_NAME : nom de la fonctionnalité, comme décrit dans la section "Déterminer les noms de caractéristiques" de ce document.
    • OUTPUT_NAME : nom de la sortie, tel que décrit dans la section "Déterminer le nom de sortie" de ce document.

    Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

    Si vous spécifiez des valeurs de référence, assurez-vous qu'elles correspondent à l'entrée de votre modèle, généralement une liste de matrices 2D. Sinon, la valeur de référence par défaut est une matrice 2D de valeur 0 de la forme d'entrée.

  2. Exécutez la commande suivante pour créer une ressource Model compatible avec Vertex Explainable AI. Les options les plus pertinentes pour Vertex Explainable AI sont mises en surbrillance. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Remplacez l'élément suivant :

    • PATH_COUNT : nombre de permutations de caractéristiques à utiliser pour la méthode d'attribution d'échantillonnage des valeurs de Shapley. La valeur doit être un nombre entier compris dans la plage [1, 50].

      Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 25.

    Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PATH_COUNT : nombre de permutations de caractéristiques à utiliser pour la méthode d'attribution d'échantillonnage des valeurs de Shapley. La valeur doit être un nombre entier compris dans la plage [1, 50].

    Une valeur plus élevée peut réduire l'erreur d'approximation, mais elle utilise plus de ressources de calcul. Si vous ne savez pas quelle valeur utiliser, essayez 25.

  • FEATURE_NAME : nom de la fonctionnalité, comme décrit dans la section "Déterminer les noms de caractéristiques" de ce document.
  • OUTPUT_NAME : nom de la sortie, tel que décrit dans la section "Déterminer le nom de sortie" de ce document.

Pour en savoir plus sur les valeurs appropriées pour les autres espaces réservés, consultez les sections upload et Importer des modèles.

Vous pouvez éventuellement ajouter des valeurs de référence d'entrée à ExplanationMetadata. Sinon, Vertex AI choisit des valeurs de référence d'entrée pour Model.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corps JSON de la requête : 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Étapes suivantes