共用方式為

使用自動化機器學習來定型電腦視覺模型的數據架構

  • 發行項

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

瞭解如何在定型和推斷期間，格式化 JSONL 檔案，以在自動化 ML 實驗中用於電腦視覺工作的數據耗用量。

定型的數據架構

適用於影像的 Azure 機器學習 AutoML 需要以 JSONL （JSON Lines） 格式準備輸入影像數據。 本節說明影像分類多類別、影像分類多標籤、物件偵測和實例分割的輸入數據格式或架構。 我們也會提供最終定型或驗證 JSON Lines 檔案的範例。

影像類別 （二進位/多類別）

在每個 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",
}
關鍵 描述 範例
image_url Azure 機器學習 資料存放區中的映射位置。
my-subscription-id 需要由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱 這裡。 同樣地my-resource-group，my-workspacemy-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		 "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 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_1",
      "class_name_2",
      "class_name_3",
      "...",
      "class_name_n"
        
   ]
}
關鍵 描述 範例
image_url Azure 機器學習 資料存放區中的映射位置。
my-subscription-id 需要由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱 這裡。 同樣地my-resource-group，my-workspacemy-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		 "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 座標
關鍵 描述 範例
image_url Azure 機器學習 資料存放區中的映射位置。
my-subscription-id 需要由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱 這裡。 同樣地my-resource-group，my-workspacemy-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 支援影像類型（支援枕頭媒體櫃中所有可用的影像格式。但僅支援 opencv 允許的 YOLO 影像格式）
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"]]
      }
   ]
}
關鍵 描述 範例
image_url Azure 機器學習 資料存放區中的映射位置。
my-subscription-id 需要由映像所在的 Azure 訂用帳戶取代。 如需 Azure 訂用帳戶的詳細資訊，請參閱 這裡。 同樣地my-resource-group，my-workspacemy-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_datacolumns的字典，data如下表所述。 端點會接受上述格式的 json 字串，並將它轉換成評分腳本所需的範例數據框架。 json 區段中的每個輸入影像 request_json["input_data"]["data"] 都是 base64編碼字串。

關鍵 描述
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） 來產生說明。

關鍵 描述 預設值
image_base64 base64 格式的輸入影像
Required, String		 -
model_explainability 是要產生說明還是只產生評分
Optional, Bool		 False
xai_parameters 如果 model_explainability 為 True，則 xai_parameters 為包含具有 、 visualizations的可解釋性演算法相關參數xai_algorithm的字典，attributions請詢問索引鍵。
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為， attributions visualizations則會在輸入要求中設定為 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為， attributions visualizations則會在輸入要求中設定為 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。 因此，只會傳回分數。 如需評分範例，請參閱 在線評分一節。

注意

本文中使用的影像來自冰箱對象數據集、著作權 © Microsoft Corporation，並可在 MIT 授權下於 computervision-recipes/01_training_introduction.ipynb 取得。

下一步