本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 調用端點
<a name="clarify-online-explainability-invoke-endpoint"></a>

端點執行後，請使用 SageMaker AI 執行期服務的 SageMaker AI 執行期 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) API 向端點傳送請求或調用端點。作為回應，SageMaker Clarify 解釋器會將這些要請求為無法解釋的請求進行處理。

**注意**  
若要調用端點，請選擇下列其中一種選項：  
如需使用 Boto3 或 AWS CLI 叫用端點的指示，請參閱 [調用模型以進行即時推論](realtime-endpoints-test-endpoints.md)。
若要使用適用於 Python 的 SageMaker SDK 調用端點，請參閱 [Predictor](https://sagemaker.readthedocs.io/en/stable/api/inference/predictors.html) API。

## 請求
<a name="clarify-online-explainability-request"></a>

`InvokeEndpoint` API 有一個可選參數 `EnableExplanations`，該參數會對應到 HTTP 標題 `X-Amzn-SageMaker-Enable-Explanations`。如果提供此參數，它會覆寫 `ClarifyExplainerConfig` 的 `EnableExplanations` 參數。

**注意**  
`InvokeEndpoint` API 的 `ContentType` 及 `Accept` 參數為必要項目。支援的格式包括 MIME 類型 `text/csv` 及 `application/jsonlines`。

使用 `sagemaker_runtime_client` 將請求傳送至端點，如下所示：

```
response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName='name-of-your-endpoint',
    EnableExplanations='`true`',
    ContentType='text/csv',
    Accept='text/csv',
    Body='1,2,3,4',  # single record (of four numerical features)
)
```

對於多模型端點，請在上一個範例請求傳遞其他 `TargetModel` 參數，以指定端點的目標模型。多模型端點會視需要動態載入目標模型。如需多模型端點的詳細資訊，請參閱[多模型端點](multi-model-endpoints.md)。如需如何從單一端點設定及調用多個目標模型的範例，請參閱 [SageMaker Clarify 多模型端點範例筆記本的線上可解釋性](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular_multi_model_endpoint/multi_model_xgboost_with_online_explainability.ipynb)。

## 回應
<a name="clarify-online-explainability-response"></a>

如果使用 `ExplainerConfig` 建立端點，則會使用新的回應結構描述，此新架構與缺少提供的 `ExplainerConfig` 參數的端點不同且不相容。

回應的 MIME 類型為 `application/json`，回應承載可以從 UTF-8 位元組解碼為 JSON 物件。下面顯示了這個 JSON 物件的成員如下：
+ `version`：以字串格式顯示的回應結構描述版本。例如 `1.0`。
+ `predictions`：請求做出的預測如下：
  + `content_type`：預測的 MIME 類型，指的是模型容器回應的 `ContentType`。
  + `data`：作為請求的模型容器回應承載傳遞的預測資料字串。
+ `label_headers`：來自 `LabelHeaders` 參數的標籤標題。這在解釋器組態或模型容器輸出所提供。
+ `explanations`：請求承載提供的解釋。如果沒有解釋任何記錄，則該成員傳回空物件 `{}`。
+ 
  + `kernel_shap`：指請求中每筆記錄的核心 SHAP 解釋陣列的索引鍵。如果沒有解釋記錄，則相應的解釋為 `null`。

`kernel_shap` 元素具有下列成員：
+ `feature_header`：解釋器組態 `ExplainerConfig` 中 `FeatureHeaders` 參數提供的特徵的標題名稱。
+ `feature_type`：由解釋器推斷或在 `ExplainerConfig` 中的 `FeatureTypes` 參數提供的特徵類型。此元素僅適用於 NLP 可解釋性問題。
+ `attributions`：屬性物件的陣列。文字特徵可以有多個屬性物件，每個屬性物件對應一個單位。屬性物件具有下列成員：
  + `attribution`：為每個類別提供的機率值清單。
  + `description`：文字單位的描述，僅適用於 NLP 可解釋性問題。
    + `partial_text`：解釋者解釋的文字部分。
    + `start_idx`：從零開始的索引，用於標識部分文字片段開頭的陣列位置。