設定特徵式解釋

注意：Vertex Explainable AI 已於 2026 年 3 月 16 日淘汰。2027 年 3 月 16 日起，您將無法再存取 Vertex Explainable AI。詳情請參閱淘汰項目頁面。

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

如要搭配 AutoML 表格模型使用 Vertex Explainable AI，則不需要進行任何設定；Vertex AI 會自動為 Vertex Explainable AI 設定模型。略過這份文件，並參閱「取得說明」。

何時及何處設定說明

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

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

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

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

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

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

部署模型或取得批次推論結果時，設定說明

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

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

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

在取得線上說明時覆寫設定

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

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

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

• 任何自訂訓練模型的輸入基準
• 圖片模型的視覺化設定
• ExplanationParameters 但method除外

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

匯入含有 explanationSpec 欄位的模型

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

TensorFlow 預先建構的容器

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

下列範例假設模型接受單一輸入特徵，這通常適用於序列 Keras 模型和許多其他 TensorFlow 模型。由於特徵是任意形狀的張量，因此實際上可以編碼許多資訊。當您要求說明時，Vertex Explainable AI 會提供張量中每個元素的歸因。

如果模型接受多個具名輸入張量，請在 inputs 中繼資料欄位新增對應項目。

如果是 TensorFlow 2 模型，則 ExplanationMetadata 為選用項目。如果省略，Vertex AI 會自動從模型推斷值，並使用張量名稱做為特徵名稱。這個筆記本示範如何匯入模型，而不使用 ExplanationMetadata。

Sampled Shapley

根據您要用來建立或匯入 Model 的工具，選取下列其中一個分頁標籤：

控制台

請按照指南使用 Google Cloud 控制台匯入模型。 到達「可解釋性」步驟時，請執行下列操作：

1. 選取「Sampled Shapely (for tabular models)」(Shapley 取樣 (適用於表格式模型)) 做為特徵歸因方法。

2. 將路徑計數設為要用於 Shapley 值取樣歸因方法的特徵排列組合數量。必須是介於 [1, 50] 之間的整數。

   值越高，近似誤差就越小，但運算量也越大。如果您不確定要使用哪個值，請嘗試 25。

3. 設定模型中的每個輸入特徵：

   注意：如果是 TensorFlow 2 模型，輸入特徵名稱為選填欄位。

   1. 填入輸入特徵名稱。

   2. 您也可以視需要新增一或多個輸入基準線。否則，Vertex Explainable AI 會選擇全為零值的預設輸入基準，這對圖片資料來說是黑色圖片。

   3. 如要匯入 TensorFlow 模型，請填寫下列額外輸入欄位：

      1. 填寫「輸入張量名稱」。

      2. 視需要填寫「索引張量名稱」和/或「稠密形狀張量名稱」。

      3. 您無法在這裡更新「模式」。系統會自動將其設為表格模型適用的 NUMERIC，或圖片模型適用的 IMAGE。

      4. 如果適用，請設定「編碼」欄位。如果未設定，預設值為 IDENTITY。

      5. 視需要設定「群組名稱」欄位。

4. 如要匯入 TensorFlow 模型，請指定輸出欄位：

   1. 設定特徵的「輸出名稱」。
   2. 設定特徵的「輸出張量名稱」。
   3. 如適用，請設定「索引顯示名稱對應」。
   4. 如適用，請設定「顯示名稱對應鍵」。

5. 設定完可解釋性設定後，請按一下「匯入」按鈕。

gcloud

1. 如果是 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 中新增 input baselines。否則，Vertex AI 會為 Model 選擇輸入基準。

2. 執行下列指令，建立支援 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 中新增 input baselines。否則，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 init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 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. 設定「視覺化類型」和「色碼圖」。

   2. 你可以保留「下方剪輯片段」、「上方剪輯片段」、「疊加類型」和「整數步驟數」的預設設定。

   進一步瞭解視覺化設定。

3. 設定用於特徵歸因期間預估路徑積分的步驟數。必須是介於 [1, 100] 之間的整數。

   值越高，近似誤差就越小，但運算量也越大。如果您不確定要使用哪個值，請嘗試 50。

4. 設定模型中的每個輸入特徵：

   注意：如果是 TensorFlow 2 模型，輸入特徵名稱為選填欄位。

   1. 填入輸入特徵名稱。

   2. 您也可以視需要新增一或多個輸入基準線。否則，Vertex Explainable AI 會選擇全為零值的預設輸入基準，這對圖片資料來說是黑色圖片。

   3. 如要匯入 TensorFlow 模型，請填寫下列額外輸入欄位：

      1. 填寫「輸入張量名稱」。

      2. 視需要填寫「索引張量名稱」和/或「稠密形狀張量名稱」。

      3. 您無法在這裡更新「模式」。系統會自動將其設為表格模型適用的 NUMERIC，或圖片模型適用的 IMAGE。

      4. 如果適用，請設定「編碼」欄位。如果未設定，預設值為 IDENTITY。

      5. 視需要設定「群組名稱」欄位。

5. 如要匯入 TensorFlow 模型，請指定輸出欄位：

   1. 設定特徵的「輸出名稱」。
   2. 設定特徵的「輸出張量名稱」。
   3. 如適用，請設定「索引顯示名稱對應」。
   4. 如適用，請設定「顯示名稱對應鍵」。

6. 設定完可解釋性設定後，請按一下「匯入」按鈕。

gcloud

1. 如果是 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：image (如果 Model 接受圖片做為輸入內容) 或 numeric (如果 Model 接受表格資料做為輸入內容)。預設值為 numeric。

   • VIZUALIZATION_OPTIONS：說明視覺化選項。如要瞭解如何填入這個欄位，請參閱「設定圖片資料的視覺化設定」。

     如果省略 modality 欄位或將 modality 欄位設為 numeric，請完全省略 visualization 欄位。

   • OUTPUT_NAME：模型輸出的任何好記名稱。
   • OUTPUT_TENSOR_NAME：TensorFlow 中的輸出張量名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。

   您可以選擇在 ExplanationMetadata 中新增 input baselines。否則，Vertex AI 會為 Model 選擇輸入基準。

2. 執行下列指令，建立支援 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：image (如果 Model 接受圖片做為輸入內容) 或 numeric (如果 Model 接受表格資料做為輸入內容)。預設值為 numeric。

• VIZUALIZATION_OPTIONS：說明視覺化選項。如要瞭解如何填入這個欄位，請參閱「設定圖片資料的視覺化設定」。

  如果省略 modality 欄位或將 modality 欄位設為 numeric，請完全省略 visualization 欄位。

• OUTPUT_NAME：模型輸出的任何好記名稱。
• OUTPUT_TENSOR_NAME：TensorFlow 中的輸出張量名稱。如要找出這個欄位的正確值，請參閱「搭配使用 TensorFlow 與 Vertex Explainable AI」。

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

您可以選擇在 ExplanationMetadata 中新增 input baselines。否則，Vertex AI 會為 Model 選擇輸入基準。

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

如果是 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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 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

XRAI

根據您要用來建立或匯入 Model 的工具，選取下列其中一個分頁標籤：

控制台

請按照指南使用 Google Cloud 控制台匯入模型。 到達「可解釋性」步驟時，請執行下列操作：

1. 在特徵歸因方法部分，選取「XRAI (適用於圖片分類模型)」。

2. 設定下列圖表選項：

   1. 設定「Color map」(色彩對應)。

   2. 你可以保留「下方剪輯片段」、「上方剪輯片段」、「疊加類型」和「整數步驟數」的預設設定。

      進一步瞭解視覺化設定。

3. 設定用於特徵歸因期間預估路徑積分的步驟數。必須是介於 [1, 100] 之間的整數。

   值越高，近似誤差就越小，但運算量也越大。如果您不確定要使用哪個值，請嘗試 50。

4. 設定模型中的每個輸入特徵：

   注意：如果是 TensorFlow 2 模型，輸入特徵名稱為選填欄位。

   1. 填入輸入特徵名稱。

   2. 您也可以視需要新增一或多個輸入基準線。否則，Vertex Explainable AI 會選擇全為零值的預設輸入基準，這對圖片資料來說是黑色圖片。

   3. 如要匯入 TensorFlow 模型，請填寫下列額外輸入欄位：

      1. 填寫「輸入張量名稱」。

      2. 視需要填寫「索引張量名稱」和/或「稠密形狀張量名稱」。

      3. 您無法在這裡更新「模式」。系統會自動將其設為表格模型適用的 NUMERIC，或圖片模型適用的 IMAGE。

      4. 如果適用，請設定「編碼」欄位。如果未設定，預設值為 IDENTITY。

      5. 視需要設定「群組名稱」欄位。

5. 如要匯入 TensorFlow 模型，請指定輸出欄位：

   1. 設定特徵的「輸出名稱」。
   2. 設定特徵的「輸出張量名稱」。
   3. 如適用，請設定「索引顯示名稱對應」。
   4. 如適用，請設定「顯示名稱對應鍵」。

6. 設定完可解釋性設定後，請按一下「匯入」按鈕。

gcloud

1. 如果是 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 中新增 input baselines。否則，Vertex AI 會為 Model 選擇輸入基準。

2. 執行下列指令，建立支援 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 中新增 input baselines。否則，Vertex AI 會為 Model 選擇輸入基準。

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

如果是 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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 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

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

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

下列範例假設模型接受單一 2D 矩陣做為輸入內容，這通常是 scikit-learn 和 XGBoost 模型的情況。當您要求說明時，Vertex Explainable AI 會提供輸入矩陣中每個元素的歸因。

根據您要用來建立或匯入 Model 的工具，選取下列其中一個分頁標籤：

控制台

請按照指南使用 Google Cloud 控制台匯入模型。 到達「可解釋性」步驟時，請執行下列操作：

1. 選取「Sampled Shapely (for tabular models)」(Shapley 取樣 (適用於表格式模型)) 做為特徵歸因方法。

2. 將路徑計數設為要用於 Shapley 值取樣歸因方法的特徵排列組合數量。必須是介於 [1, 50] 之間的整數。

   值越高，近似誤差就越小，但運算量也越大。如果您不確定要使用哪個值，請嘗試 25。

3. 設定模型中的每個輸入特徵：

   1. 填入輸入特徵名稱。

      如果模型構件未包含特徵名稱，Vertex AI 就無法將指定的輸入特徵名稱對應至模型。在這種情況下，您應該只提供一個輸入特徵，並使用任意好記的名稱，例如 input_features。在說明回應中，您會取得 N 維度的屬性清單，其中 N 是模型中的特徵數量，清單中的元素會與訓練資料集中的順序相同。

   2. 您也可以視需要新增一或多個輸入基準線。否則，Vertex Explainable AI 會選擇全為零值的預設輸入基準，這對圖片資料來說是黑色圖片。

4. 設定特徵的「輸出名稱」。

5. 設定完可解釋性設定後，請按一下「匯入」按鈕。

gcloud

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

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
       }
     }
   }
   

   更改下列內容：

   • FEATURE_NAME：輸入特徵的任何好記名稱。
   • OUTPUT_NAME：模型輸出的任何好記名稱。

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

2. 執行下列指令，建立支援 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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 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 接受表格資料做為輸入內容，並使用自訂容器提供預測結果，則可以設定使用抽樣 Shapley 歸因方法來產生說明。

注意： 如果您使用 Vertex AI 的預建容器來提供預測結果，則無法按照下列操作說明進行。您必須使用 Vertex AI 未代管的自訂容器映像檔，且該映像檔須符合自訂容器規定。

自訂預測伺服器必須接受並傳回批次推論。

判斷特徵和輸出名稱

在後續步驟中，您必須向 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。

注意： 下列範例假設模型具有單一輸入特徵。如果模型有多項功能 (如本節所述)，請在 inputs 欄位中新增對應項目。

決定輸出名稱

如果 Model 傳回的每個線上預測例項都含有鍵控輸出，則該鍵就是輸出名稱。

舉例來說，假設 Model 會以以下格式傳回每項預測：

{
  "scores": <value>
}

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

如果 Model 傳回未加註索引鍵的預測結果，則輸出名稱可使用任何容易記住的字串。舉例來說，如果 Model 為每項預測傳回陣列或純量，就適用這項規定。

正在建立「Model」

根據您要用來建立或匯入 Model 的工具，選取下列其中一個分頁標籤：

控制台

請按照指南使用 Google Cloud 控制台匯入模型。 到達「可解釋性」步驟時，請執行下列操作：

1. 選取「Sampled Shapely (for tabular models)」(Shapley 取樣 (適用於表格式模型)) 做為特徵歸因方法。

2. 將路徑計數設為要用於 Shapley 值取樣歸因方法的特徵排列組合數量。必須是介於 [1, 50] 之間的整數。

   值越高，近似誤差就越小，但運算量也越大。如果您不確定要使用哪個值，請嘗試 25。

3. 設定模型中的每個輸入特徵：

   1. 填入輸入特徵名稱。

      如果模型構件未包含特徵名稱，Vertex AI 就無法將指定的輸入特徵名稱對應至模型。在這種情況下，您應該只提供一個輸入特徵，並使用任意好記的名稱，例如 input_features。在說明回應中，您會取得 N 維度的屬性清單，其中 N 是模型中的特徵數量，清單中的元素會與訓練資料集中的順序相同。

   2. 您也可以視需要新增一或多個輸入基準線。否則，Vertex Explainable AI 會選擇全為零值的預設輸入基準，這對圖片資料來說是黑色圖片。

4. 設定特徵的「輸出名稱」。

5. 設定完可解釋性設定後，請按一下「匯入」按鈕。

gcloud

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

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {}
     },
     "outputs": {
       "OUTPUT_NAME": {}
     }
   }
   

   更改下列內容：

   • FEATURE_NAME：功能名稱，如本文「判斷功能名稱」一節所述。
   • OUTPUT_NAME：輸出內容的名稱，如本文「判斷輸出名稱」一節所述。

   您可以選擇在 ExplanationMetadata 中新增 input baselines。否則，Vertex AI 會為 Model 選擇輸入基準。

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

2. 執行下列指令，建立支援 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 中新增 input baselines。否則，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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 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 部署至 Endpoint，並取得說明。