配置管道

此功能处于 Beta 测试阶段。有关功能分级的更多信息，请参阅 API 分级。

本页面介绍了如何创建和配置节点分类流水线。

创建流水线

构建新流水线的第一步是使用 gds.beta.pipeline.nodeClassification.create 进行创建。这会在流水线目录中存储一个类型为 Node classification training pipeline 的可训练流水线对象。它代表一个可配置的流水线，稍后可调用它进行训练，进而创建一个分类模型。后者也是一个模型，并以 NodeClassification 类型存储在目录中。

语法

创建流水线语法

CALL gds.beta.pipeline.nodeClassification.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	Map	用于定义模型训练前数据拆分的配置。
autoTuningConfig	Map	用于定义自动调优行为的配置。
parameterSpace	映射列表	模型参数配置列表，训练模式使用这些配置进行模型选择。

示例

以下代码将创建一个流水线

CALL gds.beta.pipeline.nodeClassification.create('pipe')

表 3. 结果
名称 (name)	nodePropertySteps	featureProperties	splitConfig	autoTuningConfig	parameterSpace
"pipe"	[]	[]	{testFraction=0.3, validationFolds=3}	{maxTrials=10}	{LogisticRegression=[], MultilayerPerceptron=[], RandomForest=[]}

这表明新创建的流水线尚不包含任何步骤，并且对拆分和训练参数使用了默认值。

添加节点属性

节点分类流水线可以在“mutate（变异）”模式下执行一个或多个 GDS 算法，从而在内存图中创建节点属性。这些产生节点属性的步骤可以一个接一个地链接，创建的属性稍后可用作特征。此外，添加到训练流水线的节点属性步骤将在训练模型时以及分类流水线应用于分类时执行。

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

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

语法

添加节点属性语法

CALL gds.beta.pipeline.nodeClassification.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	Map	用于生成过程配置的映射。它包含除 `nodeLabels` 和 `relationshipTypes` 之外的过程特定配置。它可以选择性地包含下表中的参数。

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

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

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

示例

以下内容将向流水线添加节点属性步骤。在此我们假设输入图包含一个 sizePerStory 属性。

CALL gds.beta.pipeline.nodeClassification.addNodeProperty('pipe', 'scaleProperties', {
  nodeProperties: 'sizePerStory',
  scaler: 'Mean',
  mutateProperty:'scaledSizes'
})
YIELD name, nodePropertySteps

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

scaledSizes 属性稍后可用作特征。

添加特征

节点分类流水线允许您选择可用节点属性的子集作为机器学习模型的特征。执行流水线时，所选的 nodeProperties 必须存在于输入图中，或者是通过之前的节点属性步骤创建的。

语法

添加流水线特征语法

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

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

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

示例

以下内容将为流水线选择特征。

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

表 10. 结果
名称 (name)	featureProperties
"pipe"	["scaledSizes", "sizePerStory"]

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

配置节点拆分

节点分类流水线管理节点到多个集合的拆分，这些集合用于训练、测试和验证参数空间中定义的模型候选。配置拆分是可选的，如果省略，将使用默认设置进行拆分。可以使用 gds.model.list 并产出 splitConfig 来查看流水线的拆分配置。

节点拆分在训练过程中的使用方式如下

输入图被拆分为两部分：训练图和测试图。请参阅下方的示例。
训练图进一步划分为多个验证折叠（validation folds），每个折叠包含一个训练部分和一个验证部分。请参阅下方的动画。
每个模型候选都在每个训练部分进行训练，并在相应的验证部分进行评估。
根据主要指标平均得分最高的模型将赢得训练。
获胜模型随后将在整个训练图上进行重训练。
获胜模型将在训练图和测试图上进行评估。
获胜模型将在整个原始图上进行重训练。

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

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

语法

配置节点拆分语法

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

表 11. 参数
名称	类型	描述
pipelineName	字符串	流水线的名称。
配置	Map	图拆分配置。

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

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

示例

以下内容将配置流水线的拆分

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

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

我们现在重新配置了流水线的拆分，这将在训练期间应用。

添加模型候选

流水线包含一个初始为空的模型候选配置集合。该集合称为参数空间。每个模型候选配置都包含训练参数的固定值或范围。当存在范围时，范围内的值由自动调优算法自动确定，请参阅自动调优。必须使用以下过程之一将一个或多个模型配置添加到训练流水线的参数空间中

gds.beta.pipeline.nodeClassification.addLogisticRegression
gds.beta.pipeline.nodeClassification.addRandomForest
gds.alpha.pipeline.nodeClassification.addMLP

有关 GDS 中可用训练方法（逻辑回归、随机森林和多层感知器）的信息，请参阅训练方法。

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

可以使用 gds.model.list 并选择性地仅产出 parameterSpace 来查看流水线的参数空间。

在训练之前，必须至少向流水线添加一个模型候选。

语法

配置训练参数语法

CALL gds.beta.pipeline.nodeClassification.addLogisticRegression(
  pipelineName: String,
  config: Map
)
YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: Map

表 15. 参数
名称	类型	描述
pipelineName	字符串	流水线的名称。
config	Map	潜在模型的逻辑回归配置。模型的允许参数在下表中定义。

表 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`	是	用于逻辑回归的惩罚项。默认情况下，不应用惩罚。
`focusWeight`	浮点数或映射 ^[1]	`0.0`	是	焦点损失因子的指数，使模型更关注训练集中难以分类的样本。默认值 `0.0` 表示不应用焦点，而是使用交叉熵。必须为正数。
`classWeights`	浮点数列表	`1.0 的列表`	是	损失函数中每个类的权重。第 `i` 个权重对应于第 `i` 个类（当按整数值对类进行排序时）。列表长度必须等于类的数量。
1. 映射应为 `{range: [minValue, maxValue]}` 格式。它由自动调优使用。 2. 该参数的范围在对数刻度上自动调优。

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

配置训练参数语法

CALL gds.beta.pipeline.nodeClassification.addRandomForest(
  pipelineName: String,
  config: Map
)
YIELD
  name: String,
  nodePropertySteps: List of Map,
  featureProperties: List of String,
  splitConfig: Map,
  autoTuningConfig: Map,
  parameterSpace: Map

表 18. 参数
名称	类型	描述
pipelineName	字符串	流水线的名称。
config	Map	潜在模型的随机森林配置。模型的允许参数在下表中定义。

表 19. 随机森林分类配置
名称	类型	默认	可选	描述
maxFeaturesRatio	浮点数或映射 ^[3]	`1 / sqrt(\|features\|)`	是	寻找最佳拆分时要考虑的特征比例。
numberOfSamplesRatio	浮点数或映射 ^[3]	`1.0`	是	每个决策树考虑的样本比例。我们使用有放回采样。值为 `0` 表示使用每个训练样本（不采样）。
numberOfDecisionTrees	整数或映射 ^[3]	`100`	是	决策树的数量。
maxDepth	整数或映射 ^[3]	`无最大深度`	是	决策树的最大深度。
minLeafSize	整数或映射 ^[3]	`1`	是	决策树叶节点所需的最小样本数。必须严格小于 `minSplitSize`。
minSplitSize	整数或映射 ^[3]	`2`	是	决策树中拆分内部节点所需的最小样本数。必须严格大于 `minLeafSize`。
criterion	字符串	`"GINI"`	是	在决策树训练期间用于评估潜在节点拆分的不纯度准则。有效选项为 `"GINI"` 和 `"ENTROPY"`（均不区分大小写）。
3. 映射应为 `{range: [minValue, maxValue]}` 格式。它由自动调优使用。

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

配置训练参数语法

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

表 21. 参数
名称	类型	描述
pipelineName	字符串	流水线的名称。
config	Map	潜在模型的多层感知器配置。模型的允许参数在下表中定义。

表 22. 多层感知器分类配置
名称	类型	默认	可选	描述
batchSize	整数或映射 ^[4]	`100`	是	每批次的节点数。
minEpochs	整数或映射 ^[4]	`1`	是	最小训练轮数。
maxEpochs	整数或映射 ^[4]	`100`	是	最大训练轮数。
learningRate ^[5]	浮点数或映射 ^[4]	`0.001`	是	学习率决定了每一轮在 Adam 优化器指定的方向上移动以最小化损失时的步长。
patience	整数或映射 ^[4]	`1`	是	无提升的最大连续轮数。
tolerance ^[5]	浮点数或映射 ^[4]	`0.001`	是	被视为有效的损失最小改进值。
penalty ^[5]	浮点数或映射 ^[4]	`0.0`	是	用于逻辑回归的惩罚项。默认情况下，不应用惩罚。
hiddenLayerSizes	整数列表	`[100]`	是	表示每层神经元数量的整数列表。默认值指定了一个具有 1 个隐藏层、100 个神经元的 MLP。
focusWeight	浮点数或映射 ^[4]	`0.0`	是	焦点损失因子的指数，使模型更关注训练集中难以分类的样本。默认值 `0.0` 表示不应用焦点，而是使用交叉熵。必须为正数。
classWeights	浮点数列表	`1.0 的列表`	是	交叉熵损失中每个类的权重。第 `i` 个权重对应于第 `i` 个类（当按整数值对类进行排序时）。列表长度必须等于类的数量。
4. 映射应采用 `{range: [minValue, maxValue]}` 的形式。它由自动调优使用。 5. 此参数的范围在对数尺度上进行自动调优。

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

示例

我们可以向流水线添加多个模型候选者。

以下内容将添加一个具有默认配置的逻辑回归模型

CALL gds.beta.pipeline.nodeClassification.addLogisticRegression('pipe')
YIELD parameterSpace

以下内容将添加一个随机森林模型

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

以下内容将添加一个具有类加权焦点损失的多层感知器模型

CALL gds.alpha.pipeline.nodeClassification.addMLP('pipe', {classWeights: [0.4,0.3,0.3], focusWeight: 0.5})
YIELD parameterSpace

以下内容将添加一个具有范围参数的逻辑回归模型

CALL gds.beta.pipeline.nodeClassification.addLogisticRegression('pipe', {maxEpochs: 500, penalty: {range: [1e-4, 1e2]}})
YIELD parameterSpace
RETURN parameterSpace.RandomForest AS randomForestSpace, parameterSpace.LogisticRegression AS logisticRegressionSpace, parameterSpace.MultilayerPerceptron AS MultilayerPerceptronSpace

表 24. 结果
randomForestSpace	logisticRegressionSpace	MultilayerPerceptronSpace
[{criterion="GINI", maxDepth=2147483647, methodName="RandomForest", minLeafSize=1, minSplitSize=2, numberOfDecisionTrees=5, numberOfSamplesRatio=1.0}]	[{batchSize=100, classWeights=[], focusWeight=0.0, learningRate=0.001, maxEpochs=100, methodName="LogisticRegression", minEpochs=1, patience=1, penalty=0.0, tolerance=0.001}, {batchSize=100, classWeights=[], focusWeight=0.0, learningRate=0.001, maxEpochs=500, methodName="LogisticRegression", minEpochs=1, patience=1, penalty={range=[0.0001, 100.0]}, tolerance=0.001}]	[{batchSize=100, classWeights=[0.4, 0.3, 0.3], focusWeight=0.5, hiddenLayerSizes=[100], learningRate=0.001, maxEpochs=100, methodName="MultilayerPerceptron", minEpochs=1, patience=1, penalty=0.0, tolerance=0.001}]

流水线中的 parameterSpace 现在包含四个不同的模型候选，并已使用默认值进行扩展。每个指定的模型候选都将在训练的模型选择期间进行测试。

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

配置自动调优

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

语法

配置自动调优语法

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

表 25. 参数
名称	类型	描述
pipelineName	字符串	所创建流水线的名称。
配置	Map	自动调优的配置。

表 26. 配置
名称	类型	默认	描述
maxTrials	整数	10	`maxTrials` 的值决定了在训练流水线时应评估和比较的最大允许模型候选者数量。如果参数空间中不存在范围，则 `maxTrials` 被忽略，并且参数空间中的每个模型候选者都会被评估。

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

示例

以下代码将配置自动调优的最大试验次数

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

表 28. 结果
autoTuningConfig
{maxTrials=2}

我们现在重新配置了自动调优，以便在训练期间最多尝试 100 个模型候选。