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

# 使用 SageMaker Training Compiler 執行 PyTorch 訓練任務
<a name="training-compiler-enable-pytorch"></a>

您可以使用任何 SageMaker AI 介面，透過 SageMaker Training Compiler 執行訓練任務：Amazon SageMaker Studio Classic 適用於 Python (Boto3) 的 AWS SDK、Amazon SageMaker 筆記本執行個體，以及 AWS Command Line Interface。

**Topics**
+ [使用 SageMaker Python SDK](#training-compiler-enable-pytorch-pysdk)
+ [使用 SageMaker AI `CreateTrainingJob` API 作業](#training-compiler-enable-pytorch-api)

## 使用 SageMaker Python SDK
<a name="training-compiler-enable-pytorch-pysdk"></a>

適用於 PyTorch 的 SageMaker Training Compiler 可透過 SageMaker AI [https://sagemaker.readthedocs.io/en/stable/frameworks/pytorch/sagemaker.pytorch.html](https://sagemaker.readthedocs.io/en/stable/frameworks/pytorch/sagemaker.pytorch.html) 和 [https://sagemaker.readthedocs.io/en/stable/frameworks/huggingface/sagemaker.huggingface.html#hugging-face-estimator](https://sagemaker.readthedocs.io/en/stable/frameworks/huggingface/sagemaker.huggingface.html#hugging-face-estimator) 架構估算器類別取得。若要開啟 SageMaker Training Compiler，請將 `compiler_config` 參數新增至 SageMaker AI 估計器。匯入 `TrainingCompilerConfig` 類別並將其執行個體傳遞至 `compiler_config` 參數。下列程式碼範例顯示已開啟 SageMaker Training Compiler 的 SageMaker AI 估算器類別結構。

**提示**  
如要開始使用 PyTorch 或轉換器提供的預建置模型，請嘗試使用 [測試過的模型](training-compiler-support.md#training-compiler-tested-models) 參考表中提供的批次大小。

**注意**  
原生 PyTorch 支援可在 SageMaker Python SDK 版本 2.121.0 及較新版本中取得。請確認您已就此更新 SageMaker Python SDK。

**注意**  
從 PyTorch 版本 1.12.0 開始，可以使用適用於 PyTorch 的 SageMaker Training Compiler 容器。請注意，適用於 PyTorch 的 SageMaker Training Compiler 容器不會與 Hugging Face 轉換器一起預先包裝。如需在容器中安裝程式庫，請務必在提交訓練任務時將 `requirements.txt` 檔案新增至來源目錄下。  
對於 PyTorch 版本 1.11.0 和之前的版本，請針對 Hugging Face 和 PyTorch 使用先前版本的 SageMaker Training Compiler 容器。  
如需架構版本和相應容器資訊的完整清單，請參閱[支援的架構](training-compiler-support.md#training-compiler-supported-frameworks)。

如需符合您使用案例的資訊，請參閱下列其中一個選項。

### 適用於單一 GPU 訓練
<a name="training-compiler-estimator-pytorch-single"></a>

------
#### [ PyTorch v1.12.0 and later ]

若要編譯和訓練 PyTorch 模型，請使用 SageMaker Training Compiler 來設定 SageMaker AI PyTorch 估算器，如下列程式碼範例所示。

**注意**  
此原生 PyTorch 支援可在 SageMaker AI Python SDK 版本 2.120.0 及較新版本中使用。請確認您已更新 SageMaker AI Python SDK。

```
from sagemaker.pytorch import PyTorch, TrainingCompilerConfig

# the original max batch size that can fit into GPU memory without compiler
batch_size_native=12
learning_rate_native=float('5e-5')

# an updated max batch size that can fit into GPU memory with compiler
batch_size=64

# update learning rate
learning_rate=learning_rate_native/batch_size_native*batch_size

hyperparameters={
    "n_gpus": 1,
    "batch_size": batch_size,
    "learning_rate": learning_rate
}

pytorch_estimator=PyTorch(
    entry_point='train.py',
    source_dir='path-to-requirements-file', # Optional. Add this if need to install additional packages.
    instance_count=1,
    instance_type='ml.p3.2xlarge',
    framework_version='1.13.1',
    py_version='py3',
    hyperparameters=hyperparameters,
    compiler_config=TrainingCompilerConfig(),
    disable_profiler=True,
    debugger_hook_config=False
)

pytorch_estimator.fit()
```

------
#### [ Hugging Face Transformers with PyTorch v1.11.0 and before ]

若要透過 PyTorch 編譯和訓練變壓器模型，請使用 SageMaker Training Compiler 來設定 SageMaker AI Hugging Face 估算器，如下列程式碼範例所示。

```
from sagemaker.huggingface import HuggingFace, TrainingCompilerConfig

# the original max batch size that can fit into GPU memory without compiler
batch_size_native=12
learning_rate_native=float('5e-5')

# an updated max batch size that can fit into GPU memory with compiler
batch_size=64

# update learning rate
learning_rate=learning_rate_native/batch_size_native*batch_size

hyperparameters={
    "n_gpus": 1,
    "batch_size": batch_size,
    "learning_rate": learning_rate
}

pytorch_huggingface_estimator=HuggingFace(
    entry_point='train.py',
    instance_count=1,
    instance_type='ml.p3.2xlarge',
    transformers_version='4.21.1',
    pytorch_version='1.11.0',
    hyperparameters=hyperparameters,
    compiler_config=TrainingCompilerConfig(),
    disable_profiler=True,
    debugger_hook_config=False
)

pytorch_huggingface_estimator.fit()
```

如需準備訓練指令碼的說明，請參閱下列頁面。
+ 使用 Hugging Face 轉換器的[訓練器 API](https://huggingface.co/docs/transformers/main_classes/trainer) 的 [適用於單一 GPU 訓練](training-compiler-pytorch-models.md#training-compiler-pytorch-models-transformers-trainer-single-gpu) PyTorch 模型
+ 未使用 Hugging Face 轉換器的[訓練器 API](https://huggingface.co/transformers/main_classes/trainer.html) 的 [適用於單一 GPU 訓練](training-compiler-pytorch-models.md#training-compiler-pytorch-models-non-trainer-single-gpu) PyTorch 模型

如需端對端範例，請參閱下列筆記本：
+ [使用 SQuAD 資料集編譯和訓練 Hugging Face 轉換器訓練器模型以進行問答](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_single_gpu_single_node/albert-base-v2/albert-base-v2.html) 
+ [透過 SageMaker Training Compiler，使用 SST 資料集編譯和訓練 Hugging Face 轉換器 `BERT` 模型](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_single_gpu_single_node/bert-base-cased/bert-base-cased-single-node-single-gpu.html) 
+ [使用適用於單一節點單一 GPU 訓練的 SST2 資料集，編譯和訓練二進制分類訓練器模型](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_single_gpu_single_node/roberta-base/roberta-base.html)

------

### 分散式訓練
<a name="training-compiler-estimator-pytorch-distributed"></a>

------
#### [ PyTorch v1.12 ]

針對 PyTorch 版本 1.12，您可以將指定的 `pytorch_xla` 選項新增至 SageMaker AI PyTorch 估計器類別的 `distribution` 參數，藉此使用 SageMaker Training Compiler 執行分散式訓練。

**注意**  
此原生 PyTorch 支援可在 SageMaker AI Python SDK 版本 2.121.0 及較新版本中使用。請確認您已更新 SageMaker AI Python SDK。

```
from sagemaker.pytorch import PyTorch, TrainingCompilerConfig

# choose an instance type, specify the number of instances you want to use,
# and set the num_gpus variable the number of GPUs per instance.
instance_count=1
instance_type='ml.p3.8xlarge'
num_gpus=4

# the original max batch size that can fit to GPU memory without compiler
batch_size_native=16
learning_rate_native=float('5e-5')

# an updated max batch size that can fit to GPU memory with compiler
batch_size=26

# update learning rate
learning_rate=learning_rate_native/batch_size_native*batch_size*num_gpus*instance_count

hyperparameters={
    "n_gpus": num_gpus,
    "batch_size": batch_size,
    "learning_rate": learning_rate
}

pytorch_estimator=PyTorch(
    entry_point='your_training_script.py',
    source_dir='path-to-requirements-file', # Optional. Add this if need to install additional packages.
    instance_count=instance_count,
    instance_type=instance_type,
    framework_version='1.13.1',
    py_version='py3',
    hyperparameters=hyperparameters,
    compiler_config=TrainingCompilerConfig(),
    distribution ={'pytorchxla' : { 'enabled': True }},
    disable_profiler=True,
    debugger_hook_config=False
)

pytorch_estimator.fit()
```

**提示**  
若要準備訓練指令碼，請參閱[PyTorch](training-compiler-pytorch-models.md)

------
#### [ Transformers v4.21 with PyTorch v1.11 ]

對於 PyTorch 版本 1.11 及較新版本，SageMaker Training Compiler 可用於使用指定給 `distribution` 參數的 `pytorch_xla` 選項進行分散式訓練。

```
from sagemaker.huggingface import HuggingFace, TrainingCompilerConfig

# choose an instance type, specify the number of instances you want to use,
# and set the num_gpus variable the number of GPUs per instance.
instance_count=1
instance_type='ml.p3.8xlarge'
num_gpus=4

# the original max batch size that can fit to GPU memory without compiler
batch_size_native=16
learning_rate_native=float('5e-5')

# an updated max batch size that can fit to GPU memory with compiler
batch_size=26

# update learning rate
learning_rate=learning_rate_native/batch_size_native*batch_size*num_gpus*instance_count

hyperparameters={
    "n_gpus": num_gpus,
    "batch_size": batch_size,
    "learning_rate": learning_rate
}

pytorch_huggingface_estimator=HuggingFace(
    entry_point='your_training_script.py',
    instance_count=instance_count,
    instance_type=instance_type,
    transformers_version='4.21.1',
    pytorch_version='1.11.0',
    hyperparameters=hyperparameters,
    compiler_config=TrainingCompilerConfig(),
    distribution ={'pytorchxla' : { 'enabled': True }},
    disable_profiler=True,
    debugger_hook_config=False
)

pytorch_huggingface_estimator.fit()
```

**提示**  
如需準備訓練指令碼的說明，請參閱下列頁面。  
使用 Hugging Face 轉換器的[訓練器 API](https://huggingface.co/transformers/main_classes/trainer.html) 的 [適用於分散式訓練](training-compiler-pytorch-models.md#training-compiler-pytorch-models-transformers-trainer-distributed) PyTorch 模型
未使用 Hugging Face 轉換器的[訓練器 API](https://huggingface.co/transformers/main_classes/trainer.html) 的 [適用於分散式訓練](training-compiler-pytorch-models.md#training-compiler-pytorch-models-non-trainer-distributed) PyTorch 模型

------
#### [ Transformers v4.17 with PyTorch v1.10.2 and before ]

對於支援的 PyTorch 版本 1.10.2 及之前版本，SageMaker Training Compiler 需要一個替代機制來啟動分散式訓練任務。若要執行分散式訓練，SageMaker Training Compiler 會要求您將 SageMaker AI 分散式訓練啟動器指令碼傳遞至 `entry_point` 引數，並將訓練指令碼傳遞至 `hyperparameters` 引數。下列程式碼範例示範如何套用所需變更，來設定 SageMaker AI Hugging Face 估算器。

```
from sagemaker.huggingface import HuggingFace, TrainingCompilerConfig

# choose an instance type, specify the number of instances you want to use,
# and set the num_gpus variable the number of GPUs per instance.
instance_count=1
instance_type='ml.p3.8xlarge'
num_gpus=4

# the original max batch size that can fit to GPU memory without compiler
batch_size_native=16
learning_rate_native=float('5e-5')

# an updated max batch size that can fit to GPU memory with compiler
batch_size=26

# update learning rate
learning_rate=learning_rate_native/batch_size_native*batch_size*num_gpus*instance_count

training_script="your_training_script.py"

hyperparameters={
    "n_gpus": num_gpus,
    "batch_size": batch_size,
    "learning_rate": learning_rate,
    "training_script": training_script     # Specify the file name of your training script.
}

pytorch_huggingface_estimator=HuggingFace(
    entry_point='distributed_training_launcher.py',    # Specify the distributed training launcher script.
    instance_count=instance_count,
    instance_type=instance_type,
    transformers_version='4.17.0',
    pytorch_version='1.10.2',
    hyperparameters=hyperparameters,
    compiler_config=TrainingCompilerConfig(),
    disable_profiler=True,
    debugger_hook_config=False
)

pytorch_huggingface_estimator.fit()
```

啟動器指令碼看起來應該如下所示。它會封裝您的訓練指令碼，並根據您所選的訓練執行個體大小來設定分散式訓練環境。

```
# distributed_training_launcher.py

#!/bin/python

import subprocess
import sys

if __name__ == "__main__":
    arguments_command = " ".join([arg for arg in sys.argv[1:]])
    """
    The following line takes care of setting up an inter-node communication
    as well as managing intra-node workers for each GPU.
    """
    subprocess.check_call("python -m torch_xla.distributed.sm_dist " + arguments_command, shell=True)
```

**提示**  
如需準備訓練指令碼的說明，請參閱下列頁面。  
使用 Hugging Face 轉換器的[訓練器 API](https://huggingface.co/transformers/main_classes/trainer.html) 的 [適用於分散式訓練](training-compiler-pytorch-models.md#training-compiler-pytorch-models-transformers-trainer-distributed) PyTorch 模型
未使用 Hugging Face 轉換器的[訓練器 API](https://huggingface.co/transformers/main_classes/trainer.html) 的 [適用於分散式訓練](training-compiler-pytorch-models.md#training-compiler-pytorch-models-non-trainer-distributed) PyTorch 模型

**提示**  
如需端對端範例，請參閱下列筆記本：  
[編譯和訓練 GPT2 模型，使用轉換器訓練器 API 搭配 SST2 資料集進行單一節點多重 GPU 訓練](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_multiple_gpu_single_node/language-modeling-multi-gpu-single-node.html)
[編譯和訓練 GPT2 模型，使用轉換器訓練器 API 搭配 SST2 資料集進行多節點多重 GPU 訓練](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_multiple_gpu_multiple_node/language-modeling-multi-gpu-multi-node.html)

------

下列清單是使用編譯器執行 SageMaker 訓練任務所需的最小參數集。

**注意**  
使用 SageMaker AI Hugging Face 估算器時，您必須指定 `transformers_version`、`pytorch_version`、`hyperparameters` 和 `compiler_config` 參數，以啟用 SageMaker Training Compiler。您無法使用 `image_uri` 手動指定列於 [支援的架構](training-compiler-support.md#training-compiler-supported-frameworks) 的 Training Compiler 整合式深度學習容器。
+ `entry_point` (str) — 必要條件。指定訓練指令碼的檔案名稱。
**注意**  
若要使用 SageMaker Training Compiler 和 PyTorch 版本 1.10.2 及之前版本執行分散式訓練，請為此參數指定啟動器指令碼的檔案名稱。您應準備好啟動器指令碼，以包裝您的訓練指令碼並配置分散式訓練環境。如需詳細資訊，請參閱下列範例筆記本：  
[編譯和訓練 GPT2 模型，使用轉換器訓練器 API 搭配 SST2 資料集進行單一節點多重 GPU 訓練](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_multiple_gpu_single_node/language-modeling-multi-gpu-single-node.html)
[編譯和訓練 GPT2 模型，使用轉換器訓練器 API 搭配 SST2 資料集進行多節點多重 GPU 訓練](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-training-compiler/huggingface/pytorch_multiple_gpu_multiple_node/language-modeling-multi-gpu-multi-node.html)
+ `source_dir` (str) — 選用。如需安裝其他套件，請新增此項目。如要安裝套件，您需要在此目錄下備妥一個 `requirements.txt` 檔案。
+ `instance_count` (int) — 必要條件。指定執行個體數目。
+ `instance_type` (str) — 必要條件。指定執行個體類型。
+ `transformers_version` (str) — 僅在使用 SageMaker AI Hugging Face 估算器時才需使用。指定 SageMaker Training Compiler 支援的 Hugging Face 轉換器程式庫版本。若要尋找可用版本，請參閱[支援的架構](training-compiler-support.md#training-compiler-supported-frameworks)。
+ `framework_version` 或 `pytorch_version` (str) — 必要條件。指定 SageMaker Training Compiler 支援的 PyTorch 版本。若要尋找可用版本，請參閱[支援的架構](training-compiler-support.md#training-compiler-supported-frameworks)。
**注意**  
使用 SageMaker AI Hugging Face 估算器時，您必須同時指定 `transformers_version` 和 `pytorch_version`。
+ `hyperparameters` (dict) — 選用。指定訓練任務的超參數，例如 `n_gpus`、`batch_size` 和 `learning_rate`。啟用 SageMaker Training Compiler 時，請嘗試較大的批次大小並相應地調整學習速率。若要尋找使用編譯器和調整批次大小以改善訓練速度的案例研究，請參閱[測試過的模型](training-compiler-support.md#training-compiler-tested-models)和[SageMaker Training Compiler 範例筆記本與部落格](training-compiler-examples-and-blogs.md)。
**注意**  
若要使用 SageMaker Training Compiler 和 PyTorch 版本 1.10.2 及之前版本執行分散式訓練，您需要新增其他參數 (`"training_script"`)，以指定訓練指令碼，如前面的程式碼範例所示。
+ `compiler_config` (TrainingCompilerConfig 物件) — 啟動 SageMaker Training Compiler 時所需。納入此參數，以開啟 SageMaker Training Compiler。下列是 `TrainingCompilerConfig` 類型的參數。
  + `enabled` (bool) – 選用。指定 `True` 或 `False` 以開啟或關閉 SageMaker Training Compiler。預設值為 `True`。
  + `debug` (bool) – 選用。若要從編譯器加速型訓練任務接收更詳細的訓練日誌，請將其變更為 `True`。不過，額外的記錄可能會增加額外負荷，並降低已編譯的訓練任務。預設值為 `False`。
+ `distribution` (dict) — 選用。若要使用 SageMaker Training Compiler 執行分散式訓練任務，請新增 `distribution = { 'pytorchxla' : { 'enabled': True }}`。

**警告**  
若開啟 SageMaker Debugger，可能會影響 SageMaker Training Compiler 的效能。我們建議您在執行 SageMaker Training Compiler 時關閉偵錯工具，以確保不會影響效能。如需詳細資訊，請參閱[考量事項](training-compiler-tips-pitfalls.md#training-compiler-tips-pitfalls-considerations)。若要關閉偵錯工具功能，請將下列兩個引數新增至估算器：  

```
disable_profiler=True,
debugger_hook_config=False
```

如果成功啟動使用編譯器的訓練任務，您會在任務初始化階段接收到下列日誌：
+ 搭配 `TrainingCompilerConfig(debug=False)`

  ```
  Found configuration for Training Compiler
  Configuring SM Training Compiler...
  ```
+ 搭配 `TrainingCompilerConfig(debug=True)`

  ```
  Found configuration for Training Compiler
  Configuring SM Training Compiler...
  Training Compiler set to debug mode
  ```

## 使用 SageMaker AI `CreateTrainingJob` API 作業
<a name="training-compiler-enable-pytorch-api"></a>

SageMaker Training Compiler 組態選項必須透過 [`CreateTrainingJob` API 作業](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html)的請求語法中之 `AlgorithmSpecification` 和 `HyperParameters` 欄位來指定。

```
"AlgorithmSpecification": {
    "TrainingImage": "<sagemaker-training-compiler-enabled-dlc-image>"
},

"HyperParameters": {
    "sagemaker_training_compiler_enabled": "true",
    "sagemaker_training_compiler_debug_mode": "false",
    "sagemaker_pytorch_xla_multi_worker_enabled": "false"    // set to "true" for distributed training
}
```

如要尋找已實作 SageMaker Training Compiler 的深度學習容器映像 URI 的完整清單，請參閱[支援的架構](training-compiler-support.md#training-compiler-supported-frameworks)。