本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 neptune-export 工具或 Neptune-Export 服務從 Neptune for Neptune ML 匯出資料
Neptune ML 需要您為 [Deep Graph Library (DGL)](https://www.dgl.ai/) 提供訓練資料，以建立和評估模型。
您可以使用 [Neptune-Export 服務](export-service.md)或 [`neptune-export` 公用程式](export-utility.md)，從 Neptune 中匯出資料。此服務和命令列工具兩者都會以 CSV 格式將資料發佈至 Amazon Simple Storage Service (Amazon S3)，並使用 Amazon S3 伺服器端加密 (`SSE-S3`) 進行加密。請參閱 [由 Neptune-Export 和 `neptune-export` 匯出的檔案](exported-files.md)。
此外，當您針對 Neptune ML 設定訓練資料的匯出時，匯出工作會建立並發佈加密的模型訓練組態檔案，以及匯出的資料。根據預設，此檔案會命名為 `training-data-configuration.json`。
# 使用 Neptune-Export 服務匯出 Neptune ML 訓練資料的範例
此請求會匯出節點分類任務的屬性圖訓練資料：
```
curl \
(your NeptuneExportApiUri) \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"command": "export-pg",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "genre",
"type": "classification"
}
]
}
}
}'
```
此請求會匯出節點分類任務的 RDF 訓練資料：
```
curl \
(your NeptuneExportApiUri) \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"command": "export-rdf",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre",
"type": "classification"
}
]
}
}
}'
```
# 匯出訓練資料時要在參數物件中設定的欄位
匯出請求中的 `params` 物件可以包含各種欄位，如 [`params` 文件](export-params-fields.md)中所述。下列欄位與匯出機器學習訓練資料最相關：
****
+ **`endpoint`** – 使用 `endpoint` 來指定資料庫叢集中 Neptune 執行個體的端點，匯出程序可以查詢該資料庫叢集來擷取資料。
+ **`profile`** – 必須將 `params` 物件中的 `profile` 欄位設為 **`neptune-ml`**。
這會導致匯出程序針對 Neptune ML 模型訓練適當地格式化匯出的資料，若是屬性圖資料採取 CSV 格式，若是 RDF 資料則以 N-Triples 表示。它也會導致系統建立 `training-data-configuration.json` 檔案，並將其寫入與匯出的訓練資料相同的 Amazon S3 位置。
+ **`cloneCluster`** – 如果設為 `true`，匯出程序會複製您的資料庫叢集、從該複製中匯出，然後在完成時刪除該複製。
+ **`useIamAuth`** – 如果您的資料庫叢集已啟用 [IAM 身分驗證](iam-auth-enable.md)，則您必須包含這個設為 `true` 的欄位。
匯出程序還提供了幾種篩選您匯出之資料的方法 (請參閱[這些範例](export-filtering-examples.md))。
# 使用 additionalParams 物件來調整模型訓練資訊的匯出
`additionalParams` 物件包含若干欄位，您可以使用這些欄位，來指定機器學習類別標籤特徵以供訓練用途，並且指導訓練資料組態檔案的建立。
匯出程序無法自動推斷哪些節點和邊緣屬性應該是機器學習類別標籤，以作為訓練用途的範例。它也無法自動推斷數值、類別和文字屬性的最佳特徵編碼，因此您需要使用 `additionalParams` 物件中的欄位提供提示，來指定這些項目或覆寫預設編碼。
對於屬性圖資料，匯出要求中 `additionalParams` 的最上層結構可能如下所示：
```
{
"command": "export-pg",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [ (an array of node and edge class label targets) ],
"features": [ (an array of node feature hints) ]
}
}
}
```
對於 RDF 資料，其最上層結構可能如下所示：
```
{
"command": "export-rdf",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [ (an array of node and edge class label targets) ]
}
}
}
```
您也可以使用 `jobs` 欄位來提供多個匯出組態：
```
{
"command": "export-pg",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams" : {
"neptune_ml" : {
"version": "v2.0",
"jobs": [
{
"name" : "(training data configuration name)",
"targets": [ (an array of node and edge class label targets) ],
"features": [ (an array of node feature hints) ]
},
{
"name" : "(another training data configuration name)",
"targets": [ (an array of node and edge class label targets) ],
"features": [ (an array of node feature hints) ]
}
]
}
}
}
```
# additionalParams 中 neptune\$1ml 欄位的最上層元素
## neptune\$1ml 中的版本元素
指定要產生的訓練資料組態版本。
(*選用*)，*類型*：字串，*預設值*：「v2.0」。
如果確實包含 `version`，請將其設為 `v2.0`。
## neptune\$1ml 中的任務欄位
包含訓練資料組態物件的陣列，每個物件都會定義資料處理工作，並包含：
+ **`name`** – 要建立的訓練資料組態名稱。
例如，名稱為「job-number-1」的訓練資料組態會產生一個名為 `job-number-1.json` 的訓練資料組態檔案。
+ **`targets`** – 節點和邊緣類別標籤目標的 JSON 陣列，這些目標代表供訓練用途的機器學習類別標籤。請參閱 [neptune\$1ml 物件中的目標欄位](machine-learning-neptune_ml-targets.md)。
+ **`features`** – 節點屬性特徵的 JSON 陣列。請參閱[neptune\$1ml 中的功能欄位](machine-learning-neptune_ml-features.md)。
# neptune\$1ml 物件中的目標欄位
JSON 訓練資料匯出組態中的 `targets` 欄位包含目標物件的陣列，這些物件會指定訓練任務，以及用於訓練此任務的機器學習類別標籤。目標物件的內容會有所不同，取決於您是在屬性圖資料還是 RDF 資料上進行訓練。
對於屬性圖節點分類和迴歸任務，陣列中的目標物件可能如下所示：
```
{
"node": "(node property-graph label)",
"property": "(property name)",
"type" : "(used to specify classification or regression)",
"split_rate": [0.8,0.2,0.0],
"separator": ","
}
```
對於屬性圖邊緣分類，迴歸或連結預測任務，它們可以如下所示：
```
{
"edge": "(edge property-graph label)",
"property": "(property name)",
"type" : "(used to specify classification, regression or link_prediction)",
"split_rate": [0.8,0.2,0.0],
"separator": ","
}
```
對於 RDF 分類和迴歸任務，陣列中的目標物件可能如下所示：
```
{
"node": "(node type of an RDF node)",
"predicate": "(predicate IRI)",
"type" : "(used to specify classification or regression)",
"split_rate": [0.8,0.2,0.0]
}
```
對於 RDF 連結預測任務，陣列中的目標物件可以如下所示：
```
{
"subject": "(source node type of an edge)",
"predicate": "(relation type of an edge)",
"object": "(destination node type of an edge)",
"type" : "link_prediction",
"split_rate": [0.8,0.2,0.0]
}
```
目標物件可以包含下列欄位：
**Contents**
+ [屬性圖目標欄位](#machine-learning-property-graph-neptune_ml-targets)
+ [節點](#machine-learning-property-graph-neptune_ml-targets-node)
+ [節點](#machine-learning-property-graph-neptune_ml-targets-edge)
+ [屬性](#machine-learning-property-graph-neptune_ml-targets-property)
+ [type](#machine-learning-property-graph-neptune_ml-targets-type)
+ [split\$1rate](#machine-learning-property-graph-neptune_ml-targets-split_rate)
+ [separator](#machine-learning-property-graph-neptune_ml-targets-separator)
+ [RDF 目標欄位](#machine-learning-RDF-neptune_ml-targets)
+ [節點](#machine-learning-RDF-neptune_ml-targets-node)
+ [subject](#machine-learning-RDF-neptune_ml-targets-subject)
+ [述詞](#machine-learning-RDF-neptune_ml-targets-predicate)
+ [object](#machine-learning-RDF-neptune_ml-targets-object)
+ [type](#machine-learning-RDF-neptune_ml-targets-type)
+ [split\$1rate](#machine-learning-RDF-neptune_ml-targets-split_rate)
## 屬性圖目標物件中的欄位
### 目標物件中的節點 （頂點） 欄位
目標節點 (頂點) 的屬性圖標籤。目標物件必須包含 `node` 元素或 `edge` 元素，但不能同時包含兩者。
`node` 可以採取單一值，如下所示：
```
"node": "Movie"
```
或者，在多標籤頂點的情況下，它可以採取值陣列，如下所示：
```
"node": ["Content", "Movie"]
```
### 屬性圖目標物件中的邊緣欄位
透過其起始節點標籤、自己的標籤及其結束節點標籤來指定目標邊緣。目標物件必須包含 `edge` 元素或 `node` 元素，但不能同時包含兩者。
`edge` 欄位的值是一個 JSON 陣列，由三個字串組成，這些字串代表起始節點的屬性圖標籤、邊緣本身的屬性圖標籤，以及結束節點的屬性圖標籤，如下所示：
```
"edge": ["Person_A", "knows", "Person_B"]
```
如果起始節點和/或結束節點有多個標籤，請以陣列括住它們，如下所示：
```
"edge": [ ["Admin", Person_A"], "knows", ["Admin", "Person_B"] ]
```
### 屬性圖目標物件中的屬性欄位
指定目標頂點或邊緣的屬性，如下所示：
```
"property" : "rating"
```
除了目標任務為連結預測時，此欄位都為必要的。
### 屬性圖目標物件中的類型欄位
指出要在 `node` 或 `edge` 上執行的目標任務類型，如下所示：
```
"type" : "regression"
```
節點支援的任務類型如下：
+ `classification`
+ `regression`
邊緣支援的任務類型如下：
+ `classification`
+ `regression`
+ `link_prediction`
此欄位為必填。
### 屬性圖目標物件中的 split\$1rate 欄位
(*選用*) 訓練、驗證和測試階段將分別使用的節點或邊緣比例估計。這些比例是以 JSON 陣列表示，該陣列由介於零與一之間的三個數字組成，加起來最多為 1：
```
"split_rate": [0.7, 0.1, 0.2]
```
如果您不提供選用`split_rate`欄位，預設的預估值是`[0.9, 0.1, 0.0]`用於分類和迴歸任務，以及`[0.9,0.05, 0.05]`用於連結預測任務。
### 屬性圖目標物件中的分隔符號欄位
(*選用*) 搭配分類任務使用。
`separator` 欄位會指定一個字元，用來在其用來將多個類別值儲存在字串中時，將目標屬性值分割為多個類別值。例如：
```
"separator": "|"
```
`separator` 欄位的存在表示任務是多目標分類任務。
## RDF 目標物件中的欄位
### RDF 目標物件中的節點欄位
定義目標節點的節點類型。與節點分類任務或節點迴歸任務搭配使用。RDF 中節點的節點類型，其定義方式如下：
```
node_id, , node_type
```
RDF `node` 只能採取單一值，如下所示：
```
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie"
```
### RDF 目標物件中的主旨欄位
對於連結預測任務，`subject` 定義目標邊緣的來源節點類型。
```
"subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director"
```
**注意**
對於連結預測任務，`subject` 應同時與 `predicate` 和 `object` 搭配使用。如果未提供這三個的任一個，則會將所有邊緣視為訓練目標。
### RDF 目標物件中的述詞欄位
對於節點分類和節點迴歸任務，`predicate` 定義要使用哪個常值資料做為目標節點的目標節點特徵。
```
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre"
```
**注意**
如果目標節點只有一個定義目標節點特徵的述詞，則可以省略 `predicate` 欄位。
對於連結預測任務，`predicate` 定義目標邊緣的關聯類型：
```
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/direct"
```
**注意**
對於連結預測任務，`predicate` 應同時與 `subject` 和 `object` 搭配使用。如果未提供這三個的任一個，則會將所有邊緣視為訓練目標。
### RDF 目標物件中的物件欄位
對於連結預測任務，`object` 定義目標邊緣的目的地節點類型：
```
"object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie"
```
**注意**
對於連結預測任務，`object` 應同時與 `subject` 和 `predicate` 搭配使用。如果未提供這三個的任一個，則會將所有邊緣視為訓練目標。
### RDF 目標物件中的類型欄位
指示要執行的目標任務類型，如下所示：
```
"type" : "regression"
```
RDF 資料支援的任務類型如下：
+ `link_prediction`
+ `classification`
+ `regression`
此欄位為必填。
### 屬性圖目標物件中的 `split_rate` 欄位
(*選用*) 訓練、驗證和測試階段將分別使用的節點或邊緣比例估計。這些比例是以 JSON 陣列表示，該陣列由介於零與一之間的三個數字組成，加起來最多為 1：
```
"split_rate": [0.7, 0.1, 0.2]
```
如果您未提供選用 `split_rate` 欄位，則預設估計值為 `[0.9, 0.1, 0.0]`。
# neptune\$1ml 中的功能欄位
屬性值和 RDF 常值有不同的格式和資料類型。若要在機器學習中實現良好的效能，必須將這些值轉換為稱為*特徵*的數值編碼。
Neptune ML 會執行特徵擷取和編碼，做為資料匯出和資料處理步驟的一部分，如 [Neptune ML 中的特徵編碼](machine-learning-feature-encoding.md) 中所述。
對於屬性圖資料集，匯出程序會自動針對字串屬性和包含多個值的數值屬性推斷 `auto` 特徵。對於包含單一值的數值屬性，它會推斷 `numerical` 特徵。對於日期屬性，它會推斷 `datetime` 特徵。
如果您想要覆寫自動推斷的特徵規格，或為屬性新增儲存貯體數值、TF-IDF、FastText 或 SBERT 規格，您可以使用特徵欄位控制特徵編碼。
**注意**
您只能使用 `features` 欄位來控制屬性圖資料的特徵規格，而不能控制 RDF 資料的特徵規格。
對於自由格式的文字，Neptune ML 可以使用數個不同的模型，將字串屬性值中的記號序列轉換為固定大小的實數值向量：
+ [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) – 使用 [fastText](https://fasttext.cc/) 編碼。對於使用 fastText 所支援五種語言的一種且只有一種的特徵，這是建議的編碼方式。
+ [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-sbert-features) – 使用[句子 BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT) 編碼模型。對於 `text_fasttext` 不支援的文字，這是建議的編碼方式。
+ [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) – 使用 [Google](https://code.google.com/archive/p/word2vec/) 最初發佈的 [Word2VEC](https://wikipedia.org/wiki/Word2vec) 演算法來編碼文字。Word2Vec 只支援英文。
+ [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) – 使用[詞頻-逆向文件頻率](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) 向量化程式來編碼文字。TF-IDF 編碼支援其他編碼不支援的統計特徵。
`features` 欄位包含節點屬性特徵的 JSON 陣列。陣列中的物件可以包含下列欄位：
**Contents**
+ [節點](#machine-learning-neptune_ml-features-node)
+ [節點](#machine-learning-neptune_ml-features-edge)
+ [屬性](#machine-learning-neptune_ml-features-property)
+ [type](#machine-learning-neptune_ml-feature-types)
+ [norm](#machine-learning-neptune_ml-features-norm)
+ [語言](#machine-learning-neptune_ml-features-language)
+ [max\$1length](#machine-learning-neptune_ml-features-max_length)
+ [separator](#machine-learning-neptune_ml-features-separator)
+ [range](#machine-learning-neptune_ml-features-range)
+ [bucket\$1cnt](#machine-learning-neptune_ml-features-bucket_cnt)
+ [slide\$1window\$1size](#machine-learning-neptune_ml-features-slide_window_size)
+ [imputer](#machine-learning-neptune_ml-features-imputer)
+ [max\$1features](#machine-learning-neptune_ml-features-max_features)
+ [min\$1df](#machine-learning-neptune_ml-features-min_df)
+ [ngram\$1range](#machine-learning-neptune_ml-features-ngram_range)
+ [datetime\$1parts](#machine-learning-neptune_ml-features-datetime_parts)
## 功能中的節點欄位
`node` 欄位指定特徵頂點的屬性圖標籤。例如：
```
"node": "Person"
```
如果一個頂點有多個標籤，請使用陣列來包含它們。例如：
```
"node": ["Admin", "Person"]
```
## 功能中的邊緣欄位
`edge` 欄位指定特徵邊緣的邊緣類型。邊緣類型由陣列組成，此陣列包含來源頂點的屬性圖標籤、邊緣的屬性圖標籤，以及目的地頂點的屬性圖標籤。指定邊緣特徵時，您必須提供全部三個值。例如：
```
"edge": ["User", "reviewed", "Movie"]
```
如果邊緣類型的來源或目標頂點有多個標籤，請使用另一個陣列來包含它們。例如：
```
"edge": [["Admin", "Person"]. "edited", "Post"]
```
## 功能中的屬性欄位
使用屬性參數來指定由 `node` 參數所識別之頂點的屬性。例如：
```
"property" : "age"
```
## 功能的類型欄位可能值
`type` 參數指定要定義的特徵類型。例如：
```
"type": "bucket_numerical"
```
**`type` 參數的可能值**
+ **`"auto"`** – 指定 Neptune ML 應該自動偵測屬性類型並套用適當的特徵編碼。`auto` 特徵也可以具有一個選用 `separator` 欄位。
請參閱 [Neptune ML 中的自動特徵編碼](machine-learning-feature-encoding.md#machine-learning-auto-encoding)。
+ **`"category"`** – 此特徵編碼將屬性值表示為數個類別的其中一個。換句話說，此特徵可以採取一個或多個離散值。`category` 特徵也可以具有一個選用 `separator` 欄位。
請參閱 [Neptune ML 中的類別特徵](machine-learning-feature-encoding.md#machine-learning-categorical-features)。
+ **`"numerical"`** – 此特徵編碼會將數值屬性值表示為連續間隔中的數字，其中「大於」和「小於」都有意義。
`numerical` 特徵也可以具有選用 `norm`、`imputer` 和 `separator` 欄位。
請參閱 [Neptune ML 中的數值特徵](machine-learning-feature-encoding.md#machine-learning-numerical-features)。
+ **`"bucket_numerical"`** – 此特徵編碼會將數值屬性值分成一組*儲存貯體*或類別。
例如，您可以將人們的年齡編碼為 4 個儲存貯體：小孩 (0-20)、年輕人 (20-40)、中年人 (40-60) 和長者 (60 歲以上)。
`bucket_numerical` 特徵需要 `range` 和 `bucket_cnt` 欄位，也可以選擇性地包含 `imputer` 和/或 `slide_window_size` 欄位。
請參閱 [Neptune ML 中的儲存貯體數值特徵](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
+ **`"datetime"`** – 此特徵編碼會將 datetime 屬性值表示為下列類別特徵的陣列：年、月、工作日和小時。
可以使用 `datetime_parts` 參數消除這四個類別中的一個或多個類別。
請參閱 [Neptune ML 中的日期時間特徵](machine-learning-feature-encoding.md#machine-learning-datetime-features)。
+ **`"text_fasttext"`** – 此特徵編碼會使用 [fastText](https://fasttext.cc/) 模型，將由句子或自由格式文字組成的屬性值轉換為數值向量。它支持五種語言，即英文 (`en`)、中文 (`zh`)、北印度文 (`hi`)、西班牙文 (`es`) 和法文 (`fr`)。對於這五種語言中任何一種的文字屬性值，`text_fasttext` 是建議的編碼方式。不過，它無法處理同一句子包含多種語言單字的情況。
對於 fastText 所支援語言以外的其他語言，請使用 `text_sbert` 編碼。
假設，如果您的屬性值文字字串長度超過 120 個記號，請使用 `max_length` 欄位來限制 `"text_fasttext"` 編碼的每個字串中的記號數目。
請參閱 [Neptune ML 中文字屬性值的 *fastText* 編碼](machine-learning-feature-encoding.md#machine-learning-fasttext-features)。
+ **`"text_sbert"`** – 此編碼會使用[句子 BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT) 模型，將文字屬性值轉換為數值向量。Neptune 支援兩種 SBERT 方法，即 `text_sbert128`，這是預設值，如果您僅指定 `text_sbert` 和 `text_sbert512` 的話。它們之間的差異在於進行編碼的文字屬性中的記號數目上限。`text_sbert128` 編碼僅會編碼前 128 個記號，而 `text_sbert512` 最多可編碼 512 個記號。因此，使用 `text_sbert512` 可能比 `text_sbert128` 需要更多的處理時間。這兩種方法都比 `text_fasttext` 慢。
`text_sbert*` 方法支援多種語言，而且可以編碼包含多種語言的句子。
請參閱 [Neptune ML 中文字特徵的句子 BERT (SBERT) 編碼](machine-learning-feature-encoding.md#machine-learning-sbert-features)。
+ **`"text_word2vec"`** – 此編碼會使用 [Word2VEC](https://wikipedia.org/wiki/Word2vec) 演算法，將文字屬性值轉換為數值向量。它僅支援英文。
請參閱 [Neptune ML 中文字特徵的 Word2Vec 編碼](machine-learning-feature-encoding.md#machine-learning-word2vec-features)。
+ **`"text_tfidf"`** – 此編碼會使用[詞頻-逆向文件頻率](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) 向量化程式，將文字屬性值轉換為數值向量。
您可以使用 `ngram_range` 欄位、`min_df` 欄位和 `max_features` 欄位來定義 `text_tfidf` 特徵編碼的參數。
請參閱 [Neptune ML 中文字特徵的 TF-IDF 編碼](machine-learning-feature-encoding.md#machine-learning-tfidf-features)。
+ **`"none"`** – 使用 `none` 類型會導致不發生任何特徵編碼。反而會剖析並儲存原始屬性值。
僅在您計劃執行自己的自訂特徵編碼，做為自訂模型訓練的一部分時，才會使用 `none`。
## 標準欄位
數值特徵需要此欄位。它會指定要在數值上使用的標準化方法：
```
"norm": "min-max"
```
支援以下標準化方法：
+ **「min-max」** – 透過從中減去最小值，然後將其除以最大值與最小值之間的差值來標準化每個值。
+ **「standard」** – 將每個值除以所有值的總和來標準化這些值。
+ **「none」** – 不要在編碼期間標準化數值。
請參閱 [Neptune ML 中的數值特徵](machine-learning-feature-encoding.md#machine-learning-numerical-features)。
## 語言欄位
語言欄位會指定文字屬性值中使用的語言。它的用法取決於文字編碼方法：
+ 對於 [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) 編碼，此欄位是必要的，且必須指定下列其中一種語言：
+ `en` (英文)
+ `zh` (中文)
+ `hi` (北印度文)
+ `es` (西班牙文)
+ `fr` (法文)
+ 對於 [`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"
```
+ 對於 [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) 編碼，不會使用此欄位。
## max\$1length 欄位
`max_length` 欄位是 `text_fasttext` 特徵的選用欄位，其中指定將編碼之輸入文字特徵中的記號數目上限。長度超過 `max_length` 的輸入文字會被截斷。例如，將 max\$1length 設定為 128，表示將忽略文字序列中第 128 之後的任何記號：
```
"max_length": 128
```
## 分隔符號欄位
此欄位可選擇性地與 `category`、`numerical` 和 `auto` 特徵搭配使用。它會指定一個字元，其可以用來將屬性值分成多個類別值或數值：
```
"separator": ";"
```
僅在屬性將多個分隔值儲存在單一字串 (例如 `"Actor;Director"` 或 `"0.1;0.2"`) 中時，才會使用 `separator` 欄位。
請參閱[類別功能](machine-learning-feature-encoding.md#machine-learning-categorical-features)、[數值特徵](machine-learning-feature-encoding.md#machine-learning-numerical-features)和[自動編碼](machine-learning-feature-encoding.md#machine-learning-auto-encoding)。
## 範圍欄位
`bucket_numerical` 特徵需要此欄位。它會指定要分成儲存貯體的數值範圍，格式為 `[lower-bound, upper-bound]`：
```
"range" : [20, 100]
```
如果屬性值小於下限，則會將其指派給第一個儲存貯體，或者如果它大於上限，則會將其指派給最後一個儲存貯體。
請參閱 [Neptune ML 中的儲存貯體數值特徵](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
## bucket\$1cnt 欄位
`bucket_numerical` 特徵需要此欄位。它會指定由 `range` 參數定義的數值範圍應分成的儲存貯體數目：
```
"bucket_cnt": 10
```
請參閱 [Neptune ML 中的儲存貯體數值特徵](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
## slide\$1window\$1size 欄位
此欄位可選擇性地搭配 `bucket_numerical` 特徵使用，以將值指派給多個儲存貯體：
```
"slide_window_size": 5
```
滑動視窗的運作方式是 Neptune ML 採取視窗大小 **`s`**，並將屬性的每個數值 **`v`** 轉換為從 ` v - s/2 ` 到 ` v + s/2 ` 的範圍。然後，此值會指定給範圍重疊的每個儲存貯體。
請參閱 [Neptune ML 中的儲存貯體數值特徵](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
## imputer 欄位
此欄位可選擇搭配 `numerical` 和 `bucket_numerical` 特徵使用，以提供填入缺失值的插補技術：
```
"imputer": "mean"
```
支援的插補技術如下：
+ `"mean"`
+ `"median"`
+ `"most-frequent"`
如果您未包含 imputer 參數，資料預先處理會在遇到缺失值時停止並結束。
請參閱 [Neptune ML 中的數值特徵](machine-learning-feature-encoding.md#machine-learning-numerical-features) 和 [Neptune ML 中的儲存貯體數值特徵](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
## max\$1features 欄位
此欄位是 `text_tfidf` 特徵可選擇性地用來指定要編碼的詞數上限：
```
"max_features": 100
```
設定為 100 會導致 TF-IDF 向量化程式只編碼 100 個最常見的字詞。如果未包含 `max_features`，則預設值為 5,000。
請參閱 [Neptune ML 中文字特徵的 TF-IDF 編碼](machine-learning-feature-encoding.md#machine-learning-tfidf-features)。
## min\$1df 欄位
`text_tfidf` 特徵可選擇性地使用此欄位，來指定要編碼之字詞的文件頻率上限：
```
"min_df": 5
```
設定 5 表示字詞必須出現在至少 5 個不同的屬性值中，才能進行編碼。
如果您未包含 `min_df` 參數，預設值為 `2`。
請參閱 [Neptune ML 中文字特徵的 TF-IDF 編碼](machine-learning-feature-encoding.md#machine-learning-tfidf-features)。
## ngram\$1range 欄位
`text_tfidf` 特徵可選擇性地使用此欄位，指定應將單字或記號的哪些大小序列視為要編碼的潛在個別字詞：
```
"ngram_range": [2, 4]
```
值 `[2, 4]` 指定 2、3 和 4 個單字的序列應被視為潛在的個別字詞。
如果您沒有明確設定 `ngram_range`，則預設值為 `[1, 1]`，這表示只有單一單字或記號會被視為要編碼的字詞。
請參閱 [Neptune ML 中文字特徵的 TF-IDF 編碼](machine-learning-feature-encoding.md#machine-learning-tfidf-features)。
## datetime\$1parts 欄位
`datetime` 特徵可選擇性地使用此欄位，來指定要以分類方式編碼 datetime 值的哪些部分：
```
"datetime_parts": ["weekday", "hour"]
```
如果您未包含 `datetime_parts`，Neptune ML 預設會編碼 datetime 值的年、月、工作日和小時部分。值 `["weekday", "hour"]` 表示只有 datetime 值的工作日和小時應在特徵中進行分類編碼。
如果其中一個部分在訓練集中沒有多個唯一值，則不會對其進行編碼。
請參閱[Neptune ML 中的日期時間特徵](machine-learning-feature-encoding.md#machine-learning-datetime-features)。
# 在 additionalParams 中使用參數來調校模型訓練組態的範例
下列範例示範如何在屬性圖和 RDF 資料模型中使用「additionalParams」功能，為 Neptune ML 應用程式設定模型訓練程序的各個層面。這些範例涵蓋各種功能，包括指定training/validation/test資料的預設分割率、定義節點分類、迴歸和連結預測任務，以及設定不同的特徵類型，例如數值儲存貯體、文字內嵌、日期時間和分類資料。這些詳細組態可讓您根據特定資料和建模需求量身打造機器學習管道，釋放 Neptune ML 功能的完整潛力。
**Contents**
+ [使用 additionalParams 的屬性圖範例](#machine-learning-property-graph-additionalParams-examples)
+ [為模型訓練組態指定預設分割率](#machine-learning-property-graph-additionalParams-default-split-rate-example)
+ [為模型訓練組態指定節點分類任務](#machine-learning-property-graph-additionalParams-node-classification-example)
+ [為模型訓練組態指定多類別節點分類任務](#machine-learning-property-graph-additionalParams-multi-class-example)
+ [為模型訓練組態指定節點迴歸任務](#machine-learning-property-graph-additionalParams-node-regression-example)
+ [為模型訓練組態指定 edge-classification 任務](#machine-learning-property-graph-additionalParams-edge-classification-example)
+ [為模型訓練組態指定多類別邊緣分類任務](#machine-learning-property-graph-additionalParams-multi-edge-classification-example)
+ [為模型訓練組態指定邊緣迴歸](#machine-learning-property-graph-additionalParams-edge-regression-example)
+ [為模型訓練組態指定連結預測任務](#machine-learning-property-graph-additionalParams-link-prediction-example)
+ [指定數值儲存貯體特徵](#machine-learning-property-graph-additionalParams-numeric-bucket-example)
+ [指定 `Word2Vec` 特徵](#machine-learning-property-graph-additionalParams-word2vec-example)
+ [指定 `FastText` 特徵](#machine-learning-property-graph-additionalParams-fasttext-example)
+ [指定 `Sentence BERT` 特徵](#machine-learning-property-graph-additionalParams-sbert-example)
+ [指定 `TF-IDF` 特徵](#machine-learning-property-graph-additionalParams-tf-idf-example)
+ [指定 `datetime` 特徵](#machine-learning-property-graph-additionalParams-datetime-example)
+ [指定 `category` 特徵](#machine-learning-property-graph-additionalParams-category-example)
+ [指定 `numerical` 特徵](#machine-learning-property-graph-additionalParams-numerical-example)
+ [指定 `auto` 特徵](#machine-learning-property-graph-additionalParams-auto-example)
+ [使用 `additionalParams` 的 RDF 範例](#machine-learning-RDF-additionalParams-examples)
+ [為模型訓練組態指定預設分割率](#machine-learning-RDF-additionalParams-default-split-rate-example)
+ [為模型訓練組態指定節點分類任務](#machine-learning-RDF-additionalParams-node-classification-example)
+ [為模型訓練組態指定節點迴歸任務](#machine-learning-RDF-additionalParams-node-regression-example)
+ [為特定邊緣指定連結預測任務](#machine-learning-RDF-additionalParams-link-prediction-example)
+ [為所有邊緣指定連結預測任務](#machine-learning-RDF-additionalParams-link-prediction-example)
## 使用 additionalParams 的屬性圖範例
### 為模型訓練組態指定預設分割率
在下列範例中，`split_rate` 參數會設定模型訓練的預設分割率。如果未指定預設分割率，則訓練會使用 [0.9, 0.1, 0.0] 的值。您可以透過為每個目標指定 `split_rate`，覆寫每個目標上的預設值。
在下列範例中，`default split_rate` 欄位指示除非針對每個目標進行覆寫，否則應使用 `[0.7,0.1,0.2]` 的分割率：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"split_rate": [0.7,0.1,0.2],
"targets": [
(...)
],
"features": [
(...)
]
}
}
```
### 為模型訓練組態指定節點分類任務
若要指示哪個節點屬性包含標記的範例可供訓練用途，請使用 `"type" : "classification"` 將節點分類元素新增至 `targets` 陣列。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
在下列範例中，`node` 目標會指示應將每個 `Movie` 節點的 `genre` 屬性視為節點類別標籤。`split_rate` 值會覆寫預設分割率：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "genre",
"type": "classification",
"split_rate": [0.7,0.1,0.2]
}
],
"features": [
(...)
]
}
}
```
### 為模型訓練組態指定多類別節點分類任務
若要指示哪個節點屬性包含多個標記的範例可供訓練用途，請使用 `"type" : "classification"` 和 `separator` 將節點分類元素新增至目標陣列，來指定可以用來將目標屬性值分割為多個類別值的字元。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
在下列範例中，`node` 目標會指示應將每個 `Movie` 節點的 `genre` 屬性視為節點類別標籤。`separator` 欄位指示每個類型屬性包含多個分號分隔值：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "genre",
"type": "classification",
"separator": ";"
}
],
"features": [
(...)
]
}
}
```
### 為模型訓練組態指定節點迴歸任務
若要指示哪個節點屬性包含用於訓練用途的標記迴歸，請使用 `"type" : "regression"` 將節點迴歸元素新增至陣列。如果想要覆寫預設分割率，請新增 split\$1rate 欄位。
下列 `node` 目標指示應將每個 `Movie` 節點的 `rating` 屬性視為節點迴歸標籤。
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "rating",
"type" : "regression",
"split_rate": [0.7,0.1,0.2]
}
],
"features": [
...
]
}
}
```
### 為模型訓練組態指定 edge-classification 任務
若要指示哪個邊緣屬性包含用於訓練用途的標記範例，請使用 `"type" : "regression"` 將邊緣元素新增至 `targets` 陣列。如果想要覆寫預設分割率，請新增 split\$1rate 欄位。
下列 `edge` 目標指示應將每個 `knows` 邊緣的 `metAtLocation` 屬性視為迴歸類別標籤：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Person", "knows", "Person"],
"property": "metAtLocation",
"type": "classification"
}
],
"features": [
(...)
]
}
}
```
### 為模型訓練組態指定多類別邊緣分類任務
若要指示哪個邊緣屬性包含多個用於訓練用途的標記範例，請使用 `"type" : "classification"` 和 `separator` 欄位將邊緣元素新增至 `targets` 陣列，來指定用來將目標屬性值分割為多個類別值的字元。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
下列 `edge` 目標指示應將每個 `repliedTo` 邊緣的 `sentiment` 屬性視為迴歸類別標籤。分隔符號欄位會指示每個情緒屬性都包含多個逗號分隔值：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Person", "repliedTo", "Message"],
"property": "sentiment",
"type": "classification",
"separator": ","
}
],
"features": [
(...)
]
}
}
```
### 為模型訓練組態指定邊緣迴歸
若要指示哪個邊緣屬性包含用於訓練用途的標記迴歸範例，請使用 `"type" : "regression"` 將 `edge` 元素新增至 `targets` 陣列。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
下列 `edge` 目標指示應將每個 `reviewed` 邊緣的 `rating` 屬性視為邊緣迴歸：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Person", "reviewed", "Movie"],
"property": "rating",
"type" : "regression"
}
],
"features": [
(...)
]
}
}
```
### 為模型訓練組態指定連結預測任務
若要指示應將哪些邊緣用於連結預測訓練用途，請使用 `"type" : "link_prediction"` 將邊緣元素新增至目標陣列。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
下列 `edge` 目標指示應該使用 `cites` 邊緣進行連結預測：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Article", "cites", "Article"],
"type" : "link_prediction"
}
],
"features": [
(...)
]
}
}
```
### 指定數值儲存貯體特徵
您可以透過將 `"type": "bucket_numerical"` 新增至 `features` 陣列來為節點屬性指定數值資料特徵。
下列 `node` 特徵指示應將每個 `Person` 節點的 `age` 屬性視為數值儲存貯體特徵：
```
"additionalParams": {
"neptune_ml": {
"targets": [
...
],
"features": [
{
"node": "Person",
"property": "age",
"type": "bucket_numerical",
"range": [1, 100],
"bucket_cnt": 5,
"slide_window_size": 3,
"imputer": "median"
}
]
}
}
```
### 指定 `Word2Vec` 特徵
您可以透過將 `"type": "text_word2vec"` 新增至 `features` 陣列來為節點屬性指定 `Word2Vec` 特徵。
下列 `node` 特徵指示應將每個 `Movie` 節點的 `description` 屬性視為 `Word2Vec` 特徵：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "description",
"type": "text_word2vec",
"language": "en_core_web_lg"
}
]
}
}
```
### 指定 `FastText` 特徵
您可以透過將 `"type": "text_fasttext"` 新增至 `features` 陣列來為節點屬性指定 `FastText` 特徵。`language` 欄位為必要的，且必須指定下列其中一個語言代碼：
+ `en` (英文)
+ `zh` (中文)
+ `hi` (北印度文)
+ `es` (西班牙文)
+ `fr` (法文)
請注意，`text_fasttext` 編碼無法在特徵中一次處理多種語言。
下列 `node` 特徵指示應將每個 `Movie` 節點的法文 `description` 屬性視為 `FastText` 特徵：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "description",
"type": "text_fasttext",
"language": "fr",
"max_length": 1024
}
]
}
}
```
### 指定 `Sentence BERT` 特徵
您可以透過將 `"type": "text_sbert"` 新增至 `features` 陣列來為節點屬性指定 `Sentence BERT` 特徵。您不需要指定語言，因為方法會使用多語系模型自動編碼文字特徵。
下列 `node` 特徵指示應將每個 `Movie` 節點的 `description` 屬性視為 `Sentence BERT` 特徵：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "description",
"type": "text_sbert128",
}
]
}
}
```
### 指定 `TF-IDF` 特徵
您可以透過將 `"type": "text_tfidf"` 新增至 `features` 陣列來為節點屬性指定 `TF-IDF` 特徵。
下列 `node` 特徵指示應將每個 `Person` 節點的 `bio` 屬性視為 `TF-IDF` 特徵：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "bio",
"type": "text_tfidf",
"ngram_range": [1, 2],
"min_df": 5,
"max_features": 1000
}
]
}
}
```
### 指定 `datetime` 特徵
匯出程序會自動推斷日期屬性的 `datetime` 特徵。不過，如果要限制用於 `datetime` 特徵的 `datetime_parts`，或覆寫特徵規格，以便將通常被視為 `auto` 特徵的屬性明確地視為 `datetime` 特徵，則您可以透過將特徵陣列新增至 `"type": "datetime"` 來執行此操作。
下列 `node` 特徵指示應將每個 `Post` 節點的 `createdAt` 屬性視為 `datetime` 特徵：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Post",
"property": "createdAt",
"type": "datetime",
"datetime_parts": ["month", "weekday", "hour"]
}
]
}
}
```
### 指定 `category` 特徵
匯出程序會自動針對字串屬性和包含多個值的數值屬性推斷 `auto` 特徵。對於包含單一值的數值屬性，它會推斷 `numerical` 特徵。對於日期屬性，它會推斷 `datetime` 特徵。
如果您想要覆寫特徵規格，以便將屬性視為類別特徵，請將 `"type": "category"` 新增至特徵陣列。如果屬性包含多個值，請包括一個 `separator` 欄位。例如：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Post",
"property": "tag",
"type": "category",
"separator": "|"
}
]
}
}
```
### 指定 `numerical` 特徵
匯出程序會自動針對字串屬性和包含多個值的數值屬性推斷 `auto` 特徵。對於包含單一值的數值屬性，它會推斷 `numerical` 特徵。對於日期屬性，它會推斷 `datetime` 特徵。
如果您想要覆寫特徵規格，以便將屬性視為 `numerical` 特徵，請將 `"type": "numerical"` 新增至特徵陣列。如果屬性包含多個值，請包括一個 `separator` 欄位。例如：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Recording",
"property": "duration",
"type": "numerical",
"separator": ","
}
]
}
}
```
### 指定 `auto` 特徵
匯出程序會自動針對字串屬性和包含多個值的數值屬性推斷 `auto` 特徵。對於包含單一值的數值屬性，它會推斷 `numerical` 特徵。對於日期屬性，它會推斷 `datetime` 特徵。
如果您想要覆寫特徵規格，以便將屬性視為 `auto` 特徵，請將 `"type": "auto"` 新增至特徵陣列。如果屬性包含多個值，請包括一個 `separator` 欄位。例如：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "User",
"property": "role",
"type": "auto",
"separator": ","
}
]
}
}
```
## 使用 `additionalParams` 的 RDF 範例
### 為模型訓練組態指定預設分割率
在下列範例中，`split_rate` 參數會設定模型訓練的預設分割率。如果未指定預設分割率，則訓練會使用 [0.9, 0.1, 0.0] 的值。您可以透過為每個目標指定 `split_rate`，覆寫每個目標上的預設值。
在下列範例中，`default split_rate` 欄位指示除非針對每個目標進行覆寫，否則應使用 `[0.7,0.1,0.2]` 的分割率：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"split_rate": [0.7,0.1,0.2],
"targets": [
(...)
]
}
}
```
### 為模型訓練組態指定節點分類任務
若要指示哪個節點屬性包含訓練用途的標記範例，請使用 `"type" : "classification"` 將節點分類元素新增至 `targets` 陣列。新增節點欄位以指示目標節點的節點類型。新增 `predicate` 欄位以定義使用哪個常值資料做為目標節點的目標節點特徵。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
在下列範例中，`node` 目標會指示應將每個 `Movie` 節點的 `genre` 屬性視為節點類別標籤。`split_rate` 值會覆寫預設分割率：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre",
"type": "classification",
"split_rate": [0.7,0.1,0.2]
}
]
}
}
```
### 為模型訓練組態指定節點迴歸任務
若要指示哪個節點屬性包含用於訓練用途的標記迴歸，請使用 `"type" : "regression"` 將節點迴歸元素新增至陣列。新增 `node` 欄位以指示目標節點的節點類型。新增 `predicate` 欄位以定義使用哪個常值資料做為目標節點的目標節點特徵。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
下列 `node` 目標指示應將每個 `Movie` 節點的 `rating` 屬性視為節點迴歸標籤。
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/rating",
"type": "regression",
"split_rate": [0.7,0.1,0.2]
}
]
}
}
```
### 為特定邊緣指定連結預測任務
若要指示應將哪些邊緣用於連結預測訓練用途，請使用 `"type" : "link_prediction"` 將邊緣元素新增至目標陣列。新增 `subject`、`predicate` 和 `object` 欄位以指定邊緣類型。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
下列 `edge` 目標指示將 `Directors` 連線至 `Movies` 的 `directed` 邊緣應該用於連結預測：
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/directed",
"object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"type" : "link_prediction"
}
]
}
}
```
### 為所有邊緣指定連結預測任務
若要指示應將所有邊緣用於連結預測訓練用途，請使用 `"type" : "link_prediction"` 將 `edge` 元素新增至目標陣列。請不要新增 `subject`、`predicate` 或 `object` 欄位。如果想要覆寫預設分割率，請新增 `split_rate` 欄位。
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"type" : "link_prediction"
}
]
}
}
```