本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# SageMaker AI Workflows
擴展機器學習 (ML) 操作時，您可以使用 Amazon SageMaker AI 全受管工作流程服務，為您的 ML 生命週期實作持續整合和部署 (CI/CD) 實務。使用 Pipeline SDK ，您可以選擇管道步驟並將其整合到一個統一的解決方案中，從資料準備到模型部署都能自動執行模型建置程序。對於 Kubernetes 型架構，您可以在您的 Kubernetes 叢集上安裝 SageMaker AI Operators，以使用 Kubernetes API 和命令列工具 (例如 `kubectl`) 原生建立 SageMaker AI 任務。使用 Kubeflow 管道的 SageMaker AI 元件，您可以從 Kubeflow 管道建立和監控原生 SageMaker AI 任務。來自 SageMaker AI 的工作參數、狀態和輸出都可以從 Kubeflow Pipelines UI 存取。最後，如果您想要排程批次任務，您可以使用 AWS Batch 任務佇列整合或 Jupyter 筆記本型工作流程服務，根據您定義的排程啟動獨立或定期執行。
總之，SageMaker AI 提供下列工作流程技術：
+ [管道](pipelines.md)：用於建置和管理機器學習 (ML) 管道的工具。
+ [Kubernetes 協調](kubernetes-workflows.md)：用於 Kubernetes 叢集的 SageMaker AI 自訂運算子，以及用於 Kubeflow Pipelines 的元件。
+ [SageMaker 筆記本工作](notebook-auto-run.md)：依需求或排定的 Jupyter 筆記本非互動式批次執行。
您也可以利用與 SageMaker AI 整合的其他服務來建立您的工作流程。選項包括下列服務：
+ [Airflow 工作流程](https://sagemaker.readthedocs.io/en/stable/workflows/airflow/index.html)：SageMaker API 可匯出用於建立和管理 Airflow 工作流程的組態。
+ [AWS Step Functions](https://sagemaker.readthedocs.io/en/stable/workflows/step_functions/index.html)：Python 中的多步驟 ML 工作流程，可協調 SageMaker AI 基礎設施，而不必單獨佈建您的資源。
+ [AWS Batch](https://docs.aws.amazon.com/batch/latest/userguide/getting-started-sagemaker.html)：將 SageMaker AI 訓練任務提交至 AWS Batch 任務佇列，您可以在其中排定任務在運算環境中執行的優先順序和排程任務。
有關管理 SageMaker 訓練和推理的詳細資訊，請參閱[Amazon SageMaker Python SDK 工作流程](https://sagemaker.readthedocs.io/en/stable/workflows/index.html)。
**Topics**
+ [管道](pipelines.md)
+ [Kubernetes 協調](kubernetes-workflows.md)
+ [SageMaker 筆記本工作](notebook-auto-run.md)
+ [排程您的 ML 工作流程](workflow-scheduling.md)
+ [AWS Batch 支援 SageMaker AI 訓練任務](training-job-queues.md)
# 管道
Amazon SageMaker Pipelines 是一種專門建置的工作流程協同運作服務，可自動化機器學習 (ML) 開發。
相較於其他 AWS 工作流程產品，管道提供下列優點：
**自動擴展無伺服器基礎設施** 您不需要管理基礎協同運作基礎設施來執行 Pipelines，這可讓您專注於核心 ML 任務。SageMaker AI 會自動根據您的 ML 工作負載需求佈建、擴展和關閉管道協同運作運算資源。
**直覺式使用者體驗** 您可以透過選擇的介面建立和管理管道：視覺化編輯器、SDK、API或 JSON。您可以在 Amazon SageMaker Studio 視覺化介面中拖放各種 ML 步驟來編寫管道。下列螢幕擷取畫面顯示適用於管道的 Studio 視覺化編輯器。
![\[Studio 中 Pipelines 視覺化拖放介面的螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipelines/pipelines-studio-overview.png)
如果您偏好以程式設計方式管理 ML 工作流程，SageMaker Python SDK 會提供進階協同運作特徵。如需詳細資訊，請參閱 SageMaker Python SDK 文件中的 [Amazon SageMaker Pipelines](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html)。
**AWS 整合**管道提供與所有 SageMaker AI 功能和其他 AWS 服務的無縫整合，以自動化資料處理、模型訓練、微調、評估、部署和監控任務。您可以將 SageMaker AI 特徵納入 Pipelines，並使用深層連結來大規模建立、監控和偵錯 ML 工作流程，以導覽這些特徵。
使用 Pipelines **降低成本**，您只需為 SageMaker Studio 環境和 Pipelines 協調的基礎任務 (例如 SageMaker Training、SageMaker Processing、SageMaker AI Inference 和 Amazon S3 資料儲存) 付費。
使用 Pipelines 的**可稽核性和歷程追蹤**，您可以使用內建版本控制來追蹤管道更新和執行的歷程記錄。Amazon SageMaker ML 歷程追蹤可協助您分析端對端 ML 開發生命週期中的資料來源和資料消費者。
**Topics**
+ [管道概觀](pipelines-overview.md)
+ [Pipelines 動作](pipelines-build.md)
# 管道概觀
Amazon SageMaker AI 管道是有向無環圖 (DAG) 中的一系列互連步驟，這些步驟是使用拖放 UI 或 [Pipelines SDK](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html) 所定義的。您也可以使用[管道定義 JSON 結構描述](https://aws-sagemaker-mlops.github.io/sagemaker-model-building-pipeline-definition-JSON-schema/)建置管道。此 DAG JSON 定義會提供管道每個步驟之間的要求和關係的相關資訊。管道的 DAG 結構由步驟之間的資料相依性決定。當一個步驟的輸出的内容作為輸入傳遞給另一個步驟時，就會建立這些資料相依性。下列影像是管道 DAG 範例：
![\[\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipeline-full.png)
**範例 DAG 包含下列步驟：**
1. `AbaloneProcess` ([處理](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-processing)步驟的執行個體) 會對用於訓練的資料執行預先處理指令碼。例如，指令碼可以填入缺失值、標準化數值資料，或將資料分割成訓練、驗證和測試資料集。
1. `AbaloneTrain` ([訓練](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-training)步驟的執行個體) 會設定超參數，並從預先處理的輸入資料訓練模型。
1. `AbaloneEval` ([處理](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-processing)步驟的另一個執行個體) 會評估模型的準確性。此步驟顯示資料相依性的範例 - 此步驟使用 `AbaloneProcess` 的測試資料集輸出。
1. `AbaloneMSECond` 是[條件](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-condition)步驟的實例，在此範例中，其會檢查以確保模型評估的均方誤差結果低於特定限制。如果模型不符合條件，管道執行會停止。
1. 管道執行會繼續進行下列步驟：
1. `AbaloneRegisterModel`，其中 SageMaker AI 會呼叫 [RegisterModel](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-register-model) 步驟，將模型當作版本控制模型套件群組註冊至 Amazon SageMaker 模型註冊表。
1. `AbaloneCreateModel`，其中 SageMaker AI 會呼叫 [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-create-model) 步驟來建立模型，以準備批次轉換。在 `AbaloneTransform` 中，SageMaker AI 會呼叫[轉換](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#step-type-transform)步驟，在您指定的資料集上產生模型預測。
下列主題描述 Pipelines 的基本概念。有關描述實現這些概念的教學課程，請參閱[Pipelines 動作](pipelines-build.md)。
**Topics**
+ [管道結構與執行](build-and-manage-pipeline.md)
+ [IAM 存取管理](build-and-manage-access.md)
+ [設定 Pipelines 的跨帳戶支援](build-and-manage-xaccount.md)
+ [管道參數](build-and-manage-parameters.md)
+ [Pipelines 步驟](build-and-manage-steps.md)
+ [使用 @step 裝飾項目直接移轉程式碼](pipelines-step-decorator.md)
+ [在步驟之間傳遞資料](build-and-manage-propertyfile.md)
+ [快取管道步驟](pipelines-caching.md)
+ [管道步驟的重試政策](pipelines-retry-policy.md)
+ [管道步驟的選取性執行](pipelines-selective-ex.md)
+ [Amazon SageMaker Pipelines 中具有 ClarifyCheck 和 QualityCheck 步驟的基準計算、漂移偵測和生命週期](pipelines-quality-clarify-baseline-lifecycle.md)
+ [排程管道執行](pipeline-eventbridge.md)
+ [Amazon SageMaker Experiments 整合](pipelines-experiments.md)
+ [使用本機模式執行管道](pipelines-local-mode.md)
+ [針對 Amazon SageMaker Pipelines 進行疑難排解](pipelines-troubleshooting.md)
# 管道結構與執行
**Topics**
+ [管道結構](#build-and-manage-pipeline-structure)
+ [使用平行組態執行管道](#build-and-manage-pipeline-execution)
## 管道結構
Amazon SageMaker Pipelines 執行個體由 `name`、`parameters` 和 `steps` 組成。`(account, region)` 對內的管道名稱必須是唯一的。步驟定義中使用的所有參數都必須在管道中定義。列出的管道步驟會透過彼此的資料相依性，自動判斷其執行順序。Pipelines 服務會解析資料相依性 DAG 中步驟之間的關係，以建立執行完成的一系列步驟。下圖是管道結構範例。
**警告**
透過視覺化編輯器或 SageMaker AI Python SDK 建置管道時，請勿在管道參數或任何步驟定義欄位 (例如環境變數) 中包含敏感資訊。未來在 `DescribePipeline` 請求中傳回這些欄位時，將可以看見它們。
```
from sagemaker.workflow.pipeline import Pipeline
pipeline_name = f"AbalonePipeline"
pipeline = Pipeline(
name=pipeline_name,
parameters=[
processing_instance_type,
processing_instance_count,
training_instance_type,
model_approval_status,
input_data,
batch_data,
],
steps=[step_process, step_train, step_eval, step_cond],
)
```
## 使用平行組態執行管道
依預設，管道會執行可平行執行的所有步驟。您可以在建立或更新管道時，以及啟動或重試管線執行時使用 `ParallelismConfiguration` 屬性，來控制此行為。
每次執行都會套用平行組態。例如，如果啟動兩個執行，則每個執行最多可以同時執行 50 個步驟，總共可以同時執行 100 個步驟。此外，在啟動、重試或更新執行時指定的 `ParallelismConfiguration` 優先於管道中定義的平行組態。
**Example 使用 `ParallelismConfiguration` 建立管道執行**
```
pipeline = Pipeline(
name="myPipeline",
steps=[step_process, step_train]
)
pipeline.create(role, parallelism_config={"MaxParallelExecutionSteps": 50})
```
# IAM 存取管理
下列各節說明 Amazon SageMaker 管道的 AWS Identity and Access Management (IAM) 要求。有關如何實現這些權限的範例，請參閱[先決條件](define-pipeline.md#define-pipeline-prereq)。
**Topics**
+ [管道角色許可](#build-and-manage-role-permissions)
+ [管道步驟許可](#build-and-manage-step-permissions)
+ [CORS 設定與 Amazon S3 儲存貯體](#build-and-manage-cors-s3)
+ [自訂 Pipelines 任務的存取管理](#build-and-manage-step-permissions-prefix)
+ [自訂管道版本的存取權](#build-and-manage-step-permissions-version)
+ [服務控制政策與 Pipelines](#build-and-manage-scp)
## 管道角色許可
您的管道需要 IAM 管道執行角色，該角色會在您建立管道時傳遞至管道。您用來建立管道的 SageMaker AI 執行個體角色必須具有指定管道執行角色之`iam:PassRole`許可的政策。這是因為執行個體需要許可，才能將您的管道執行角色傳遞至管道服務，以用於建立和執行管道。如需 IAM 角色的詳細資訊，請參閱 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
您的管道執行角色需要下列許可：
+ 您可以針對管道中的任何 SageMaker AI 任務步驟 （而不是預設使用的管道執行角色），使用唯一或自訂角色。請確定您的管道執行角色已新增具有指定這些角色之 `iam:PassRole`許可的政策。
+ 管道中每個任務類型 `Create` 和 `Describe` 許可。
+ 使用 `JsonGet` 函式的 Amazon S3 許可。您可以控制哪些使用者有權使用以資源為基礎的政策或以身分為基礎的政策來存取 Amazon S3 資源。資源型政策會套用至 Amazon S3 儲存貯體，並授予 Pipelines 存取儲存貯體的權限。以身分為基礎的政策可讓您的管道從您的帳戶發起 Amazon S3 呼叫。如需有關以資源為基礎的政策和以身分為基礎的政策的詳細資訊，請參閱[以身分為基礎的政策和以資源為基礎的政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html)。
```
{
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::/*",
"Effect": "Allow"
}
```
## 管道步驟許可
Pipelines 包括執行 SageMaker 任務的步驟。為了讓管道步驟執行這些任務，這些管道需要在您的帳戶中具有 IAM 角色，以提供所需資源的存取許可。此角色是由您的管道傳遞至 SageMaker AI 服務主體。如需 IAM 角色的詳細資訊，請參閱 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
依預設，每個步驟都具有管道執行角色。您可以選擇性地將不同的角色傳遞給管道中的任何步驟。這可確保每個步驟中的程式碼不會影響其他步驟中使用的資源，除非管道定義中指定的兩個步驟之間有直接關係。您可以在定義步驟的處理器或估算器時傳遞這些角色。如需如何在這些定義中包含這些角色的範例，請參閱 [SageMaker AI Python SDK 文件](https://sagemaker.readthedocs.io/en/stable/overview.html#using-estimators)。
## CORS 設定與 Amazon S3 儲存貯體
若要確保您的映像以可預測的方式從 Amazon S3 儲存貯體匯入至 Pipelines，必須將 CORS 組態新增至從中匯入映像的 Amazon S3 儲存貯體。本節提供如何將所需 CORS 組態設定為 Amazon S3 儲存貯體的指示。Pipelines 所需的 XML `CORSConfiguration` 與 [輸入影像資料的 CORS 要求](sms-cors-update.md) 中的不同，否則您可以使用其中的資訊，進一步了解 Amazon S3 儲存貯體的 CORS 需求。
針對託管您映像的 Amazon S3 儲存貯體使用以下 CORS 組態程式碼。如需設定 CORS 的指示，請參閱 Amazon Simple Storage Service 使用者指南中的[設定跨來源資源共用 (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-cors-configuration.html)。如果您使用 Amazon S3 主控台，將政策新增至您的儲存貯體，則必須使用 JSON 格式。
**JSON**
```
[
{
"AllowedHeaders": [
"*"
],
"AllowedMethods": [
"PUT"
],
"AllowedOrigins": [
"*"
],
"ExposeHeaders": [
"Access-Control-Allow-Origin"
]
}
]
```
**XML**
```
*
*
PUT
Access-Control-Allow-Origin
```
若要使用 Amazon S3 主控台新增 CORS 標題政策，下列 GIF 會示範在 Amazon S3 文件中找到的指示。
![\[有關如何使用 Amazon S3 主控台新增 CORS 標頭政策的 Gif。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/sms/gifs/cors-config.gif)
## 自訂 Pipelines 任務的存取管理
您可以進一步自訂 IAM 政策，以便您的組織中選定的成員可以執行任何或所有管道步驟。例如，您可以授予特定使用者建立訓練任務的許可，以及另一組使用者建立處理任務的許可，以及所有使用者執行剩餘步驟的許可。要使用此功能，您可以選擇一個自訂字串，其字首位您的任務名稱。您的管理員在允許的 ARN 前面加上字首，而您的資料科學家在管道執行個體中包含此字首。由於允許使用者的 IAM 政策包含具有指定字首的任務 ARN，因此管道步驟的後續任務要有必要的許可才能繼續。任務字首預設為關閉 – 您必須在 `Pipeline` 類別中開啟此選項才能使用它。
對於關閉字首的任務，任務名稱的格式如圖所示，並且是下表所述欄位的串連：
`pipelines----`
| 欄位 | 定義 |
| --- | --- |
| 管道 | 靜態字串始終在前面。此字串會將管道協同運作服務識別為任務的來源。 |
| executionId | 管道執行中執行個體的隨機緩衝區。 |
| stepNamePrefix | 使用者指定的步驟名稱 (在管道步驟的 `name` 引數中指定)，限制為前 20 個字元。 |
| entityToken | 一個隨機的權杖，用於確保步驟實體的等冪性。 |
| failureCount | 目前嘗試完成任務的重試次數。 |
在此情況下，任務名稱前面不會加上自訂字首，且對應的 IAM 政策必須與此字串相符。
對於開啟任務字首的使用者，基礎任務名稱會採用下列格式，並將自訂字首指定為 `MyBaseJobName`：
**-**-**-**
自訂字首會取代靜態 `pipelines` 字串，以協助您縮小可在管道中執行 SageMaker AI 任務之使用者的選取範圍。
**字首長度限制**
任務名稱具有特定於個別管道步驟的內部長度限制。此約束也會限制允許字首的長度。字首長度要求如下：
| 管道步驟 | 字首長度 |
| --- | --- |
| `[TrainingStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#trainingstep)`, `[ModelStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#step-collections)`, `[TransformStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#transformstep)`, `[ProcessingStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#processingstep)`, `[ClarifyCheckStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#clarifycheckstep)`, `[QualityCheckStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#qualitycheckstep)`, `[RegisterModelStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#step-collections)` | 38 |
| `[TuningStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#tuningstep)`, `[AutoML](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#automlstep)` | 6 |
### 將任務字首套用至 IAM 政策
您的管理員會建立 IAM 政策，允許特定字首的使用者建立任務。下列範例正策允許資料科學家在使用 `MyBaseJobName` 字首時建立訓練任務。
```
{
"Action": "sagemaker:CreateTrainingJob",
"Effect": "Allow",
"Resource": [
"arn:aws:sagemaker:region:account-id:*/MyBaseJobName-*"
]
}
```
### 將任務字首套用至管道建立
您可以使用任務執行個體類別的 `*base_job_name` 引數來指定字首。
**注意**
您可以在建立管道步驟之前，將任務字首和 `*base_job_name` 引數傳遞至人任務執行個體。此任務執行個體包含任務在管道中作為步驟執行的必要資訊。此引數會根據使用的任務執行個體而有所不同。下列清單顯示每個管道步驟類型要使用的引數：
對於 `[Estimator](https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html)` (`[TrainingStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#trainingstep)`)、`[Processor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html)` (`[ProcessingStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#processingstep)`) 和 `[AutoML](https://sagemaker.readthedocs.io/en/stable/api/training/automl.html)` (`[AutoMLStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#automlstep)`) 類別，引數為 `base_job_name`
對於 `[Tuner](https://sagemaker.readthedocs.io/en/stable/api/training/tuner.html)` (`[TuningStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#tuningstep)`) 類別，引數為 `tuning_base_job_name`
對於 `[Transformer](https://sagemaker.readthedocs.io/en/stable/api/inference/transformer.html)` (`[TransformStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#transformstep)`) 類別，引數為 `transform_base_job_name`
對於 `[QualityCheckStep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#qualitycheckstep)` (品質檢查) 和 `[ClarifyCheckstep](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#clarifycheckstep)` (澄清檢查) 類別，引數為 `[CheckJobConfig](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#checkjobconfig)` 中的 `base_job_name`
對於 `[Model](https://sagemaker.readthedocs.io/en/stable/api/inference/model.html)` 類別，使用的引數取決於將結果傳遞給 `[ModelStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#step-collections)` 之前在模型上執行的是 `create` 還是 `register`
如果您呼叫 `create`，則自訂字首來自構造模型時的 `name` 引數 (即 `Model(name=)`)
如果您呼叫 `register`，則自訂字首來自您呼叫 `register` 的 `model_package_name` 引數 (即 `my_model.register(model_package_name=)`)
以下範例顯示如何指定新訓練任務執行個體的字首。
```
# Create a job instance
xgb_train = Estimator(
image_uri=image_uri,
instance_type="ml.m5.xlarge",
instance_count=1,
output_path=model_path,
role=role,
subnets=["subnet-0ab12c34567de89f0"],
base_job_name="MyBaseJobName"
security_group_ids=["sg-1a2bbcc3bd4444e55"],
tags = [ ... ]
encrypt_inter_container_traffic=True,
)
# Attach your job instance to a pipeline step
step_train = TrainingStep(
name="TestTrainingJob",
estimator=xgb_train,
inputs={
"train": TrainingInput(...),
"validation": TrainingInput(...)
}
)
```
任務字首依預設處於關閉狀態。若要選擇使用此功能，請使用 `PipelineDefinitionConfig` 的 `use_custom_job_prefix` 選項，如下列程式碼片段所示：
```
from sagemaker.workflow.pipeline_definition_config import PipelineDefinitionConfig
# Create a definition configuration and toggle on custom prefixing
definition_config = PipelineDefinitionConfig(use_custom_job_prefix=True);
# Create a pipeline with a custom prefix
pipeline = Pipeline(
name="MyJobPrefixedPipeline",
parameters=[...]
steps=[...]
pipeline_definition_config=definition_config
)
```
建立並執行管道。下列範例會建立並執行管道，並示範如何關閉任務字首並重新執行管道。
```
pipeline.create(role_arn=sagemaker.get_execution_role())
# Optionally, call definition() to confirm your prefixed job names are in the built JSON
pipeline.definition()
pipeline.start()
# To run a pipeline without custom-prefixes, toggle off use_custom_job_prefix, update the pipeline
# via upsert() or update(), and start a new run
definition_config = PipelineDefinitionConfig(use_custom_job_prefix=False)
pipeline.pipeline_definition_config = definition_config
pipeline.update()
execution = pipeline.start()
```
同樣，您可以開啟現有管道的功能，並啟動使用任務字首的新執行。
```
definition_config = PipelineDefinitionConfig(use_custom_job_prefix=True)
pipeline.pipeline_definition_config = definition_config
pipeline.update()
execution = pipeline.start()
```
最後，您可以透過呼叫管道執行 `list_steps` 來查看自訂字首的任務。
```
steps = execution.list_steps()
prefixed_training_job_name = steps['PipelineExecutionSteps'][0]['Metadata']['TrainingJob']['Arn']
```
## 自訂管道版本的存取權
您可以使用 `sagemaker:PipelineVersionId` 條件金鑰，授予特定版本 Amazon SageMaker Pipelines 的自訂存取權。例如，以下政策僅授予版本 ID 6 及更新版本啟動執行或更新管道版本的存取權。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Sid": "AllowStartPipelineExecution",
"Effect": "Allow",
"Action": [
"sagemaker:StartPipelineExecution",
"sagemaker:UpdatePipelineVersion"
],
"Resource": "*",
"Condition": {
"NumericGreaterThanEquals": {
"sagemaker:PipelineVersionId": 6
}
}
}
}
```
------
如需支援的條件金鑰的詳細資訊，請參閱 [Amazon SageMaker AI 的條件金鑰](https://docs.aws.amazon.com//service-authorization/latest/reference/list_amazonsagemaker.html#amazonsagemaker-policy-keys)。
## 服務控制政策與 Pipelines
服務控制政策 (SCP) 是一種組織政策類型，可用來管理您的組織中的許可。SCP 可集中控制組織中所有帳戶可用的許可上限。透過在組織內使用管道，您可以確保資料科學家管理您的管道執行，而不必與 AWS 主控台互動。
如果您將 VPC 與 SCP 搭配使用來限制對 Amazon S3 的存取，則需要採取措施來允許管道存取其他 Amazon S3 資源。
若要允許 Pipelines 使用 `JsonGet` 函式在 VPC 之外存取 Amazon S3，請更新組織的 SCP，以確保使用 Pipelines 的角色可以存取 Amazon S3。若要這樣做，請使用主體標籤和條件索引鍵，透過管道執行角色為 Pipelines 執行器使用的角色建立例外狀況。
**允許 Pipelines 在 VPC 以外存取 Amazon S3**
1. 按照[標記 IAM 使用者和角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)中的步驟，為您的管道執行角色建立唯一標籤。
1. 使用您建立之標籤的 `Aws:PrincipalTag IAM` 條件索引鍵，在 SCP 中授予例外狀況。有關詳細資訊，請參閱[建立、更新和刪除服務控制策略](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps_create.html)。
# 設定 Pipelines 的跨帳戶支援
Amazon SageMaker Pipelines 的跨帳戶支援可讓您與在不同 AWS 帳戶中運作的其他團隊或組織協作機器學習管道。透過設定跨帳戶管道共用，您可以授予管道的受控存取權、允許其他帳戶檢視管道詳細資訊、觸發執行，以及監控執行。下列主題涵蓋如何設定跨帳戶管道共用、共用資源可用的不同許可政策，以及如何透過對 SageMaker AI 的直接 API 呼叫來存取共用管道實體並與之互動。
## 設定跨帳戶管道共用
SageMaker AI 使用 [AWS Resource Access Manager](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html) (AWS RAM) 協助您跨帳戶安全地共用管道實體。
### 建立資源共用
1. 透過 [AWS RAM](https://console.aws.amazon.com/ram/home) 主控台選取**建立資源共用**。
1. 指定資源共用詳細資訊時，請選擇 Pipelines 資源類型，然後選取一或多個您要共用的管道。當您與其他帳戶共用管道時，也會隱含共用其所有執行。
1. 將許可與資源共用建立關聯。選擇預設唯讀許可政策或擴充管道執行許可政策。如需詳細資訊，請參閱[Pipelines 資源的許可政策](#build-and-manage-xaccount-permissions)。
**注意**
如果您選取延伸管道執行政策，請注意，共用帳戶呼叫的任何啟動、停止和重試命令都會使用 AWS 共用管道帳戶中的資源。
1. 使用 AWS 帳戶 IDs 指定您要授予共用資源存取權的帳戶。
1. 檢閱您的資源共用組態，然後選取**建立資源共用**。資源共用和主體關聯可能需要幾分鐘的時間才能完成。
如需詳細資訊，請參閱 *AWS Resource Access Manager 使用者指南*中的[共用您的 AWS 資源](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html)。
### 取得資源共用邀請的回應
設定資源共用和主體關聯後，指定的 AWS 帳戶會收到加入該資源共用的邀請。 AWS 帳戶必須接受邀請，才能存取任何共用資源。
如需透過 接受資源共用邀請的詳細資訊 AWS RAM，請參閱*AWS 《Resource Access Manager 使用者指南*》中的[使用共用 AWS 資源](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-shared.html)。
## Pipelines 資源的許可政策
建立資源共用時，請選擇兩個支援的許可政策之一，以與 SageMaker AI 管道資源類型建立關聯。這兩項政策都會授予任何選取管道及其所有執行的存取權。
### 預設唯讀許可
`AWSRAMDefaultPermissionSageMakerPipeline` 政策允許下列唯讀動作：
```
"sagemaker:DescribePipeline"
"sagemaker:DescribePipelineDefinitionForExecution"
"sagemaker:DescribePipelineExecution"
"sagemaker:ListPipelineExecutions"
"sagemaker:ListPipelineExecutionSteps"
"sagemaker:ListPipelineParametersForExecution"
"sagemaker:Search"
```
### 擴充管道執行許可
`AWSRAMPermissionSageMakerPipelineAllowExecution` 政策包括預設政策中的所有唯讀許可，並允許共用帳戶啟動、停止和重試管道執行。
**注意**
使用延伸管道執行許可政策時，請注意 AWS 資源使用情況。透過此政策，共用帳戶可以啟動、停止和重試管道執行。擁有者帳戶會使用用於共用管道執行的所有資源。
擴充管道執行許可政策允許下列動作：
```
"sagemaker:DescribePipeline"
"sagemaker:DescribePipelineDefinitionForExecution"
"sagemaker:DescribePipelineExecution"
"sagemaker:ListPipelineExecutions"
"sagemaker:ListPipelineExecutionSteps"
"sagemaker:ListPipelineParametersForExecution"
"sagemaker:StartPipelineExecution"
"sagemaker:StopPipelineExecution"
"sagemaker:RetryPipelineExecution"
"sagemaker:Search"
```
## 透過直接 API 呼叫存取共用管道實體
設定跨帳戶管道共用之後，您可以使用管道 ARN 呼叫下列 SageMaker API 動作：
**注意**
僅在 API 命令包含在與資源共用關聯的許可中時，您才能呼叫這些命令。如果您選取`AWSRAMPermissionSageMakerPipelineAllowExecution`政策，則開始、停止和重試命令會使用共用管道 AWS 之帳戶中的資源。
+ [DescribePipeline](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribePipeline.html)
+ [DescribePipelineDefinitionForExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribePipelineDefinitionForExecution.html)
+ [DescribePipelineExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribePipelineExecution.html)
+ [ListPipelineExecutions](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListPipelineExecutions.html)
+ [ListPipelineExecutionSteps](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListPipelineExecutionSteps.html)
+ [ListPipelineParametersForExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListPipelineParametersForExecution.html)
+ [StartPipelineExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StartPipelineExecution.html)
+ [StopPipelineExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StopPipelineExecution.html)
+ [RetryPipelineExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RetryPipelineExecution.html)
# 管道參數
您可以使用參數將變數引入管道定義。您可以參考您在整個管道定義中定義的參數。參數具有預設值，您可以透過在啟動管道執行時指定參數值來覆寫預設值。預設值必須是與參數類型相符的執行個體。步驟定義中使用的所有參數都必須在管道定義中定義。本主題描述您可以定義的參數，以及如何實作這些參數。
Amazon SageMaker Pipelines 支援下列參數類型：
+ `ParameterString` – 表示字串參數。
+ `ParameterInteger` – 表示整數參數。
+ `ParameterFloat` – 表示浮點數參數。
+ `ParameterBoolean` – 表示布林值 Python 類型。
參數的格式如下：
```
= (
name="",
default_value=
)
```
以下範例顯示範例參數實作。
```
from sagemaker.workflow.parameters import (
ParameterInteger,
ParameterString,
ParameterFloat,
ParameterBoolean
)
processing_instance_count = ParameterInteger(
name="ProcessingInstanceCount",
default_value=1
)
```
您可以在建立管道時傳遞參數，如下列範例所示。
```
pipeline = Pipeline(
name=pipeline_name,
parameters=[
processing_instance_count
],
steps=[step_process]
)
```
您也可以將不同於預設值的參數值傳遞給管道執行，如下列範例所示。
```
execution = pipeline.start(
parameters=dict(
ProcessingInstanceCount="2",
ModelApprovalStatus="Approved"
)
)
```
您可以使用類似 `[ sagemaker.workflow.functions.Join](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.functions.Join)` 的 SageMaker Python SDK 函式來操作參數。如需有關參數的詳細資訊，請參閱 [SageMaker Pipelines 參數](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#parameters)。
如需 Pipelines 參數的已知限制，請參閱 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 中的*[限制 - 參數化](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#parameterization)*。
# Pipelines 步驟
Pipelines 由步驟組成。這些步驟使用屬性定義管道採取的動作以及步驟之間的關係。下頁描述步驟的類型、其屬性，以及它們之間的關係。
**Topics**
+ [新增步驟](build-and-manage-steps-types.md)
+ [新增整合](build-and-manage-steps-integration.md)
+ [步驟屬性](#build-and-manage-properties)
+ [步驟平行處理](#build-and-manage-parallelism)
+ [步驟之間的資料相依性](#build-and-manage-data-dependency)
+ [步驟之間的自訂相依性](#build-and-manage-custom-dependency)
+ [步驟中的自訂映像](#build-and-manage-images)
# 新增步驟
下文描述每個步驟類型的要求，並提供步驟的範例實作，以及如何將步驟新增至 Pipelines。這些不是有效的實作，因為它們不提供所需的資源和輸入。有關實現這些步驟的教學課程，請參閱[Pipelines 動作](pipelines-build.md)。
**注意**
您也可以從本機機器學習程式碼建立步驟，方法是使用 `@step` 裝飾項目將其轉換為 Pipelines 步驟。如需詳細資訊，請參閱[@step 裝飾項目](#step-type-custom)。
Amazon SageMaker Pipelines 支援下列步驟類型：
+ [執行程式碼](#step-type-executecode)
[處理](#step-type-processing)
+ [培訓](#step-type-training)
+ [調校](#step-type-tuning)
+ [AutoML](#step-type-automl)
+ [`Model`](#step-type-model)
+ [`Create model`](#step-type-create-model)
+ [`Register model`](#step-type-register-model)
+ [`Deploy model (endpoint)`](#step-type-deploy-model-endpoint)
+ [轉換](#step-type-transform)
+ [條件](#step-type-condition)
+ [`Callback`](#step-type-callback)
+ [Lambda](#step-type-lambda)
+ [`ClarifyCheck`](#step-type-clarify-check)
+ [`QualityCheck`](#step-type-quality-check)
+ [EMR](#step-type-emr)
+ [筆記本任務](#step-type-notebook-job)
+ [失敗](#step-type-fail)
## @step 裝飾項目
如果您想要在drag-and-drop管道 UI 中協調利用進階 SageMaker AI 功能或其他 AWS 服務的自訂 ML 任務，請使用 [執行程式碼步驟](#step-type-executecode)。
您可以使用 `@step` 裝飾項目從本機機器學習程式碼建立步驟。測試您的程式碼後，您可以透過使用 `@step` 裝飾項目註釋函數，將該函數轉換為 SageMaker AI 管道步驟。當您將 `@step` 裝飾函數的輸出作為步驟傳遞至管道時，Pipelines 會建立並執行管道。您也可以建立多步驟 DAG 管道，其中包含一或多個 `@step` 裝飾函數，以及傳統 SageMaker AI 管道步驟。如需如何使用 `@step` 裝飾項目建立步驟的詳細資訊，請參閱[使用 @step 裝飾項目直接移轉程式碼](pipelines-step-decorator.md)。
## 執行程式碼步驟
在 Pipelines 拖放 UI 中，您可以使用**執行程式碼**步驟，將您自己的程式碼作為管道步驟執行。您可以上傳 Python 函數、指令碼或筆記本，作為管道的一部分執行。如果您想要協調利用進階 SageMaker AI 功能或其他 AWS 服務的自訂 ML 任務，您應該使用此步驟。
**執行程式碼**步驟會將檔案上傳至 Amazon SageMaker AI 的預設 Amazon S3 儲存貯體。此儲存貯體可能未設定必要的跨來源資源共用 (CORS) 許可。若要進一步了解如何設定 CORS 許可，請參閱[輸入影像資料的 CORS 要求](sms-cors-update.md)。
**執行程式碼**步驟會使用 Amazon SageMaker 訓練任務來執行您的程式碼。確保您的 IAM 角色具有 `sagemaker:DescribeTrainingJob` 和 `sagemaker:CreateTrainingJob` API 許可。若要進一步了解 Amazon SageMaker AI 的所有必要許可，以及如何設定這些許可，請參閱 [Amazon SageMaker AI API 許可：動作、許可與資源參考](api-permissions-reference.md)。
若要使用管道設計工具將執行程式碼步驟新增至管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Amazon SageMaker Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**執行程式碼**並將其拖曳至畫布。
1. 在畫布中，選擇您已新增的**執行程式碼**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。
1. 您可以上傳單一檔案，以執行或上傳包含多個成品的壓縮資料夾。
1. 對於單一檔案上傳，您可以為筆記本、python 函數或指令碼提供選用參數。
1. 提供 Python 函數時，必須以格式 `file.py:` 提供處理常式
1. 對於壓縮資料夾上傳，必須提供程式碼的相對路徑，而且您可以選擇性地在壓縮資料夾內提供 `requirements.txt` 檔案或初始化指令碼的路徑。
1. 如果畫布包含緊接在您已新增之**執行程式碼**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**執行程式碼**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**執行程式碼**步驟之後的任何步驟，請按一下游標，然後將其從**執行程式碼**步驟拖曳到該步驟以建立邊緣。Python 函數可以參考**執行程式碼**步驟的輸出。
## 處理步驟
使用處理步驟建立用於資料處理的處理任務。如需有關處理工作的詳細資訊，請參閱[處理資料和評估模型](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html)。
------
#### [ Pipeline Designer ]
若要使用管道設計工具將處理步驟新增至管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Amazon SageMaker Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 在左側邊欄中，選擇**處理資料**並將其拖曳至畫布。
1. 在畫布中，選擇您新增的**處理資料**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.steps.ProcessingStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.ProcessingStep)。
1. 如果畫布包含緊接在您已新增之**處理資料**步驟之前的任何步驟，請按一下游標，然後將其從步驟拖曳到**處理資料**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**處理資料**步驟之後的任何步驟，請按一下游標，然後將其從**處理資料**步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
處理步驟需要處理器、定義處理程式碼的 Python 指令碼、處理輸出以及任務引數。下列範例示範如何建立 `ProcessingStep` 定義。
```
from sagemaker.sklearn.processing import SKLearnProcessor
sklearn_processor = SKLearnProcessor(framework_version='1.0-1',
role=,
instance_type='ml.m5.xlarge',
instance_count=1)
```
```
from sagemaker.processing import ProcessingInput, ProcessingOutput
from sagemaker.workflow.steps import ProcessingStep
inputs = [
ProcessingInput(source=, destination="/opt/ml/processing/input"),
]
outputs = [
ProcessingOutput(output_name="train", source="/opt/ml/processing/train"),
ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"),
ProcessingOutput(output_name="test", source="/opt/ml/processing/test")
]
step_process = ProcessingStep(
name="AbaloneProcess",
step_args = sklearn_processor.run(inputs=inputs, outputs=outputs,
code="abalone/preprocessing.py")
)
```
**傳遞執行期參數**
下列範例示範如何將執行期參數從 PySpark 處理器傳遞給 `ProcessingStep`。
```
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.spark.processing import PySparkProcessor
from sagemaker.processing import ProcessingInput, ProcessingOutput
from sagemaker.workflow.steps import ProcessingStep
pipeline_session = PipelineSession()
pyspark_processor = PySparkProcessor(
framework_version='2.4',
role=,
instance_type='ml.m5.xlarge',
instance_count=1,
sagemaker_session=pipeline_session,
)
step_args = pyspark_processor.run(
inputs=[ProcessingInput(source=, destination="/opt/ml/processing/input"),],
outputs=[
ProcessingOutput(output_name="train", source="/opt/ml/processing/train"),
ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"),
ProcessingOutput(output_name="test", source="/opt/ml/processing/test")
],
code="preprocess.py",
arguments=None,
)
step_process = ProcessingStep(
name="AbaloneProcess",
step_args=step_args,
)
```
如需有關處理步驟要求的詳細資訊，請參閱 [sagemaker.workflow.steps.ProcessingStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.ProcessingStep) 文件。如需深入範例，請參閱[協調任務以使用 Amazon SageMaker Pipelines 訓練和評估模型](https://github.com/aws/amazon-sagemaker-examples/blob/62de6a1fca74c7e70089d77e36f1356033adbe5f/sagemaker-pipelines/tabular/abalone_build_train_deploy/sagemaker-pipelines-preprocess-train-evaluate-batch-transform.ipynb)範例筆記本。*定義特徵工程的處理步驟*一節包含詳細資訊。
------
## 訓練步驟
您使用訓練步驟建立訓練任務來訓練模型。如需訓練任務的詳細資訊，請參閱[使用 Amazon SageMaker AI 訓練模型](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html)。
訓練步驟需要估算器以及訓練和驗證資料輸入。
------
#### [ Pipeline Designer ]
若要使用管道設計工具將訓練步驟新增至管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Amazon SageMaker Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**訓練模型**並將其拖曳至畫布。
1. 在畫布中，選擇您新增的**訓練模型**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.steps.TrainingStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TrainingStep)。
1. 如果畫布包含緊接在您已新增之**訓練模型**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**訓練模型**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**訓練模型**步驟之後的任何步驟，請按一下游標，然後將其從**訓練模型**步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
下列範例示範如何建立 `TrainingStep` 定義。如需訓練步驟要求的詳細資訊，請參閱 [sagemaker.workflow.steps.TrainingStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TrainingStep) 文件。
```
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.inputs import TrainingInput
from sagemaker.workflow.steps import TrainingStep
from sagemaker.xgboost.estimator import XGBoost
pipeline_session = PipelineSession()
xgb_estimator = XGBoost(..., sagemaker_session=pipeline_session)
step_args = xgb_estimator.fit(
inputs={
"train": TrainingInput(
s3_data=step_process.properties.ProcessingOutputConfig.Outputs[
"train"
].S3Output.S3Uri,
content_type="text/csv"
),
"validation": TrainingInput(
s3_data=step_process.properties.ProcessingOutputConfig.Outputs[
"validation"
].S3Output.S3Uri,
content_type="text/csv"
)
}
)
step_train = TrainingStep(
name="TrainAbaloneModel",
step_args=step_args,
)
```
------
## 調校步驟
您可以使用調校步驟來建立超參數調校任務，也稱為超參數最佳化 (HPO)。超參數調校任務會執行多個訓練任務，每個任務都會產生一個模型版本。如需有關超參數調校的詳細資訊，請參閱[使用 SageMaker AI 執行自動模型調校](automatic-model-tuning.md)。
調校任務與管道的 SageMaker AI 實驗相關聯，並以試驗的形式建立訓練任務。如需詳細資訊，請參閱[Experiments 整合](pipelines-experiments.md)。
調校步驟需要 [HyperparameterTuner](https://sagemaker.readthedocs.io/en/stable/api/training/tuner.html) 和訓練輸入。您可以指定 `HyperparameterTuner` 之 `warm_start_config` 參數來重新訓練先前的調校任務。如需有關超參數調整和熱啟動的詳細資訊，請參閱[執行超參數調校任務的暖啟動](automatic-model-tuning-warm-start.md)。
您使用 [sagemaker.workflow.steps.TuningStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TuningStep) 類別的 [get\$1top\$1model\$1s3\$1uri](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TuningStep.get_top_model_s3_uri) 方法，從效能最佳的模型版本之一取得模型成品。如需顯示如何在 SageMaker AI 管道中使用調校步驟的筆記本，請參閱 [sagemaker-pipelines-tuning-step.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/tuning-step/sagemaker-pipelines-tuning-step.ipynb)。
**重要**
Amazon SageMaker Python SDK v2.48.0 和 Amazon SageMaker Studio Classic v3.8.0 中引入了調校步驟。您必須先更新 Studio Classic，才能使用調校步驟，否則管道 DAG 不會顯示。若要更新 Studio Classic，請參閱[關閉並更新 Amazon SageMaker Studio Classic](studio-tasks-update-studio.md)。
下列範例示範如何建立 `TuningStep` 定義。
```
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.tuner import HyperparameterTuner
from sagemaker.inputs import TrainingInput
from sagemaker.workflow.steps import TuningStep
tuner = HyperparameterTuner(..., sagemaker_session=PipelineSession())
step_tuning = TuningStep(
name = "HPTuning",
step_args = tuner.fit(inputs=TrainingInput(s3_data="s3://amzn-s3-demo-bucket/my-data"))
)
```
**取得最佳模型版本**
下列範例示範如何使用 `get_top_model_s3_uri` 方法從調校任務取得最佳模型版本。根據 [HyperParameterTuningJobObjective](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_HyperParameterTuningJobObjective.html)，最多提供效能排名前 50 的版本。`top_k` 引數是版本的索引，其中 `top_k=0` 是效能最佳的版本，而 `top_k=49` 是效能最差的版本。
```
best_model = Model(
image_uri=image_uri,
model_data=step_tuning.get_top_model_s3_uri(
top_k=0,
s3_bucket=sagemaker_session.default_bucket()
),
...
)
```
如需有關調整步驟要求的詳細資訊，請參閱 [sagemaker.workflow.steps.TuningStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TuningStep) 文件。
## 微調步驟
微調會在新資料集上，從 Amazon SageMaker JumpStart 訓練預先訓練的基礎模型。這個程序也稱為移轉學習，可以利用較小的資料集和較短的訓練時間來產生精確的模型。微調模型時，您可以使用預設資料集或選擇自己的資料。若要進一步了解如何從 JumpStart 微調基礎模型，請參閱[微調模型](jumpstart-fine-tune.md)。
微調步驟使用 Amazon SageMaker 訓練任務來自訂您的模型。確保您的 IAM 角色具有在您管道中執行微調任務的 `sagemaker:DescribeTrainingJob` 和 `sagemaker:CreateTrainingJob` API 許可。若要進一步了解 Amazon SageMaker AI 的必要許可，以及如何設定這些許可，請參閱 [Amazon SageMaker AI API 許可：動作、許可與資源參考](api-permissions-reference.md)。
若要使用拖放編輯器將**微調模型**步驟新增至您的管道，請遵循下列步驟：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**微調模型**並將其拖曳至畫布。
1. 在畫布中，選擇您已新增的**微調模型**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。
1. 如果畫布包含緊接在您已新增之**微調模型**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**微調模型**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**微調模型**步驟之後的任何步驟，請按一下游標，然後將其從**微調模型**步驟拖曳到該步驟以建立邊緣。
## AutoML 步驟
使用 [AutoML](https://sagemaker.readthedocs.io/en/stable/api/training/automl.html) API 建立 AutoML 任務以自動訓練模型。如需有關 AutoML 任務的詳細資訊，請參閱[使用 Amazon SageMaker Autopilot 將模型開發自動化](https://docs.aws.amazon.com/sagemaker/latest/dg/autopilot-automate-model-development.html)。
**注意**
目前，AutoML 步驟僅支援[集成訓練模式](https://docs.aws.amazon.com/sagemaker/latest/dg/autopilot-model-support-validation.html)。
下列範例示範如何使用 `AutoMLStep` 建立定義。
```
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.workflow.automl_step import AutoMLStep
pipeline_session = PipelineSession()
auto_ml = AutoML(...,
role="",
target_attribute_name="my_target_attribute_name",
mode="ENSEMBLING",
sagemaker_session=pipeline_session)
input_training = AutoMLInput(
inputs="s3://amzn-s3-demo-bucket/my-training-data",
target_attribute_name="my_target_attribute_name",
channel_type="training",
)
input_validation = AutoMLInput(
inputs="s3://amzn-s3-demo-bucket/my-validation-data",
target_attribute_name="my_target_attribute_name",
channel_type="validation",
)
step_args = auto_ml.fit(
inputs=[input_training, input_validation]
)
step_automl = AutoMLStep(
name="AutoMLStep",
step_args=step_args,
)
```
**取得最佳模型版本**
AutoML 步驟會自動訓練多個候選模型。使用 `get_best_auto_ml_model` 方法從 AutoML 任務取得具有最佳目標指標的模型，如下所示。您亦須使用 IAM `role` 來存取模型成品。
```
best_model = step_automl.get_best_auto_ml_model(role=)
```
如需詳細資訊，請參閱 SageMaker Python SDK 中的 [AutoML](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.automl_step.AutoMLStep) 步驟。
## 模型步驟
使用 `ModelStep` 建立或註冊 SageMaker AI 模型。如需有關 `ModelStep` 要求的更多資訊，請參閱 [sagemaker.workflow.model\$1step.ModelStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.model_step.ModelStep) 文件。
### 建立模型
您可以使用 `ModelStep` 建立 SageMaker AI 模型。`ModelStep` 需要模型成品以及您用來建立模型所需之 SageMaker AI 執行個體的相關資訊。如需 SageMaker AI 模型的詳細資訊，請參閱[使用 Amazon SageMaker AI 訓練模型](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html)。
下列範例示範如何建立 `ModelStep` 定義。
```
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.model import Model
from sagemaker.workflow.model_step import ModelStep
step_train = TrainingStep(...)
model = Model(
image_uri=pytorch_estimator.training_image_uri(),
model_data=step_train.properties.ModelArtifacts.S3ModelArtifacts,
sagemaker_session=PipelineSession(),
role=role,
)
step_model_create = ModelStep(
name="MyModelCreationStep",
step_args=model.create(instance_type="ml.m5.xlarge"),
)
```
### 註冊模型
您可以使用 `ModelStep` 搭配 Amazon SageMaker 模型註冊表註冊 `sagemaker.model.Model` 或 `sagemaker.pipeline.PipelineModel`。`PipelineModel` 表示推論管道，是一種由直線順序容器構成的模型，可處理推論請求。如需有關如何註冊模型的詳細資訊，請參閱[使用模型註冊庫進行模型註冊部署](model-registry.md)。
下列範例示範如何建立註冊 `PipelineModel` 所需的 `ModelStep`。
```
import time
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.sklearn import SKLearnModel
from sagemaker.xgboost import XGBoostModel
pipeline_session = PipelineSession()
code_location = 's3://{0}/{1}/code'.format(bucket_name, prefix)
sklearn_model = SKLearnModel(
model_data=processing_step.properties.ProcessingOutputConfig.Outputs['model'].S3Output.S3Uri,
entry_point='inference.py',
source_dir='sklearn_source_dir/',
code_location=code_location,
framework_version='1.0-1',
role=role,
sagemaker_session=pipeline_session,
py_version='py3'
)
xgboost_model = XGBoostModel(
model_data=training_step.properties.ModelArtifacts.S3ModelArtifacts,
entry_point='inference.py',
source_dir='xgboost_source_dir/',
code_location=code_location,
framework_version='0.90-2',
py_version='py3',
sagemaker_session=pipeline_session,
role=role
)
from sagemaker.workflow.model_step import ModelStep
from sagemaker import PipelineModel
pipeline_model = PipelineModel(
models=[sklearn_model, xgboost_model],
role=role,sagemaker_session=pipeline_session,
)
register_model_step_args = pipeline_model.register(
content_types=["application/json"],
response_types=["application/json"],
inference_instances=["ml.t2.medium", "ml.m5.xlarge"],
transform_instances=["ml.m5.xlarge"],
model_package_group_name='sipgroup',
)
step_model_registration = ModelStep(
name="AbaloneRegisterModel",
step_args=register_model_step_args,
)
```
## 建立模型步驟
您可以使用建立模型步驟建立 SageMaker AI 模型。如需 SageMaker AI 模型的詳細資訊，請參閱[使用 Amazon SageMaker 訓練模型](how-it-works-training.md)。
建立模型步驟需要模型成品以及您用來建立模型所需之 SageMaker AI 執行個體的相關資訊。下列範例展示如何建立一個建立模型步驟定義。如需建立模型步驟要求的詳細資訊，請參閱 [sagemaker.workflow.steps.CreateModelStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.CreateModelStep) 文件。
------
#### [ Pipeline Designer ]
若要將建立模型步驟新增至您的管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**建立模型**並將其拖曳至畫布。
1. 在畫布中，選擇您已新增的**建立模型**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些索引標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.steps.CreateModelStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.CreateModelStep)。
1. 如果畫布包含緊接在您已新增之**建立模型**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**建立模型**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**建立模型**步驟之後的任何步驟，請按一下游標，然後將其從**建立模型**步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
**重要**
我們建議從 SageMaker AI Python SDK v2.90.0 起使用 [模型步驟](#step-type-model) 建立模型。`CreateModelStep` 將會繼續在 SageMaker Python SDK 的先前版本中運作，但不再受到主動支援。
```
from sagemaker.workflow.steps import CreateModelStep
step_create_model = CreateModelStep(
name="AbaloneCreateModel",
model=best_model,
inputs=inputs
)
```
------
## 註冊模型步驟
註冊模型步驟會將模型註冊至 SageMaker 模型註冊庫。
------
#### [ Pipeline Designer ]
若要使用管道設計工具從管道註冊模型，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Amazon SageMaker Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**註冊模型**並將其拖曳至畫布。
1. 在畫布中，選擇您新增的**註冊模型**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.step\$1collections.RegisterModel](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.step_collections.RegisterModel)。
1. 如果畫布包含緊接在您已新增之**註冊模型**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**註冊模型**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**註冊模型**步驟之後的任何步驟，請按一下游標，然後將其從**註冊模型**步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
**重要**
我們建議從 SageMaker AI Python SDK v2.90.0 起使用 [模型步驟](#step-type-model) 註冊模型。`RegisterModel` 將會繼續在 SageMaker Python SDK 的先前版本中運作，但不再受到主動支援。
您可以使用 `RegisterModel` 步驟搭配 Amazon SageMaker 模型註冊表註冊 [sagemaker.model.Model](https://sagemaker.readthedocs.io/en/stable/api/inference/model.html) 或 [sagemaker.pipeline.PipelineModel](https://sagemaker.readthedocs.io/en/stable/api/inference/pipeline.html#pipelinemodel)。`PipelineModel` 表示推論管道，是一種由直線順序容器構成的模型，可處理推論請求。
如需有關如何註冊模型的詳細資訊，請參閱[使用模型註冊庫進行模型註冊部署](model-registry.md)。如需有關 `RegisterModel` 步驟要求的詳細資訊，請參閱 [sagemaker.workflow.step\$1collections.RegisterModel](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.step_collections.RegisterModel) 文件。
下列範例示範如何建立註冊 `PipelineModel` 所需的 `RegisterModel` 步驟。
```
import time
from sagemaker.sklearn import SKLearnModel
from sagemaker.xgboost import XGBoostModel
code_location = 's3://{0}/{1}/code'.format(bucket_name, prefix)
sklearn_model = SKLearnModel(model_data=processing_step.properties.ProcessingOutputConfig.Outputs['model'].S3Output.S3Uri,
entry_point='inference.py',
source_dir='sklearn_source_dir/',
code_location=code_location,
framework_version='1.0-1',
role=role,
sagemaker_session=sagemaker_session,
py_version='py3')
xgboost_model = XGBoostModel(model_data=training_step.properties.ModelArtifacts.S3ModelArtifacts,
entry_point='inference.py',
source_dir='xgboost_source_dir/',
code_location=code_location,
framework_version='0.90-2',
py_version='py3',
sagemaker_session=sagemaker_session,
role=role)
from sagemaker.workflow.step_collections import RegisterModel
from sagemaker import PipelineModel
pipeline_model = PipelineModel(models=[sklearn_model,xgboost_model],role=role,sagemaker_session=sagemaker_session)
step_register = RegisterModel(
name="AbaloneRegisterModel",
model=pipeline_model,
content_types=["application/json"],
response_types=["application/json"],
inference_instances=["ml.t2.medium", "ml.m5.xlarge"],
transform_instances=["ml.m5.xlarge"],
model_package_group_name='sipgroup',
)
```
如果未提供 `model`，則註冊模型步驟需要估算器，如下列範例所示。
```
from sagemaker.workflow.step_collections import RegisterModel
step_register = RegisterModel(
name="AbaloneRegisterModel",
estimator=xgb_train,
model_data=step_train.properties.ModelArtifacts.S3ModelArtifacts,
content_types=["text/csv"],
response_types=["text/csv"],
inference_instances=["ml.t2.medium", "ml.m5.xlarge"],
transform_instances=["ml.m5.xlarge"],
model_package_group_name=model_package_group_name,
approval_status=model_approval_status,
model_metrics=model_metrics
)
```
------
## 部署模型 (端點) 步驟
在管道設計工具中，使用部署模型 (端點) 步驟將您的模型部署到端點。您可以建立新的端點或使用現有的端點。即時推論非常適合您具有即時、互動、低延遲需求的推論工作負載。您可以將模型部署到 SageMaker AI 託管服務，並取得可用於推論的即時端點。這些端點是完全受管且支援自動擴展。若要進一步了解 SageMaker AI 中的即時推論，請參閱[即時推論](realtime-endpoints.md)。
在將部署模型步驟新增至您的管道之前，請確定您的 IAM 角色具有下列許可：
+ `sagemaker:CreateModel`
+ `sagemaker:CreateEndpointConfig`
+ `sagemaker:CreateEndpoint`
+ `sagemaker:UpdateEndpoint`
+ `sagemaker:DescribeModel`
+ `sagemaker:DescribeEndpointConfig`
+ `sagemaker:DescribeEndpoint`
若要進一步了解 SageMaker AI 的所有必要許可，以及如何設定這些許可，請參閱 [Amazon SageMaker AI API 許可：動作、許可與資源參考](api-permissions-reference.md)。
若要在拖放編輯器中將模型部署步驟新增至您的管道，請完成下列步驟：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**部署模型 (端點)** 並將其拖曳至畫布。
1. 在畫布中，選擇您新增的**部署模型 (端點)** 步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。
1. 如果畫布包含緊接在您已新增之**部署模型 (端點)** 步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**部署模型 (端點)** 步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**部署模型 (端點)** 步驟之後的任何步驟，請按一下游標，然後將其從**部署模型 (端點)** 步驟拖曳到該步驟以建立邊緣。
## 轉換步驟
您可以使用批次轉換的轉換步驟對整個資料集執行推論。有關批次轉換的更多資訊，請參閱[使用推論管道執行批次轉換](inference-pipeline-batch.md)。
轉換步驟需要轉換器以及要對其執行批次轉換的資料。下列範例展示如何建立轉換步驟定義。如需轉換步驟要求的詳細資訊，請參閱 [sagemaker.workflow.steps.TransformStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TransformStep) 文件。
------
#### [ Pipeline Designer ]
若要使用拖放視覺化編輯器將批次轉換步驟新增至您的管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**部署模型 (批次轉換)** 並將其拖曳至畫布。
1. 在畫布中，選擇您已新增的**部署模型 (批次轉換)** 步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些索引標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.steps.TransformStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.steps.TransformStep)。
1. 如果畫布包含緊接在您已新增之**部署模型 (批次轉換)** 步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**部署模型 (批次轉換)** 步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**部署模型 (批次轉換)** 步驟之後的任何步驟，請按一下游標，然後將其從**部署模型 (批次轉換)** 步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
```
from sagemaker.workflow.pipeline_context import PipelineSession
from sagemaker.transformer import Transformer
from sagemaker.inputs import TransformInput
from sagemaker.workflow.steps import TransformStep
transformer = Transformer(..., sagemaker_session=PipelineSession())
step_transform = TransformStep(
name="AbaloneTransform",
step_args=transformer.transform(data="s3://amzn-s3-demo-bucket/my-data"),
)
```
------
## 條件步驟
您可以使用條件步驟來評估步驟屬性的條件，以評估接下來應該在管道中採取哪些動作。
條件步驟需要：
+ 條件清單。
+ 如果條件評估為 `true`，要執行的步驟清單。
+ 如果條件評估為 `false`，要執行的步驟清單。
------
#### [ Pipeline Designer ]
若要使用管道設計工具將條件步驟新增至管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Amazon SageMaker Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**條件**並將其拖曳至畫布。
1. 在畫布中，選擇您已新增的**條件**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些索引標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.condition\$1step.ConditionStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.condition_step.ConditionStep)。
1. 如果畫布包含緊接在您已新增之**條件**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**條件**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**條件**步驟之後的任何步驟，請按一下游標，然後將其從**條件**步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
下列範例示範如何建立 `ConditionStep` 定義。
**限制**
+ Pipelines 不支援使用巢狀條件步驟。您無法將條件步驟作為另一個條件步驟的輸入傳遞。
+ 條件步驟不能在兩個分支中使用相同的步驟。如果您需要在兩個分支中使用相同的步驟功能，請複製該步驟並為其指定不同的名稱。
```
from sagemaker.workflow.conditions import ConditionLessThanOrEqualTo
from sagemaker.workflow.condition_step import ConditionStep
from sagemaker.workflow.functions import JsonGet
cond_lte = ConditionLessThanOrEqualTo(
left=JsonGet(
step_name=step_eval.name,
property_file=evaluation_report,
json_path="regression_metrics.mse.value"
),
right=6.0
)
step_cond = ConditionStep(
name="AbaloneMSECond",
conditions=[cond_lte],
if_steps=[step_register, step_create_model, step_transform],
else_steps=[]
)
```
如需有關 `ConditionStep` 要求的詳細資訊，請參閱 [sagemaker.workflow.condition\$1step.ConditionStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#conditionstep) API 參考。如需支援的條件的詳細資訊，請參閱 SageMaker AI Python SDK 文件中的 *[Amazon SageMaker Pipelines - 條件](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#conditions)*。
------
## 回呼步驟
使用`Callback`步驟將非由 Amazon SageMaker Pipelines 直接提供的其他程序和 AWS 服務新增至工作流程。`Callback` 步驟執行時，會發生下列程序：
+ Pipelines 會將訊息傳送至客戶指定的 Amazon Simple Queue Service (Amazon SQS) 佇列。訊息包含 Pipelines 產生的字符，以及客戶提供的輸入參數清單。傳送訊息後，Pipelines 會等待客戶回應。
+ 客戶從 Amazon SQS 佇列擷取訊息，並開始自訂程序。
+ 程序完成時，客戶會呼叫下列其中一個 API，並提交 Pipelines 產生的字符：
+ [SendPipelineExecutionStepSuccess](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SendPipelineExecutionStepSuccess.html) 以及輸出參數清單
+ [SendPipelineExecutionStepFailure](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SendPipelineExecutionStepFailure.html) 以及失敗原因
+ API 呼叫會使 Pipeline 繼續進行管道程序或使程序失敗。
如需有關 `Callback` 步驟要求的詳細資訊，請參閱[工作流程回調步驟回調步驟](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.callback_step.CallbackStep)文件。有關完整的解決方案，請參閱[擴展 SageMaker 管道以包含使用回調步驟的自訂步驟](https://aws.amazon.com/blogs/machine-learning/extend-amazon-sagemaker-pipelines-to-include-custom-steps-using-callback-steps/)。
**重要**
Amazon SageMaker Python SDK v2.45.0 和 Amazon SageMaker Studio Classic v3.6.2 中引入了 `Callback` 步驟。您必須先更新 Studio Classic，才能使用 `Callback` 步驟，否則管道 DAG 不會顯示。若要更新 Studio Classic，請參閱[關閉並更新 Amazon SageMaker Studio Classic](studio-tasks-update-studio.md)。
下列範例展示上述程序的實作。
```
from sagemaker.workflow.callback_step import CallbackStep
step_callback = CallbackStep(
name="MyCallbackStep",
sqs_queue_url="https://sqs.us-east-2.amazonaws.com/012345678901/MyCallbackQueue",
inputs={...},
outputs=[...]
)
callback_handler_code = '
import boto3
import json
def handler(event, context):
sagemaker_client=boto3.client("sagemaker")
for record in event["Records"]:
payload=json.loads(record["body"])
token=payload["token"]
# Custom processing
# Call SageMaker AI to complete the step
sagemaker_client.send_pipeline_execution_step_success(
CallbackToken=token,
OutputParameters={...}
)
'
```
**注意**
`CallbackStep` 的輸出參數不應巢狀化。例如，如果您使用巢狀字典作為輸出參數，則字典會被視為單一字串 (例如 `{"output1": "{\"nested_output1\":\"my-output\"}"}`)。如果您提供巢狀值，則當您嘗試參考特定輸出參數時，SageMaker AI 會擲出不可重試的用戶端錯誤。
**停止行為**
`Callback` 步驟執行期間，管道程序不會停止。
當您使用執行中 `Callback` 步驟對管道程序呼叫 [StopPipelineExecution](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StopPipelineExecution.html) 時，Pipelines 會將 Amazon SQS 訊息傳送到 SQS 佇列。SQS 訊息的主體包含設定為 `Stopping` 的**狀態**欄位。下列範例示範 SQS 訊息主體。
```
{
"token": "26vcYbeWsZ",
"pipelineExecutionArn": "arn:aws:sagemaker:us-east-2:012345678901:pipeline/callback-pipeline/execution/7pinimwddh3a",
"arguments": {
"number": 5,
"stringArg": "some-arg",
"inputData": "s3://sagemaker-us-west-2-012345678901/abalone/abalone-dataset.csv"
},
"status": "Stopping"
}
```
您應該將邏輯新增至 Amazon SQS 訊息取用者，以在收到訊息時採取任何必要的動作 (例如資源清理)。然後將呼叫新增至 `SendPipelineExecutionStepSuccess` 或 `SendPipelineExecutionStepFailure`。
只有當 Pipelines 接收到其中一個呼叫時，才會停止管道程序。
## Lambda 步驟
您可以使用 Lambda 步驟來執行 AWS Lambda 函數。您可以執行現有的 Lambda 函式，或 SageMaker AI 可以建立並執行新的 Lambda 函式。如果您選擇使用現有的 Lambda 函數，它必須與 SageMaker AI 管道 AWS 區域 位於相同的 中。如需顯示如何在 SageMaker AI 管道中使用 Lambda 步驟的筆記本，請參閱 [sagemaker-pipelines-lambda-step.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/lambda-step/sagemaker-pipelines-lambda-step.ipynb)。
**重要**
Amazon SageMaker Python SDK v2.51.0 和 Amazon SageMaker Studio Classic v3.9.1 中引入了 Lambda 步驟。您必須先更新 Studio Classic，才能使用 Lambda 步驟，否則管道 DAG 不會顯示。若要更新 Studio Classic，請參閱[關閉並更新 Amazon SageMaker Studio Classic](studio-tasks-update-studio.md)。
SageMaker AI 提供 [sagemaker.lambda\$1helper.Lambda](https://sagemaker.readthedocs.io/en/stable/api/utility/lambda_helper.html) 類別，以建立、更新、調用和刪除 Lambda 函式。`Lambda` 具有下列簽章。
```
Lambda(
function_arn, # Only required argument to invoke an existing Lambda function
# The following arguments are required to create a Lambda function:
function_name,
execution_role_arn,
zipped_code_dir, # Specify either zipped_code_dir and s3_bucket, OR script
s3_bucket, # S3 bucket where zipped_code_dir is uploaded
script, # Path of Lambda function script
handler, # Lambda handler specified as "lambda_script.lambda_handler"
timeout, # Maximum time the Lambda function can run before the lambda step fails
...
)
```
[sagemaker.workflow.lambda\$1step.LambdaStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.lambda_step.LambdaStep) 類別具有 `Lambda` 類型的 `lambda_func` 引數。若要調用現有的 Lambda 函式，唯一的要求是將函式的 Amazon Resource Name (ARN) 提供給 `function_arn`。如果您未提供 `function_arn` 的值，則必須指定 `handler` 和下列其中一項：
+ `zipped_code_dir` – 壓縮 Lambda 函式的路徑
`s3_bucket` – `zipped_code_dir` 上傳至的 Amazon S3 儲存貯體
+ `script` – Lambda 函式指令碼檔案的路徑
下列範例示範如何建立調用現有 Lambda 函式的 `Lambda` 步驟定義。
```
from sagemaker.workflow.lambda_step import LambdaStep
from sagemaker.lambda_helper import Lambda
step_lambda = LambdaStep(
name="ProcessingLambda",
lambda_func=Lambda(
function_arn="arn:aws:lambda:us-west-2:012345678910:function:split-dataset-lambda"
),
inputs={
s3_bucket = s3_bucket,
data_file = data_file
},
outputs=[
"train_file", "test_file"
]
)
```
下列範例示範如何建立使用 Lambda 函式指令碼建立並調用 Lambda 函式的 `Lambda` 步驟定義。
```
from sagemaker.workflow.lambda_step import LambdaStep
from sagemaker.lambda_helper import Lambda
step_lambda = LambdaStep(
name="ProcessingLambda",
lambda_func=Lambda(
function_name="split-dataset-lambda",
execution_role_arn=execution_role_arn,
script="lambda_script.py",
handler="lambda_script.lambda_handler",
...
),
inputs={
s3_bucket = s3_bucket,
data_file = data_file
},
outputs=[
"train_file", "test_file"
]
)
```
**輸入和輸出**
如果您的 `Lambda` 函式具有輸入或輸出，則輸入或輸出也必須在 `Lambda` 步驟中定義。
**注意**
輸入和輸出參數不應巢狀化。例如，如果您使用巢狀字典作為輸出參數，則字典會被視為單一字串 (例如 `{"output1": "{\"nested_output1\":\"my-output\"}"}`)。如果您提供巢狀值並稍後嘗試參考它，則系統會拋出不可重試的用戶端錯誤。
定義 `Lambda` 步驟時，`inputs` 必須是鍵值對的字典。`inputs` 字典的每個值都必須是基本類型 (字串、整數或浮點數)。不支援巢狀物件。如果未定義，則 `inputs` 值預設為 `None`。
`outputs` 值必須是鍵清單。這些鍵指的是在 `Lambda` 函式的輸出中定義的字典。與 `inputs` 類似，這些鍵必須是基本類型，並且不支援巢狀物件。
**逾時和停止行為**
`Lambda` 類別具有一個 `timeout` 引數，可指定 Lambda 函式可以執行的最長時間。預設值是 120 秒，上限值為 10 分鐘。如果 Lambda 函式在達到逾時時間時正在執行，則 Lambda 步驟會失敗；不過，Lambda 函式會繼續執行。
Lambda 步驟執行時，無法停止管道程序，因為 Lambda 步驟調用的 Lambda 函式無法停止。如果您在 Lambda 函式執行時停止程序，管道會等待該函式完成，或直到逾時為止。這取決於哪個先發生。程序接著會停止。如果 Lambda 函式完成，則管道程序狀態為 `Stopped`。如果超時到達，則管道程序狀態為 `Failed`。
## ClarifyCheck 步驟
您可以使用 `ClarifyCheck` 步驟可對照先前的基準執行基準漂移檢查，以便進行偏差分析和模型可解釋性。然後，您可以使用 `model.register()` 方法產生並[註冊基準](https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-quality-clarify-baseline-lifecycle.html#pipelines-quality-clarify-baseline-calculations)，然後使用 `[step\$1args](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#model-step)` 將該方法的輸出傳遞給 [模型步驟](#step-type-model)。Amazon SageMaker Model Monitor 可以針對您的模型端點使用這些基準，進行漂移檢查。因此，您不需要個別提出[基準](https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor-create-baseline.html)建議。
`ClarifyCheck` 步驟也可以從模型註冊中提取漂移檢查基準。`ClarifyCheck` 步驟會使用 SageMaker Clarify 預先建置的容器。此容器提供一系列模型監控功能，包括建議限制條件和根據指定基準來驗證限制條件。如需詳細資訊，請參閱[預先建置的 SageMaker Clarify 容器](clarify-processing-job-configure-container.md)。
### 設定 ClarifyCheck 步驟
您可以設定 `ClarifyCheck` 步驟，以便每次在管道中使用該步驟時僅執行下列其中一種可用的檢查類型。
+ 資料偏差檢查
+ 模型偏差檢查
+ 模型可解釋性檢查
若要這樣做，請使用下列其中一個檢查類型值來設定 `clarify_check_config` 參數：
+ `DataBiasCheckConfig`
+ `ModelBiasCheckConfig`
+ `ModelExplainabilityCheckConfig`
`ClarifyCheck` 步驟會啟動執行 SageMaker Clarify AI 預先建置容器的處理任務，並需要專用的[檢查和處理任務組態](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-configure-processing-jobs.html)。`ClarifyCheckConfig` 和 `CheckJobConfig` 是這些組態的協助程式函式。這些協助程式函式與 SageMaker Clarify 處理任務進行運算，以檢查模型偏差、資料偏差或模型可解釋性的方式一玫。如需詳細資訊，請參閱[執行 SageMaker Clarify 處理任務以進行偏差分析和解釋性](clarify-processing-job-run.md)。
### 控制漂移檢查的步驟行為
`ClarifyCheck` 步驟需要下列兩個布林標記來控制其行為：
+ `skip_check`：此參數指示是否略過針對先前基準的漂移檢查。如果設定為 `False`，則必須有已設定檢查類型的先前基準。
+ `register_new_baseline`：此參數指示是否可透過步驟屬性 `BaselineUsedForDriftCheckConstraints` 存取新計算的基準。如果設定為 `False`，則也必須有已設定檢查類型的先前基準。這可以透過 `BaselineUsedForDriftCheckConstraints` 屬性存取。
如需更多詳細資訊，請參閱[Amazon SageMaker Pipelines 中具有 ClarifyCheck 和 QualityCheck 步驟的基準計算、漂移偵測和生命週期](pipelines-quality-clarify-baseline-lifecycle.md)。
### 處理基準
您可以選擇性地指定 `model_package_group_name` 來尋找現有的基準。然後，`ClarifyCheck` 步驟會在模型套件群組中提取最新核准的模型套件上的 `DriftCheckBaselines`。
或者，您可以透過 `supplied_baseline_constraints` 參數提供先前的基準。如果同時指定 `model_package_group_name` 和 `supplied_baseline_constraints`，則 `ClarifyCheck` 步驟會使用 `supplied_baseline_constraints` 參數指定的基準。
如需使用 `ClarifyCheck` 步驟要求的詳細資訊，請參閱 *Amazon SageMaker AI SageMaker AI SDK for Python* 中的 [sagemaker.workflow.steps.ClarifyCheckStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.clarify_check_step.ClarifyCheckStep)。如需顯示如何在 Pipelines 中使用 `ClarifyCheck` 步驟的 Amazon SageMaker Studio Classic 筆記本，請參閱 [sagemaker-pipeline-model-monitor-clarify-steps.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/model-monitor-clarify-pipelines/sagemaker-pipeline-model-monitor-clarify-steps.ipynb)。
**Example 為資料偏差檢查建立 `ClarifyCheck` 步驟**
```
from sagemaker.workflow.check_job_config import CheckJobConfig
from sagemaker.workflow.clarify_check_step import DataBiasCheckConfig, ClarifyCheckStep
from sagemaker.workflow.execution_variables import ExecutionVariables
check_job_config = CheckJobConfig(
role=role,
instance_count=1,
instance_type="ml.c5.xlarge",
volume_size_in_gb=120,
sagemaker_session=sagemaker_session,
)
data_bias_data_config = DataConfig(
s3_data_input_path=step_process.properties.ProcessingOutputConfig.Outputs["train"].S3Output.S3Uri,
s3_output_path=Join(on='/', values=['s3:/', your_bucket, base_job_prefix, ExecutionVariables.PIPELINE_EXECUTION_ID, 'databiascheckstep']),
label=0,
dataset_type="text/csv",
s3_analysis_config_output_path=data_bias_analysis_cfg_output_path,
)
data_bias_config = BiasConfig(
label_values_or_threshold=[15.0], facet_name=[8], facet_values_or_threshold=[[0.5]]
)
data_bias_check_config = DataBiasCheckConfig(
data_config=data_bias_data_config,
data_bias_config=data_bias_config,
)h
data_bias_check_step = ClarifyCheckStep(
name="DataBiasCheckStep",
clarify_check_config=data_bias_check_config,
check_job_config=check_job_config,
skip_check=False,
register_new_baseline=False
supplied_baseline_constraints="s3://sagemaker-us-west-2-111122223333/baseline/analysis.json",
model_package_group_name="MyModelPackageGroup"
)
```
## QualityCheck 步驟
使用 `QualityCheck` 步驟，針對管道中先前的資料品質或模型品質基準執行[基準建議](https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor-create-baseline.html)和漂移檢查。然後，您可以使用 `model.register()` 方法產生並[註冊基準](https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-quality-clarify-baseline-lifecycle.html#pipelines-quality-clarify-baseline-calculations)，然後使用 `[step\$1args](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#model-step)` 將該方法的輸出傳遞給 [模型步驟](#step-type-model)。
Model Monitor 可針對模型端點使用這些基準進行漂移檢查，因此您不需要單獨執行基準建議。`QualityCheck` 步驟也可以從模型註冊中提取漂移檢查基準。`QualityCheck` 步驟會利用 Amazon SageMaker AI Model Monitor 預先建置的容器。此容器具有一系列模型監控功能，包括建議限制條件、產生統計資料和根據基準驗證限制條件。如需詳細資訊，請參閱[Amazon SageMaker Model Monitor 預建容器](model-monitor-pre-built-container.md)。
### 設定 QualityCheck 步驟
您可以將 `QualityCheck` 步驟設定為每次在管道中使用該步驟時，僅執行下列其中一種檢查類型。
+ 資料品質檢查
+ 模型品質檢查
為了執行此動作，您可以使用下列其中一個檢查類型值來設定 `quality_check_config` 參數：
+ `DataQualityCheckConfig`
+ `ModelQualityCheckConfig`
`QualityCheck` 步驟會啟動執行 Model Monitor 預先建置容器的處理任務，並需要檢查和處理任務的專用組態。`QualityCheckConfig` 和 `CheckJobConfig` 是這些組態的協助程式函式。這些協助程式函式與 Model Monitor 為模型品質或資料品質監控建立基準的方式一致。如需有關模型監視器基線建議的詳細資訊，請參閱[建立基準](model-monitor-create-baseline.md)和[建立模型品質基準](model-monitor-model-quality-baseline.md)。
### 控制漂移檢查的步驟行為
`QualityCheck` 步驟需要下列兩個布林標記來控制其行為：
+ `skip_check`：此參數指示是否略過針對先前基準的漂移檢查。如果設定為 `False`，則必須有已設定檢查類型的先前基準。
+ `register_new_baseline`：此參數指示是否可透過步驟屬性 `BaselineUsedForDriftCheckConstraints` 和 `BaselineUsedForDriftCheckStatistics` 存取新計算的基準。如果設定為 `False`，則也必須有已設定檢查類型的先前基準。這些可透過 `BaselineUsedForDriftCheckConstraints` 和 `BaselineUsedForDriftCheckStatistics` 屬性存取。
如需更多詳細資訊，請參閱[Amazon SageMaker Pipelines 中具有 ClarifyCheck 和 QualityCheck 步驟的基準計算、漂移偵測和生命週期](pipelines-quality-clarify-baseline-lifecycle.md)。
### 處理基準
您可以直接透過 `supplied_baseline_statistics` 和 `supplied_baseline_constraints` 參數指定先前的基準。您也可以指定 `model_package_group_name`，然後 `QualityCheck` 步驟會在模型套件組中提取最新核准的模型套件上的 `DriftCheckBaselines`。
當您指定下列項目時，`QualityCheck` 步驟會對 `QualityCheck` 步驟的檢查類型使用 `supplied_baseline_constraints` 和 `supplied_baseline_statistics` 指定的基準。
+ `model_package_group_name`
+ `supplied_baseline_constraints`
+ `supplied_baseline_statistics`
如需使用 `QualityCheck` 步驟要求的詳細資訊，請參閱 *Amazon SageMaker AI SageMaker AI SDK for Python* 中的 [sagemaker.workflow.steps.QualityCheckStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.quality_check_step.QualityCheckStep)。如需顯示如何在 Pipelines 中使用 `QualityCheck` 步驟的 Amazon SageMaker Studio Classic 筆記本，請參閱 [sagemaker-pipeline-model-monitor-clarify-steps.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/model-monitor-clarify-pipelines/sagemaker-pipeline-model-monitor-clarify-steps.ipynb)。
**Example 為資料品質檢查建立 `QualityCheck` 步驟**
```
from sagemaker.workflow.check_job_config import CheckJobConfig
from sagemaker.workflow.quality_check_step import DataQualityCheckConfig, QualityCheckStep
from sagemaker.workflow.execution_variables import ExecutionVariables
check_job_config = CheckJobConfig(
role=role,
instance_count=1,
instance_type="ml.c5.xlarge",
volume_size_in_gb=120,
sagemaker_session=sagemaker_session,
)
data_quality_check_config = DataQualityCheckConfig(
baseline_dataset=step_process.properties.ProcessingOutputConfig.Outputs["train"].S3Output.S3Uri,
dataset_format=DatasetFormat.csv(header=False, output_columns_position="START"),
output_s3_uri=Join(on='/', values=['s3:/', your_bucket, base_job_prefix, ExecutionVariables.PIPELINE_EXECUTION_ID, 'dataqualitycheckstep'])
)
data_quality_check_step = QualityCheckStep(
name="DataQualityCheckStep",
skip_check=False,
register_new_baseline=False,
quality_check_config=data_quality_check_config,
check_job_config=check_job_config,
supplied_baseline_statistics="s3://sagemaker-us-west-2-555555555555/baseline/statistics.json",
supplied_baseline_constraints="s3://sagemaker-us-west-2-555555555555/baseline/constraints.json",
model_package_group_name="MyModelPackageGroup"
)
```
## EMR 步驟
使用 Amazon SageMaker Pipelines [EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-overview.html) 步驟：
+ 在執行中 Amazon EMR 叢集上處理 [Amazon EMR 步驟](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-work-with-steps.html)。
+ 讓管道為您在 Amazon EMR 叢集上建立和管理叢集。
如需有關 Amazon EMR 的詳細資訊，請參閱 [Getting started with Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-gs.html)。
EMR 步驟要求 `EMRStepConfig` 包括 Amazon EMR 叢集所使用的 JAR 檔案的位置，以及要傳遞的任何引數。如果您想要在執行中的 EMR 叢集上執行步驟，您也會提供 Amazon EMR 叢集 ID。您也可以傳遞叢集組態，在其為您建立、管理和終止的叢集上執行 EMR 步驟。以下章節包括示範這兩種方法的範例和範例筆記本連結。
**注意**
EMR 步驟要求傳遞至管道的角色具有其他許可。將 [AWS 受管政策：`AmazonSageMakerPipelinesIntegrations`](https://docs.aws.amazon.com/sagemaker/latest/dg/security-iam-awsmanpol-pipelines.html#security-iam-awsmanpol-AmazonSageMakerPipelinesIntegrations) 連接至您的管道角色，或確保該角色包含該政策中的許可。
如果您在執行中的叢集上處理 EMR 步驟，則只能使用處於下列其中一種狀態的叢集：
`STARTING`
`BOOTSTRAPPING`
`RUNNING`
`WAITING`
如果您在正在執行的叢集上處理 EMR 步驟，則 EMR 叢集上最多可以有 256 個處於 `PENDING` 狀態的 EMR 步驟。提交超出此限制的 EMR 步驟會導致管道執行失敗。您可以考慮使用 [管道步驟的重試政策](pipelines-retry-policy.md)。
您可以指定叢集 ID 或叢集組態，但不能同時指定兩者。
EMR 步驟憑藉 Amazon EventBridge 來監控 EMR 步驟或叢集狀態變更。如果您在正在執行的叢集上處理 Amazon EMR 任務，EMR 步驟會使用 `SageMakerPipelineExecutionEMRStepStatusUpdateRule` 規則來監控 EMR 步驟狀態。如果您在 EMR 步驟建立的叢集上處理任務，則此步驟會使用 `SageMakerPipelineExecutionEMRClusterStatusRule` 規則來監控叢集狀態中的變化。如果您在 AWS 帳戶中看到其中一個 EventBridge 規則，請不要刪除它們，否則 EMR 步驟可能未完成。
**將 Amazon EMR 步驟新增至管道**
若要將 EMR 步驟新增至管道，請執行下列動作：
+ 依照[啟動 Amazon SageMaker Studio 中的指示開啟 Studio ](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-launch.html)主控台。
+ 在左側導覽窗格中，選取**管道**。
+ 選擇**建立**。
+ 選擇**空白**。
+ 在左側邊欄中，選擇**處理資料**並將其拖曳至畫布。
+ 在畫布中，選擇您新增的**處理資料**步驟。
+ 在右側邊欄中的 模式下，選擇 **EMR （受管）**。
+ 在右側邊欄中，完成**設定和詳細資訊**索引標籤中的表單。如需這些標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.fail\$1step.EMRstep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.emr_step.EMRStep)。
**在正在執行的 Amazon EMR 叢集上啟動新任務**
若要在執行中的 Amazon EMR 叢集上啟動新任務，請將叢集 ID 作為字串傳遞至 `EMRStep` 的 `cluster_id` 引數。下列範例示範此程序。
```
from sagemaker.workflow.emr_step import EMRStep, EMRStepConfig
emr_config = EMRStepConfig(
jar="jar-location", # required, path to jar file used
args=["--verbose", "--force"], # optional list of arguments to pass to the jar
main_class="com.my.Main1", # optional main class, this can be omitted if jar above has a manifest
properties=[ # optional list of Java properties that are set when the step runs
{
"key": "mapred.tasktracker.map.tasks.maximum",
"value": "2"
},
{
"key": "mapreduce.map.sort.spill.percent",
"value": "0.90"
},
{
"key": "mapreduce.tasktracker.reduce.tasks.maximum",
"value": "5"
}
]
)
step_emr = EMRStep (
name="EMRSampleStep", # required
cluster_id="j-1ABCDEFG2HIJK", # include cluster_id to use a running cluster
step_config=emr_config, # required
display_name="My EMR Step",
description="Pipeline step to execute EMR job"
)
```
如需逐步引導您完成整個範例的範例筆記本，請參閱 [Pipelines EMR Step With Running EMR Cluster](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/emr-step/sagemaker-pipelines-emr-step-with-running-emr-cluster.ipynb)。
**在新的 Amazon EMR 叢集上啟動新任務**
若要在 `EMRStep` 為您建立的新叢集上啟動新任務，請提供您的叢集組態作為字典。字典必須具有與 [RunJobFlow](https://docs.aws.amazon.com/emr/latest/APIReference/API_RunJobFlow.html) 請求相同的結構。但是，請勿在叢集組態中包含下列欄位：
+ [`Name`]
+ [`Steps`]
+ [`AutoTerminationPolicy`]
+ [`Instances`][`KeepJobFlowAliveWhenNoSteps`]
+ [`Instances`][`TerminationProtected`]
所有其他 `RunJobFlow` 引數都可以在叢集組態中使用。如需有關請求語法的詳細資訊，請參閱 [RunJobFlow](https://docs.aws.amazon.com/emr/latest/APIReference/API_RunJobFlow.html)。
下列範例會將叢集組態傳遞至 EMR 步驟定義。這會提示在新的 EMR 叢集上啟動新任務的步驟。此範例中的 EMR 叢集組態包含主要和核心 EMR 叢集節點的規格。如需有關 Amazon EMR 節點類型的詳細資訊，請參閱[了解節點類型：主節點、核心節點和任務節點](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-master-core-task-nodes.html)。
```
from sagemaker.workflow.emr_step import EMRStep, EMRStepConfig
emr_step_config = EMRStepConfig(
jar="jar-location", # required, path to jar file used
args=["--verbose", "--force"], # optional list of arguments to pass to the jar
main_class="com.my.Main1", # optional main class, this can be omitted if jar above has a manifest
properties=[ # optional list of Java properties that are set when the step runs
{
"key": "mapred.tasktracker.map.tasks.maximum",
"value": "2"
},
{
"key": "mapreduce.map.sort.spill.percent",
"value": "0.90"
},
{
"key": "mapreduce.tasktracker.reduce.tasks.maximum",
"value": "5"
}
]
)
# include your cluster configuration as a dictionary
emr_cluster_config = {
"Applications": [
{
"Name": "Spark",
}
],
"Instances":{
"InstanceGroups":[
{
"InstanceRole": "MASTER",
"InstanceCount": 1,
"InstanceType": "m5.2xlarge"
},
{
"InstanceRole": "CORE",
"InstanceCount": 2,
"InstanceType": "m5.2xlarge"
}
]
},
"BootstrapActions":[],
"ReleaseLabel": "emr-6.6.0",
"JobFlowRole": "job-flow-role",
"ServiceRole": "service-role"
}
emr_step = EMRStep(
name="emr-step",
cluster_id=None,
display_name="emr_step",
description="MyEMRStepDescription",
step_config=emr_step_config,
cluster_config=emr_cluster_config
)
```
如需逐步引導您完成整個範例的範例筆記本，請參閱 [Pipelines EMR Step With Cluster Lifecycle Management](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/emr-step/sagemaker-pipelines-emr-step-with-cluster-lifecycle-management.ipynb)。
## EMR 無伺服器步驟
若要將 EMR 無伺服器步驟新增至管道，請執行下列動作：
+ 依照[啟動 Amazon SageMaker Studio 中的指示開啟 Studio ](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-launch.html)主控台。
+ 在左側導覽窗格中，選取**管道**。
+ 選擇**建立**。
+ 選擇**空白**。
+ 在左側邊欄中，選擇**處理資料**並將其拖曳至畫布。
+ 在畫布中，選擇您新增的**處理資料**步驟。
+ 在右側邊欄中的 模式下，選擇 **EMR （無伺服器）**。
+ 在右側邊欄中，完成**設定和詳細資訊**索引標籤中的表單。
## 筆記本任務步驟
使用 `NotebookJobStep` 以非互動方式將您的 SageMaker 筆記本任務做為管道步驟執行。如果您在 Pipelines 拖放 UI 中建置管道，請使用 [執行程式碼步驟](#step-type-executecode) 來執行筆記本。如需 SageMaker 筆記本任務的詳細資訊，請參閱 [SageMaker 筆記本工作](notebook-auto-run.md)。
`NotebookJobStep` 至少需要一個輸入筆記本、映像 URI 和核心名稱。如需筆記本任務步驟要求以及您可以設定為自訂步驟的其他參數的詳細資訊，請參閱 [sagemaker.workflow.steps.NotebookJobStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.notebook_job_step.NotebookJobStep)。
下列範例使用最少引數來定義 `NotebookJobStep`。
```
from sagemaker.workflow.notebook_job_step import NotebookJobStep
notebook_job_step = NotebookJobStep(
input_notebook=input_notebook,
image_uri=image_uri,
kernel_name=kernel_name
)
```
您的 `NotebookJobStep` 管道步驟會被視為 SageMaker 筆記本任務。因此，請在 Studio Classic UI 筆記本任務儀表板中追蹤執行狀態，方法是使用 `tags` 引數包含特定標籤。如需要包含的標籤詳細資訊，請參閱[在 Studio UI 儀表板中檢視您的筆記本任務](create-notebook-auto-run-sdk.md#create-notebook-auto-run-dash)。
此外，如果您使用 SageMaker Python SDK 排程筆記本任務，您只能指定特定映像來執行筆記本任務。如需詳細資訊，請參閱[SageMaker AI Python SDK 筆記本任務的映像限制條件](notebook-auto-run-constraints.md#notebook-auto-run-constraints-image-sdk)。
## 失敗步驟
使用失敗步驟在未達到所需條件或狀態時停止 Amazon SageMaker Pipelines 執行。失敗步驟也可讓您輸入自訂錯誤訊息，指出管道執行失敗的原因。
**注意**
當失敗步驟和其他管道步驟同時執行時，在所有並行步驟都完成之前，管道都不會終止。
### 使用失敗步驟的限制
+ 您無法將失敗步驟新增至其他步驟的 `DependsOn` 清單。如需詳細資訊，請參閱[步驟之間的自訂相依性](build-and-manage-steps.md#build-and-manage-custom-dependency)。
+ 其他步驟無法參考失敗步驟。它*始終*是管道執行的最後一步。
+ 您無法重試以失敗步驟結束的管道執行。
您能以靜態文字字串的形式建立失敗步驟錯誤訊息。或者，您也可以使用[管道參數](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-parameters.html)和[聯結](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html?highlight=Join#sagemaker.workflow.functions.Join)操作或其他[步驟屬性](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#build-and-manage-properties)，來建立資訊更豐富的錯誤訊息，如果您使用 SDK 的話。
------
#### [ Pipeline Designer ]
若要將失敗步驟新增至您的管道，請執行下列動作：
1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Studio 主控台。
1. 在左側導覽窗格中，選取**管道**。
1. 選擇**建立**。
1. 選擇**空白**。
1. 在左側邊欄中，選擇**失敗**並將其拖曳至畫布。
1. 在畫布中，選擇您已新增的**失敗**步驟。
1. 在右側邊欄中，完成**設定**和**詳細資訊**索引標籤中的表單。如需這些索引標籤中欄位的相關資訊，請參閱 [sagemaker.workflow.fail\$1step.FailStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.fail_step.FailStep)。
1. 如果畫布包含緊接在您已新增之**失敗**步驟之前的任何步驟，請按一下游標，然後將其從該步驟拖曳到**失敗**步驟以建立邊緣。
1. 如果畫布包含緊接在您已新增之**失敗**步驟之後的任何步驟，請按一下游標，然後將其從**失敗**步驟拖曳到該步驟以建立邊緣。
------
#### [ SageMaker Python SDK ]
**Example**
下列範例程式碼片段使用 `FailStep` (包含透過管道參數和 `Join` 操作設定的 `ErrorMessage`)。
```
from sagemaker.workflow.fail_step import FailStep
from sagemaker.workflow.functions import Join
from sagemaker.workflow.parameters import ParameterInteger
mse_threshold_param = ParameterInteger(name="MseThreshold", default_value=5)
step_fail = FailStep(
name="AbaloneMSEFail",
error_message=Join(
on=" ", values=["Execution failed due to MSE >", mse_threshold_param]
),
)
```
------
# 新增整合
MLflow 整合可讓您將 MLflow 與管道搭配使用，以選取追蹤伺服器或無伺服器應用程式、選擇實驗和日誌指標。
## 重要概念
**預設應用程式建立** - 當您輸入管道視覺化編輯器時，將會建立預設 MLflow 應用程式。
**整合面板** - 新的整合面板包含 MLflow，您可以選取和設定。
**更新應用程式和實驗** - 在管道執行期間覆寫所選應用程式和實驗的選項。
## 運作方式
+ 前往**管道視覺化編輯器**
+ 在工具列上選擇**整合**
+ 選擇 **MLflow**
+ 設定 MLflow 應用程式和實驗
## 範例螢幕擷取畫面
整合側邊面板
![\[要執行的描述。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/screenshot-pipeline-1.png)
MLflow 組態
![\[要執行的描述。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/screenshot-pipeline-2.png)
如何在管道執行期間覆寫實驗
![\[要執行的描述。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/screenshot-pipeline-3.png)
## 步驟屬性
使用 `properties` 屬性在管道中的步驟之間新增資料相依性。Pipelines 會使用這些資料相依性，從管道定義建構 DAG。這些屬性可以作為預留位置值參考，並在執行期解析。
Pipelines 步驟的 `properties` 屬性與 `Describe` 呼叫針對對應 SageMaker AI 任務類型傳回的物件相符。對於每個任務類型，`Describe` 呼叫都會傳回下列回應物件：
+ `ProcessingStep` – [DescribeProcessingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeProcessingJob.html)
+ `TrainingStep` – [DescribeTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingJob.html)
+ `TransformStep` – [DescribeTransformJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTransformJob.html)
若要在建立資料相依性期間檢查每個步驟類型可參考的屬性，請參閱 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 中的 *[資料相依性 - 屬性參考](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#data-dependency-property-reference)*。
## 步驟平行處理
當步驟不依賴任何其他步驟時，其會在管道執行時立即執行。不過，平行執行過多管道步驟可能會快速耗盡可用的資源。使用 `ParallelismConfiguration` 控制管道執行的並行步驟數量。
下列範例使用 `ParallelismConfiguration` 將並行步驟限制為 5 個。
```
pipeline.create(
parallelism_config=ParallelismConfiguration(5),
)
```
## 步驟之間的資料相依性
您可以透過指定步驟之間的資料關係來定義 DAG 的結構。若要在步驟之間建立資料相依性，請將一個步驟的屬性作為輸入傳遞至管道中的另一個步驟。在提供輸入的步驟執行完後，接收輸入的步驟才會啟動。
資料相依性使用以下格式的 JsonPath 表示法。此格式會周遊 JSON 屬性檔案。這表示您可以視需要附加任意數量的 ** 執行個體，以達到檔案中所需的巢狀屬性。如需有關 JsonPath 符號的詳細資訊，請參閱 [JSONPath 回購](https://github.com/json-path/JsonPath)。
```
.properties..
```
下面示範如何使用處理步驟的 `ProcessingOutputConfig` 屬性來指定 Amazon S3 儲存貯體。
```
step_process.properties.ProcessingOutputConfig.Outputs["train_data"].S3Output.S3Uri
```
若要建立資料相依性，請將儲存貯體傳遞至訓練步驟，如下所示。
```
from sagemaker.workflow.pipeline_context import PipelineSession
sklearn_train = SKLearn(..., sagemaker_session=PipelineSession())
step_train = TrainingStep(
name="CensusTrain",
step_args=sklearn_train.fit(inputs=TrainingInput(
s3_data=step_process.properties.ProcessingOutputConfig.Outputs[
"train_data"].S3Output.S3Uri
))
)
```
若要在建立資料相依性期間檢查每個步驟類型可參考的屬性，請參閱 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 中的[Data Dependency - Property Reference](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#data-dependency-property-reference)。**
## 步驟之間的自訂相依性
當您指定資料相依性時，Pipelines 會提供步驟之間的資料連線。或者，一個步驟可以存取上一個步驟中的資料，而無需直接使用 Pipelines。在此情況下，您可以建立自訂相依性，告知 Pipelines 在另一個步驟完成執行之前不要開始步驟。您可以透過指定步驟的 `DependsOn` 屬性來建立自訂相依性。
例如，下列內容定義了僅在 `A` 步驟和 `B` 步驟執行完後才開始的 `C` 步驟。
```
{
'Steps': [
{'Name':'A', ...},
{'Name':'B', ...},
{'Name':'C', 'DependsOn': ['A', 'B']}
]
}
```
如果相依性將建立循環相依性，Pipelines 會擲回驗證例外狀況。
下列範例會建立在處理步驟執行完後開始的訓練步驟。
```
processing_step = ProcessingStep(...)
training_step = TrainingStep(...)
training_step.add_depends_on([processing_step])
```
下列範例會建立在兩個不同的處理步驟執行完後才開始的訓練步驟。
```
processing_step_1 = ProcessingStep(...)
processing_step_2 = ProcessingStep(...)
training_step = TrainingStep(...)
training_step.add_depends_on([processing_step_1, processing_step_2])
```
下面提供了建立自訂相依性的替代方法。
```
training_step.add_depends_on([processing_step_1])
training_step.add_depends_on([processing_step_2])
```
下列範例會建立一個訓練步驟，接收來自一個處理步驟的輸入，並等待另一個處理步驟執行完成。
```
processing_step_1 = ProcessingStep(...)
processing_step_2 = ProcessingStep(...)
training_step = TrainingStep(
...,
inputs=TrainingInput(
s3_data=processing_step_1.properties.ProcessingOutputConfig.Outputs[
"train_data"
].S3Output.S3Uri
)
training_step.add_depends_on([processing_step_2])
```
下列範例示範如何擷取步驟之自訂相依性的字串清單。
```
custom_dependencies = training_step.depends_on
```
## 步驟中的自訂映像
在您的管道中建立步驟時，您可以使用任何可用的 SageMaker AI [深度學習容器映像](https://github.com/aws/deep-learning-containers/blob/master/available_images.md)。
您也可以在管道步驟中使用您自己的容器。因為您無法從 Studio Classic 內建立映像，所以必須先使用另一種方法建立映像，然後才能使用該映像搭配 Pipelines。
若要在為管道建立步驟時使用您自己的容器，請在估算器定義中包含映像 URI。如需使用您自己的容器搭配 SageMaker AI 的詳細資訊，請參閱[使用 Docker 容器搭配 SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/docker-containers.html)。
# 使用 @step 裝飾項目直接移轉程式碼
`@step` 裝飾項目是將本機機器學習 (ML) 程式碼轉換為一或多個管道步驟的特徵。您可以像撰寫任何 ML 專案一樣撰寫 ML 函式。一旦使用 `@remote` 裝飾項目在本機或做為訓練任務測試，您就可以透過新增 `@step` 裝飾項目，將函式轉換為 SageMaker AI 管道步驟。然後，您可以將 `@step` 裝飾的函式呼叫的輸出做為步驟傳遞至 Pipelines，以建立和執行管道。您也可以使用 `@step` 裝飾項目鏈結一系列函式，以建立多步驟有向無環圖 (DAG) 管道。
使用 `@step` 裝飾項目的設定與使用 `@remote` 裝飾項目的設定相同。如需如何[設定環境](https://docs.aws.amazon.com/sagemaker/latest/dg/train-remote-decorator.html#train-remote-decorator-env)和[使用組態檔案](https://docs.aws.amazon.com/sagemaker/latest/dg/train-remote-decorator-config.html)來設定預設值的詳細資訊，請參閱遠端函式文件。如需 `@step` 裝飾項目的詳細資訊，請參閱。[sagemaker.workflow.function\$1step.step](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.function_step.step)。
若要檢視示範如何使用 `@step` 裝飾項目的範例筆記本，請參閱 [@step 裝飾項目範例筆記本](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker-pipelines/step-decorator)。
下列各節說明如何使用 `@step` 裝飾項目註釋您的本機 ML 程式碼，以建立步驟、使用步驟建立和執行管道，以及為您的使用案例自訂體驗。
**Topics**
+ [使用 `@step` 裝飾的函式建立管道](pipelines-step-decorator-create-pipeline.md)
+ [執行管道](pipelines-step-decorator-run-pipeline.md)
+ [設定您的管道](pipelines-step-decorator-cfg-pipeline.md)
+ [最佳實務](pipelines-step-decorator-best.md)
+ [限制](pipelines-step-decorator-limit.md)
# 使用 `@step` 裝飾的函式建立管道
您可以建立一個管道，方法是使用 `@step` 裝飾項目將 Python 函式轉換為管道步驟、在這些函式之間建立相依性以建立管道圖形 (或有向無環圖 (DAG))，然後將該圖形的分葉節點做為步驟清單傳遞至管道。下列各節會使用範例詳細說明此程序。
**Topics**
+ [將函式轉換為步驟](#pipelines-step-decorator-run-pipeline-convert)
+ [在步驟之間建立相依性](#pipelines-step-decorator-run-pipeline-link)
+ [使用 `ConditionStep` 搭配 `@step` 裝飾的步驟](#pipelines-step-decorator-condition)
+ [使用步驟的 `DelayedReturn` 輸出定義管道](#pipelines-step-define-delayed)
+ [建立管道](#pipelines-step-decorator-pipeline-create)
## 將函式轉換為步驟
若要使用 `@step` 裝飾項目建立步驟，請使用 `@step` 註釋函式。下列範例顯示預先處理資料的 `@step` 裝飾函式。
```
from sagemaker.workflow.function_step import step
@step
def preprocess(raw_data):
df = pandas.read_csv(raw_data)
...
return procesed_dataframe
step_process_result = preprocess(raw_data)
```
當您調用 `@step` 裝飾函式時，SageMaker AI 會傳回 `DelayedReturn` 執行個體，而不是執行該函式。`DelayedReturn` 執行個體是該函式實際傳回的 Proxy。`DelayedReturn` 執行個體可以做為引數傳遞至另一個函式，或直接做為步驟傳遞至管道執行個體。如需 `DelayedReturn` 類別的相關資訊，請參閱 [sagemaker.workflow.function\$1step.DelayedReturn](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.function_step.DelayedReturn)。
## 在步驟之間建立相依性
當您在兩個步驟之間建立相依性時，您可以在管道圖中的步驟之間建立連線。下列各節介紹在管道步驟之間建立相依性的多種方式。
### 透過輸入引數的資料相依性
將某個函式的 `DelayedReturn` 輸出做為輸入傳遞至另一個函式，會自動在管道 DAG 中建立資料相依性。在下列範例中，將 `preprocess` 函式的 `DelayedReturn` 輸出傳遞至 `train` 函式，會在 `preprocess` 與 `train` 之間建立相依性。
```
from sagemaker.workflow.function_step import step
@step
def preprocess(raw_data):
df = pandas.read_csv(raw_data)
...
return procesed_dataframe
@step
def train(training_data):
...
return trained_model
step_process_result = preprocess(raw_data)
step_train_result = train(step_process_result)
```
前一個範例定義了使用 `@step` 裝飾的訓練函式。調用此函式時，其會接收預先處理管道步驟的 `DelayedReturn` 輸出做為輸入。調用訓練函式會傳回另一個 `DelayedReturn`。執行個體。此執行個體會保留形成管道 DAG 之函式 (即此範例中 `preprocess` 的步驟) 中定義之所有先前步驟的相關資訊。
在前一個範例中，`preprocess` 函式會傳回單一值。如需清單或元組等更複雜的傳回類型，請參閱[限制](pipelines-step-decorator-limit.md)。
### 定義自訂相依性
在前一個範例中，`train` 函式收到 `preprocess` 的 `DelayedReturn` 輸出並建立了相依性。如果您想要明確定義相依性，而不傳遞前一個步驟輸出，請使用 `add_depends_on` 函式搭配步驟。您可以使用 `get_step()` 函式，從其 `DelayedReturn` 執行個體擷取基礎步驟，然後使用相依性做為輸入來呼叫 `add_depends_on`\$1on。若要檢視 `get_step()` 函式定義，請參閱 [sagemaker.workflow.step\$1outputs.get\$1step](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.step_outputs.get_step)。下列範例展示如何使用 `get_step()` 和 `add_depends_on()` 建立 `preprocess` 與 `train` 之間的相依性。
```
from sagemaker.workflow.step_outputs import get_step
@step
def preprocess(raw_data):
df = pandas.read_csv(raw_data)
...
processed_data = ..
return s3.upload(processed_data)
@step
def train():
training_data = s3.download(....)
...
return trained_model
step_process_result = preprocess(raw_data)
step_train_result = train()
get_step(step_train_result).add_depends_on([step_process_result])
```
### 將資料從 `@step` 裝飾函式傳遞至傳統管道步驟，或從中將資料傳遞至該函式
您可以建立一個管道，其中包含 `@step` 裝飾步驟和傳統管道步驟，以及在它們之間傳遞資料。例如，您可以使用 `ProcessingStep` 來處理資料，並將其結果傳遞至 `@step` 裝飾的訓練函式。在下列範例中，`@step` 裝飾的訓練步驟會參考處理步驟的輸出。
```
# Define processing step
from sagemaker.sklearn.processing import SKLearnProcessor
from sagemaker.processing import ProcessingInput, ProcessingOutput
from sagemaker.workflow.steps import ProcessingStep
sklearn_processor = SKLearnProcessor(
framework_version='1.2-1',
role='arn:aws:iam::123456789012:role/SagemakerExecutionRole',
instance_type='ml.m5.large',
instance_count='1',
)
inputs = [
ProcessingInput(source=input_data, destination="/opt/ml/processing/input"),
]
outputs = [
ProcessingOutput(output_name="train", source="/opt/ml/processing/train"),
ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"),
ProcessingOutput(output_name="test", source="/opt/ml/processing/test")
]
process_step = ProcessingStep(
name="MyProcessStep",
step_args=sklearn_processor.run(inputs=inputs, outputs=outputs,code='preprocessing.py'),
)
```
```
# Define a @step-decorated train step which references the
# output of a processing step
@step
def train(train_data_path, test_data_path):
...
return trained_model
step_train_result = train(
process_step.properties.ProcessingOutputConfig.Outputs["train"].S3Output.S3Uri,
process_step.properties.ProcessingOutputConfig.Outputs["test"].S3Output.S3Uri,
)
```
## 使用 `ConditionStep` 搭配 `@step` 裝飾的步驟
Pipelines 支援 `ConditionStep` 類別，其會評估先前步驟的結果，以決定要在管道中採取的動作。您也可以使用 `ConditionStep` 搭配 `@step` 裝飾的步驟。若要使用任何 `@step` 裝飾步驟的輸出搭配 `ConditionStep`，請輸入該步驟的輸出做為 `ConditionStep` 的引數。在下列範例中，條件步驟會收到 `@step` 裝飾的模型評估步驟的輸出。
```
# Define steps
@step(name="evaluate")
def evaluate_model():
# code to evaluate the model
return {
"rmse":rmse_value
}
@step(name="register")
def register_model():
# code to register the model
...
```
```
# Define ConditionStep
from sagemaker.workflow.condition_step import ConditionStep
from sagemaker.workflow.conditions import ConditionGreaterThanOrEqualTo
from sagemaker.workflow.fail_step import FailStep
conditionally_register = ConditionStep(
name="conditional_register",
conditions=[
ConditionGreaterThanOrEqualTo(
# Output of the evaluate step must be json serializable
left=evaluate_model()["rmse"], #
right=5,
)
],
if_steps=[FailStep(name="Fail", error_message="Model performance is not good enough")],
else_steps=[register_model()],
)
```
## 使用步驟的 `DelayedReturn` 輸出定義管道
無論您是否使用 `@step` 裝飾項目，您都會以相同的方式定義管道。將 `DelayedReturn` 執行個體傳遞至您的管道時，您不需要傳遞完整步驟清單以建置管道。SDK 會根據您定義的相依性，自動推斷先前的步驟。管道圖中包含您傳遞至管道的 `Step` 物件或 `DelayedReturn` 物件的所有先前步驟。在下列範例中，管道會收到 `train` 函式的 `DelayedReturn` 物件。SageMaker AI 會將 `preprocess` 步驟做為 `train` 的前一個步驟傳遞至管道圖。
```
from sagemaker.workflow.pipeline import Pipeline
pipeline = Pipeline(
name="",
steps=[step_train_result],
sagemaker_session=,
)
```
如果步驟之間沒有資料或自訂相依性，而且您平行執行多個步驟，則管道圖具有多個分葉節點。將清單中的所有這些分葉節點傳遞至管道定義中的 `steps` 引數，如下列範例所示：
```
@step
def process1():
...
return data
@step
def process2():
...
return data
step_process1_result = process1()
step_process2_result = process2()
pipeline = Pipeline(
name="",
steps=[step_process1_result, step_process2_result],
sagemaker_session=sagemaker-session,
)
```
當管道執行時，這兩個步驟都會平行執行。
您只能將圖形的分葉節點傳遞至管道，因為分葉節點包含透過資料或自訂相依性定義之所有先前步驟的相關資訊。當其編譯管道時，SageMaker AI 也會推斷形成管道圖的所有後續步驟，並將每個步驟做為個別步驟新增至管道。
## 建立管道
呼叫 `pipeline.create()` 來建立管道，如下列程式碼片段所示。如需 `create()` 的詳細資訊，請參閱 [sagemaker.workflow.pipeline.Pipeline.create](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.pipeline.Pipeline.create)。
```
role = "pipeline-role"
pipeline.create(role)
```
當您呼叫 `pipeline.create()` 時，SageMaker AI 會編譯所有定義為管道執行個體一部分的步驟。SageMaker AI 會將序列化函式、引數和所有其他步驟相關成品上傳至 Amazon S3。
根據下列結構，資料位於 S3 儲存貯體中：
```
s3_root_uri/
pipeline_name/
sm_rf_user_ws/
workspace.zip # archive of the current working directory (workdir)
step_name/
timestamp/
arguments/ # serialized function arguments
function/ # serialized function
pre_train_dependencies/ # any dependencies and pre_execution scripts provided for the step
execution_id/
step_name/
results # returned output from the serialized function including the model
```
`s3_root_uri` 定義在 SageMaker AI 組態檔案中，並套用至整個管道。如果未定義，則會使用預設的 SageMaker AI 儲存貯體。
**注意**
每次 SageMaker AI 編譯管道時，SageMaker AI 都會將步驟的序列化函式、引數和相依性儲存在以目前時間加上時間戳記的資料夾中。每次執行 `pipeline.create()`、`pipeline.update()`、`pipeline.upsert()` 或 `pipeline.definition()` 時都會發生這種情況。
# 執行管道
下頁描述如何使用 Amazon SageMaker Pipelines 執行管道，無論是搭配 SageMaker AI 資源還是在本機。
使用 `pipeline.start()` 函式啟動新的管道執行，就像傳統 SageMaker AI 管道執行一樣。如需 `start()` 函式的相關資訊，請參閱 [sagemaker.workflow.pipeline.Pipeline.start](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.pipeline.Pipeline.start)。
**注意**
使用 `@step` 裝飾項目定義的步驟會做為訓練任務執行。因此，請注意下列限制：
您帳戶中的執行個體限制和訓練任務限制。相應地更新您的限制，以避免發生任何限流或資源限制問題。
與管道中每個訓練步驟執行相關聯的金錢成本。如需詳細資訊，請參閱 [Amazon SageMaker 定價](https://aws.amazon.com/sagemaker/pricing/)。
## 從本機執行的管道擷取結果
若要檢視管道執行任何步驟的結果，請使用 [execution.result()](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.pipeline._PipelineExecution.result )，如下列程式碼片段所示：
```
execution = pipeline.start()
execution.result(step_name="train")
```
**注意**
Pipelines 不支援本機模式下的 `execution.result()`。
您一次只能擷取一個步驟的結果。如果步驟名稱是由 SageMaker AI 產生，您可以呼叫 `list_steps` 來擷取步驟名稱，如下所示：
```
execution.list_step()
```
## 在本機執行管道
您可以像執行傳統管道步驟一樣，使用 `@step` 裝飾步驟在本機執行管道。如需本機模式管道執行的詳細資訊，請參閱[使用本機模式執行管道](pipelines-local-mode.md)。若要使用本機模式，請將 `LocalPipelineSession` 而非 `SageMakerSession` 提供給管道定義，如下列範例所示：
```
from sagemaker.workflow.function_step import step
from sagemaker.workflow.pipeline import Pipeline
from sagemaker.workflow.pipeline_context import LocalPipelineSession
@step
def train():
training_data = s3.download(....)
...
return trained_model
step_train_result = train()
local_pipeline_session = LocalPipelineSession()
local_pipeline = Pipeline(
name="",
steps=[step_train_result],
sagemaker_session=local_pipeline_session # needed for local mode
)
local_pipeline.create(role_arn="role_arn")
# pipeline runs locally
execution = local_pipeline.start()
```
# 設定您的管道
建議您使用 SageMaker AI 組態檔案來設定管道的預設值。如需 SageMaker AI 組態檔案的詳細資訊，請參閱[搭配 SageMaker Python SDK 設定和使用預設值](https://sagemaker.readthedocs.io/en/stable/overview.html#configuring-and-using-defaults-with-the-sagemaker-python-sdk)。新增至組態檔案的任何組態都會套用至管道中的所有步驟。如果您想要覆寫任何步驟的選項，請在 `@step` 裝飾項目引數中提供新值。下列主題描述如何設定組態檔案。
組態檔案中 `@step` 裝飾項目的組態與 `@remote` 裝飾項目的組態相同。若要在組態檔案中設定管道角色 ARN 和管道標籤，請使用下列程式碼片段中顯示的 `Pipeline` 區段：
```
SchemaVersion: '1.0'
SageMaker:
Pipeline:
RoleArn: 'arn:aws:iam::555555555555:role/IMRole'
Tags:
- Key: 'tag_key'
Value: 'tag_value'
```
對於您在組態檔案中設定的大多數預設值，您也可以透過將新值傳遞至 `@step` 裝飾項目來覆寫這些預設值。例如，您可以覆寫組態檔案中為預先處理步驟設定的執行個體類型，如下列範例所示：
```
@step(instance_type="ml.m5.large")
def preprocess(raw_data):
df = pandas.read_csv(raw_data)
...
return procesed_dataframe
```
一些引數不是 `@step` 裝飾項目參數清單的一部分 - 只能透過 SageMaker AI 組態檔案為整個管道設定這些引數。它們列示如下：
+ `sagemaker_session` (`sagemaker.session.Session`)：獲 SageMaker AI 委派服務呼叫的基礎 SageMaker AI 工作階段。如果未指定，則會使用預設組態建立工作階段，如下所示：
```
SageMaker:
PythonSDK:
Modules:
Session:
DefaultS3Bucket: 'default_s3_bucket'
DefaultS3ObjectKeyPrefix: 'key_prefix'
```
+ `custom_file_filter` (`CustomFileFilter)`)：一種 `CustomFileFilter` 物件，其指定要包含在管道步驟中的本機目錄和檔案。如果未指定，此值預設為 `None`。`custom_file_filter` 若要生效，您必須將 `IncludeLocalWorkdir` 設定為 `True`。下列範例顯示的組態會忽略所有筆記本檔案，以及名為 `data` 的檔案和目錄。
```
SchemaVersion: '1.0'
SageMaker:
PythonSDK:
Modules:
RemoteFunction:
IncludeLocalWorkDir: true
CustomFileFilter:
IgnoreNamePatterns: # files or directories to ignore
- "*.ipynb" # all notebook files
- "data" # folder or file named "data"
```
如需如何使用 `IncludeLocalWorkdir` 搭配 `CustomFileFilter` 的詳細資訊，請參閱[搭配 @remote 裝飾項目使用模組化代碼](train-remote-decorator-modular.md)。
+ `s3_root_uri (str)`：SageMaker AI 將程式碼封存和資料上傳至其中的根 Amazon S3 資料夾。如果未指定，則會使用預設 SageMaker AI 儲存貯體。
+ `s3_kms_key (str)`：用來加密輸入和輸出資料的金鑰。您只能在 SageMaker AI 組態檔案中設定此引數，而且此引數會套用至管道中定義的所有步驟。如果未指定，則值預設為 `None`。如需範例 S3 KMS 金鑰組態，請參閱下列程式碼片段：
```
SchemaVersion: '1.0'
SageMaker:
PythonSDK:
Modules:
RemoteFunction:
S3KmsKeyId: 's3kmskeyid'
S3RootUri: 's3://amzn-s3-demo-bucket/my-project
```
# 最佳實務
以下各節建議在您針對管道步驟使用 `@step` 裝飾項目時要遵循的最佳實務。
## 使用暖集區
如需加快管道步驟的執行速度，請使用為訓練任務提供的暖集區功能。您可以將 `keep_alive_period_in_seconds` 引數提供給 `@step` 裝飾項目以開啟暖集區功能，如下列程式碼片段所示範：
```
@step(
keep_alive_period_in_seconds=900
)
```
如需有關暖集區的詳細資訊，請參閱 [SageMaker AI 受管暖集區](train-warm-pools.md)。
## 建構您的目錄
建議您在使用 `@step` 裝飾項目時使用程式碼模組。將您在其中調用步驟函式並定義管道的 `pipeline.py` 模組放在工作區的根目錄。建議的結構如下所示：
```
.
├── config.yaml # the configuration file that define the infra settings
├── requirements.txt # dependencies
├── pipeline.py # invoke @step-decorated functions and define the pipeline here
├── steps/
| ├── processing.py
| ├── train.py
├── data/
├── test/
```
# 限制
下列各節概述您在針對管道步驟中使用 `@step` 裝飾項目時應注意的限制。
## 函式引數限制
將輸入引數傳遞至 `@step` 裝飾函式時，適用下列限制：
+ 您可以將 `DelayedReturn`、`Properties` (其他類型的步驟)、`Parameter` 和 `ExecutionVariable` 物件傳遞至 `@step` 裝飾函式做為引數。但是 `@step` 裝飾函式不支援 `JsonGet` 和 `Join` 物件做為引數。
+ 您無法直接從 `@step` 函式存取管道變數。以下範例產生錯誤：
```
param = ParameterInteger(name="", default_value=10)
@step
def func():
print(param)
func() # this raises a SerializationError
```
+ 您無法將一個管道變數套疊另一個物件中，然後將其傳遞至 `@step` 函式。以下範例產生錯誤：
```
param = ParameterInteger(name="", default_value=10)
@step
def func(arg):
print(arg)
func(arg=(param,)) # this raises a SerializationError because param is nested in a tuple
```
+ 由於函式的輸入和輸出是序列化的，因此對可做為函數輸入或輸出傳遞的資料類型有限制。如需詳細資訊，請參閱[調用遠端函式](train-remote-decorator-invocation.md)的*資料序列化和還原序列化*一節。相同的限制適用於 `@step` 裝飾函式。
+ 任何具有 boto 用戶端的物件都無法序列化，因此您無法將這類物件做為輸入傳遞至 `@step` 裝飾函式，也無法將其做為此函式的輸出傳遞。例如，`Estimator`、`Predictor` 和 `Processor` 等 SageMaker Python SDK 用戶端類別無法序列化。
## 函式匯入
您應該在函式內匯入步驟所需的程式庫，而不是函數外。如果您在全域範圍內匯入它們，則在序列化函式時您會有發生匯入衝突的風險。例如，`sklearn.pipeline.Pipeline` 可被 `sagemaker.workflow.pipeline.Pipeline` 覆寫。
## 參考函式傳回值的子成員
如果您參考 `@step` 裝飾函式傳回值的子成員，則適用下列限制：
+ 如果 `DelayedReturn` 物件代表元組、清單或字典，您可以參考具有 `[]` 的子成員，如下列範例所示：
```
delayed_return[0]
delayed_return["a_key"]
delayed_return[1]["a_key"]
```
+ 您無法解壓縮元組或清單輸出，因為當您調用函式時，無法得知基礎元組或清單的確切長度。以下範例產生錯誤：
```
a, b, c = func() # this raises ValueError
```
+ 您無法逐一查看 `DelayedReturn` 物件。以下範例會引發錯誤：
```
for item in func(): # this raises a NotImplementedError
```
+ 您無法參考具有 '`.`' 的任意子成員。以下範例產生錯誤：
```
delayed_return.a_child # raises AttributeError
```
## 不支援的現有管道特徵
您無法使用 `@step` 裝飾項目搭配下列管道特徵：
+ [管道步驟快取](https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-caching.html)
+ [屬性檔案](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-propertyfile.html#build-and-manage-propertyfile-property)
# 在步驟之間傳遞資料
使用 Amazon SageMaker Pipelines 建置管道時，您可能需要將資料從某個步驟傳遞到下一個步驟。例如，您可能想要使用訓練步驟產生的模型成品，做為模型評估或部署步驟的輸入。您可以使用此功能來建立相互依賴的管道步驟，並建置 ML 工作流程。
當您需要從管道步驟的輸出擷取資訊時，您可以使用 `JsonGet`。`JsonGet` 可協助您從 Amazon S3 或屬性檔案中擷取資訊。下列各節說明您可以用來搭配 `JsonGet` 擷取步驟輸出的方法。
## 使用 Amazon S3 在步驟之間傳遞資料
您可以在 `JsonGet` 中使用 `ConditionStep`，直接從 Amazon S3 擷取 JSON 輸出。Amazon S3 URI 可以是包含基本字串、管道執行變數或管道參數的 `Std:Join` 函式。以下範例展示如何在 `ConditionStep` 中使用 `JsonGet`。
```
# Example json file in s3 bucket generated by a processing_step
{
"Output": [5, 10]
}
cond_lte = ConditionLessThanOrEqualTo(
left=JsonGet(
step_name="",
s3_uri="",
json_path="Output[1]"
),
right=6.0
)
```
如果您在條件步驟中使用 `JsonGet` 搭配 Amazon S3 路徑，則必須在條件步驟與產生 JSON 輸出的步驟之間明確新增相依性。在下列範例中，條件步驟是透過處理步驟上的相依性建立的：
```
cond_step = ConditionStep(
name="",
conditions=[cond_lte],
if_steps=[fail_step],
else_steps=[register_model_step],
depends_on=[processing_step],
)
```
## 使用屬性檔案在步驟之間傳遞資料
使用屬性檔案來存放處理步驟輸出中的資訊。這在分析處理步驟的結果以決定如何執行條件步驟時特別有用。`JsonGet` 函式會處理屬性檔案，並可讓您使用 JsonPath 表示法來查詢屬性 JSON 檔案。如需有關 JsonPath 符號的詳細資訊，請參閱 [JSONPath 回購](https://github.com/json-path/JsonPath)。
若要存放屬性檔案以供日後使用，您必須先建立使用下列格式的 `PropertyFile` 執行個體。`path` 參數是儲存屬性檔案的 JSON 檔案的名稱。所有 `output_name` 都必須符合您在處理步驟中定義的 `ProcessingOutput` 之 `output_name`。這可讓屬性檔案在步驟中擷取 `ProcessingOutput`。
```
from sagemaker.workflow.properties import PropertyFile
= PropertyFile(
name="",
output_name="",
path=""
)
```
建立 `ProcessingStep` 執行個體時，請新增 `property_files` 參數以列出 Amazon SageMaker Pipelines 服務必須為其編製索引的所有參數檔案。這將儲存屬性檔案以供日後使用。
```
property_files=[]
```
若要在條件步驟中使用屬性檔案，請將 `property_file` 新增至您傳遞至條件步驟的條件 (如下列範例所示)，以使用 `json_path` 參數查詢所需屬性的 JSON 檔案。
```
cond_lte = ConditionLessThanOrEqualTo(
left=JsonGet(
step_name=step_eval.name,
property_file=,
json_path="mse"
),
right=6.0
)
```
如需更深入的範例，請參閱 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 中的 [Property File](https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_building_pipeline.html#property-file)。**
# 快取管道步驟
在 Amazon SageMaker Pipelines 中，您可以使用步驟快取，在重新執行管道時節省時間和資源。當步驟具有相同的組態和輸入時，步驟快取會重複使用步驟先前成功執行後的輸出 (而不是重新計算)。這可協助您在具有相同參數的管道重新執行之間獲得一致的結果。下列主題說明如何為您的管道設定和開啟步驟快取。
當您使用步驟簽章快取時，Pipelines 會嘗試尋找先前執行的目前管道步驟，該步驟具有相同的特定屬性值。如果找到，Pipelines 會傳播先前執行的輸出，而不是重新計算步驟。核取的屬性是步驟類型特有的，會在 [依管道步驟類型的預設快取金鑰屬性](pipelines-default-keys.md) 中列出。
您必須選擇啟用步驟快取，該功能依預設處於關閉狀態。當您開啟步驟快取時，還必須定義逾時。此逾時定義間隔多久的先前執行仍可作為重新執行候選。
步驟快取只會考慮成功的執行，決不會重複使用失敗的執行。當逾時期間內存在多個成功的執行時，Pipelines 會使用最近一次成功執行的結果。如果逾時期間內沒有相符的成功執行，Pipelines 會重新執行該步驟。如果執行器找到符合條件之先前的執行，但該執行仍在進行，則這兩個步驟都會繼續執行並在成功時更新快取。
步驟快取的範圍僅限於個別管道，因此即使有步驟簽名相符，您也無法重複使用其他管道中的步驟。
步驟快取適用於下列步驟類型：
+ [處理](build-and-manage-steps-types.md#step-type-processing)
+ [培訓](build-and-manage-steps-types.md#step-type-training)
+ [調校](build-and-manage-steps-types.md#step-type-tuning)
+ [AutoML](build-and-manage-steps-types.md#step-type-automl)
+ [轉換](build-and-manage-steps-types.md#step-type-transform)
+ [`ClarifyCheck`](build-and-manage-steps-types.md#step-type-clarify-check)
+ [`QualityCheck`](build-and-manage-steps-types.md#step-type-quality-check)
+ [EMR](build-and-manage-steps-types.md#step-type-emr)
**Topics**
+ [開啟步驟快取](pipelines-caching-enabling.md)
+ [關閉步驟快取](pipelines-caching-disabling.md)
+ [依管道步驟類型的預設快取金鑰屬性](pipelines-default-keys.md)
+ [快取資料存取控制](pipelines-access-control.md)
# 開啟步驟快取
若要開啟步驟快取，您必須將 `CacheConfig` 屬性新增至步驟定義。`CacheConfig` 屬性會在管道定義檔案中使用以下格式：
```
{
"CacheConfig": {
"Enabled": false,
"ExpireAfter": "