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

# Neptune ML 中的自訂模型開發
<a name="machine-learning-custom-model-development"></a>

開始自訂模型開發的好方法是，遵循 [Neptune ML 工具組範例](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/introduction)來建構和撰寫訓練模組。Neptune ML 工具組也會在 [modelzoo](https://github.com/awslabs/neptuneml-toolkit/tree/main/src/neptuneml_toolkit/modelzoo) 中實作模組化圖形 ML 模型元件，您可以堆疊並使用這些元件來建立自訂模型。

此外，此工具組還提供公用程式函數，協助您在模型訓練和模型轉換期間產生必要的成品。您可以在自訂實作中匯入此 Python 套件。此工具組中提供的任何函數或模組也可在 Neptune ML 訓練環境中使用。

如果您的 Python 模組有額外的外部相依性，則您可以透過在模組的目錄中建立 `requirements.txt` 檔案，來包含這些額外的相依性。然後，會在訓練指令碼執行之前安裝 `requirements.txt` 檔案中列出的套件。

實作自訂模型的 Python 模組至少需要包含以下內容：
+ 訓練指令碼進入點
+ 轉換指令碼進入點
+ `model-hpo-configuration.json` 檔案

## Neptune ML 中的自訂模型訓練指令碼開發
<a name="machine-learning-custom-model-training-script"></a>

您的自訂模型訓練指令碼應該是可執行的 Python 指令碼，例如 Neptune ML 工具組的 [https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) 範例。它必須接受超參數名稱和值作為命令列參數。在模型訓練期間，會從 `model-hpo-configuration.json` 檔案取得超參數名稱。超參數值會落在有效的超參數範圍內 (如果超參數是可調校的話)，或採取預設的超參數值 (如果無法調校的話)。

您的訓練指令碼會使用如下所示的語法在 SageMaker AI 訓練執行個體上執行：

```
python3 (script entry point) --(1st parameter) (1st value) --(2nd parameter) (2nd value) (...)
```

對於所有工作，除了您指定的超參數之外，Neptune ML AutoTrainer 還會將數個必要的參數傳送至您的訓練指令碼，而且您的指令碼必須能夠處理這些額外的參數，才能正常運作。

這些額外的必要參數會因任務而有所不同：

**若是節點分類或節點迴歸**
+ **`task`** – Neptune ML 內部使用的任務類型。對於節點分類，這是 `node_class`，對於節點迴歸，它是 `node_regression`。
+ **`model`** – Neptune ML 內部使用的模組名稱，在此情況下，該模組為 `custom`。
+ **`name`** – Neptune ML 內部使用的任務名稱，在此情況下該任務是 `node_class-custom` (用於節點分類)，以及 `node_regression-custom` (用於節點迴歸)。
+ **`target_ntype`** – 用於分類或迴歸的節點類型名稱。
+ **`property`** – 用於分類或迴歸的節點屬性名稱。

**若是連結預測**
+ **`task`** – Neptune ML 內部使用的任務類型。對於連結預測，這是 `link_predict`。
+ **`model`** – Neptune ML 內部使用的模組名稱，在此情況下，該模組為 `custom`。
+ **`name`** – Neptune ML 內部使用的任務名稱，在此情況下，該任務為 `link_predict-custom`。

**若是邊緣分類或邊緣迴歸**
+ **`task`** – Neptune ML 內部使用的任務類型。對於邊緣分類，這是 `edge_class`，對於邊緣迴歸，它是 `edge_regression`。
+ **`model`** – Neptune ML 內部使用的模組名稱，在此情況下，該模組為 `custom`。
+ **`name`** – Neptune ML 內部使用的任務名稱，在此情況下該任務是 `edge_class-custom` (用於邊緣分類)，以及 `edge_regression-custom` (用於邊緣迴歸)。
+ **`target_etype`** – 用於分類或迴歸的邊緣類型名稱。
+ **`property`** – 用於分類或迴歸的邊緣屬性名稱。

您的指令碼應該儲存模型參數，以及訓練結束時將需要的任何其他成品。

您可以使用 Neptune ML 工具組公用程式函數，來判斷所處理圖形資料的位置、應儲存模型參數的位置，以及訓練執行個體上可用的 GPU 裝置。如需如何使用這些公用程式函數的範例，請參閱 [train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) 範例訓練指令碼。

## Neptune ML 中的自訂模型轉換指令碼開發
<a name="machine-learning-custom-model-transform-script"></a>

需要轉換指令碼，才能利用 Neptune ML [增量工作流程](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental)，在不重新訓練模型的情況下，對不斷發展的圖形進行模型推論。即使模型部署所需的所有成品都是由訓練指令碼產生，但如果您想要在不重新訓練模型的情況下產生更新的模型，您仍然需要提供轉換指令碼。

**注意**  
自訂模型目前不支援[即時歸納推論](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)。

您的自訂模型轉換指令碼應該是可執行的 Python 指令碼，例如 Neptune ML 工具組的 [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) 範例指令碼。因為這個指令碼是在模型訓練期間調用，沒有命令列引數，所以指令碼接受的任何命令列引數都必須具有預設值。

指令碼在 SageMaker AI 訓練執行個體上執行，語法如下：

```
python3 (your transform script entry point)
```

您的轉換指令碼將需要各項資訊，例如：
+ 所處理圖形資料的位置。
+ 儲存模型參數的位置，以及應儲存新模型成品的位置。
+ 可在執行個體上使用的裝置。
+ 已產生最佳模型的超參數。

這些輸入是使用指令碼可呼叫的 Neptune ML 公用程式函數來取得。如需如何執行此操作的範例，請參閱工具組的範例 [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) 指令碼。

指令碼應儲存節點嵌入、節點 ID 對應，以及每項任務的模型部署所需的任何其他成品。如需不同 Neptune ML 任務所需之模型成品的詳細資訊，請參閱[模型成品文件](machine-learning-model-artifacts.md)。

## Neptune ML 中的自訂 `model-hpo-configuration.json` 檔案
<a name="machine-learning-custom-model-hpo-configuration-file"></a>

`model-hpo-configuration.json` 檔案會針對您的自訂模型定義超參數。它的[格式](machine-learning-customizing-hyperparams.md)同於與 Neptune ML 內建模型搭配使用的 `model-hpo-configuration.json` 檔案，而且優先於 Neptune ML 自動產生並上傳到所處理資料位置的版本。

將新的超參數新增至您的模型時，您也必須為此檔案中的超參數新增一個項目，以便該超參數會傳遞至您的訓練指令碼。

如果您想要超參數可調校，則必須為這個超參數提供範圍，並將其設定為 `tier-1`、`tier-2`、或 `tier-3` 參數。如果設定的訓練工作總數允許調整其層中的超參數，則會調整超參數。對於不可調校的參數，您必須提供預設值，並將超參數新增至檔案的 `fixed-param` 區段。如需如何執行此操作的範例，請參閱工具組的[範例 `model-hpo-configuration.json` 檔案](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/model-hpo-configuration.json)範例。

您還必須提供指標定義，SageMaker AI HyperParameter 最佳化任務將用於評估訓練的候選模型。若要這樣做，您可以將 `eval_metric` JSON 物件新增至 `model-hpo-configuration.json` 檔案，如下所示：

```
"eval_metric": {
  "tuning_objective": {
      "MetricName": "(metric_name)",
      "Type": "Maximize"
  },
  "metric_definitions": [
    {
      "Name": "(metric_name)",
      "Regex": "(metric regular expression)"
    }
  ]
},
```

`eval_metric` 物件中的`metric_definitions`陣列會列出您希望 SageMaker AI 從訓練執行個體擷取的每個指標的指標定義物件。每個指標定義物件都有一個 `Name` 索引鍵，可讓您提供指標的名稱 (例如「accuracy」、「f1」等)。`Regex` 索引鍵可讓您提供一個規則表達式字串，與該特定指標在訓練日誌中列印的方式相符。如需如何定義指標的詳細資訊，請參閱 [SageMaker AI HyperParameter 調校頁面](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-define-metrics.html)。

然後，`eval_metric` 中的 `tuning_objective` 物件可讓您指定 `metric_definitions` 中的哪個指標應用作評估指標，做為超參數最佳化的目標指標。`MetricName` 的值必須與 `metric_definitions` 內其中一個定義中 `Name` 的值相符。`Type` 的值應該是「Maximize」或「Minimize」，取決於是否應將指標解譯為更大更好 (例如「accuracy」) 或更少更好 (例如「mean-squared-error」)。

`model-hpo-configuration.json` 檔案的此區段中的錯誤可能會導致 Neptune ML 模型訓練 API 任務失敗，因為 SageMaker AI HyperParameter 調校任務將無法選取最佳模型。

## 在 Neptune ML 中對您的自訂模型實作進行本機測試
<a name="machine-learning-custom-model-testing"></a>

您可以使用 Neptune ML 工具組 Conda 環境，在本機執行程式碼，以便測試並驗證您的模型。如果您是在 Neptune 筆記本執行個體上進行開發，則此 Conda 環境將預先安裝在 Neptune 筆記本執行個體執行個體上。如果您是在不同的執行個體上進行開發，則需要遵循 Neptune ML 工具組中的[本機設定指示](https://github.com/awslabs/neptuneml-toolkit#local-installation)。

當您呼叫[模型訓練 API](machine-learning-api-modeltraining.md) 時，Conda 環境會準確地重現模型將在其中執行的環境。所有範例訓練指令碼和轉換指令碼都可讓您傳遞命令列 `--local` 旗標，在本機環境中執行指令碼，進行輕鬆的偵錯。在開發自己的模型時，這是一個很好的做法，因為它可以讓您以互動方式並反覆測試模型實作。在 Neptune ML 生產訓練環境中進行模型訓練期間，會省略此參數。