DistributedGradientBoostedTreesLearner

DistributedGradientBoostedTreesLearner

DistributedGradientBoostedTreesLearner ¶

DistributedGradientBoostedTreesLearner(
    label: str,
    task: Task = CLASSIFICATION,
    *,
    weights: Optional[str] = None,
    ranking_group: Optional[str] = None,
    uplift_treatment: Optional[str] = None,
    features: Optional[ColumnDefs] = None,
    include_all_columns: bool = False,
    max_vocab_count: int = 2000,
    min_vocab_frequency: int = 5,
    discretize_numerical_columns: bool = False,
    num_discretized_numerical_bins: int = 255,
    max_num_scanned_rows_to_infer_semantic: int = 100000,
    max_num_scanned_rows_to_compute_statistics: int = 100000,
    data_spec: Optional[DataSpecification] = None,
    extra_training_config: Optional[TrainingConfig] = None,
    apply_link_function: bool = True,
    force_numerical_discretization: bool = False,
    max_depth: int = 6,
    max_unique_values_for_discretized_numerical: int = 16000,
    maximum_model_size_in_memory_in_bytes: float = -1.0,
    maximum_training_duration_seconds: float = -1.0,
    min_examples: int = 5,
    num_candidate_attributes: Optional[int] = -1,
    num_candidate_attributes_ratio: Optional[float] = None,
    num_trees: int = 300,
    pure_serving_model: bool = False,
    random_seed: int = 123456,
    shrinkage: float = 0.1,
    use_hessian_gain: bool = False,
    worker_logs: bool = True,
    workers: Optional[Sequence[str]] = None,
    resume_training: bool = False,
    resume_training_snapshot_interval_seconds: int = 1800,
    working_dir: Optional[str] = None,
    num_threads: Optional[int] = None,
    tuner: Optional[AbstractTuner] = None,
    feature_selector: Optional[
        AbstractFeatureSelector
    ] = None,
    explicit_args: Optional[Set[str]] = None
)

继承自: GenericCCLearner

分布式梯度提升树学习算法。

梯度提升树学习算法的精确分布式版本。有关 GBT 的介绍，请参阅非分布式梯度提升树学习算法的文档。

使用示例

import ydf
import pandas as pd

dataset = pd.read_csv("project/dataset.csv")

model = ydf.DistributedGradientBoostedTreesLearner().train(dataset)

print(model.describe())

超参数已配置为对典型数据集给出合理的结果。超参数也可以手动修改（参见下面的描述）或通过应用 DistributedGradientBoostedTreesLearner.hyperparameter_templates() 提供的超参数模板（有关详细信息，请参阅此函数的文档）。

属性

名称	类型	描述
`label`		数据集的标签。标签列不应在 `features` 参数中被标识为特征。
`task`		要解决的任务（例如 Task.CLASSIFICATION, Task.REGRESSION, Task.RANKING, Task.CATEGORICAL_UPLIFT, Task.NUMERICAL_UPLIFT）。
`weights`		标识每个示例权重的特征名称。如果未指定权重，则假定单位权重。权重列不应在 `features` 参数中被标识为特征。
`ranking_group`		仅用于 `task=Task.RANKING`。标识查询/文档排序任务中查询的特征名称。排序分组不应在 `features` 参数中被标识为特征。
`uplift_treatment`		仅用于 `task=Task.CATEGORICAL_UPLIFT` 和 `task=Task.NUMERICAL_UPLIFT`。标识提升问题中处理方式的数值特征名称。值 0 保留给对照处理。目前仅支持 0/1 二进制处理方式。
`features`		如果为 None，则所有列都用作特征。特征的语义是自动确定的。否则，如果 include_all_columns=False（默认），则只导入 `features` 中列出的列。如果 include_all_columns=True，则所有列都作为特征导入，并且只有不在 `columns` 中的列的语义是自动确定的。如果指定，则定义特征的顺序 - 任何未列出的特征（如果 include_all_columns=True）将按顺序添加到指定特征之后。标签、权重、提升处理和 ranking_group 列不应被指定为特征。
`include_all_columns`		参见 `features`。
`max_vocab_count`		存储为字符串的 CATEGORICAL 和 CATEGORICAL_SET 列的词汇表的最大大小。如果存在更多唯一值，则只保留最常出现的值，其余值被视为词汇外。
`min_vocab_frequency`		CATEGORICAL 和 CATEGORICAL_SET 列中值的最小出现次数。出现次数少于 `min_vocab_frequency` 的值被视为词汇外。
`discretize_numerical_columns`		如果为 true，则在训练前对所有数值列进行离散化。离散化后的数值列训练速度更快，但可能对模型质量产生负面影响。使用 `discretize_numerical_columns=True` 等同于在 `column` 参数中设置列语义 DISCRETIZED_NUMERICAL。有关 DISCRETIZED_NUMERICAL 的更多详细信息，请参见其定义。
`num_discretized_numerical_bins`		对数值列进行离散化时使用的 bin 数量。
`max_num_scanned_rows_to_infer_semantic`		未明确指定列语义时，扫描用于推断列语义的行数。仅在从文件读取时使用，内存中的数据集始终会完全读取。将此值设置得较低会加快数据集读取速度，但可能导致不正确的列语义。设置为 -1 以扫描整个数据集。
`max_num_scanned_rows_to_compute_statistics`		计算列统计信息时扫描的行数。仅在从文件读取时使用，内存中的数据集始终会完全读取。列的统计信息包括分类特征的字典以及数值特征的平均值/最小值/最大值。将此值设置得较低会加快数据集读取速度，但会扭曲数据规范中的统计信息，这可能会损害模型质量（例如，如果某个重要的分类特征类别被视为 OOV）。设置为 -1 以扫描整个数据集。
`data_spec`		要使用的数据规范 (高级)。如果提供了数据规范，则 `columns`, `include_all_columns`, `max_vocab_count`, `min_vocab_frequency`, `discretize_numerical_columns` 和 `num_discretized_numerical_bins` 将被忽略。
`extra_training_config`		训练配置 proto (高级)。如果设置，此训练配置 proto 将与学习器隐式定义的配置合并。可用于设置未作为构造函数参数公开的内部或高级参数。extra_training_config 中的参数具有比构造函数参数更高的优先级。
`apply_link_function`		如果为 true，则在返回模型预测之前应用链接函数（也称为激活函数）（如果存在）。如果为 false，则返回应用链接函数之前的模型输出。例如，在二分类的情况下，应用链接函数之前的输出是对数几率 (logit)，而应用链接函数之后的输出是概率。默认值: True。
`force_numerical_discretization`		如果为 false，则只有满足 "max_unique_values_for_discretized_numerical" 的数值列会被离散化。如果为 true，则所有数值列都会被离散化。具有超过 "max_unique_values_for_discretized_numerical" 个唯一值的列将使用 "max_unique_values_for_discretized_numerical" 个 bin 进行近似。此参数会影响模型训练。默认值: False。
`max_depth`		树的最大深度。`max_depth=1` 表示所有树都将是根节点。`max_depth=-1` 表示树的深度不受此参数限制。小于等于 -2 的值将被忽略。默认值: 6。
`max_unique_values_for_discretized_numerical`		允许预离散化的数值特征的最大唯一值数量。对于大型数据集，唯一值数量较少的离散化数值特征比经典/非离散化数值特征的学习效率更高。此参数不会影响最终模型，但可以加快或减慢训练速度。默认值: 16000。
`maximum_model_size_in_memory_in_bytes`		限制模型存储在 RAM 中的大小。不同的算法可以以不同的方式强制执行此限制。请注意，当模型编译为推理引擎时，推理引擎的大小通常比原始模型小得多。默认值: -1.0。
`maximum_training_duration_seconds`		模型的最长训练持续时间，以秒为单位。每个学习算法都可以根据自己的需要自由使用此参数。启用最大训练持续时间会使模型训练变得不确定。默认值: -1.0。
`min_examples`		节点中的最小示例数。默认值: 5。
`num_candidate_attributes`		每个节点测试的唯一有效属性数量。如果一个属性至少有一个有效分割，则它是有效的。如果 `num_candidate_attributes=0`，则该值设置为随机森林的经典默认值：分类情况下为 `sqrt(number of input attributes)`，回归情况下为 `number_of_input_attributes / 3`。如果 `num_candidate_attributes=-1`，则测试所有属性。默认值: -1。
`num_candidate_attributes_ratio`		每个节点测试的属性比例。如果设置，则等同于 `num_candidate_attributes = number_of_input_features x num_candidate_attributes_ratio`。可能的值在 ]0, 1] 之间以及 -1。如果未设置或等于 -1，则使用 `num_candidate_attributes`。默认值: None。
`num_trees`		决策树的最大数量。如果启用早停，实际训练的树数量可能会更少。默认值: 300。
`pure_serving_model`		清除模型中任何不需要用于模型服务的信息。这包括调试、模型解释和其他元数据。序列化模型的大小可以显著减小（通常可以减小 50%）。此参数对模型服务的质量、服务速度或 RAM 使用没有影响。默认值: False。
`random_seed`		模型训练的随机种子。学习器应通过随机种子实现确定性。默认值: 123456。
`shrinkage`		应用于每个树预测的系数。较小的值（0.02）往往会产生更准确的结果（假设训练了足够的树），但会生成更大的模型。类似于神经网络的学习率。对于 DART 模型固定为 1.0。默认值: 0.1。
`use_hessian_gain`		如果为 true，则使用包含 Hessian 项的分割增益公式，即优化分割以最小化 "梯度 / Hessian" 的方差。除回归外，所有损失函数均可用。默认值: False。
`worker_logs`		如果为 true，worker 将打印训练日志。默认值: True。
`workers`		如果设置，启用分布式训练。"workers" 是 worker 的 IP 地址列表。worker 是一个运行 `ydf.start_worker(port)` 的进程。
`resume_training`		如果为 true，模型训练将从存储在 `working_dir` 目录中的检查点恢复。如果 `working_dir` 不包含任何模型检查点，训练将从头开始。恢复训练在以下情况下很有用：(1) 训练被用户中断（例如，在 notebook 中按 ctrl+c 或点击“停止”按钮）或重新安排，或者 (2) 学习器的超参数被改变，例如增加了树的数量。
`resume_training_snapshot_interval_seconds`		当 `resume_training=True` 时，快照之间的指示性秒数。可能会被某些学习器忽略。
`working_dir`		学习算法可用于存储中间计算结果的目录路径。根据学习算法和参数的不同，working_dir 可能是可选的、必需的或被忽略的。例如，分布式训练算法总是需要一个 "working_dir"，并且如果提供了 "working_dir"，梯度提升树和超参数调优器会将结果导出到该目录。
`num_threads`		用于训练模型的线程数。不同的学习算法使用多线程的方式和效率程度不同。如果为 `None`，`num_threads` 将自动设置为处理器数量（最多 32 个；如果处理器数量不可用，则设置为 6）。将 `num_threads` 设置得远大于处理器数量可能会降低训练速度。默认值逻辑将来可能会改变。
`tuner`		如果设置，则使用提供的调优器自动选择最佳超参数。使用分布式训练时，调优也是分布式的。
`feature_selector`		如果设置，则使用指定的特征选择器自动选择模型的输入特征。
`explicit_args`		用于内部使用的辅助参数。如果用户明确提供此参数，则抛出异常。

hyperparameters `property` ¶

hyperparameters: HyperParameters

此学习器超参数的一个（可变）字典。

此对象可用于在创建学习器后检查或修改超参数。在构建学习器后修改超参数适用于一些高级用例。由于此方法绕过了对给定超参数集的一些可行性检查，通常最好为每个模型重新创建学习器。当前的超参数集可以使用 validate_hyperparameters() 手动验证。

learner_name `property` ¶

learner_name: str

capabilities `classmethod` ¶

capabilities() -> LearnerCapabilities

cross_validation ¶

cross_validation(
    ds: InputDataset,
    folds: int = 10,
    bootstrapping: Union[bool, int] = False,
    parallel_evaluations: int = 1,
) -> Evaluation

extract_input_feature_names ¶

extract_input_feature_names(ds: InputDataset) -> List[str]

hyperparameter_templates `classmethod` ¶

hyperparameter_templates() -> (
    Dict[str, HyperparameterTemplate]
)

此学习器的超参数模板。

此学习器当前不提供任何超参数模板，此方法是为了与其他学习器保持一致而提供的。

返回值

类型	描述
`Dict[str, HyperparameterTemplate]`	空字典。

post_init ¶

post_init()

train ¶

train(
    ds: InputDataset,
    valid: Optional[InputDataset] = None,
    verbose: Optional[Union[int, bool]] = None,
) -> GradientBoostedTreesModel

在给定数据集上训练模型。

数据集读取选项在学习器上给出。有关 YDF 中数据集读取的更多信息，请查阅学习器的文档或 ydf.create_vertical_dataset()。

使用示例

import ydf
import pandas as pd

train_ds = pd.read_csv(...)

learner = ydf.DistributedGradientBoostedTreesLearner(label="label")
model = learner.train(train_ds)
print(model.summary())

如果训练被中断（例如，通过中断 Colab 中的单元格执行），模型将返回到中断时的状态。

参数

名称	类型	描述	默认值
`ds`	`InputDataset`	训练数据集。	必需
`valid`	`Optional[InputDataset]`	可选的验证数据集。某些学习器（例如随机森林）不需要验证数据集。某些学习器（例如梯度提升树）如果在未提供验证数据集的情况下，会自动从训练数据集中提取一个验证数据集。	`None`
`verbose`	`Optional[Union[int, bool]]`	训练期间的详细程度。如果为 None，则使用 `ydf.verbose` 的全局详细程度。级别为：0 或 False：无日志；1 或 True：在 notebook 中打印少量日志；在终端中打印所有日志。2：在所有界面上打印所有日志。	`None`

返回值

类型	描述
`GradientBoostedTreesModel`	训练好的模型。

train_imp ¶

train_imp(
    ds: InputDataset,
    valid: Optional[InputDataset],
    verbose: Optional[Union[int, bool]],
) -> ModelType

validate_hyperparameters ¶

validate_hyperparameters() -> None

DistributedGradientBoostedTreesLearner