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

設定以範例為基礎的解釋

如要使用範例式解釋，您必須在匯入或上傳 Model 資源至 Model Registry 時，指定 explanationSpec 來設定解釋。

接著，當您要求線上解釋時，可以在要求中指定 ExplanationSpecOverride，覆寫部分設定值。系統不支援批次解釋功能，因此您無法要求批次解釋。

本頁面說明如何設定及更新這些選項。

匯入或上傳模型時設定說明

開始之前，請確認您具備以下項目：

內含模型構件的 Cloud Storage 位置。您的模型必須是深層類神經網路 (DNN) 模型，您必須提供層的名稱或簽名，其輸出內容可用於潛在空間，或者您可以提供直接輸出嵌入資料 (潛在空間表示法) 的模型。這個潛在空間會擷取用於產生說明的示例表示法。
包含要為近似最近鄰搜尋建立索引的執行個體的 Cloud Storage 位置。詳情請參閱輸入資料規定。

主控台

請按照這份指南的說明，使用 Google Cloud 控制台匯入模型。

在「可解釋性」分頁中，選取「範例式說明」，然後填入欄位。

如需瞭解各欄位的相關資訊，請參閱 Google Cloud 主控台中的提示 (如下所示)，以及 Example 和 ExplanationMetadata 的參考說明文件。

控制台中的「匯入模型」畫面，顯示「可解釋性」分頁中的可用選項。

gcloud CLI

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

{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

(選用) 如果您要指定完整的 NearestNeighborSearchConfig，請在本機環境中將下列內容寫入 JSON 檔案。檔案名稱不拘，但在本例中，請呼叫 search_config.json 檔案：

{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }

執行下列指令，上傳 Model。

如果您使用 Preset 搜尋設定，請移除 --explanation-nearest-neighbor-search-config-file 標記。如果您要指定 NearestNeighborSearchConfig，請移除 --explanation-modality 和 --explanation-query 標記。

與範例式解釋最相關的標記已加粗顯示。

gcloud ai models upload \
    --region=LOCATION \
    --display-name=MODEL_NAME \
    --container-image-uri=IMAGE_URI \
    --artifact-uri=MODEL_ARTIFACT_URI \
    --explanation-method=examples \
    --uris=[URI, ...] \
    --explanation-neighbor-count=NEIGHBOR_COUNT \
    --explanation-metadata-file=explanation-metadata.json \
    --explanation-modality=IMAGE|TEXT|TABULAR \
    --explanation-query=PRECISE|FAST \
    --explanation-nearest-neighbor-search-config-file=search_config.json

詳情請參閱「gcloud ai 模型上傳」。

上傳動作會傳回 OPERATION_ID，可用於檢查作業何時完成。您可以輪詢作業狀態，直到回應中包含 "done": true 為止。使用 gcloud ai operations describe 指令輪詢狀態，例如：
```
gcloud ai operations describe <operation-id>
```
您必須等到作業完成後才能要求說明。視資料集和模型架構的大小而定，這個步驟可能需要花費數小時，才能建構用於查詢範例的索引。

REST

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

PROJECT
LOCATION

如要瞭解其他預留位置，請參閱 Model、explanationSpec 和 Examples。

如要進一步瞭解如何上傳模型，請參閱 upload 方法和匯入模型。

以下 JSON 要求主體會指定 Preset 搜尋設定。或者，您也可以指定完整的 NearestNeighborSearchConfig。

HTTP 方法和網址：

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

JSON 要求主體：

{
  "model": {
    "displayName": "my-model",
    "artifactUri": "gs://your-model-artifact-folder",
    "containerSpec": {
      "imageUri": "us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-11:latest",
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": ["gs://your-examples-folder"]
          },
          "neighborCount": 10,
          "presets": {
            "modality": "image"
          }
        }
      },
      "metadata": {
        "outputs": {
            "embedding": {
                "output_tensor_name": "embedding"
            }
        },
        "inputs": {
          "my_fancy_input": {
            "input_tensor_name": "input_tensor_name",
            "encoding": "identity",
            "modality": "image"
          },
          "id": {
            "input_tensor_name": "id",
            "encoding": "identity"
          }
        }
      }
    }
  }
}

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

curl (Linux、macOS 或 Cloud Shell)

注意：以下指令假設您已使用使用者帳戶登入 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/locations/LOCATION/models:upload"

PowerShell (Windows)

注意：下列指令假設您已透過執行 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/locations/LOCATION/models:upload" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UploadModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T01:21:10.147035Z",
      "updateTime": "2022-01-08T01:21:10.147035Z"
    }
  }
}

上傳動作會傳回 OPERATION_ID，可用於檢查作業何時完成。您可以輪詢作業狀態，直到回應中包含 "done": true 為止。使用 gcloud ai operations describe 指令輪詢狀態，例如：

gcloud ai operations describe <operation-id>

您必須等到作業完成後才能要求說明。視資料集和模型架構的大小而定，這個步驟可能需要花費數小時，才能建構用於查詢範例的索引。

Python

請參閱圖像分類示例說明工作階段筆記中的「上傳模型」一節。

`NearestNeighborSearchConfig`

下列 JSON 要求主體示範如何在 upload 要求中指定完整的 NearestNeighborSearchConfig (而非預設值)。

{
  "model": {
    "displayName": displayname,
    "artifactUri": model_path_to_deploy,
    "containerSpec": {
      "imageUri": DEPLOY_IMAGE,
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": [DATASET_PATH]
          },
          "neighborCount": 5,
          "nearest_neighbor_search_config": {
            "contentsDeltaUri": "",
            "config": {
              "dimensions": dimensions,
              "approximateNeighborsCount": 10,
              "distanceMeasureType": "SQUARED_L2_DISTANCE",
              "featureNormType": "NONE",
              "algorithmConfig": {
                  "treeAhConfig": {
                      "leafNodeEmbeddingCount": 1000,
                      "fractionLeafNodesToSearch": 1.0
                  }
                }
              }
          }
        }
      },
      "metadata": { ... }
    }
  }
}

下表列出 NearestNeighborSearchConfig 的欄位。

欄位
`dimensions`	`int32` 這是必要旗標，輸入向量的維度數量。僅用於稠密嵌入。
`approximateNeighborsCount`	`int32` 如果使用樹狀 AH 演算法，則為必要屬性。執行確切重新排序之前，要透過近似搜尋尋找的預設鄰點數量。精確重新排序是一種程序，其中會使用較耗時的距離計算，重新排序近似搜尋演算法傳回的結果。
`ShardSize`	`ShardSize` 每個分割區的大小。索引資料量大時，系統會根據指定的分割大小進行分割。在服務期間，每個區塊都會在個別節點上提供服務，並獨立調整。
`distanceMeasureType`	`DistanceMeasureType` 最鄰近搜尋所使用的距離度量。
`featureNormType`	`FeatureNormType` 要針對各個向量執行的正規化類型。
`algorithmConfig`	`oneOf:` `TreeAhConfig` `BruteForceConfig` Vector Search 用於高效率搜尋的演算法設定。僅用於稠密嵌入。 `TreeAhConfig`：使用 tree-AH 演算法的設定選項。詳情請參閱這篇網誌文章「使用 TensorFlow Recommenders 和向量搜尋擴大深度擷取功能」 `BruteForceConfig`：這個選項會針對每個查詢在資料庫中實作標準線性搜尋。沒有可設定暴力搜尋的欄位。如要選取這個演算法，請為 `BruteForceConfig` 傳遞空物件。

`DistanceMeasureType`

列舉
`SQUARED_L2_DISTANCE`	歐幾里得 (L₂) 距離
`L1_DISTANCE`	曼哈頓 (L₁) 距離
`DOT_PRODUCT_DISTANCE`	預設值。定義為點積的負值。
`COSINE_DISTANCE`	餘弦距離。強烈建議您使用 DOT_PRODUCT_DISTANCE + UNIT_L2_NORM，而不要使用 COSINE 距離。我們的演算法已針對 DOT_PRODUCT 距離進行最佳化，如將點積距離與 UNIT_L2_NORM 搭配使用，在數學上就等同於餘弦距離，並能產生相同的排名。

`FeatureNormType`

列舉
`UNIT_L2_NORM`	單位 L2 正規化類型。
`NONE`	預設值。未指定規格化類型。

`TreeAhConfig`

這些是 tree-AH 演算法 (淺層樹 + 不對稱雜湊) 要選取的欄位。

欄位
`fractionLeafNodesToSearch`	`double`
	分葉節點的預設比率，任何查詢都有可能因此而經搜尋。必須介於 0.0 到 1.0 之間 (不含頭尾值)。如未設定，則預設值為 0.05。
`leafNodeEmbeddingCount`	`int32`
	每個分葉節點的嵌入項目數量。如未設定，則預設值為 1000。
`leafNodesToSearchPercent`	`int32`
	已淘汰，請改用 `fractionLeafNodesToSearch`。分葉節點的預設比率，任何查詢都有可能因此而經搜尋。必須介於 1 到 100 之間 (含 1 和 100)。如未設定，則預設值為 10 (代表 10%)。

`BruteForceConfig`

這個選項會為每個查詢在資料庫中實作標準線性搜尋。沒有可設定的欄位可用於暴力搜尋。如要選取此演算法，請將 BruteForceConfig 的空物件傳遞至 algorithmConfig。

輸入資料規定

將資料集上傳至 Cloud Storage 位置。請確認檔案採用 JSON Lines 格式。

檔案必須採用 JSON Lines 格式。以下範例取自圖像分類示例式說明筆記本：

{"id": "0", "bytes_inputs": {"b64": "..."}}
{"id": "1", "bytes_inputs": {"b64": "..."}}
{"id": "2", "bytes_inputs": {"b64": "..."}}

更新索引或設定

Vertex AI 可讓您更新模型的最近鄰索引或 Example 設定。如果您想更新模型，但不想重新為其資料集建立索引，這項功能就很實用。舉例來說，如果模型的索引包含 1,000 個例項，而您想要新增 500 個例項，可以呼叫 UpdateExplanationDataset 來新增至索引，而不需要重新處理原始的 1,000 個例項。

如要更新說明資料集，請按照下列步驟操作：

Python

def update_explanation_dataset(model_id, new_examples):
    response = clients["model"].update_explanation_dataset(model=model_id,  examples=new_examples)
    update_dataset_response = response.result()
    return update_dataset_response

PRESET_CONFIG = {
    "modality": "TEXT",
    "query": "FAST"
}
NEW_DATASET_FILE_PATH = "new_dataset_path"
NUM_NEIGHBORS_TO_RETURN = 10

EXAMPLES = aiplatform.Examples(presets=PRESET_CONFIG,
                                    gcs_source=aiplatform.types.io.GcsSource(uris=[NEW_DATASET_FILE_PATH]),
                                      neighbor_count=NUM_NEIGHBORS_TO_RETURN)

MODEL_ID = 'model_id'
update_dataset_response = update_explanation_dataset(MODEL_ID, EXAMPLES)

使用須知：

UpdateExplanationDataset 作業後，model_id 仍維持不變。
UpdateExplanationDataset 作業只會影響 Model 資源，不會更新任何相關聯的 DeployedModel。這表示 deployedModel 的索引會在部署時包含資料集。如要更新 deployedModel 的索引，您必須將更新後的模型重新部署至端點。

取得線上說明時覆寫設定

要求說明時，您可以指定 ExplanationSpecOverride 欄位，在執行中覆寫部分參數。

視應用程式而定，您可能需要對傳回的說明類型設定一些限制。舉例來說，為確保解釋內容多樣化，使用者可以指定擁擠參數，以免某一類型的範例在解釋中過度重複。具體來說，如果使用者想瞭解為何模型將鳥類標示為飛機，可能不會想看到太多鳥類示例，因為這會讓他們更深入瞭解問題的根本原因。

下表列出可覆寫參數的範例解釋要求：

屬性名稱	屬性值	說明
neighborCount	`int32`	要傳回做為說明的範例數量
crowdingCount	`int32`	傳回相同擁擠標記的範例數量上限
allow	`String Array`	說明可使用的標記
deny	`String Array`	說明不得包含的代碼

向量搜尋篩選會更詳細說明這些參數。

以下是 JSON 要求主體 (含覆寫值) 的範例：

{
  "instances":[
    {
      "id": data[0]["id"],
      "bytes_inputs": {"b64": bytes},
      "restricts": "",
      "crowding_tag": ""
    }
  ],
  "explanation_spec_override": {
    "examples_override": {
      "neighbor_count": 5,
      "crowding_count": 2,
      "restrictions": [
        {
          "namespace_name": "label",
          "allow": ["Papilloma", "Rift_Valley", "TBE", "Influenza", "Ebol"]
        }
      ]
    }
  }
}

後續步驟

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

以下是範例 explain 要求的回應範例：

[
   {
      "neighbors":[
         {
            "neighborId":"311",
            "neighborDistance":383.8
         },
         {
            "neighborId":"286",
            "neighborDistance":431.4
         }
      ],
      "input":"0"
   },
   {
      "neighbors":[
         {
            "neighborId":"223",
            "neighborDistance":471.6
         },
         {
            "neighborId":"55",
            "neighborDistance":392.7
         }
      ],
      "input":"1"
   }
]

定價

請參閱定價頁面中的範例式解釋部分。

設定以範例為基礎的解釋 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

匯入或上傳模型時設定說明

主控台

gcloud CLI

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

NearestNeighborSearchConfig

DistanceMeasureType

FeatureNormType

TreeAhConfig

BruteForceConfig

輸入資料規定

更新索引或設定

Python

取得線上說明時覆寫設定

後續步驟

定價

設定以範例為基礎的解釋

`NearestNeighborSearchConfig`

`DistanceMeasureType`

`FeatureNormType`

`TreeAhConfig`

`BruteForceConfig`