다음을 통해 공유

주문형 기능 계산

이 문서에서는 Azure Databricks에서 주문형 기능을 만들고 사용하는 방법을 설명합니다.

주문형 기능을 사용하려면 Unity 카탈로그 작업 영역을 사용하도록 설정해야 하며 Databricks Runtime 13.3 LTS ML 이상을 사용해야 합니다.

주문형 기능이란?

"주문형"은 값을 미리 알 수 없지만 유추 시 계산되는 기능을 나타냅니다. Azure Databricks에서는 Python UDF(사용자 정의 함수)를 사용하여 주문형 기능을 계산하는 방법을 지정합니다. 이러한 함수는 Unity 카탈로그에 의해 관리되며 카탈로그 탐색기통해 검색할 수 있습니다.

요구 사항

  • UDF(사용자 정의 함수)를 사용하여 학습 집합을 만들거나 기능 제공 엔드포인트를 만들려면 카탈로그에 대한 USE CATALOG 권한과 system Unity 카탈로그의 USE SCHEMA 스키마에 대한 권한이 있어야 합니다system.information_schema.

워크플로

주문형 기능을 계산하려면 기능 값을 계산하는 방법을 설명하는 Python UDF(사용자 정의 함수)를 지정합니다.

  • 학습하는 동안 이 함수와 해당 입력 바인딩을 feature_lookups API의 create_training_set 매개 변수에 제공합니다.
  • 기능 저장소 메서드 log_model를 사용하여 학습된 모델을 기록해야 합니다. 이렇게 하면 모델이 유추에 사용될 때 주문형 기능을 자동으로 평가합니다.
  • 일괄 처리 채점의 경우 score_batch API는 주문형 기능을 포함하여 모든 기능 값을 자동으로 계산하고 반환합니다.
  • Mosaic AI Model Serving을 사용하여 모델을 제공하는 경우 모델은 자동으로 Python UDF를 사용하여 각 점수 매기기 요청에 대한 주문형 기능을 계산합니다.

Python UDF 만들기

SQL 또는 Python 코드를 사용하여 Python UDF를 만들 수 있습니다. 다음 예제에서는 카탈로그 main 및 스키마 default에 Python UDF를 만듭니다.

파이썬

Python을 사용하려면 먼저 패키지를 설치 databricks-sdk[openai] 해야 합니다. 다음과 같이 사용합니다 %pip install .

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

그런 다음, 다음과 유사한 코드를 사용하여 Python UDF를 만듭니다.

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 (데이터브릭스 SQL)

다음 코드에서는 Databricks SQL을 사용하여 Python UDF를 만드는 방법을 보여 줍니다.

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

코드를 실행한 후 카탈로그 탐색기 3개 수준 네임스페이스를 탐색하여 함수 정의를 볼 수 있습니다.

카탈로그 탐색기 함수

Python UDF를 만드는 방법에 대한 자세한 내용은 Python UDF를 Unity 카탈로그에 등록하는 방법 및 SQL 언어 수동을 참조하세요.

누락된 기능 값을 처리하는 방법

Python UDF가 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
$$

주문형 기능을 사용하여 모델 학습

모델을 학습하려면 FeatureFunction 매개 변수의 create_training_set API에 전달되는 feature_lookups을 사용합니다.

다음 예제 코드는 이전 섹션에서 정의한 Python UDF main.default.example_feature를 사용합니다.

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

주문형 기능을 정의하는 Python UDF가 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을 제외한 기능 저장소에서 지원하는 모든 데이터 형식을 출력할 수 있습니다.

Notebook 예제: 주문형 기능

다음 Notebook에서는 주문형 기능을 사용하는 모델을 학습시키고 점수를 매기는 방법의 예를 보여줍니다.

기본 주문형 기능 데모 Notebook

노트북을 가져오기

다음 Notebook에서는 식당 추천 모델의 예를 보여줍니다. 레스토랑의 위치는 Databricks 온라인 테이블에서 조회됩니다. 사용자의 현재 위치는 점수 매기기 요청의 일부로 전송됩니다. 이 모델은 주문형 기능을 사용하여 사용자에서 식당까지의 실시간 거리를 계산합니다. 그런 다음 해당 거리가 모델에 대한 입력으로 사용됩니다.

온라인 테이블 데모 노트북을 사용하는 레스토랑 추천 온디맨드 기능

노트북을 가져오기

  • Last updated on