autogluon.tabular.TabularPredictor

class autogluon.tabular.TabularPredictor(label: str, problem_type: str = None, eval_metric: str | Scorer = None, path: str = None, verbosity: int = 2, log_to_file: bool = False, log_file_path: str = 'auto', sample_weight: str = None, weight_evaluation: bool = False, groups: str = None, positive_class: int | str | None = None, **kwargs)

AutoGluon TabularPredictor 预测表格数据集（分类或回归）中某一列的值。

参数：

• label (str) – 包含要预测的目标变量的列的名称。

• problem_type (str, default = None) – 预测问题的类型，即是二分类/多分类还是回归问题（选项：‘binary’、‘multiclass’、‘regression’、‘quantile’）。如果 problem_type = None，则根据提供数据集中的标签值推断预测问题类型。

• eval_metric (str or Scorer, default = None) –

  最终用于评估测试数据上预测结果的指标。AutoGluon 调整超参数、早停、集成权重等因素，以改善在验证数据上的此指标。

  如果 eval_metric = None，则会根据 problem_type 自动选择。二分类和多分类的默认值为“accuracy”，回归的默认值为“root_mean_squared_error”，分位数回归的默认值为“pinball_loss”。

  否则，分类的选项有

  [‘accuracy’, ‘balanced_accuracy’, ‘log_loss’, ‘f1’, ‘f1_macro’, ‘f1_micro’, ‘f1_weighted’, ‘roc_auc’, ‘roc_auc_ovo’, ‘roc_auc_ovo_macro’, ‘roc_auc_ovo_weighted’, ‘roc_auc_ovr’, ‘roc_auc_ovr_macro’, ‘roc_auc_ovr_micro’, ‘roc_auc_ovr_weighted’, ‘average_precision’, ‘precision’, ‘precision_macro’, ‘precision_micro’, ‘precision_weighted’, ‘recall’, ‘recall_macro’, ‘recall_micro’, ‘recall_weighted’, ‘mcc’, ‘pac_score’]

  回归的选项有

  [‘root_mean_squared_error’, ‘mean_squared_error’, ‘mean_absolute_error’, ‘median_absolute_error’, ‘mean_absolute_percentage_error’, ‘r2’, ‘symmetric_mean_absolute_percentage_error’]

  有关这些选项的更多信息，请参见 sklearn.metrics：https://scikit-learn.cn/stable/modules/classes.html#sklearn-metrics-metrics 有关指标源代码，请参见 autogluon.core.metrics。

  您也可以在此处传递您自己的评估函数，只要其遵循 autogluon.core.metrics 文件夹中定义的函数的格式即可。有关创建和使用自定义指标的详细说明，请参阅 https://autogluon.cn/stable/tutorials/tabular/advanced/tabular-custom-metric.html

• path (Union[str, pathlib.Path], default = None) – 保存模型和中间输出的目录路径。如果未指定，将在工作目录中创建一个名为“AutogluonModels/ag-[TIMESTAMP]”的时间戳文件夹来存储所有模型。注意：要两次调用 fit() 并保存每次 fit 的所有结果，您必须指定不同的 path 位置，或者完全不指定 path。否则，第一次 fit() 的文件将被第二次 fit() 覆盖。

• verbosity (int, default = 2) –

  详细级别范围从 0 到 4，控制打印的信息量。级别越高，打印的详细信息越多（您可以设置 verbosity = 0 来抑制警告）。如果使用日志记录，您还可以通过 logger.setLevel(L) 控制打印的信息量，其中 L 的范围为 0 到 50（注意：L 的值越高，打印的信息越少，与详细级别相反）。详细级别如下：

  0：仅记录异常 1：仅记录警告 + 异常 2：标准日志记录 3：详细日志记录（例如：每 50 次迭代记录一次验证分数） 4：最大详细日志记录（例如：每次迭代记录一次验证分数）

• log_to_file (bool, default = False) – 是否将日志保存到文件中以便将来参考

• log_file_path (str, default = "auto") – 保存日志的文件路径。如果设置为 auto，日志将保存到 predictor_path/logs/predictor_log.txt 下。如果 log_to_file 设置为 False，此参数将被忽略。

• sample_weight (str, default = None) – 如果指定，此列名指示应将数据中的哪一列视为样本权重。此列将不被视为预测特征。样本权重应为非负值（且不能为 nan），值越大表示该行比其他行更重要。如果您希望样本权重的用法与此 Predictor 外部获得的结果一致，请确保训练（或调优）数据的样本权重总和等于训练（或调优）数据中的行数。您还可以指定两个特殊字符串：“auto_weight”（根据数据自动选择加权策略）或“balance_weight”（在分类中对类别进行等权重处理，对回归无效）。如果指定您自己的 sample_weight 列，请确保其名称与这些特殊字符串不冲突。

• weight_evaluation (bool, default = False) – 仅当 sample_weight 列不为 None 时考虑。确定在计算验证/测试数据上的评估指标时是否应考虑样本权重。如果为 True，则根据指定的 sample_weight 提供样本权重的加权指标将被报告（在这种情况下，sample_weight 列也必须存在于测试数据中）。在这种情况下，默认用于预测的“最佳”模型也将根据评估指标的加权版本决定。注意：当 sample_weight 是“auto_weight”或“balance_weight”时，我们不建议指定 weight_evaluation，而应指定适当的 eval_metric。

• groups (str, default = None) –

  [实验性功能] 如果指定，AutoGluon 将在 .fit 期间使用 train_data 中名为 groups 的列作为 bagging 的数据分割索引。此列在模型训练期间不会用作特征。如果未启用 bagging，则此参数将被忽略。若要在禁用 bagging 的情况下指定自定义验证集，请在 .fit 中指定 tuning_data。数据将通过 sklearn.model_selection.LeaveOneGroupOut 进行分割。使用此选项可以控制 AutoGluon 使用的确切分割索引。除非在非常特殊的情况下需要，否则不建议使用此选项。如果提供的组无效而无法正确训练模型（例如，在多分类中训练期间并非所有类别都存在），则可能会出现边缘情况错误。用户有责任清理其组。

  例如，如果您希望数据折叠在表格中保留相邻行而不进行洗牌，那么对于 6 行数据的 3 折 bagging，groups 列的值应为 [0, 0, 1, 1, 2, 2]。

• positive_class (str or int, default = None) –

  用于确定二分类中的正类别。这用于某些指标（如“f1”），这些指标根据哪个类别被视为正类别而产生不同的分数。如果未设置，将推断为现有唯一类别排序后的第二个元素。

  如果类别是 [0, 1]，则将 1 选择为正类别。如果类别是 [‘def’, ‘abc’]，则将 ‘def’ 选择为正类别。如果类别是 [True, False]，则将 True 选择为正类别。

• **kwargs –

  learner_typeAbstractLearner, default = DefaultLearner

  一个继承自 AbstractLearner 的类。这决定了 predictor 的内部逻辑。如果您不知道这是什么，请保持其为默认值。

  learner_kwargsdict, default = None

  要发送给 learner 的 kwargs。选项包括

  ignored_columnslist, default = None

  predictor 不能用作预测特征的禁止列名子集（例如行的唯一标识符或用户 ID）。这些列在 fit() 期间会被忽略。

  label_count_thresholdint, default = 10

  对于多分类问题，这是标签在数据集中必须出现的最小次数才能被视为输出类别。AutoGluon 将忽略数据集中标签出现次数少于此次数的任何类别（即永远不会预测它们）。

  cache_databool, default = True

  启用后，训练和验证数据将保存到磁盘以供将来重用。启用 predictor 中的高级功能，例如 fit_extra() 和在原始数据上计算特征重要性。

  trainer_typeAbstractTabularTrainer, default = AutoTrainer

  一个继承自 AbstractTabularTrainer 的类，用于控制多个模型的训练/集成。如果您不知道这是什么，请保持其为默认值。

__init__(label: str, problem_type: str = None, eval_metric: str | Scorer = None, path: str = None, verbosity: int = 2, log_to_file: bool = False, log_file_path: str = 'auto', sample_weight: str = None, weight_evaluation: bool = False, groups: str = None, positive_class: int | str | None = None, **kwargs)

方法

calibrate_decision_threshold	在二分类中校准决策阈值以优化给定指标。
clone	将 predictor 及其所有 artifact 克隆到本地磁盘上的新位置。
clone_for_deployment	将 predictor 及其所有 artifact 克隆到本地磁盘上的新位置，然后删除克隆 artifact 中预测期间不必要的部分。
compile	编译模型以加速预测。
delete_models	从 predictor 中删除模型。这有助于最小化内存和磁盘使用，特别是对于模型部署。这将删除 predictor 中对模型的所有引用。例如，删除的模型将不会出现在 predictor.leaderboard() 中。警告：如果设置 delete_from_disk=True，这将删除已删除模型目录中的所有文件，无论它们是否由 AutoGluon 创建。请勿将与 AutoGluon 无关的文件存储在模型目录中。
disk_usage	返回 predictor.path 目录下所有文件的总大小（以字节为单位）。
disk_usage_per_file	返回 predictor.path 目录下每个文件的大小（以字节为单位）。
distill	[实验性功能] 将 AutoGluon 最准确的集成预测器蒸馏成更简单/更快且需要更少内存/计算的单个模型。
evaluate	报告在给定数据集上评估的预测性能。
evaluate_predictions	根据真实标签评估提供的预测概率。
feature_importance	通过置换重要性计算给定模型的特征重要性分数。
features	返回一个依赖于 feature_stage 值的功能名称列表。
fit	拟合模型，根据数据表（features）的其他列预测某一列（label）的值。
fit_extra	在原始的 TabularPredictor.fit() 调用之后拟合额外的模型。
fit_pseudolabel	[高级功能] 使用额外数据 (pseudo_data) 来尝试获得更好的模型质量。
fit_summary	输出 fit() 期间生成的模型信息摘要。
fit_weighted_ensemble	拟合新的加权集成模型，以结合先前训练模型的预测结果。
info	[实验性功能] 返回 predictor 元数据的字典。警告：此功能目前处于预览模式。返回的元数据信息结构可能会在未来版本中更改，恕不另行通知。各种元数据值的定义尚未记录。此函数的输出不应用于程序性决策。包含诸如行数、列数、模型训练时间、验证分数、超参数等信息。
leaderboard	将 fit() 期间生成的模型信息摘要输出为 pd.DataFrame。包括所有模型的测试和验证分数、模型训练时间、推理时间以及堆叠级别信息。输出 DataFrame 列包括：'model'：模型的名称。
learning_curves	检索 predictor.fit() 期间生成的学习曲线。
load	从文件加载先前由 fit() 生成的 TabularPredictor 对象并返回此对象。
load_data_internal	加载模型训练期间使用的内部数据表示。诸如神经网络之类的单个 AutoGluon 模型可能会应用此方法中未反映的其他特征转换。此方法仅应用所有 AutoGluon 模型使用的通用转换。警告：内部表示可能：与原始数据相比具有不同的特征。与原始数据相比具有不同的行数。具有与原始数据不一致的索引。具有与原始数据中不同的标签值。内部数据表示不应与原始数据结合使用，在大多数情况下这是不可能的。
load_log	加载 predictor 的日志文件
model_failures	[高级功能] 获取模型拟合期间发生的模型失败，以 pandas DataFrame 的形式呈现。
model_hyperparameters	返回给定模型的超参数。
model_info	返回给定模型的元数据信息。
model_names	返回在此 predictor 对象中训练的模型名称列表。
model_refit_map	返回原始模型名称 -> refit full 模型名称的字典。
persist	将模型持久化到内存中以减少推理延迟。
plot_ensemble_model	输出 fit() 训练的模型的可视化堆叠集成架构。
predict	使用训练好的模型预测新数据的 label 列值。
predict_from_proba	给定预测概率，转换为预测结果。
predict_multi	返回一个预测字典，其中键是模型名称，值是模型在该数据上的预测概率。
predict_oof	注意：这是高级功能，不适用于普通使用。
predict_proba	使用训练好的模型生成预测的类别概率，而不是类别标签（如果任务是分类）。
predict_proba_multi	返回一个预测概率字典，其中键是模型名称，值是模型在该数据上的预测概率。
predict_proba_oof	注意：这是高级功能，不适用于普通使用。
refit_full	在所有数据（训练 + 验证）上重新训练模型。对于 Bagging 模型：通过将 Bagging 集成折叠到在所有训练数据上拟合的单个模型中来优化模型的推理时间。此过程通常会导致准确率略有下降，但推理速度会大幅提升。推理速度通常比原始 Bagging 集成模型快 10-200 倍。推理加速因子相当于 (k * n)，其中 k 是 Bagging 集成中的折叠数 (num_bag_folds)，n 是完成的重复次数 (num_bag_sets)。运行时通常是原始 fit 运行时的 10% 或更少。运行时可以大致估计为原始 fit 运行时的 1 / (k * n)，其中 k 和 n 如上所述。对于非 Bagging 模型：通过在不使用验证集的情况下对 100% 的数据进行再训练来优化模型准确率。通常会导致准确率略有提升，并且推理时间没有变化。运行时将大约等于原始 fit 运行时。此过程不会修改原始模型，而是添加额外的模型。如果堆叠模型通过此过程重新拟合，它们将在推理期间使用祖先模型的 refit_full 版本。此过程生成的模型将没有验证分数，因为它们使用所有数据进行训练。因此，用户需要通过在 predictor.leaderboard(test_data) 中包含测试数据来确定模型的质量是否足够。如果用户没有额外的测试数据，他们应参考原始模型的分数来估计 refit_full 模型的性能。警告：请注意，在未单独在测试数据上验证的情况下使用 refit_full 模型意味着模型未经测试，并且不能保证与原始模型一致。在原始训练期间必须将 cache_data 设置为 True 才能启用此功能。
save	将此 Predictor 保存到由其 path 指定的目录中的文件中。
save_space	通过删除在新数据上进行预测不需要的辅助模型文件来减少 predictor 的内存和磁盘占用空间。
set_decision_threshold	设置 predictor.decision_threshold。
set_model_best	设置调用 predictor.predict(data) 时默认使用的模型。
simulation_artifact	[高级功能] 计算并返回执行零样本 HPO 模拟所需的信息。
transform_features	通过 AutoGluon 特征生成器转换数据特征。这有助于了解 AutoGluon 如何解释数据特征。此函数的输出可用于训练更多模型，即使在 AutoGluon 之外。这对于在与 AutoGluon 相同的数据表示上训练您自己的模型非常有用。诸如神经网络之类的单个 AutoGluon 模型可能会应用此方法中未反映的其他特征转换。此方法仅应用所有 AutoGluon 模型使用的通用转换。当 data=None，base_models=[{best_model}]，并且在 fit() 期间启用了 bagging 时：这将返回最佳模型的折叠外预测，可用作自定义用户堆叠模型的训练输入。
transform_labels	将数据标签转换为内部标签表示。
unpersist	从内存中解除模型的持久化状态以减少内存使用。

属性

can_predict_proba	如果 predictor 可以通过 .predict_proba 返回预测概率，则返回 True；否则返回 False。
class_labels	self.classes_ 的别名
class_labels_internal	对于多分类问题，此列表包含内部类别标签，按内部 predict_proba() 输出的排序顺序排列。对于二分类问题，此列表包含内部类别标签，按内部 predict_proba(as_multiclass=True) 输出的排序顺序排列。对于二分类问题，其值始终为 class_labels_internal=[0, 1]，其中 0 为负类别，1 为正类别。对于其他问题类型，此值为 None。
class_labels_internal_map	对于二分类和多分类问题，此字典包含原始标签到内部标签的映射。例如，在二分类中，标签值“True”和“False”将被映射到内部表示 1 和 0。因此，class_labels_internal_map 将等于 {'True': 1, 'False': 0}。对于其他问题类型，此值为 None。对于多分类，可能并非所有标签值都有映射。这表明内部模型永远不会预测那些缺失的标签，并且与缺失标签相关的训练行已被删除。
classes_	对于多分类问题，此列表包含类别标签，按 predict_proba() 输出的排序顺序排列。对于二分类问题，此列表包含类别标签，按 predict_proba(as_multiclass=True) 输出的排序顺序排列。classes_[0] 对应于内部标签 = 0（负类别），classes_[1] 对应于内部标签 = 1（正类别）。这对于某些指标（如 F1）非常重要，其中 True 和 False 标签对指标分数的影响不同。对于其他问题类型，此值为 None。例如，如果 pred = predict_proba(x, as_multiclass=True)，则 pred 的第 i 个索引提供 x 属于由 classes_[i] 给定的类别的预测概率。
decision_threshold	用于将预测概率转换为预测结果的决策阈值。
eval_metric	用于评估预测性能的指标
feature_metadata	返回内部 FeatureMetadata。
feature_metadata_in	返回输入 FeatureMetadata。
has_val	如果在 fit 期间使用了留出验证数据，则返回 True；否则返回 False。
is_fit	如果 predictor.fit 已被调用，则返回 True；否则返回 False。
label	标签、响应变量、目标变量、因变量、y 等)。
model_best	返回按验证分数衡量的最佳模型的字符串名称，该模型可以进行推理。
original_features	用户在处理前传递给 fit 的原始特征
path	此 Predictor 使用的所有模型存储目录的路径
positive_class	返回二分类中的正类别名称。
predictor_file_name
problem_type	此 Predictor 训练用于解决的预测问题类型
quantile_levels