本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 SageMaker AI Python SDK 建立筆記本任務範例
若要使用 SageMaker Python SDK 執行獨立筆記本，您需要建立筆記本任務步驟、將其連接至管道，並使用 Pipelines 提供的公用程式來隨需執行任務，或選擇性地排程一或多個未來任務。下列各節描述建立隨需或排程筆記本任務並追蹤執行的基本步驟。此外，如果您需要將參數傳遞至筆記本任務或連線到筆記本中的 Amazon EMR，請參閱下列討論 - 在這些情況下，需要額外準備 Jupyter 筆記本。您也可以套用 `NotebookJobStep` 引數子集的預設值，以便您不必在每次建立筆記本任務步驟時指定這些引數。
若要檢視示範如何使用 SageMaker AI Python SDK 排程筆記本工作的範例筆記本，請參閱[筆記本工作範例筆記本](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker-pipelines/notebook-job-step)。
**Topics**
+ [建立筆記本任務的步驟](#create-notebook-auto-run-overall)
+ [在 Studio UI 儀表板中檢視您的筆記本任務](#create-notebook-auto-run-dash)
+ [在 Studio 中檢視您的管道圖](#create-notebook-auto-run-graph)
+ [將參數傳遞到您的筆記本](#create-notebook-auto-run-passparam)
+ [在您的輸入筆記本中連線至 Amazon EMR 叢集](#create-notebook-auto-run-emr)
+ [設定預設選項](#create-notebook-auto-run-intdefaults)
## 建立筆記本任務的步驟
您可以建立一個立即執行或依排程執行的筆記本任務。下列指示描述這兩種方法。
**若要排程筆記本任務，請完成下列步驟：**
1. 建立 `NotebookJobStep` 執行個體。如需 `NotebookJobStep` 參數的詳細資訊，請參閱 [sagemaker.workflow.steps.NotebookJobStep](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.notebook_job_step.NotebookJobStep)。至少，您可以提供下列引數，如下列程式碼片段所示：
**重要**
如果您使用 SageMaker Python SDK 排程筆記本任務，您只能指定特定映像來執行筆記本任務。如需詳細資訊，請參閱[SageMaker AI Python SDK 筆記本任務的映像限制條件](notebook-auto-run-constraints.md#notebook-auto-run-constraints-image-sdk)。
```
notebook_job_step = NotebookJobStep(
input_notebook=input-notebook,
image_uri=image-uri,
kernel_name=kernel-name
)
```
1. 使用 `NotebookJobStep` 做為單一步驟建立管道，如下列程式碼片段所示：
```
pipeline = Pipeline(
name=pipeline-name,
steps=[notebook_job_step],
sagemaker_session=sagemaker-session,
)
```
1. 隨需執行管道，或選擇性地排程未來的管道執行。若要啟動立即執行，請使用下列命令：
```
execution = pipeline.start(
parameters={...}
)
```
或者，您可以按預定間隔排程單一未來管道執行或多個執行。您可以在 `PipelineSchedule` 中指定排程，然後使用 `put_triggers` 將排程物件傳遞至管道。如需管道排程的詳細資訊，請參閱[使用 SageMaker Python SDK 排程管道](pipeline-eventbridge.md#build-and-manage-scheduling)。
下列範例排程您的管道在 2023 年 12 月 12 日 10:31:32 UTC 執行一次。
```
my_schedule = PipelineSchedule(
name="my-schedule“,
at=datetime(year=2023, month=12, date=25, hour=10, minute=31, second=32)
)
pipeline.put_triggers(triggers=[my_schedule])
```
以下範例排程您的管道在 2022 年至 2023 年每個月的最後一個星期五上午 10:15 UTC 執行。如需 Cron 型排程的詳細資訊，請參閱 [Cron 型排程](https://docs.aws.amazon.com/scheduler/latest/UserGuide/schedule-types.html#cron-based)。
```
my_schedule = PipelineSchedule(
name="my-schedule“,
cron="15 10 ? * 6L 2022-2023"
)
pipeline.put_triggers(triggers=[my_schedule])
```
1. (選用) 在 SageMaker 筆記本任務儀表板中檢視您的筆記本任務。您為筆記本任務步驟的 `tags` 引數提供的值會控制 Studio UI 擷取和顯示任務的方式。如需詳細資訊，請參閱[在 Studio UI 儀表板中檢視您的筆記本任務](#create-notebook-auto-run-dash)。
## 在 Studio UI 儀表板中檢視您的筆記本任務
如果您指定特定標籤，做為管道步驟建立的筆記本任務會出現在 Studio Notebook 任務儀表板中。
**注意**
只有 Studio 或本機 JupyterLab 環境中建立的筆記本工作才會建立工作定義。因此，如果您使用 SageMaker Python SDK 建立筆記本任務，則不會在筆記本任務儀表板中看到任務定義。不過，您可以檢視筆記本任務，如[檢視筆記本任務](view-notebook-jobs.md)中所述。
您可以使用下列標籤控制哪些團隊成員可以檢視您的筆記本任務：
+ 若要將筆記本顯示給網域中的所有使用者設定檔或[空間](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-jl-user-guide.html)，請使用您的網域名稱新增網域標籤。範例顯示如下：
+ 金鑰：`sagemaker:domain-name`、值：`d-abcdefghij5k`
+ 若要將筆記本任務顯示給網域中的特定使用者設定檔，請同時新增使用者設定檔和網域標籤。使用者設定檔標籤的範例如下所示：
+ 金鑰：`sagemaker:user-profile-name`、值：`studio-user`
+ 若要將筆記本任務顯示給[空間](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-jl-user-guide.html)，請同時新增空間和網域標籤。空間標籤的範例如下所示：
+ 金鑰：`sagemaker:shared-space-name`、值：`my-space-name`
+ 如果您未連接任何網域或使用者設定檔或空間標籤，則 Studio UI 不會顯示管道步驟建立的筆記本任務。在這種情況下，您可以在訓練任務主控台中檢視基礎訓練任務，也可以在[管道執行清單](https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-studio-view-execution.html)中檢視狀態。
一旦您設定必要的標籤以在儀表板中檢視任務，請參閱[檢視筆記本任務](view-notebook-jobs.md)以取得如何檢視任務和下載輸出的指示。
## 在 Studio 中檢視您的管道圖
由於您的筆記本任務步驟是管道的一部分，因此您可以在 Studio 中檢視管道圖 (DAG)。在管道圖中，您可以檢視管道執行的狀態並追蹤歷程。如需詳細資訊，請參閱[檢視管道執行的詳細資訊](pipelines-studio-view-execution.md)。
## 將參數傳遞到您的筆記本
如果您想要將參數傳遞至您的筆記本任務 (使用 `NotebookJobStep` 的 `parameters` 引數)，您需要準備輸入筆記本來接收參數。
Papermill 型筆記本任務執行器會搜尋標記有 `parameters` 標籤的 Jupyter 儲存格，並在此儲存格之後立即套用新參數或參數覆寫。如需詳細資訊，請參閱[對筆記本進行參數化](notebook-auto-run-troubleshoot-override.md)。
一旦您執行了此步驟，請將參數傳遞至 `NotebookJobStep`，如下列範例所示：
```
notebook_job_parameters = {
"company": "Amazon"
}
notebook_job_step = NotebookJobStep(
image_uri=image-uri,
kernel_name=kernel-name,
role=role-name,
input_notebook=input-notebook,
parameters=notebook_job_parameters,
...
)
```
## 在您的輸入筆記本中連線至 Amazon EMR 叢集
如果您從 Studio 中的 Jupyter 筆記本連線至 Amazon EMR 叢集，您可能需要進一步修改 Jupyter 筆記本。請查看[從您的筆記本連線至 Amazon EMR 叢集](scheduled-notebook-connect-emr.md)，您是否需要在筆記本中執行下列任何任務：
+ **將參數傳遞到您的 Amazon EMR 連線命令。**Studio 使用 Papermill 執行筆記本。在 SparkMagic 核心中，由於 Papermill 傳遞資訊至 SparkMagic 的方式，因此您傳遞至 Amazon EMR 連線命令的參數可能無法如預期運作。
+ **將使用者憑證傳遞至經過 Kerberos、LDAP 或 HTTP 基本身分驗證的 Amazon EMR 叢集**。您必須透過 AWS Secrets Manager傳遞使用者憑證。
## 設定預設選項
SageMaker SDK 可讓您選擇為參數子集設定預設值，以便您不必在每次建立 `NotebookJobStep` 執行個體時指定這些參數。這些參數為 `role`、`s3_root_uri`、`s3_kms_key`、`volume_kms_key`、`subnets` 和 `security_group_ids`。使用 SageMaker AI 組態檔案來設定步驟的預設值。如需 SageMaker AI 組態檔案的詳細資訊，請參閱[搭配 SageMaker Python SDK 設定和使用預設值](https://sagemaker.readthedocs.io/en/stable/overview.html#configuring-and-using-defaults-with-the-sagemaker-python-sdk)。
若要設定筆記本任務預設值，請將新的預設值套用至組態檔案的筆記本任務區段，如下列程式碼片段所示：
```
SageMaker:
PythonSDK:
Modules:
NotebookJob:
RoleArn: 'arn:aws:iam::555555555555:role/IMRole'
S3RootUri: 's3://amzn-s3-demo-bucket/my-project'
S3KmsKeyId: 's3kmskeyid'
VolumeKmsKeyId: 'volumekmskeyid1'
VpcConfig:
SecurityGroupIds:
- 'sg123'
Subnets:
- 'subnet-1234'
```