分析組態檔案 - Amazon SageMaker AI
分析組態檔案的結構描述範例分析組態檔案

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

分析組態檔案

若要使用 SageMaker Clarify 分析資料和模型的可解釋性和偏差，您必須設定處理任務。此處理工作的一部分組態包括分析檔案的組態。分析檔案會指定偏差分析和可解釋性的參數。請參閱 以設定 SageMaker Clarify 處理工作了解如何設定處理任務和分析檔案。

本指南說明此分析組態檔案的結構描述和參數。本指南也包含用於計算表格式資料集偏差指標的分析組態檔案範例，以及產生自然語言處理 (NLP)、電腦視覺 (CV) 和時間序列 (TS) 問題的解釋。

您可以建立分析組態檔案，或使用 SageMaker Python SDK 透過 SageMaker ClarifyProcessor API 產生分析組態檔案。檢視檔案內容有助於瞭解 SageMaker Clarify 工作所使用的基礎組態。

分析組態檔案的結構描述

下節說明分析組態檔案的結構描述，包括參數的需求和描述。

分析組態檔案的需求

SageMaker Clarify 處理工作預期分析組態檔案的結構符合下列需求：

  • 處理輸入名稱必須是 analysis_config.

  • 分析組態檔案為 JSON 格式，並以 UTF-8 編碼。

  • 分析組態檔案是 Amazon S3 物件。

您可以在分析組態檔案中指定其他參數。下節提供各種選項，可針對您的使用案例和所需的分析類型，量身打造 SageMaker Clarify 處理工作。

在分析組態檔案中，您可以指定下列參數。

  • version — (選用) 分析組態檔案結構描述的版本字串。如果未提供版本，SageMaker Clarify 會使用最新的支援版本。目前，唯一支援的版本是 1.0。

  • dataset_type — 資料集的格式。輸入資料集格式可以是下列任何值：

    • 表格式

      • text/csv 適用於 CSV

      • application/jsonlines for SageMaker AI JSON Lines 密集格式

      • application/json 適用於 JSON

      • application/x-parquet 適用於 Apache Parquet

      • application/x-image 以啟動電腦視覺問題的可解釋性

    • 時間序列預測模型說明

      • application/json 適用於 JSON

  • dataset_uri - (選用) 主資料集的統一資源識別碼 (URI)。如果您提供 S3 URI 字首，SageMaker Clarify 處理工作會以遞迴方式收集位於字首下的所有 S3 檔案。您可以為電腦視覺問題的影像資訊清單檔案提供 S3 URI 字首或 S3 URI。如果已提供 dataset_uri，這會優先於處理工作輸入的資料集。對於影像和時間序列使用案例以外的任何格式類型，SageMaker Clarify 處理任務會將輸入資料集載入表格式資料框架，做為表格式資料集。此格式可讓 SageMaker AI 輕鬆操作和分析輸入資料集。

  • 標頭 – （選用）

    • 表格：包含表格式資料集資料欄名稱的字串陣列。如果未為 提供值headers，SageMaker Clarify 處理任務會從資料集讀取標頭。如果資料集沒有標頭，Clarify 處理任務會根據以零為基礎的資料欄索引自動產生預留位置名稱。例如，第一欄和第二欄的預留位置名稱將為 column_0、 column_1等。

      注意

      根據慣例，如果 dataset_type是 application/jsonlines或 application/json，則 headers應依序包含下列名稱：

      1. 功能名稱

      2. 標籤名稱 label （如果指定）

      3. 預測標籤名稱 predicted_label （如果已指定）

      如果已指定 label，application/jsonlines 資料集類型的 headers 範例為：["feature1","feature2","feature3","target_label"]。

    • 時間序列：資料集中的資料欄名稱清單。如果未提供，Clarify 會產生要在內部使用的標頭。對於時間序列可解釋性案例，請依下列順序提供標頭：

      1. 項目 ID

      2. timestamp

      3. 目標時間序列

      4. 所有相關時間序列資料欄

      5. 所有靜態共變數資料欄

  • label — (選用) 字串或從零開始的整數索引。如果提供，label 用於定位 Ground Truth 標籤，也稱為表格式資料集中的觀察標籤或目標屬性。Ground Truth 標籤用於計算偏差指標。label 的值是根據 dataset_type 參數的值指定，如下所示。

    • 如果 dataset_type 是 text/csv，則 label 可以指定為下列任一項：

      • 有效的欄位名稱

      • 介於資料集欄位範圍內的索引

    • 如果 dataset_type 是 application/parquet，則 label 必須是有效的欄位名稱。

    • 如果 dataset_type 是 application/jsonlines，則 label 必須是寫入以從資料集中擷取 Ground Truth 標籤的 JMESPath 運算式。按照慣例，如果指定 headers，則其應包含標籤名稱。

    • 如果 dataset_type 是 application/json，則 label 必須是寫入為資料集中的每個記錄擷取 Ground Truth 標籤的 JMESPath 運算式。此 JMESPath 運算式必須產生標籤清單，其中第 i 個標籤與第 i 個記錄相互關聯。

  • predicted_label — (選用) 字串或從零開始的整數索引。如果提供，predicted_label 用於在表格式資料集中定位包含預測標籤的欄位。預測標籤用於計算訓練後的偏差指標。如果資料集不包含預測標籤，則參數 predicted_label 為選用。如果計算需要預測標籤，則 SageMaker Clarify 處理工作將從模型取得預測。

    predicted_label 的值是根據 dataset_type 的值指定，如下所示：

    • 如果 dataset_type 是 text/csv，則 predicted_label 可以指定為下列任一項：

      • 有效的欄位名稱。如果已指定 predicted_label_dataset_uri 但未提供 predicted_label，則預設的預測標籤名稱為 “predicted_label”。

      • 介於資料集欄位範圍內的索引。如果已指定 predicted_label_dataset_uri，則索引將用於在預測標籤資料集中定位預測標籤欄位。

    • 如果 dataset_type 是 application/x-parquet，則 predicted_label 必須是有效的欄位名稱。

    • 如果 dataset_type 是 application/jsonlines，則 predicted_label 必須是寫入以從資料集中擷取預測標籤的有效 JMESPath 運算式。按照慣例，如果指定 headers，則其應包含預測標籤名稱。

    • 如果 dataset_type 是 application/json，則 predicted_label 必須是寫入為資料集中的每個記錄擷取預測標籤的 JMESPath 運算式。JMESPath 運算式應產生預測標籤清單，其中第 i 個預測標籤是針對第 i 個記錄。

  • 功能 – （選用） 如果 dataset_type為 application/jsonlines或 ，non-time-series使用案例的必要項目application/json。寫入以定位輸入資料集中的功能的 JMESPath 字串運算式。對於 application/jsonlines，JMESPath 運算式會套用至每一行，以擷取該記錄的功能。對於 application/json，JMESPath 運算式會套用至整個輸入資料集。JMESPath 運算式應擷取清單的清單，或功能的 2D 陣列/矩陣，其中第 i 行包含與第 i 個記錄相互關聯的功能。對於 text/csv 或 application/x-parquet 的 dataset_type，除了 Ground Truth 標籤和預測標籤欄以外的所有欄都會自動指定為功能。

  • predicted_label_dataset_uri – （選用） 僅適用於 dataset_type 為 時text/csv。資料集的 S3 URI 包含用於計算訓練後偏差指標的預測標籤。SageMaker Clarify 處理工作將從提供的 URI 載入預測，而不是從模型取得預測。在此情況下，predicted_label 需要在預測標籤資料集中找到預測標籤欄位。如果預測標籤資料集或主資料集分割為多個檔案，則 joinsource_name_or_index 必須指定識別碼欄位以加入這兩個資料集。

  • predicted_label_headers – （選用） 僅適用於指定 predicted_label_dataset_uri 時。包含預測標籤資料集的欄位名稱的字串陣列。除了預測標籤標題，predicted_label_headers 也可以包含標識符欄位的標題以加入預測標籤資料集和主資料集。如需詳細資訊，請參閱參數 joinsource_name_or_index 的以下描述。

  • joinsource_name_or_index – （選用） 表格式資料集中的資料欄名稱或以零為基礎的索引，在執行內部聯結時用作識別符資料欄。此欄僅用作識別碼。不用於任何其他計算，如偏差分析或功能屬性分析。在下列情況下，需要 joinsource_name_or_index 的值：

    • 有多個輸入資料集，而且有任何一個被分成多個檔案。

    • 透過將 SageMaker Clarify 處理工作 InstanceCount 設定為大於 1 的值來啟動分散式處理。

  • excluded_columns —(選用) 要排除不傳送至模型做為預測輸入的名稱陣列或從零開始的欄位索引。Ground Truth 標籤和預測標籤已自動排除。時間序列不支援此功能。

  • probability_threshold — (選用) 浮點數，在此浮點數上選取一個標籤或物件。預設值為 0.5。SageMaker Clarify 處理工作會在下列情況下使用 probability_threshold：

    • 在訓練後偏差分析中，如果模型是二進位分類器，probability_threshold 會將數值模型預測 (機率值或分數) 轉換為二進位標籤。大於閾值的分數會轉換為 1。而小於或等於閾值的分數會轉換為 0。

    • 在電腦視覺可解釋性問題中，如果 model_type 是 OBJECT_DETECTION，, probability_threshold 會篩選掉可信度分數低於閾值的偵測到物件。

  • label_values_or_threshold – （選用） 偏差分析的必要項目。標籤值或閾值數的陣列，表示偏差指標的 Ground Truth 和預測標籤的正面結果。如需詳細資訊，請參閱 中的正面標籤值Amazon SageMaker Clarify 偏差和公平性條款。如果標籤是數值，會將閾值套用為下限以選取正面結果。若要針對不同的問題類型設定 label_values_or_threshold，請參閱下列範例：

    • 對於二進位分類問題，標籤有兩個可能的值 0 和 1。如果標籤值 1 對樣本中觀察的人口統計群組有利，則 label_values_or_threshold 應設定為 [1]。

    • 對於多類別分類問題，標籤有三個可能的值 bird、cat 和 dog。如果後兩項定義偏差有利的人口統計群組，則 label_values_or_threshold 應設定為 ["cat","dog"]。

    • 對於迴歸問題，標籤值是連續的，範圍從 0 到 1。如果大於 0.5 的值應將樣本指定為具有正面結果，則 label_values_or_threshold 應設定為 0.5。

  • 面向 – （選用） 偏差分析的必要項目。facet 物件的陣列，由用以測量偏差的敏感屬性組成。您可以使用 facet 來瞭解資料集和模型的偏差特性，即使未使用敏感屬性來訓練模型也可以。如需詳細資訊，請參閱 中的面向Amazon SageMaker Clarify 偏差和公平性條款。每個 facet 物件包含以下欄位：

    • name_or_index – （選用） 表格式資料集中敏感屬性資料欄的名稱或以零為基礎的索引。如果指定 facet_dataset_uri，則索引會參考 facet 資料集，而不是主資料集。

    • value_or_threshold – （選用） 如果 label_values_or_threshold facet是數值且套用為下限以選取敏感群組，則為必要）。facet 值或閾值數陣列，表示偏差有利的敏感人口統計群組。如果 facet 資料類型為分類而且未提供 value_or_threshold，偏差指標會將每個唯一值 (而非所有值) 計算為一個群組。若要針對不同的 facet 資料類型設定 value_or_threshold，請參閱下列範例：

      • 對於二進位 facet 資料類型，功能有兩個可能的值 0 和 1。如果要計算每個值的偏差指標，則 value_or_threshold 可以省略或設定為空陣列。

      • 對於分類 facet 資料類型，功能有三個可能的值 bird、cat 和 dog。如果前兩項定義偏差有利的人口統計群組，則 value_or_threshold 應設定為 ["bird", "cat"]。在此範例中，資料集範例會分割為兩個人口統計群組。有利群組中的 facet 有值 bird 或 cat，而不利群組中的 facet 有值 dog。

      • 對於數值 facet 資料類型，功能值是連續的，範圍從 0 到 1。例如，如果大於 0.5 的值應將樣本指定為有利，則 value_or_threshold 應設定為 0.5。在此範例中，資料集範例會分割為兩個人口統計群組。有利群組中的 facet 有大於 0.5 的值 ，而不利群組中的 facet 有小於或等於 0.5 的值。

  • group_variable – （選用） 資料欄的名稱或以零為基礎的索引，指出要用於偏差指標條件式的人口統計差異 (CDD)或 的子群組預測標籤 (CDDPL) 中的條件人口統計差異。

  • facet_dataset_uri – （選用） 僅適用於 dataset_type 為 時text/csv。包含用於偏差分析的敏感屬性的資料集的 S3 URI。您可以使用 facet 來瞭解資料集和模型的偏差特性，即使未使用敏感屬性來訓練模型也可以。

    注意

    如果 facet 資料集或主資料集分割為多個檔案，則 joinsource_name_or_index 必須指定識別符欄位以加入這兩個資料集。您必須使用參數 facet 來識別 facet 資料集中的每個 facet。

  • facet_headers – （選用） 僅適用於指定 facet_dataset_uri 時。字串陣列，其中包含構面資料集的資料欄名稱，以及選擇性地加入構面資料集和主資料集的識別符資料欄標頭，請參閱 joinsource_name_or_index。

  • time_series_data_config – （選用） 指定用於時間序列資料處理的組態。

    • item_id – 字串或零整數索引。此欄位用於尋找共用輸入資料集中的項目 ID。

    • 時間戳記 – 字串或零整數索引。此欄位用於在共用輸入資料集中找到時間戳記。

    • dataset_format – 可能的值為 columns、 item_records或 timestamp_records。此欄位用於描述 JSON 資料集的格式，這是時間序列可解釋性支援的唯一格式。

    • target_time_series – JMESPath 字串或零整數索引。此欄位用於在共用輸入資料集中找到目標時間序列。如果此參數是字串，則除 以外的所有其他參數dataset_format都必須是字串或字串清單。如果此參數是整數，則除 以外的所有其他參數dataset_format必須是整數或整數清單。

    • related_time_series – （選用） JMESPath 表達式陣列。如果存在，此欄位用於尋找共用輸入資料集中的所有相關時間序列。

    • static_covariates – （選用） JMESPath 表達式的陣列。如果存在，此欄位用於尋找共用輸入資料集中的所有靜態共變數欄位。

    如需範例，請參閱 時間序列資料集組態範例。

  • methods — 包含一或多個分析方法及其參數的物件。如果省略任何方法，則不會用於分析和報告。

    • pre_training_bias — 如果您想要計算訓練前偏差指標，請包含此方法。您可以在 中找到指標的詳細說明訓練前偏差指標。物件具有下列參數：

    • post_training_bias — 如果您想要計算訓練後偏差指標，請包含此方法。您可以在 中找到指標的詳細說明訓練後資料和模型偏差指標。post_training_bias 物件具有下列參數。

    • shap - 如果要計算 SHAP 值，請包括此方法。SageMaker Clarify 處理工作支援核心 SHAP 演算法。shap 物件具有下列參數。

      • baseline – （選用） SHAP 基準資料集，也稱為背景資料集。表格式資料集或電腦視覺問題中的基準資料集的其他需求如下。如需 SHAP 基準的詳細資訊，請參閱 用於可解釋性的 SHAP 基準

        • 對於表格式資料集，baseline 可以是基準檔案的就地基準資料或 S3 URI。如果未提供 baseline，SageMaker Clarify 處理工作會透過叢集輸入資料集來計算基準。以下是基準的必要條件：

          • 格式必須與 dataset_type 指定的資料集格式相同。

          • 基準只能包含模型可以接受為輸入的功能。

          • 基準資料集可以有一或多個執行個體。基準執行個體的數目會直接影響綜合資料集大小和工作執行期。

          • 如果指定 text_config，則文字欄的基準值是用來取代 granularity 指定的文字單位的字串。例如，一個常見的預留位置是 “[MASK]”，用來表示遺失或未知的單字或文字片段。

          下面的範例顯示如何為不同的 dataset_type 參數設定就地基準資料：

          • 如果 dataset_type 是 text/csv 或 application/x-parquet，則模型會接受四個數值特徵，且基準有兩個執行個體。在此範例中，如果一筆記錄有所有零特徵值，而另一筆記錄有所有一特徵值，則應將基準設定為 [[0,0,0,0],[1,1,1,1]]，不包含任何標題。

          • 如果 dataset_type 是 application/jsonlines，features 為四個數值特徵值清單的金鑰。此外，在這個範例中，如果基準有一筆具所有零值的記錄，則 baseline 應該是 [{"features":[0,0,0,0]}]。

          • 如果 dataset_type 是 application/json，baseline 資料集應具有與輸入資料集相同的結構和格式。

        • 對於電腦視覺問題，baseline 可以是影像的 S3 URI，用來遮蔽輸入影像中的特徵 (區段)。SageMaker Clarify 處理工作會載入遮蔽影像，並將其調整為與輸入影像相同的解析度。如果未提供基準，SageMaker Clarify 處理工作會以與輸入影像相同的解析度來產生白色雜訊的遮蔽影像。

      • features_to_explain — (選用) 功能欄位的字串或從零開始的索引的陣列，以計算其 SHAP 值。如果未提供 features_to_explain，則會計算所有功能欄位的 SHAP 值。這些功能欄位不能包括標籤欄位或預測標籤欄位。只有具有數值和分類欄位的表格式資料集才支援features_to_explain 參數。

      • num_clusters — (選用) 資料集所分割成的叢集數以計算基準資料集。每個叢集都用來計算一個基準執行個體。如果未指定 baseline，SageMaker Clarify 處理工作會嘗試將表格式資料集分割為介於 1 和 12 之間的最佳叢集數來計算基準資料集。基準執行個體數會直接影響 SHAP 分析的執行期。

      • num_samples — (選用) 核心 SHAP 演算法中要使用的樣本數。如果未提供 num_samples，SageMaker Clarify 處理工作會為您選擇數量。樣本數會直接影響綜合資料集大小和工作執行期。

      • seed - (選用) 一個整數，用於初始化 SHAP 解釋器中的虛擬隨機數產生器，為相同工作產生一致的 SHAP 值。如果未指定 seed，則每次執行相同工作時，模型可能會輸出略有不同的 SHAP 值。

      • use_logit – (選用) 布林值，指出您要將 logit 函式套用至模型預測。預設為 false。如果 use_logit 是 true，則使用邏輯迴歸係數來計算 SHAP 值，該係數可解譯為對數機率比。

      • save_local_shap_values — (選用) 布林值，指出您要將資料集中每個記錄的本機 SHAP 值包含在分析結果中。預設為 false。

        如果主資料集分割為多個檔案或已啟動分散式處理，也可以使用參數 joinsource_name_or_index 來指定識別碼欄位。識別碼欄位和本機 SHAP 值會儲存在分析結果中。如此一來，您可以將每個記錄對應至其本機 SHAP 值。

      • agg_method— (選擇性) 用來將所有執行個體的本機 SHAP 值 (每個執行個體的 SHAP 值) 彙總至全域 SHAP 值 (整個資料集的 SHAP 值) 的方法。預設為 mean_abs。以下方法可用於彙總 SHAP 值。

        • mean_abs—所有執行個體的絕對本地 SHAP 值的平均值。

        • mean_sq—所有執行個體的平方本地 SHAP 值的平均值。

        • 中位數—所有執行個體的本地 SHAP 值的中位數。

      • text_config – 自然語言處理可解釋性的必要項目。如果您要將文字欄視為文字，請包含此組態，並針對個別文字單位提供解釋。如需自然語言處理可解釋性的分析組態範例，請參閱 自然語言處理解釋性的分析組態

        • 粒度—分析文字欄的粒度單位。有效值為 token、sentence 或 paragraph。文字的每個單位都被視為一個功能，並針對每個單位運算本機 SHAP 值。

        • 語言—文字欄的語言。有效值為 chinese、danish、dutch、english、french、german、greek、italian、japanese、lithuanian、multi-language、norwegian bokmål、polish、portuguese、romanian、russian、spanish、afrikaans、albanian、arabic、armenian、basque、bengali、bulgarian、catalan、croatian、czech、estonian、finnish、gujarati、hebrew、hindi、hungarian、icelandic、indonesian、irish、kannada、kyrgyz、latvian、ligurian、luxembourgish、macedonian、malayalam、marathi、nepali、persian、sanskrit、serbian、setswana、sinhala、slovak、slovenian、swedish、tagalog、tamil、tatar、telugu、thai、turkish、ukrainian、urdu、vietnamese、yoruba。輸入 multi-language 以混合多種語言。

        • max_top_tokens — (選擇性) 根據全域 SHAP 值的頂端權杖數目上限。預設為 50。符記可能在資料集中多次出現。SageMaker Clarify 處理任務會彙總每個符記的 SHAP 值，然後根據其全域 SHAP 值選取頂端符記。所選頂端符記的全域 SHAP 值會包含在分析 .json 檔案的global_top_shap_text區段中。

        • 彙總的本機 SHAP 值。

      • image_config—電腦視覺解釋性需要。如果您有由映像組成的輸入資料集，並且想要在電腦視覺問題中分析這些資料集以解釋這些資料集，請包含此組態。

        • model_type—模型的類型。有效值包含：

          • 調校映像分類模型的 IMAGE_CLASSIFICATION。

          • 調校物件偵測模型的 OBJECT_DETECTION。

        • max_objects — 僅當 model_type 為時才適用OBJECT_DETECTION。由電腦視覺模型偵測到的最大物件數 (依可信度分數排序)。任何依可信度分數排名低於頂部 max_objects 的物件都會被篩選掉。預設為 3。

        • context—僅當模型類型為時適用。OBJECT_DETECTION它指示偵測到的物件邊界方框周圍區域是否被基線映像遮罩。有效值是 0 遮罩所有內容，或者1什麼都不遮罩。預設值為 1。

        • iou_threshold — 僅適用當 model_type 為 OBJECT_DETECTION。以原始偵測評估預測的交併比 (IOU) 計量下限。高 IOU 計量對應於預測和 Ground Truth 檢測框之間的大重疊。預設為 0.5。

        • num_segments ー (選擇性) 一個整數，用於決定要在輸入映像中標示的近似區段數。映像的每個區段都被視為一個功能，並且會針對每個區段運算本地 SHAP 值。預設為 20。

        • segment_compactness — (選擇性) 整數，用於決定由 scikit-image slic 方法所產生之映像區段的形狀和大小。預設為 5。

    • pdp – 包含此方法來運算部分相依性圖 (PDPs)。如需產生 PDPs的分析組態範例，請參閱 運算部分相依性繪圖 (PDP)

      • 功能—如果未請求該shap方法，則為強制性。用於運算和繪製 PDP 繪圖的功能名稱或索引陣列。

      • top_k_features — (選擇性) 指定用於產生 PDP 繪圖的頂層特徵數目。如果 features 未提供，但請求 shap 方法，則 SageMaker Clarify 處理任務會根據其 SHAP 屬性選擇最上層功能。預設為 10。

      • grid_resolution—要將數值範圍分割成的儲存貯體數目。這會指定 PDP 繪圖的格點粒度。

    • asymmetric_shapley_value – 如果您想要計算時間序列預測模型的可解釋性指標，請包含此方法。SageMaker Clarify 處理任務支援非對稱 Shapley 值演算法。非對稱 Shapley 值是捨棄對稱軸的 Shapley 值變體。如需詳細資訊，請參閱非對稱 Shapley 值：將因果知識納入模型無關可解釋性。使用這些值來判斷特徵對預測結果的貢獻。非對稱 Shapley 值會考慮預測模型作為輸入的時間序列資料的時間相依性。

      演算法包含下列參數：

      • 方向 – 可用的類型為 chronological、 anti_chronological和 bidirectional。時間結構可以按時間順序或反時間順序或兩者進行導覽。透過反覆新增從第一個步驟開始的資訊，來建立計時說明。反時間性說明會新增從最後一個步驟開始並向後移動的資訊。在出現延遲偏差的情況下，後者順序可能更合適，例如預測股票價格。

      • 精細程度 – 要使用的解釋精細程度。可用的精細程度選項如下所示：

        • 時間 – timewise解釋費用低廉，僅提供有關特定時間步驟的資訊，例如計算過去第 n 天的資訊對預測未來第 mth 天有何貢獻。產生的屬性不會個別解釋靜態共變數，也不會區分目標和相關時間序列。

        • fine_grained – fine_grained解釋的運算更為密集，但提供輸入變數所有屬性的完整明細。方法會計算大約的解釋，以減少執行時間。如需詳細資訊，請參閱下列參數 num_samples。

          注意

          fine_grained 說明僅支援chronological順序。

      • num_samples – （選用） fine_grained說明需要此引數。數字越高，近似值就越精確。此數字應隨輸入功能的維度而擴展。經驗法則是，如果結果不大，則將此變數設定為 (1 + max（相關時間序列的數量、靜態共變數的數量）)^2。

      • baseline – （選用） 取代對應資料集 （也稱為背景資料） out-of-coalition值的基準組態。下列程式碼片段顯示基準組態的範例：

        {
    "related_time_series": "zero",
    "static_covariates": {
        <item_id_1>: [0, 2],
        <item_id_2>: [-1, 1]
    },
    "target_time_series": "zero"
}

        • 對於目標時間序列或相關時間序列等時間資料，基準值類型可以是下列其中一個值：

          • zero — out-of-coalition範圍的值都會取代為 0.0。

          • mean — 所有out-of-coalition值都會取代為時間序列的平均值。

        • 對於靜態共變數，只有在模型請求接受靜態共變數值時，才應該提供基準項目，在這種情況下，需要此欄位。應為每個項目提供做為清單的基準。例如，如果您的資料集有兩個靜態共變數，您的基準組態可能如下：

          "static_covariates": {
    <item_id_1>: [1, 1],
    <item_id_2>: [0, 1]
}

          在上述範例中，<item_id_1> 和 <item_id_2> 是來自資料集的項目 ID。

    • report — (選用) 使用此物件可自訂分析報告。時間序列說明任務不支援此參數。分析結果中有三份相同報告副本：Jupyter 筆記本報表、HTML 報告和 PDF 報告。此物件具有下列參數：

      • name—報表檔案的檔案名稱。例如，如果 name 是 MyReport，則報告檔案為 MyReport.ipynbMyReport.html、和 MyReport.pdf。預設為 report。

      • title — (選用) 報表的標題字串。預設為 SageMaker AI Analysis Report。

  • predictor—如果分析需要來自模型的預測，則需要此選項。例如，當請求 shap、pdp、 asymmetric_shapley_value或 post_training_bias方法時，但輸入資料集不提供預測標籤。以下是要搭配使用的參數predictor：

    • model_name – 由 CreateModel API 建立的 SageMaker AI 模型名稱。如果您指定model_name而不是 endpoint_name，SageMaker Clarify 處理任務會建立具有模型名稱 (稱為陰影端點) 的暫時端點，並從端點取得預測結果。運算完成後，任務會刪除陰影端點。如果模型是多模型，則必須指定 target_model 參數。如需多模型端點的詳細資訊，請參閱 多模型端點。

    • endpoint_name_prefix — (選擇性) 陰影端點的自訂名稱字首。如果您提供 model_name 而不是 endpoint_name，則是用。例如，如果要透過端點名稱限制端點存取，則提供 endpoint_name_prefix。字首必須與 EndpointName 模式相符，且其最大長度為 23。預設為 sm-clarify。

    • initial_instance_count—指定陰影端點的執行個體數目。如果您提供 model_name 而不是 endpoint_name，則需要此選項。initial_instance_count 的值可以與任務的 InstanceCount 不同，但我們建議使用 1:1 的比例。

    • instance_type—指定陰影端點的執行個體類型。如果您提供 model_name 而不是 endpoint_name，則需要此選項。作為一個範例，instance_type 可以設定為 “ml.m5.large”。在某些情況下，instance_type的指定值有助於減少模型推論時間。例如，若要有效執行，自然語言處理模型和電腦視覺模型通常需要圖表處理單元 (GPU) 執行個體類型。

    • endpoint_name – 由 CreateEndpoint API 建立的 SageMaker AI 端點名稱。如果提供，endpoint_name 優先於 model_name 參數。使用現有端點減少陰影端點啟動程序的時間，但也可能導致該端點的負載大幅增加。此外，某些分析方法 (例如 shap 和 pdp) 會產生傳送至端點的合成資料集。這可能會導致端點的指標或擷取的資料被合成資料污染，這可能無法準確反映真實世界的使用情況。基於這些原因，通常不推薦使用現有的生產端點進行 SageMaker Clarify 分析。

    • target_model – 傳遞至 SageMaker AI InvokeEndpoint API TargetModel 參數的字串值。如果您的模型 (由 model_name 參數指定) 或端點 (由 endpoint_name 參數指定) 為多模型，則需要此選項。如需多模型端點的詳細資訊，請參閱 多模型端點。

    • custom_attributes — (選用) 字串可讓您提供有關提交至端點之推論請求的其他資訊。字串值會傳遞至 SageMaker AI InvokeEndpoint API 的 CustomAttributes 參數。

    • content_type—用於從端點取得預測的模型輸入格式。如果提供，它會傳遞至 SageMaker AI InvokeEndpoint API 的 ContentType 參數。

      • 對於電腦視覺解釋性，有效值為 image/jpeg、image/png 或 application/x-npy。如 content_type 未提供，則預設值為 image/jpeg。

      • 對於時間序列預測可解釋性，有效值為 application/json。

      • 對於其他類型的解釋性，有效值為 text/csv、application/jsonlines, 和 application/json。如果 dataset_type是 ，content_type則需要 的值application/x-parquet。否則 content_type 預設值為 dataset_type 參數。

    • accept_type—用於從端點取得預測的模型輸出格式。的值accept_type會傳遞至 SageMaker AI InvokeEndpoint API 的 Accept 參數。

      • 對於電腦視覺解釋性，如果 model_type 是 “OBJECT_DETECTION”，則 accept_type 預設為 application/json。

      • 對於時間序列預測可解釋性，有效值為 application/json。

      • 對於其他類型的解釋性，有效值為 text/csv、application/jsonlines和 application/json。如果 accept_type 的值未提供，則 accept_type 預設為 content_type 參數的值。

    • content_template—用於從資料集記錄建構模型輸入的範本字串。只有在 content_type 參數值為 application/jsonlines 或 application/json 時，才會使用且需要 content_template 參數。

      當content_type 參數為時 application/jsonlines，範本應該只有一個預留位置 $features，在執行期會由功能清單取代。例如，如果範本是 "{\"myfeatures\":$features}"，且如果記錄具有三個數值功能值：1、2 和 3，則記錄將以 JSON 行的形式傳送至模型{"myfeatures":[1,2,3]}。

      如果 content_type 是 application/json，範本則可以有預留位置 $record 或 records。如果預留位置為record，則會將單一記錄取代為已套用 record_template 的範本記錄。在此情況下，一次只會將單一記錄傳送至模型。如果預留位置為 $records，則記錄會由記錄清單取代，每筆記錄都有提供的範本 record_template。

    • record_template—一個範本字串，用於從資料集執行個體建構模型輸入的每個記錄。它僅在 content_type 是 application/json 時使用和需要。範本字串可能包含下列其中一項：

      • 由功能值陣列取代的預留位置 $features 參數。其他可選預留位置可以取代 $feature_names 中的功能欄標題名稱。此可選的預留位置將替換為功能名稱的陣列。

      • 只有一個預留位置 $features_kvp，由鍵值對、功能名稱和功能值取代。

      • headers 模型組態中的一個功能。例如，由預留位置語法 "${A}" 註記的功能名稱A，將由 A 的功能值取代。

      record_template 的值用於 content_template 建構模型輸入。以下有一個顯示如何使用內容和記錄範本構建模型輸入的組態範例。

      在下列程式碼範例中，標題和功能定義如下。

      • `headers`:["A", "B"]

      • `features`:[[0,1], [3,4]]

      範例模型輸入如下。

      {
    "instances": [[0, 1], [3, 4]],
    "feature_names": ["A", "B"]
}

      以下是用來建構先前的範例模型輸入的範例 content_template 和 record_template 參數值。

      • content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"

      • record_template: "$features"

      在下列程式碼範例中，標題和功能定義如下。

      [
    { "A": 0, "B": 1 },
    { "A": 3, "B": 4 },
]

      以下是用來建構先前的範例模型輸入的範例 content_template 和 record_template 參數值。

      • content_template: "$records"

      • record_template: "$features_kvp"

      以下是建構先前範例模型輸入的替代程式碼範例。

      • content_template: "$records"

      • record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"

      在下列程式碼範例中，標題和功能定義如下。

      { "A": 0, "B": 1 }

      上面要構建的範例 content_template 和 record_template 參數值：先前的範例模型輸入如下。

      • content_template: "$record"

      • record_template: "$features_kvp"

      如需更多範例，請參閱時間序列資料的端點請求。

    • label – （選用） 以零為基礎的整數索引或 JMESPath 表達式字串，用於從模型輸出擷取預測標籤以進行偏差分析。如果模型是多類別，且 label 參數從模型輸出中擷取所有預測標籤，則適用以下內容。時間序列不支援此功能。

      • 需要 probability 參數才能從模型輸出中獲取相應的機率 (或分數)。

      • 選擇最高分的預測標籤。

      label 的值取決於 accept_type 參數的值，如下所示。

      • 如果 accept_type 是 text/csv，則 label 為模型輸出中任何預測標籤之索引。

      • 如果 accept_type 是 application/jsonlines 或 application/json，則 label 是應用於模型輸出以取得預測標籤的 JMESPath 表達式。

    • label_headers – （選用） 標籤可在資料集中使用的值陣列。如果請求偏差分析，則還需要該 probability 參數從模型輸出中獲取相應的機率值 (分數)，並選擇最高分的預測標籤。如果請求解釋性分析，則使用標籤標題來美化分析報告。電腦視覺解釋性需要 label_headers 的值。例如，對於多類別分類問題，如果標籤有三個可能的值 bird、cat 和 dog，則 label_headers 應設定為 ["bird","cat","dog"]。

    • 機率 – （選用） 以零為基礎的整數索引或 JMESPath 表達式字串，用於擷取機率 （分數） 以進行可解釋性分析 （但不適用於時間序列可解釋性），或選擇預測標籤以進行偏差分析。probability 的值取決於 accept_type 參數的值，如下所示。

      • 如果 accept_type 是 text/csv，則 probability 為模型輸出中機率 (分數) 的索引。如果 probability 未提供，則會將整個模型輸出視為機率 (分數)。

      • 如果 accept_type 是 JSON 資料 (application/jsonlines 或 application/json)，則 probability 應該是用於從模型輸出中擷取機率(分數)的 JMESPath 表達式。

    • time_series_predictor_config – （選用） 僅用於時間序列可解釋性。用來指示 SageMaker Clarify 處理器如何從 中以 S3 URI 形式傳遞的資料正確剖析資料dataset_uri。

      • 預測 – 用來擷取預測結果的 JMESPath 表達式。

範例分析組態檔案

下列各節包含 CSV 格式、JSON Lines 格式的資料分析組態檔案範例，以及自然語言處理 (NLP)、電腦視覺 (CV) 和時間序列 (TS) 可解釋性的範例分析組態檔案。

以下的範例顯示如何設定 CSV 格式之表格式資料集的偏差和解釋性分析。在這些範例中，內送資料集具有四個功能資料欄，以及一個二進位標籤資料欄Target。資料集的檔案內容如下。1的標籤值表示正面結果。資料集會透過 dataset 處理輸入提供給 SageMaker Clarify 任務。

"Target","Age","Gender","Income","Occupation"
0,25,0,2850,2
1,36,0,6585,0
1,22,1,1759,1
0,48,0,3446,1
...

以下各章節說明如何運算訓練前和訓練後偏差指標、SHAP 值以及部分相依性繪圖 (PDP)，以顯示 CSV 格式資料集的功能重要性。

運算所有訓練前偏差指標

此範例組態顯示如何測量先前的範例資料集是否偏向 Gender 值為 0 的範例。下列分析組態說明 SageMaker Clarify 處理任務運算資料集的所有訓練前偏差指標。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

運算所有訓練後偏差指標

您可以在訓練前運算訓練前偏差指標。但是，您必須擁有訓練好的模型才能運算訓練後的偏差指標。下列範例輸出來自二進制分類模型，該模型以 CSV 格式輸出資料。在此範例輸出中，每一列都包含兩欄。第一欄包含預測標籤，第二欄則包含該標籤的機率值。

0,0.028986845165491
1,0.825382471084594
...

下列組態範例說明 SageMaker Clarify 處理任務，使用資料集和模型輸出的預測來運算所有可能的偏差指標。在此範例中，模型會部署到 SageMaker AI 端點 your_endpoint。

注意

在下列範例程式碼中，未設定和參數 content_type 和 accept_type。因此，它們會自動使用參數 dataset_type 的值，也就是 text/csv。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "label": 0
    }
}

運算 SHAP 值

以下範例分析組態說明任務運算 SHAP 值，將 Target 欄指定為標籤，並將所有其他欄指定為功能。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

在此範例中，會省略 SHAP baseline 參數，且 num_clusters 參數的值為 1。這會指示 SageMaker Clarify 處理器運算一個 SHAP 基準範例。在此範例中，機率設定為 1。這會指示 SageMaker Clarify 處理任務從模型輸出的第二欄擷取機率分數 (使用從零開始的索引)。

運算部分相依性繪圖 (PDP)

下列範例顯示如何使用 PDP 在分析報告中檢視 Income 功能的重要性。報告參數會指示 SageMaker Clarify 處理任務產生報告。任務完成後，產生的報告會以 report.pdf 的形式儲存至 analysis_result 位置。grid_resolution 參數會將功能值的範圍劃分為 10 儲存貯體。在下列範例中指定的參數一起指示 SageMaker Clarify 處理任務產生一個報告，其中包含在 x 軸上具有 10 區段的 Income PDP 圖表的報告。y 軸將顯示對 Income 預測的邊際影響。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "pdp": {
            "features": ["Income"],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    },
}

運算偏差指標和功能重要性

您可以將之前的組態範例中，所有方法合併為單一分析組態檔案，然後透過單一任務進行全部運算。下列範例顯示結合所有步驟的分析組態。

在此範例中，probability 參數設定為 1，指出機率包含在第二欄中 (使用從零開始的索引)。但是，由於偏差分析需要預測標籤，因此 probability_threshold 參數設定為 0.5，將機率分數轉換為二進位標籤。在此範例中，部分相依繪圖 pdp 方法的 top_k_features 參數設定為 2。這會指示 SageMaker Clarify 處理任務針對具有最大全域 SHAP 值的頂部 2 功能運算部分相依性繪圖 (PDP)。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

您可以使用 model_name 參數將 SageMaker AI 模型的名稱提供給 SageMaker Clarify 處理任務，而不是將模型部署到端點。下列範例示範如何指定名為 your_model 的模型。SageMaker Clarify 處理任務將使用組態建立陰影端點。

{
     ...
    "predictor": {
        "model_name": "your_model",
        "initial_instance_count": 1,
        "instance_type": "ml.m5.large",
        "probability": 1
    }
}

下列範例說明如何針對 JSON 行格式的表格式資料集設定偏差分析和解釋性分析。在這些範例中，傳入資料集具有與上一節相同的資料，但它們採用 SageMaker AI JSON Lines 密集格式。每行都是有效的 JSON 物件。主要 “特徵” 指向特徵值的陣列，主要 “標籤” 指向 Ground Truth 標籤。資料集是由 “資料集” 處理輸入提供給 SageMaker Clarify 工作。如需 JSON Lines 的詳細資訊，請參閱 JSONLINES 請求格式。

{"Features":[25,0,2850,2],"Label":0}
{"Features":[36,0,6585,0],"Label":1}
{"Features":[22,1,1759,1],"Label":1}
{"Features":[48,0,3446,1],"Label":0}
...

下列各章節說明如何運算訓練前和訓練後偏差指標、SHAP 值，以及部分相依性繪圖 (PDP)，以 JSON 行格式顯示資料集的功能重要性。

運算訓練前的偏向指標

指定標籤、功能、格式和方法，以測量 Gender 值為0 的訓練前偏差指標。在下列範例中，headers 參數會先提供功能名稱。標籤名稱最後提供。按照慣例，最後一個標題是標籤標題。

此 features 參數設定為 JMESPath 運算式 “特徵”，以便 SageMaker Clarify 處理工作可以從每個記錄中擷取特徵陣列。此 label 參數設定為 JMESPath 運算式 “標籤”，以便 SageMaker Clarify 處理工作可以從每個記錄中擷取 Ground Truth 標籤。使用面向名稱來指定敏感屬性，如下所示。

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

運算所有偏差指標

您必須擁有訓練好的模型，才能運算訓練後的偏差指標。下列範例來自二進制分類模型，該模型會以範例的格式輸出 JSON 行資料。模型輸出的每一列都是有效的 JSON 物件。鍵predicted_label指向預測標籤，鍵probability指向機率值。

{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...

您可以將模型部署到名為 的 SageMaker AI 端點your_endpoint。下列範例分析組態說明 SageMaker Clarify 處理任務運算資料集和模型的所有可能偏差指標。在此範例中，參數 content_type 和 accept_type 未設定。因此，它們會自動設定為使用參數 dataset_type 的值，也就是 application/jsonlines。SageMaker Clarify 處理任務使用 content_template 參數來構成模型輸入，方法是以功能陣列取代 $features 預留位置。

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "label": "predicted_label"
    }
}

運算 SHAP 值

由於 SHAP 分析不需要 Ground Truth 標籤，因此會省略 label 參數。在此範例中，也會省略 headers 參數。因此，SageMaker Clarify 處理任務必須使用一般名稱 (例如 column_0 或 column_1 功能標題) 以及 label0，為標籤標題產生預留位置。您可以指定 headers 和 a label 的值，以提高分析結果的可讀性。由於機率參數設定為 JMESPath 表達式 probability，機率值將從模型輸出中擷取。以下是運算 SHAP 值的範例。

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

運算部分相依性繪圖 (PDP)

下列範例示範如何檢視 PDP 上 “收入” 的重要性。在此範例中，不會提供功能標題。因此，pdp 方法的 features 參數必須使用從零開始的索引來參考功能資料欄的位置。grid_resolution 參數會將功能值的範圍劃分為 10 儲存貯體。範例中的參數共同指示 SageMaker Clarify 處理任務產生一個報告，其中包含在 X 軸上具有 10 區段的 Income PDP 圖表。y 軸將顯示對 Income 預測的邊際影響。

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

運算偏差指標和功能重要性

您可以將所有先前的方法合併為一個分析組態檔案，然後透過單一任務來運算它們。下列範例顯示結合所有步驟的分析組態。在此範例中，已設定 probability 參數。但是由於偏差分析需要預測標籤，因此 probability_threshold 參數被設定為 0.5，將機率分數轉換為二進制標籤。在此範例中，pdp 方法的 top_k_features 參數設定為 2。這會指示 SageMaker Clarify 處理任務運算具有最大全域 SHAP 值的頂層 2 功能的 PDP。

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

下列範例說明如何針對 JSON 格式的表格式資料集設定偏差和解釋性分析。在這些範例中，傳入資料集具有與上一節相同的資料，但它們採用 SageMaker AI JSON 密集格式。如需 JSON Lines 的詳細資訊，請參閱 JSONLINES 請求格式。

整個輸入請求是有效的 JSON，其中外部結構是一個清單，每個元素是記錄的資料。在每個記錄中，關鍵 Features 指向功能值的陣列，並且關鍵 Label 指向 Ground Truth 標籤。資料集會透過 dataset 處理輸入提供給 SageMaker Clarify 任務。

[
    {"Features":[25,0,2850,2],"Label":0},
    {"Features":[36,0,6585,0],"Label":1},
    {"Features":[22,1,1759,1],"Label":1},
    {"Features":[48,0,3446,1],"Label":0},
    ...
]

下列各章節說明如何運算訓練前和訓練後偏差指標量、SHAP 值，以及部分依賴性繪圖 (PDP)，這些圖表顯示JSON 行格式的資料集的功能重要性。

運算訓練前的偏向指標

指定標籤、功能、格式和方法，以測量 Gender 值為0 的訓練前偏差指標。在下列範例中，headers 參數會先提供功能名稱。標籤名稱最後提供。對於 JSON 資料集，最後一個標題是標籤標題。

features 參數設定為擷取二維陣列或矩陣的 JMESPath 運算式。此矩陣中的每一列都必須包含每筆記錄 Features 的清單。label 參數設定為 JMESPath 表達式，該表達式擷取 Ground Truth 標籤清單。此清單中的每個元素都必須包含記錄的標籤。

使用面向名稱來指定敏感屬性，如下所示。

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

運算所有偏差指標

您必須擁有訓練好的模型，才能運算訓練後的偏差指標。下列程式碼範例來自二進制分類模型，該模型會以範例的格式輸出 JSON 資料。在範例中，predictions 下的每個元素都是記錄的預測輸出。範例程式碼包含指向預測標籤的鍵 predicted_label，以及指向機率值的鍵 probability。

{
    "predictions": [
        {"predicted_label":0,"probability":0.028986845165491},
        {"predicted_label":1,"probability":0.825382471084594},
        ...
    ]
}

您可以將模型部署到名為 的 SageMaker AI 端點your_endpoint。

在下列範例中，未設定 content_type 和 accept_type 參數。因此，content_type 和 accept_type 自動設定為使用參數 dataset_type 值，即 application/json。然後，SageMaker Clarify 處理任務會使用 content_template 參數來構成模型輸入。

在下列範例中，模型輸入是以記錄陣列取代 $records 預留位置所組構成。然後，record_template 參數會組成每個記錄的 JSON 結構，並以每個記錄的功能陣列取代 $features 預留位置。

下列範例分析組態說明 SageMaker Clarify 處理任務運算資料集和模型的所有可能偏差指標。

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "label": "predictions[*].predicted_label"
    }
}

運算 SHAP 值

您不需要指定 SHAP 分析的標籤。在下列範例中，未指定 headers 參數。因此，SageMaker Clarify 處理任務將會使用一般名稱，例如功能標題 column_0 或 column_1，以及 label0，為標籤標題產生預留位置。您可以指定 headers 和 a label 的值，以提高分析結果的可讀性。

在下列組態範例中，機率參數設定為 JMESPath 運算式，該運算式會從每筆記錄的每個預測中擷取機率。以下是運算 SHAP 值的範例。

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

運算部分相依性繪圖 (PDP)

下列範例示範如何在 PDP 中檢視功能重要性。在此範例中，不提供功能標題。因此，pdp 方法的 features 參數必須使用從零開始的索引來參考功能資料欄的位置。grid_resolution 參數會將功能值的範圍劃分為 10 儲存貯體。

下列範例中的參數共同指示 SageMaker Clarify 處理任務產生一個報告，其中包含在 x 軸上具有 10 區段的 Income PDP 圖表報告。y 軸顯示對預測的 Income 邊際影響。

下列組態範例顯示如何檢視 PDP Income 上的重要性。

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

運算偏差指標和功能重要性

您可以將所有之前的組態方法合併為單一分析組態檔案，然後透過單一任務進行運算。下列範例顯示結合所有步驟的分析組態。

在此範例中，已設定 probability 參數。因為偏差分析需要預測標籤，所以 probability_threshold 參數設定為 0.5，用於將機率分數轉換為二進位標籤。在此範例中，pdp 方法的 top_k_features 參數設定為 2。這會指示 SageMaker Clarify 處理任務運算具有最大全域 SHAP 值的頂層 2 功能的 PDP。

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

下列範例顯示用於運算自然語言處理 (NLP) 之功能重要性的分析組態檔案。在此範例中，內送資料集是 CSV 格式的表格式資料集，其中包含一個二進位標籤資料欄和兩個功能資料欄，如下所示。資料集會透過 dataset 處理輸入提供給 SageMaker Clarify 任務。

0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...

在此範例中，在先前的資料集上訓練了二進制分類模型。模型接受 CSV 資料，並在 0 和 1 之間輸出單一分數，如下所示。

0.491656005382537
0.569582343101501
...

此模型用於建立名為「your_model」的 SageMaker AI 模型。以下分析組態顯示如何使用模型和資料集執行權杖化的解釋性分析。此 text_config 參數會啟動 NLP 解釋性分析。該 granularity 參數指示分析應該剖析符記。

在英語中，每個符記都是一個單詞。下列範例也展示如何使用 4 的平均 “評比” 來提供就地 SHAP “基準線” 執行個體。特殊的遮罩符記 “[MASK]” 用於取代 “註解” 中的權杖 (文字)。此範例也會使用 GPU 端點執行個體類型來加速推論。

{
    "dataset_type": "text/csv",
    "headers": ["Target","Rating","Comments"]
    "label": "Target",
    "methods": {
        "shap": {
            "text_config": {
                "granularity": "token",
                "language": "english"
            }
            "baseline": [[4,"[MASK]"]],
        }
    },
    "predictor": {
        "model_name": "your_nlp_model",
        "initial_instance_count": 1,
        "instance_type": "ml.g4dn.xlarge"
    }
}

以下的範例顯示了一個分析組態檔案運算功能對電腦視覺的重要性。在此範例中，輸入資料集由 JPEG 映像組成。資料集會透過 dataset 處理輸入提供給 SageMaker Clarify 任務。此範例顯示如何使用 SageMaker 映像分類模型設定解釋性分析。在這個範例中，一個名為 your_cv_ic_model 的模型已經被訓練，以對輸入的 JPEG 映像的動物進行分類。

{
    "dataset_type": "application/x-image",
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "IMAGE_CLASSIFICATION",
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_ic_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

如需影像分類的詳細資訊，請參閱 影像分類 - MXNet。

在此範例中，SageMaker AI 物件偵測模型your_cv_od_model在相同的 JPEG 影像上訓練，以識別動物。以下的範例說明如何設定物件偵測模型的解釋性分析。

{
    "dataset_type": "application/x-image",
    "probability_threshold": 0.5,
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "OBJECT_DETECTION",
                 "max_objects": 3,
                "context": 1.0,
                "iou_threshold": 0.5,
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_od_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

下列範例顯示分析組態檔案，用於計算時間序列 (TS) 的功能重要性。在此範例中，傳入資料集是 JSON 格式的時間序列資料集，具有一組動態和靜態共變數功能。資料集由資料集處理輸入參數 提供給 SageMaker Clarify 任務dataset_uri。

[
    {
        "item_id": "item1",
        "timestamp": "2019-09-11",
        "target_value": 47650.3,
        "dynamic_feature_1": 0.4576,
        "dynamic_feature_2": 0.2164,
        "dynamic_feature_3": 0.1906,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item1",
        "timestamp": "2019-09-12",
        "target_value": 47380.3,
        "dynamic_feature_1": 0.4839,
        "dynamic_feature_2": 0.2274,
        "dynamic_feature_3": 0.1889,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item2",
        "timestamp": "2020-04-23",
        "target_value": 35601.4,
        "dynamic_feature_1": 0.5264,
        "dynamic_feature_2": 0.3838,
        "dynamic_feature_3": 0.4604,
        "static_feature_1": 1,
        "static_feature_2": 2
    },
]

下列各節說明如何使用 JSON 資料集的非對稱 Shapley 值演算法來計算預測模型的功能屬性。

計算時間序列預測模型的說明

下列範例分析組態會顯示任務用來計算時間序列預測模型說明的選項。

{
    'dataset_type': 'application/json',
    'dataset_uri': 'DATASET_URI',
    'methods': {
        'asymmetric_shapley_value': {
            'baseline': {
                "related_time_series": "zero",
                "static_covariates": {
                    "item1": [0, 0], "item2": [0, 0]
                },
                "target_time_series": "zero"
            },
            'direction': 'chronological',
            'granularity': 'fine_grained',
            'num_samples': 10
        },
        'report': {'name': 'report', 'title': 'Analysis Report'}
    },
    'predictor': {
        'accept_type': 'application/json',
        'content_template': '{"instances": $records}',
        'endpoint_name': 'ENDPOINT_NAME', 
        'content_type': 'application/json',              
        'record_template': '{
            "start": $start_time, 
            "target": $target_time_series, 
            "dynamic_feat": $related_time_series, 
            "cat": $static_covariates
        }',
        'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
    },
    'time_series_data_config': {
        'dataset_format': 'timestamp_records',
        'item_id': '[].item_id',
        'related_time_series': ['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
        'static_covariates': ['[].static_feature_1', '[].static_feature_2'],
        'target_time_series': '[].target_value',
        'timestamp': '[].timestamp'
    }
}
時間序列可解釋性組態

上述範例使用 asymmetric_shapley_value中的 methods來定義時間序列可解釋性引數，例如基準、方向、精細程度和樣本數量。系統會為這三種類型的資料設定基準值：相關時間序列、靜態共變數和目標時間序列。這些欄位會指示 SageMaker Clarify 處理器一次運算一個項目的功能屬性。

預測器組態

您可以使用 JMESPath 語法，完全控制 SageMaker Clarify 處理器傳送的承載結構。在上述範例中，predictor組態會指示 Clarify 將記錄彙總到 '{"instances": $records}' ，其中每個記錄都是使用record_template範例中為 提供的引數來定義。請注意，$start_time、$related_time_series、 和 $target_time_series$static_covariates是用於將資料集值映射至端點請求值的內部字符。

同樣地， forecast中的 屬性time_series_predictor_config用於從端點回應擷取模型預測。例如，您的端點批次回應可能如下：

{
    "predictions": [
        {"mean": [13.4, 3.6, 1.0]}, 
        {"mean": [23.0, 4.7, 3.0]}, 
        {"mean": [3.4, 5.6, 2.0]}
    ]
}

假設您指定下列時間序列預測器組態：

'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}

預測值剖析如下：

[
    [13.4, 3.6],
    [23.0, 4.7],
    [3.4, 5.6]
]
資料組態

使用 time_series_data_config 屬性指示 SageMaker Clarify 處理器從 中以 S3 URI 形式傳遞的資料正確剖析資料dataset_uri。