Azure Databricks AutoML Python API リファレンス

  • [アーティクル]

この記事では、分類、回帰、および予測 AutoML の実行を開始するメソッドを提供する Azure Databricks AutoML Python API について説明します。 各メソッド呼び出しによって、一連のモデルがトレーニングされ、各モデルの試用版ノートブックが生成されます。

ローコード UI オプションを含む AutoML の詳細については、「AutoML とは」を参照してください。

分類

databricks.automl.classify メソッドは、分類モデルのトレーニングを行う AutoML の実行を構成します。

Note

max_trials パラメーターは Databricks Runtime 10.4 ML では非推奨であり、Databricks Runtime 11.0 ML 以上ではサポートされていません。 AutoML 実行の期間を制御するには、timeout_minutes を使用します。

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 トレーニングの特徴量とターゲットを含む入力テーブル名または 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 によって考慮されないアルゴリズム フレームワークの一覧。 使用可能な値: 空のリスト、または 1 つ以上の "sklearn"、"lightgbm"、"xgboost"。

既定値: [] (すべてのフレームワークが考慮されます)
experiment_dir str 省略可能。 生成されたノートブックと実験を保存するための、ワークスペース内のディレクトリへのパス。

既定値: /Users/<username>/databricks_automl/
experiment_name str 省略可能。 AutoML によって作成される MLflow 実験の名前。

既定値: 名前が自動的に生成されます。
feature_store_lookups List[Dict] 省略可能。 データ拡張用の Feature Store の特徴を表すディクショナリの一覧。 各ディクショナリの有効なキーは次のとおりです。

* table_name (str): 必須。 特徴テーブルの名前。
* lookup_key (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 省略可能。 分割された列の列名。 API ワークフローでは、Databricks Runtime 15.3 ML 以上でのみ使用できます。 指定した場合、AutoML はユーザー指定の値でトレーニング/検証/テスト セットを分割しようとします。この列はトレーニング機能から自動的に除外されます。

受け入れられる列の型は文字列です。 この列の各エントリの値は、"トレーニング"、"検証"、"テスト" のいずれかにする必要があります。
time_col str Databricks Runtime 10.1 ML 以降で使用できます。

省略可能。 時間列の列名。

指定した場合、AutoML では、最も古いポイントをトレーニング データとして、最も新しいポイントをテスト セットとして使用して、データセットのトレーニング、検証、およびテスト セットへの時系列での分割が試みられます。

許容される列の型は、タイムスタンプと整数です。 Databricks Runtime 10.2 ML 以降では、文字列の列もサポートされています。

列の型が文字列の場合、AutoML ではセマンティック検出を使用してタイムスタンプへの変換が試みられます。 変換に失敗すると、AutoML の実行は失敗します。
timeout_minutes int 省略可能。 AutoML 試用版が完了するまでの最大待機時間。 タイムアウトを長く設定すると、AutoML により、より多くの試用版が実行され、精度の高いモデルが識別されます。

既定値: 120 分

最小値: 5 分

タイムアウトが短かすぎて、1 つの試用版も完了できない場合は、エラーが報告されます。
sample_weight_col str 分類 API ワークフローの場合は、Databricks Runtime 15.4 ML 以降で使用できます。

省略可能。 各行のサンプルの重みを含むデータセット内の列名。 分類では、クラスごとのサンプルの重みがサポートされます。 これらの重みは、モデル トレーニング中に各クラスの重要度を調整します。 クラス内の各サンプルは同じサンプルの重みを持つ必要があり、重みは、負ではない 10 進数または整数の値 (0 から 10,000 の範囲) である必要があります。 サンプルの重みが大きいクラスはより重要と見なされ、学習アルゴリズムに対してより大きな影響を与えます。 この列が指定されていない場合、すべてのクラスが同じ重みを持つものと見なされます。

回帰

databricks.automl.regress メソッドは、回帰モデルのトレーニングを行う AutoML の実行を構成します。 このメソッドでは、AutoMLSummary が返されます。

Note

max_trials パラメーターは Databricks Runtime 10.4 ML では非推奨であり、Databricks Runtime 11.0 ML 以上ではサポートされていません。 AutoML 実行の期間を制御するには、timeout_minutes を使用します。

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 トレーニングの特徴量とターゲットを含む入力テーブル名または 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 によって考慮されないアルゴリズム フレームワークの一覧。 使用可能な値: 空のリスト、または 1 つ以上の "sklearn"、"lightgbm"、"xgboost"。

既定値: [] (すべてのフレームワークが考慮されます)
experiment_dir str 省略可能。 生成されたノートブックと実験を保存するための、ワークスペース内のディレクトリへのパス。

既定値: /Users/<username>/databricks_automl/
experiment_name str 省略可能。 AutoML によって作成される MLflow 実験の名前。

既定値: 名前が自動的に生成されます。
feature_store_lookups List[Dict] 省略可能。 データ拡張用の Feature Store の特徴を表すディクショナリの一覧。 各ディクショナリの有効なキーは次のとおりです。

* table_name (str): 必須。 特徴テーブルの名前。
* lookup_key (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 省略可能。 分割された列の列名。 API ワークフローでは、Databricks Runtime 15.3 ML 以上でのみ使用できます。 指定した場合、AutoML はユーザー指定の値でトレーニング/検証/テスト セットを分割しようとします。この列はトレーニング機能から自動的に除外されます。

受け入れられる列の型は文字列です。 この列の各エントリの値は、"トレーニング"、"検証"、"テスト" のいずれかにする必要があります。
time_col str Databricks Runtime 10.1 ML 以降で使用できます。

省略可能。 時間列の列名。

指定した場合、AutoML では、最も古いポイントをトレーニング データとして、最も新しいポイントをテスト セットとして使用して、データセットのトレーニング、検証、およびテスト セットへの時系列での分割が試みられます。

許容される列の型は、タイムスタンプと整数です。 Databricks Runtime 10.2 ML 以降では、文字列の列もサポートされています。

列の型が文字列の場合、AutoML ではセマンティック検出を使用してタイムスタンプへの変換が試みられます。 変換に失敗すると、AutoML の実行は失敗します。
timeout_minutes int 省略可能。 AutoML 試用版が完了するまでの最大待機時間。 タイムアウトを長く設定すると、AutoML により、より多くの試用版が実行され、精度の高いモデルが識別されます。

既定値: 120 分

最小値: 5 分

タイムアウトが短かすぎて、1 つの試用版も完了できない場合は、エラーが報告されます。
sample_weight_col str 回帰 API ワークフローの場合は、Databricks Runtime 15.3 ML 以降で使用できます。

省略可能。 各行のサンプルの重みを含むデータセット内の列名。 これらの重みは、モデル トレーニング中の各行の重要度を調整します。 重みは、0 から 10,000 の範囲で、負以外の 10 進数または整数の値である必要があります。 サンプルの重みが大きい行はより重要と見なされ、学習アルゴリズムに対してより大きな影響を与えます。 この列が指定されていない場合、すべての行の重みが等しいと見なされます。

予測

databricks.automl.forecast メソッドでは、予測モデルをトレーニングするための AutoML 実行を構成します。 このメソッドでは、AutoMLSummary が返されます。 Auto-ARIMA を使用するには、時系列の頻度が一定である必要があります (つまり、任意の 2 つのポイント間の間隔は、時系列全体で同じである必要があります)。 頻度は、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 トレーニングの特徴量とターゲットを含む入力テーブル名または 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 によって考慮されないアルゴリズム フレームワークの一覧。 指定できる値: 空のリスト、または 1 つ以上の "prophet"、"arima"。

既定値: [] (すべてのフレームワークが考慮されます)
experiment_dir str 省略可能。 生成されたノートブックと実験を保存するための、ワークスペース内のディレクトリへのパス。

既定値: /Users/<username>/databricks_automl/
experiment_name str 省略可能。 AutoML によって作成される MLflow 実験の名前。

既定値: 名前が自動的に生成されます。
feature_store_lookups List[Dict] 省略可能。 データ拡張用の Feature Store の特徴を表すディクショナリの一覧。 各ディクショナリの有効なキーは次のとおりです。

* table_name (str): 必須。 特徴テーブルの名前。
* lookup_key (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 分

タイムアウトが短かすぎて、1 つの試用版も完了できない場合は、エラーが報告されます。
country_code str Databricks Runtime 12.0 ML 以降で使用できます。 Prophet 予測モデルでのみサポートされます。

省略可能。 予測モデルで使用する国の休日を示す 2 文字の国番号。 休日を無視するには、このパラメーターを空の文字列 ("") に設定します。

サポート対象の国。

既定値: 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 には、試用版用に生成されたモデルを読み込むメソッドが含まれます。

Method 説明
load_model() この試用版で生成され、MLflow 成果物としてログに記録された、モデルを読み込みます。

ImportNotebookResult

プロパティ タイプ 説明
path str ノートブックをインポートする Databricks ワークスペース内のパス。 これは絶対パスにする必要があります。 ディレクトリが存在しない場合は作成されます。
url str 試用版ノートブックを含む MLflow 成果物の URI。