GradientBoostedTreesLearner

GradientBoostedTreesLearner

GradientBoostedTreesLearner ¶

GradientBoostedTreesLearner(
    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,
    adapt_subsample_for_maximum_training_duration: bool = False,
    allow_na_conditions: bool = False,
    apply_link_function: bool = True,
    categorical_algorithm: str = "CART",
    categorical_set_split_greedy_sampling: float = 0.1,
    categorical_set_split_max_num_items: int = -1,
    categorical_set_split_min_item_frequency: int = 1,
    compute_permutation_variable_importance: bool = False,
    cross_entropy_ndcg_truncation: Optional[int] = None,
    dart_dropout: Optional[float] = None,
    early_stopping: str = "LOSS_INCREASE",
    early_stopping_initial_iteration: int = 10,
    early_stopping_num_trees_look_ahead: int = 30,
    focal_loss_alpha: Optional[float] = None,
    focal_loss_gamma: Optional[float] = None,
    forest_extraction: str = "MART",
    goss_alpha: float = 0.2,
    goss_beta: float = 0.1,
    growing_strategy: str = "LOCAL",
    honest: bool = False,
    honest_fixed_separation: bool = False,
    honest_ratio_leaf_examples: float = 0.5,
    in_split_min_examples_check: bool = True,
    keep_non_leaf_label_distribution: bool = True,
    l1_regularization: float = 0.0,
    l2_categorical_regularization: float = 1.0,
    l2_regularization: float = 0.0,
    lambda_loss: float = 1.0,
    loss: str = "DEFAULT",
    max_depth: int = 6,
    max_num_nodes: Optional[int] = None,
    maximum_model_size_in_memory_in_bytes: float = -1.0,
    maximum_training_duration_seconds: float = -1.0,
    mhld_oblique_max_num_attributes: Optional[int] = None,
    mhld_oblique_sample_attributes: Optional[bool] = None,
    min_examples: int = 5,
    missing_value_policy: str = "GLOBAL_IMPUTATION",
    ndcg_truncation: Optional[int] = None,
    num_candidate_attributes: Optional[int] = -1,
    num_candidate_attributes_ratio: Optional[float] = None,
    num_trees: int = 300,
    numerical_vector_sequence_num_examples: int = 1000,
    numerical_vector_sequence_num_random_anchors: int = 100,
    pure_serving_model: bool = False,
    random_seed: int = 123456,
    sampling_method: str = "RANDOM",
    selective_gradient_boosting_ratio: float = 0.01,
    shrinkage: float = 0.1,
    sorting_strategy: str = "PRESORT",
    sparse_oblique_max_num_features: Optional[int] = None,
    sparse_oblique_max_num_projections: Optional[
        int
    ] = None,
    sparse_oblique_normalization: Optional[str] = None,
    sparse_oblique_num_projections_exponent: Optional[
        float
    ] = None,
    sparse_oblique_projection_density_factor: Optional[
        float
    ] = None,
    sparse_oblique_weights: Optional[str] = None,
    sparse_oblique_weights_integer_maximum: Optional[
        int
    ] = None,
    sparse_oblique_weights_integer_minimum: Optional[
        int
    ] = None,
    sparse_oblique_weights_power_of_two_max_exponent: Optional[
        int
    ] = None,
    sparse_oblique_weights_power_of_two_min_exponent: Optional[
        int
    ] = None,
    split_axis: str = "AXIS_ALIGNED",
    subsample: float = 1.0,
    uplift_min_examples_in_treatment: int = 5,
    uplift_split_score: str = "KULLBACK_LEIBLER",
    use_hessian_gain: bool = False,
    validation_interval_in_trees: int = 1,
    validation_ratio: float = 0.1,
    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)，也称为梯度提升决策树 (GBDT) 或梯度提升机 (GBM)，是一系列按顺序训练的浅层决策树。每棵树都经过训练，用于预测并“纠正”先前训练树的错误（更准确地说，每棵树预测损失相对于模型输出的梯度）。

使用示例

import ydf
import pandas as pd

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

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

print(model.describe())

超参数被配置为对典型数据集给出合理的结果。超参数也可以手动修改（参见下面的描述）或通过应用 GradientBoostedTreesLearner.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）。标签、权重、提升处理和排序组列不应指定为特征。
`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`		离散化数值列时使用的分箱数量。
`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 中的参数具有比构造函数参数更高的优先级。
`adapt_subsample_for_maximum_training_duration`		控制如何应用最大训练持续时间（如果已设置）。如果为 false，则在时间用尽时停止训练。如果为 true，则用于训练单个树的采样数据集的大小会动态调整，以便在规定时间内训练所有树。默认值：False。
`allow_na_conditions`		如果为 true，则树训练评估类型为 `X is NA` 即 `X 缺失` 的条件。默认值：False。
`apply_link_function`		如果为 true，则在返回模型预测之前应用（也称为激活函数）链接函数（如果存在）。如果为 false，则返回链接函数之前的模型输出。例如，在二元分类的情况下，链接函数之前的输出是逻辑值，而链接函数之后的输出是概率。默认值：True。
`categorical_algorithm`		如何学习类别属性的分割。- `CART`: CART 算法。查找形式为“value \in mask”的类别分割。对于二元分类、回归和排序，该解决方案是精确的。对于多类分类，它是近似的。这是一个很好的首选算法。在过拟合（数据集非常小，字典很大）的情况下，“random”算法是一个很好的替代方案。- `ONE_HOT`: One-hot 编码。查找形式为“attribute == param”的最优类别分割。此方法类似于（但更高效）将每个可能的类别值转换为布尔特征。此方法可用于比较目的，通常比其他替代方案性能更差。- `RANDOM`: 在一组随机候选中最优的分割。使用随机搜索查找形式为“value \in mask”的类别分割。该解决方案可以看作是 CART 算法的近似。此方法是 CART 的有力替代方案。该算法灵感来源于 2001 年“Random Forest”一书的“5.1 Categorical Variables”章节。默认值：“CART”。
`categorical_set_split_greedy_sampling`		对于类别集合分割，例如文本。类别值成为正样本集合候选的概率。采样在每个节点上应用一次（即不在贪婪优化的每一步）。默认值：0.1。
`categorical_set_split_max_num_items`		对于类别集合分割，例如文本。最大项数（采样之前）。如果可用项更多，则忽略最不频繁的项。更改此值类似于在加载数据集之前更改“max_vocab_count”，但有一个例外：使用 `max_vocab_count` 时，所有剩余项都分组到一个特殊的词汇表外项中。使用 `max_num_items` 时则不是这种情况。默认值：-1。
`categorical_set_split_min_item_frequency`		对于类别集合分割，例如文本。要考虑的项的最小出现次数。默认值：1。
`compute_permutation_variable_importance`		如果为 true，则在训练结束时使用验证数据集计算模型的置换变量重要性。启用此功能可能会显著增加训练时间。默认值：False。
`cross_entropy_ndcg_truncation`		交叉熵 NDCG 损失的截断（默认值 5）。仅与交叉熵 NDCG 损失一起使用，即 `loss="XE_NDCG_MART"`。默认值：None。
`dart_dropout`		使用 DART 时应用的 Dropout 率，即当 forest_extraction=DART 时。默认值：None。
`early_stopping`		提前停止检测模型的过拟合，并使用验证数据集停止训练。如果未直接提供，验证数据集将从训练数据集中提取（参见“validation_ratio”参数）：- `NONE`: 不进行提前停止。所有 num_trees 都被训练并保留。- `MIN_LOSS_FINAL`: 所有 num_trees 都被训练。然后截断模型以最小化验证损失，即丢弃部分树以使验证损失最小化。- `LOSS_INCREASE`: 经典的提前停止。当验证损失在 `early_stopping_num_trees_look_ahead` 棵树内没有减少时停止训练。默认值：“LOSS_INCREASE”。
`early_stopping_initial_iteration`		用于计算提前停止时考虑的第一个迭代的 0-based 索引。增加此值可以防止由于学习器初始迭代的噪声而导致的过早停止。默认值：10。
`early_stopping_num_trees_look_ahead`		用于检测验证损失增加并触发提前停止的滚动树数量。默认值：30。
`focal_loss_alpha`		实验性参数，默认值 0.5。Focal Loss 的加权参数，正样本权重为 alpha，负样本权重为 (1-alpha)。默认值 0.5 表示没有活动的类别级别加权。仅与 Focal Loss 一起使用，即 `loss="BINARY_FOCAL_LOSS"`。默认值：None。
`focal_loss_gamma`		实验性参数，默认值 2.0。Focal Loss 中误预测指数项的指数，对应于 https://arxiv.org/pdf/1708.02002.pdf 中的 gamma 参数。仅与 Focal Loss 一起使用，即 `loss="BINARY_FOCAL_LOSS"`。默认值：None。
`forest_extraction`		如何构建森林：- MART: 多重加性回归树。构建 GBDT 的“经典”方法，即每棵树都尝试“纠正”先前树的错误。- DART: Dropout 加性回归树。MART 的一个修改，在 http://proceedings.mlr.press/v38/korlakaivinayak15.pdf 中提出。在这里，每棵树都尝试“纠正”先前树的随机子集的错误。默认值：“MART”。
`goss_alpha`		GOSS（基于梯度的单侧采样；参见“LightGBM：一种高效的梯度提升决策树”）采样方法的 Alpha 参数。默认值：0.2。
`goss_beta`		GOSS（基于梯度的单侧采样）采样方法的 Beta 参数。默认值：0.1。
`growing_strategy`		如何生长树。- `LOCAL`: 每个节点独立于其他节点进行分割。换句话说，只要一个节点满足分割“约束”（例如最大深度、最小观察数量），该节点就会被分割。这是生长决策树的“经典”方式。- `BEST_FIRST_GLOBAL`: 选择树中所有节点中损失减少量最优的节点进行分割。此方法也称为“best first”或“leaf-wise growth”。有关详细信息，请参见 Shi 的“Best-first decision tree learning”和 Friedman 的“Additive logistic regression : A statistical view of boosting”。默认值：“LOCAL”。
`honest`		在 Honest 树中，使用不同的训练示例来推断结构和叶子值。这种正则化技术通过交换示例来估计偏差。它可能会增加或降低模型质量。参见 Athey 等人的“Generalized Random Forests”。在本文中， Honest 树使用 Random Forest 算法和无放回采样进行训练。默认值：False。
`honest_fixed_separation`		仅适用于 Honest 树，即 honest=true。如果为 true，则为每棵树生成一个新的随机分离。如果为 false，则对所有树使用相同的分离（例如，在包含多棵树的梯度提升树中）。默认值：False。
`honest_ratio_leaf_examples`		仅适用于 Honest 树，即 honest=true。用于设置叶子值的示例比例。默认值：0.5。
`in_split_min_examples_check`		是否在分割搜索中检查 `min_examples` 约束（即导致某个子节点示例少于 `min_examples` 的分割被视为无效），或者在分割搜索之前检查（即只有当节点包含的示例多于 `min_examples` 时才能进行派生）。如果为 false，则可能存在训练示例少于 `min_examples` 的节点。默认值：True。
`keep_non_leaf_label_distribution`		是否保留非叶子节点的节点值（即训练示例标签的分布）。此信息在模型服务期间不使用，但可用于模型解释以及超参数调优。这可能占用大量空间，有时占模型大小的一半。默认值：True。
`l1_regularization`		应用于训练损失的 L1 正则化。影响树结构和叶子值。默认值：0.0。
`l2_categorical_regularization`		应用于类别特征训练损失的 L2 正则化。影响树结构和叶子值。默认值：1.0。
`l2_regularization`		应用于除类别特征外的所有特征训练损失的 L2 正则化。默认值：0.0。
`lambda_loss`		应用于某些训练损失函数的 Lambda 正则化。仅适用于 NDCG 损失。默认值：1.0。
`loss`		模型优化的损失函数。如果未指定 (DEFAULT)，则根据“task”和标签统计信息自动选择损失函数。例如，如果 task=CLASSIFICATION 且标签有两个可能值，则损失函数将设置为 BINOMIAL_LOG_LIKELIHOOD。可能的值有：- `DEFAULT`: 根据任务和标签统计信息自动选择损失函数。- `BINOMIAL_LOG_LIKELIHOOD`: 二项式对数似然。仅适用于二元分类。- `SQUARED_ERROR`: 最小二乘损失。仅适用于回归。- `POISSON`: 泊松对数似然损失。主要用于计数问题。仅适用于回归。- `MULTINOMIAL_LOG_LIKELIHOOD`: 多项式对数似然，即交叉熵。仅适用于二元或多类分类。- `LAMBDA_MART_NDCG`: 使用 NDCG@5 的 LambdaMART。- `XE_NDCG_MART`: 交叉熵损失 NDCG。参见 arxiv.org/abs/1911.09798。- `BINARY_FOCAL_LOSS`: Focal Loss。仅适用于二元分类。参见 https://arxiv.org/pdf/1708.02002.pdf。- `POISSON`: 泊松对数似然。仅适用于回归。- `MEAN_AVERAGE_ERROR`: 平均绝对误差，即 MAE。对于自定义损失函数，在此处传递损失对象。请注意，使用自定义损失函数时，链接函数会被停用（即 apply_link_function 始终为 False）。- `LAMBDA_MART_NDCG5`: 已弃用，请使用 LAMBDA_MART_NDCG。使用 NDCG@5 的 LambdaMART。默认值：“DEFAULT”。
`max_depth`		树的最大深度。`max_depth=1` 表示所有树都是根节点。`max_depth=-1` 表示树深度不受此参数限制。小于等于 -2 的值将被忽略。默认值：6。
`max_num_nodes`		树中的最大节点数。设置为 -1 可禁用此限制。仅适用于 `growing_strategy=BEST_FIRST_GLOBAL`。默认值：None。
`maximum_model_size_in_memory_in_bytes`		限制模型存储在内存中的大小时。不同的算法可以以不同的方式强制执行此限制。请注意，当模型编译为推理引擎时，推理引擎的大小通常远小于原始模型。默认值：-1.0。
`maximum_training_duration_seconds`		模型的最大训练持续时间，以秒表示。每个学习算法可以根据需要自由使用此参数。启用最大训练持续时间会使模型训练变得非确定性。默认值：-1.0。
`mhld_oblique_max_num_attributes`		对于 MHLD 斜向分割，即 `split_axis=MHLD_OBLIQUE`。投影中的最大属性数量。增加此值会增加训练时间。减小此值可起到正则化作用。该值应在 [2, num_numerical_features] 范围内。如果该值超过数值特征总数，则会自动限制该值。允许值为 1，但会产生普通（非斜向）分割。默认值：None。
`mhld_oblique_sample_attributes`		对于 MHLD 斜向分割，即 `split_axis=MHLD_OBLIQUE`。如果为 true，则应用由“num_candidate_attributes”或“num_candidate_attributes_ratio”参数控制的属性采样。如果为 false，则测试所有属性。默认值：None。
`min_examples`		节点中的最小示例数量。默认值：5。
`missing_value_policy`		处理缺失属性值的方法。- `GLOBAL_IMPUTATION`: 缺失属性值通过在整个数据集上计算的均值（对于数值属性）或最频繁项（对于类别属性）进行填充（即数据规范中包含的信息）。- `LOCAL_IMPUTATION`: 缺失属性值通过在当前节点的训练示例上评估的均值（数值属性）或最频繁项（对于类别属性）进行填充。- `RANDOM_LOCAL_IMPUTATION`: 缺失属性值从当前节点的训练示例中随机采样值进行填充。此方法由 Clinic 等人在“Random Survival Forests” (https://projecteuclid.org/download/pdfview_1/euclid.aoas/1223908043) 中提出。默认值：“GLOBAL_IMPUTATION”。
`ndcg_truncation`		NDCG 损失的截断（默认值 5）。仅与 NDCG 损失一起使用，即 `loss="LAMBDA_MART_NDCG"`。默认值：None。
`num_candidate_attributes`		每个节点测试的唯一有效属性的数量。如果属性至少有一个有效的分割，则该属性是有效的。如果 `num_candidate_attributes=0`，则该值设置为 Random Forest 的经典默认值：分类情况下为 `sqrt(输入属性数量)`，回归情况下为 `number_of_input_attributes / 3`。如果 `num_candidate_attributes=-1`，则测试所有属性。默认值：-1。
`num_candidate_attributes_ratio`		每个节点测试的属性比例。如果设置，它等同于 `num_candidate_attributes = 输入特征数量 x num_candidate_attributes_ratio`。可能的值在 ]0, 1] 之间以及 -1。如果未设置或等于 -1，则使用 `num_candidate_attributes`。默认值：None。
`num_trees`		决策树的最大数量。如果启用了提前停止，训练树的实际数量可能会更少。默认值：300。
`numerical_vector_sequence_num_examples`		对于包含 NUMERICAL_VECTOR_SEQUENCE 特征的数据集（即，固定大小数值向量序列）。用于查找分割的最大示例数量。较大的值可以提高模型质量，但训练时间更长。默认值：1000。
`numerical_vector_sequence_num_random_anchors`		对于包含 NUMERICAL_VECTOR_SEQUENCE 特征的数据集（即，固定大小数值向量序列）。随机生成的锚点值的数量。较大的值可以提高模型质量，但训练时间更长。默认值：100。
`pure_serving_model`		清除模型中所有模型服务不需要的信息。这包括调试、模型解释和其他元数据。序列化模型的大小可以显著减小（模型大小减小 50% 很常见）。此参数对模型服务的质量、服务速度或内存使用没有影响。默认值：False。
`random_seed`		模型训练的随机种子。学习器应通过随机种子实现确定性。默认值：123456。
`sampling_method`		控制用于训练单个树的数据集的采样。- NONE: 不应用采样。这等同于 \"subsample=1\" 的 RANDOM 采样。- RANDOM (默认): 均匀随机采样。如果设置了 \"subsample\"，则自动选择。- GOSS: 基于梯度的单侧采样。如果设置了 \"goss_alpha\" 或 \"goss_beta\"，则自动选择。- SELGB: 选择性梯度提升。如果设置了 \"selective_gradient_boosting_ratio\"，则自动选择。仅适用于排序。默认值：“RANDOM”。
`selective_gradient_boosting_ratio`		用于训练选择性梯度提升（用于有效学习排序的选择性梯度提升；Lucchese 等人；http://quickrank.isti.cnr.it/selective-data/selective-SIGIR2018.pdf）采样方法的单个树的数据集比例。默认值：0.01。
`shrinkage`		应用于每个树预测的系数。较小的值 (0.02) 倾向于给出更准确的结果（假设训练了足够的树），但会导致更大的模型。类似于神经网络的学习率。对于 DART 模型固定为 1.0。默认值：0.1。
`sorting_strategy`		如何对数值特征进行排序以找到分割点 - AUTO: 在 IN_NODE、FORCE_PRESORT 和 LAYER 中选择最有效的方法。- IN_NODE: 仅在使用前在节点中对特征进行排序。此解决方案速度慢但内存消耗少。- FORCE_PRESORT: 在训练开始时对特征进行预排序。此解决方案速度快但比 IN_NODE 消耗更多内存。- PRESORT: 在 FORCE_PRESORT 和 IN_NODE 之间自动选择。默认值：“PRESORT”。
`sparse_oblique_max_num_features`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE`。控制分割中特征的最大数量。设置为 -1 表示没有最大限制。仅在需要对变量数量进行硬性限制时使用，否则 Prefer `projection_density_factor` 来控制每个投影的特征数量。默认值：None。
`sparse_oblique_max_num_projections`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE`。最大投影数量（在 num_projections_exponent 后应用）。斜向分割尝试 max(p^num_projections_exponent, max_num_projections) 个随机投影来选择分割，其中 p 是数值特征的数量。增加“max_num_projections”会增加训练时间，但不增加推理时间。在后期模型开发中，如果准确性至关重要，请增加此值。论文“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）没有定义此超参数。默认值：None。
`sparse_oblique_normalization`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE`。在应用稀疏斜向投影之前，对特征应用的归一化。- `NONE`: 不进行归一化。- `STANDARD_DEVIATION`: 根据整个训练数据集上估计的标准差对特征进行归一化。也称为 Z-Score 归一化。- `MIN_MAX`: 根据整个训练数据集上估计的范围（即 max-min）对特征进行归一化。默认值：None。
`sparse_oblique_num_projections_exponent`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE`。控制每个节点测试的随机投影数量。增加此值很可能提高模型质量，但会显著增加训练时间，且不影响推理时间。斜向分割尝试 max(p^num_projections_exponent, max_num_projections) 个随机投影来选择分割，其中 p 是数值特征的数量。因此，增加 `num_projections_exponent` 以及可能的 `max_num_projections` 可能会提高模型质量，但也会显著增加训练时间。请注意，(经典) Random Forests 的复杂度大致与 `num_projections_exponent=0.5` 成正比，因为它考虑了 sqrt(num_features) 进行分割。(经典) GBDT 的复杂度大致与 `num_projections_exponent=1` 成正比，因为它考虑了所有特征进行分割。论文“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）推荐的值范围为 [1/4, 2]。默认值：None。
`sparse_oblique_projection_density_factor`		投影的密度作为特征数量的指数。对于每个投影独立地，每个特征都有“projection_density_factor / num_features”的概率被纳入投影。论文“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）将此参数称为 `lambda`，并推荐值范围为 [1, 5]。增加此值会增加训练和推理时间（平均而言）。此值最好针对每个数据集进行调优。默认值：None。
`sparse_oblique_weights`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE`。请注意，归一化在采样权重后应用，例如，仅当归一化为 NONE 时才能保证二进制权重为二进制。可能的值：- `BINARY`: 斜向权重在 {-1,1} 中采样（默认）。- `CONTINUOUS`: 斜向权重在 [-1,1] 中采样。- `POWER_OF_TWO`: 斜向权重是 2 的幂。指数在 [sparse_oblique_weights_power_of_two_min_exponent, sparse_oblique_weights_power_of_two_max_exponent] 中均匀采样，符号均匀采样。- `INTEGER`: 权重是在 [sparse_oblique_weights_integer_minimum, sparse_oblique_weights_integer_maximum] 范围内均匀采样的整数。默认值：None。
`sparse_oblique_weights_integer_maximum`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE` 并使用整数权重，即 `sparse_oblique_weights=INTEGER`。权重的最大值。默认值：None。
`sparse_oblique_weights_integer_minimum`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE` 并使用整数权重，即 `sparse_oblique_weights=INTEGER`。权重的最小值。默认值：None。
`sparse_oblique_weights_power_of_two_max_exponent`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE` 并使用 2 的幂权重，即 `sparse_oblique_weights=POWER_OF_TWO`。权重的最大指数。默认值：None。
`sparse_oblique_weights_power_of_two_min_exponent`		对于稀疏斜向分割，即 `split_axis=SPARSE_OBLIQUE` 并使用 2 的幂权重，即 `sparse_oblique_weights=POWER_OF_TWO`。权重的最小指数。默认值：None。
`split_axis`		考虑用于数值特征的分割结构。- `AXIS_ALIGNED`: 轴对齐分割（即每次一个条件）。这是训练树的“经典”方式。默认值。- `SPARSE_OBLIQUE`: 来自 Tomita 等人 2020 年论文“Sparse Projection Oblique Random Forests”的稀疏斜向分割（即对少量特征进行随机分割）。- `MHLD_OBLIQUE`: 来自 Canete-Sifuentes 等人 2029 年论文“Classification Based on Multivariate Contrast Patterns”的多类 Hellinger 线性判别分割。默认值：“AXIS_ALIGNED”。
`subsample`		用于随机采样方法训练单个树的数据集比例（无放回采样）。如果设置了“subsample”且“sampling_method”未设置或设置为“NONE”，则“sampling_method”隐式设置为“RANDOM”。换句话说，要启用随机子采样，只需设置“subsample”即可。默认值：1.0。
`uplift_min_examples_in_treatment`		仅适用于提升模型。节点中每种处理方式的最小示例数量。默认值：5。
`uplift_split_score`		仅适用于提升模型。分割器分数，即由分割器优化的分数。这些分数在 Rzepakowski 等人的论文“Decision trees for uplift modeling with single and multiple treatments”中介绍。记号：`p` 表示正向结果的概率/平均值，`q` 表示对照组的概率/平均值。- `KULLBACK_LEIBLER` 或 `KL`: - p log (p/q) - `EUCLIDEAN_DISTANCE` 或 `ED`: (p-q)^2 - `CHI_SQUARED` 或 `CS`: (p-q)^2/q 默认值：“KULLBACK_LEIBLER”。
`use_hessian_gain`		如果为 true，则使用包含 Hessian 项的分割增益公式，即优化分割以最小化“梯度 / Hessian”的方差。适用于除回归外的所有损失函数。默认值：False。
`validation_interval_in_trees`		每隔“validation_interval_in_trees”棵树在验证集上评估模型。增加此值可降低验证成本，并可能影响提前停止策略（因为提前停止仅在验证期间测试）。默认值：1。
`validation_ratio`		如果未提供验证数据集，则用于验证的训练数据集比例。验证数据集，无论是直接提供还是从训练数据集中提取，都用于计算验证损失、其他验证指标，并可能触发提前停止（如果启用）。禁用提前停止时，验证数据集仅用于监控，不直接影响模型。如果“validation_ratio”设置为 0，则禁用提前停止（即意味着设置 early_stopping=NONE）。默认值：0.1。
`workers`		如果设置，则启用分布式训练。“workers”是工作节点的 IP 地址列表。工作节点是运行 `ydf.start_worker(port)` 的进程。
`resume_training`		如果为 true，模型训练将从存储在 `working_dir` 目录中的检查点恢复。如果 `working_dir` 不包含任何模型检查点，训练将从头开始。恢复训练在以下情况下很有用：（1）训练被用户中断（例如在笔记本中按下 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]
)

此学习器的超参数模板。

超参数模板是预定义的超参数集，用于轻松访问学习器的不同变体。每个模板都映射到一组超参数，可以直接应用于学习器。

使用示例

templates = ydf.GradientBoostedTreesLearner.hyperparameter_templates()
better_defaultv1 = templates["better_defaultv1"]
# Print a description of the template
print(better_defaultv1.description)
# Apply the template's settings on the learner.
learner = ydf.GradientBoostedTreesLearner(label, **better_defaultv1)

返回

类型	描述
`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.GradientBoostedTreesLearner(label="label")
model = learner.train(train_ds)
print(model.summary())

如果训练中断（例如，在 Colab 中中断单元格执行），模型将恢复到中断时的状态。

参数

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

返回

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

train_imp ¶

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

validate_hyperparameters ¶

validate_hyperparameters() -> None

GradientBoostedTreesLearner