本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 SageMaker AI 和 hydra 簡化從本機開發到可擴展實驗的機器學習工作流程
*David Sauerwein、Marco Geiger 和 Julian Ferdinand Grueber，Amazon Web Services*
## 摘要
此模式提供統一的方法，以設定和執行從本機測試到 Amazon SageMaker AI 生產的機器學習 (ML) 演算法。ML 演算法是此模式的重點，但其方法延伸到特徵工程、推論和整個 ML 管道。此模式示範透過範例使用案例，從本機指令碼開發轉換至 SageMaker AI 訓練任務。
典型的 ML 工作流程是在本機機器上開發和測試解決方案、在雲端執行大規模實驗 （例如，使用不同的參數），以及在雲端部署已核准的解決方案。然後，必須監控和維護部署的解決方案。如果沒有統一的工作流程方法，開發人員通常需要在每個階段重構程式碼。如果解決方案依賴於此工作流程的任何階段可能變更的大量參數，則保持組織和一致性可能會變得越來越困難。
此模式可解決這些挑戰。首先，它提供統一的工作流程，無論在本機機器、容器還是 SageMaker AI 上執行，都不需要在環境之間進行程式碼重構。其次，它透過 Hydra 的組態系統簡化參數管理，其中參數是在不同的組態檔案中定義，可輕鬆修改和合併，並自動記錄每個執行的組態。如需此模式如何處理這些挑戰的詳細資訊，請參閱[其他資訊](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-additional)。
## 先決條件和限制
**先決條件**
+ 作用中 AWS 帳戶
+ 部署和啟動 SageMaker AI 訓練任務的 AWS Identity and Access Management (IAM) [使用者角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)
+ AWS Command Line Interface (AWS CLI) 2.0 版或更新版本[已安裝](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)並[設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
+ 已安裝 [Poetry](https://python-poetry.org/) 1.8 版或更新版本，但早於 2.0 版
+ 已安裝 [Docker](https://www.docker.com/)
+ Python [3.10.x 版](https://www.python.org/downloads/release/python-31011/)
**限制**
+ 此程式碼目前僅鎖定 SageMaker AI 訓練任務。將其擴展到處理任務和整個 SageMaker AI 管道非常簡單。
+ 若要進行完全生產的 SageMaker AI 設定，必須備妥其他詳細資訊。範例可以是用於運算和儲存的自訂 AWS Key Management Service (AWS KMS) 金鑰，或聯網組態。您也可以在 `config` 資料夾的專用子資料夾中使用 hydra 來設定這些額外的選項。
+ 有些 AWS 服務 無法全部使用 AWS 區域。如需區域可用性，請參閱[AWS 依區域的服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。如需特定端點，請參閱[服務端點和配額](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)，然後選擇服務的連結。
## Architecture
下圖說明解決方案的架構。
該圖顯示以下工作流程：
1. 資料科學家可以在本機環境中以小規模迭代演算法、調整參數，以及快速測試訓練指令碼，而不需要 Docker 或 SageMaker AI。（如需詳細資訊，請參閱《[Epics](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-epics)》中的「在本機執行以進行快速測試」任務。)
1. 滿足演算法後，資料科學家會建置 Docker 映像並將其推送至名為 的 Amazon Elastic Container Registry (Amazon ECR) 儲存庫`hydra-sm-artifact`。（如需詳細資訊，請參閱《[Epics](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-epics)》中的「在 SageMaker AI 上執行工作流程」。)
1. 資料科學家使用 Python 指令碼啟動 SageMaker AI 訓練任務或超參數最佳化 (HPO) 任務。對於一般訓練任務，調整後的組態會寫入名為 的 Amazon Simple Storage Service (Amazon S3) 儲存貯體`hydra-sample-config`。對於 HPO 任務，會套用位於 `config` 資料夾中的預設組態集。
1. SageMaker AI 訓練任務會提取 Docker 映像、從 Amazon S3 儲存貯體 讀取輸入資料`hydra-sample-data`，以及從 Amazon S3 儲存貯體擷取組態`hydra-sample-config`或使用預設組態。訓練後，任務會將輸出資料儲存至 Amazon S3 儲存貯體 `hydra-sample-data`。
**自動化和擴展**
+ 對於自動訓練、重新訓練或推論，您可以將 AWS CLI 程式碼與 [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)、 [AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html)或 [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) 等服務整合。
+ 可以透過變更執行個體大小的組態或新增分散式訓練的組態來實現擴展。
## 工具
**AWS 服務**
+ [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) 可協助您設定 AWS 資源、快速且一致地佈建資源，以及在整個 AWS 帳戶 和 生命週期中管理資源 AWS 區域。
+ [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 是一種開放原始碼工具，可協助您 AWS 服務 透過命令列 shell 中的命令與 互動。對於此模式， AWS CLI 適用於初始資源組態和測試。
+ [Amazon Elastic Container Registry (Amazon ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) 是一種受管容器映像登錄服務，安全、可擴展且可靠。
+ [Amazon SageMaker AI](https://docs.aws.amazon.com/sagemaker/?id=docs_gateway) 是一種受管機器學習 (ML) 服務，可協助您建置和訓練 ML 模型，然後將模型部署到生產就緒的託管環境中。SageMaker AI Training 是 SageMaker AI 內的全受管 ML 服務，可大規模訓練 ML 模型。該工具可以有效地處理訓練模型的運算需求，利用內建的可擴展性和與其他模型的整合 AWS 服務。SageMaker AI Training 也支援自訂演算法和容器，因此可靈活用於各種 ML 工作流程。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) 是一種雲端型物件儲存服務，可協助您儲存、保護和擷取任何數量的資料。
**其他工具**
+ [Docker](https://www.docker.com/) 是一組平台即服務 (PaaS) 產品，可在作業系統層級使用虛擬化在容器中交付軟體。它用於此模式，以確保從開發到部署，以及可靠地封裝相依性和程式碼等各種階段的環境一致。允許 Docker 的容器化，以便在整個工作流程中輕鬆擴展和控制版本。
+ [Hydra](https://hydra.cc/) 是一種組態管理工具，可為處理多個組態和動態資源管理提供彈性。它有助於管理環境組態，允許在不同環境中無縫部署。如需 Hydra 的詳細資訊，請參閱[其他資訊](#streamline-machine-learning-workflows-by-using-amazon-sagemaker-additional)。
+ [Python](https://www.python.org/) 是一種一般用途的電腦程式設計語言。Python 用於撰寫 ML 程式碼和部署工作流程。
+ [Poetry](https://python-poetry.org/) 是一種在 Python 中管理相依性和封裝的工具。
**程式碼儲存庫**
此模式的程式碼可在 GitHub [configuring-sagemaker-training-jobs-with-hydra](https://github.com/aws-samples/configuring-sagemaker-training-jobs-with-hydra) 儲存庫中使用。
## 最佳實務
+ 選擇 IAM 角色以部署和啟動遵循最低權限原則的 SageMaker AI 訓練任務，並授予執行任務所需的最低許可。如需詳細資訊，請參閱 IAM 文件中的[授予最低權限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#grant-least-priv)和[安全最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
+ 使用暫時登入資料來存取終端機中的 IAM 角色。
## 史詩
### 設定環境
| 任務 | Description | 所需的技能 |
| --- | --- | --- |
| 建立和啟用虛擬環境。 | 若要建立和啟用虛擬環境，請在儲存庫的根目錄中執行下列命令：poetry install
poetry shell
| 一般 AWS |
| 部署基礎設施。 | 若要使用 CloudFormation 部署基礎設施，請執行下列命令：aws cloudformation deploy --template-file infra/hydra-sagemaker-setup.yaml --stack-name hydra-sagemaker-setup --capabilities CAPABILITY_NAMED_IAM
| 一般 AWS，DevOps 工程師 |
| 下載範例資料。 | 若要將輸入資料從 [openml](https://www.openml.org/) 下載到本機電腦，請執行下列命令：python scripts/download_data.py
| 一般 AWS |
| 在本機執行 以進行快速測試。 | 若要在本機執行訓練程式碼進行測試，請執行下列命令：python mypackage/train.py data.train_data_path=data/train.csv evaluation.base_dir_path=data
所有執行的日誌會依執行時間儲存在名為 的資料夾中`outputs`。如需詳細資訊，請參閱 [GitHub 儲存庫](https://github.com/aws-samples/configuring-sagemaker-training-jobs-with-hydra)中的「輸出」一節。
您也可以使用 `--multirun`功能，以不同的參數平行執行多個訓練。如需詳細資訊，請參閱 [Hydra 文件](https://hydra.cc/docs/tutorials/basic/running_your_app/multi-run/)。 | 資料科學家 |
### 在 SageMaker AI 上執行工作流程
| 任務 | Description | 所需的技能 |
| --- | --- | --- |
| 設定環境變數。 | 若要在 SageMaker AI 上執行任務，請設定下列環境變數，並提供您的 AWS 區域 和 AWS 帳戶 ID：export ECR_REPO_NAME=hydra-sm-artifact
export image_tag=latest
export AWS_REGION="" # for instance, us-east-1
export ACCOUNT_ID=""
export BUCKET_NAME_DATA=hydra-sample-data-$ACCOUNT_ID
export BUCKET_NAME_CONFIG=hydra-sample-config-$ACCOUNT_ID
export AWS_DEFAULT_REGION=$AWS_REGION
export ROLE_ARN=arn:aws:iam::${ACCOUNT_ID}:role/hydra-sample-sagemaker
export INPUT_DATA_S3_PATH=s3://$BUCKET_NAME_DATA/hydra-on-sm/input/
export OUTPUT_DATA_S3_PATH=s3://$BUCKET_NAME_DATA/hydra-on-sm/output/
| 一般 AWS |
| 建立並推送 Docker 映像。 | 若要建立 Docker 映像並將其推送至 Amazon ECR 儲存庫，請執行下列命令：chmod +x scripts/create_and_push_image.sh
scripts/create_and_push_image.sh $ECR_REPO_NAME $image_tag $AWS_REGION $ACCOUNT_ID
此任務假設您在環境中擁有有效的登入資料。Docker 映像會推送到先前任務中環境變數中指定的 Amazon ECR 儲存庫，並用於啟用訓練任務將在其中執行的 SageMaker AI 容器。 | ML 工程師，一般 AWS |
| 將輸入資料複製到 Amazon S3。 | SageMaker AI 訓練任務需要接收輸入資料。若要將輸入資料複製到 Amazon S3 儲存貯體以取得資料，請執行下列命令：aws s3 cp data/train.csv "${INPUT_DATA_S3_PATH}train.csv" | 資料工程師，一般 AWS |
| 提交 SageMaker AI 訓練任務。 | 若要簡化指令碼的執行，請在 `default.yaml` 檔案中指定預設組態參數。除了確保跨執行的一致性之外，此方法還提供視需要輕鬆覆寫預設設定的彈性。請參閱下列範例：python scripts/start_sagemaker_training_job.py sagemaker.role_arn=$ROLE_ARN sagemaker.config_s3_bucket=$BUCKET_NAME_CONFIG sagemaker.input_data_s3_path=$INPUT_DATA_S3_PATH sagemaker.output_data_s3_path=$OUTPUT_DATA_S3_PATH
| 一般 AWS、ML 工程師、資料科學家 |
| 執行 SageMaker AI 超參數調校。 | 執行 SageMaker AI 超參數調校類似於提交 SageMaker AII 訓練任務。不過，執行指令碼在一些重要方面有所不同，如您在 [start\_sagemaker\_hpo\_job.py](https://github.com/aws-samples/configuring-sagemaker-training-jobs-with-hydra/blob/main/scripts/start_sagemaker_hpo_job.py) 檔案中所見。要調校的超參數必須透過 boto3 承載傳遞，而不是訓練任務的通道。
若要啟動超參數最佳化 (HPO) 任務，請執行下列命令：python scripts/start_sagemaker_hpo_job.py sagemaker.role_arn=$ROLE_ARN sagemaker.config_s3_bucket=$BUCKET_NAME_CONFIG sagemaker.input_data_s3_path=$INPUT_DATA_S3_PATH sagemaker.output_data_s3_path=$OUTPUT_DATA_S3_PATH
| 資料科學家 |
## 疑難排解
| 問題 | 解決方案 |
| --- | --- |
| 權杖過期 | 匯出新的 AWS 登入資料。 |
| 缺少 IAM 許可 | 請務必匯出具備所有必要 IAM 許可的 IAM 角色憑證，以部署 CloudFormation 範本並啟動 SageMaker AI 訓練任務。 |
## 相關資源
+ [使用 Amazon SageMaker AI 訓練模型](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html) (AWS 文件）
+ [什麼是超參數調校？](https://aws.amazon.com/what-is/hyperparameter-tuning/#:~:text=Hyperparameter%20tuning%20allows%20data%20scientists,the%20model%20as%20a%20hyperparameter.)
## 其他資訊
此模式可解決下列挑戰：
**從本機開發到大規模部署的一致性** – 透過此模式，開發人員可以使用相同的工作流程，無論他們是使用本機 Python 指令碼、執行本機 Docker 容器、在 SageMaker AI 上執行大型實驗，還是在 SageMaker AI 的生產環境中部署。由於下列原因，此一致性很重要：
+ **更快速的反覆運算** – 它允許快速的本機實驗，而不需要在擴展時進行重大調整。
+ **不重構** – 在 SageMaker AI 上轉換到更大的實驗是無縫的，不需要對現有設定進行大修。
+ **持續改進** – 開發新功能並持續改進演算法非常簡單，因為程式碼在環境中保持不變。
**組態管理** – 此模式使用組態管理工具 [hydra](https://hydra.cc/) 來提供下列優點：
+ 參數是在組態檔案中定義，與程式碼分開。
+ 您可以輕鬆交換或組合不同的參數集。
+ 實驗追蹤會簡化，因為每個執行的組態都會自動記錄。
+ 雲端實驗可以使用與本機執行相同的組態結構，以確保一致性。
使用 Hydra，您可以有效管理組態，啟用下列功能：
+ **分割組態** – 將您的專案組態分成可獨立修改的較小、可管理的部分。這種方法可讓您更輕鬆地處理複雜的專案。
+ **輕鬆調整預設值** – 快速變更基準組態，讓您更輕鬆地測試新想法。
+ **對齊 CLI 輸入和組態檔案** – 順暢地將命令列輸入與您的組態檔案合併。這種方法可減少雜亂和混淆，讓您的專案隨著時間更易於管理。