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

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

分析組態檔案

若要使用 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 — 資料集的格式。輸入資料集格式可以是下列任何值：

    • 表格式

      • 適用於 CSV 的 text/csv

      • application/jsonlines 適用於SageMaker JSON行密集格式

      • 適用於 JSON 的 application/json

      • application/x-parquet 適用於 Apache Parquet

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

    • 時間序列預測模型說明

      • 適用於 JSON 的 application/json

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

  • 標頭 – （選用）

    • 表格：包含表格資料集資料欄名稱的字串陣列。如果未為 提供值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則 必須是寫入的JMESPath表達式，才能從資料集擷取地面實況標籤。按照慣例，如果指定 headers，則其應包含標籤名稱。

    • 如果 dataset_type是 application/json，label則 必須是寫入的JMESPath表達式，以擷取資料集中每個記錄的地面實況標籤。此JMESPath表達式必須產生標籤清單，其中 ith 標籤與 ith 記錄相關聯。

  • 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 表達式應產生預測標籤的清單，其中 ith 預測標籤是用於 ith 記錄。

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

  • predicted_label_dataset_uri – （選用） 僅適用於 dataset_type 為 時text/csv。資料集URI的 S3，其中包含用於計算訓練後偏差指標 的預測標籤。 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。在probability_threshold下列情況下 SageMaker ，Clarify 處理任務會使用：

    • 在訓練後偏差分析中，如果模型是二進位分類器，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 物件的陣列，由用以測量偏差的敏感屬性組成。您可以使用 facet 來瞭解資料集和模型的偏差特性，即使未使用敏感屬性來訓練模型也可以。如需詳細資訊，請參閱中的 FacetAmazon SageMaker Clarify 偏見和公平條款。每個 facet 物件包含以下欄位：

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

    • value_or_threshold – （選用） 如果 facet是數值，且label_values_or_threshold套用為選取敏感群組的下限，則為必要）。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。資料集URI的 S3，其中包含用於偏差分析的敏感屬性。您可以使用 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 可以是就地基準資料或基準檔案URI的 S3。如果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可以是用於從輸入映像遮罩特徵 （區段） URI之映像的 S3。 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值。如果未指定種子，則每次執行相同任務時，模型可能會輸出略有不同的SHAP值。

      • use_logit – (選用) 布林值，指出您要將 logit 函式套用至模型預測。預設為 false。如果 use_logit是 true，則SHAP值會使用羅吉斯迴歸係數計算，其可以解譯為 log-odds 比率。

      • 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值包含在 analysis.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指標對應於預測和地面真相偵測方塊之間的大型重疊。預設為 0.5。

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

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

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

      • 功能—如果未請求該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。

      • 基準 – （選用） 取代 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 Notebook 報告、HTML報告和PDF報告。此物件具有下列參數：

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

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

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

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

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

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

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

      • 對於電腦視覺解釋性，有效值為 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會傳遞至 的 Accept SageMaker InvokeEndpoint 參數API。

      • 對於電腦視覺可解釋性，如果 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 處理器如何正確剖析 URI中以 S3 形式傳遞的資料dataset_uri。

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

範例分析組態檔案

下列各節包含 範例分析組態檔案，適用於 CSV 格式、JSON行格式的資料，以及自然語言處理 （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值和部分相依性圖表 （PDPs），以 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 端點 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值

下列範例分析組態會指示任務運算將Target資料欄指定為標籤SHAP的值，並將所有其他資料欄指定為 功能。

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

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

運算部分相依性圖表 （PDPs）

下列範例顯示如何使用 檢視分析報告上 Income功能的重要性PDPs。報告參數會指示 SageMaker Clarify 處理任務產生報告。任務完成後，產生的報告會以 report.pdf 的形式儲存至 analysis_result 位置。grid_resolution 參數會將功能值的範圍劃分為 10 儲存貯體。以下範例中指定的參數會指示 SageMaker Clarify 處理任務產生報告，其中包含 x 軸上Income具有 10區段的 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功能，計算部分相依性圖表 （PDPs）。

{
    "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 SageMaker Clarify 處理任務，而不是將模型部署到端點。下列範例示範如何指定名為 your_model 的模型。 SageMaker Clarify 處理任務將使用 組態建立影子端點。

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

下列範例示範如何為JSON行格式的表格式資料集設定偏差分析和可解釋性分析。在這些範例中，傳入的資料集具有與上一節相同的資料，但它們採用 SageMaker JSON行密集格式。每行都是有效的JSON物件。主要 “特徵” 指向特徵值的陣列，主要 “標籤” 指向 Ground Truth 標籤。資料集由「資料集」處理輸入提供給 SageMaker Clarify 任務。如需JSON行的詳細資訊，請參閱 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值和部分相依性圖表 （PDPs），以JSON行格式顯示資料集的功能重要性。

運算訓練前的偏向指標

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

features 參數設定為「特徵」JMESPath表達式，以便 SageMaker Clarify 處理任務可以從每個記錄擷取特徵陣列。label 參數設定為JMESPath「標籤」表達式，以便 SageMaker Clarify 處理任務可以從每個記錄擷取地面實況標籤。使用面向名稱來指定敏感屬性，如下所示。

{
    "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 端點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分析不需要地面實況標籤，因此會省略 label 參數。在此範例中，也會省略 headers 參數。因此， SageMaker Clarify 處理任務必須使用一般名稱產生預留位置，例如功能標頭column_1的 column_0 或 ，以及標籤標頭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"
    }
}

運算部分相依性圖表 （PDPs）

下列範例顯示如何在 上檢視「收入」的重要性PDP。在此範例中，不會提供功能標題。因此，pdp 方法的 features 參數必須使用從零開始的索引來參考功能資料欄的位置。grid_resolution 參數會將功能值的範圍劃分為 10 儲存貯體。範例中的參數會指示 SageMaker Clarify 處理任務產生報告，其中包含 x 軸上Income具有 10區段的 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 處理任務PDPs運算具有最大全域SHAP值的首要2功能。

{
    "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 JSON但它們採用密集格式。如需JSON行的詳細資訊，請參閱 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值和部分相依性圖表 （PDPs），這些圖表以JSON行格式顯示資料集的功能重要性。

運算訓練前的偏向指標

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

features 參數會設定為擷取 2D 陣列或矩陣的JMESPath表達式。此矩陣中的每一列都必須包含每筆記錄 Features 的清單。label 參數設定為可擷取地面實況標籤清單的JMESPath表達式。此清單中的每個元素都必須包含記錄的標籤。

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

{
    "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 端點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"
    }
}

運算部分相依性圖表 （PDPs）

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

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

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

{
    "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 處理任務PDPs運算具有最大全域SHAP值的首要2功能。

{
    "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 模型。以下分析組態顯示如何使用模型和資料集執行權杖化的解釋性分析。text_config 參數會啟用可NLP解釋性分析。granularity參數指示分析應該解析權杖。

在英語中，每個權杖都是一個單詞。下列範例也會示範如何使用平均 SHAP "Rating" 4 提供就地 "baseline" 執行個體。特殊遮罩字符 "【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 物件偵測模型 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_valuemethods定義時間序列可解釋性引數，例如基準、方向、精細度和樣本數量。會針對所有三種類型的資料設定基準值：相關時間序列、靜態共變數和目標時間序列。這些欄位指示 SageMaker Clarify 處理器一次計算一個項目的功能屬性。

Predictor 組態

您可以使用JMESPath語法完全控制 SageMaker Clarify 處理器傳送的承載結構。在上述範例中， 組態會指示 Clarify predictor 將記錄彙總到 '{"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 處理器正確剖析 URI中以 S3 形式傳遞的資料dataset_uri。