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

# JSON 訓練資料組態檔案的結構
<a name="machine-learning-processing-training-config-file-structure"></a>

訓練組態檔案是指匯出程序儲存在 `nodes/` 和 `edges/` 資料夾中的 CSV 檔案。

`nodes/` 下的每個檔案都會儲存具有相同屬性圖節點標籤之節點的相關資訊。節點檔案中的每一資料行都會儲存節點 ID 或節點屬性。檔案的第一行包含一個標頭，為每一資料行指定 `~id` 或屬性名稱。

`edges/` 下的每個檔案都會儲存具有相同屬性圖邊緣標籤之節點的相關資訊。節點檔案中的每一資料行都會儲存節點 ID、目的地節點 ID 或邊緣屬性。檔案的第一行包含一個標頭，為每一資料行指定 `~from`、`~to` 或屬性名稱。

訓練資料組態檔案具有三個最上層元素：

```
{
  "version" : "v2.0",
  "query_engine" : "gremlin",
  "graph" : [ ... ]
}
```
+ `version` – (字串) 正在使用的組態檔案版本。
+ `query_engine` – (字串) 用於匯出圖形資料的查詢語言。目前，僅「gremlin」是有效的。
+ `graph` – (JSON 陣列) 列出一或多個組態物件，其中包含每個將使用之節點和邊緣的模型參數。

  圖形陣列中的組態物件具有下一節所述的結構。

## `graph` 陣列中列出之組態物件的內容
<a name="machine-learning-graph-training-config-object"></a>

`graph` 陣列中的組態物件可以包含三個最上層節點：

```
    {
      "edges"    : [ ... ],
      "nodes"    : [ ... ],
      "warnings" : [ ... ],
    }
```
+ `edges` – (JSON 物件陣列) 每個 JSON 物件都會指定一組參數，以定義在模型處理和訓練期間將如何處理圖形中的邊緣。這僅會與 Gremlin 引擎搭配使用。
+ `nodes` – (JSON 物件陣列) 每個 JSON 物件都會指定一組參數，以定義在模型處理和訓練期間將如何處理圖形中的節點。這僅會與 Gremlin 引擎搭配使用。
+ `warnings` – (JSON 物件陣列) 每個物件都包含在資料匯出過程中產生的警告。

## `edges` 陣列中列出之邊緣組態物件的內容
<a name="machine-learning-graph-edges-config"></a>

`edges` 陣列中列出的邊緣組態物件可以包含下列最上層欄位：

```
      {
        "file_name" : "(path to a CSV file)",
        "separator" : "(separator character)",
        "source"    : ["(column label for starting node ID)", "(starting node type)"],
        "relation"  : ["(column label for the relationship name)", "(the prefix name for the relationship name)"],
        "dest"      : ["(column label for ending node ID)", "(ending node type)"],
        "features"  : [(array of feature objects)],
        "labels"    : [(array of label objects)]
      }
```
+ **`file_name`** – 字串，其會指定 CSV 檔案的路徑，而此檔案會儲存具有相同屬性圖標籤之邊緣的相關資訊。

  該檔案的第一行包含資料行標籤的標頭行。

  前兩個資料行標籤為 `~from` 和 `~to`。第一個資料行 (`~from` 資料行) 儲存邊緣起始節點的 ID，而第二個資料行 (`~to` 資料行) 儲存邊緣結束節點的 ID。

  標頭行中的其餘資料行標籤會為每個剩餘的資料行指定其值已匯出至該資料行的邊緣屬性名稱。
+ **`separator`** – 字串，其中包含分隔該 CSV 檔案中資料行的分隔符號。
+ **`source`** – JSON 陣列，其中包含兩個指定邊緣起始節點的字串。第一個字串包含起始節點 ID 儲存所在資料行的標頭名稱。第二個字串指定節點類型。
+ **`relation`** – JSON 陣列，其中包含兩個指定邊緣關聯類型的字串。第一個字串包含關聯名稱 (`relname`) 儲存所在資料行的標頭名稱。第二個字串包含關聯名稱 (`prefixname`) 的字首。

  完整的關聯類型由兩個字串組合而成，它們之間有一個連字號，如下所示：`prefixname-relname`。

  如果第一個字串是空的，則所有邊緣都具有相同的關聯類型，即 `prefixname` 字串。
+ **`dest`** – JSON 陣列，其中包含兩個指定邊緣結束節點的字串。第一個字串包含節點 ID 儲存所在資料行的標頭名稱。第二個字串指定節點類型。
+ **`features`** – 屬性值特徵物件的 JSON 陣列。每個屬性值特徵物件包含下列欄位：
  + **feature** – 由三個字串組成的 JSON 陣列。第一個字串包含資料行的標頭名稱，而該資料行包含屬性值。第二個字串包含特徵名稱。第三個字串包含特徵類型。
  + **norm** – (*選用*) 指定要套用至屬性值的標準化方法。

    
+ **`labels`** – 物件的 JSON 陣列。每個物件都會定義邊緣的目標特徵，並指定訓練和驗證階段應採取的邊緣比例。每個物件包含下列欄位：
  + **label** – 由兩個字串組成的 JSON 陣列。第一個字串包含資料行的標頭名稱，而該資料行包含目標特徵屬性值。第二個字串會指定下列其中一個目標任務類型：
    + `"classification"` – 邊緣分類任務。`label` 陣列中第一個字串所識別之資料行中提供的屬性值會被視為類別值。對於邊緣分類任務，`label` 陣列中的第一個字串不能是空的。
    + `"regression"` – 邊緣迴歸任務。`label` 陣列中第一個字串所識別之資料行中提供的屬性值會被視為數值。對於邊緣迴歸任務，`label` 陣列中的第一個字串不能是空的。
    + `"link_prediction"` – 連結預測任務。不需要任何屬性值。對於連結預測任務，會忽略 `label` 陣列中的第一個字串。
  + **`split_rate`** – JSON 陣列，其中包含三個介於零和一之間的數字，這些數字加起來最多為一，並代表訓練、驗證和測試階段將分別使用的節點比例估計值。可以定義此欄位或 `custom_split_filenames`，但不能同時定義這兩者。請參閱 [split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate)。
  + **`custom_split_filenames`** – JSON 物件，其會指定用來定義訓練、驗證和測試母體之檔案的名稱。可以定義此欄位或 `split_rate`，但不能同時定義這兩者。如需詳細資訊，請參閱[自訂訓練-驗證-測試比例](#machine-learning-custom-stages-splits)。

## `nodes` 陣列中列出之節點組態物件的內容
<a name="machine-learning-graph-nodes-config"></a>

`nodes` 陣列中列出的節點組態物件可以包含下列欄位：

```
      {
        "file_name" : "(path to a CSV file)",
        "separator" : "(separator character)",
        "node"      : ["(column label for the node ID)", "(node type)"],
        "features"  : [(feature array)],
        "labels"    : [(label array)],
      }
```
+ **`file_name`** – 字串，其會指定 CSV 檔案的路徑，而此檔案會儲存具有相同屬性圖標籤之節點的相關資訊。

  該檔案的第一行包含資料行標籤的標頭行。

  第一個資料行標籤是 `~id`，且第一個資料行 (`~id` 資料行) 會儲存節點 ID。

  標頭行中的其餘資料行標籤會為每個剩餘的資料行指定其值已匯出至該資料行的節點屬性名稱。
+ **`separator`** – 字串，其中包含分隔該 CSV 檔案中資料行的分隔符號。
+ **`node`** – 包含兩個字串的 JSON 陣列。第一個字串包含儲存節點 ID 之資料行的標頭名稱。第二個字串指定圖形中的節點類型，該類型對應至節點的屬性圖標籤。
+ **`features`** – 節點特徵物件的 JSON 陣列。請參閱 [列示在節點或邊緣之 `features` 陣列中的特徵物件內容](#machine-learning-graph-node-features-config)。
+ **`labels`** – 節點標籤物件的 JSON 陣列。請參閱 [節點 `labels` 陣列中列出之節點標籤物件的內容](#machine-learning-graph-node-labels-config)。

## 列示在節點或邊緣之 `features` 陣列中的特徵物件內容
<a name="machine-learning-graph-node-features-config"></a>

節點 `features` 陣列中列出的節點特徵物件可以包含下列最上層欄位：
+ **`feature`** – 由三個字串組成的 JSON 陣列。第一個字串包含資料行的標頭名稱，而該資料行包含特徵的屬性值。第二個字串包含特徵名稱。

  第三個字串包含特徵類型。有效的特徵類型列示在 [功能的類型欄位可能值](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-feature-types) 中。
+ **`norm`** – 數值特徵需要此欄位。它會指定要在數值上使用的標準化方法。有效值為 `"none"`、`"min-max"` 和「standard」。如需詳細資訊，請參閱 [標準欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-norm)。
+ **`language`** – 語言欄位會指定文字屬性值中使用的語言。它的用法取決於文字編碼方法：
  + 對於 [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) 編碼，此欄位是必要的，且必須指定下列其中一種語言：
    + `en` (英文)
    + `zh` (中文)
    + `hi` (北印度文)
    + `es` (西班牙文)
    + `fr` (法文)

    不過，`text_fasttext` 一次無法處理多種語言。
  + 對於 [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) 編碼，不會使用此欄位，因為 SBERT 編碼是多語系的。
  + 對於 [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) 編碼，此欄位是選用的，因為 `text_word2vec` 僅支援英文。如果存在，它必須指定英文模型的名稱：

    ```
    "language" : "en_core_web_lg"
    ```
  + 對於 [`tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) 編碼，不會使用此欄位。
+ **`max_length`** – 此欄位是 [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) 特徵的選用欄位，其中指定將編碼之輸入文字特徵中的記號數目上限。在到達 `max_length` 之後，會忽略輸入文字。例如，將 max\$1length 設定為 128，表示將忽略文字序列中第 128 個之後的任何記號：
+ **`separator`** – 此欄位可選擇性地與 `category`、`numerical` 和 `auto` 特徵搭配使用。它會指定一個字元，其可以用來將屬性值分成多個類別值或數值。

  請參閱 [分隔符號欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-separator)。
+ **`range`** – `bucket_numerical` 特徵需要此欄位。它會指定要分成儲存貯體的數值範圍。

  請參閱 [範圍欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-range)。
+ **`bucket_cnt`** – `bucket_numerical` 特徵需要此欄位。它會指定由 `range` 參數定義的數值範圍應分成的儲存貯體數目。

  請參閱 [Neptune ML 中的儲存貯體數值特徵](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
+ **`slide_window_size`** – 此欄位可選擇性地與 `bucket_numerical` 特徵搭配使用，以將值指派給多個儲存貯體。

  請參閱 [slide\$1window\$1size 欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-slide_window_size)。
+ **`imputer`** – 此欄位可選擇性地與 `numerical`、`bucket_numerical` 和 `datetime` 特徵搭配使用，以提供填入缺失值的插補技術。支援的插補技術為 `"mean"`、`"median"` 和 `"most_frequent"`。

  請參閱 [imputer 欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-imputer)。
+ **`max_features`** – `text_tfidf` 特徵可選擇性地使用此欄位，來指定要編碼的字詞數上限。

  請參閱 [max\$1features 欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-max_features)。
+ **`min_df`** – `text_tfidf` 特徵可選擇性地使用此欄位，來指定要編碼之字詞的文件頻率下限

  請參閱 [min\$1df 欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-min_df)。
+ **`ngram_range`** – `text_tfidf` 特徵可選擇性地使用此欄位，來指定哪個範圍或多少單字或記號要被視為要編碼的潛在個別字詞

  請參閱 [ngram\$1range 欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-ngram_range)。
+ **`datetime_parts`** – `datetime` 特徵可選擇性地使用此欄位，來指定日期時間值的哪些部分要進行類別編碼。

  請參閱 [datetime\$1parts 欄位](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-datetime_parts)。

## 節點 `labels` 陣列中列出之節點標籤物件的內容
<a name="machine-learning-graph-node-labels-config"></a>

節點 `labels` 陣列中列出的標籤物件會定義節點目標特徵，並會指定訓練、驗證和測試階段將使用的節點比例。每個物件可以包含下列欄位：

```
      {
        "label"      : ["(column label for the target feature property value)", "(task type)"],
        "split_rate" : [(training proportion), (validation proportion), (test proportion)],
        "custom_split_filenames" : {"train": "(training file name)", "valid": "(validation file name)", "test": "(test file name)"},
        "separator"  : "(separator character for node-classification category values)",
      }
```
+ **`label`** – 包含兩個字串的 JSON 陣列。第一個字串包含資料行的標頭名稱，而該資料行會儲存特徵的屬性值。第二個字串指定目標任務類型，其可以是：
  + `"classification"` – 節點分類任務。所指定資料行中的屬性值用來建立類別特徵。
  + `"regression"` – 節點迴歸任務。所指定資料行中的屬性值用來建立數值特徵。
+ **`split_rate`** – JSON 陣列，其中包含三個介於零和一之間的數字，這些數字加起來最多為一，並代表訓練、驗證和測試階段將分別使用的節點比例估計值。請參閱 [split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate)。
+ **`custom_split_filenames`** – JSON 物件，其會指定用來定義訓練、驗證和測試母體之檔案的名稱。可以定義此欄位或 `split_rate`，但不能同時定義這兩者。如需詳細資訊，請參閱[自訂訓練-驗證-測試比例](#machine-learning-custom-stages-splits)。
+ **`separator`** – 包含分隔符號的字串，此分隔符號會分隔分類任務的類別特徵值。

**注意**  
如果未對邊緣和節點兩者提供標籤物件，則會自動假設任務為連結預測，且邊緣會隨機分割成 90% 用於訓練，10% 用於驗證。

## 自訂訓練-驗證-測試比例
<a name="machine-learning-custom-stages-splits"></a>

根據預設，Neptune ML 會使用 `split_rate` 參數，以使用此參數中定義的比例，將圖形隨機分割成訓練、驗證和測試母體。若要更精確地控制在這些不同母體中使用哪些實體，可以建立明確定義它們的檔案，然後[可以編輯訓練資料組態檔案](machine-learning-processing-training-config-file.md)，將這些索引檔案對應至母體。此對應是由 JSON 物件針對訓練組態檔案中的 [`custom_split_filesnames`](#custom_split_filenames) 索引鍵所指定。如果使用此選項，則必須為 `train` 和 `validation` 索引鍵提供檔案名稱，而對於 `test` 索引鍵則是選用的。

這些檔案的格式應符合 [Gremlin 資料格式](bulk-load-tutorial-format-gremlin.md#bulk-load-tutorial-format-gremlin-systemheaders)。特別是，對於節點層級任務，每個檔案應包含其 `~id` 標頭列出節點 ID 的資料行，而對於邊緣層級任務，檔案應分別指定 `~from` 和 `~to`，以指示邊緣的來源和目的地節點。這些檔案必須放置在與用於資料處理之匯出資料相同的 Amazon S3 位置 (請參閱：[`outputS3Path`](export-parameters.md#export-parameters-outputS3Path))。

對於屬性分類或迴歸任務，這些檔案可以選擇性地定義機器學習任務的標籤。在此情況下，檔案必須具有一個屬性資料行，其標頭名稱與[訓練資料組態檔案中定義的](#machine-learning-graph-node-labels-config)相同。如果在匯出的節點和邊緣檔案以及自訂分割檔案中都定義了屬性標籤，則會優先考慮自訂分割檔案。