AutoML Python API 参考

本文介绍 AutoML Python API，它提供用于启动 AutoML 运行分类、回归和预测的方法。 每个方法调用将训练一组模型，并为每个模型生成一个试运行笔记本。

有关 AutoML 的详细信息（包括低代码 UI 选项）请参阅“什么是 AutoML？”。

分类

databricks.automl.classify 方法配置 AutoML 运行来训练分类模型。

注意

max_trials 参数在 Databricks Runtime 10.4 中已弃用，Databricks Runtime 11.0 ML 及更高版本不支持此参数。 timeout_minutes 用于控制 AutoML 运行的持续时间。

databricks.automl.classify(
  dataset: Union[pyspark.sql.DataFrame, pandas.DataFrame, pyspark.pandas.DataFrame, str],
  *,
  target_col: str,
  primary_metric: str = "f1",
  data_dir: Optional[str] = None,
  experiment_dir: Optional[str] = None,                             # <DBR> 10.4 LTS ML and above
  experiment_name: Optional[str] = None,                            # <DBR> 12.1 ML and above
  exclude_cols: Optional[List[str]] = None,                         # <DBR> 10.3 ML and above
  exclude_frameworks: Optional[List[str]] = None,                   # <DBR> 10.3 ML and above
  feature_store_lookups: Optional[List[Dict]] = None,               # <DBR> 11.3 LTS ML and above
  imputers: Optional[Dict[str, Union[str, Dict[str, Any]]]] = None, # <DBR> 10.4 LTS ML and above
  pos_label: Optional[Union[int, bool, str]] = None,                 # <DBR> 11.1 ML and above
  time_col: Optional[str] = None,
  split_col: Optional[str] = None,                                  # <DBR> 15.3 ML and above
  sample_weight_col: Optional[str] = None                           # <DBR> 15.4 ML and above
  max_trials: Optional[int] = None,                                 # <DBR> 10.5 ML and below
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary

分类参数

参数名称	类型	描述
dataset	str、、pandas.DataFramepyspark.DataFrame、、pyspark.sql.DataFrame	包含训练特征和目标的输入表名称或数据帧。 表名称的格式可以是“<database_name>.<table_name>”或“<schema_name>.<table_name>”（对于非 Unity Catalog 表）。
target_col	str	目标标签的列名。
primary_metric	str	用于评估模型性能并为其排名的指标。 支持的回归指标：“R2”（默认）、“MAE”、“RMSE”、“MSE” 支持的分类指标：“f1”（默认）、“log_loss”、“precision”、“accuracy”、“roc_auc”
data_dir	格式为 dbfs:/<folder-name> 的 str	可选。 用于存储训练数据集的 DBFS 路径。 此路径对驱动程序节点和工作器节点均可见。 Databricks 建议将此字段留空，因此 AutoML 可以将训练数据集保存为 MLflow 项目。 如果指定了自定义路径，数据集不会继承 AutoML 试验的访问权限。
experiment_dir	str	可选。 工作区中用于保存生成的笔记本和试验的目录的路径。 默认值：/Users/<username>/databricks_automl/
experiment_name	str	可选。 AutoML 创建的 MLflow 试验的名称。 默认设置：自动生成名称。
exclude_cols	List[str]	可选。 在 AutoML 计算期间要忽略的列列表。 默认值：[]
exclude_frameworks	List[str]	可选。 AutoML 在开发模型时不应考虑的算法框架列表。 可能的值：空列表，或“sklearn”、“lightGBM”、“xgboost”中的一个或多个。 默认值：[]（考虑所有框架）
feature_store_lookups	List[Dict]	可选。 表示特征存储中用于数据增强的特征的字典的列表。 每个字典中的有效键为： - table_name (str)：必需。 特征表的名称。 - lookup_key（list 或 str）：必需。 将特征表与 dataset 参数中传递的数据联接时用作键的列名。 列名的顺序必须与特征表的主键顺序相匹配。 - timestamp_lookup_key (str)：如果指定的表是时序特征表，则此项为必需项。 使用 dataset 参数中传递的数据对特征表执行时间点查找时使用的列名。 默认值：[]
imputers	Dict[str, Union[str, Dict[str, Any]]]	可选。 字典，其中的每个键是列名，每个值是描述插补策略的字符串或字典。 如果指定为字符串，则该值必须是“mean”、“median”或“most_frequend”之一。 若要使用已知值进行插补，请将该值指定为字典 {"strategy": "constant", "fill_value": <desired value>}。 还可将字符串选项指定为字典，例如 {"strategy": "mean"}。 如果未为列提供插补策略，AutoML 将根据列类型和内容选择默认策略。 如果指定非默认插补方法，则 AutoML 不会执行语义类型检测。 默认值：{}
pos_label	Union[int, bool, str]	（仅分类）正类。 对于计算精度和召回率等指标，这很有用。 只应为二元分类问题指定。
time_col	str	在 Databricks Runtime 10.1 ML 及更高版本中可用。 可选。 时间列的列名。 如果提供，AutoML 会尝试按时间顺序将数据集拆分为训练集、验证集和测试集，使用最早的点作为训练数据，使用最新的点作为测试集。 接受的列类型是 timestamp 和 integer。 对于 Databricks Runtime 10.2ML 及以上版本，也支持字符串列。 如果列类型是字符串，AutoML 尝试使用语义检测将其转换为时间戳。 如果转换失败，则 AutoML 运行失败。
split_col	str	可选。 拆分列的列名。 仅在 Databricks Runtime 15.3 ML 及更高版本中可用于 API 工作流。 如果提供了指定值，AutoML 会尝试按用户指定的值拆分训练/验证/测试集，且此列会自动从训练功能中排除。 接受的列类型为字符串。 此列中每个条目的值必须是下列项之一：“train”、“validate”或“test”。
sample_weight_col	str	在 Databricks Runtime 15.4 ML 及更高版本中可用于分类 API 工作流。 可选。 包含每一行的样本权重的数据集中的列名。 分类支持按类设置的样本权重。 这些权重在模型训练期间调整每个类的重要性。 类中的每个样本必须有相同的样本权重，并且权重必须是 0 到 10,000 范围内的非负小数或整数值。 样本权重越高的类被认为越重要，并且对学习算法的影响越大。 如果未指定此列，则假设所有类具有相同的权重。
max_trials	int	可选。 运行的最大试运行次数。 此参数在 Databricks Runtime 10.5 ML 及更低版本中可用，但从 Databricks Runtime 10.3 ML 开始弃用。 Databricks Runtime 11.0 ML 及更高版本中不支持此参数。 默认值：20 如果 timeout_minutes=None，AutoML 将运行最大试运行次数。
timeout_minutes	int	可选。 表示等待 AutoML 试运行完成的最长时间。 如果超时较长，则 AutoML 可以运行更多的试运行，并为模型标识更高的准确度。 默认值：120 分钟 最小值：5 分钟 如果超时太短，无法完成至少一次试运行，则会报告错误。

回归

databricks.automl.regress 方法配置 AutoML 运行来训练回归模型。 此方法返回 AutoMLSummary。

注意

max_trials 参数在 Databricks Runtime 10.4 中已弃用，Databricks Runtime 11.0 ML 及更高版本不支持此参数。 timeout_minutes 用于控制 AutoML 运行的持续时间。

databricks.automl.regress(
  dataset: Union[pyspark.sql.DataFrame, pandas.DataFrame, pyspark.pandas.DataFrame, str],
  *,
  target_col: str,
  primary_metric: str = "r2",
  data_dir: Optional[str] = None,
  experiment_dir: Optional[str] = None,                             # <DBR> 10.4 LTS ML and above
  experiment_name: Optional[str] = None,                            # <DBR> 12.1 ML and above
  exclude_cols: Optional[List[str]] = None,                         # <DBR> 10.3 ML and above
  exclude_frameworks: Optional[List[str]] = None,                   # <DBR> 10.3 ML and above
  feature_store_lookups: Optional[List[Dict]] = None,               # <DBR> 11.3 LTS ML and above
  imputers: Optional[Dict[str, Union[str, Dict[str, Any]]]] = None, # <DBR> 10.4 LTS ML and above
  time_col: Optional[str] = None,
  split_col: Optional[str] = None,                                  # <DBR> 15.3 ML and above
  sample_weight_col: Optional[str] = None,                          # <DBR> 15.3 ML and above
  max_trials: Optional[int] = None,                                 # <DBR> 10.5 ML and below
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary

回归参数

参数名称	类型	描述
dataset	str、、pandas.DataFramepyspark.DataFrame、、pyspark.sql.DataFrame	包含训练特征和目标的输入表名称或数据帧。 表名称的格式可以是“<database_name>.<table_name>”或“<schema_name>.<table_name>”（对于非 Unity Catalog 表）。
target_col	str	目标标签的列名。
primary_metric	str	用于评估模型性能并为其排名的指标。 支持的回归指标：“R2”（默认）、“MAE”、“RMSE”、“MSE” 支持的分类指标：“f1”（默认）、“log_loss”、“precision”、“accuracy”、“roc_auc”
data_dir	格式为 dbfs:/<folder-name> 的 str	可选。 用于存储训练数据集的 DBFS 路径。 此路径对驱动程序节点和工作器节点均可见。 Databricks 建议将此字段留空，因此 AutoML 可以将训练数据集保存为 MLflow 项目。 如果指定了自定义路径，数据集不会继承 AutoML 试验的访问权限。
experiment_dir	str	可选。 工作区中用于保存生成的笔记本和试验的目录的路径。 默认值：/Users/<username>/databricks_automl/
experiment_name	str	可选。 AutoML 创建的 MLflow 试验的名称。 默认设置：自动生成名称。
exclude_cols	List[str]	可选。 在 AutoML 计算期间要忽略的列列表。 默认值：[]
exclude_frameworks	List[str]	可选。 AutoML 在开发模型时不应考虑的算法框架列表。 可能的值：空列表，或“sklearn”、“lightGBM”、“xgboost”中的一个或多个。 默认值：[]（考虑所有框架）
feature_store_lookups	List[Dict]	可选。 表示特征存储中用于数据增强的特征的字典的列表。 每个字典中的有效键为： - table_name (str)：必需。 特征表的名称。 - lookup_key（list 或 str）：必需。 将特征表与 dataset 参数中传递的数据联接时用作键的列名。 列名的顺序必须与特征表的主键顺序相匹配。 - timestamp_lookup_key (str)：如果指定的表是时序特征表，则此项为必需项。 使用 dataset 参数中传递的数据对特征表执行时间点查找时使用的列名。 默认值：[]
imputers	Dict[str, Union[str, Dict[str, Any]]]	可选。 字典，其中的每个键是列名，每个值是描述插补策略的字符串或字典。 如果指定为字符串，则该值必须是“mean”、“median”或“most_frequend”之一。 若要使用已知值进行插补，请将该值指定为字典 {"strategy": "constant", "fill_value": <desired value>}。 还可将字符串选项指定为字典，例如 {"strategy": "mean"}。 如果未为列提供插补策略，AutoML 将根据列类型和内容选择默认策略。 如果指定非默认插补方法，则 AutoML 不会执行语义类型检测。 默认值：{}
time_col	str	在 Databricks Runtime 10.1 ML 及更高版本中可用。 可选。 时间列的列名。 如果提供，AutoML 会尝试按时间顺序将数据集拆分为训练集、验证集和测试集，使用最早的点作为训练数据，使用最新的点作为测试集。 接受的列类型是 timestamp 和 integer。 对于 Databricks Runtime 10.2ML 及以上版本，也支持字符串列。 如果列类型是字符串，AutoML 尝试使用语义检测将其转换为时间戳。 如果转换失败，则 AutoML 运行失败。
split_col	str	可选。 拆分列的列名。 仅在 Databricks Runtime 15.3 ML 及更高版本中可用于 API 工作流。 如果提供了指定值，AutoML 会尝试按用户指定的值拆分训练/验证/测试集，且此列会自动从训练功能中排除。 接受的列类型为字符串。 此列中每个条目的值必须是下列项之一：“train”、“validate”或“test”。
sample_weight_col	str	在 Databricks Runtime 15.3 ML 及更高版本中可用于回归 API 工作流。 可选。 包含每一行的样本权重的数据集中的列名。 这些权重在模型训练期间会调整每一行的重要性。 权重必须是非负十进制数或整数值，范围从 0 到 10,000。 样本权重越高的行被认为越重要，并且对学习算法的影响越大。 如果未指定此列，则假设所有行具有相同的权重。
max_trials	int	可选。 运行的最大试运行次数。 此参数在 Databricks Runtime 10.5 ML 及更低版本中可用，但从 Databricks Runtime 10.3 ML 开始弃用。 Databricks Runtime 11.0 ML 及更高版本中不支持此参数。 默认值：20 如果 timeout_minutes=None，AutoML 将运行最大试运行次数。
timeout_minutes	int	可选。 表示等待 AutoML 试运行完成的最长时间。 如果超时较长，则 AutoML 可以运行更多的试运行，并为模型标识更高的准确度。 默认值：120 分钟 最小值：5 分钟 如果超时太短，无法完成至少一次试运行，则会报告错误。

预测

databricks.automl.forecast 配置一个用于训练预测模型的 AutoML 运行。 此方法返回 AutoMLSummary。 要使用 Auto-ARIMA，时间序列必须有一个规则的频率（也就是说，任意两点之间的间隔必须在整个时间序列中相同）。 频率必须与 API 调用中指定的频率单位相匹配。 AutoML 通过用前一个值填充这些值，以此来处理丢失的时间步长。

databricks.automl.forecast(
  dataset: Union[pyspark.sql.DataFrame, pandas.DataFrame, pyspark.pandas.DataFrame, str],
  *,
  target_col: str,
  time_col: str,
  primary_metric: str = "smape",
  country_code: str = "US",                                         # <DBR> 12.0 ML and above
  frequency: str = "D",
  horizon: int = 1,
  data_dir: Optional[str] = None,
  experiment_dir: Optional[str] = None,
  experiment_name: Optional[str] = None,                            # <DBR> 12.1 ML and above
  exclude_frameworks: Optional[List[str]] = None,
  feature_store_lookups: Optional[List[Dict]] = None,               # <DBR> 12.2 LTS ML and above
  identity_col: Optional[Union[str, List[str]]] = None,
  sample_weight_col: Optional[str] = None,                          # <DBR> 16.0 ML and above
  output_database: Optional[str] = None,                            # <DBR> 10.5 ML and above
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary

预测参数

参数名称	类型	描述
dataset	str、、pandas.DataFramepyspark.DataFrame、、pyspark.sql.DataFrame	包含训练特征和目标的输入表名称或数据帧。 表名称的格式可以是“..” 或“.” 对于非 Unity Catalog 表
target_col	str	目标标签的列名。
time_col	str	用于预测的时间列的名称。
primary_metric	str	用于评估模型性能并为其排名的指标。 支持的指标：“smape”（默认值）、“mse”、“rmse”、“mae”或“mdape”。
country_code	str	适用于 Databricks Runtime 12.0 ML 和更高版本。 仅受 Prophet 预测模型支持。 可选。 双字母国家/地区代码，指示预测模型应使用哪个国家/地区的节假日。 若要忽略节假日，请将此参数设置为空字符串 (“”)。 支持的国家/地区。 默认值：US（美国节假日）。
frequency	str	用于预测的时序的频率。 这是预期事件发生的时间段。 默认设置是“D”或每日数据。 如果数据有其他频率，请务必更改该设置。 可能的值： “W” (weeks) "D" / "days" / "day" “hours” / “hour” / “hr” / “h” “m” / “minute” / “min” / “minutes” / “T” “S” / “seconds” / “sec” / “second” 以下内容仅适用于 Databricks Runtime 12.0 ML 和更高版本： “M” / “month” / “months” “Q” / “quarter” / “quarters” “Y” / “year” / “years” 默认值：“D”
horizon	int	预测应返回的将来的时间段数。 单位是时序频率。 默认值：1
data_dir	格式为 dbfs:/<folder-name> 的 str	可选。 用于存储训练数据集的 DBFS 路径。 此路径对驱动程序节点和工作器节点均可见。 Databricks 建议将此字段留空，因此 AutoML 可以将训练数据集保存为 MLflow 项目。 如果指定了自定义路径，数据集不会继承 AutoML 试验的访问权限。
experiment_dir	str	可选。 工作区中用于保存生成的笔记本和试验的目录的路径。 默认值：/Users/<username>/databricks_automl/
experiment_name	str	可选。 AutoML 创建的 MLflow 试验的名称。 默认设置：自动生成名称。
exclude_frameworks	List[str]	可选。 AutoML 在开发模型时不应考虑的算法框架列表。 可能的值：空列表，或者是“prophet”、“arima”中的一个或多个。 默认值：[]（考虑所有框架）
feature_store_lookups	List[Dict]	可选。 表示特征存储中用于协变量数据增强的特征的字典的列表。 每个字典中的有效键为： - table_name (str)：必需。 特征表的名称。 - lookup_key（list 或 str）：必需。 将特征表与 dataset 参数中传递的数据联接时用作键的列名。 列名的顺序必须与特征表的主键顺序相匹配。 - timestamp_lookup_key (str)：如果指定的表是时序特征表，则此项为必需项。 使用 dataset 参数中传递的数据对特征表执行时间点查找时使用的列名。 默认值：[]
identity_col	Union[str, list]	可选。 用于标识多系列预测的时序的列。 AutoML 按这些列和用于预测的时间列进行分组。
sample_weight_col	str	在 Databricks Runtime 16.0 ML 及更高版本中可用。 仅适用于多时序工作流。 可选。 指定数据集中包含样本权重的列。 这些权重指示模型训练和评估期间每个时序的相对重要性。 权重较高的时序对模型的影响更大。 如果未提供，则所有时序都以相等的权重进行处理。 属于同一时序的所有行必须具有相同的权重。 权重必须是非负值（小数或整数）且介于 0 和 10,000 之间。
output_database	str	可选。 如果已提供，则 AutoML 会将最佳模型的预测结果保存到指定的数据库中的新表中。 默认设置：不保存预测结果。
timeout_minutes	int	可选。 表示等待 AutoML 试运行完成的最长时间。 如果超时较长，则 AutoML 可以运行更多的试运行，并为模型标识更高的准确度。 默认值：120 分钟 最小值：5 分钟 如果超时太短，无法完成至少一次试运行，则会报告错误。

导入笔记本

databricks.automl.import_notebook 方法导入已保存为 MLflow 项目的笔记本。 此方法返回 ImportNotebookResult。

databricks.automl.import_notebook(
  artifact_uri: str,
  path: str,
  overwrite: bool = False
) -> ImportNotebookResult:

参数	类型	描述
artifact_uri	str	包含试用笔记本的 MLflow 项目的 URI。
path	str	Databricks 工作区中应导入笔记本的路径。 它必须为绝对路径。 将创建目录（如果不存在）。
overwrite	bool	如果笔记本已经存在，指示是否将其覆盖。 默认情况下，它为 False。

导入笔记本示例

summary = databricks.automl.classify(...)
result = databricks.automl.import_notebook(summary.trials[5].artifact_uri, "/Users/you@yourcompany.com/path/to/directory")
print(result.path)
print(result.url)

AutoMLSummary

AutoML 运行的摘要对象，用于描述每个试运行的指标、参数和其他详细信息。 还可以使用此对象加载特定试运行训练的模型。

属性	类型​​	描述
experiment	mlflow.entities.Experiment	MLflow 试验用于记录试运行。
trials	List[TrialInfo]	TrialInfo 对象的列表，其中包含有关已运行的所有试运行的信息。
best_trial	TrialInfo	TrialInfo 对象，其中包含产生了主要指标最佳加权评分的试运行的相关信息。
metric_distribution	str	所有试运行中主要指标的加权评分的分布情况。
output_table_name	str	仅用于预测且仅在提供 output_database 时使用。 包含模型预测的 output_database 中表的名称。

TrialInfo

每个试运行的摘要对象。

属性	类型​​	描述
notebook_path	Optional[str]	此试运行生成的笔记本在工作区中的路径。 对于分类和回归，此值仅为最佳试用设置，而所有其他试验的值都设置为 None。 对于预测，此值适用于所有试运行。
notebook_url	Optional[str]	此试运行生成的笔记本的 URL。 对于分类和回归，此值仅为最佳试用设置，而所有其他试验的值都设置为 None。 对于预测，此值适用于所有试运行。
artifact_uri	Optional[str]	生成的笔记本的 MLflow 项目 URI。
mlflow_run_id	str	与此试运行关联的 MLflow 运行 ID。
metrics	Dict[str, float]	在此试运行的 MLflow 中记录的指标。
params	Dict[str, str]	在为此试运行使用的 MLflow 中记录的参数。
model_path	str	此试运行中训练的模型的 MLflow 项目 URL。
model_description	str	模型的简短说明以及用于训练此模型的超参数。
duration	str	训练持续时间，以分钟为单位。
preprocessors	str	在训练模型之前运行的预处理器的说明。
evaluation_metric_score	float	为验证数据集评估的主要指标的评分。

TrialInfo 具有一种方法来加载为试运行生成的模型。

方法	说明
load_model()	加载在此试运行中生成的模型，记录为 MLflow 项目。

ImportNotebookResult

properties	类型​​	描述
path	str	Databricks 工作区中应导入笔记本的路径。 它必须为绝对路径。 将创建目录（如果不存在）。
url	str	包含试用笔记本的 MLflow 项目的 URI。