使用自動化機器學習來定型電腦視覺模型的資料結構描述

  • 發行項

適用於：Azure CLI ml 延伸模組 v2 (目前)Python SDK azure-ai-ml v2 (目前)

了解如何格式化 JSONL 檔案，以針對定型和推斷期間的電腦視覺工作獲得自動化 ML 實驗中的資料耗用量。

定型的資料結構描述

影像的 Azure Machine Learning AutoML 需要在 JSONL (JSON 行) 格式中準備輸入影像資料。 本節說明影像分類多類別、影像分類多標籤、物件偵測和執行個體分割的輸入資料格式或結構描述。 我們也會提供最後定型或驗證 JSON 行檔案的範例。

影像分類 (二進位/多類別)

每個 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",
}
Key 描述 範例
image_url Azure Machine Learning 資料存放區中的影像位置。
my-subscription-id 必須由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱。 同樣地，應該分別以資源群組名稱、工作區名稱和資料存放區名稱來取代 my-resource-group、my-workspace、my-datastore。
path_to_image 應該是資料存放區上映像的完整路徑。
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 映像詳細資料
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format 影像類型 (支援 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 影像的寬度
Optional, String or Positive Integer		 "400px" or 400
height 影像的高度
Optional, String or Positive Integer		 "200px" or 200
label 影像的類別/標籤
Required, String		 "cat"

多類別影像分類的 JSONL 檔案範例：

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

影像分類多類別的影像範例。

影像分類多標籤

以下是在影像分類的每個 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_1",
      "class_name_2",
      "class_name_3",
      "...",
      "class_name_n"
        
   ]
}
Key 描述 範例
image_url Azure Machine Learning 資料存放區中的影像位置。
my-subscription-id 必須由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱。 同樣地，應該分別以資源群組名稱、工作區名稱和資料存放區名稱來取代 my-resource-group、my-workspace、my-datastore。
path_to_image 應該是資料存放區上映像的完整路徑。
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 映像詳細資料
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format 影像類型 (支援 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 影像的寬度
Optional, String or Positive Integer		 "400px" or 400
height 影像的高度
Optional, String or Positive Integer		 "200px" or 200
label 影像中的類別/標籤清單
Required, List of Strings		 ["cat","dog"]

影像分類多標籤的 JSONL 檔案範例：

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

影像分類多標籤的影像範例。

物件偵測

以下為用於物件偵測的範例 JSONL 檔案。

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

在這裡，

  • xmin = 週框方塊左上角的 x 座標
  • ymin = 週框方塊左上角的 y 座標
  • xmax = 週框方塊右下角的 x 座標
  • ymax = 週框方塊右下角的 y 座標
Key 描述 範例
image_url Azure Machine Learning 資料存放區中的影像位置。
my-subscription-id 必須由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱。 同樣地，應該分別以資源群組名稱、工作區名稱和資料存放區名稱來取代 my-resource-group、my-workspace、my-datastore。
path_to_image 應該是資料存放區上映像的完整路徑。
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 映像詳細資料
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format 影像類型 (支援 Pillow 程式庫中所有可用的影像格式。但針對 YOLO，只有 opencv 允許的影像格式可受到支援)
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 影像的寬度
Optional, String or Positive Integer		 "499px" or 499
height 影像的高度
Optional, String or Positive Integer		 "665px" or 665
label (外部金鑰) 週框方塊清單，其中每個方塊都是 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 (內部金鑰) 週框方塊中物件的類別/標籤
Required, String		 "cat"
topX 週框方塊的左上角 x 座標和影像寬度的比率
Required, Float in the range [0,1]		 0.260
topY 週框方塊的左上角 y 座標和影像高度的比率
Required, Float in the range [0,1]		 0.406
bottomX 週框方塊的右下角 x 座標和影像寬度的比率
Required, Float in the range [0,1]		 0.735
bottomY 週框方塊的右下角 y 座標和影像高度的比率
Required, Float in the range [0,1]		 0.701
isCrowd 指出週框方塊是否在物件的範圍週圍。 如果設定了這個特殊旗標，我們會在計算計量時略過這個特定的週框方塊。
Optional, Bool		 0

用於物件偵測的 JSONL 檔案範例：

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

物件偵測的影像範例。

執行個體分割

針對執行個體分割，自動 ML 僅支援多邊形做為輸入和輸出，不支援遮罩。

以下是 JSONL 檔案範例，例如分割。

{
   "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"]]
      }
   ]
}
Key 描述 範例
image_url Azure Machine Learning 資料存放區中的影像位置。
my-subscription-id 必須由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱。 同樣地，應該分別以資源群組名稱、工作區名稱和資料存放區名稱來取代 my-resource-group、my-workspace、my-datastore。
path_to_image 應該是資料存放區上映像的完整路徑。
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 映像詳細資料
Optional, Dictionary		 "image_details":{"format": "jpg", "width": "400px", "height": "258px"}
format 映像類型
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 影像的寬度
Optional, String or Positive Integer		 "499px" or 499
height 影像的高度
Optional, String or Positive Integer		 "665px" or 665
label (外部金鑰) 遮罩清單，其中每個遮罩都是 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 (內部金鑰) 遮罩中物件的類別/標籤
Required, String		 "cat"
isCrowd 指出遮罩是否在物件的範圍週圍
Optional, Bool		 0
polygon 物件的多邊形座標
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]]

執行個體分割的 JSONL 檔案範例：

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

執行個體分割的影像範例。

線上評分的資料結構描述

在本節中，我們會記錄在使用已部署的模型時進行預測所需的輸入資料格式。

輸入格式

下列 JSON 是使用工作特定模型端點在任何工作上產生預測所需的輸入格式。

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

此 json 是具有外部索引鍵 input_data 和內部索引鍵 columns 的字典，data 如下表所述。 該端點接受上述格式的 json 字串，並將它轉換成評分指令碼所需的樣本資料框架。 json request_json["input_data"]["data"] 區段中的每一個輸入影像都是 base64 編碼的字串。

Key 描述
input_data
(外部金鑰)		 它是 json 要求中的外部索引鍵。 input_data 是接受輸入影像樣本的字典
Required, Dictionary
columns
(內部金鑰)		 用來建立資料框架的資料行名稱。 它只接受一個含 image 的資料行作為資料行名稱。
Required, List
data
(內部金鑰)		 base64 編碼影像的清單
Required, List

部署 mlflow 模型之後，我們可以使用下列程式碼片段來取得所有工作的預測。

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

輸出格式

根據工作類型而定，在模型端點上所做的預測會遵循不同的結構。 本節將探索多類別、多重標籤影像分類、物件偵測和執行個體分割工作的輸出資料格式。

當輸入要求包含一個影像時，適用下列架構。

影像分類 (二進位/多類別)

影像分類的端點會傳回資料集中的所有標籤，並以下列格式傳回輸入影像的機率分數。 visualizations 和 attributions 與可解釋性有關，而且當要求只用于評分時，這些索引鍵將不會包含在輸出中。 如需影像分類之可解釋性輸入和輸出架構的詳細資訊，請參閱 影像分類的說明一節。

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

影像分類多標籤

針對影像分類多標籤，模型端點會傳回標籤及其機率。 visualizations 和 attributions 與可解釋性有關，而且當要求只用于評分時，這些索引鍵將不會包含在輸出中。 如需多重標籤分類的可解釋性輸入和輸出架構的詳細資訊，請參閱 影像分類多標籤的說明性一節。

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

物件偵測

物件偵測模型會傳回多個方塊，其調整的左上角和右下角座標，以及方塊標籤和信賴分數。

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

執行個體分割

在執行個體分割中，輸出包含多個方塊，其調整的左上角和右下角座標、標籤、信賴分數和多邊形 (非遮罩)。 在這裡，多邊形值的格式與我們在 架構一節中所討論的格式相同。

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

線上評分和說明性的資料格式 (XAI)

重要

這些設定目前處於公開預覽狀態。 雖已提供，但沒有服務等級協定。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

警告

只有多重類別分類和多重標籤分類才支援可解釋性。 在線上端點上產生說明時，如果您遇到逾時問題，請使用 批次評分筆記本 (SDK v1) 來產生說明。

在本節中，我們會記錄進行預測所需的輸入資料格式，並使用已部署的模型來產生預測類別/類別的說明。 說明性不需要個別的部署。 線上評分的相同端點可用來產生說明。 我們只需要在輸入架構中傳遞一些額外的可解釋性相關參數，並取得說明和/或屬性分數矩陣的視覺效果， (圖元層級說明) 。

支援的可解釋性方法：

XAI) 輸入格式 (

支援下列輸入格式，以使用工作特定的模型端點，針對任何分類工作產生預測和說明。 部署模型之後，我們可以使用下列架構來取得預測和說明。

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

除了映射之外，輸入架構中還需要兩個額外的參數 (model_explainability 和 xai_parameters) 來產生說明。

Key 描述 預設值
image_base64 base64 格式的輸入影像
Required, String		 -
model_explainability 是否要產生說明，還是只產生評分
Optional, Bool		 False
xai_parameters 如果 model_explainability 為 True，則 xai_parameters 為字典，其中包含與 xai_algorithm 、 visualizationsattributions 詢問索引鍵的可解釋性演算法相關參數。
Optional, Dictionary
如果未 xai_parameters 傳遞，則 xrai 說明性演算法會搭配其預設值使用		 {"xai_algorithm": "xrai", "visualizations": True, "attributions": False}
xai_algorithm 要使用的說明性演算法名稱。 支援的 XAI 演算法為 { xrai 、 integrated_gradients 、 guided_gradcamguided_backprop }
Optional, String		 xrai
visualizations 是否傳回說明的視覺效果。
Optional, Bool		 True
attributions 是否要傳回特徵屬性。
Optional, Bool		 False
confidence_score_threshold_multilabel 要選取最上層類別的信賴分數閾值，以在 多標籤分類中產生說明。
Optional, Float		 0.5

下表說明可解釋性的支援架構。

類型 結構描述
以 base64 格式推斷單一影像 索引 image_base64 鍵和值的字典是 base64 編碼影像，
model_explainability 具有 True 或 False 的索引鍵，以及 xai_parameters 具有 XAI 演算法特定參數的字典
Required, Json String
Works for one or more images

下列程式碼中定義的每個輸入影像 request_json 都是附加至清單 request_json["input_data"]["data"] 的 base64 編碼字串：

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)

XAI) (輸出格式

根據工作類型，在模型端點上進行的預測會遵循不同的架構。 本節描述多類別多標籤影像分類工作的輸出資料格式。

下列架構是針對兩個輸入影像的案例所定義。

影像分類 (二進位/多類別)

輸出架構與上述相同，不同之處在于， visualizations 如果要求中已將這些索引鍵設定 True 為 ，則會包含 和 attributions 索引鍵值。

如果 model_explainability 為 ， attributionsvisualizations 則會在輸入要求中設定為 True ，則輸出將會有 visualizations 和 attributions 。 下表說明這些參數的詳細資料。 視覺效果和屬性會針對具有最高機率分數的類別產生。

輸出索引鍵 描述
visualizations base64 字串格式的單一影像，類型為
Optional, String
attributions 具有圖形圖元屬性分數的多維度陣列 [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]]]
    }
]

影像分類多標籤

相較于多類別分類，多標籤分類的輸出架構唯一差異在於，每個影像中可以有多個類別可供產生說明。 因此，是 base64 影像字串的清單， visualizations 並根據 attributions (預設的每個選取類別 confidence_score_threshold_multilabel 列出屬性分數為 0.5) 。

如果 model_explainability 為 ， attributionsvisualizations 則會在輸入要求中設定為 True ，則輸出將會有 visualizations 和 attributions 。 下表說明這些參數的詳細資料。 視覺效果和屬性會針對所有機率分數大於或等於 confidence_score_threshold_multilabel 的類別產生。

輸出索引鍵 描述
visualizations base64 字串格式的影像清單，其類型為
Optional, String
attributions 針對每個類別具有圖元屬性分數的多維度陣列清單，其中每個多維度陣列都是圖形 [3, valid_crop_size, valid_crop_size]
Optional, List

警告

在線上端點上產生說明時，請務必只根據信賴分數選取少數類別，以避免端點上的逾時問題，或使用具有 GPU 實例類型的端點。 若要產生多標籤分類中大量類別的說明，請參閱 批次評分筆記本 (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]]],
                        .
                        .
                        .
                       ]
    }
]

物件偵測

警告

不支援 XAI。 因此，只會傳回分數。 如需評分範例，請參閱 線上評分一節。

執行個體分割

警告

不支援 XAI。 因此，只會傳回分數。 如需評分範例，請參閱 線上評分一節。

注意

本文中使用的影像來自 Fridge 物件資料集、© Microsoft Corporation 版權所有，並可在MIT 授權下的 computervision-recipes/01_training_introduction.ipynb 取得。

後續步驟