Compartilhar via

Esquemas de dados para treinar modelos de pesquisa visual computacional com machine learning automatizado

  • Artigo

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)

Saiba como formatar arquivos JSONL para o consumo de dados em experimentos de ML automatizados para tarefas da pesquisa visual computacional durante o treinamento e a inferência.

Esquema de dados para treinamento

O Azure Machine Learning AutoML para imagens requer que os dados de imagem de entrada sejam preparados no formato JSONL (JSON Lines). Esta seção descreve os formatos de dados de entrada ou o esquema para classificação de imagem de várias classes, classificação de imagem de vários rótulos, detecção de objetos e segmentação de instância. Também incluímos um exemplo de arquivo JSON Lines de validação ou treinamento final.

Classificação de imagem (binário/várias classes)

Formato/esquema de dados de entrada em cada JSON Line:

{
   "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",
}
Chave Descrição Exemplo
image_url Local da imagem no armazenamento de dados do Azure Machine Learning.
my-subscription-id precisa ser substituído pela assinatura do Azure em que as imagens estão localizadas. Mais informações sobre assinaturas do Azure podem ser encontradas aqui. Da mesma formamy-resource-group, my-workspace e my-datastore devem ser substituídos pelo nome do grupo de recursos, pelo nome do workspace e pelo nome do repositório de dados, respectivamente.
path_to_image deve ser o caminho completo para a imagem no armazenamento de dados.
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 Detalhes da imagem
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Tipo de imagem (há suporte para todos os formatos de imagem disponíveis na biblioteca Pillow)
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 A largura da imagem
Optional, String or Positive Integer		 "400px" or 400
height A altura da imagem
Optional, String or Positive Integer		 "200px" or 200
label A classe/rótulo da imagem
Required, String		 "cat"

Exemplo de um arquivo JSONL para classificação de imagem de várias classes:

{"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"}

Exemplo de imagem para classificação de imagem de várias classes.

Classificação de imagem de vários rótulos

Veja a seguir um exemplo de formato/esquema de dados de entrada em cada JSON Line para classificação de imagem.

{
   "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"
        
   ]
}
Chave Descrição Exemplo
image_url Local da imagem no armazenamento de dados do Azure Machine Learning.
my-subscription-id precisa ser substituído pela assinatura do Azure em que as imagens estão localizadas. Mais informações sobre assinaturas do Azure podem ser encontradas aqui. Da mesma formamy-resource-group, my-workspace e my-datastore devem ser substituídos pelo nome do grupo de recursos, pelo nome do workspace e pelo nome do repositório de dados, respectivamente.
path_to_image deve ser o caminho completo para a imagem no armazenamento de dados.
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 Detalhes da imagem
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Tipo de imagem (há suporte para todos os formatos de imagem disponíveis na biblioteca Pillow)
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 A largura da imagem
Optional, String or Positive Integer		 "400px" or 400
height A altura da imagem
Optional, String or Positive Integer		 "200px" or 200
label Lista de classes/rótulos na imagem
Required, List of Strings		 ["cat","dog"]

Exemplo de um arquivo JSONL para classificação de imagem de vários rótulos:

{"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"]}

Exemplo de imagem para classificação de imagem com vários rótulos.

Detecção de objetos

Veja a seguir um exemplo de arquivo JSONL para detecção de objetos.

{
   "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"
      },
      "..."
   ]
}

Aqui,

  • xmin = coordenada X do canto superior esquerdo da caixa delimitadora
  • ymin = coordenada Y do canto superior esquerdo da caixa delimitadora
  • xmax = coordenada X do canto inferior direito da caixa delimitadora
  • ymax = coordenada Y do canto inferior direito da caixa delimitadora
Chave Descrição Exemplo
image_url Local da imagem no armazenamento de dados do Azure Machine Learning.
my-subscription-id precisa ser substituído pela assinatura do Azure em que as imagens estão localizadas. Mais informações sobre assinaturas do Azure podem ser encontradas aqui. Da mesma formamy-resource-group, my-workspace e my-datastore devem ser substituídos pelo nome do grupo de recursos, pelo nome do workspace e pelo nome do repositório de dados, respectivamente.
path_to_image deve ser o caminho completo para a imagem no armazenamento de dados.
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 Detalhes da imagem
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Tipo de imagem (há suporte para todos os formatos de imagem disponíveis na biblioteca Pillow. Mas para YOLO somente os formatos de imagem permitidos pelo opencv têm suporte)
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 A largura da imagem
Optional, String or Positive Integer		 "499px" or 499
height A altura da imagem
Optional, String or Positive Integer		 "665px" or 665
label (chave externa) Lista de caixas delimitadoras, em que cada caixa é um dicionário das coordenadas superior esquerda e inferior direita 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 (chave interna) Classe/rótulo do objeto na caixa delimitadora
Required, String		 "cat"
topX Razão entre a coordenada X do canto superior esquerdo da caixa delimitadora e a largura da imagem
Required, Float in the range [0,1]		 0.260
topY Razão entre a coordenada Y do canto superior esquerdo da caixa delimitadora e a altura da imagem
Required, Float in the range [0,1]		 0.406
bottomX Razão entre a coordenada X do canto inferior direito da caixa delimitadora e a largura da imagem
Required, Float in the range [0,1]		 0.735
bottomY Razão entre a coordenada Y do canto inferior direito da caixa delimitadora e a altura da imagem
Required, Float in the range [0,1]		 0.701
isCrowd Indica se a caixa delimitadora está em volta do grupo de objetos. Se esse sinalizador especial estiver definido, ignoraremos essa caixa delimitadora ao calcular a métrica.
Optional, Bool		 0

Exemplo de um arquivo JSONL para detecção de objetos:

{"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}]}

Exemplo de imagem para detecção de objeto.

Segmentação de instâncias

Para a segmentação de instância, o ML automatizado dá suporte apenas para polígono como entrada e saída, sem máscaras.

Este é um arquivo JSONL de exemplo para segmentação de instâncias.

{
   "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"]]
      }
   ]
}
Chave Descrição Exemplo
image_url Local da imagem no armazenamento de dados do Azure Machine Learning.
my-subscription-id precisa ser substituído pela assinatura do Azure em que as imagens estão localizadas. Mais informações sobre assinaturas do Azure podem ser encontradas aqui. Da mesma formamy-resource-group, my-workspace e my-datastore devem ser substituídos pelo nome do grupo de recursos, pelo nome do workspace e pelo nome do repositório de dados, respectivamente.
path_to_image deve ser o caminho completo para a imagem no armazenamento de dados.
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 Detalhes da imagem
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format Tipo de Imagem
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 A largura da imagem
Optional, String or Positive Integer		 "499px" or 499
height A altura da imagem
Optional, String or Positive Integer		 "665px" or 665
label (chave externa) Lista de máscaras, em que cada máscara é um dicionário 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 (chave interna) Classe/rótulo do objeto na máscara
Required, String		 "cat"
isCrowd Indica se a máscara está em volta do grupo de objetos
Optional, Bool		 0
polygon Coordenadas de polígono do objeto
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]]

Exemplo de um arquivo JSONL para segmentação de instâncias:

{"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 ]]}]}

Exemplo de imagem para segmentação de instância.

Esquema de dados para pontuação online

Nesta seção, documentamos o formato de dados de entrada necessário para fazer previsões ao usar um modelo implantado.

Formato de entrada

O JSON a seguir é o formato de entrada necessário para gerar previsões em qualquer tarefa usando o ponto de extremidade de modelo específico da tarefa.

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

Esse json é um dicionário com chave externa input_data e chaves internas columns, data conforme descrito na tabela a seguir. O ponto de extremidade aceita uma cadeia de caracteres json no formato acima e converte-a em um dataframe de exemplos exigidos pelo script de pontuação. Cada imagem de entrada na seção request_json["input_data"]["data"] do json é uma cadeia de caracteres codificada em base64.

Chave Descrição
input_data
(chave externa)		 É uma chave externa na solicitação json. input_data é um dicionário que aceita exemplos de imagens de entrada
Required, Dictionary
columns
(chave interna)		 Nomes de coluna a serem usados para criar o dataframe. Ele aceita apenas uma coluna, com image como nome da coluna.
Required, List
data
(chave interna)		 Lista de imagens codificadas em base64
Required, List

Depois de implantar o modelo mlflow, podemos usar o seguinte snippet de código para gerar previsões para todas as tarefas.

# 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,
)

Formato da saída

As previsões feitas em pontos de extremidade de modelo seguem uma estrutura diferente, dependendo do tipo de tarefa. Esta seção explora os formatos de dados de saída para classificação de imagem com várias classes e vários rótulos, detecção de objetos e segmentação de instâncias.

Os esquemas a seguir são aplicáveis quando a solicitação de entrada contém uma imagem.

Classificação de imagem (binário/várias classes)

O ponto de extremidade para classificação de imagem retorna todos os rótulos no conjunto de dados e as respectivas pontuações de probabilidade para a imagem de entrada no formato a seguir. visualizations e attributions estão relacionadas à explicabilidade, e quando a solicitação é apenas para pontuação, essas chaves não serão incluídas na saída. Para obter mais informações sobre o esquema de entrada e saída de explicabilidade para classificação de imagem, consulte a seção de explicabilidade para classificação de imagem.

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

Classificação de imagem de vários rótulos

Para classificação de imagem com vários rótulos, o ponto de extremidade de modelo retorna rótulos e as respectivas probabilidades. visualizations e attributions estão relacionadas à explicabilidade, e quando a solicitação é apenas para pontuação, essas chaves não serão incluídas na saída. Para obter mais informações sobre o esquema de entrada e saída de explicabilidade para classificação de vários rótulos, consulte a seção de vários rótulos da explicabilidade para classificação de imagem.

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

Detecção de objetos

O modelo de detecção de objetos retorna várias caixas com as coordenadas superior esquerda e inferior direita em escala, juntamente com o rótulo da caixa e a pontuação de confiança.

[
   {
      "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
         }
      ]
   }
]

Segmentação de instâncias

Na segmentação de instâncias, a saída consiste em várias caixas com as coordenadas superior esquerda e inferior direita em escala, rótulos, pontuações de confiança e polígonos (não máscaras). Aqui, os valores de polígono estão no mesmo formato que discutimos na seção de esquema.

[
    {
       "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
                ]
             ]
          }
       ]
    }
]

Formato de dados para Pontuação e Explicabilidade Online (XAI)

Importante

Essas configurações estão atualmente em visualização pública. Eles são fornecidos sem um acordo de nível de serviço. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Aviso

A Explicabilidade tem suporte apenas para classificação de várias classes e classificação de vários rótulos. Ao gerar explicações no ponto de extremidade online, se você encontrar problemas de tempo limite, use o notebook de pontuação em lote (SDK v1) para gerar explicações.

Nesta seção, documentamos o formato de dados de entrada necessário para fazer previsões e gerar explicações para classe/classes previstas usando um modelo implantado. Não há nenhuma implantação separada necessária para explicabilidade. O mesmo ponto de extremidade para pontuação online pode ser utilizado para gerar explicações. Só precisamos passar alguns parâmetros adicionais relacionados à explicabilidade no esquema de entrada e obter visualizações de explicações e/ou matrizes de pontuação de atribuição (explicações de nível de pixel).

Métodos de explicabilidade compatíveis:

Formato de entrada (XAI)

Os formatos de entrada a seguir têm suporte para gerar previsões e explicações sobre qualquer tarefa de classificação usando o ponto de extremidade do modelo específico da tarefa. Depois de implantar o modelo, podemos usar o seguinte esquema para gerar previsões e explicações.

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

Junto com a imagem, há dois parâmetros adicionais (model_explainability e xai_parameters) necessários no esquema de entrada para gerar explicações.

Chave Descrição Valor padrão
image_base64 imagem de entrada no formato base64
Required, String		 -
model_explainability Se deve gerar explicações ou apenas a pontuação
Optional, Bool		 False
xai_parameters Se model_explainability for True, xai_parameters será um dicionário que contém parâmetros relacionados ao algoritmo de explicabilidade com as chaves ask xai_algorithm, visualizations, e attributions.
Optional, Dictionary
Se xai_parameters não passar, o algoritmo de explicação xrai será usado com seu valor padrão		 {"xai_algorithm": "xrai", "visualizations": True, "attributions": False}
xai_algorithm Nome do algoritmo de Explicabilidade a ser usado. Os algoritmos XAI compatíveis são {xrai, integrated_gradients, guided_gradcam, guided_backprop}
Optional, String		 xrai
visualizations Se deve retornar visualizações de explicações.
Optional, Bool		 True
attributions Se deve retornar atribuições de recurso.
Optional, Bool		 False
confidence_score_threshold_multilabel Limite de pontuação de confiança para selecionar as principais classes para gerar explicações na classificação de vários rótulos.
Optional, Float		 0.5

A tabela a seguir descreve os esquemas compatíveis com a explicabilidade.

Tipo Esquema
Inferência em uma única imagem no formato base64 Dicionário com image_base64 como chave e valor é imagem codificada em base64,
model_explainability chave com True ou False e xai_parameters dicionário com parâmetros específicos do algoritmo XAI
Required, Json String
Works for one or more images

Cada imagem de entrada no request_json, definida no código abaixo, é uma cadeia de caracteres codificada em base64 acrescentada à lista 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)

Formato de saída (XAI)

As previsões feitas em pontos de extremidade de modelo seguem uma esquema diferente, dependendo do tipo de tarefa. Esta seção descreve os formatos de dados de saída para tarefas de classificação de imagem de várias classes e vários rótulos.

Os esquemas a seguir são definidos para o caso de duas imagens de entrada.

Classificação de imagem (binário/várias classes)

O esquema de saída é o mesmo descrito acima, exceto que os valores das chaves visualizations e attributions estão incluídos, se essas chaves foram definidas como True na solicitação.

Se model_explainability, visualizations, attributions estiverem definidos como True na solicitação de entrada, a saída terá visualizations e attributions. Mais detalhes sobre esses parâmetros são explicados na tabela a seguir. Visualizações e atribuições são geradas em relação a uma classe que tem a pontuação de probabilidade mais alta.

Chave de saída Descrição
visualizations Imagem única em formato de string base64 com tipo
Optional, String
attributions matriz de várias dimensões com pontuações de atribuição de pixel de forma [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]]]
    }
]

Classificação de imagem de vários rótulos

A única diferença no esquema de saída da classificação de vários rótulos em comparação com a classificação de várias classes é que pode haver várias classes em cada imagem para as quais as explicações podem ser geradas. Portanto, visualizations é a lista de cadeias de caracteres de imagem base64, e attributions é a lista de pontuações de atribuição em relação a cada classe selecionada de acordo com o confidence_score_threshold_multilabel (o padrão é 0,5).

Se model_explainability, visualizations, attributions estiverem definidos como True na solicitação de entrada, a saída terá visualizations e attributions. Mais detalhes sobre esses parâmetros são explicados na tabela a seguir. Visualizações e atribuições são geradas em relação a todas as classes que têm a pontuação de probabilidade maior ou igual a confidence_score_threshold_multilabel.

Chave de saída Descrição
visualizations Lista de imagens no formato de string base64 com tipo
Optional, String
attributions Lista de matrizes de várias dimensões com pontuações de atribuição de pixel em cada classe, onde cada matriz de várias dimensões tem a forma [3, valid_crop_size, valid_crop_size]
Optional, List

Aviso

Ao gerar explicações no ponto de extremidade online, selecione apenas algumas classes de acordo com a pontuação de confiança para evitar problemas de tempo limite no ponto de extremidade ou use o ponto de extremidade com o tipo de instância de GPU. Para gerar explicações para um grande número de classes na classificação de vários rótulos, consulte o notebook de pontuação em lote (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]]],
                        .
                        .
                        .
                       ]
    }
]

Detecção de objetos

Aviso

Não há suporte para XAI. Portanto, apenas as pontuações são retornadas. Para obter um exemplo de pontuação, consulte a seção de pontuação online.

Segmentação de instâncias

Aviso

Não há suporte para XAI. Portanto, apenas as pontuações são retornadas. Para obter um exemplo de pontuação, consulte a seção de pontuação online.

Observação

As imagens usadas neste artigo são do grupo de dados Objects, direitos autorais © Microsoft Corporation e estão disponíveis em computervision-recipes/01_training_introduction.ipynb na Licença MIT.

Próximas etapas