本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 生產中模型的特徵屬性偏離 生產中模型的即時資料分佈偏離可能會導致功能屬性值中對應的偏離，就像在監控偏差指標時可能會導致偏差偏離一樣。Amazon SageMaker Clarify 功能屬性監控可協助資料科學家和機器學習 (ML) 工程師定期監控功能屬性偏離的預測。當模型受到監控時，客戶可以在 SageMaker Studio 中檢視可匯出的報告和圖表以詳細說明功能屬性，並在 Amazon CloudWatch 中設定警示以便在偵測到屬性值偏離超過特定閾值時接收通知。 為了用具體情況來說明這一點，請假設一個大學入學的情況。假設我們在訓練資料和即時資料中觀察到下列 (彙總) 功能屬性值： 大學入學假設情況 | 功能 | 訓練資料中的屬性 | 即時資料中的屬性 | | --- | --- | --- | | SAT 分數 | 0.70 | 0.10 | | GPA | 0.50 | 0.20 | | 班級排名 | 0.05 | 0.70 | 從訓練資料到即時資料的變更看起來顯著。功能排名已完全顛倒。與偏差偏離類似，功能屬性偏離可能是由於即時資料分佈的變更所造成，並保證仔細研究即時資料上的模型行為。同樣地，在這些情況下的第一步是提出偏離已發生的警示。 我們可以透過比較從訓練資料到即時資料的各個功能排名如何變更來偵測偏離。除了對排名順序的變更敏感之外，我們還希望對功能的原始屬性分數敏感。舉例來說，假設在排名中的兩個功能從訓練到即時資料的名次都相同，則我們希望對訓練資料中屬性分數較高的功能更加敏感。考慮到這些屬性，我們會使用標準化折扣累計收益 (NDCG) 分數來比較訓練和即時資料的功能屬性排名。 具體來說，假設我們有以下情況： + *F=[f1​,…,fm​] * 是在訓練資料中根據其屬性分數排序的功能清單，其中 *m* 是功能總數。例如，在我們的情況下，*F*=[SAT 分數, GPA, 班級排名]。 + *a(f)* 是在特定功能 *f* 的訓練資料上傳回功能屬性分數的函式。例如，*a*(SAT 分數) = 0.70。 + *F′=[f′​1​, …, f′​m​] *是根據即時資料中的屬性分數排序的功能清單。例如，*F*′= [班級排名, GPA, SAT 分數]。 然後，我們可以將 NDCG 計算為：         NDCG=DCG/iDCG​ 取代為 + DCG = ∑1m*a*(*f'i*)/log2​(*i*\$11) + iDCG = ∑1m*a*(*fi*)/log2​(*i*\$11) 數量 DCG 會測量訓練資料中具有高屬性的功能是否也會在即時資料中計算的功能屬性中排名較高。數量 iDCG 會測量*理想分數*，它只是一個正常化係數，以確保最終數量駐留在範圍 [0, 1] 內，其中 1 是最佳的可能值。NDCG 值為 1 表示即時資料中的功能屬性排名與訓練資料中的功能屬性排名相同。在此特定範例中，由於排名變更了很多，因此 NDCG 值為 0.69。 在 SageMaker Clarify 中，如果 NDCG 值低於 0.90，我們會自動提出警示。 ## 模型監控範例筆記本 SageMaker Clarify 提供下列範例筆記本，其中顯示如何擷取即時端點的推論資料、建立基準以監控不斷發展的偏差，以及檢查結果： + [監控偏差偏離和功能屬性偏離 Amazon SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.html) – 使用 Amazon SageMaker Model Monitor 來監控一段時間後的偏差偏離和功能屬性偏離。 此筆記本已通過驗證，只能在 SageMaker Studio 中執行。如果您需要有關如何在 SageMaker Studio 中打開筆記本的說明，請參閱[建立或開啟 Amazon SageMaker Studio Classic 筆記本](notebooks-create-open.md)。如果系統提示您選擇核心，請選擇 **Python 3 (資料科學)**。下列主題包含最後兩個步驟的重點內容，其中包含範例筆記本的程式碼範例。 **Topics** + [模型監控範例筆記本](#clarify-model-monitor-sample-notebooks-feature-drift) + [為生產中的模型建立 SHAP 基準](clarify-model-monitor-shap-baseline.md) + [模型功能屬性偏離違規](clarify-model-monitor-model-attribution-drift-violations.md) + [要監控屬性偏離的參數](clarify-config-json-monitor-model-explainability-parameters.md) + [排程功能屬性偏離監控工作](clarify-model-monitor-feature-attribute-drift-schedule.md) + [檢查生產模型中功能屬性偏離的報告](clarify-feature-attribute-drift-report.md) + [功能偏離分析的 CloudWatch 指標](clarify-feature-attribute-drift-cw.md) # 為生產中的模型建立 SHAP 基準 解釋通常是相反的 (也就是說，它們說明偏離基準的情況)。如需可解釋性基準的資訊，請參閱[用於可解釋性的 SHAP 基準](clarify-feature-attribute-shap-baselines.md)。 除了針對每個執行個體推論提供說明之外，SageMaker Clarify 也支援機器學習 (ML) 模型的全域說明，協助您根據模型的功能來瞭解整個模型的行為。SageMaker Clarify 透過彙總多個執行個體的 Shapley 值，產生機器學習 (ML) 模型的全域說明。SageMaker Clarify 支援下列不同的彙總方式，您可以使用這些方式來定義基準： + `mean_abs` – 所有執行個體的絕對 SHAP 值的平均值。 + `median` – 所有執行個體的 SHAP 值的中間值。 + `mean_sq` – 所有執行個體的平方 SHAP 值的平均值。 將應用程式設定為擷取即時或批次轉換推論資料之後，監控功能屬性偏離的第一項任務就是建立要比較的基準。這包括設定資料輸入、哪些群組是敏感的、如何擷取預測，以及模型及其訓練後的偏差指標。然後，您需要開始進行基準工作。模型可解釋性監控可以解釋已部署模型的預測，該模型會產生推論並定期偵測功能屬性偏離。 ``` model_explainability_monitor = ModelExplainabilityMonitor( role=role, sagemaker_session=sagemaker_session, max_runtime_in_seconds=1800, ) ``` 在這個範例中，可解釋性基準工作與偏差基準工作共用測試資料集，因此它使用相同的 `DataConfig`，唯一的差異是任務輸出 URI。 ``` model_explainability_baselining_job_result_uri = f"{baseline_results_uri}/model_explainability" model_explainability_data_config = DataConfig( s3_data_input_path=validation_dataset, s3_output_path=model_explainability_baselining_job_result_uri, label=label_header, headers=all_headers, dataset_type=dataset_type, ) ``` 目前 SageMaker Clarify 解釋器提供了 SHAP 的可擴展性和高效，因此可解釋性組態是 ShapConfig，包括以下內容： + `baseline` – 要在核心 SHAP 演算法中用作基準資料集的資料列 (至少一個) 或 S3 物件 URI 的清單。此格式應與資料集格式相同。每一列應該只包含功能欄/值，並省略標籤欄/值。 + `num_samples` – 要在核心 SHAP 演算法中使用的樣本數。此數字決定產生的合成資料集的大小來計算 SHAP 值。 + agg\$1method — 全域 SHAP 值的彙總方法。以下為有效值： + `mean_abs` – 所有執行個體的絕對 SHAP 值的平均值。 + `median` – 所有執行個體的 SHAP 值的中間值。 + `mean_sq` – 所有執行個體的平方 SHAP 值的平均值。 + `use_logit` – 是否將 logit 函式套用於模型預測的指示器。預設值為 `False`。如果 `use_logit` 是 `True`，SHAP 值將有對數機率單位。 + `save_local_shap_values` (bool) – 是否將本機 SHAP 值儲存在輸出位置的指示器。預設值為 `False`。 ``` # Here use the mean value of test dataset as SHAP baseline test_dataframe = pd.read_csv(test_dataset, header=None) shap_baseline = [list(test_dataframe.mean())] shap_config = SHAPConfig( baseline=shap_baseline, num_samples=100, agg_method="mean_abs", save_local_shap_values=False, ) ``` 開始基準工作。需要相同的 `model_config`，因為可解釋性基準工作需要建立陰影端點以取得產生的合成資料集的預測。 ``` model_explainability_monitor.suggest_baseline( data_config=model_explainability_data_config, model_config=model_config, explainability_config=shap_config, ) print(f"ModelExplainabilityMonitor baselining job: {model_explainability_monitor.latest_baselining_job_name}") ``` # 模型功能屬性偏離違規 功能屬性偏離工作會根據目前 `MonitoringExecution` 的分析結果，評估[基準組態](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelExplainabilityJobDefinition.html#sagemaker-CreateModelExplainabilityJobDefinition-request-ModelExplainabilityBaselineConfig)提供的基準限制條件。如果偵測到違規，工作會將其列於執行輸出位置中的 *constraint\$1violations.json* 檔案，並將執行狀態標記為 [解讀結果](model-monitor-interpreting-results.md)。 以下是功能屬性偏離違規檔案的結構描述。 + `label` – 標籤名稱、工作分析組態 `label_headers` 或預留位置，例如 `"label0"`。 + `metric_name` – 可解釋性分析方法的名稱。目前僅支援 `shap`。 + `constraint_check_type` – 監控的違規類型。目前僅支援 `feature_attribution_drift_check`。 + `description` – 說明違規的描述訊息。 ``` { "version": "1.0", "violations": [{ "label": "string", "metric_name": "string", "constraint_check_type": "string", "description": "string" }] } ``` 對於 `explanations` 區段中的每個標籤，監控工作會計算其在基準限制檔案和工作分析結果檔案 (*analysis.json*) 中的全域 SHAP 值的 [nDCG 分數](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.ndcg_score.html)。如果分數小於 0.9，會記錄違規。會評估合併的全域 SHAP 值，因此違規項目中沒有 `“feature”` 欄位。下列輸出提供幾個記錄違規的範例。 ``` { "version": "1.0", "violations": [{ "label": "label0", "metric_name": "shap", "constraint_check_type": "feature_attribution_drift_check", "description": "Feature attribution drift 0.7639720923277322 exceeds threshold 0.9" }, { "label": "label1", "metric_name": "shap", "constraint_check_type": "feature_attribution_drift_check", "description": "Feature attribution drift 0.7323763972092327 exceeds threshold 0.9" }] } ``` # 要監控屬性偏離的參數 Amazon SageMaker Clarify 可解釋性監控會重複使用 [分析組態檔案](clarify-processing-job-configure-analysis.md) 的分析組態中使用的參數子集。下列參數必須在 JSON 檔案中提供，且必須在 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelExplainabilityAppSpecification](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelExplainabilityAppSpecification) 的 `ConfigUri` 參數中提供路徑。 + `"version"` –(選用) 組態檔案的結構描述版本。如果未提供，則會使用最新的支援版本。 + `"headers"` –(選用) 資料集中的功能名稱清單。可解釋性分析不需要標籤。 + `"methods"` – 用於分析和報告的方法及其參數的清單。如果省略了任何區段，則不列入計算。 + `"shap"` –(選用) SHAP 值計算的區段。 + `"baseline"` –(選用) 資料列清單(至少一個)，或 Amazon Simple Storage Service Amazon S3 物件 URI。用作核心 SHAP 演算法中的基準資料集 (也稱為背景資料集)。此格式應與資料集格式相同。每一列應該只包含功能欄 (或值)。在將每一列傳送至模型之前，省略必須排除的任何欄。 + `"num_samples"` – 要在核心 SHAP 演算法中使用的樣本數。此數字決定產生的合成資料集的大小來計算 SHAP 值。如果未提供，則 SageMaker Clarify 工作會根據功能計數來選擇值。 + `"agg_method"` – 全域 SHAP 值的彙總方法。有效值如下： + `"mean_abs"` – 所有執行個體的絕對 SHAP 值的平均值。 + `"median"` – 所有執行個體的 SHAP 值的中間值。 + `"mean_sq"` – 所有執行個體的平方 SHAP 值的平均值。 + `"use_logit"` –(選用) 布林值，指出 logit 函式是否要套用至模型預測。如果 `"use_logit"` 是 `true`，則 SHAP 值有對數機率單位。預設值為 `false`。 + `"save_local_shap_values"` –(選用) 布林值，指示是否要將本機 SHAP 值儲存在輸出位置。使用 `true` 以儲存。使用 `false` 不要儲存。預設值為 `false`。 + `"predictor"` – (即時端點為選用，批次轉換為必要) 模型參數的區段，如果 `"shap"` 和 `"post_training_bias"` 區段存在，則為必要。 + `"model_name"` – 由 `CreateModel` API 建立的模型名稱，容器模式為 `SingleModel`。 + `"instance_type"` – 陰影端點的執行個體類型。 + `"initial_instance_count"` – 陰影端點的執行個體計數。 + `"content_type"` –(選用) 用於透過陰影端點取得推論的模型輸入格式。有效值為 `"text/csv"` (對於 CSV)、`"application/jsonlines"` (對於 JSON 行)、`application/x-parquet` (對於 Apache Parquet)，以及 `application/x-image` 以啟用電腦視覺可解釋性。預設值與 `dataset_type` 格式相同。 + `"accept_type"` –(選用) 用於透過陰影端點取得推論的模型*輸出*格式。有效值為 `"text/csv"` (對於 CSV)、`"application/jsonlines"` (對於 JSON 行)。如果省略，SageMaker Clarify 會使用擷取資料的回應資料類型。 + `"content_template"` –(選用) 用來建構資料集執行個體之模型輸入的範本字串。只有在 `"content_type"` 為 `"application/jsonlines"` 時才會使用。該範本應只有一個預留位置 `$features`，它在執行期時被功能清單取代。例如，指定 `"content_template":"{\"myfeatures\":$features}"`，如果執行個體 (無標籤) 是 `1,2,3`，則模型輸入變為 JSON 行 `'{"myfeatures":[1,2,3]}'`。 + `"label_headers"` –(選用) 資料集中 `"label"` 接收的值清單。將模型端點或批次轉換工作傳回的分數與其對應的標籤值相關聯。如果有提供，則分析報告會使用標題，而不是像 `“label0”` 的預留位置。 其他參數應在 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelExplainabilityJobInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelExplainabilityJobInput) API 的 `EndpointInput` (用於即時端點)或 `BatchTransformInput` (用於批次轉換工作)中提供。 + `FeaturesAttribute` – 如果端點或批次工作輸入資料格式為 `"application/jsonlines"`，則此參數是必要項目。如果資料集格式是 JSON 行，它是用於定位功能欄的 JMESPath。 + `ProbabilityAttribute` – 機率的模型輸出中的索引或 JMESPath 位置。例如，如果模型輸出是含有標籤和機率清單的 JSON 行，則會選擇對應於最大機率的標籤進行偏差運算。 ## CSV 和 JSON 行資料集的 JSON 組態檔案範例 以下是 JSON 檔案的範例，用來設定 CSV 和 JSON 行資料集以監控功能屬性偏離。 **Topics** + [CSV 資料集](#clarify-config-json-monitor-model-explainability-parameters-example-csv) + [JSON 行資料集](#clarify-config-json-monitor-model-explainability-parameters-example-jsonlines) ### CSV 資料集 考慮有三個數值特徵欄的資料集，如下列範例所示。 ``` 0.5814568701544718, 0.6651538910132964, 0.3138080342665499 0.6711642728531724, 0.7466687034026017, 0.1215477472819713 0.0453256543003371, 0.6377430803264152, 0.3558625219713576 0.4785191813363956, 0.0265841045263860, 0.0376935084990697 ``` 假設模型輸出有兩欄，其中第一個是預測標籤，第二個是機率，如下列範例所示。 ``` 1, 0.5385257417814224 ``` 下列 JSON 組態檔案會顯示如何設定此 CSV 資料集。 ``` { "headers": [ "feature_1", "feature_2", "feature_3" ], "methods": { "shap": { "baseline": [ [0.4441164946610942, 0.5190374448171748, 0.20722795300473712] ], "num_samples": 100, "agg_method": "mean_abs" } }, "predictor": { "model_name": "my_model", "instance_type": "ml.m5.xlarge", "initial_instance_count": 1 } } ``` 預測標籤由 `"ProbabilityAttribute"` 參數選取。使用從零開始的編號，因此 1 表示模型輸出的第二欄。 ``` "EndpointInput": { ... "ProbabilityAttribute": 1 ... } ``` ### JSON 行資料集 考慮有四個功能欄和一個標籤欄的資料集，其中第一個功能和標籤是二進位，如下列範例所示。 ``` {"features":[0, 0.5814568701544718, 0.6651538910132964, 0.3138080342665499], "label":0} {"features":[1, 0.6711642728531724, 0.7466687034026017, 0.1215477472819713], "label":1} {"features":[0, 0.0453256543003371, 0.6377430803264152, 0.3558625219713576], "label":1} {"features":[1, 0.4785191813363956, 0.0265841045263860, 0.0376935084990697], "label":1} ``` 模型輸入與資料集格式相同，模型輸出為 JSON 行，如下列範例所示。 ``` {"predicted_label":1, "probability":0.5385257417814224} ``` 在下面的範例中，JSON 組態檔案會顯示如何設定此 JSON 行資料集。 ``` { "headers": [ "feature_1", "feature_2", "feature_3" ], "methods": { "shap": { "baseline": [ {"features":[0.4441164946610942, 0.5190374448171748, 0.20722795300473712]} ], "num_samples": 100, "agg_method": "mean_abs" } }, "predictor": { "model_name": "my_model", "instance_type": "ml.m5.xlarge", "initial_instance_count": 1, "content_template":"{\"features\":$features}" } } ``` 然後，`EndpointInput` 中的 `"features"` 參數值 (針對即時端點) 或 `BatchTransformInput` (針對批次轉換工作) 用於訂位資料集中的功能，而 `"probability"` 參數值會從模型輸出中選取機率值。 ``` "EndpointInput": { ... "FeaturesAttribute": "features", "ProbabilityAttribute": "probability", ... } ``` # 排程功能屬性偏離監控工作 建立基準之後，您可以呼叫 `ModelExplainabilityMonitor` 類別執行個體的 `create_monitoring_schedule()` 方法來排程每小時的模型可解釋性監控。以下各節說明如何為部署到即時端點的模型以及批次轉換工作建立模型可解釋性監控。 **重要** 在建立監控排程時，您可以指定批次轉換輸入或端點輸入，但不能同時指定兩者。 如果已提交基準工作，監控會自動從基準工作中挑選分析組態。不過，如果您略過基準步驟，或擷取資料集的性質與訓練資料集的性質不同，您必須提供分析組態。`ModelConfig` 需要 `ExplainabilityAnalysisConfig` 與基準工作需要它的原因相同。請注意，只有在計算功能屬性時才需要功能，因此您應排除 Ground Truth 標籤。 ## 部署至即時端點的模型的功能屬性偏離監控 若要為即時端點排程模型可解釋性監控，請將 `EndpointInput` 執行個體傳遞至 `ModelExplainabilityMonitor` 執行個體的 `endpoint_input` 引數，如下列程式碼範例所示： ``` from sagemaker.model_monitor import CronExpressionGenerator model_exp_model_monitor = ModelExplainabilityMonitor( role=sagemaker.get_execution_role(), ... ) schedule = model_exp_model_monitor.create_monitoring_schedule( monitor_schedule_name=schedule_name, post_analytics_processor_script=s3_code_postprocessor_uri, output_s3_uri=s3_report_path, statistics=model_exp_model_monitor.baseline_statistics(), constraints=model_exp_model_monitor.suggested_constraints(), schedule_cron_expression=CronExpressionGenerator.hourly(), enable_cloudwatch_metrics=True, endpoint_input=EndpointInput( endpoint_name=endpoint_name, destination="/opt/ml/processing/input/endpoint", ) ) ``` ## 批次轉換工作的功能屬性偏離監控 若要為批次轉換工作排程模型可解釋性監控，請將 `BatchTransformInput` 執行個體傳遞至 `ModelExplainabilityMonitor` 執行個體的 `batch_transform_input` 引數，如下列程式碼範例所示： ``` from sagemaker.model_monitor import CronExpressionGenerator model_exp_model_monitor = ModelExplainabilityMonitor( role=sagemaker.get_execution_role(), ... ) schedule = model_exp_model_monitor.create_monitoring_schedule( monitor_schedule_name=schedule_name, post_analytics_processor_script=s3_code_postprocessor_uri, output_s3_uri=s3_report_path, statistics=model_exp_model_monitor.baseline_statistics(), constraints=model_exp_model_monitor.suggested_constraints(), schedule_cron_expression=CronExpressionGenerator.hourly(), enable_cloudwatch_metrics=True, batch_transform_input=BatchTransformInput( destination="opt/ml/processing/data", model_name="batch-fraud-detection-model", input_manifests_s3_uri="s3://amzn-s3-demo-bucket/batch-fraud-detection/on-schedule-monitoring/in/", excludeFeatures="0", ) ) ``` # 檢查生產模型中功能屬性偏離的報告 在您設定的排程依預設開始之後，您必須等待其第一次執行以開始，然後停止排程以避免產生費用。 若要檢查報告，請使用以下程式碼： ``` schedule_desc = model_explainability_monitor.describe_schedule() execution_summary = schedule_desc.get("LastMonitoringExecutionSummary") if execution_summary and execution_summary["MonitoringExecutionStatus"] in ["Completed", "CompletedWithViolations"]: last_model_explainability_monitor_execution = model_explainability_monitor.list_executions()[-1] last_model_explainability_monitor_execution_report_uri = last_model_explainability_monitor_execution.output.destination print(f'Report URI: {last_model_explainability_monitor_execution_report_uri}') last_model_explainability_monitor_execution_report_files = sorted(S3Downloader.list(last_model_explainability_monitor_execution_report_uri)) print("Found Report Files:") print("\n ".join(last_model_explainability_monitor_execution_report_files)) else: last_model_explainability_monitor_execution = None print("====STOP==== \n No completed executions to inspect further. Please wait till an execution completes or investigate previously reported failures.") ``` 如果與基準相比存在任何違規，則會在此列出： ``` if last_model_explainability_monitor_execution: model_explainability_violations = last_model_explainability_monitor_execution.constraint_violations() if model_explainability_violations: print(model_explainability_violations.body_dict) ``` 如果您的模型部署到即時端點，您可以選擇**端點**索引標籤，然後按兩下端點，在 SageMaker Studio 中查看分析結果和 CloudWatch 指標的視覺效果。 # 功能偏離分析的 CloudWatch 指標 本指南顯示可在 SageMaker Clarify 中用於功能屬性偏離分析的 CloudWatch 指標及其屬性。功能屬性偏離監控工作會計算並發佈兩種類型的指標： + 每個功能的全域 SHAP 值。 **注意** 此指標的名稱會將工作分析組態提供的功能名稱附加至 `feature_`。例如，`feature_X` 是功能 `X` 的全域 SHAP 值。 + 指標的 `ExpectedValue`。 這些指標會發佈到以下 CloudWatch 命名空間： + 對於即時端點：`aws/sagemaker/Endpoints/explainability-metrics` + 對於批次轉換工作：`aws/sagemaker/ModelMonitoring/explainability-metrics` 每個指標都具有下列屬性： + `Endpoint`：受監控端點的名稱 (如果適用)。 + `MonitoringSchedule`：監控工作排程的名稱。 + `ExplainabilityMethod`：用來計算 Shapley 值的方法。選擇 `KernelShap`。 + `Label`：工作分析組態 `label_headers` 提供的名稱，或類似 `label0` 的預留位置。 + `ValueType`：指標傳回的值類型。選擇 `GlobalShapValues` 或 `ExpectedValue`。 若要停止發佈指標的監控工作，請在[模型可解釋性工作](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelExplainabilityJobDefinition.html)定義的 `Environment` 對應中將 `publish_cloudwatch_metrics` 設定為 `Disabled`。