Výpočet prvků na vyžádání

V Azure Databricks se funkce na vyžádání počítají při inferenci pomocí uživatelsky definovaných funkcí v Pythonu (UDF). Použijte je, když hodnoty vlastností nejsou předem známé a závisejí na vstupech v době požadavku.

Chcete-li používat funkce dostupné na vyžádání, váš pracovní prostor musí mít povolený Unity Catalog a musíte používat Databricks Runtime 13.3 LTS ML nebo vyšší.

Co jsou funkce na vyžádání?

"Na vyžádání" odkazuje na funkce, jejichž hodnoty nejsou předem známé, ale počítají se v době odvozování. V Azure Databricks použijete uživatelem definované funkce Pythonu (UDF) k určení způsobu výpočtu funkcí na vyžádání. Tyto funkce se řídí katalogem Unity a zjistitelné prostřednictvím Průzkumníka katalogu.

Workflow

Pokud chcete vypočítat funkce na vyžádání, zadáte uživatelem definovanou funkci Pythonu (UDF), která popisuje, jak vypočítat hodnoty funkcí.

• Během trénování zadáte tuto funkci a její vstupní vazby v feature_lookups parametru create_training_set rozhraní API.
• Musíte zaznamenat natrénovaný model pomocí metody log_modelFeature Store. Tím se zajistí, že model automaticky vyhodnocuje funkce na vyžádání, když se použije k odvozování.
• Pro dávkové vyhodnocování score_batch rozhraní API automaticky vypočítá a vrátí všechny hodnoty funkcí, včetně funkcí na vyžádání.
• Když model nasadíte pomocí Model Serving, model automaticky použije uživatelsky definovanou funkci (UDF) v Pythonu k výpočtu atributů na vyžádání pro každý požadavek na skórování.

Vytvořit uživatelsky definovanou funkci v Pythonu

Uživatelem definovanou funkci v Pythonu lze vytvořit pomocí SQL nebo Pythonu. Následující příklady vytvoří uživatelem definovanou funkci Pythonu v katalogu main a schématu default.

Python

Pokud chcete použít Python, musíte nejprve nainstalovat databricks-sdk[openai] balíček. Použijte %pip install následující příkaz:

%pip install unitycatalog-ai[databricks]
dbutils.library.restartPython()

Pak použijte kód podobný následujícímu ke vytvoření uživatelem definované funkce v Pythonu:

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

CATALOG = "main"
SCHEMA = "default"

def add_numbers(number_1: float, number_2: float) -> float:
  """
  A function that accepts two floating point numbers, adds them,
  and returns the resulting sum as a float.

  Args:
      number_1 (float): The first of the two numbers to add.
      number_2 (float): The second of the two numbers to add.

  Returns:
      float: The sum of the two input numbers.
  """
  return number_1 + number_2

function_info = client.create_python_function(
  func=add_numbers,
  catalog=CATALOG,
  schema=SCHEMA,
  replace=True
)

Databricks SQL

Následující kód ukazuje, jak pomocí Databricks SQL vytvořit uživatelskou funkci v Pythonu.

%sql
CREATE OR REPLACE FUNCTION main.default.add_numbers(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)
$$

Po spuštění kódu můžete procházet tříúrovňový obor názvů v Průzkumníku katalogu a zobrazit definici funkce:

Další informace o vytváření uživatelsky definovaných funkcí v Pythonu najdete v tématu Registrace Python UDF do Unity Catalog a v referenční příručce k jazyku SQL.

Zpracování chybějících hodnot funkcí

Pokud UDF Pythonu závisí na výsledku funkceLookup, hodnota vrácená v případě, že požadovaný vyhledávací klíč nebyl nalezen, závisí na prostředí. Při použití score_batch je vrácená hodnota None. Při použití online obsluhování je vrácená hodnota float("nan").

Následující kód je příkladem způsobu zpracování obou případů.

%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
$$

Trénování modelu pomocí funkcí na vyžádání

K natrénování modelu použijete FeatureFunction, který se předává rozhraní API create_training_set v parametru feature_lookups.

Následující ukázka kódu používá funkci Python UDF main.default.example_feature, která byla definována v předchozí části.

# 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 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)

Zadání výchozích hodnot

Chcete-li zadat výchozí hodnoty pro funkce, použijte default_values parametr v souboru FeatureLookup.

FeatureLookup(
  table_name = 'main.default.table',
  feature_names = ['materialized_feature_value'],
  lookup_key = 'id',
  default_values={
    "materialized_feature_value": 0
  }
)

Pokud se sloupce funkcí přejmenují pomocí parametru rename_outputs , default_values musí používat přejmenované názvy funkcí.

FeatureLookup(
  table_name = 'main.default.table',
  feature_names = ['materialized_feature_value'],
  lookup_key = 'id',
  rename_outputs={"materialized_feature_value": "feature_value"},
  default_values={
    "feature_value": 0
  }
)

Zalogujte model a zaregistrujte ho do Unity Catalog

Modely zabalené s metadaty funkcí je možné zaregistrovat do katalogu Unity. Tabulky funkcí použité k vytvoření modelu musí být uložené v katalogu Unity.

Pokud chcete zajistit, aby model při odvozování automaticky vyhodnocoval funkce na vyžádání, musíte nastavit identifikátor URI registru a pak model protokolovat následujícím způsobem:

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"
)

Pokud funkce Python UDF, která definuje funkce na vyžádání, importuje nějaké balíčky Pythonu, musíte tyto balíčky zadat pomocí argumentu extra_pip_requirements. Příklad:

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"]
)

Omezení

• Funkce na vyžádání můžou vypisovat všechny datové typy podporované úložištěm funkcí s výjimkou MapType a ArrayType.
• Pro verze databricks-feature-engineering nižší než 0.14.0 jsou k použití uživatelsky definované funkce (UDF) pro vytvoření tréninkové sady nebo k vytvoření koncového bodu pro podávání funkcí vyžadována následující oprávnění katalogu Unity.
  • USE CATALOG oprávnění v system katalogu
  • USE SCHEMAoprávnění ke schématu system.information_schema

Příklady poznámkových bloků: Funkce na vyžádání

Následující poznámkový blok ukazuje příklad trénování a hodnocení modelu, který používá funkci na vyžádání.

Ukázkový notebook se základními funkcemi na vyžádání

Získat poznámkový sešit

Následující poznámkový blok ukazuje příklad modelu doporučení restaurace. Poloha restaurace se hledá z online tabulky Databricks. Aktuální umístění uživatele se odešle jako součást žádosti o bodování. Model používá funkci na vyžádání k výpočtu vzdálenosti v reálném čase od uživatele do restaurace. Tato vzdálenost se pak použije jako vstup do modelu.

Doporučení restaurací na vyžádání s využitím online poznámkového bloku s ukázkami tabulek

Získat poznámkový sešit