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

# 如何建置您自己的處理容器 (進階案例)
<a name="build-your-own-processing-container"></a>

您可以透過 Docker 映像提供具有自己的程式碼和相依性的 Amazon SageMaker Processing 來執行資料處理、功能工程和模型評估工作負載。以下提供如何建置您自有處理容器的相關資訊。

以下 Dockerfile 範例使用 Python 程式庫 scikit-learn 和 pandas 建置容器，供您作為處理任務執行。

```
FROM python:3.7-slim-buster

# Install scikit-learn and pandas
RUN pip3 install pandas==0.25.3 scikit-learn==0.21.3

# Add a Python script and configure Docker to run it
ADD processing_script.py /
ENTRYPOINT ["python3", "/processing_script.py"]
```

如需處理指令碼的範例，請參閱[開始使用 SageMaker Processing](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker_processing/basic_sagemaker_data_processing/basic_sagemaker_processing.ipynb)。

建置該 Docker 映像檔，將此推送到 Amazon Elastic Container Registry (Amazon ECR) 儲存庫，並確保您的 SageMaker AI IAM 角色可以從 Amazon ECR 提取映像。然後，您可以在 Amazon SageMaker Processing 上執行此映像。

# Amazon SageMaker Processing 如何執行您的處理容器映像
<a name="byoc-run-image"></a>

Amazon SageMaker Processing 會以類似下列命令的方式執行容器映像，其中 `AppSpecification.ImageUri` 是您在 `CreateProcessingJob` 操作中指定的 Amazon ECR 映像 URI。

```
docker run [AppSpecification.ImageUri]
```

這個命令會執行 Docker 映像中配置的 `ENTRYPOINT` 命令。

您也可以在 `CreateProcessingJob` 請求中使用 `AppSpecification.ContainerEntrypoint` 和 `AppSpecification.ContainerArgument` 參數，以覆寫映像中的進入點命令，或提供命令列引數給進入點命令。指定這些參數會設定 Amazon SageMaker Processing 為執行容器，類似於下列命令的執行方式。

```
 docker run --entry-point [AppSpecification.ContainerEntrypoint] [AppSpecification.ImageUri] [AppSpecification.ContainerArguments]
```

例如，如果您在 `CreateProcessingJob ` 請求中將 `ContainerEntrypoint` 指定為 `[python3, -v, /processing_script.py]`，並將 `ContainerArguments` 指定為 `[data-format, csv]`，Amazon SageMaker Processing 會使用以下命令執行您的容器。

```
 python3 -v /processing_script.py data-format csv 
```

 建置處理容器時，請注意下列細節：
+ Amazon SageMaker Processing 會根據命令執行的結束代碼，判斷任務完成或失敗。如果所有處理容器都成功結束且結束代碼為 0，表示處理任務完成，如果有任何容器結束時傳回非零結束代碼，表示處理任務失敗。
+  Amazon SageMaker Processing 可讓您覆寫處理容器的進入點，並設定命令列引數，就像使用 Docker API 時一樣。Docker 影像也可以使用 `ENTRYPOINT` 和 CMD 指令來設定進入點和命令列引數。`CreateProcessingJob` 的 `ContainerEntrypoint` 和 `ContainerArgument` 參數設定 Docker 映像的進入點和引數時，方式類似於 Docker 透過 Docker API 覆寫進入點和引數：
  + 如果 `ContainerEntrypoint` 和 `ContainerArguments` 都未提供，Processing 會使用預設的 `ENTRYPOINT` 或映像中的 CMD。
  + 如果提供 `ContainerEntrypoint`，但未提供 `ContainerArguments`，則 Processing 會執行具有指定入口點的映像，並忽略映像中的 `ENTRYPOINT` 和 CMD。
  + 如果提供 `ContainerArguments`，但未提供 `ContainerEntrypoint`，則 Processing 會以映像中的預設 `ENTRYPOINT` 搭配提供的參數來執行影像。
  + 如果同時提供 `ContainerEntrypoint` 和 `ContainerArguments`，Processing 則會以特定的進入點和引數執行映像，並忽略映像中的 `ENTRYPOINT` 和 CMD。
+ 在 Dockerfile 中，請使用 exec 形式的 `ENTRYPOINT` 指令 (`ENTRYPOINT` `["executable", "param1", "param2"])`，而不是 “shell” 形式 (`ENTRYPOINT`` command param1 param2`)。這可讓您的處理容器接收 `SIGINT` 和 `SIGKILL` 訊號，Processing 會根據這些訊號，使用 `StopProcessingJob` API 停止處理任務。
+ SageMaker AI 會保留 `/opt/ml` 與所有子目錄。在建置 Processing Docker 映像時，請不要將處理容器所需的任何資料放在這些目錄中。
+ 如果您打算使用 GPU 裝置，請確保您的容器與 nvidia-docker 相容。請只在容器中包含 CUDA 工具組。請勿將 NVIDIA 驅動程式與映像整合成套件。如需 nvidia-docker 的詳細資訊，請參閱 [NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker)。

# Amazon SageMaker Processing 如何為處理容器設定輸入和輸出
<a name="byoc-input-and-output"></a>

當您使用 `CreateProcessingJob` 操作建立處理任務時，您可以指定多個 `ProcessingInput` 和 `ProcessingOutput` 值。

您可以使用 `ProcessingInput` 參數指定 Amazon Simple Storage Service (Amazon S3) URI 來下載資料，以及處理容器中要下載資料的路徑。`ProcessingOutput` 參數會在處理容器中設定要從中上傳資料的路徑，以及要在 Amazon S3 中上傳資料的位置。對於 `ProcessingInput` 和 `ProcessingOutput`，Processing 容器中的路徑必須以 `/opt/ml/processing/ ` 開頭。

例如，您建立的處理任務可能使用一個 `ProcessingInput` 參數將資料從 `s3://your-data-bucket/path/to/input/csv/data` 下載到處理容器中的 `/opt/ml/processing/csv`，並使用 `ProcessingOutput` 參數將資料從 `/opt/ml/processing/processed_csv` 上傳到 `s3://your-data-bucket/path/to/output/csv/data`。您的處理任務將讀取輸入資料，並將輸出資料寫入 `/opt/ml/processing/processed_csv`。然後它將寫入此路徑的資料上傳到指定的 Amazon S3 輸出位置。

**重要**  
符號連結 (symlinks) 無法用來將輸出資料上傳到 Amazon S3。上傳輸出資料時不會遵循符號連結。

# Amazon SageMaker Processing 如何為處理容器提供日誌和指標
<a name="byoc-logs-and-metrics"></a>

當處理容器寫入 `stdout` 或 `stderr` 時，Amazon SageMaker Processing 會儲存每個處理容器的輸出，並將輸出放在 Amazon CloudWatch 日誌中。如需日誌記錄的相關資訊，請參閱[Amazon SageMaker AI 的 CloudWatch Logs](logging-cloudwatch.md)。

Amazon SageMaker Processing 也為執行處理容器的每個執行個體提供 CloudWatch 指標。如需指標的相關資訊，請參閱[Amazon CloudWatch 中的 Amazon SageMaker AI 指標](monitoring-cloudwatch.md)。

## Amazon SageMaker Processing 如何設定您的處理容器
<a name="byoc-config"></a>

Amazon SageMaker Processing 透過環境變數和容器中預先定義位置上的兩個 JSON 檔案 (`/opt/ml/config/processingjobconfig.json` 和 `/opt/ml/config/resourceconfig.json`)，提供組態資訊給您的處理容器。

當處理任務啟動時，它會使用您在 `CreateProcessingJob` 請求中使用 `Environment` 對應指定的環境變數。`/opt/ml/config/processingjobconfig.json` 檔案包含有關處理容器的主機名稱訊息，這也會在 `CreateProcessingJob` 請求中指定。

下列範例顯示 `/opt/ml/config/processingjobconfig.json` 檔案的格式。

```
{
    "ProcessingJobArn": "<processing_job_arn>",
    "ProcessingJobName": "<processing_job_name>",
    "AppSpecification": {
        "ImageUri": "<image_uri>",
        "ContainerEntrypoint": null,
        "ContainerArguments": null
    },
    "Environment": {
        "KEY": "VALUE"
    },
    "ProcessingInputs": [
        {
            "InputName": "input-1",
            "S3Input": {
                "LocalPath": "/opt/ml/processing/input/dataset",
                "S3Uri": "<s3_uri>",
                "S3DataDistributionType": "FullyReplicated",
                "S3DataType": "S3Prefix",
                "S3InputMode": "File",
                "S3CompressionType": "None",
                "S3DownloadMode": "StartOfJob"
            }
        }
    ],
    "ProcessingOutputConfig": {
        "Outputs": [
            {
                "OutputName": "output-1",
                "S3Output": {
                    "LocalPath": "/opt/ml/processing/output/dataset",
                    "S3Uri": "<s3_uri>",
                    "S3UploadMode": "EndOfJob"
                }
            }
        ],
        "KmsKeyId": null
    },
    "ProcessingResources": {
        "ClusterConfig": {
            "InstanceCount": 1,
            "InstanceType": "ml.m5.xlarge",
            "VolumeSizeInGB": 30,
            "VolumeKmsKeyId": null
        }
    },
    "RoleArn": "<IAM role>",
    "StoppingCondition": {
        "MaxRuntimeInSeconds": 86400
    }
}
```

`/opt/ml/config/resourceconfig.json` 檔案包含處理容器的主機名稱的相關資訊。建立或執行分散式處理程式碼時，請使用以下主機名稱。

```
{
  "current_host": "algo-1",
  "hosts": ["algo-1","algo-2","algo-3"]
}
```

請勿使用 `/etc/hostname` 或 `/etc/hosts` 包含的主機名稱相關資訊，因為可能不正確。

主機名稱資訊可能無法立即供處理容器使用。當叢集中的節點可供使用時，建議您在主機名稱解析作業中新增重試政策。

# 儲存並存取處理任務的中繼資料資訊
<a name="byoc-metadata"></a>

若要在結束處理容器後儲存中繼資料，容器可以將 UTF-8 編碼的文字寫入 `/opt/ml/output/message` 檔案。當處理任務進入任何終止狀態之後 (“`Completed`”、“`Stopped`” 或 “`Failed`”)，[https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeProcessingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeProcessingJob.html) 中的 “`ExitMessage`” 欄位包含此檔案的開頭 1 KB。透過對 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeProcessingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeProcessingJob.html) 呼叫存取檔案的初始部分，系統會透過 `ExitMessage` 參數傳回該部分。例如，對於失敗的處理任務，您可以使用此欄位來傳達處理容器失敗的原因。

**重要**  
不要將敏感資料寫入 `/opt/ml/output/message` 檔案。

如果此檔案中的資料不是 UTF-8 編碼，則任務會失敗並傳回 `ClientError`。如果多個容器結束時出現 `ExitMessage,`，則會串連每個處理容器的 `ExitMessage` 內容，然後截斷為 1 KB。

# 使用 SageMaker AI Python SDK 執行處理容器
<a name="byoc-run"></a>

您可以使用 SageMaker Python SDK，利用 `Processor` 類別執行您自己的處理影像。下列範例示範如何使用一個來自 Amazon Simple Storage Service (Amazon S3) 的輸入和一個放到 Amazon S3 的輸出，以執行您自己的處理容器。

```
from sagemaker.processing import Processor, ProcessingInput, ProcessingOutput

processor = Processor(image_uri='<your_ecr_image_uri>',
                     role=role,
                     instance_count=1,
                     instance_type="ml.m5.xlarge")

processor.run(inputs=[ProcessingInput(
                        source='<s3_uri or local path>',
                        destination='/opt/ml/processing/input_data')],
                    outputs=[ProcessingOutput(
                        source='/opt/ml/processing/processed_data',
                        destination='<s3_uri>')],
                    )
```

您可以將映像和想要執行的命令，以及您想要在該容器內執行的程式碼，提供給 `ScriptProcessor` (而不是將處理程式碼內建到處理映像中)。如需範例，請參閱[使用您自己的處理容器執行指令碼](processing-container-run-scripts.md)。

您也可以透過 `SKLearnProcessor`，使用 Amazon SageMaker Processing 提供的 scikit-learn 影像來執行 scikit-learn 指令碼。如需範例，請參閱[使用 scikit-learn 執行資料處理](use-scikit-learn-processing-container.md)。