Вычисление функций по запросу

В этой статье описывается создание и использование функций по запросу в Azure Databricks.

Чтобы использовать функции по запросу, рабочая область должна быть включена для каталога Unity, и необходимо использовать Databricks Runtime 13.3 LTS ML или более поздней версии.

Что такое функции по запросу?

"По запросу" относится к функциям, значения которых не известны заранее, но вычисляются во время вывода. В Azure Databricks вы используете определяемые пользователем функции Python , чтобы указать, как вычислять функции по запросу. Эти функции управляются каталогом Unity и доступны для обнаружения с помощью обозревателя каталогов.

Рабочий процесс

Чтобы вычислить функции по запросу, укажите определяемую пользователем функцию Python ( UDF), которая описывает вычисление значений признаков.

Во время обучения вы предоставляете эту функцию и ее входные привязки в feature_lookups параметре create_training_set API.
Необходимо записать обученную модель с помощью метода log_modelFeature Store. Это гарантирует, что модель автоматически вычисляет функции по запросу при использовании для вывода.
Для пакетной оценки API score_batch автоматически вычисляет и возвращает все значения признаков, включая функции по запросу.
При обслуживании модели с мозаичной моделью ИИ, модель автоматически использует UDF Python для вычисления функций по запросу для каждого запроса оценки.

Создание UDF Python

Вы можете создать UDF Python с помощью кода SQL или Python. В следующих примерах в каталоге main и схеме defaultсоздается UDF Python.

Питон

Чтобы использовать Python, необходимо сначала установить databricks-sdk[openai] пакет. Используйте %pip install следующим образом:

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

Затем используйте код, аналогичный следующему, чтобы создать UDF Python:

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

В следующем коде показано, как использовать Databricks SQL для создания UDF Python:

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

После выполнения кода можно перейти к пространству имен трех уровней в обозревателе каталогов , чтобы просмотреть определение функции:

функция в обозревателе каталогов

Дополнительные сведения о создании пользовательских функций Python см. в разделе Регистрация UDF Python в каталоге Unity и справочнике по языку SQL.

Как обращаться с отсутствующими значениями признаков

Если UDF Python зависит от результата featureLookup, значение, возвращаемое, если запрошенный ключ подстановки не найден, зависит от среды. При использовании score_batchвозвращается Noneвозвращаемое значение. При использовании онлайн-обслуживания возвращается float("nan")значение.

Следующий код является примером обработки обоих вариантов.

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

Обучение модели с помощью функций по запросу

Для обучения модели используется FeatureFunctionapi, который передается create_training_set в API в параметре feature_lookups .

В следующем примере кода используется UDF main.default.example_feature 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 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)

Указание значений по умолчанию

Чтобы указать значения по умолчанию для функций, используйте default_values параметр в файле FeatureLookup.

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

Если столбцы компонентов переименованы с помощью rename_outputs параметра, default_values необходимо использовать переименованные имена компонентов.

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

Запишите модель и зарегистрируйте ее в каталоге Unity

Модели, упакованные с метаданными компонентов, можно зарегистрированы в каталоге Unity. Таблицы компонентов, используемые для создания модели, должны храниться в каталоге Unity.

Чтобы модель автоматически вычисляла функции по запросу, если она используется для вывода, необходимо задать универсальный код ресурса (URI) реестра, а затем записать модель следующим образом:

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

Если UDF Python, определяющий функции по запросу, импортирует все пакеты Python, необходимо указать эти пакеты с помощью аргумента extra_pip_requirements. Например:

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

Ограничения

Функции по запросу могут выводить все типы данных, поддерживаемые Хранилищем компонентов, кроме MapType и ArrayType.
Для databricks-feature-engineering версий ниже 0.14.0 требуются следующие разрешения каталога Unity для использования пользовательской функции (UDF) для создания обучающего набора или создания Feature Serving endpoint.
- USE CATALOGпривилегии в каталоге system
- USE SCHEMAпривилегии в схеме system.information_schema

Примеры записных книжек: функции по запросу

В следующей записной книжке показан пример обучения и оценки модели, которая использует функцию по запросу.

Базовая демонстрационная записная книжка по запросу

Возьмите записную книжку

В следующей записной книжке показан пример модели рекомендаций ресторана. Расположение ресторана выбирается из онлайн-таблицы Databricks. Текущее расположение пользователя отправляется в рамках запроса оценки. Модель использует функцию по запросу для вычисления расстояния в режиме реального времени от пользователя к ресторану. Это расстояние затем используется в качестве входных данных для модели.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-04