通过

Azure Databricks AutoML Python API 参考

  • 项目

本文介绍 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 包含训练特征和目标的输入表名称或数据帧。 对于非 Unity Catalog 表，表名可以采用“<database_name>.<table_name>”或“<schema_name>.<table_name>”格式。
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_frequent”中的一个。 若要使用已知值进行插补，请将该值指定为字典 {"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 包含训练特征和目标的输入表名称或数据帧。 对于非 Unity Catalog 表，表名可以采用“<database_name>.<table_name>”或“<schema_name>.<table_name>”格式。
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_frequent”中的一个。 若要使用已知值进行插补，请将该值指定为字典 {"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"（周）

"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。