AutoML Python API 參考

發行項
12/18/2024

本文說明 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,
  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.DataFrame`、 `pyspark.DataFramepyspark.sql.DataFrame`	輸入資料表名稱或包含訓練特徵和目標的 DataFrame。對於 Unity 目錄資料包，資料表名稱的格式可以是 "<database_name>.<table_name>" 或 "<schema_name>.<table_name>"。
`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_frequent"。若要插補已知值，請將值指定為字典 `{"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 會嘗試按時間順序將資料集分割成訓練、驗證和測試集，使用最早的時間點做為訓練資料，並將最新的時間作為測試集。接受的資料行類型是時間戳記和整數。使用 Databricks Runtime 10.2 ML 和更新版本時，也支援字串資料行。如果資料行類型是字串，AutoML 會嘗試使用語意偵測將其轉換成時間戳記。如果轉換失敗，AutoML 執行即會失敗。
`split_col`	`str`	選擇性。分割資料行的資料行名稱。僅適用於 API 工作流程的 Databricks Runtime 15.3 ML 和更新版本。如果提供，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。

注意

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.DataFrame`、 `pyspark.DataFramepyspark.sql.DataFrame`	輸入資料表名稱或包含訓練特徵和目標的 DataFrame。對於 Unity 目錄資料包，資料表名稱的格式可以是 "<database_name>.<table_name>" 或 "<schema_name>.<table_name>"。
`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_frequent"。若要插補已知值，請將值指定為字典 `{"strategy": "constant", "fill_value": <desired value>}`。您也可以將字串選項指定為字典，例如 `{"strategy": "mean"}`。如果未提供資料行的插補策略，AutoML 會根據資料行類型和內容選取預設策略。如果您指定非預設插補方法，AutoML 不會執行語意類型偵測。預設：{}
`time_col`	`str`	在 Databricks Runtime 10.1 ML 和更新版本中可用。選擇性。時間資料行的資料行名稱。如果提供，AutoML 會嘗試按時間順序將資料集分割成訓練、驗證和測試集，使用最早的時間點做為訓練資料，並將最新的時間作為測試集。接受的資料行類型是時間戳記和整數。使用 Databricks Runtime 10.2 ML 和更新版本時，也支援字串資料行。如果資料行類型是字串，AutoML 會嘗試使用語意偵測將其轉換成時間戳記。如果轉換失敗，AutoML 執行即會失敗。
`split_col`	`str`	選擇性。分割資料行的資料行名稱。僅適用於 API 工作流程的 Databricks Runtime 15.3 ML 和更新版本。如果提供，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.DataFrame`、 `pyspark.DataFramepyspark.sql.DataFrame`	輸入資料表名稱或包含訓練特徵和目標的 DataFrame。資料表名稱的格式可以是 ".." 或 "." 適用於非 Unity 目錄資料表
`target_col`	`str`	目標標籤的資料行名稱。
`time_col`	`str`	用於預測的時間資料行名稱。
`primary_metric`	`str`	用來評估和排名模型效能的計量。支援的計量："smape" (預設)、"mse"、"rmse"、"mae" 或 "mdape"。
`country_code`	`str`	在 Databricks Runtime 12.0 ML 和更新版本中可用。僅受 Prophet 預測模型支援。選擇性。兩個字母的國碼 (地區碼)，可指出預測模型應使用的國家/地區假日。若要略過假日，請將此參數設定為空字串 ("")。支援的國家/地區。預設：美國 (美國假日)。
`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 分鐘如果逾時太短而無法讓至少一個試用完成，就會報告錯誤。

匯入 Notebook

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 執行識別碼。
`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。

共用方式為