配置管道

此功能处于 alpha 阶段。有关功能阶段的更多信息，请参阅 API 阶段。

此页面说明如何创建和配置节点回归管道。

创建管道

构建新管道的第一步是使用 gds.alpha.pipeline.nodeRegression.create 创建一个。这将一个可训练的管道对象存储在类型为 节点回归训练管道 的管道目录中。这表示一个可配置的管道，稍后可以调用它进行训练，进而创建一个回归模型。后者是一个存储在类型为 NodeRegression 的目录中的模型。

语法

创建管道语法

CALL gds.alpha.pipeline.nodeRegression.create(
  pipelineName: String
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: List of Map

表 1. 参数
名称	类型	描述
pipelineName	字符串	创建的管道的名称。

表 2. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

示例

以下将创建一个管道

CALL gds.alpha.pipeline.nodeRegression.create('pipe')

表 3. 结果
name	nodePropertySteps	featureProperties	splitConfig	autoTuningConfig	parameterSpace
"pipe"	[]	[]	{testFraction=0.3, validationFolds=3}	{maxTrials=10}	{LinearRegression=[], RandomForest=[]}

这表明新创建的管道尚不包含任何步骤，并且对拆分和训练参数具有默认值。

添加节点属性

节点回归管道可以在变异模式下执行一个或多个 GDS 算法，这些算法在内存图中创建节点属性。此类生成节点属性的步骤可以一个接一个地链接，并且以后可以将创建的属性用作特征。此外，添加到训练管道中的节点属性步骤将在训练模型时以及回归管道用于回归时执行。

要添加的过程的名称可以是完全限定的 GDS 过程名称，以.mutate结尾。可以省略结尾.mutate，也可以使用简写形式，例如node2vec代替gds.node2vec.mutate。但请注意，层级限定符必须作为名称的一部分给出。

例如，可以将预处理算法用作节点属性步骤。

语法

添加节点属性语法

CALL gds.alpha.pipeline.nodeRegression.addNodeProperty(
  pipelineName: String,
  procedureName: String,
  procedureConfiguration: Map
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: List of Map

表 4. 参数
名称	类型	描述
pipelineName	字符串	管道的名称。
procedureName	字符串	要添加到管道中的过程的名称。
procedureConfiguration	映射	用于生成节点属性过程配置的映射。它支持所有特定于过程的配置，不包括参数`nodeLabels`和`relationshipTypes`。此外，它还支持下表中列出的上下文参数。

表 5. 节点属性步骤上下文配置
名称	类型	默认值	描述
contextNodeLabels	字符串列表	`[]`	作为上下文添加的其他节点标签。
contextRelationshipTypes	字符串列表	`[]`	作为上下文添加的其他关系类型。

在训练期间，上下文配置与训练配置相结合，为每个节点属性步骤生成最终的节点标签和关系类型过滤器。

表 6. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

示例

以下操作将向管道添加节点属性步骤。这里我们假设输入图包含一个属性sizePerStory。

CALL gds.alpha.pipeline.nodeRegression.addNodeProperty('pipe', 'scaleProperties', {
  nodeProperties: 'sizePerStory',
  scaler: 'MinMax',
  mutateProperty:'scaledSizes'
}) YIELD name, nodePropertySteps

表 7. 结果
name	nodePropertySteps
"pipe"	[{config={contextNodeLabels=[], contextRelationshipTypes=[], mutateProperty="scaledSizes", nodeProperties="sizePerStory", scaler="MinMax"}, name="gds.scaleProperties.mutate"}]

scaledSizes属性稍后可用作特征。

添加特征

节点回归管道允许您选择可用节点属性的子集，将其用作机器学习模型的特征。执行管道时，所选的nodeProperties必须存在于输入图中，或由先前的节点属性步骤创建。

语法

向管道添加特征语法

CALL gds.alpha.pipeline.nodeRegression.selectFeatures(
  pipelineName: String,
  featureProperties: List or String
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: List of Map

表 8. 参数
名称	类型	描述
pipelineName	字符串	管道的名称。
featureProperties	列表或字符串	用作模型特征的节点属性。

表 9. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

示例

以下操作将为管道选择两个特征属性。

CALL gds.alpha.pipeline.nodeRegression.selectFeatures('pipe', ['scaledSizes', 'sizePerStory'])
YIELD name, featureProperties

表 10. 结果
name	featureProperties
"pipe"	["scaledSizes", "sizePerStory"]

这里我们假设输入图包含一个属性sizePerStory，并且scaledSizes是在nodePropertyStep中创建的。

配置节点分割

节点回归管道管理将节点分割成多个集合，这些集合用于训练、测试和验证在参数空间中定义的模型候选。配置分割是可选的，如果省略，则将使用默认设置进行分割。可以使用gds.model.list并生成splitConfig来检查管道的分割配置。

节点分割在训练过程中按如下方式使用

输入图被分成两部分：训练图和测试图。请参见下面的示例。
训练图进一步细分为多个验证折叠，每个折叠包含一个训练部分和一个验证部分。请参见下面的动画。
每个模型候选都使用每个训练部分进行训练，并在相应的验证部分进行评估。
根据主要指标获得最高平均分数的模型将赢得训练。
然后，获胜模型将在整个训练图上重新训练。
获胜模型将在训练图和测试图上进行评估。
获胜模型将在整个原始图上重新训练。

下面我们以一个包含 12 个节点的图为例进行说明。首先，我们使用 0.25 的holdoutFraction将图分割成训练和测试子图。

然后，我们进行三次验证折叠，首先将训练子图分成 3 个不相交的子集（s1、s2 和 s3），然后交替使用哪个子集进行验证。对于每个折叠，所有候选模型都使用红色节点进行训练，并使用绿色节点进行验证。

语法

配置节点分割语法

CALL gds.alpha.pipeline.nodeRegression.configureSplit(
  pipelineName: String,
  configuration: Map
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: List of Map

表 11. 参数
名称	类型	描述
pipelineName	字符串	管道的名称。
configuration	映射	用于分割图的配置。

表 12. 配置
名称	类型	默认值	描述
validationFolds	整数	3	模型选择期间训练图的划分次数。
testFraction	双精度浮点数	0.3	为测试保留的图的分数。必须在范围 (0, 1) 内。用于训练的分数为`1 - testFraction`。

表 13. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

示例

以下操作将配置管道的图分割。

CALL gds.alpha.pipeline.nodeRegression.configureSplit('pipe', {
  testFraction: 0.2,
  validationFolds: 5
}) YIELD splitConfig

表 14. 结果
splitConfig
{testFraction=0.2, validationFolds=5}

我们现在重新配置了管道的图分割，这将在训练期间使用。

添加模型候选

管道包含一个最初为空的模型候选配置集合。这个集合称为参数空间。每个模型候选配置包含训练参数的固定值或范围。当存在范围时，自动调整算法会自动确定范围中的值，请参见自动调整。必须使用以下过程之一将一个或多个模型配置添加到训练管道的参数空间中

gds.alpha.pipeline.nodeRegression.addLinearRegression
gds.alpha.pipeline.nodeRegression.addRandomForest

有关 GDS 中可用训练方法的详细信息，请参见训练方法。

在训练管道中，我们将进一步解释如何训练、评估和比较已配置的模型候选。

可以使用gds.model.list并生成parameterSpace来检查管道的参数空间。

在训练管道之前，必须向管道中添加至少一个模型候选。

语法

添加线性回归模型候选

CALL gds.alpha.pipeline.nodeRegression.addLinearRegression(
  pipelineName: String,
  configuration: Map
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: Map

表 15. 参数
名称	类型	描述
pipelineName	字符串	管道的名称。
configuration	映射	候选模型的线性回归配置。下一表中定义了模型候选的支持参数。

表 16. 线性回归配置
名称	类型	默认值	可选	描述
batchSize	整数或映射 ^[1]	`100`	是	每个批次的节点数。
minEpochs	整数或映射 ^[1]	`1`	是	最小训练轮数。
maxEpochs	整数或映射 ^[1]	`100`	是	最大训练轮数。
learningRate ^[2]	浮点数或映射 ^[1]	`0.001`	是	学习率决定了在每个轮次中沿 Adam 优化器指示的方向移动以最小化损失时的步长。
patience	整数或映射 ^[1]	`1`	是	最大无生产性连续轮数。
tolerance ^[2]	浮点数或映射 ^[1]	`0.001`	是	要视为有效损失的最小改进。
penalty ^[2]	浮点数或映射 ^[1]	`0.0`	是	用于逻辑回归的惩罚。默认情况下，不应用任何惩罚。
1. 映射应采用`{range: [minValue, maxValue]}`的形式。它由自动调整使用。 2. 此参数的范围在对数刻度上进行自动调整。

表 17. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

添加随机森林模型候选

CALL gds.alpha.pipeline.nodeRegression.addRandomForest(
  pipelineName: String,
  configuration: Map
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: Map

表 18. 参数
名称	类型	描述
pipelineName	字符串	管道的名称。
configuration	映射	候选模型的随机森林配置。下一表中定义了模型候选的支持参数。

表 19. 随机森林回归配置
名称	类型	默认值	可选	描述
maxFeaturesRatio	浮点数或映射 ^[3]	`1 / sqrt(\|features\|)`	是	查找最佳分割时要考虑的特征比例
numberOfSamplesRatio	浮点数或映射 ^[3]	`1.0`	是	每个决策树要考虑的样本比例。我们使用有放回抽样。值为`0`表示使用每个训练示例（无抽样）。
numberOfDecisionTrees	整数或映射 ^[3]	`100`	是	决策树的数量。
maxDepth	整数或映射 ^[3]	`无最大深度`	是	决策树的最大深度。
minLeafSize	整数或映射 ^[3]	`1`	是	决策树中叶子节点的最小样本数。必须严格小于`minSplitSize`。
minSplitSize	整数或映射 ^[3]	`2`	是	决策树中分割内部节点所需的最小样本数。必须严格大于`minLeafSize`。
3. 映射应采用`{range: [minValue, maxValue]}`的形式。它由自动调整使用。

表 20. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

示例

我们可以向管道添加多个模型候选。

以下操作将添加一个具有默认配置的线性回归模型候选

CALL gds.alpha.pipeline.nodeRegression.addLinearRegression('pipe')
YIELD parameterSpace

以下操作将添加一个随机森林模型候选

CALL gds.alpha.pipeline.nodeRegression.addRandomForest('pipe', {numberOfDecisionTrees: 5})
YIELD parameterSpace

以下操作将添加一个具有范围参数的线性回归模型候选

CALL gds.alpha.pipeline.nodeRegression.addLinearRegression('pipe', {maxEpochs: 500, penalty: {range: [1e-4, 1e2]}})
YIELD parameterSpace
RETURN parameterSpace.RandomForest AS randomForestSpace, parameterSpace.LinearRegression AS linearRegressionSpace

表 21. 结果
randomForestSpace	linearRegressionSpace
[{maxDepth=2147483647, methodName="RandomForest", minLeafSize=1, minSplitSize=2, numberOfDecisionTrees=5, numberOfSamplesRatio=1.0}]	[{batchSize=100, learningRate=0.001, maxEpochs=100, methodName="LinearRegression", minEpochs=1, patience=1, penalty=0.0, tolerance=0.001}, {batchSize=100, learningRate=0.001, maxEpochs=500, methodName="LinearRegression", minEpochs=1, patience=1, penalty={range=[0.0001, 100.0]}, tolerance=0.001}]

管道中的parameterSpace现在包含三个不同的模型候选，并扩展了默认值。在训练中的模型选择期间，将尝试每个指定的模型候选。

这些是有关如何添加和配置模型候选的一些简单的示例。有关如何调整每种方法的配置参数的更多信息，请参见训练方法。

配置自动调整

为了找到好的模型，管道支持自动调整训练算法的参数。可以选择使用下面描述的过程来配置自动调整行为。否则，将使用默认的自动调整配置。目前，只能配置要评估的超参数设置的最大尝试次数。

语法

配置自动调整语法

CALL gds.alpha.pipeline.nodeRegression.configureAutoTuning(
  pipelineName: String,
  configuration: Map
) YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: List of Map

表 22. 参数
名称	类型	描述
pipelineName	字符串	创建的管道的名称。
configuration	映射	用于自动调整的配置。

表 23. 配置
名称	类型	默认值	描述
maxTrials	整数	10	`maxTrials`的值决定了训练管道时应评估和比较的最大允许模型候选数。如果参数空间中不存在任何范围，则忽略`maxTrials`，并评估参数空间中的每个模型候选。

表 24. 结果
名称	类型	描述
name	字符串	管道的名称。
nodePropertySteps	映射列表	节点属性步骤的配置列表。
featureProperties	字符串列表	用作特征的节点属性列表。
splitConfig	映射	用于定义模型训练前拆分的配置。
autoTuningConfig	映射	用于定义自动调整行为的配置。
parameterSpace	映射列表	模型的参数配置列表，训练模式使用这些参数进行模型选择。

示例

以下操作将配置自动调整的最大尝试次数

CALL gds.alpha.pipeline.nodeRegression.configureAutoTuning('pipe', {
  maxTrials: 100
}) YIELD autoTuningConfig

表 25. 结果
autoTuningConfig
{maxTrials=100}

我们在训练期间明确配置了自动调整，最多尝试 100 个模型候选者。