本文說明 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 Catalog 的資料表，資料表名稱的格式可以是 "<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 |
格式 str 的 dbfs:/<folder-name> |
選擇性。 用來儲存訓練資料集的 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] |
選擇性。 代表特徵存放區中用於資料增強的特徵的字典清單。 每個字典中的有效索引鍵為：
預設：[] |
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。
注意
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,
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 Catalog 的資料表，資料表名稱的格式可以是 "<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 |
格式 str 的 dbfs:/<folder-name> |
選擇性。 用來儲存訓練資料集的 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] |
選擇性。 代表特徵存放區中用於資料增強的特徵的字典清單。 每個字典中的有效索引鍵為：
預設：[] |
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 Catalog 的資料表 |
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"（週） "D" / "天數" / "天" "小時" / "小時" / "小時" / "小時" "m" / "分鐘" / "分" / "分鐘" / "T" "S" / "秒" / "秒" / "秒" 只有在 Databricks Runtime 12.0 ML 及以上版本中，才可使用以下功能： "M" / "月" / "月" "Q" / "季" / "季" “年” / “年” / “年” 預設："D" |
horizon |
int |
應傳回未來預測的期數。 單位是時間序列頻率。 預設值：1 |
data_dir |
格式 str 的 dbfs:/<folder-name> |
選擇性。 用來儲存訓練資料集的 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] |
選擇性。 字典清單，代表特徵存放區中用於變項資料增強的特徵。 每個字典中的有效索引鍵為：
預設：[] |
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 分鐘 如果超時太短而無法讓至少一次測試完成，就會報告錯誤。 |
匯入筆記本
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] |
工作區中針對此測試生成的 Notebook 的路徑。 對於分類和迴歸，此值只會針對最佳試用設定，而所有其他試用的值會設定為 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。 |