기능 보기를 사용하면 유추 시 특정 시점의 올바른 기능 계산 및 자동 기능 조회를 사용하여 모델을 학습시킬 수 있습니다. 기능 뷰 정의에 대한 자세한 내용은 기능 보기를 참조하세요.
요구 사항
- 피처는 피처 뷰로 생성해야 합니다. 기능 보기를 참조하세요.
-
FeatureViewSource및CustomUDF요구 사항은 Feature Views API 참조 문서를 참조하세요.
API 메서드
create_training_set()
기능 뷰를 만든 후 다음 단계는 모델에 대한 학습 데이터를 만드는 것입니다. 이렇게 하려면 레이블이 지정된 데이터 세트를 전달하여 create_training_set각 기능 값의 지정 시간 정확한 계산을 자동으로 보장합니다.
다음은 그 예입니다.
FeatureEngineeringClient.create_training_set(
df: DataFrame, # DataFrame with training data
features: Optional[List[Feature]], # List of Feature objects
label: Union[str, List[str], None], # Label column name(s)
exclude_columns: Optional[List[str]] = None, # Optional: columns to exclude
) -> TrainingSet
특정 시점의 동적으로 계산된 기능을 사용하여 원래 학습 데이터를 조인하기 위한 호출 TrainingSet.load_df 입니다.
인수는 df 다음 요구 사항을 충족해야 합니다.
- 기능 정의에서 참조하는 모든 엔터티 열을 포함해야 합니다.
- 기능 정의에서 참조하는 timeseries 열을 포함해야 합니다.
- 모든
RequestSource스키마에 선언된 열을 포함해야 합니다. 형식은 선언된 스키마에 대해 유효성을 검사합니다. 불일치는 오류를 발생합니다(암시적 캐스팅 없음). - 레이블 열을 포함해야 합니다.
- 엔터티 열 이름, 시간 열 이름 및 요청 기능 열 이름 집합은 모든 원본에서 전역적으로 고유해야 합니다.
지정 시간 정확성: 테이블 원본에서 지원되는 집계 및 ColumnSelection 기능의 경우 각 행의 타임스탬프 전에 사용할 수 있는 원본 데이터만 사용하여 기능을 계산하여 향후 모델 학습으로 데이터가 누출되는 것을 방지합니다. 기능의 경우 RequestSource 값은 레이블이 지정된 DataFrame 행에서 직접 가져옵니다.
log_model()
MLflow를 사용하여 유추 중에 계보 추적 및 자동 기능 조회를 위한 기능 메타데이터를 사용하여 모델을 기록합니다.
FeatureEngineeringClient.log_model(
model, # Trained model object
artifact_path: str, # Path to store model artifact
flavor: ModuleType, # MLflow flavor module (e.g., mlflow.sklearn)
training_set: TrainingSet, # TrainingSet used for training
registered_model_name: Optional[str], # Optional: register model in Unity Catalog
extra_pip_requirements: Optional[List[str]] = None, # Optional: Additional serving dependencies
)
매개 변수는 flavor 사용할 MLflow 모델 버전 모듈(예: mlflow.sklearn 또는 mlflow.xgboost.)을 지정합니다.
학습에 TrainingSet 사용되는 기능에 대한 계보를 자동으로 추적하여 기록된 모델입니다. 학습 집합에 RequestSource 특징이 포함되면 필요한 입력으로 MLflow 모델 RequestSource 열이 사양에 추가됩니다. 이렇게 하면 서비스 엔드포인트의 API 스키마가 호출자가 유추 시간에 제공해야 하는 필드를 반영합니다. 자세한 내용은 기능 테이블을 사용하여 모델 학습을 참조하세요.
에 대해 FeatureViewSource, 모델을 기록하기 전에 파생 특징과 그 상류 특징을 등록합니다. 추론 시점에 전이 의존성에 필요한 요청 입력도 필요합니다. 모델 패키지 요구사항에 대해서는 Custom UDF 의존성을 참조하세요.
score_batch()
자동 기능 조회를 사용하여 일괄 처리 유추를 수행합니다.
FeatureEngineeringClient.score_batch(
model_uri: str, # URI of logged model
df: DataFrame, # DataFrame with entity keys and timestamps
) -> DataFrame
score_batch 는 모델과 함께 저장된 기능 메타데이터를 사용하여 유추를 위해 지정 시간 올바른 기능을 자동으로 계산하여 학습과의 일관성을 보장합니다. 자세한 내용은 기능 테이블을 사용하여 모델 학습을 참조하세요.
예시 워크플로
import mlflow
from databricks.feature_engineering import FeatureEngineeringClient
from sklearn.ensemble import RandomForestClassifier
fe = FeatureEngineeringClient()
# Assume features are registered in UC
# labeled_df should have columns "user_id", "transaction_time", and "is_fraud"
# 1. Create training set using Feature Views
training_set = fe.create_training_set(
df=labeled_df,
features=features,
label="is_fraud",
)
# 2. Load training data with computed features
training_df = training_set.load_df()
X = training_df.drop("is_fraud").toPandas()
y = training_df.select("is_fraud").toPandas().values.ravel()
# 3. Train model
model = RandomForestClassifier().fit(X, y)
# 4. Log model with feature metadata
with mlflow.start_run():
fe.log_model(
model=model,
artifact_path="fraud_model",
flavor=mlflow.sklearn,
training_set=training_set,
registered_model_name="main.ecommerce.fraud_model",
)
# 5. Batch scoring with automatic feature lookup
# inference_df must contain the same entity and timeseries columns
# used during training. Features are automatically computed.
predictions = fe.score_batch(
model_uri="models:/main.ecommerce.fraud_model/1",
df=inference_df,
)
predictions.display()
RequestSource 기능을 사용하여 학습
모델이 유추 시간에 제공되는 데이터(예: API 호출의 트랜잭션 세부 정보)를 필요로 하는 경우, 테이블 기반 특징과 함께 RequestSource 특징을 사용하십시오. 학습할 때 RequestSource 레이블이 지정된 DataFrame에서 열이 추출됩니다.
from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
DeltaTableSource, Feature, FieldDefinition, RequestSource,
ScalarDataType, ColumnSelection,
)
fe = FeatureEngineeringClient()
# RequestSource provides transaction data at inference time
request_source = RequestSource(
schema=[
FieldDefinition(name="transaction_amount", data_type=ScalarDataType.DOUBLE),
FieldDefinition(name="vendor_id", data_type=ScalarDataType.STRING),
FieldDefinition(name="transaction_id", data_type=ScalarDataType.STRING),
FieldDefinition(name="transaction_time", data_type=ScalarDataType.DATE),
]
)
delta_source = DeltaTableSource(
catalog_name="catalog",
schema_name="schema",
table_name="vendor_data",
)
# A column selection feature from the request source (pass-through)
latest_transaction_amount = Feature(
source=request_source,
function=ColumnSelection("transaction_amount"),
name="latest_transaction_amount",
)
# A lookup feature from a delta table
vendor_category = Feature(
source=delta_source,
function=ColumnSelection("vendor_category"),
entity=["vendor_id"],
timeseries_column="transaction_time",
name="vendor_category",
)
# labels_df must contain: transaction_id, transaction_time, vendor_id,
# transaction_amount, and the label column.
ts = fe.create_training_set(
df=labels_df,
features=[latest_transaction_amount, vendor_category],
label="is_fraud",
exclude_columns=["card_id"],
)
import mlflow
from sklearn.ensemble import RandomForestClassifier
with mlflow.start_run():
training_df = ts.load_df().toPandas()
X = training_df.drop(columns=["is_fraud"])
y = training_df["is_fraud"]
model = RandomForestClassifier().fit(X, y)
# log_model() adds RequestSource columns to the MLflow model signature
fe.log_model(
model=model,
artifact_path="fraud_model",
flavor=mlflow.sklearn,
training_set=ts,
registered_model_name="catalog.schema.fraud_model",
)
CustomUDF를 사용해 요청 값을 변환
요청 데이터를 변환하려면 . 대신 ColumnSelection를 사용 CustomUDF 하세요. 이 예시는 트랜잭션 로그-변환 기능을 사용합니다:
log_transaction_amount = fe.get_feature(
full_name="main.ecommerce.log_transaction_amount"
)
request_df = spark.createDataFrame(
[(0.0, 0), (99.0, 1)],
"transaction_amount DOUBLE, label INT",
)
transaction_training_set = fe.create_training_set(
df=request_df,
features=[log_transaction_amount],
label="label",
)
transaction_training_set.load_df().show()
결과에는 원래의 transaction_amount 및 label 열과 log_transaction_amount가 포함됩니다. UDF는 각 행에서 transaction_amount를 읽습니다. 계산에 필요한 요청 열은 exclude_columns에 나열할 수 없습니다.
FeatureViewSource 기능을 사용하여 학습
FeatureViewSource를 사용하면 CustomUDF가 파생 특성을 포함한 다른 특성의 출력을 사용할 수 있습니다. 원하는 create_training_set출력을 전달하세요. 중간 의존성을 나열할 필요는 없습니다.
각 입력 행에 대해 Azure Databricks는 전체 의존성 그래프를 해결합니다:
- 엔티티 키, 타임스탬프, 윈도우 정의를 사용하여 테이블 백업 업스트림 기능을 계산합니다. 사용 가능한 경우 호환되는 오프라인 구체화를 사용합니다.
- 입력된 DataFrame에서 필요한 요청 열을 읽고 요청 지원 기능을 평가합니다.
- 파생 특징을 종속 순서로 평가하여 각 UDF가 상류 결과를 받도록 합니다.
파생된 특징은 또 다른 시간 창이나 시점 조회를 도입하지 않습니다. 상류 기능들은 고유한 시간 의미를 유지합니다. 데이터프레임에는 최종 파생 기능만 요청될 때조차도 해당 상류가 필요로 하는 엔티티, 타임스탬프, 요청 열을 포함해야 합니다.
예를 들어, cost_sum_7d와 revenue_sum_7d를 결합한 등록된 마진 기능을 사용합니다:
from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
margin = fe.get_feature(full_name="main.ecommerce.margin")
# labeled_df contains customer_id, event_time, and label.
training_set = fe.create_training_set(
df=labeled_df,
features=[margin],
label="label",
exclude_columns=["customer_id", "event_time"],
)
training_df = training_set.load_df()
결과에는 margin와 label가 포함됩니다. 수익 및 비용 특성은 계산되지만 추가 열로 반환되지는 않습니다. 학습 데이터에 수익을 포함하려면 revenue = fe.get_feature(full_name="main.ecommerce.revenue_sum_7d")를 사용해 수익을 가져오고 features=[margin, revenue]를 전달하세요. 이것은 다중 레벨 체인에도 적용되며, 최종 기능을 요청해도 각 중간 출력을 반환하지 않습니다.
요청 지원, 테이블 지원, 파생 기능을 같은 features 목록에 결합할 수 있습니다. 하나의 UDF 내에서 해당 값들을 결합하려면 요청 값을 피처로 표현하고 FeatureViewSource에서 테이블 기반 피처와 함께 참조합니다.
실험을 위해, 상류 그래프를 포함한 로컬 Feature 객체를 등록하지 않고 구성하세요.
create_training_set선택적으로 label=None, 와 함께 사용하여 결과를 검사합니다.
compute_features는 RequestSource 또는 FeatureViewSource를 지원하지 않습니다.
Note
Unity 카탈로그 UDF 호출 횟수는 조회당 5회 제한 이 훈련 쿼리에도 적용됩니다. 전체 의존성 그래프에 필요한 UDF 호출량을 계산하며, 요청된 함수만 출력으로 계산하지 마세요. 이 쿼리 제한은 그래프의 깊이 제한과는 별개입니다.
커스텀 UDF 의존성
오프라인 계산을 위해서는 Unity Catalog UDF의 ENVIRONMENT 절에서 Python 패키지를 선언하세요. 노트북에 패키지를 설치하는 것만으로는 UDF 환경에는 설치되지 않습니다.
모델 서빙의 경우 필요한 패키지도 log_model에 명시적으로 전달하세요. UDF의 ENVIRONMENT도 Feature View를 포함하는 이름이 지정된 기능 사양도 이러한 모델 요구 사항을 자동으로 제공하지 않습니다. 요청된 기능 출력뿐만 아니라 업스트림 UDF에 필요한 의존성을 포함하세요.
scikit-learn 모델을 transaction_training_set.load_df()에서 훈련한 후, 동일한 훈련 세트로 해당 모델을 로그하세요. NumPy와 호환되는 조회 패키지를 포함하세요:
import mlflow
fe.log_model(
model=model,
artifact_path="transaction_model",
flavor=mlflow.sklearn,
training_set=transaction_training_set,
registered_model_name="main.ecommerce.transaction_model",
extra_pip_requirements=[
"numpy==1.26.4",
"databricks-feature-lookup>=1.15.0",
],
)
서비스 엔드포인트는 RequestSource 기능을 위한 온디맨드 Unity Catalog UDF 계산을 지원하는 버전 1.15.0 이상을 자동으로 선택 databricks-feature-lookup 해야 합니다. 계산된 값 차이를 피하기 위해 오프라인과 서빙 환경 간 UDF 패키지 버전을 일관되게 유지하세요. 모델이 없는 Feature Serving 엔드포인트의 경우, 대신 create_feature_spec에서 패키지를 선언하세요.
Python 의존성 추가를 참조하세요.
스트리밍 기능을 사용한 교육
Stream을 정의하면 Databricks는 델타 테이블에 스트림 데이터를 쓰는 수집 파이프라인을 관리합니다.
create_training_set는 이 수집 테이블에서 읽어 와서 DeltaTableSource의 배치 피처와 마찬가지로 레이블이 지정된 데이터프레임에 대해 시점 조인을 수행합니다. 인제스팅 구성, 백필 및 중복 제거에 대한 자세한 내용은 인제스 및 백필 항목을 참조하세요.
예시
from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
StreamSource,
Feature,
AggregationFunction,
Sum,
RollingWindow,
)
from datetime import timedelta
fe = FeatureEngineeringClient()
# Define a streaming feature
stream_source = StreamSource(full_name="my_catalog.my_schema.my_stream")
streaming_feature = Feature(
name="user_purchase_sum",
source=stream_source,
entity=["value.user_id"],
timeseries_column="value.event_time",
function=AggregationFunction(
operator=Sum(input="value.amount"),
time_window=RollingWindow(window_duration=timedelta(hours=1)),
),
)
# Create training set — reads from the ingestion table
# labeled_df must contain "user_id", "event_time", and label columns.
# Entity and timeseries columns use leaf node names (not value. prefixes).
training_set = fe.create_training_set(
df=labeled_df,
features=[streaming_feature],
label="is_fraud",
)
training_df = training_set.load_df()
일괄 처리 및 스트리밍 기능 혼합
일괄 처리 및 스트리밍 기능은 동일한 학습 집합 및 모델에서 함께 사용할 수 있습니다. 서비스 시간에 일괄 처리 기능은 오프라인 또는 온라인 스토어에서 조회되고 스트리밍 기능은 온라인 스토어에서 조회됩니다.
training_set = fe.create_training_set(
df=labeled_df,
features=[batch_feature, streaming_feature],
label="is_fraud",
)
로 log_model() 깅된 모델은 온라인 저장소에서 기능 조회를 수행하고 두 소스 형식 모두에 대한 모델 서명을 구성합니다.
운영 시점에 원시 모델에 도달하는 데이터
기능 저장소 모델 래퍼는 열을 원시 모델에 전달하기 전에 필터링합니다.
| 열 형식 | 내부 모델에 도달합니까? |
|---|---|
명시적 기능 출력(ColumnSelection, 집계) |
예 |
RequestSource 기능으로 선언된 열 |
예 |
| 엔티티 열(조회 키) | 아니요(기능으로 명시적으로 선언되지 않은 경우) |
| 시계열 열 | 아니요(기능으로 명시적으로 선언되지 않은 경우) |