Ensinando modelos com recurso declarativo

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Esta página descreve como usar recursos declarativos para treinamento de modelos. Para informações sobre definição de recurso declarativo, veja Recurso declarativo.

Requisitos

• O recurso deve ser criado com a API declarativa de recursos. Veja Recurso declarativo.

Métodos da API

create_training_set()

Após criar o recurso declarativo, o próximo passo é criar os dados de treinamento para o seu modelo. Para fazer isso, passe um dataset de rótulo para create_training_set, o que garante automaticamente o cálculo preciso de cada valor de recurso em um determinado momento.

Por exemplo:

Python

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

Chame TrainingSet.load_df para join os dados de treinamento originais com o recurso de cálculo dinâmico pontual.

O argumento df deve atender aos seguintes requisitos:

• Deve conter todas as colunas de entidade referenciadas pelas definições de recurso.
• Deve conter a coluna de série temporal referenciada pelas definições de recurso.
• Deve conter todas as colunas declaradas em qualquer esquema RequestSource . Os tipos são validados em relação ao esquema declarado — incompatibilidades geram um erro (sem conversão implícita).
• Deve conter coluna(s) de rótulo.
• O conjunto de nomes de colunas de entidade, nomes de colunas de séries temporais e nomes de colunas de recursos de solicitação deve ser globalmente exclusivo em todas as fontes.

Correção pontual: Para agregações e recursos ColumnSelection baseados em uma fonte de tabela, os recursos são calculados usando apenas os dados de origem disponíveis antes do carimbo de data/hora de cada linha, para evitar vazamento futuro de dados no treinamento do modelo. Para o recurso RequestSource , o valor é obtido diretamente da linha DataFrame rótulo.

log_model()

Use MLflow para log um modelo com metadados de recursos para acompanhamento de linhagem e busca automática de recursos durante a inferência:

Python

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
)

O parâmetro flavor especifica o módulo de sabor do modelo MLflow a ser usado, como mlflow.sklearn ou mlflow.xgboost.

Os registros de modelos com um TrainingSet rastreiam automaticamente a linhagem até o recurso usado no treinamento. Quando o conjunto de treinamento inclui RequestSource recurso, as colunas RequestSource são adicionadas à assinatura do modelo MLflow como entradas obrigatórias. Isso garante que o esquema da API do endpoint de serviço reflita os campos que os chamadores devem fornecer no momento da inferência. Para mais detalhes, consulte ensinar modelos com tabelas de recursos.

score_batch()

Realizar inferência de lotes com busca automática de recursos:

Python

FeatureEngineeringClient.score_batch(
    model_uri: str,                           # URI of logged model
    df: DataFrame,                            # DataFrame with entity keys and timestamps
) -> DataFrame

score_batch Utiliza os metadados de recurso armazenados com o modelo para compute automaticamente o recurso correto em um determinado momento para inferência, garantindo a consistência com o treinamento. Para mais detalhes, consulte ensinar modelos com tabelas de recursos.

Exemplo de fluxo de trabalho

Python

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 declarative features
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()

treinamento com recurso RequestSource

Quando seu modelo requer dados que são fornecidos no momento da inferência (como detalhes de transação de uma chamada API ), use o recurso RequestSource juntamente com o recurso baseado em tabela. Durante o treinamento, RequestSource colunas são extraídas do DataFrame de rótulo.

Python

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

O que chega ao modelo bruto no momento do atendimento?

O wrapper do modelo Feature Store filtra as colunas antes de passá-las para o modelo bruto:

Tipo de coluna	Atinge o modelo interno?
Saídas de recurso explícitas (ColumnSelection, agregação)	Sim
RequestSource colunas declaradas como recurso	Sim
Colunas de entidade (chave de pesquisa)	Não (a menos que seja explicitamente declarado como um recurso)
Colunas de séries temporais	Não (a menos que seja explicitamente declarado como um recurso)