本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Neptune ML 中自訂模型超參數組態
當您啟動 Neptune ML 模型訓練工作時，Neptune ML 會自動使用從先前[資料處理](machine-learning-on-graphs-processing.md)工作推斷出的資訊。它使用資訊來產生超參數組態範圍，用於建立 [SageMaker AI 超參數調校任務](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-how-it-works.html)，以訓練任務的多個模型。如此一來，您就不必為要訓練的模型指定很長的超參數值清單。相反，根據任務類型、圖形類型和調校工作設定來選取模型超參數範圍和預設值。
不過，您也可以修改資料處理工作所產生的 JSON 組態檔，來覆寫預設超參數組態並提供自訂超參數。
使用 Neptune ML [modelTraining API](machine-learning-api-modeltraining.md)，您可以控制數個高階超參數調校工作設定，例如 `maxHPONumberOfTrainingJobs`、`maxHPOParallelTrainingJobs` 和 `trainingInstanceType`。若要對模型超參數進行更精細的控制，您可以自訂資料處理工作所產生的 `model-HPO-configuration.json` 檔案。此檔案會儲存在您針對處理工作輸出所指定的 Amazon S3 位置。
您可以下載此檔案、進行編輯以覆寫預設的超參數組態，然後將其上傳回相同的 Amazon S3 位置。請不要變更檔案名稱，編輯時請小心遵循這些指示。
若要從 S3 下載檔案：
```
aws s3 cp \
s3://(bucket name)/(path to output folder)/model-HPO-configuration.json \
./
```
完成編輯後，請將檔案上傳回原來的位置：
```
aws s3 cp \
model-HPO-configuration.json \
s3://(bucket name)/(path to output folder)/model-HPO-configuration.json
```
## `model-HPO-configuration.json` 檔案的結構
`model-HPO-configuration.json` 檔案會指定要訓練的模型、機器學習 `task_type`，以及對於各種模型訓練執行應變動或固定的超參數。
超參數會分類為屬於不同層，這些層表示調用超參數調校工作時給與超參數的優先順序：
+ 第 1 層超參數具有最高優先順序。如果您將 `maxHPONumberOfTrainingJobs` 設定為小於 10 的值，則只會調校第 1 層超參數，其餘的則採取預設值。
+ 第 2 層超參數的優先順序較低，因此，如果對於調校工作，您有總數超過 10 個，但少於 50 個的訓練工作，則會同時調校第 1 層和第 2 層超參數。
+ 僅在您有總數超過 50 個的訓練工作時，第 3 層超參數才會與第 1 層和第 2 層一起進行調校。
+ 最後，固定的超參數完全不會進行調校，並且始終採取其預設值。
### `model-HPO-configuration.json` 檔案的範例
以下是範例 `model-HPO-configuration.json` 檔案：
```
{
"models": [
{
"model": "rgcn",
"task_type": "node_class",
"eval_metric": {
"metric": "acc"
},
"eval_frequency": {
"type": "evaluate_every_epoch",
"value": 1
},
"1-tier-param": [
{
"param": "num-hidden",
"range": [16, 128],
"type": "int",
"inc_strategy": "power2"
},
{
"param": "num-epochs",
"range": [3,30],
"inc_strategy": "linear",
"inc_val": 1,
"type": "int",
"node_strategy": "perM"
},
{
"param": "lr",
"range": [0.001,0.01],
"type": "float",
"inc_strategy": "log"
}
],
"2-tier-param": [
{
"param": "dropout",
"range": [0.0,0.5],
"inc_strategy": "linear",
"type": "float",
"default": 0.3
},
{
"param": "layer-norm",
"type": "bool",
"default": true
}
],
"3-tier-param": [
{
"param": "batch-size",
"range": [128, 4096],
"inc_strategy": "power2",
"type": "int",
"default": 1024
},
{
"param": "fanout",
"type": "int",
"options": [[10, 30],[15, 30], [15, 30]],
"default": [10, 15, 15]
},
{
"param": "num-layer",
"range": [1, 3],
"inc_strategy": "linear",
"inc_val": 1,
"type": "int",
"default": 2
},
{
"param": "num-bases",
"range": [0, 8],
"inc_strategy": "linear",
"inc_val": 2,
"type": "int",
"default": 0
}
],
"fixed-param": [
{
"param": "concat-node-embed",
"type": "bool",
"default": true
},
{
"param": "use-self-loop",
"type": "bool",
"default": true
},
{
"param": "low-mem",
"type": "bool",
"default": true
},
{
"param": "l2norm",
"type": "float",
"default": 0
}
]
}
]
}
```
### `model-HPO-configuration.json` 檔案的元素
此檔案包含一個 JSON 物件，其中包含名為 `models` 的單一最上層陣列，該陣列包含單一模型組態物件。自訂檔案時，請確定 `models` 陣列中只有一個模型組態物件。如果您的檔案包含多個模型組態物件，調校工作將會失敗並出現警告。
模型組態物件包含下列最上層元素：
+ **`model`** – (*字串*) 要訓練的模型類型 (**請勿修改**)。有效的值如下：
+ `"rgcn"` – 這是節點分類和迴歸任務以及異質連結預測任務的預設值。
+ `"transe"` – 這是 KGE 連結預測任務的預設值。
+ `"distmult"` – 這是 KGE 連結預測任務的替代模型類型。
+ `"rotate"` – 這是 KGE 連結預測任務的替代模型類型。
規則是不要直接修改 `model` 值，因為不同的模型類型通常具有截然不同的適用超參數，這可能會在訓練工作開始之後導致剖析錯誤。
若要變更模型類型，請使用 [modelTraining API](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job) 中的 `modelName` 參數，而不是在 `model-HPO-configuration.json` 檔案中變更它。
變更模型類型並進行精細超參數變更的方法是，為您要使用的模型複製預設模型組態範本，然後將其貼入 `model-HPO-configuration.json` 檔案中。如果推斷的任務類型支援多個模型，則在與 `model-HPO-configuration.json` 檔案相同的 Amazon S3 位置中會有一個名為 `hpo-configuration-templates` 的資料夾。此資料夾包含適用於任務之其他模型的所有預設超參數組態。
例如，如果您想要將 `KGE` 連結預測任務的模型和超參數組態從預設 `transe` 模型變更為 `distmult` 模型，只需將 `hpo-configuration-templates/distmult.json` 檔案內容貼入 `model-HPO-configuration.json` 檔案中，然後視需要編輯超參數即可。
**注意**
如果您在 `modelTraining` API 中設定 `modelName` 參數，同時變更 `model-HPO-configuration.json` 檔案中的 `model` 和超參數規格，且這些規格不同，則 `model-HPO-configuration.json` 檔案中的 `model` 值優先採用，且會忽略 `modelName` 值。
+ **`task_type`** – (*字串*) 由資料處理工作推斷或直接傳遞至資料處理工作的機器學習任務類型 (**請勿修改**)。有效的值如下：
+ `"node_class"`
+ `"node_regression"`
+ `"link_prediction"`
資料處理工作會推斷任務類型，方法是檢查匯出的資料集和資料集屬性所產生的訓練工作組態檔案，以取得資料集的屬性。
此值不得變更。如果您想要訓練不同的任務，則需要[執行新的資料處理工作](machine-learning-on-graphs-processing.md)。如果 `task_type` 值不是您預期的值，您應該檢查資料處理工作的輸入，以確定它們是正確的。這包括 `modelTraining` API 的參數，以及資料匯出程序所產生的訓練工作組態檔案中的參數。
+ **`eval_metric`** – (*字串*) 評估指標應用於評估模型效能，以及用於跨 HPO 執行選取效能最佳的模型。有效的值如下：
+ `"acc"` – 標準分類正確性。這是單一標籤分類任務的預設值，除非在資料處理期間發現不平衡的標籤，在此情況下，預設值為 `"F1"`。
+ `"acc_topk"` – 正確標籤位列排名最高 **`k`** 預測的次數。您也可以透過慱入 `topk` 做為額外索引鍵來設定值 **`k`**。
+ `"F1"` – [F1 分數](https://en.wikipedia.org/wiki/F-score)。
+ `"mse"` – 迴歸任務的[均方誤差指標](https://en.wikipedia.org/wiki/Mean_squared_error)。
+ `"mrr"` – [平均倒數排名指標](https://en.wikipedia.org/wiki/Mean_reciprocal_rank)。
+ `"precision"` – 模型精確度，計算方式為真正陽性與預測陽性之比：`= true-positives / (true-positives + false-positives)`。
+ `"recall"` – 模型回收，計算方式為真正陽性與實際陽性之比：`= true-positives / (true-positives + false-negatives)`。
+ `"roc_auc"` – [ROC 曲線](https://en.wikipedia.org/wiki/Receiver_operating_characteristic)下方的區域。這是多標籤分類的預設值。
例如，若要將指標變更為 `F1`，請變更 `eval_metric` 值，如下所示：
```
" eval_metric": {
"metric": "F1",
},
```
或者，若要將指標變更為 `topk` 正確性分數，您將變更 `eval_metric`，如下所示：
```
"eval_metric": {
"metric": "acc_topk",
"topk": 2
},
```
+ **`eval_frequency`** – (*物件*) 指定在訓練期間應檢查驗證集上模型效能的頻率。根據驗證效能，可以接著啟動提前停止，並儲存最佳模型。
`eval_frequency` 物件包含兩個元素，即 `"type"` 和 `"value"`。例如：
```
"eval_frequency": {
"type": "evaluate_every_pct",
"value": 0.1
},
```
有效的 `type` 值如下：
+ **`evaluate_every_pct`** – 指定每個評估要完成的訓練百分比。
對於 `evaluate_every_pct`，`"value"` 欄位包含一個介於零與一之間的浮點數，表示該百分比。
+ **`evaluate_every_batch`** – 指定每個評估要完成的訓練批次數目。
對於 `evaluate_every_batch`，`"value"` 欄位包含表示該批次計數的整數。
+ **`evaluate_every_epoch`** – 指定每個評估的 epoch 數目，其中新 epoch 從午夜開始。
對於 `evaluate_every_epoch`，`"value"` 欄位包含表示該 epoch 計數的整數。
`eval_frequency` 的預設設定如下：
```
"eval_frequency": {
"type": "evaluate_every_epoch",
"value": 1
},
```
+ **`1-tier-param`** – (*必要*) 第 1 層超參數的陣列。
如果您不想要調校任何超參數，則可以將此設定為空陣列。這不會影響 SageMaker AI 超參數調校任務啟動的訓練任務總數。其只是意味著所有的訓練作業 (如果超過 1 個，但少於 10 個) 將搭配相同的一組超參數執行。
另一方面，如果您想要以同等重要的方式處理所有可調校的超參數，則可以將所有的超參數放在這個陣列中。
+ **`2-tier-param`** – (*必要*) 第 2 層超參數的陣列。
僅在 `maxHPONumberOfTrainingJobs` 具有大於 10 的值時，才會調校這些參數。否則，它們會固定為預設值。
如果您的訓練預算最多為 10 個訓練工作，或者因為任何其他原因而不想要第 2 層超參數，但是您想要調校所有可調校的超參數，則可以將此設定為空陣列。
+ **`3-tier-param`** – (*必要*) 第 3 層超參數的陣列。
僅在 `maxHPONumberOfTrainingJobs` 具有大於 50 的值時，才會調校這些參數。否則，它們會固定為預設值。
如果您不想要第 3 層超參數，則可以將此設定為空陣列。
+ **`fixed-param`** – (*必要*) 固定超參數的陣列，這些超參數僅採取其預設值，且在不同的訓練工作中不會有所變動。
如果想要改變所有超參數，您可以將其設定為空陣列，然後將 `maxHPONumberOfTrainingJobs` 的值設定為足以改變所有層的大小，或使所有超參數成為第 1 層。
代表 `1-tier-param`、`2-tier-param`、`3-tier-param` 和 `fixed-param` 中每個超參數的 JSON 物件包含下列元素：
+ **`param`** – (*字串*) 超參數的名稱 (**請勿變更**)。
請參閱 [Neptune ML 中有效的超參數名稱清單](#machine-learning-hyperparams-list)。
+ **`type`** – (*字串*) 超參數類型 (**請勿變更**)。
有效類型為：`bool`、`int` 和 `float`。
+ **`default`** – (*字串*) 超參數的預設值。
您可以設定新的預設值。
可調校的超參數也可以包含下列元素：
+ **`range`** – (*陣列*) 連續可調校超參數的範圍。
這應該是具有兩個值的陣列，即範圍的最小值和最大值 (`[min, max]`)。
+ **`options`** – (*陣列*) 類別可調校超參數的選項。
這個陣列應該包含所有要考慮的選項：
```
"options" : [value1, value2, ... valuen]
```
+ **`inc_strategy`** – (*字串*) 連續可調校超參數範圍的增量變更類型 (**請勿變更**)。
有效值為 `log`、`linear` 和 `power2`。這僅在設定了範圍索引鍵時才適用。
修改此選項可能會導致未使用完整範圍的超參數進行調校。
+ **`inc_val`** – (*浮動*) 連續增量對連續可調校超參數的差異量 (**請勿變更**)。
這僅在設定了範圍索引鍵時才適用。
修改此選項可能會導致未使用完整範圍的超參數進行調校。
+ **`node_strategy`** – (*字串*) 表示此超參數的有效範圍應根據圖形中的節點數目而變更 (**請勿變更**)。
有效值為 `"perM"` (每百萬)、`"per10M"` (每千萬) 和 `"per100M"` (每億)。
不是變更此值，而是變更 `range`。
+ **`edge_strategy`** – (*字串*) 表示此超參數的有效範圍應根據圖形中的邊緣數目而變更 (**請勿變更**)。
有效值為 `"perM"` (每百萬)、`"per10M"` (每千萬) 和 `"per100M"` (每億)。
不是變更此值，而是變更 `range`。
### Neptune ML 中所有超參數的清單
下列清單包含可在 Neptune ML 中任何位置針對任何模型類型和任務設定的所有超參數。因為它們並非全部適用於每種模型類型，所以請務必只針對您正在使用的模型設定 `model-HPO-configuration.json` 檔案中出現在範本的超參數。
+ **`batch-size`** – 在一個正向傳遞中使用之目標節點的批次大小。*類型*：`int`。
將此值設定為更大的值可能會導致 GPU 執行個體訓練時出現記憶體問題。
+ **`concat-node-embed`** – 指示是否透過串連節點處理的特徵與可學習的初始節點嵌入來取得節點的初始表示法，以便增加模型的表達能力。*類型*：`bool`。
+ **`dropout`** – 套用至退出層的退出機率。*類型*：`float`。
+ **`edge-num-hidden`** – 邊緣特徵模組的隱藏層大小或單位數量。僅在 `use-edge-features` 設為 `True` 時才使用。*類型*：浮動。
+ **`enable-early-stop`** – 切換是否使用提前停止功能。*類型*：`bool`。*預設*︰`true`。
使用此布林參數來關閉提前停止功能。
+ **`fanout`** – 鄰近取樣期間要為目標節點取樣的鄰近節點數。*類型*：`int`。
此值與 `num-layers` 緊密結合，並且應始終位於相同的超參數層中。這是因為您可以為每個潛在的 GNN 層指定扇出。
因為這個超參數可能會造成模型效能發生很大變化，所以其應該固定或設定為第 2 層或第 3 層超參數。將其設定為更大的值可能會導致 GPU 執行個體訓練時出現記憶體問題。
+ **`gamma`** – 分數函數中的邊距值。*類型*：`float`。
這僅適用於 `KGE` 連結預測模型。
+ **`l2norm`** – 最佳化工具中使用的權重衰減值，該值會對權重施加 L2 標準化懲罰。*類型*：`bool`。
+ **`layer-norm`** – 指示是否要對 `rgcn` 模型使用層標準化。*類型*：`bool`。
+ **`low-mem`** – 指示是否以犧牲速度為代價，使用關聯訊息傳遞函數的低記憶體實作。*類型*：`bool`。
+ **`lr`** – 學習率。*類型*：`float`。
這應該設為第 1 層超參數。
+ **`neg-share`** – 在連結預測中，指示正取樣邊緣是否可以共用負邊緣取樣。*類型*：`bool`。
+ **`num-bases`** – `rgcn` 模型中基礎分解的基數。使用小於圖形中邊緣類型數目的 `num-bases` 值，做為 `rgcn` 模型的正規化器。*類型*：`int`。
+ **`num-epochs`** – 要執行之訓練的 epoch 數量。*類型*：`int`。
一個 epoch 是通過圖形的完整訓練。
+ **`num-hidden`** – 隱藏層大小或單位數量。*類型*：`int`。
這也會設定無特徵節點的初始嵌入大小。
在沒有減少 `batch-size` 的情況下將此值設定為更大的值可能會導致 GPU 執行個體訓練時出現記憶體用光問題。
+ **`num-layer`** – 模型中 GNN 層的數量。*類型*：`int`。
此值與扇出參數緊密結合，並且應該在同一超參數層中設定扇出之後出現。
因為此值可能會造成模型效能發生很大變化，所以其應該固定或設定為第 2 層或第 3 層超參數。
+ **`num-negs`** – 在連結預測中，每個正樣本的負樣本數量。*類型*：`int`。
+ **`per-feat-name-embed`** – 指示是否在組合特徵之前透過獨立轉換來嵌入每個特徵。*類型*：`bool`。
當設定為 `true` 時，在串連節點的所有轉換特徵並進一步轉換為 `num_hidden` 維度之前，將每個節點的每個特徵獨立轉換為固定維度大小。
當設定為 `false` 時，會串連特徵，而不會進行任何特徵特定的轉換。
+ **`regularization-coef`** – 在連結預測中，正規化損失的係數。*類型*：`float`。
+ **`rel-part`** – 指示是否使用關聯分割區進行 `KGE` 連結預測。*類型*：`bool`。
+ **`sparse-lr`** – 可學習節點嵌入的學習率。*類型*：`float`。
可學習的初始節點嵌入用於沒有特徵或設定 `concat-node-embed` 時的節點。稀疏可學習節點嵌入層的參數會使用個別的最佳化工具進行訓練，該最佳化工具可以具有個別的學習率。
+ **`use-class-weight`** – 指示是否針對不平衡的分類任務套用類別權重。如果設定為 `true`，則會使用標籤計數來設定每個類別標籤的權重。*類型*：`bool`。
+ **`use-edge-features`** – 指示是否要在訊息傳遞期間使用邊緣特徵。如果設定為 `true`，則對於具有特徵的邊緣類型，會將自訂邊緣特徵模組新增至 RGCN 層。*類型*：`bool`。
+ **`use-self-loop`** – 指示是否要在訓練 `rgcn` 模型時包含自我迴圈。*類型*：`bool`。
+ **`window-for-early-stop`** – 控制要平均的最新驗證分數，以決定是否要提前停止。預設值為 3。type=int。另請參閱[提前停止 Neptune ML 中的模型訓練程序](machine-learning-improve-model-performance.md#machine-learning-model-training-early-stop)。*類型*：`int`。*預設*︰`3`。
請參閱 。
## 在 Neptune ML 中自訂超參數
當您編輯 `model-HPO-configuration.json` 檔案時，以下是最常進行的變更種類：
+ 編輯 `range` 超參數的最小值和/或最大值。
+ 將超參數設定為固定值，方法是將該超參數移至 `fixed-param` 區段，並將其預設值設定為您想要其採取的固定值。
+ 變更超參數的優先順序，方法是將該超參數置於特定層中、編輯其範圍，並確定已適當地設定其預設值。