Computar recurso sob demanda usando Python funções definidas pelo usuário

Este artigo descreve como criar e usar o recurso on-demand em Databricks.

Para usar o recurso on-demand, seu workspace deve estar habilitado para Unity Catalog e o senhor deve usar Databricks Runtime 13.3 LTS ML ou acima.

O que é recurso on-demand?

"On-demand" refere-se a recursos cujos valores não são conhecidos antecipadamente, mas são calculados no momento da inferência. No site Databricks, o usuário utiliza as funções definidas pelo usuário (UDFs) do sitePython para especificar como calcular o recurso on-demand. Essas funções são controladas pelo Unity Catalog e podem ser descobertas por meio do Catalog Explorer.

Requisitos

• Para usar uma função definida pelo usuário (UDF) para criar um conjunto de treinamento ou para criar um Feature Serving endpointo senhor deve ter o privilégio USE CATALOG no catálogo system em Unity Catalog.

fluxo de trabalho

Para compute recurso on-demand, o senhor especifica uma função definida pelo usuário Python (UDF) que descreve como calcular os valores do recurso.

• Durante o treinamento, o senhor fornece essa função e seus vínculos de entrada no parâmetro feature_lookups da API create_training_set.
• O senhor deve log o modelo treinado usando o método Recurso Store log_model. Isso garante que o modelo avalie automaticamente o recurso on-demand quando for usado para inferência.
• Para a pontuação de lotes, o score_batch API calcula e retorna automaticamente todos os valores de recurso, inclusive o recurso on-demand.
• Quando o senhor atende a um modelo com Mosaic AI Model Servingo modelo usa automaticamente o recurso Python UDF para compute on-demand para cada solicitação de pontuação.

Criar uma UDF Python

O senhor pode criar um Python UDF em um Notebook ou em Databricks SQL.

Por exemplo, a execução do código a seguir em uma célula do Notebook cria o site Python UDF example_feature no catálogo main e no esquema default.

%sql
CREATE FUNCTION main.default.example_feature(x INT, y INT)
RETURNS INT
LANGUAGE PYTHON
COMMENT 'add two numbers'
AS $$
def add_numbers(n1: int, n2: int) -> int:
  return n1 + n2

return add_numbers(x, y)
$$

Depois de executar o código, o senhor pode navegar pelo namespace de três níveis no Catalog Explorer para view a definição da função:

Para obter mais detalhes sobre a criação de UDFs em Python, consulte o registro em Python UDF a Unity Catalog e o manual da linguagem SQL.

Como lidar com valores de recurso ausentes

Quando um Python UDF depende do resultado de um FeatureLookup, o valor retornado se a pesquisa solicitada key não for encontrada depende do ambiente. Ao usar score_batch, o valor retornado é None. Ao usar o serviço on-line, o valor retornado é float("nan").

O código a seguir é um exemplo de como lidar com os dois casos.

%sql
CREATE OR REPLACE FUNCTION square(x INT)
RETURNS INT
LANGUAGE PYTHON AS
$$
import numpy as np
if x is None or np.isnan(x):
  return 0
return x * x
$$

Treinar um modelo usando recurso on-demand

Para treinar o modelo, o senhor usa um FeatureFunction, que é passado para a API create_training_set no parâmetro feature_lookups.

O código de exemplo a seguir usa o Python UDF main.default.example_feature que foi definido na seção anterior.

Python

# Install databricks-feature-engineering first with:
# %pip install databricks-feature-engineering
# dbutils.library.restartPython()

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering import FeatureFunction, FeatureLookup
from sklearn import linear_model

fe = FeatureEngineeringClient()

features = [
  # The feature 'on_demand_feature' is computed as the sum of the the input value 'new_source_input'
  # and the pre-materialized feature 'materialized_feature_value'.
  # - 'new_source_input' must be included in base_df and also provided at inference time.
  #   - For batch inference, it must be included in the DataFrame passed to 'FeatureEngineeringClient.score_batch'.
  #   - For real-time inference, it must be included in the request.
  # - 'materialized_feature_value' is looked up from a feature table.

  FeatureFunction(
      udf_name="main.default.example_feature",    # UDF must be in Unity Catalog so uses a three-level namespace
      input_bindings={
        "x": "new_source_input",
        "y": "materialized_feature_value"
      },
      output_name="on_demand_feature",
  ),
  # retrieve the prematerialized feature
  FeatureLookup(
    table_name = 'main.default.table',
    feature_names = ['materialized_feature_value'],
    lookup_key = 'id'
  )
]

# base_df includes the columns 'id', 'new_source_input', and 'label'
training_set = fe.create_training_set(
  df=base_df,
  feature_lookups=features,
  label='label',
  exclude_columns=['id', 'new_source_input', 'materialized_feature_value']     # drop the columns not used for training
)

# The training set contains the columns 'on_demand_feature' and 'label'.
training_df = training_set.load_df().toPandas()

# training_df columns ['materialized_feature_value', 'label']
X_train = training_df.drop(['label'], axis=1)
y_train = training_df.label

model = linear_model.LinearRegression().fit(X_train, y_train)

registre o modelo e registre-o no Unity Catalog

Os modelos de pacote com metadados de recurso podem ser registrados em Unity Catalog. As tabelas de recurso usadas para criar o modelo devem ser armazenadas em Unity Catalog.

Para garantir que o modelo avalie automaticamente o recurso on-demand quando for usado para inferência, o senhor deve definir o URI do registro e, em seguida, log o modelo, como segue:

Python

import mlflow
mlflow.set_registry_uri("databricks-uc")

fe.log_model(
    model=model,
    artifact_path="main.default.model",
    flavor=mlflow.sklearn,
    training_set=training_set,
    registered_model_name="main.default.recommender_model"
)

Se o Python UDF que define o recurso on-demand importar qualquer Python pacote, o senhor deverá especificar esse pacote usando o argumento extra_pip_requirements. Por exemplo:

Python

import mlflow
mlflow.set_registry_uri("databricks-uc")

fe.log_model(
    model=model,
    artifact_path="model",
    flavor=mlflow.sklearn,
    training_set=training_set,
    registered_model_name="main.default.recommender_model",
    extra_pip_requirements=["scikit-learn==1.20.3"]
)

Limitação

O recurso On-demand pode gerar todos os tipos de dados suportados pelo recurso Store, exceto MapType e ArrayType.

Notebook exemplos: Recurso sob demanda

O Notebook a seguir mostra um exemplo de como treinar e pontuar um modelo que usa um recurso on-demand.

Demonstração básica do recurso on-demand Notebook

Open notebook in new tab

O Notebook a seguir mostra um exemplo de um modelo de recomendação de restaurante. A localização do restaurante é pesquisada em uma tabela on-line do Databricks. A localização atual do usuário é enviada como parte da solicitação de pontuação. O modelo usa um recurso sob demanda para compute o tempo real de distância do usuário até o restaurante. Essa distância é então usada como entrada para o modelo.

Recurso de recomendação de restaurante sob demanda usando tabelas on-line demo Notebook

Open notebook in new tab