使用 Azure Databricks AutoML Python API 训练 ML 模型
本文演示如何通过 API 训练使用 Azure Databricks AutoML 的模型。 详细了解什么是 AutoML？。 Python API 提供用于启动分类、回归和预测 AutoML 运行的函数。 每个函数调用将训练一组模型，并为每个模型生成一个试运行笔记本。
以下步骤概括性地说明了如何使用 API 设置 AutoML 试验：
- 创建一个笔记本并将其附加到运行 Databricks Runtime ML 的群集。
- 确定要从现有数据源使用哪个表，或者将数据文件上传到 DBFS 并创建表。
- 若要启动 AutoML 运行，请将表名传递给相应的 API 规范：分类、回归或预测。
- AutoML 运行开始时，控制台中会显示 MLflow 试验 URL。 使用此 URL 可以监视运行进度。 刷新 MLflow 试验查看已完成的试运行。
- AutoML 运行完成后：
- 使用输出摘要中的链接导航到 MLflow 试验或导航到生成最佳结果的笔记本。
- 使用数据探索笔记本的链接可以深入了解传递给 AutoML 的数据。 还可以将此笔记本附加到同一群集，然后重新运行此笔记本以重现结果或执行其他数据分析。
- 使用 AutoML 调用返回的摘要对象来探索有关试验的更多详细信息或加载给定试运行训练的模型。 详细了解 AutoMLSummary 对象。
- 克隆试运行生成的任何笔记本，并通过将其附加到同一群集来重新运行该笔记本，以重现结果。 还可以进行必要的编辑，然后重新运行该笔记本以训练其他模型并将其记录到同一个试验中。
要求
请参阅 AutoML 试验的要求。
分类规范
以下代码示例配置一个用于训练分类模型的 AutoML 运行。 有关用于进一步自定义 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,
) -> AutoMLSummary
回归规范
以下代码示例配置一个用于训练回归模型的 AutoML 运行。 有关用于进一步自定义 AutoML 运行的其他参数，请参阅分类和回归参数。
注意
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,
) -> AutoMLSummary
预测规范
以下代码示例配置一个用于训练预测模型的 AutoML 运行。 有关 AutoML 运行参数的更多详细信息，请参阅预测参数。 要使用 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 | 目标标签的列名。 |
| data_dir | str，格式为dbfs:/<folder-name> |
（可选）用于存储训练数据集的 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 参数中传递的数据对特征表执行时间点查找时使用的列名。默认值：[] |
| 填补器 | 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” |
| time_col | str | 在 Databricks Runtime 10.1 ML 及更高版本中可用。 （可选）时间列的列名。 如果提供，AutoML 会尝试按时间顺序将数据集拆分为训练集、验证集和测试集，使用最早的点作为训练数据，使用最新的点作为测试集。 接受的列类型是 timestamp 和 integer。 对于 Databricks Runtime 10.2ML 及以上版本，也支持字符串列。 如果列类型是字符串，AutoML 尝试使用语义检测将其转换为时间戳。 如果转换失败，则 AutoML 运行失败。 |
| timeout_minutes | int | （可选）表示等待 AutoML 试运行完成的最长时间。 如果超时较长，则 AutoML 可以运行更多的试运行，并为模型标识更高的准确度。 默认值：120 分钟 最小值：5 分钟 如果超时太短，无法完成至少一次试运行，则会报告错误。 |
预测参数
| 字段名称 | 类型 | 说明 |
|---|---|---|
| dataset | str pandas.DataFrame pyspark.DataFrame pyspark.sql.DataFrame |
包含训练特征和目标的输入表名称或数据帧。 对于非 Unity Catalog 表，表名的格式可以是“..”或“.” |
| target_col | str | 目标标签的列名。 |
| time_col | str | 用于预测的时间列的名称。 |
| 频率 | 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” |
| 范围 | int | 预测应返回的将来的时间段数。 单位是时序频率。 默认值：1 |
| data_dir | str，格式为dbfs:/<folder-name> |
（可选）用于存储训练数据集的 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（美国节假日）。 |
返回值
AutoMLSummary
AutoML 运行的摘要对象，用于描述每个试运行的指标、参数和其他详细信息。 还可以使用此对象加载特定试运行训练的模型。
| 属性 | 类型 | 说明 |
|---|---|---|
| experiment | mlflow.entities.Experiment | MLflow 试验用于记录试运行。 |
| trials | List[TrialInfo] | 一个列表，其中包含有关已运行的所有试运行的信息。 |
| best_trial | 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。 |
| 指标 | 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 | 为验证数据集评估的主要指标的评分。 |
| 方法 | 说明 |
|---|---|
| load_model() | 加载在此试运行中生成的模型，记录为 MLflow 项目。 |
导入笔记本
若要导入已保存为 MLflow 项目的笔记本，请使用 databricks.automl.import_notebook Python API。
def import_notebook(artifact_uri: str, path: str, overwrite: bool = False) -> ImportNotebookResult:
"""
Import a trial notebook, saved as an MLflow artifact, into the workspace.
:param artifact_uri: The URI of the MLflow artifact that contains the trial notebook.
:param path: The path in the Databricks workspace where the notebook should be imported. This must be an absolute path. The directory will be created if it does not exist.
:param overwrite: Whether to overwrite the notebook if it already exists. It is `False` by default.
:return: ImportNotebookResult contains two fields, `path` and `url`, referring to the imported notebook
"""
用法示例：
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)
注册和部署模型
可以注册和部署 AutoML 训练的模型，就像 MLflow 模型注册表中的任何已注册模型一样，详见记录、加载、注册和部署 MLflow 模型。
没有名为“pandas.core.indexes.numeric”的模块
通过模型服务为使用 AutoML 生成的模型提供服务时，可能会收到错误：No module named 'pandas.core.indexes.numeric。
这是由于 AutoML 和模型服务终结点环境之间的 pandas 版本是不兼容的版本。 可以通过运行 add-pandas-dependency.py 脚本解决此错误。 该脚本会为你记录的模型编辑 requirements.txt 和 conda.yaml，以包含适当的 pandas 依赖项版本：pandas==1.5.3。
- 修改脚本以包含记录模型时所在的 MLflow 运行的
run_id。 - 将模型重新注册到 MLflow 模型注册表。
- 尝试为新版 MLflow 模型提供服务。
Notebook 示例
请查看这些笔记本以开始使用 AutoML。
以下笔记本演示如何使用 AutoML 进行分类。
AutoML 分类示例笔记本
以下笔记本演示如何使用 AutoML 进行回归。
AutoML 回归示例笔记本
以下笔记本演示如何使用 AutoML 进行预测。
AutoML 预测示例笔记本
以下笔记本演示如何使用 AutoML 特征表和“特征存储”特征表训练 ML 模型。