Referência da API do Databricks AutoML Python

Este artigo descreve o site Databricks AutoML Python API, que fornece métodos para iniciar a classificação, a regressão e a previsão de execução AutoML. Cada chamada de método ensina um conjunto de modelos e gera uma tentativa Notebook para cada modelo.

Para obter mais informações sobre AutoML, incluindo uma opção de UI de baixo código, consulte O que é AutoML?

Classificar

O método databricks.automl.classify configura uma execução do AutoML para ensinar um modelo de classificação.

Observação

O parâmetro max_trials foi preterido no Databricks Runtime 10,4 ML e não tem suporte no Databricks Runtime 11,0 MLe acima. Use timeout_minutes para controlar a duração de uma execução do 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

Classificar parâmetros

Nome do parâmetro	Tipo	Descrição
dataset	str, pandas.DataFrame, pyspark.DataFrame, pyspark.sql.DataFrame	Insira o nome da tabela ou DataFrame que contém o treinamento recurso e o destino. O nome da tabela pode estar no formato "<database_name>.<table_name>" ou "<schema_name>.<table_name>" para tabelas que não sejam do Unity Catalog.
target_col	str	Nome da coluna para o rótulo de destino.
data_dir	str de formato dbfs:/<folder-name>	Opcional. DBFS caminho usado para armazenar o treinamento dataset. Esse caminho é visível para os nós do driver e do worker. Databricks recomenda deixar esse campo vazio, para que o site AutoML possa salvar o treinamento dataset como um artefato MLflow. Se um caminho personalizado for especificado, o dataset não herdará as permissões de acesso do experimento AutoML.
exclude_cols	List[str]	Opcional. Lista de colunas a serem ignoradas durante os cálculos do AutoML. default: []
exclude_frameworks	List[str]	Opcional. Lista de estruturas de algoritmos que o AutoML não deve considerar ao desenvolver modelos. Valores possíveis: lista vazia, ou um ou mais de "sklearn", "lightgbm", "xgboost". default: [] (todas as estruturas são consideradas)
experiment_dir	str	Opcional. Caminho para o diretório no site workspace para salvar o Notebook e os experimentos gerados. default: /Users/<username>/databricks_automl/
experiment_name	str	Opcional. Nome do experimento MLflow que o AutoML cria. default: O nome é gerado automaticamente.
feature_store_lookups	List[Dict]	Opcional. Lista de dicionários que representam recurso do repositório de recursos para aumento de dados. As chaves válidas em cada dicionário são: table_name (str): Obrigatório. Nome da tabela de recursos. lookup_key (lista ou str): Obrigatório. Nome(s) da(s) coluna(s) a ser(em) usado(s) como key ao unir a tabela de recurso com os dados passados no parâmetro dataset. A ordem dos nomes das colunas deve corresponder à ordem da chave primária da tabela de recursos. timestamp_lookup_key (str): Necessário se a tabela especificada for uma tabela de recurso de série temporal. O nome da coluna a ser usada ao realizar a pesquisa pontual na tabela de recursos com os dados passados no parâmetro dataset. default: []
imputers	Dict[str, Union[str, Dict[str, Any]]]	Opcional. Dicionário em que cada key é um nome de coluna e cada valor é uma cadeia de caracteres ou um dicionário que descreve a estratégia de imputação. Se for especificado como uma cadeia de caracteres, o valor deverá ser uma das opções "mean" (média), "median" (mediana) ou "most_frequent" (mais frequente). Para fazer a imputação com um valor conhecido, especifique o valor como um dicionário {"strategy": "constant", "fill_value": <desired value>}. O senhor também pode especificar opções de strings como dicionários, por exemplo, {"strategy": "mean"}. Se nenhuma estratégia de imputação for fornecida para uma coluna, o site AutoML seleciona uma estratégia default com base no tipo e no conteúdo da coluna. Se o senhor especificar um método de imputação que não seja odefault, o AutoML não realizará a detecção do tipo semântico. default: {}
max_trials	int	Opcional. Número máximo de tentativas para execução. Esse parâmetro está disponível no Databricks Runtime 10.5 ML e abaixo, mas está obsoleto a partir do Databricks Runtime 10.3 ML. Em Databricks Runtime 11.0 ML e acima, não há suporte para esse parâmetro. default: 20 Se timeout_minutes=None, AutoML executa o número máximo de tentativas.
pos_label	Union[int, bool, str]	(Somente classificação) A classe positiva. Isso é útil para calcular métricas como precisão e recall. Deve ser especificado apenas para problemas de classificação binária.
primary_metric	str	métricas usadas para avaliar e classificar o desempenho do modelo. Métricas suportadas para regressão: "r2" (default), "mae", "rmse", "mse" Métricas suportadas para classificação: "f1" (default), "logs", "precision", "accuracy", "ROC"
split_col	str	Opcional. Nome da coluna para uma coluna dividida. Disponível somente em Databricks Runtime 15.3 ML e acima para API fluxo de trabalho. Se fornecido, o site AutoML tentará dividir os conjuntos ensinar/validar/testar por valores especificados pelo usuário, e essa coluna será automaticamente excluída do treinamento recurso. O tipo de coluna aceito é a cadeia de caracteres. O valor de cada entrada nessa coluna deve ser um dos seguintes: "ensinar", "validar" ou "testar".
time_col	str	Disponível no Databricks Runtime 10.1 MLe acima. Opcional. Nome da coluna para uma coluna de tempo. Se fornecido, o site AutoML tenta dividir o dataset em conjuntos de treinamento, validação e teste cronologicamente, usando os pontos mais antigos como dados de treinamento e os pontos mais recentes como conjunto de teste. Os tipos de coluna aceitos são timestamp e integer. Com o Databricks Runtime 10.2 MLe acima, colunas strings também são suportadas. Se o tipo de coluna for strings, o AutoML tentará convertê-lo em carimbo de data/hora usando a detecção semântica. Se a conversão falhar, a execução do AutoML falhará.
timeout_minutes	int	Opcional. Tempo máximo de espera para que os testes do AutoML sejam concluídos. Os tempos limite mais longos permitem que o site AutoML execute mais testes e identifique um modelo com melhor precisão. default: 120 minutos Valor mínimo: 5 minutos Um erro será relatado se o tempo limite for muito curto para permitir a conclusão de pelo menos uma tentativa.
sample_weight_col	str	Disponível somente em Databricks Runtime 15.3 ML e acima para regressão API fluxo de trabalho. Opcional. Nome da coluna no site dataset que contém os pesos da amostra para cada linha. Esses pesos ajustam a importância de cada linha durante o treinamento do modelo. Os pesos devem ser valores decimais ou inteiros não negativos, variando de 0 a 10.000. As linhas com pesos de amostra mais altos são consideradas mais importantes e têm maior influência sobre o algoritmo de aprendizado. Se essa coluna não for especificada, presume-se que todas as linhas tenham o mesmo peso.

Regressão

O método databricks.automl.regress configura uma execução do AutoML para ensinar um modelo de regressão. Esse método retorna um AutoMLSummary.

Observação

O parâmetro max_trials foi preterido no Databricks Runtime 10,4 ML e não tem suporte no Databricks Runtime 11,0 MLe acima. Use timeout_minutes para controlar a duração de uma execução do 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

Parâmetros de regressão

Nome do parâmetro	Tipo	Descrição
dataset	str, pandas.DataFrame, pyspark.DataFrame, pyspark.sql.DataFrame	Insira o nome da tabela ou DataFrame que contém o treinamento recurso e o destino. O nome da tabela pode estar no formato "<database_name>.<table_name>" ou "<schema_name>.<table_name>" para tabelas que não sejam do Unity Catalog.
target_col	str	Nome da coluna para o rótulo de destino.
data_dir	str de formato dbfs:/<folder-name>	Opcional. DBFS caminho usado para armazenar o treinamento dataset. Esse caminho é visível para os nós do driver e do worker. Databricks recomenda deixar esse campo vazio, para que o site AutoML possa salvar o treinamento dataset como um artefato MLflow. Se um caminho personalizado for especificado, o dataset não herdará as permissões de acesso do experimento AutoML.
exclude_cols	List[str]	Opcional. Lista de colunas a serem ignoradas durante os cálculos do AutoML. default: []
exclude_frameworks	List[str]	Opcional. Lista de estruturas de algoritmos que o AutoML não deve considerar ao desenvolver modelos. Valores possíveis: lista vazia, ou um ou mais de "sklearn", "lightgbm", "xgboost". default: [] (todas as estruturas são consideradas)
experiment_dir	str	Opcional. Caminho para o diretório no site workspace para salvar o Notebook e os experimentos gerados. default: /Users/<username>/databricks_automl/
experiment_name	str	Opcional. Nome do experimento MLflow que o AutoML cria. default: O nome é gerado automaticamente.
feature_store_lookups	List[Dict]	Opcional. Lista de dicionários que representam recurso do repositório de recursos para aumento de dados. As chaves válidas em cada dicionário são: table_name (str): Obrigatório. Nome da tabela de recursos. lookup_key (lista ou str): Obrigatório. Nome(s) da(s) coluna(s) a ser(em) usado(s) como key ao unir a tabela de recurso com os dados passados no parâmetro dataset. A ordem dos nomes das colunas deve corresponder à ordem da chave primária da tabela de recursos. timestamp_lookup_key (str): Necessário se a tabela especificada for uma tabela de recurso de série temporal. O nome da coluna a ser usada ao realizar a pesquisa pontual na tabela de recursos com os dados passados no parâmetro dataset. default: []
imputers	Dict[str, Union[str, Dict[str, Any]]]	Opcional. Dicionário em que cada key é um nome de coluna e cada valor é uma cadeia de caracteres ou um dicionário que descreve a estratégia de imputação. Se for especificado como uma cadeia de caracteres, o valor deverá ser uma das opções "mean" (média), "median" (mediana) ou "most_frequent" (mais frequente). Para fazer a imputação com um valor conhecido, especifique o valor como um dicionário {"strategy": "constant", "fill_value": <desired value>}. O senhor também pode especificar opções de strings como dicionários, por exemplo, {"strategy": "mean"}. Se nenhuma estratégia de imputação for fornecida para uma coluna, o site AutoML seleciona uma estratégia default com base no tipo e no conteúdo da coluna. Se o senhor especificar um método de imputação que não seja odefault, o AutoML não realizará a detecção do tipo semântico. default: {}
max_trials	int	Opcional. Número máximo de tentativas para execução. Esse parâmetro está disponível no Databricks Runtime 10.5 ML e abaixo, mas está obsoleto a partir do Databricks Runtime 10.3 ML. Em Databricks Runtime 11.0 ML e acima, não há suporte para esse parâmetro. default: 20 Se timeout_minutes=None, AutoML executa o número máximo de tentativas.
pos_label	Union[int, bool, str]	(Somente classificação) A classe positiva. Isso é útil para calcular métricas como precisão e recall. Deve ser especificado apenas para problemas de classificação binária.
primary_metric	str	métricas usadas para avaliar e classificar o desempenho do modelo. Métricas suportadas para regressão: "r2" (default), "mae", "rmse", "mse" Métricas suportadas para classificação: "f1" (default), "logs", "precision", "accuracy", "ROC"
split_col	str	Opcional. Nome da coluna para uma coluna dividida. Disponível somente em Databricks Runtime 15.3 ML e acima para API fluxo de trabalho. Se fornecido, o site AutoML tentará dividir os conjuntos ensinar/validar/testar por valores especificados pelo usuário, e essa coluna será automaticamente excluída do treinamento recurso. O tipo de coluna aceito é a cadeia de caracteres. O valor de cada entrada nessa coluna deve ser um dos seguintes: "ensinar", "validar" ou "testar".
time_col	str	Disponível no Databricks Runtime 10.1 MLe acima. Opcional. Nome da coluna para uma coluna de tempo. Se fornecido, o site AutoML tenta dividir o dataset em conjuntos de treinamento, validação e teste cronologicamente, usando os pontos mais antigos como dados de treinamento e os pontos mais recentes como conjunto de teste. Os tipos de coluna aceitos são timestamp e integer. Com o Databricks Runtime 10.2 MLe acima, colunas strings também são suportadas. Se o tipo de coluna for strings, o AutoML tentará convertê-lo em carimbo de data/hora usando a detecção semântica. Se a conversão falhar, a execução do AutoML falhará.
timeout_minutes	int	Opcional. Tempo máximo de espera para que os testes do AutoML sejam concluídos. Os tempos limite mais longos permitem que o site AutoML execute mais testes e identifique um modelo com melhor precisão. default: 120 minutos Valor mínimo: 5 minutos Um erro será relatado se o tempo limite for muito curto para permitir a conclusão de pelo menos uma tentativa.
sample_weight_col	str	Disponível somente em Databricks Runtime 15.3 ML e acima para regressão API fluxo de trabalho. Opcional. Nome da coluna no site dataset que contém os pesos da amostra para cada linha. Esses pesos ajustam a importância de cada linha durante o treinamento do modelo. Os pesos devem ser valores decimais ou inteiros não negativos, variando de 0 a 10.000. As linhas com pesos de amostra mais altos são consideradas mais importantes e têm maior influência sobre o algoritmo de aprendizado. Se essa coluna não for especificada, presume-se que todas as linhas tenham o mesmo peso.

Previsão

O método databricks.automl.forecast configura uma execução AutoML para o treinamento de um modelo de previsão. Esse método retorna um AutoMLSummary. Para usar o Auto-ARIMA, a série temporal deve ter uma frequência regular (ou seja, o intervalo entre dois pontos quaisquer deve ser o mesmo em toda a série temporal). A frequência deve corresponder à unidade de frequência especificada na chamada de API. AutoML lida com os passos de tempo ausentes preenchendo esses valores com o valor anterior.

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

Parâmetros de previsão

Nome do parâmetro	Tipo	Descrição
dataset	str, pandas.DataFrame, pyspark.DataFrame, pyspark.sql.DataFrame	Insira o nome da tabela ou DataFrame que contém o treinamento recurso e o destino. O nome da tabela pode estar no formato "..." ou "." para tabelas que não sejam do Unity Catalog
target_col	str	Nome da coluna para o rótulo de destino.
time_col	str	Nome da coluna de tempo para previsão.
frequency	str	Frequência da série temporal para previsão. Esse é o período em que se espera que os eventos ocorram. A configuração do site default é "D" ou dados diários. Não se esqueça de alterar a configuração se seus dados tiverem uma frequência diferente. Valores possíveis: "W" (semanas) "D" / "days" / "day" "hours" / "hour" / "hr" / "h" "m" / "minute" / "min" / "minutes" / "T" "S" / "seconds" / "sec" / "second" O seguinte está disponível apenas com Databricks Runtime 12.0 MLe acima: "M" / "month" / "months" "Q" / "quarter" / "quarters" "Y" / "year" / "years" default: "D"
horizon	int	Número de períodos no futuro para os quais as previsões devem ser retornadas. As unidades são a frequência da série temporal. default: 1
data_dir	str de formato dbfs:/<folder-name>	Opcional. DBFS caminho usado para armazenar o treinamento dataset. Esse caminho é visível para os nós do driver e do worker. Databricks recomenda deixar esse campo vazio, para que o site AutoML possa salvar o treinamento dataset como um artefato MLflow. Se um caminho personalizado for especificado, o dataset não herdará as permissões de acesso do experimento AutoML.
exclude_frameworks	List[str]	Opcional. Lista de estruturas de algoritmos que o AutoML não deve considerar ao desenvolver modelos. Valores possíveis: lista vazia, ou um ou mais de "prophet", "arima". default: [] (todas as estruturas são consideradas)
experiment_dir	str	Opcional. Caminho para o diretório no site workspace para salvar o Notebook e os experimentos gerados. default: /Users/<username>/databricks_automl/
experiment_name	str	Opcional. Nome do experimento MLflow que o AutoML cria. default: O nome é gerado automaticamente.
feature_store_lookups	List[Dict]	Opcional. Lista de dicionários que representam recurso do repositório de recursos para aumento de dados. As chaves válidas em cada dicionário são: table_name (str): Obrigatório. Nome da tabela de recursos. lookup_key (lista ou str): Obrigatório. Nome(s) da(s) coluna(s) a ser(em) usado(s) como key ao unir a tabela de recurso com os dados passados no parâmetro dataset. A ordem dos nomes das colunas deve corresponder à ordem da chave primária da tabela de recursos. timestamp_lookup_key (str): Necessário se a tabela especificada for uma tabela de recurso de série temporal. O nome da coluna a ser usada ao realizar a pesquisa pontual na tabela de recursos com os dados passados no parâmetro dataset. default: []
identity_col	Union[str, list]	Opcional. Coluna(s) que identifica(m) a série temporal para previsão de várias séries. O AutoML agrupa por essa(s) coluna(s) e a coluna de tempo para previsão.
output_database	str	Opcional. Se fornecido, o AutoML salvará as previsões do melhor modelo em uma nova tabela no banco de dados especificado. default: As previsões não são salvas.
primary_metric	str	métricas usadas para avaliar e classificar o desempenho do modelo. Métricas suportadas: "smape" (default), "mse", "rmse", "mae" ou "mdape".
timeout_minutes	int	Opcional. Tempo máximo de espera para que os testes do AutoML sejam concluídos. Os tempos limite mais longos permitem que o site AutoML execute mais testes e identifique um modelo com melhor precisão. default: 120 minutos Valor mínimo: 5 minutos Um erro será relatado se o tempo limite for muito curto para permitir a conclusão de pelo menos uma tentativa.
country_code	str	Disponível no Databricks Runtime 12,0 MLe acima. Suportado apenas pelo modelo de previsão do Profeta. Opcional. Código de país de duas letras que indica os feriados do país que o modelo de previsão deve usar. Para ignorar os feriados, defina esse parâmetro como uma cadeia de caracteres vazia (""). Países suportados. default: US (feriados nos Estados Unidos).

Importação Notebook

O método databricks.automl.import_notebook importa um Notebook que foi salvo como um artefato MLflow. Esse método retorna um ImportNotebookResult.

databricks.automl.import_notebook(
  artifact_uri: str,
  path: str,
  overwrite: bool = False
) -> ImportNotebookResult:

Parâmetros	Tipo	Descrição
artifact_uri	str	O URI do artefato MLflow que contém a tentativa Notebook.
path	str	O caminho em Databricks workspace onde o Notebook deve ser importado. Esse deve ser um caminho absoluto. O diretório será criado se não existir.
overwrite	bool	Se o senhor deve substituir o site Notebook caso ele já exista. É False por default.

Importar Notebook exemplo

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

Objeto de resumo de uma execução do AutoML que descreve as métricas, os parâmetros e outros detalhes de cada um dos testes. O senhor também usa esse objeto para carregar o modelo treinado por uma tentativa específica.

Propriedade	Tipo	Descrição
experiment	mlflow.entities.Experiment	O experimento MLflow usado para log os testes.
trials	List[TrialInfo]	Uma lista de objetos TrialInfo contendo informações sobre todas as tentativas que foram executadas.
best_trial	TrialInfo	Um objeto TrialInfo contendo informações sobre o estudo que resultou na melhor pontuação ponderada para as métricas primárias.
metric_distribution	str	A distribuição dos escores ponderados para as métricas primárias em todos os estudos.
output_table_name	str	Usado somente com previsão e somente se o output_database for fornecido. Nome da tabela no output_database que contém as previsões do modelo.

TrialInfo

Objeto de resumo para cada teste individual.

Propriedade	Tipo	Descrição
notebook_path	Optional[str]	O caminho para o site Notebook gerado para esse teste no site workspace. Para classificação e regressão, esse valor é definido apenas para a melhor tentativa, enquanto todas as outras tentativas têm o valor definido como None. Para previsão, esse valor está presente em todas as tentativas.
notebook_url	Optional[str]	O URL do site Notebook gerado para esse teste. Para classificação e regressão, esse valor é definido apenas para a melhor tentativa, enquanto todas as outras tentativas têm o valor definido como None. Para previsão, esse valor está presente em todas as tentativas.
artifact_uri	Optional[str]	O URI do artefato MLflow para o Notebook gerado.
mlflow_run_id	str	A ID de execução do MLflow associada a essa execução de teste.
metrics	Dict[str, float]	As métricas acessam MLflow para esse teste.
params	Dict[str, str]	O registro dos parâmetros em MLflow que foram usados para este teste.
model_path	str	O URL do artefato do MLflow do modelo treinado nessa tentativa.
model_description	str	Breve descrição do modelo e dos hiperparâmetros usados para o treinamento desse modelo.
duration	str	treinamento duração em minutos.
preprocessors	str	Descrição da execução dos pré-processadores antes do treinamento do modelo.
evaluation_metric_score	float	Pontuação de métricas primárias, avaliadas para a validação dataset.

TrialInfo tem um método para carregar o modelo gerado para o teste.

Método	Descrição
load_model()	Carregue o modelo gerado nesse teste, registrado como um artefato do site MLflow.

ImportNotebookResult

Propriedade	Tipo	Descrição
path	str	O caminho em Databricks workspace onde o Notebook deve ser importado. Esse deve ser um caminho absoluto. O diretório será criado se não existir.
url	str	O URI do artefato MLflow que contém a tentativa Notebook.