本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 neptune-export 工具或 Neptune-Export 服务从 Neptune 导出数据用于 Neptune ML
Neptune ML 要求您为[深度图表库 (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)中所述，导出请求中的 `params` 对象可以包含各种字段。以下字段与导出机器学习训练数据最为相关：
****
+ **`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 中的 jobs 字段
包含训练数据配置对象的数组，其中每个对象都定义了一个数据处理任务，并包含：
+ **`name`** – 要创建的训练数据配置的名称。
例如，名为“job-number-1”的训练数据配置会生成名为 `job-number-1.json` 的训练数据配置文件。
+ **`targets`** – 由节点和边缘类别标签目标组成的 JSON 数组，代表用于训练目的的机器学习类别标签。请参阅[neptune\$1ml 对象中的 targets 字段](machine-learning-neptune_ml-targets.md)。
+ **`features`**– 节点属性特征的 JSON 数组。请参阅[neptune\$1ml 中的 features 字段](machine-learning-neptune_ml-features.md)。
# neptune\$1ml 对象中的 targets 字段
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**
+ [property-graph 目标字段](#machine-learning-property-graph-neptune_ml-targets)
+ [节点](#machine-learning-property-graph-neptune_ml-targets-node)
+ [边缘](#machine-learning-property-graph-neptune_ml-targets-edge)
+ [property](#machine-learning-property-graph-neptune_ml-targets-property)
+ [类型](#machine-learning-property-graph-neptune_ml-targets-type)
+ [split\$1rate](#machine-learning-property-graph-neptune_ml-targets-split_rate)
+ [分隔符](#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)
+ [类型](#machine-learning-RDF-neptune_ml-targets-type)
+ [split\$1rate](#machine-learning-RDF-neptune_ml-targets-split_rate)
## property-graph 目标对象中的字段
### 目标对象中的 node（顶点）字段
目标节点（顶点）的属性图标签。目标对象必须包含一个 `node` 元素或一个 `edge` 元素，但不能同时包含两者。
`node` 可以取一个单一值，如下所示：
```
"node": "Movie"
```
或者，对于多标签顶点，它可以采用一个值数组，如下所示：
```
"node": ["Content", "Movie"]
```
### property-graph 目标对象中的 edge 字段
通过目标边缘的起始节点标签、其自己的标签和其结束节点标签来指定目标边缘。目标对象必须包含一个 `edge` 元素或一个 `node` 元素，但不能同时包含两者。
`edge` 字段的值是一个由三个字符串组成的 JSON 数组，这些字符串代表起始节点的属性图标签、边缘本身的属性图标签和结束节点的属性图标签，如下所示：
```
"edge": ["Person_A", "knows", "Person_B"]
```
如果起始节点 and/or 结束节点有多个标签，请将它们封装在数组中，如下所示：
```
"edge": [ ["Admin", Person_A"], "knows", ["Admin", "Person_B"] ]
```
### property-graph 目标对象中的 property 字段
指定目标顶点或边缘的属性，如下所示：
```
"property" : "rating"
```
除非目标任务是链接预测，否则此字段为必需字段。
### property-graph 目标对象中的 type 字段
表示要在 `node` 或 `edge` 上执行的目标任务的类型，如下所示：
```
"type" : "regression"
```
节点支持的任务类型有：
+ `classification`
+ `regression`
边缘支持的任务类型有：
+ `classification`
+ `regression`
+ `link_prediction`
该字段为必填。
### property-graph 目标对象中的 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]` 适用于链接预测任务。
### property-graph 目标对象中的 separator 字段
（*可选*）与分类任务一起使用。
`separator` 字段指定一个字符，当它用于在字符串中存储多个类别值时，用来将目标属性值拆分为多个类别值。例如：
```
"separator": "|"
```
`separator` 字段的存在表示该任务是一项多目标分类任务。
## RDF 目标对象中的字段
### RDF 目标对象中的 node 字段
定义目标节点的节点类型。与节点分类任务或节点回归任务一起使用。RDF 中节点的节点类型定义如下：
```
node_id, , node_type
```
RDF `node` 只能取一个值，如下所示：
```
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie"
```
### RDF 目标对象中的 subject 字段
对于链接预测任务，`subject` 定义目标边缘的源节点类型。
```
"subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director"
```
**注意**
对于链接预测任务，`subject` 应与 `predicate` 和 `object` 一起使用。如果未提供这三者中的任何一个，则所有边缘都将被视为训练目标。
### RDF 目标对象中的 predicate 字段
对于节点分类和节点回归任务，`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` 定义目标边缘的目标节点类型：
```
"object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie"
```
**注意**
对于链接预测任务，`object` 应与 `subject` 和 `predicate` 一起使用。如果未提供这三者中的任何一个，则所有边缘都将被视为训练目标。
### RDF 目标对象中的 type 字段
表示要执行的目标任务的类型，如下所示：
```
"type" : "regression"
```
RDF 数据支持的任务类型有：
+ `link_prediction`
+ `classification`
+ `regression`
该字段为必填。
### property-graph 目标对象中的 `split_rate` 字段
（*可选*）训练、验证和测试阶段将分别使用的节点或边缘的比例的估计值。这些比例由 JSON 数组表示，该数组包含介于零和一之间的三个数字，这些数字加起来为 1：
```
"split_rate": [0.7, 0.1, 0.2]
```
如果您未提供可选 `split_rate` 字段，则默认估计值为 `[0.9, 0.1, 0.0]`。
# neptune\$1ml 中的 features 字段
属性值和 RDF 文本值有不同的格式和数据类型。为了在机器学习中获得良好的性能，务必将这些值转换为称为*特征*的数字编码。
Neptune ML 在数据导出和数据处理步骤中执行特征提取和编码，如[Neptune ML 中的特征编码](machine-learning-feature-encoding.md)中所述。
对于属性图数据集，导出过程会自动推理字符串属性和包含多个值的数值属性的 `auto` 特征。对于包含单个值的数值属性，它会推理 `numerical` 特征。对于日期属性，它会推理 `datetime` 特征。
如果要覆盖自动推断的功能规范，或者要为属性添加存储桶数字、TF-IDF 或 SBERT 规范，则可以使用功能字段控制特征编码。 FastText
**注意**
您只能使用 `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)
+ [property](#machine-learning-neptune_ml-features-property)
+ [类型](#machine-learning-neptune_ml-feature-types)
+ [norm](#machine-learning-neptune_ml-features-norm)
+ [language](#machine-learning-neptune_ml-features-language)
+ [max\$1length](#machine-learning-neptune_ml-features-max_length)
+ [分隔符](#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` 字段指定特征顶点的属性图标签。例如：
```
"node": "Person"
```
如果顶点有多个标签，则使用数组来包含它们。例如：
```
"node": ["Admin", "Person"]
```
## 特征中的 edge 字段
`edge` 字段指定特征边缘的边缘类型。边缘类型由一个数组组成，该数组包含源顶点的属性图标签、边缘的属性图标签和目标顶点的属性图标签。指定边缘特征时，必须提供所有三个值。例如：
```
"edge": ["User", "reviewed", "Movie"]
```
如果边缘类型的源顶点或目标顶点有多个标签，请使用另一个数组来包含它们。例如：
```
"edge": [["Admin", "Person"]. "edited", "Post"]
```
## 特征中的 property 字段
使用 property 参数指定由 `node` 参数标识的顶点的属性。例如：
```
"property" : "age"
```
## 特征的 type 字段的可能值
`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` and/or `slide_window_size`字段。
请参阅[Neptune ML 中的桶数值特征](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)。
+ **`"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 字段。
此字段是数字特征的必需字段。它指定了一种用于数值的规范化方法：
```
"norm": "min-max"
```
支持以下规范化方法：
+ **“min-max”**– 通过从每个值中减去最小值，然后将其除以最大值和最小值之间的差值来规范化每个值。
+ **“standard”**- 通过将每个值除以所有值的总和来对其进行规范化。
+ **“none”**- 在编码过程中不对数值进行规范化。
请参阅[Neptune ML 中的数值特征](machine-learning-feature-encoding.md#machine-learning-numerical-features)。
## language 字段
语言字段指定文本属性值中使用的语言。它的用法取决于文本编码方法：
+ 对于 [`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 字段
对于 `text_fasttext` 特征，`max_length` 字段是可选的，它指定输入文本特征中要编码的最大令牌数。长度大于 `max_length` 的输入文本会被截断。例如，将 max\$1length 设置为 128，表示将忽略文本序列中第 128 个之后的任何令牌：
```
"max_length": 128
```
## separator 字段
此字段可选择性地与 `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)。
## range 字段
此字段是 `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`，则默认值为 5000。
请参阅[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_parts": ["weekday", "hour"]
```
如果不包括 `datetime_parts`，则默认情况下，Neptune ML 会对日期时间值的年、月、工作日和小时部分进行编码。值 `["weekday", "hour"]` 表示只应在该特征中对日期时间值的工作日和小时进行分类编码。
如果其中一个部分在训练集中没有多个唯一值，则不会对其进行编码。
请参阅[Neptune ML 中的日期时间特征](machine-learning-feature-encoding.md#machine-learning-datetime-features)。
# 使用 additionalParams 中的参数调整模型训练配置的示例
以下示例演示了如何利用 property-graph 中的“additionalParams”功能和 RDF 数据模型为 Neptune ML 应用程序配置模型训练过程的各个方面。这些示例涵盖了广泛的功能，包括指定training/validation/test数据的默认拆分率、定义节点分类、回归和链接预测任务，以及配置不同的特征类型，例如数字存储桶、文本嵌入、日期时间和分类数据。这些详细的配置使您可以根据自己的特定数据和建模要求定制机器学习管道，从而充分发挥 Neptune ML 功能的潜力。
**Contents**
+ [使用 additionalParams 的 property-graph 示例](#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)
+ [为模型训练配置指定边缘分类任务](#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 的 property-graph 示例
### 为模型训练配置指定默认分割率
在以下示例中，`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": [
...
]
}
}
```
### 为模型训练配置指定边缘分类任务
要指明哪个边缘属性包含用于训练目的的带标签的示例，请使用 `"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"` 向 `targets` 数组中添加 `edge` 元素。如果您想覆盖默认分割率，则可添加 `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"
}
]
}
}
```