本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon SageMaker Model Monitor 支援您自己的容器
Amazon SageMaker Model Monitor 提供預先建置的容器，能夠分析從表格式資料集的端點或批次轉換工作擷取的資料。如果您想使用自有容器，模型監控提供擴充點供您利用。
在幕後，當您建立 `MonitoringSchedule` 時，模型監控最終會啟動處理工作。因此，容器需要知道 [如何建置您自己的處理容器 (進階案例)](build-your-own-processing-container.md) 主題中所記載的處理工作合約。請注意，模型監控會根據排程為您啟動處理工作。調用時，模型監控會為您設定額外的環境變數，以針對排程監控的該特定執行，讓容器有足夠的情境來處理資料。如需容器輸入的其他資訊，請參閱[容器合約輸入](model-monitor-byoc-contract-inputs.md)。
在容器中，您現在可以使用上述環境變數/情境，在自訂程式碼中針對目前時段分析資料集。完成此分析後，您可以選擇發出報告以上傳至 S3 儲存貯體。預先建置容器產生的報告記載於 [容器合約輸出](model-monitor-byoc-contract-outputs.md)。如果您想要在 SageMaker Studio 中啟用報告視覺化，則應該遵循相同的格式。您也可以選擇發出完全自訂的報告。
您也可以依照[適用於使用自有容器的 CloudWatch 指標](model-monitor-byoc-cloudwatch.md)中的指示，從容器發出 CloudWatch 指標。
**Topics**
+ [容器合約輸入](model-monitor-byoc-contract-inputs.md)
+ [容器合約輸出](model-monitor-byoc-contract-outputs.md)
+ [適用於使用自有容器的 CloudWatch 指標](model-monitor-byoc-cloudwatch.md)
# 容器合約輸入
Amazon SageMaker Model Monitor 平台根據指定的排程，調用您的容器程式碼。如果您選擇撰寫自己的容器程式碼，下列環境變數可使用。在此情況下，您可以分析目前資料集或評估限制條件 (如果選擇如此)，並發出指標 (如果適用)。
即時端點和批次轉換工作的可用環境變數相同，`dataset_format` 變數除外。如果您使用的是即時端點，`dataset_format` 變數會支援下列選項：
```
{\"sagemakerCaptureJson\": {\"captureIndexNames\": [\"endpointInput\",\"endpointOutput\"]}}
```
如果您使用的是批次轉換工作，則 `dataset_format` 支援下列選項：
```
{\"csv\": {\"header\": [\"true\",\"false\"]}}
```
```
{\"json\": {\"line\": [\"true\",\"false\"]}}
```
```
{\"parquet\": {}}
```
下列程式碼範例顯示可用於容器程式碼的完整環境變數集 (並使用即時端點的 `dataset_format` 格式)。
```
"Environment": {
"dataset_format": "{\"sagemakerCaptureJson\": {\"captureIndexNames\": [\"endpointInput\",\"endpointOutput\"]}}",
"dataset_source": "/opt/ml/processing/endpointdata",
"end_time": "2019-12-01T16: 20: 00Z",
"output_path": "/opt/ml/processing/resultdata",
"publish_cloudwatch_metrics": "Disabled",
"sagemaker_endpoint_name": "endpoint-name",
"sagemaker_monitoring_schedule_name": "schedule-name",
"start_time": "2019-12-01T15: 20: 00Z"
}
```
Parameters
| 參數名稱 | Description |
| --- | --- |
| dataset\$1format | 對於從 `Endpoint` 支援的 `MonitoringSchedule` 開始的工作，此為 `sageMakerCaptureJson` 且擷取索引為 `endpointInput`、`endpointOutput` 或兩者兼有。對於批次轉換工作，這會指定資料格式，無論是 CSV、JSON 或 Parquet。 |
| dataset\$1source | 如果您使用的是即時端點，可使用與 `start_time` 和 `end_time` 指定的監控期間對應的資料所在的本機路徑。在此路徑中，資料位於 ` /{endpoint-name}/{variant-name}/yyyy/mm/dd/hh` 中。 我們有時會下載超過開始和結束時間所指定的資料量。容器程式碼會依需要來剖析資料。 |
| output\$1path | 寫入輸出報告和其他檔案的本機路徑。請在 `CreateMonitoringSchedule` 請求中以 `MonitoringOutputConfig.MonitoringOutput[0].LocalPath` 指定此參數。它會上傳到 `MonitoringOutputConfig.MonitoringOutput[0].S3Uri` 中指定的 `S3Uri` 路徑。 |
| publish\$1cloudwatch\$1metrics | 對於由 `CreateMonitoringSchedule` 啟動的工作，此參數設定為 `Enabled`。容器可以選擇在 `[filepath]` 寫入 Amazon CloudWatch 輸出檔案。 |
| sagemaker\$1endpoint\$1name | 如果您使用的是即時端點，則為啟動此排程工作的 `Endpoint` 名稱。 |
| sagemaker\$1monitoring\$1schedule\$1name | 啟動此工作的 `MonitoringSchedule` 名稱。 |
| \$1sagemaker\$1endpoint\$1datacapture\$1prefix\$1 | 如果您使用的是即時端點，則為 `Endpoint` 的 `DataCaptureConfig` 參數中指定的前置詞。如果容器需要直接存取超過 SageMaker AI 在 `dataset_source` 路徑上已下載的資料量，則可以使用此參數。 |
| start\$1time, end\$1time | 此分析執行的時間範圍。例如，對於排定在 05:00 (UTC) 執行的工作和 2020/2/20 執行的工作，`start_time` 為 2020-02-19T06:00:00Z，`end_time` 為 2020-02-20T05:00:00Z |
| baseline\$1constraints: | ` BaselineConfig.ConstraintResource.S3Uri` 中指定的基準限制條件檔案的本機路徑。這只有當 `CreateMonitoringSchedule` 請求中指定此參數時才能使用。 |
| baseline\$1statistics | `BaselineConfig.StatisticsResource.S3Uri` 中指定的基準統計資料檔案的本機路徑。這只有當 `CreateMonitoringSchedule` 請求中指定此參數時才能使用。 |
# 容器合約輸出
容器可以分析 `*dataset_source*` 路徑中可用的資料，並將報告寫入 `*output_path*.` 中的路徑。容器程式碼可以撰寫符合您需求的任何報告。
如果您使用下列結構和合約，SageMaker AI 在視覺化和 API 上會特別處理某些輸出檔案。這只適用於表格式資料集。
表格式資料集的輸出檔案
| 檔案名稱 | Description |
| --- | --- |
| statistics.json | 針對所分析資料集的每個特徵，此檔案會有單欄式統計資料。在下一節可查看此檔案的結構描述。 |
| constraints.json | 針對所觀察的特徵，此檔案會有限制條件。在下一節可查看此檔案的結構描述。 |
| constraints\$1violations.json | 與 `baseline_constaints` 和 `baseline_statistics` 路徑中指定的基準統計資料和限制條件檔案相比較之後，此檔案中預期會有目前這組資料中發現的違規清單。 |
此外，如果 `publish_cloudwatch_metrics` 值為 `"Enabled"`，容器程式碼可以在此位置發出 Amazon CloudWatch 指標：`/opt/ml/output/metrics/cloudwatch`。下列各節描述這些檔案的結構描述。
**Topics**
+ [統計資料的結構描述 (statistics.json 檔案)](model-monitor-byoc-statistics.md)
+ [限制條件的結構描述 (constraints.json 檔案)](model-monitor-byoc-constraints.md)
# 統計資料的結構描述 (statistics.json 檔案)
針對基準和擷取的資料，`statistics.json` 檔案中定義的結構描述指定要計算的統計參數。另外還設定儲存貯體供 [KLL](https://datasketches.apache.org/docs/KLL/KLLSketch.html) 使用 (非常簡潔的分位數草圖，具有延遲壓縮配置)。
```
{
"version": 0,
# dataset level stats
"dataset": {
"item_count": number
},
# feature level stats
"features": [
{
"name": "feature-name",
"inferred_type": "Fractional" | "Integral",
"numerical_statistics": {
"common": {
"num_present": number,
"num_missing": number
},
"mean": number,
"sum": number,
"std_dev": number,
"min": number,
"max": number,
"distribution": {
"kll": {
"buckets": [
{
"lower_bound": number,
"upper_bound": number,
"count": number
}
],
"sketch": {
"parameters": {
"c": number,
"k": number
},
"data": [
[
num,
num,
num,
num
],
[
num,
num
][
num,
num
]
]
}#sketch
}#KLL
}#distribution
}#num_stats
},
{
"name": "feature-name",
"inferred_type": "String",
"string_statistics": {
"common": {
"num_present": number,
"num_missing": number
},
"distinct_count": number,
"distribution": {
"categorical": {
"buckets": [
{
"value": "string",
"count": number
}
]
}
}
},
#provision for custom stats
}
]
}
```
**備註**
在稍後的視覺化變更中，SageMaker AI 可辨識指定的指標。如果需要，容器可以發出更多指標。
[KLL 草圖](https://datasketches.apache.org/docs/KLL/KLLSketch.html)是可辨識的草圖。自訂容器可以撰寫自己的表示法，但無法由 SageMaker AI 在視覺化中辨識。
依預設，分成 10 個儲存貯體將分佈具體化。這無法變更。
# 限制條件的結構描述 (constraints.json 檔案)
constraints.json 檔案是用來表達資料集必須滿足的限制條件。Amazon SageMaker Model Monitor 容器可以使用 constraints.json 檔案來評估資料集。預先建置的容器能夠為基準資料集自動產生 constraints.json 檔案。如果您使用自有容器，則可以在容器中提供類似的功能，或者，您可以用其他方式建立 constraints.json 檔案。以下是預先建置的容器所使用的限制條件檔案的結構描述。使用自有容器可以採用相同的格式，或依需要來增強。
```
{
"version": 0,
"features":
[
{
"name": "string",
"inferred_type": "Integral" | "Fractional" |
| "String" | "Unknown",
"completeness": number,
"num_constraints":
{
"is_non_negative": boolean
},
"string_constraints":
{
"domains":
[
"list of",
"observed values",
"for small cardinality"
]
},
"monitoringConfigOverrides":
{}
}
],
"monitoring_config":
{
"evaluate_constraints": "Enabled",
"emit_metrics": "Enabled",
"datatype_check_threshold": 0.1,
"domain_content_threshold": 0.1,
"distribution_constraints":
{
"perform_comparison": "Enabled",
"comparison_threshold": 0.1,
"comparison_method": "Simple"||"Robust",
"categorical_comparison_threshold": 0.1,
"categorical_drift_method": "LInfinity"||"ChiSquared"
}
}
}
```
`monitoring_config` 物件包含用於監控功能工作的選項。下表描述各個選項。
監控限制條件
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/model-monitor-byoc-constraints.html)
# 適用於使用自有容器的 CloudWatch 指標
在 `/opt/ml/processing/processingjobconfig.json` 檔案的 `Environment` 對應中，如果 `publish_cloudwatch_metrics` 值為 `Enabled`，容器程式碼會在此位置發出 Amazon CloudWatch 指標：`/opt/ml/output/metrics/cloudwatch`。
此檔案的結構描述緊密地以 `PutMetrics` API 為基礎。此處未指定命名空間。它預設為下列項目：
+ `For real-time endpoints: /aws/sagemaker/Endpoint/data-metrics`
+ `For batch transform jobs: /aws/sagemaker/ModelMonitoring/data-metrics`
但是，您可以指定維度。建議您至少增加以下維度：
+ 適用於即時端點的 `Endpoint` 和 `MonitoringSchedule`
+ 適用於批次轉換工作的 `MonitoringSchedule`
下列 JSON 程式碼片段顯示如何設定維度。
如果是即時端點，請參閱下列包含 `Endpoint` 和 `MonitoringSchedule` 維度的 JSON 程式碼片段：
```
{
"MetricName": "", # Required
"Timestamp": "2019-11-26T03:00:00Z", # Required
"Dimensions" : [{"Name":"Endpoint","Value":"endpoint_0"},{"Name":"MonitoringSchedule","Value":"schedule_0"}]
"Value": Float,
# Either the Value or the StatisticValues field can be populated and not both.
"StatisticValues": {
"SampleCount": Float,
"Sum": Float,
"Minimum": Float,
"Maximum": Float
},
"Unit": "Count", # Optional
}
```
如果是批次轉換工作，請參閱下列包含 `MonitoringSchedule` 維度的 JSON 程式碼片段：
```
{
"MetricName": "", # Required
"Timestamp": "2019-11-26T03:00:00Z", # Required
"Dimensions" : [{"Name":"MonitoringSchedule","Value":"schedule_0"}]
"Value": Float,
# Either the Value or the StatisticValues field can be populated and not both.
"StatisticValues": {
"SampleCount": Float,
"Sum": Float,
"Minimum": Float,
"Maximum": Float
},
"Unit": "Count", # Optional
}
```