Azure Databricks AutoML Python API 參考

本文說明 Azure Databricks AutoML Python API，其提供開始分類、回歸和預測 AutoML 執行的方法。 每個方法呼叫都會訓練一組模型，併為每個模型產生試用筆記本。

如需 AutoML 的詳細資訊，包括低程式代碼 UI 選項，請參閱 什麼是 AutoML？。

分類

方法 databricks.automl.classify 會設定 AutoML 執行來定型分類模型。

注意

參數 max_trials 在 Databricks Runtime 10.4 ML 中已被取代，而且 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
) -> AutoMLSummary

分類參數

參數名稱	類型	描述
dataset	str、 、 pandas.DataFrame、 pyspark.DataFramepyspark.sql.DataFrame	輸入數據表名稱或包含定型功能和目標的 DataFrame。 數據表名稱的格式可以是 「<database_name>。<>table_name“ 或 「<schema_name>。<非 Unity 目錄資料表table_name>」 。
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 參數的數據。 預設值： []
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”、“precision”、“precision”、“roc_auc”
split_col	str	選擇性。 分割數據行的數據行名稱。 僅適用於 API 工作流程的 Databricks Runtime 15.3 ML 和更新版本。 如果提供，AutoML 會嘗試依使用者指定的值分割定型/驗證/測試集，而且此數據行會自動從定型功能中排除。 接受的數據行類型為字串。 此數據行中每個專案的值都必須是下列其中一項：“train”、“validate” 或 “test”。
time_col	str	適用於 Databricks Runtime 10.1 ML 和更新版本。 選擇性。 時間數據行的數據行名稱。 如果提供，AutoML 會嘗試以時間順序將數據集分割成定型、驗證和測試集，使用最早的點做為定型數據，並將最新的點當做測試集。 接受的數據行類型是時間戳和整數。 使用 Databricks Runtime 10.2 ML 和更新版本時，也支援字串數據行。 如果數據行類型是字串，AutoML 會嘗試使用語意偵測將它轉換成時間戳。 如果轉換失敗，AutoML 執行會失敗。
timeout_minutes	int	選擇性。 等候 AutoML 試用版完成的時間上限。 較長的逾時時間可讓 AutoML 執行更多試用版，並識別更精確的模型。 預設值：120 分鐘 最小值：5 分鐘 如果逾時太短而無法讓至少一個試用完成，就會報告錯誤。
sample_weight_col	str	僅適用於 Databricks Runtime 15.3 ML 和更新版本，以供回歸 API 工作流程使用。 選擇性。 數據集中的數據行名稱，其中包含每個數據列的範例權數。 這些權數會調整模型定型期間每個數據列的重要性。 權數必須是非負數小數或整數值，範圍從0到10,000。 具有較高樣本權數的數據列會被視為更重要，並且對學習演算法產生更大的影響。 如果未指定此數據行，則會假設所有數據列的權數相等。

退步

方法 databricks.automl.regress 會設定 AutoML 執行來定型回歸模型。 這個方法會傳 回 AutoMLSummary。

注意

參數 max_trials 在 Databricks Runtime 10.4 ML 中已被取代，而且 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.DataFramepyspark.sql.DataFrame	輸入數據表名稱或包含定型功能和目標的 DataFrame。 數據表名稱的格式可以是 「<database_name>。<>table_name“ 或 「<schema_name>。<非 Unity 目錄資料表table_name>」 。
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 參數的數據。 預設值： []
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”、“precision”、“precision”、“roc_auc”
split_col	str	選擇性。 分割數據行的數據行名稱。 僅適用於 API 工作流程的 Databricks Runtime 15.3 ML 和更新版本。 如果提供，AutoML 會嘗試依使用者指定的值分割定型/驗證/測試集，而且此數據行會自動從定型功能中排除。 接受的數據行類型為字串。 此數據行中每個專案的值都必須是下列其中一項：“train”、“validate” 或 “test”。
time_col	str	適用於 Databricks Runtime 10.1 ML 和更新版本。 選擇性。 時間數據行的數據行名稱。 如果提供，AutoML 會嘗試以時間順序將數據集分割成定型、驗證和測試集，使用最早的點做為定型數據，並將最新的點當做測試集。 接受的數據行類型是時間戳和整數。 使用 Databricks Runtime 10.2 ML 和更新版本時，也支援字串數據行。 如果數據行類型是字串，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.DataFramepyspark.sql.DataFrame	輸入數據表名稱或包含定型功能和目標的 DataFrame。 數據表名稱的格式可以是 “ .” 或 “.” 適用於非 Unity 目錄數據表
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” / “month” “Q” / “quarter” / “quarters” “Y” / “year” / “years” 默認值：“D”
horizon	int	未來應該傳回預測的期間數。 單位是時間序列頻率。 預設值：1
data_dir	str 格式的 dbfs:/<folder-name>	選擇性。 用來儲存定型數據集的 DBFS 路徑。 驅動程式和背景工作角色節點都可以看到此路徑。 Databricks 建議將此字段保留空白，因此 AutoML 可以將定型數據集儲存為 MLflow 成品。 如果指定自定義路徑，數據集不會繼承 AutoML 實驗的訪問許可權。
exclude_frameworks	List[str]	選擇性。 AutoML 不應該在開發模型時考慮的演算法架構清單。 可能的值：空白清單，或一或多個「先知」、「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 和更新版本。 只有先知預測模型支援。 選擇性。 兩個字母的國家/地區代碼，指出預測模型應該使用的國家/地區假日。 若要忽略假日，請將此參數設定為空字串 （“” ）。 支援的國家/地區。 默認值：美國（美國 假日）。

匯入筆記本

方法 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 執行的 Summary 物件，描述每個試用版的計量、參數和其他詳細數據。 您也可以使用此物件來載入由特定試用版定型的模型。

屬性	類型​	描述
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

每個個別試用版的 Summary 物件。

屬性	類型​	描述
notebook_path	Optional[str]	工作區中針對此試用版產生的筆記本路徑。 針對分類和回歸，此值只會針對最佳試用版設定，而所有其他試驗的值都會設定為 None。 針對預測，此值適用於所有試用版。
notebook_url	Optional[str]	此試用版所產生筆記本的 URL。 針對分類和回歸，此值只會針對最佳試用版設定，而所有其他試驗的值都會設定為 None。 針對預測，此值適用於所有試用版。
artifact_uri	Optional[str]	所產生筆記本的 MLflow 成品 URI。
mlflow_run_id	str	與此試用回合相關聯的 MLflow 執行標識碼。
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

屬性	類型​	描述
path	str	Databricks 工作區中應該匯入筆記本的路徑。 這必須是絕對路徑。 如果目錄不存在，將會建立目錄。
url	str	包含試用筆記本之 MLflow 成品的 URI。