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

# 使用 Amazon SageMaker Experiments 記錄參數與指標
<a name="train-remote-decorator-experiments"></a>

本指南說明如何使用 Amazon SageMaker Experiments 記錄參數與指標。SageMaker AI 實驗由執行組成，每次執行都包含單一模型訓練互動的所有輸入、參數、組態與結果。

您可以使用 @remote 裝飾項目或 `RemoteExecutor` API 從遠端函式記錄參數與指標。

若要從遠端函式記錄參數與指標，請選擇下列其中一個方法：
+ 使用 SageMaker AI Experiments 程式庫的 `Run`，在遠端函式內部具現化 SageMaker 實驗執行。如需更多資訊，請參閱[建立 Amazon SageMaker AI Experiment](https://docs.aws.amazon.com/sagemaker/latest/dg/experiments-create.html)。
+ 從 SageMaker AI Experiments 程式庫的遠端函式內部使用 `load_run` 函式。這將載入在遠端函式外部宣告的 `Run` 執行個體。

以下區段說明如何運用先前列出的方法，使用 SageMaker AI 實驗執行來建立並追蹤歷程。以下區段同時描述 SageMaker 訓練不支援的案例。

## 使用 @remote 裝飾項目整合 SageMaker Experiments
<a name="train-remote-decorator-experiments-remote"></a>

您可以在 SageMaker AI 具現化實驗，也可以從遠端函式內部載入目前的 SageMaker AI 實驗。下列區段顯示如何使用任一方法。

### 利用 SageMaker Experiments 建立實驗
<a name="train-remote-decorator-experiments-remote-create"></a>

您可以建立在 SageMaker AI 實驗建立實驗執行。若要做到這點，請傳遞實驗名稱、執行名稱與其他參數至遠端函式。

下列代碼範例會匯入實驗名稱、執行名稱，以及每次執行期間要記錄的參數。參數 `param_1` 與 `param_2` 會隨著時間記錄於訓練迴路內部。常見參數可能包含批次大小或週期。在此範例，指標 `metric_a` 與 `metric_b` 會隨著執行時間記錄於訓練迴路內部。其他常見指標可能包含 `accuracy` 或 `loss`。

```
from sagemaker.remote_function import remote
from sagemaker.experiments.run import Run

# Define your remote function
@remote
def train(value_1, value_2, exp_name, run_name):
    ...
    ...
    #Creates the experiment
    with Run(
        experiment_name=exp_name,
        run_name=run_name,
    ) as run:
        ...
        #Define values for the parameters to log
        run.log_parameter("param_1", value_1)
        run.log_parameter("param_2", value_2) 
        ...
        #Define metrics to log
        run.log_metric("metric_a", 0.5)
        run.log_metric("metric_b", 0.1)


# Invoke your remote function        
train(1.0, 2.0, "my-exp-name", "my-run-name")
```

### 使用 @remote 裝飾項目初始化的工作載入目前的 SageMaker Experiments
<a name="train-remote-decorator-experiments-remote-current"></a>

使用 SageMaker Experiments 程式庫的 `load_run()` 函式，從執行內容載入目前執行物件。您還可以在遠端函式內使用 `load_run()` 函式。如下列代碼範例所示，將 `with` 陳述式在本機初始化的執行物件載入執行物件。

```
from sagemaker.experiments.run import Run, load_run

# Define your remote function
@remote
def train(value_1, value_2):
    ...
    ...
    with load_run() as run:
        run.log_metric("metric_a", value_1)
        run.log_metric("metric_b", value_2)


# Invoke your remote function
with Run(
    experiment_name="my-exp-name",
    run_name="my-run-name",
) as run:
    train(0.5, 1.0)
```

## 在使用 `RemoteExecutor` API 初始化的工作內載入目前的實驗執行
<a name="train-remote-decorator-experiments-api"></a>

如工作是使用 `RemoteExecutor` API 初始化，您還可以載入目前的 SageMaker AI 實驗執行。下列代碼範例示範如何運用 SageMaker Experiments `load_run` 函式來使用 `RemoteExecutor` API。這樣做是為了載入目前的 SageMaker AI 實驗執行，並在 `RemoteExecutor` 提交的工作擷取指標。

```
from sagemaker.experiments.run import Run, load_run

def square(x):
    with load_run() as run:
        result = x * x
        run.log_metric("result", result)
    return result


with RemoteExecutor(
    max_parallel_job=2,
    instance_type="ml.m5.large"
) as e:
    with Run(
        experiment_name="my-exp-name",
        run_name="my-run-name",
    ):
        future_1 = e.submit(square, 2)
```

## 當使用 @remote 裝飾項目註釋代碼時，SageMaker Experiments 不支援的使用
<a name="train-remote-decorator-experiments-unsupported"></a>

SageMaker AI 不支援傳遞 `Run` 類型物件至 @remote 函式或使用全域 `Run` 物件。下列範例顯示將擲回 `SerializationError` 的代碼。

下列代碼範例會嘗試傳遞 `Run` 類型物件至 @remote 裝飾項目，但會產生錯誤。

```
@remote
def func(run: Run):
    run.log_metrics("metric_a", 1.0)
    
with Run(...) as run:
    func(run) ---> SerializationError caused by NotImplementedError
```

下列代碼範例會嘗試使用在遠端函式外部具現化的全域 `run` 物件。在此代碼範例，`train()` 函式在 `with Run` 內容內部進行定義，從內部參考全域執行物件。當呼叫 `train()` 時，其會產生錯誤。

```
with Run(...) as run:
    @remote
    def train(metric_1, value_1, metric_2, value_2):
        run.log_parameter(metric_1, value_1)
        run.log_parameter(metric_2, value_2)
    
    train("p1", 1.0, "p2", 0.5) ---> SerializationError caused by NotImplementedError
```