本頁面由 Cloud Translation API 翻譯而成。

設定特徵式解釋

如要搭配自訂訓練模型使用 Vertex Explainable AI，您必須在建立要用於要求說明的 Model 資源、部署模型，或提交批次說明工作時，設定特定選項。本頁面將說明如何設定這些選項。

如果您想搭配 AutoML 表格型模型使用 Vertex Explainable AI，則無需執行任何設定；Vertex AI 會自動為 Vertex Explainable AI 設定模型。請略過這份文件，改為閱讀取得說明。

設定說明的時間和位置

您可以在建立或匯入模型時設定說明。您也可以為先前建立的模型設定說明，即使先前未設定說明也沒關係。

建立或匯入模型時設定說明

建立或匯入 Model 時，您可以使用 Model 的 explanationSpec 欄位，為所有說明設定預設設定。

您可以透過下列方式，在 Vertex AI 中建立自訂訓練的 Model：

將 Model 匯入或註冊至 Vertex AI Model Registry
建立可匯入 Model 的自訂 TrainingPipeline 資源。
建立 BigQuery ML 模型，並在 CREATE MODEL 語法中指定選用的 model_registry 設定。這項設定會自動將模型註冊至 Vertex AI Model Registry，並設定其 explanationSpec。

無論是哪種情況，您都可以設定 Model 以支援 Vertex Explainable AI。本文件的範例假設您要匯入 Model。如要使用 TrainingPipeline 建立自訂訓練的 Model，請在 TrainingPipeline 的 modelToUpload 欄位中，使用本文所述的設定。

在部署模型或取得批次預測時設定說明

將 Model 部署至 Endpoint 資源時，您可以：

設定說明：模型是否先前已設定說明。如果您原本不打算取得解釋 (並在建立模型時省略 explanationSpec 欄位)，但之後決定要取得模型的解釋，或是想要覆寫部分解釋設定，這項功能就很實用。
停用說明。如果模型已設定為提供解釋，但您不打算從端點取得解釋，這項功能就很實用。如要在部署模型至端點時停用說明，請在 Cloud 控制台中清除「Explainability」(可解釋性) 選項，或將 DeployedModel.disableExplanations 設為 true。

同樣地，當您從 Model 取得批次預測結果時，可以填入 BatchPredictionJob.explanationSpec 欄位來設定說明，或是將 BatchPredictionJob.generateExplanation 設為 false 來停用說明。

取得線上說明時覆寫設定

無論您是否已建立或匯入含有說明設定的 Model，以及是否在部署期間設定說明設定，您都可以在取得線上說明時覆寫 Model 的初始說明設定。

將 explain 要求傳送至 Vertex AI 時，您可以覆寫先前為 Model 或 DeployedModel 設定的部分說明設定。

在 explain 要求中，您可以覆寫下列欄位：

任何自訂訓練模型的輸入基準
圖像模型的視覺化設定
ExplanationParameters except method

在說明要求的 explanationSpecOverride 欄位中覆寫這些設定。

匯入含有 `explanationSpec` 欄位的模型

視您是使用預先建構的容器還是自訂容器提供預測結果而定，請為 ExplanationSpec 指定略有不同的詳細資料。請選取與您使用的容器相符的分頁：

TensorFlow 預先建構的容器

您可以使用下列任一歸因方法為 Vertex Explainable AI 進行歸因。請參閱特徵歸因方法比較，為您的 Model 選取合適的方法：

Sampled Shapley

請根據您要使用哪個工具建立或匯入 Model，選取下列任一分頁：

控制台

請按照這份指南的說明，使用 Google Cloud 控制台匯入模型。在「可解釋性」步驟中，請執行下列操作：

選取特徵歸因方法時，請選取「Sampled Shapely (適用於表格式模型)」。
將路徑計數設為要用於 Shapley 值取樣歸因方法的特徵排列組合數量。此值必須是介於 [1, 50] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
設定模型中的每個輸入特徵：

注意：對於 TensorFlow 2 模型，輸入特徵名稱為選填欄位。
1. 填入輸入特徵名稱。
2. 您可以視需要新增一或多個輸入基準。否則，Vertex Explainable AI 會選擇預設輸入基準，即全零值，也就是圖像資料的黑色圖片。
3. 如果您要匯入 TensorFlow 模型，則會有其他輸入欄位：
  1. 填寫「輸入張量名稱」。
  2. 如適用，請填入「索引張量名稱」和/或「稠密形狀張量名稱」。
  3. Modality 無法在此更新。對於表格模型，系統會自動將其設為 NUMERIC；對於圖像模型，則會設為 IMAGE。
  4. 視情況設定「Encoding」欄位。如果未設定，預設值為 IDENTITY。
  5. 視需要設定「Group name」欄位。
如果要匯入 TensorFlow 模型，請指定輸出欄位：
1. 設定特徵的「Output name」。
2. 設定特徵的「輸出張量名稱」。
3. 視情況設定索引顯示名稱對應。
4. 視情況設定顯示名稱對應鍵。
設定可解釋性設定完成後，請按一下「Import」按鈕。

gcloud

在 TensorFlow 2 中，ExplanationMetadata 為選用項目。
將下列 ExplanationMetadata 寫入本機環境中的 JSON 檔案。檔案名稱不拘，但在本例中，請將檔案命名為 explanation-metadata.json：

explanation-metadata.json
```
{
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}
```
更改下列內容：
- FEATURE_NAME：輸入功能的任何易記名稱。
- INPUT_TENSOR_NAME：TensorFlow 中輸入張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
- OUTPUT_NAME：模型輸出的任何易記名稱。
- OUTPUT_TENSOR_NAME：TensorFlow 中輸出張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。
執行下列指令，建立支援 Vertex Explainable AI 的 Model 資源。畫面上會醒目顯示與 Vertex Explainable AI 最相關的標記。
```
gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json
```
更改下列內容：
- IMAGE_URI：TensorFlow 預先建構的用於提供預測結果的容器的 URI。
- PATH_COUNT：用於取樣 Shapley 歸因方法的特徵排列組合數量。必須是介於 [1, 50] 的範圍內的整數。
  
  較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

REST

使用任何要求資料之前，請先替換以下項目：

IMAGE_URI：TensorFlow 預先建構的用於提供預測結果的容器的 URI。
PATH_COUNT：用於取樣 Shapley 歸因方法的特徵排列組合數量。必須是介於 [1, 50] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
FEATURE_NAME：輸入功能的任何易記名稱。
INPUT_TENSOR_NAME：TensorFlow 中輸入張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
OUTPUT_NAME：模型輸出的任何易記名稱。
OUTPUT_TENSOR_NAME：TensorFlow 中輸出張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。

如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。

對於 TensorFlow 2 模型，metadata 欄位為選填欄位。如果省略，Vertex AI 會自動從模型推斷 inputs 和 outputs。

HTTP 方法和網址：

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

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

注意：以下指令假設您已使用使用者帳戶登入 gcloud CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 Cloud Shell，後者會自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

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

積分梯度

請根據您要使用哪個工具建立或匯入 Model，選取下列任一分頁：

控制台

請按照這份指南的說明，使用 Google Cloud 控制台匯入模型。在「可解釋性」步驟中，請執行下列操作：

請根據模型的適合性，選取特徵歸因方法，例如「積分梯度 (適用於表格式模型)」或「積分梯度 (適用於圖片分類模型)」。
如果您要匯入圖片分類模型，請按照下列步驟操作：
1. 設定「視覺化類型」和「色彩圖」。
2. 您可以保留「下方剪輯片段」、「上方剪輯片段」、「重疊類型」和「整合步驟數量」的預設設定。
進一步瞭解視覺化設定。
設定在功能歸因期間用於預估路徑積分的步驟數。此值必須是介於 [1, 100] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 50。
設定模型中的每個輸入特徵：

注意：對於 TensorFlow 2 模型，輸入特徵名稱為選填欄位。
1. 填入輸入特徵名稱。
2. 您可以視需要新增一或多個輸入基準。否則，Vertex Explainable AI 會選擇預設輸入基準，即全零值，也就是圖像資料的黑色圖片。
3. 如果您要匯入 TensorFlow 模型，則會有其他輸入欄位：
  1. 填寫「輸入張量名稱」。
  2. 如適用，請填入「索引張量名稱」和/或「稠密形狀張量名稱」。
  3. Modality 無法在此更新。對於表格模型，系統會自動將其設為 NUMERIC；對於圖像模型，則會設為 IMAGE。
  4. 視情況設定「Encoding」欄位。如果未設定，預設值為 IDENTITY。
  5. 視需要設定「Group name」欄位。
如果要匯入 TensorFlow 模型，請指定輸出欄位：
1. 設定特徵的「Output name」。
2. 設定特徵的「輸出張量名稱」。
3. 視情況設定索引顯示名稱對應。
4. 視情況設定顯示名稱對應鍵。
設定可解釋性設定完成後，請按一下「Import」按鈕。

gcloud

在 TensorFlow 2 中，ExplanationMetadata 為選用項目。
將下列 ExplanationMetadata 寫入本機環境中的 JSON 檔案。檔案名稱不拘，但在本例中，請將檔案命名為 explanation-metadata.json：

explanation-metadata.json
```
{
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "MODALITY",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}
```
更改下列內容：
- FEATURE_NAME：輸入功能的任何易記名稱。
- INPUT_TENSOR_NAME：TensorFlow 中輸入張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
- MODALITY：如果 Model 接受圖片做為輸入內容，則為 image；如果 Model 接受表格資料做為輸入內容，則為 numeric。預設值為 numeric。
- VIZUALIZATION_OPTIONS：用於視覺化說明的選項。如要瞭解如何填入這個欄位，請參閱「為圖像資料設定視覺化設定」。
  
  如果您略過 modality 欄位或將 modality 欄位設為 numeric，請完全略過 visualization 欄位。
- OUTPUT_NAME：模型輸出的任何易記名稱。
- OUTPUT_TENSOR_NAME：TensorFlow 中輸出張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。
執行下列指令，建立支援 Vertex Explainable AI 的 Model 資源。畫面上會醒目顯示與 Vertex Explainable AI 最相關的標記。
```
gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=integrated-gradients \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json
```
更改下列內容：
- IMAGE_URI：TensorFlow 預先建構的用於提供預測結果的容器的 URI。
- STEP_COUNT：在功能歸因期間，用於近似路徑積分的步驟數。必須是介於 [1, 100] 的範圍內的整數。
  
  較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 50。
如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

您可以選擇新增標記來設定漸層的 SmoothGrad 近似值。

REST

使用任何要求資料之前，請先替換以下項目：

IMAGE_URI：TensorFlow 預先建構的用於提供預測結果的容器的 URI。
STEP_COUNT：在功能歸因期間，用於近似路徑積分的步驟數。必須是介於 [1, 100] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 50。
FEATURE_NAME：輸入功能的任何易記名稱。
INPUT_TENSOR_NAME：TensorFlow 中輸入張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
MODALITY：如果 Model 接受圖片做為輸入內容，則為 image；如果 Model 接受表格資料做為輸入內容，則為 numeric。預設值為 numeric。
VIZUALIZATION_OPTIONS：用於視覺化說明的選項。如要瞭解如何填入這個欄位，請參閱「為圖像資料設定視覺化設定」。

如果您略過 modality 欄位或將 modality 欄位設為 numeric，請完全略過 visualization 欄位。
OUTPUT_NAME：模型輸出的任何易記名稱。
OUTPUT_TENSOR_NAME：TensorFlow 中輸出張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。

如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。

您可以選擇新增欄位，將 SmoothGrad 的梯度近似值設定為 ExplanationParameters。

對於 TensorFlow 2 模型，metadata 欄位為選填欄位。如果省略，Vertex AI 會自動從模型推斷 inputs 和 outputs。

HTTP 方法和網址：

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

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

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

XRAI

請根據您要使用哪個工具建立或匯入 Model，選取下列任一分頁：

控制台

請按照這份指南的說明，使用 Google Cloud 控制台匯入模型。在「可解釋性」步驟中，請執行下列操作：

選取「特徵歸因方法」時，請選取「XRAI (適用於圖片分類模型)」。
設定下列視覺化選項：
1. 設定色彩圖。
2. 您可以保留「下方剪輯片段」、「上方剪輯片段」、「重疊類型」和「整合步驟數量」的預設設定。
  
  進一步瞭解視覺化設定。
設定在功能歸因期間用於預估路徑積分的步驟數。此值必須是介於 [1, 100] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 50。
設定模型中的每個輸入特徵：

注意：對於 TensorFlow 2 模型，輸入特徵名稱為選填欄位。
1. 填入輸入特徵名稱。
2. 您可以視需要新增一或多個輸入基準。否則，Vertex Explainable AI 會選擇預設輸入基準，即全零值，也就是圖像資料的黑色圖片。
3. 如果您要匯入 TensorFlow 模型，則會有其他輸入欄位：
  1. 填寫「輸入張量名稱」。
  2. 如適用，請填入「索引張量名稱」和/或「稠密形狀張量名稱」。
  3. Modality 無法在此更新。對於表格模型，系統會自動將其設為 NUMERIC；對於圖像模型，則會設為 IMAGE。
  4. 視情況設定「Encoding」欄位。如果未設定，預設值為 IDENTITY。
  5. 視需要設定「Group name」欄位。
如果要匯入 TensorFlow 模型，請指定輸出欄位：
1. 設定特徵的「Output name」。
2. 設定特徵的「輸出張量名稱」。
3. 視情況設定索引顯示名稱對應。
4. 視情況設定顯示名稱對應鍵。
設定可解釋性設定完成後，請按一下「Import」按鈕。

gcloud

在 TensorFlow 2 中，ExplanationMetadata 為選用項目。
將下列 ExplanationMetadata 寫入本機環境中的 JSON 檔案。檔案名稱不拘，但在本例中，請將檔案命名為 explanation-metadata.json：

explanation-metadata.json
```
{
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "image",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}
```
更改下列內容：
- FEATURE_NAME：輸入功能的任何易記名稱。
- INPUT_TENSOR_NAME：TensorFlow 中輸入張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
- VIZUALIZATION_OPTIONS：用於視覺化說明的選項。如要瞭解如何填入這個欄位，請參閱「為圖像資料設定視覺化設定」。
- OUTPUT_NAME：模型輸出的任何易記名稱。
- OUTPUT_TENSOR_NAME：TensorFlow 中輸出張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。
執行下列指令，建立支援 Vertex Explainable AI 的 Model 資源。畫面上會醒目顯示與 Vertex Explainable AI 最相關的標記。
```
gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=xrai \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json
```
更改下列內容：
- IMAGE_URI：TensorFlow 預先建構的用於提供預測結果的容器的 URI。
- STEP_COUNT：在功能歸因期間，用於近似路徑積分的步驟數。必須是介於 [1, 100] 的範圍內的整數。
  
  較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 50。
如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

您可以選擇新增標記來設定漸層的 SmoothGrad 近似值。

REST

使用任何要求資料之前，請先替換以下項目：

IMAGE_URI：TensorFlow 預先建構的用於提供預測結果的容器的 URI。
STEP_COUNT：在功能歸因期間，用於近似路徑積分的步驟數。必須是介於 [1, 100] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 50。
FEATURE_NAME：輸入功能的任何易記名稱。
INPUT_TENSOR_NAME：TensorFlow 中輸入張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。
VIZUALIZATION_OPTIONS：用於視覺化說明的選項。如要瞭解如何填入這個欄位，請參閱「為圖像資料設定視覺化設定」。
OUTPUT_NAME：模型輸出的任何易記名稱。
OUTPUT_TENSOR_NAME：TensorFlow 中輸出張量的名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。

如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。

您可以選擇新增欄位，將 SmoothGrad 的梯度近似值設定為 ExplanationParameters。

對於 TensorFlow 2 模型，metadata 欄位為選填欄位。如果省略，Vertex AI 會自動從模型推斷 inputs 和 outputs。

HTTP 方法和網址：

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

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

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

scikit-learn 和 XGBoost 預先建構的容器

如果 Model 接受表格資料做為輸入內容，並使用預先建構的 scikit-learn 或 XGBoost 預測容器提供預測結果，您可以將其設定為使用取樣 Shapley 歸因方法來進行說明。

請根據您要使用哪個工具建立或匯入 Model，選取下列任一分頁：

控制台

請按照這份指南的說明，使用 Google Cloud 控制台匯入模型。在「可解釋性」步驟中，請執行下列操作：

選取特徵歸因方法時，請選取「Sampled Shapely (適用於表格式模型)」。
將路徑計數設為要用於 Shapley 值取樣歸因方法的特徵排列組合數量。此值必須是介於 [1, 50] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
設定模型中的每個輸入特徵：
1. 填入輸入特徵名稱。
  
  如果模型構件不包含特徵名稱，Vertex AI 就無法將指定的輸入特徵名稱對應至模型。在這種情況下，您應只提供一個輸入地圖項目，並使用任意好記的名稱，例如 input_features。在說明回應中，您會收到 N 維度的歸因清單，其中 N 是模型中的特徵數量，清單中的元素會以與訓練資料集相同的順序顯示。
2. 您可以視需要新增一或多個輸入基準。否則，Vertex Explainable AI 會選擇預設輸入基準，即全零值，也就是圖像資料的黑色圖片。
設定特徵的「Output name」。
設定可解釋性設定完成後，請按一下「Import」按鈕。

gcloud

將下列 ExplanationMetadata 寫入本機環境中的 JSON 檔案。檔案名稱不拘，但在本例中，請將檔案命名為 explanation-metadata.json：

explanation-metadata.json
```
{
  "inputs": {
    "FEATURE_NAME": {
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
    }
  }
}
```
更改下列內容：
- FEATURE_NAME：輸入功能的任何易記名稱。
- OUTPUT_NAME：模型輸出的任何易記名稱。
如果您指定輸入基準值，請確認這些基準值與模型的輸入值相符，通常是 2D 矩陣清單。否則，輸入基準的預設值是輸入形狀的 0 值 2D 矩陣。
執行下列指令，建立支援 Vertex Explainable AI 的 Model 資源。畫面上會醒目顯示與 Vertex Explainable AI 最相關的標記。
```
gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json
```
更改下列內容：
- IMAGE_URI：用於提供預測結果的預先建構容器的 URI。
- PATH_COUNT：用於取樣 Shapley 歸因方法的特徵排列組合數量。必須是介於 [1, 50] 的範圍內的整數。
  
  較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
如要瞭解其他預留位置的適當值，請參閱 upload 和匯入模型。

REST

使用任何要求資料之前，請先替換以下項目：

IMAGE_URI：用於提供預測結果的預先建構容器的 URI。
PATH_COUNT：用於取樣 Shapley 歸因方法的特徵排列組合數量。必須是介於 [1, 50] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
FEATURE_NAME：輸入功能的任何易記名稱。
OUTPUT_NAME：模型輸出的任何易記名稱。

如要瞭解其他預留位置的適當值，請參閱 upload 和匯入模型。

如果您指定輸入基準值，請確認這些基準值與模型的輸入值相符，通常是 2D 矩陣清單。否則，輸入基準的預設值是輸入形狀的 0 值 2D 矩陣。

HTTP 方法和網址：

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

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

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

自訂容器

如果 Model 接受表格資料做為輸入內容，並使用自訂容器提供預測結果，您可以將其設為使用取樣 Shapley 歸因方法來提供說明。

判斷功能和輸出名稱

在後續步驟中，您必須向 Vertex AI 提供 Model 預期的輸入特徵名稱。您還必須指定 Model 預測結果的輸出用途。

判斷功能名稱

如果 Model 預期每個 input 例項都具有特定頂層鍵，則這些鍵就是功能名稱。

舉例來說，假設 Model 預期每個輸入例項都採用下列格式：

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

在本例中，功能名稱為 length 和 width。即使這些欄位的值包含巢狀清單或物件，您仍只需要 length 和 width 這兩個鍵來執行後續步驟。當您要求說明時，Vertex Explainable AI 會為特徵的每個巢狀元素提供歸因。

如果 Model 預期未加密的輸入內容，Vertex Explainable AI 會將 Model 視為單一特徵。您可以使用任何容易記住的字串做為功能名稱。

舉例來說，假設 Model 預期每個輸入例項都採用下列格式：

[
  <value>,
  <value>
]

在這種情況下，請向 Vertex Explainable AI 提供您選擇的單一功能名稱，例如 dimensions。

決定輸出名稱

如果 Model 傳回每個線上預測例項，並附上帶有索引鍵的輸出內容，則該索引鍵就是輸出名稱。

舉例來說，請考慮以以下格式傳回每個預測結果的 Model：

{
  "scores": <value>
}

在本例中，輸出名稱為 scores。如果 scores 欄位的值是陣列，則在您取得說明時，Vertex Explainable AI 會針對每個預測中最高值的元素傳回特徵歸因。如要將 Vertex Explainable AI 設為為輸出欄位的其他元素提供特徵歸因，您可以指定 ExplanationParameters 的 topK 或 outputIndices 欄位。不過，本文件的範例並未展示這些選項。

如果 Model 傳回未鍵入的預測結果，您可以使用任何好記的字串做為輸出名稱。舉例來說，如果 Model 為每個預測傳回陣列或標量，就會套用這項規定。

建立 `Model`

請根據您要使用哪個工具建立或匯入 Model，選取下列任一分頁：

控制台

請按照這份指南的說明，使用 Google Cloud 控制台匯入模型。在「可解釋性」步驟中，請執行下列操作：

選取特徵歸因方法時，請選取「Sampled Shapely (適用於表格式模型)」。
將路徑計數設為要用於 Shapley 值取樣歸因方法的特徵排列組合數量。此值必須是介於 [1, 50] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
設定模型中的每個輸入特徵：
1. 填入輸入特徵名稱。
  
  如果模型構件不包含特徵名稱，Vertex AI 就無法將指定的輸入特徵名稱對應至模型。在這種情況下，您應只提供一個輸入地圖項目，並使用任意好記的名稱，例如 input_features。在說明回應中，您會收到 N 維度的歸因清單，其中 N 是模型中的特徵數量，清單中的元素會以與訓練資料集相同的順序顯示。
2. 您可以視需要新增一或多個輸入基準。否則，Vertex Explainable AI 會選擇預設輸入基準，即全零值，也就是圖像資料的黑色圖片。
設定特徵的「Output name」。
設定可解釋性設定完成後，請按一下「Import」按鈕。

gcloud

將下列 ExplanationMetadata 寫入本機環境中的 JSON 檔案。檔案名稱不拘，但在本例中，請將檔案命名為 explanation-metadata.json：

explanation-metadata.json
```
{
  "inputs": {
    "FEATURE_NAME": {}
  },
  "outputs": {
    "OUTPUT_NAME": {}
  }
}
```
更改下列內容：
- FEATURE_NAME：功能名稱，請參閱本文件的「決定功能名稱」一節。
- OUTPUT_NAME：輸出內容的名稱，請參閱本文件的「決定輸出名稱」一節。
您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。

如果您指定輸入基準值，請確認這些基準值與模型的輸入值相符，通常是 2D 矩陣清單。否則，輸入基準的預設值是輸入形狀的 0 值 2D 矩陣。
執行下列指令，建立支援 Vertex Explainable AI 的 Model 資源。畫面上會醒目顯示與 Vertex Explainable AI 最相關的標記。
```
gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json
```
更改下列內容：
- PATH_COUNT：用於取樣 Shapley 歸因方法的特徵排列組合數量。必須是介於 [1, 50] 的範圍內的整數。
  
  較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

REST

使用任何要求資料之前，請先替換以下項目：

PATH_COUNT：用於取樣 Shapley 歸因方法的特徵排列組合數量。必須是介於 [1, 50] 的範圍內的整數。

較高的值雖然可能會減少近似值誤差，但需要的運算量也會增加。如果不確定要使用哪個值，請試試 25。
FEATURE_NAME：功能名稱，請參閱本文件的「決定功能名稱」一節。
OUTPUT_NAME：輸出內容的名稱，請參閱本文件的「決定輸出名稱」一節。

如要瞭解其他預留位置的適當值，請參閱 upload 和「匯入模型」。

您可以選擇將輸入基準新增至 ExplanationMetadata。否則，Vertex AI 會為 Model 選擇輸入基準。

HTTP 方法和網址：

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

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

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

後續步驟

將 Model 部署至 Endpoint，並取得解釋。

設定特徵式解釋 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

設定說明的時間和位置

建立或匯入模型時設定說明

在部署模型或取得批次預測時設定說明

取得線上說明時覆寫設定

匯入含有 explanationSpec 欄位的模型

TensorFlow 預先建構的容器

Sampled Shapley

控制台

gcloud

explanation-metadata.json

REST

curl

PowerShell

積分梯度

控制台

gcloud

explanation-metadata.json

REST

curl

PowerShell

XRAI

控制台

gcloud

explanation-metadata.json

REST

curl

PowerShell

scikit-learn 和 XGBoost 預先建構的容器

控制台

gcloud

explanation-metadata.json

REST

curl

PowerShell

自訂容器

判斷功能和輸出名稱

判斷功能名稱

決定輸出名稱

建立 Model

控制台

gcloud

explanation-metadata.json

REST

curl

PowerShell

後續步驟

設定特徵式解釋

匯入含有 `explanationSpec` 欄位的模型

`explanation-metadata.json`

`explanation-metadata.json`

`explanation-metadata.json`

`explanation-metadata.json`

建立 `Model`

`explanation-metadata.json`