Azure Databricks AutoML Python API 参考

项目
07/24/2024

本文介绍 Azure Databricks AutoML Python API，该 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,
  data_dir: Optional[str] = None,
  exclude_cols: Optional[List[str]] = None,                      # <DBR> 10.3 ML and above
  exclude_frameworks: Optional[List[str]] = None,                   # <DBR> 10.3 ML and above
  experiment_dir: Optional[str] = None,                             # <DBR> 10.4 LTS ML and above
  experiment_name: Optional[str] = None,                            # <DBR> 12.1 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
  max_trials: Optional[int] = None,                                 # <DBR> 10.5 ML and below
  pos_label: Optional[Union[int, bool, str] = None,                 # <DBR> 11.1 ML and above
  primary_metric: str = "f1",
  time_col: Optional[str] = None,
  timeout_minutes: Optional[int] = None,
  split_col: Optional[str] = None,                                  # <DBR> 15.3 ML and above
  sample_weight_col: Optional[str] = None                           # <DBR> 15.4 ML and above
) -> AutoMLSummary

分类参数

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

回归

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,
  data_dir: Optional[str] = None,
  exclude_cols: Optional[List[str]] = None,                      # <DBR> 10.3 ML and above
  exclude_frameworks: Optional[List[str]] = None,                   # <DBR> 10.3 ML and above
  experiment_dir: Optional[str] = None,                             # <DBR> 10.4 LTS ML and above
  experiment_name: Optional[str] = None,                            # <DBR> 12.1 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
  max_trials: Optional[int] = None,                                 # <DBR> 10.5 ML and below
  primary_metric: str = "r2",
  time_col: Optional[str] = None,
  timeout_minutes: Optional[int] = None,
  split_col: Optional[str] = None,                                  # <DBR> 15.3 ML and above
  sample_weight_col: Optional[str] = None,                          # <DBR> 15.3 ML and above
) -> AutoMLSummary

回归参数

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

预测

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,
  country_code: str = "US",                                         # <DBR> 12.0 ML and above
  data_dir: Optional[str] = None,
  exclude_frameworks: Optional[List[str]] = None,
  experiment_dir: Optional[str] = None,
  experiment_name: Optional[str] = None,                            # <DBR> 12.1 ML and above
  feature_store_lookups: Optional[List[Dict]] = None,               # <DBR> 12.2 LTS ML and above
  frequency: str = "D",
  horizon: int = 1,
  identity_col: Optional[Union[str, List[str]]] = None,
  output_database: Optional[str] = None,                            # <DBR> 10.5 ML and above
  primary_metric: str = "smape",
  timeout_minutes: Optional[int] = None,
) -> AutoMLSummary

预测参数

参数名称	类型	描述
`dataset`	`str`、`pandas.DataFrame`、`pyspark.DataFrame`、`pyspark.sql.DataFrame`	包含训练特征和目标的输入表名称或数据帧。表名称的格式可以是“..” 或“.” 对于非 Unity Catalog 表
`target_col`	`str`	目标标签的列名。
`time_col`	`str`	用于预测的时间列的名称。
`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 试验的访问权限。
`exclude_frameworks`	`List[str]`	可选。 AutoML 在开发模型时不应考虑的算法框架列表。可能的值：空列表，或者是“prophet”、“arima”中的一个或多个。默认值：[]（考虑所有框架）
`experiment_dir`	`str`	可选。工作区中用于保存生成的笔记本和试验的目录的路径。默认值：`/Users/<username>/databricks_automl/`
`experiment_name`	`str`	可选。 AutoML 创建的 MLflow 试验的名称。默认设置：自动生成名称。
`feature_store_lookups`	`List[Dict]`	可选。表示特征存储中用于数据增强的特征的字典的列表。每个字典中的有效键为： * `table_name` (str)：必需。特征表的名称。 * `lookup_key`（list 或 str）：必需。将特征表与 `dataset` 参数中传递的数据联接时用作键的列名。列名的顺序必须与特征表的主键顺序相匹配。 * `timestamp_lookup_key` (str)：如果指定的表是时序特征表，则此项为必需项。使用 `dataset` 参数中传递的数据对特征表执行时间点查找时使用的列名。默认值：[]
`identity_col`	`Union[str, list]`	可选。用于标识多系列预测的时序的列。 AutoML 按这些列和用于预测的时间列进行分组。
`output_database`	`str`	可选。如果已提供，则 AutoML 会将最佳模型的预测结果保存到指定的数据库中的新表中。默认设置：不保存预测结果。
`primary_metric`	`str`	用于评估模型性能并为其排名的指标。支持的指标：“smape”（默认值）、“mse”、“rmse”、“mae”或“mdape”。
`timeout_minutes`	`int`	可选。表示等待 AutoML 试运行完成的最长时间。如果超时较长，则 AutoML 可以运行更多的试运行，并为模型标识更高的准确度。默认值：120 分钟最小值：5 分钟如果超时太短，无法完成至少一次试运行，则会报告错误。
`country_code`	`str`	适用于 Databricks Runtime 12.0 ML 和更高版本。仅受 Prophet 预测模型支持。可选。双字母国家/地区代码，指示预测模型应使用哪个国家/地区的节假日。若要忽略节假日，请将此参数设置为空字符串 (“”)。支持的国家/地区。默认值：US（美国节假日）。

导入笔记本

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。

通过