Schémas de données pour former des modèles de vision par ordinateur avec Machine Learning automatisé

  • Article

S’APPLIQUE À :Extension Azure ML CLI v2 (actuelle)Kit de développement logiciel (SDK) Python azure-ai-ml v2 (préversion)

Découvrez comment mettre en forme vos fichiers JSONL pour la consommation des données dans des expériences de ML automatisées pour les tâches de vision par ordinateur pendant l’apprentissage et l’inférence.

Schéma de données pour l’apprentissage

Azure Machine Learning AutoML pour les images requiert la préparation des données d’image d’entrée au format JSON (Lignes JSON). Cette section décrit les formats de données d’entrée ou le schéma pour la classification d’images multiclasse, la classification d’images multi-étiquette, la détection d’objets et la segmentation d’instance. Nous fournirons également un exemple de fichier de lignes JSON d’apprentissage ou de validation final.

Classification d’images (binaire/multiclasse)

Format/schéma des données d’entrée dans chaque ligne JSON :

{
   "image_url":"azureml://subscriptions/<my-subscription-id>/resourcegroups/<my-resource-group>/workspaces/<my-workspace>/datastores/<my-datastore>/paths/<path_to_image>",
   "image_details":{
      "format":"image_format",
      "width":"image_width",
      "height":"image_height"
   },
   "label":"class_name",
}
Clé Description Exemple
image_url Emplacement d’image dans le magasin de données Azure Machine Learning.
my-subscription-id doit être remplacé par l’abonnement Azure où se trouvent les images. Vous trouverez plus d’informations sur les abonnement Azure ici. De même, my-resource-group, my-workspace, my-datastore devraient être remplacés respectivement par le nom du groupe de ressources, le nom de l’espace de travail et le nom du magasin de données.
path_to_image devrait être le chemin d’accès complet à l’image sur le magasin de données.
Required, String		 "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg"
image_details Détails d’image
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Type d’image (tous les formats d’images disponibles dans la bibliothèque Pillow sont pris en charge)
Optional, String from {"jpg", "jpeg", "png", "jpe", "jfif","bmp", "tif", "tiff"}		 "jpg" or "jpeg" or "png" or "jpe" or "jfif" or "bmp" or "tif" or "tiff"
width Largeur de l'image
Optional, String or Positive Integer		 "400px" or 400
height Hauteur de l’image
Optional, String or Positive Integer		 "200px" or 200
label Classe/étiquette de l’image
Required, String		 "cat"

Exemple de fichier JSON pour la classification d’images multiclasse :

{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg", "image_details":{"format": "jpg", "width": "400px", "height": "258px"}, "label": "can"}
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_02.jpg", "image_details": {"format": "jpg", "width": "397px", "height": "296px"}, "label": "milk_bottle"}
.
.
.
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_n.jpg", "image_details": {"format": "jpg", "width": "1024px", "height": "768px"}, "label": "water_bottle"}

Exemple d’image pour une classification d’images multiclasse.

Classification d’images multi-étiquette

Voici un exemple de format/schéma de données d’entrée dans chaque ligne JSON pour la classification d’images.

{
   "image_url":"azureml://subscriptions/<my-subscription-id>/resourcegroups/<my-resource-group>/workspaces/<my-workspace>/datastores/<my-datastore>/paths/<path_to_image>",
   "image_details":{
      "format":"image_format",
      "width":"image_width",
      "height":"image_height"
   },
   "label":[
      "class_name_1",
      "class_name_2",
      "class_name_3",
      "...",
      "class_name_n"
        
   ]
}
Clé Description Exemple
image_url Emplacement d’image dans le magasin de données Azure Machine Learning.
my-subscription-id doit être remplacé par l’abonnement Azure où se trouvent les images. Vous trouverez plus d’informations sur les abonnement Azure ici. De même, my-resource-group, my-workspace, my-datastore devraient être remplacés respectivement par le nom du groupe de ressources, le nom de l’espace de travail et le nom du magasin de données.
path_to_image devrait être le chemin d’accès complet à l’image sur le magasin de données.
Required, String		 "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg"
image_details Détails d’image
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Type d’image (tous les formats d’images disponibles dans la bibliothèque Pillow sont pris en charge)
Optional, String from {"jpg", "jpeg", "png", "jpe", "jfif", "bmp", "tif", "tiff"}		 "jpg" or "jpeg" or "png" or "jpe" or "jfif" or "bmp" or "tif" or "tiff"
width Largeur de l'image
Optional, String or Positive Integer		 "400px" or 400
height Hauteur de l’image
Optional, String or Positive Integer		 "200px" or 200
label Liste des classes/étiquettes dans l’image
Required, List of Strings		 ["cat","dog"]

Exemple de fichier JSON pour la classification d’images multi-étiquette :

{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg", "image_details":{"format": "jpg", "width": "400px", "height": "258px"}, "label": ["can"]}
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_02.jpg", "image_details": {"format": "jpg", "width": "397px", "height": "296px"}, "label": ["can","milk_bottle"]}
.
.
.
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_n.jpg", "image_details": {"format": "jpg", "width": "1024px", "height": "768px"}, "label": ["carton","milk_bottle","water_bottle"]}

Exemple d’image pour une classification d’images multi-étiquette.

Détection d’objets

Voici un exemple de fichier JSONL pour la détection d’objets.

{
   "image_url":"azureml://subscriptions/<my-subscription-id>/resourcegroups/<my-resource-group>/workspaces/<my-workspace>/datastores/<my-datastore>/paths/<path_to_image>",
   "image_details":{
      "format":"image_format",
      "width":"image_width",
      "height":"image_height"
   },
   "label":[
      {
         "label":"class_name_1",
         "topX":"xmin/width",
         "topY":"ymin/height",
         "bottomX":"xmax/width",
         "bottomY":"ymax/height",
         "isCrowd":"isCrowd"
      },
      {
         "label":"class_name_2",
         "topX":"xmin/width",
         "topY":"ymin/height",
         "bottomX":"xmax/width",
         "bottomY":"ymax/height",
         "isCrowd":"isCrowd"
      },
      "..."
   ]
}

Ici,

  • xmin = coordonnée x de l’angle supérieur gauche du cadre englobant
  • ymin = coordonnée y de l’angle supérieur gauche du cadre englobant
  • xmax = coordonnée x de l’angle inférieur droit du cadre englobant
  • ymax = coordonnée y de l’angle inférieur droit du cadre englobant
Clé Description Exemple
image_url Emplacement d’image dans le magasin de données Azure Machine Learning.
my-subscription-id doit être remplacé par l’abonnement Azure où se trouvent les images. Vous trouverez plus d’informations sur les abonnement Azure ici. De même, my-resource-group, my-workspace, my-datastore devraient être remplacés respectivement par le nom du groupe de ressources, le nom de l’espace de travail et le nom du magasin de données.
path_to_image devrait être le chemin d’accès complet à l’image sur le magasin de données.
Required, String		 "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg"
image_details Détails d’image
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Type d’image (tous les formats d’image disponibles dans la bibliothèque Coussins sont pris en charge. Toutefois, pour YOLO, seuls les formats d’images autorisés par OpenCV sont pris en charge.
Optional, String from {"jpg", "jpeg", "png", "jpe", "jfif", "bmp", "tif", "tiff"}		 "jpg" or "jpeg" or "png" or "jpe" or "jfif" or "bmp" or "tif" or "tiff"
width Largeur de l'image
Optional, String or Positive Integer		 "499px" or 499
height Hauteur de l’image
Optional, String or Positive Integer		 "665px" or 665
label (clé externe) Liste de cadres englobante, où chaque zone est un dictionnaire de \leurs coordonnées en haut à gauche et en bas à droite label, topX, topY, bottomX, bottomY, isCrowd
Required, List of dictionaries		 [{"label": "cat", "topX": 0.260, "topY": 0.406, "bottomX": 0.735, "bottomY": 0.701, "isCrowd": 0}]
label (clé interne) Classe/étiquette de l’objet dans le cadre englobant
Required, String		 "cat"
topX Taux de coordonnée x du coin supérieur gauche du cadre englobant et de la largeur de l’image
Required, Float in the range [0,1]		 0.260
topY Taux de coordonnée y du coin supérieur gauche du cadre englobant et de la hauteur de l’image
Required, Float in the range [0,1]		 0.406
bottomX Taux de coordonnée x du coin inférieur droit du cadre englobant et de la largeur de l’image
Required, Float in the range [0,1]		 0.735
bottomY Taux de coordonnée y du coin inférieur droit du cadre englobant et de la hauteur de l’image
Required, Float in the range [0,1]		 0.701
isCrowd Indique si le cadre englobant est autour de la foule d’objets. Si cet indicateur spécial est défini, nous ignorons ce cadre englobant lors du calcul de la métrique.
Optional, Bool		 0

Exemple de fichier JSON pour la détection d’objets :

{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg", "image_details": {"format": "jpg", "width": "499px", "height": "666px"}, "label": [{"label": "can", "topX": 0.260, "topY": 0.406, "bottomX": 0.735, "bottomY": 0.701, "isCrowd": 0}]}
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_02.jpg", "image_details": {"format": "jpg", "width": "499px", "height": "666px"}, "label": [{"label": "carton", "topX": 0.172, "topY": 0.153, "bottomX": 0.432, "bottomY": 0.659, "isCrowd": 0}, {"label": "milk_bottle", "topX": 0.300, "topY": 0.566, "bottomX": 0.891, "bottomY": 0.735, "isCrowd": 0}]}
.
.
.
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_n.jpg", "image_details": {"format": "jpg", "width": "499px", "height": "666px"}, "label": [{"label": "carton", "topX": 0.0180, "topY": 0.297, "bottomX": 0.380, "bottomY": 0.836, "isCrowd": 0}, {"label": "milk_bottle", "topX": 0.454, "topY": 0.348, "bottomX": 0.613, "bottomY": 0.683, "isCrowd": 0}, {"label": "water_bottle", "topX": 0.667, "topY": 0.279, "bottomX": 0.841, "bottomY": 0.615, "isCrowd": 0}]}

Exemple d’image pour la détection d’objet.

Segmentation d’instances

Pour la segmentation d’instances, le ML automatisé prend uniquement en charge le polygone comme entrée et sortie, sans aucun masque.

Voici un exemple de fichier JSON pour la segmentation d’instance.

{
   "image_url":"azureml://subscriptions/<my-subscription-id>/resourcegroups/<my-resource-group>/workspaces/<my-workspace>/datastores/<my-datastore>/paths/<path_to_image>",
   "image_details":{
      "format":"image_format",
      "width":"image_width",
      "height":"image_height"
   },
   "label":[
      {
         "label":"class_name",
         "isCrowd":"isCrowd",
         "polygon":[["x1", "y1", "x2", "y2", "x3", "y3", "...", "xn", "yn"]]
      }
   ]
}
Clé Description Exemple
image_url Emplacement d’image dans le magasin de données Azure Machine Learning.
my-subscription-id doit être remplacé par l’abonnement Azure où se trouvent les images. Vous trouverez plus d’informations sur les abonnement Azure ici. De même, my-resource-group, my-workspace, my-datastore devraient être remplacés respectivement par le nom du groupe de ressources, le nom de l’espace de travail et le nom du magasin de données.
path_to_image devrait être le chemin d’accès complet à l’image sur le magasin de données.
Required, String		 "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg"
image_details Détails d’image
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Type d’image
Optional, String from {"jpg", "jpeg", "png", "jpe", "jfif", "bmp", "tif", "tiff" }		 "jpg" or "jpeg" or "png" or "jpe" or "jfif" or "bmp" or "tif" or "tiff"
width Largeur de l'image
Optional, String or Positive Integer		 "499px" or 499
height Hauteur de l’image
Optional, String or Positive Integer		 "665px" or 665
label (clé externe) Liste de masques, où chaque masque est un dictionnaire de label, isCrowd, polygon coordinates
Required, List of dictionaries		 [{"label": "can", "isCrowd": 0, "polygon": [[0.577, 0.689,
0.562, 0.681,
0.559, 0.686]]}]
label (clé interne) Classe/étiquette de l’objet dans le masque
Required, String		 "cat"
isCrowd Indique si le masque est autour de la foule d’objets
Optional, Bool		 0
polygon Coordonnées de polygone pour l’objet
Required, List of list for multiple segments of the same instance. Float values in the range [0,1]		 [[0.577, 0.689, 0.567, 0.689, 0.559, 0.686]]

Exemple de fichier JSON pour la segmentation d’instance :

{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_01.jpg", "image_details": {"format": "jpg", "width": "499px", "height": "666px"}, "label": [{"label": "can", "isCrowd": 0, "polygon": [[0.577, 0.689, 0.567, 0.689, 0.559, 0.686, 0.380, 0.593, 0.304, 0.555, 0.294, 0.545, 0.290, 0.534, 0.274, 0.512, 0.2705, 0.496, 0.270, 0.478, 0.284, 0.453, 0.308, 0.432, 0.326, 0.423, 0.356, 0.415, 0.418, 0.417, 0.635, 0.493, 0.683, 0.507, 0.701, 0.518, 0.709, 0.528, 0.713, 0.545, 0.719, 0.554, 0.719, 0.579, 0.713, 0.597, 0.697, 0.621, 0.695, 0.629, 0.631, 0.678, 0.619, 0.683, 0.595, 0.683, 0.577, 0.689]]}]}
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_02.jpg", "image_details": {"format": "jpg", "width": "499px", "height": "666px"}, "label": [{"label": "carton", "isCrowd": 0, "polygon": [[0.240, 0.65, 0.234, 0.654, 0.230, 0.647, 0.210, 0.512, 0.202, 0.403, 0.182, 0.267, 0.184, 0.243, 0.180, 0.166, 0.186, 0.159, 0.198, 0.156, 0.396, 0.162, 0.408, 0.169, 0.406, 0.217, 0.414, 0.249, 0.422, 0.262, 0.422, 0.569, 0.342, 0.569, 0.334, 0.572, 0.320, 0.585, 0.308, 0.624, 0.306, 0.648, 0.240, 0.657]]}, {"label": "milk_bottle",  "isCrowd": 0, "polygon": [[0.675, 0.732, 0.635, 0.731, 0.621, 0.725, 0.573, 0.717, 0.516, 0.717, 0.505, 0.720, 0.462, 0.722, 0.438, 0.719, 0.396, 0.719, 0.358, 0.714, 0.334, 0.714, 0.322, 0.711, 0.312, 0.701, 0.306, 0.687, 0.304, 0.663, 0.308, 0.630, 0.320, 0.596, 0.32, 0.588, 0.326, 0.579]]}]}
.
.
.
{"image_url": "azureml://subscriptions/my-subscription-id/resourcegroups/my-resource-group/workspaces/my-workspace/datastores/my-datastore/paths/image_data/Image_n.jpg", "image_details": {"format": "jpg", "width": "499px", "height": "666px"}, "label": [{"label": "water_bottle", "isCrowd": 0, "polygon": [[0.334, 0.626, 0.304, 0.621, 0.254, 0.603, 0.164, 0.605, 0.158, 0.602, 0.146, 0.602, 0.142, 0.608, 0.094, 0.612, 0.084, 0.599, 0.080, 0.585, 0.080, 0.539, 0.082, 0.536, 0.092, 0.533, 0.126, 0.530, 0.132, 0.533, 0.144, 0.533, 0.162, 0.525, 0.172, 0.525, 0.186, 0.521, 0.196, 0.521 ]]}, {"label": "milk_bottle", "isCrowd": 0, "polygon": [[0.392, 0.773, 0.380, 0.732, 0.379, 0.767, 0.367, 0.755, 0.362, 0.735, 0.362, 0.714, 0.352, 0.644, 0.352, 0.611, 0.362, 0.597, 0.40, 0.593, 0.444,  0.494, 0.588, 0.515, 0.585, 0.621, 0.588, 0.671, 0.582, 0.713, 0.572, 0.753 ]]}]}

Exemple d’image pour la segmentation d’instance.

Schéma de données pour le scoring en ligne

Dans cette section, nous documentons le format de données d’entrée requis pour effectuer des prédictions lors de l’utilisation d’un modèle déployé.

Format d’entrée

Le format d’entrée JSON suivant est nécessaire pour générer des prédictions sur n’importe quelle tâche à l’aide d’un point de terminaison de modèle spécifique à la tâche.

{
   "input_data": {
      "columns": [
         "image"
      ],
      "data": [
         "image_in_base64_string_format"
      ]
   }
}

Ce json est un dictionnaire avec une clé input_data externe et des clés columnsinternes, data comme décrit dans le tableau suivant. Le point de terminaison accepte une chaîne json au format ci-dessus et la convertit en dataframe d’exemples requis par le script de scoring. Chaque image d’entrée dans la section request_json["input_data"]["data"] du json est une chaîne encodée en Base64.

Clé Description
input_data
(clé externe)		 Il s’agit d’une clé externe dans la requête json. input_data est un dictionnaire qui accepte les exemples d’images d’entrée
Required, Dictionary
columns
(clé interne)		 Noms de colonnes à utiliser pour créer une dataframe. Elle n’accepte qu’une seule colonne avec image comme nom de colonne.
Required, List
data
(clé interne)		 Liste des images encodées en Base64
Required, List

Après avoir déployé le modèle mlflow, nous pouvons utiliser l’extrait de code suivant pour obtenir des prédictions pour toutes les tâches.

# Create request json
import base64

sample_image = os.path.join(dataset_dir, "images", "1.jpg")


def read_image(image_path):
    with open(image_path, "rb") as f:
        return f.read()


request_json = {
    "input_data": {
        "columns": ["image"],
        "data": [base64.encodebytes(read_image(sample_image)).decode("utf-8")],
    }
}
import json

request_file_name = "sample_request_data.json"

with open(request_file_name, "w") as request_file:
    json.dump(request_json, request_file)
resp = ml_client.online_endpoints.invoke(
    endpoint_name=online_endpoint_name,
    deployment_name=deployment.name,
    request_file=request_file_name,
)

Format de sortie

Les prédictions effectuées sur les points de terminaison de modèle suivent une structure différente selon le type de tâche. Cette section explore les formats de données de sortie pour les tâches de classification d’image multiclasse et multi-étiquette, de détection d’objets et de segmentation d’instance.

Les schémas suivants s’appliquent lorsque la demande d’entrée contient une image.

Classification d’images (binaire/multiclasse)

Le point de terminaison de la classification d’image retourne toutes les étiquettes du jeu de données et leurs scores de probabilité pour l’image d’entrée au format suivant. visualizations et attributions sont liées à l’explicabilité et lorsque la requête concerne uniquement la notation, ces clés ne seront pas incluses dans la sortie. Pour plus d’informations sur le schéma d’entrée et de sortie explicabilité pour la classification d’images, consultez la section Explicabilité pour la classification d’images.

[
   {
      "probs": [
         2.098e-06,
         4.783e-08,
         0.999,
         8.637e-06
      ],
      "labels": [
         "can",
         "carton",
         "milk_bottle",
         "water_bottle"
      ]
   }
]

Classification d’images multi-étiquette

Pour la classification d’image à multi-étiquettes, le point de terminaison de modèle retourne les étiquettes et leurs probabilités. visualizations et attributions sont liées à l’explicabilité et lorsque la requête concerne uniquement la notation, ces clés ne seront pas incluses dans la sortie. Pour plus d’informations sur le schéma d’entrée et de sortie explicabilité pour la classification multi-étiquette, consultez la section Explicabilité pour la classification d’images multi-étiquettes.

[
   {
      "probs": [
         0.997,
         0.960,
         0.982,
         0.025
      ],
      "labels": [
         "can",
         "carton",
         "milk_bottle",
         "water_bottle"
      ]
   }
]

Détection d’objets

Le modèle de détection d’objets retourne plusieurs zones avec les coordonnées de l’angle supérieur gauche et de l’angle inférieur droit, ainsi que l’étiquette de zone et le score de confiance.

[
   {
      "boxes": [
         {
            "box": {
               "topX": 0.224,
               "topY": 0.285,
               "bottomX": 0.399,
               "bottomY": 0.620
            },
            "label": "milk_bottle",
            "score": 0.937
         },
         {
            "box": {
               "topX": 0.664,
               "topY": 0.484,
               "bottomX": 0.959,
               "bottomY": 0.812
            },
            "label": "can",
            "score": 0.891
         },
         {
            "box": {
               "topX": 0.423,
               "topY": 0.253,
               "bottomX": 0.632,
               "bottomY": 0.725
            },
            "label": "water_bottle",
            "score": 0.876
         }
      ]
   }
]

Segmentation d’instances

Dans la segmentation de l’instance, la sortie est constituée de plusieurs zones avec les coordonnées en haut à gauche et en bas à droite, les étiquettes, les scores de confiance et les polygones (pas les masques). Ici, les valeurs de polygone sont au même format que nous avons abordé dans la section des schémas.

[
    {
       "boxes": [
          {
             "box": {
                "topX": 0.679,
                "topY": 0.491,
                "bottomX": 0.926,
                "bottomY": 0.810
             },
             "label": "can",
             "score": 0.992,
             "polygon": [
                [
                   0.82, 0.811, 0.771, 0.810, 0.758, 0.805, 0.741, 0.797, 0.735, 0.791, 0.718, 0.785, 0.715, 0.778, 0.706, 0.775, 0.696, 0.758, 0.695, 0.717, 0.698, 0.567, 0.705, 0.552, 0.706, 0.540, 0.725, 0.520, 0.735, 0.505, 0.745, 0.502, 0.755, 0.493
                ]
             ]
          },
          {
             "box": {
                "topX": 0.220,
                "topY": 0.298,
                "bottomX": 0.397,
                "bottomY": 0.601
             },
             "label": "milk_bottle",
             "score": 0.989,
             "polygon": [
                [
                   0.365, 0.602, 0.273, 0.602, 0.26, 0.595, 0.263, 0.588, 0.251, 0.546, 0.248, 0.501, 0.25, 0.485, 0.246, 0.478, 0.245, 0.463, 0.233, 0.442, 0.231, 0.43, 0.226, 0.423, 0.226, 0.408, 0.234, 0.385, 0.241, 0.371, 0.238, 0.345, 0.234, 0.335, 0.233, 0.325, 0.24, 0.305, 0.586, 0.38, 0.592, 0.375, 0.598, 0.365
                ]
             ]
          },
          {
             "box": {
                "topX": 0.433,
                "topY": 0.280,
                "bottomX": 0.621,
                "bottomY": 0.679
             },
             "label": "water_bottle",
             "score": 0.988,
             "polygon": [
                [
                   0.576, 0.680, 0.501, 0.680, 0.475, 0.675, 0.460, 0.625, 0.445, 0.630, 0.443, 0.572, 0.440, 0.560, 0.435, 0.515, 0.431, 0.501, 0.431, 0.433, 0.433, 0.426, 0.445, 0.417, 0.456, 0.407, 0.465, 0.381, 0.468, 0.327, 0.471, 0.318
                ]
             ]
          }
       ]
    }
]

Format de données pour le scoring et l’explicabilité en ligne (XAI)

Important

Ces paramètres sont actuellement en préversion publique. Ils sont fournis sans contrat de niveau de service. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Avertissement

L’explicabilité est prise en charge uniquement pour la classification multi-classe et la classification multi-étiquette. Lors de la génération d’explications sur le point de terminaison en ligne, si vous rencontrez des problèmes de délai d’expiration, utilisez le notebook de scoring par lots (kit de développement logiciel (SDK) v1) pour générer des explications.

Dans cette section, nous documentons le format des données d’entrée nécessaires pour faire des prédictions et générer des explications pour la ou les classes prédites à l’aide d'un modèle déployé. Aucun déploiement distinct n’est nécessaire pour l’explicabilité. Le même point de terminaison pour le scoring en ligne peut être utilisé pour générer des explications. Il nous suffit de passer des paramètres supplémentaires liés à l’explicabilité dans le schéma d’entrée et d’obtenir des visualisations d’explications et/ou des matrices de score d’attribution (explications au niveau des pixels).

Méthodes d’explicabilité prises en charge :

Format d’entrée (XAI)

Les formats d’entrée suivants sont pris en charge pour générer des prédictions et des explications sur n’importe quelle tâche de classification à l’aide d’un point de terminaison de modèle spécifique à une tâche. Après avoir déployé le modèle, nous pouvons utiliser le schéma suivant pour obtenir des prédictions et des explications.

{
   "input_data": {
      "columns": ["image"],
      "data": [json.dumps({"image_base64": "image_in_base64_string_format", 
                           "model_explainability": True,
                           "xai_parameters": {}
                         })
      ]
   }
}

Avec l’image, deux paramètres supplémentaires (model_explainability et xai_parameters) sont requis dans le schéma d’entrée pour générer des explications.

Clé Description Valeur par défaut
image_base64 image d’entrée au format base64
Required, String		 -
model_explainability S’il faut générer des explications ou seulement le scoring
Optional, Bool		 False
xai_parameters Si model_explainability a la valeur True, xai_parameters est un dictionnaire contenant des paramètres liés à l’algorithme d’explicabilité avec les clés xai_algorithm, visualizations, attributions.
Optional, Dictionary
Si xai_parameters n’est pas passé, l’algorithme xrai d’explicabilité est utilisé avec sa valeur par défaut		 {"xai_algorithm": "xrai", "visualizations": True, "attributions": False}
xai_algorithm Nom de l’algorithme d’explicabilité à utiliser. Les algorithmes XAI pris en charge sont {xrai, integrated_gradients, guided_gradcam, guided_backprop}
Optional, String		 xrai
visualizations Indique s’il faut retourner des visualisations d’explications.
Optional, Bool		 True
attributions Indique s’il faut retourner des attributions de fonctionnalités.
Optional, Bool		 False
confidence_score_threshold_multilabel Seuil de score de confiance pour sélectionner les classes supérieures afin de générer des explications dans la classification multiétiquette.
Optional, Float		 0.5

Le tableau suivant décrit les schémas pris en charge pour l’explicabilité.

Type schéma
Inférence sur une image unique au format base64 Le dictionnaire avec image_base64 comme clé et valeur est une image encodée en base64,
model_explainability clé avec True ou False et xai_parameters dictionnaire avec des paramètres spécifiques à l’algorithme XAI
Required, Json String
Works for one or more images

Chaque image d’entrée du request_json, définie dans le code ci-dessous, est une chaîne encodée en base64 ajoutée à la liste request_json["input_data"]["data"]:

import base64
import json
# Get the details for online endpoint
endpoint = ml_client.online_endpoints.get(name=online_endpoint_name)

sample_image = "./test_image.jpg"

# Define explainability (XAI) parameters
model_explainability = True
xai_parameters = {"xai_algorithm": "xrai",
                  "visualizations": True,
                  "attributions": False}

def read_image(image_path):
    with open(image_path, "rb") as f:
        return f.read()

# Create request json
request_json = {

    "input_data": {
        "columns": ["image"],
        "data": [json.dumps({"image_base64": base64.encodebytes(read_image(sample_image)).decode("utf-8"),
                             "model_explainability": model_explainability,
                             "xai_parameters": xai_parameters})],
    }
}

request_file_name = "sample_request_data.json"

with open(request_file_name, "w") as request_file:
    json.dump(request_json, request_file)

resp = ml_client.online_endpoints.invoke(
    endpoint_name=online_endpoint_name,
    deployment_name=deployment.name,
    request_file=request_file_name,
)
predictions = json.loads(resp)

Format de sortie (XAI)

Les prédictions effectuées sur les points de terminaison de modèle suivent un schéma différent selon le type de tâche. Cette section décrit les formats de données de sortie pour les tâches de classification d’images multi-classes et multi-étiquettes.

Les schémas suivants sont définis pour le cas de deux images d’entrée.

Classification d’images (binaire/multiclasse)

Le schéma de sortie est identique à celui décrit ci-dessus, sauf que les valeurs de clé des visualizations et des attributions les valeurs de clé sont incluses, si ces clés étaient définies sur True dans la requête.

Si model_explainability, visualizationssont attributions définis sur True dans la demande d’entrée, la sortie aura visualizations et attributions. Pour plus d’informations sur ces paramètres, consultez le tableau suivant. Les visualisations et les attributions sont générées par rapport à une classe qui a le score de probabilité le plus élevé.

Clé de sortie Description
visualizations Image unique au format de chaîne base64 avec type
Optional, String
attributions tableau multidimensionnel avec des scores de forme d’attribution en pixels [3, valid_crop_size, valid_crop_size]
Optional, List		 
[
    {
       "probs": [
          0.006,
          9.345e-05,
          0.992,
          0.003
       ],
       "labels": [
          "can",
          "carton",
          "milk_bottle",
          "water_bottle"
       ],
       "visualizations": "iVBORw0KGgoAAAAN.....",
       "attributions": [[[-4.2969e-04, -1.3090e-03,  7.7791e-04,  ...,  2.6677e-04,
                          -5.5195e-03,  1.7989e-03],
                          .
                          .
                          .
                         [-5.8236e-03, -7.9108e-04, -2.6963e-03,  ...,  2.6517e-03,
                           1.2546e-03,  6.6507e-04]]]
    }
]

Classification d’images multi-étiquette

La seule différence dans le schéma de sortie de la classification multi-étiquette par rapport à la classification multi-classe est qu’il peut y avoir plusieurs classes dans chaque image pour lesquelles des explications peuvent être générées. Ainsi, visualizations est la liste des chaînes d’image en base64 et attributions est la liste des scores d’attribution par rapport à chaque classe sélectionnée en fonction deconfidence_score_threshold_multilabel (la valeur par défaut est 0,5).

Si model_explainability, visualizationssont attributions définis sur True dans la demande d’entrée, la sortie aura visualizations et attributions. Pour plus d’informations sur ces paramètres, consultez le tableau suivant. Des visualisations et des attributions sont générées sur toutes les classes dont le score de probabilité est supérieur ou égal à confidence_score_threshold_multilabel.

Clé de sortie Description
visualizations Image unique au format de chaîne base64 avec type
Optional, String
attributions Liste de tableaux multidimensionnels avec des scores d’attribution en pixels par rapport à chaque classe, où chaque tableau multidimensionnel est de forme [3, valid_crop_size, valid_crop_size]
Optional, List

Avertissement

Lors de la génération d’explications sur le point de terminaison en ligne, veillez à sélectionner uniquement quelques classes basées sur le score de confiance afin d’éviter les problèmes de délai d’expiration sur le point de terminaison ou d’utiliser le point de terminaison avec le type d’instance GPU. Pour générer des explications pour un grand nombre de classes dans la classification multi-étiquette, consultez le notebook de scoring par lots (kit de développement logiciel (SDK) v1).

[
    {
       "probs": [
          0.994,
          0.994,
          0.843,
          0.166
       ],
       "labels": [
          "can",
          "carton",
          "milk_bottle",
          "water_bottle"
       ],
       "visualizations": ["iVBORw0KGgoAAAAN.....", "iVBORw0KGgoAAAAN......", .....],
       "attributions": [
                        [[[-4.2969e-04, -1.3090e-03,  7.7791e-04,  ...,  2.6677e-04,
                           -5.5195e-03,  1.7989e-03],
                           .
                           .
                           .
                          [-5.8236e-03, -7.9108e-04, -2.6963e-03,  ...,  2.6517e-03,
                            1.2546e-03,  6.6507e-04]]],
                        .
                        .
                        .
                       ]
    }
]

Détection d’objets

Avertissement

XAI n’est pas pris en charge. Ainsi, seuls les scores sont retournés. Pour obtenir un exemple de scoring, reportez-vous à la section scoring en ligne.

Segmentation d’instance

Avertissement

XAI n’est pas pris en charge. Ainsi, seuls les scores sont retournés. Pour obtenir un exemple de scoring, reportez-vous à la section scoring en ligne.

Notes

Les images utilisées dans cet article proviennent du jeu de données Fridge Objects, copyright© Microsoft Corporation, et sont disponibles sur computervision-recipes/01_training_introduction.ipynb en vertu de la licence MIT.

Étapes suivantes