Fornire viste delle funzionalità

È possibile gestire le visualizzazioni delle funzionalità online in due modi:

  • Model serving: Distribuisci un modello addestrato sulle Feature Views. L'endpoint cerca o calcola automaticamente i valori delle caratteristiche, utilizzando la linea tracciata al momento del registro del modello. Usare questa opzione per gestire le stime del modello.
  • Funzionalità di gestione: distribuire un oggetto FeatureSpec che fa riferimento direttamente alle visualizzazioni delle funzionalità, senza un modello. L'endpoint restituisce gli output delle funzionalità richiesti. Usare questa opzione quando un'applicazione richiede valori di funzionalità anziché stime del modello.

Entrambi gli approcci supportano funzionalità precomputate e on-demand. Le feature foglia supportate da tabelle e flussi devono supportare materializzazioni online. RequestSource fornisce valori dalla richiesta e CustomUDF calcola le funzionalità su richiesta. Per un CustomUDF con FeatureViewSource, servire risolve le dipendenze a monte e valuta automaticamente il grafo di dipendenza delle caratteristiche.

Registra le funzionalità richieste e tutte le loro funzionalità transitive a monte nel Catalogo Unity. Materializza solo le foglie supportate da tabelle e stream, non le funzionalità in fase di richiesta o derivate CustomUDF.

Permissions

Per gestire una funzionalità, l'entità che crea l'endpoint di gestione del modello deve avere SELECT nella tabella del catalogo Unity che esegue il backup della funzionalità materializzata. Le ricerche online vengono lette direttamente dalla tabella materializzata, quindi il livello SELECT di tabella è ciò che concede l'accesso. Per la descrizione dei privilegi, vedere SELECT.

Poiché una tabella materializzata può contenere più di una funzionalità, concedere SELECT su di essa garantisce l'accesso a tutte le funzionalità presenti in quella tabella, non solo a quella che si intende rendere disponibile. Prima di concedere l'accesso, verificare che ogni funzionalità che condivide la tabella possa essere condivisa con l'entità. Per limitare l'esposizione, materializzare separatamente le caratteristiche sensibili.

Per concedere questo accesso senza risolvere le tabelle a mano, usare FeatureEngineeringClient.grant_feature_serving_access. Dato un modello o una specifica di funzionalità, ogni funzionalità viene risolta nella relativa tabella online, concede SELECT (insieme USE CATALOG a e USE SCHEMA) in tali tabelle alle entità specificate e restituisce un report di ogni tabella e le funzionalità aggiuntive esposte dalla concessione. Passa dry_run=True per visualizzare l'anteprima del report prima di concedere l'autorizzazione.

from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()

# Preview the tables and the features each grant would expose.
report = fe.grant_feature_serving_access(
    grant_to=["serving-principal@example.com"],
    model_uri="models:/main.ecommerce.fraud_model/1",
    dry_run=True,
)
print(report)

# Grant SELECT on the resolved online tables.
fe.grant_feature_serving_access(
    grant_to=["serving-principal@example.com"],
    model_uri="models:/main.ecommerce.fraud_model/1",
)

Distribuire un endpoint di gestione di un modello

Usare un endpoint di gestione di un modello esistente o usare Databricks SDK per crearne uno nuovo. Il modello deve essere registrato in Unity Catalog.

Se a CustomUDF utilizza una funzione definita dall'utente (UDF) che importa pacchetti Python, passali esplicitamente quando extra_pip_requirements chiami log_model. Vedi Dipendenze UDF personalizzate.

Il codice seguente illustra come creare un nuovo endpoint di gestione del modello. Per altre informazioni, vedere Creare endpoint di gestione di modelli personalizzati.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

w = WorkspaceClient()

endpoint_name = "fraud-detection-endpoint"
model_name = "main.ecommerce.fraud_model"

w.serving_endpoints.create(
    name=endpoint_name,
    config=EndpointCoreConfigInput(
        name=endpoint_name,
        served_entities=[
            ServedEntityInput(
                entity_name=model_name,
                entity_version=1,
                max_provisioned_concurrency=4,
                min_provisioned_concurrency=0,
            )
        ],
    ),
)

Eseguire una query sull'endpoint

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

response = w.serving_endpoints.query(
    name="fraud-detection-endpoint",
    dataframe_records=[
        {"user_id": "user_123", "transaction_time": "2026-03-01T12:00:00"},
    ],
)

Eseguire query sull'endpoint con le funzionalità RequestSource

Se i modelli sono stati addestrati con RequestSource caratteristiche, il payload della richiesta deve includere anche tutte le RequestSource colonne. Queste colonne sono state aggiunte alla firma del modello MLflow durante log_model, quindi lo schema dell'API dell'endpoint riflette i campi di richiesta richiesti.

response = w.serving_endpoints.query(
    name="fraud-detection-endpoint",
    dataframe_records=[
        {
            "user_id": "user_123",
            "transaction_time": "2026-03-01T12:00:00",
            "transaction_amount": 275.30,  # RequestSource column
            "vendor_id": "v_42",           # RequestSource column (also used as entity key)
        },
    ],
)

Le chiavi di entità vengono usate per cercare le funzionalità supportate da tabelle dall'archivio online. Una ColumnSelection caratteristica può trasmettere un RequestSource valore al modello. Una CustomUDF caratteristica trasforma i suoi input di richiesta prima che il modello utilizzi il risultato.

È anche possibile usare curl:

curl -X POST "https://<workspace>.cloud.databricks.com/serving-endpoints/<endpoint>/invocations" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataframe_records": [
      {
        "user_id": "user_123",
        "transaction_time": "2026-03-01T12:00:00",
        "transaction_amount": 275.30,
        "vendor_id": "v_42"
      }
    ]
  }'

Gestire le funzionalità con un FeatureSpec

Per gestire le visualizzazioni delle funzionalità senza un modello, creare un oggetto FeatureSpec che faccia riferimento alle funzionalità e distribuirlo in un endpoint di gestione delle funzionalità. L'endpoint restituisce solo le funzionalità richieste nella specifica. Calcola automaticamente i valori intermedi senza restituirli, a meno che tu non richieda anche quelle caratteristiche.

Registra tutte le funzionalità nel Catalogo Unity e crea materializzazioni online supportate per le foglie supportate da tabella e flusso prima di creare l'endpoint.

Note

Un oggetto FeatureSpec che contiene viste di funzionalità non può contenere anche definizioni di FeatureLookup o di FeatureFunction. Le Feature Views non possono essere mescolate con tali definizioni nello stesso FeatureSpec.

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities.feature_serving_endpoint import (
    EndpointCoreConfig,
    ServedEntity,
)

fe = FeatureEngineeringClient()

# 1. Retrieve a registered Feature View
agg_feature = fe.get_feature(full_name="main.ecommerce.amount_sum_sliding_7d_1d")

# 2. Create a FeatureSpec that includes the Feature View
feature_spec_name = "main.ecommerce.transaction_feature_spec"
fe.create_feature_spec(name=feature_spec_name, features=[agg_feature])

# 3. Deploy a Feature Serving endpoint backed by the FeatureSpec
fe.create_feature_serving_endpoint(
    name="transaction-features",
    config=EndpointCoreConfig(
        served_entities=ServedEntity(
            feature_spec_name=feature_spec_name,
            workload_size="Small",
            scale_to_zero_enabled=True,
        )
    ),
)

Eseguire una query sull'endpoint con le chiavi di entità usate per cercare le funzionalità materializzate:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

response = w.serving_endpoints.query(
    name="transaction-features",
    dataframe_records=[{"user_id": "user_123"}],
)

Per maggiori informazioni sugli endpoint di Feature Serving consulta Servire tabelle di funzionalità.

Serve le funzionalità di CustomUDF e le loro dipendenze

Questo esempio illustra le funzionalità di transazione e di margine definite negli esempi CustomUDF e FeatureViewSource. Usa databricks-feature-engineering la versione 0.18.0 o superiore per queste API delle Feature Views.

  • log_transaction_amount applica main.ecommerce.log_amount_udf al valore transaction_amount della richiesta utilizzando NumPy.
  • margin usa FeatureViewSource per calcolare un margine da revenue_sum_7d e cost_sum_7d. Queste funzionalità upstream utilizzano customer_id come chiave dell'entità e event_time come colonna delle serie temporali.

Registra entrambe le caratteristiche di output e tutte le funzionalità a monte prima di creare la specifica. Per questo esempio, materializza online solo i revenue_sum_7d and cost_sum_7d leave. Serving cerca i loro valori e calcola margin per ogni richiesta.

Recupera gli oggetti registrati Feature e passali a create_feature_spec. Dichiara NumPy per l'esecuzione online anche se è già elencato nella clausola dell'UDF ENVIRONMENT :

from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()
log_transaction_amount = fe.get_feature(
    full_name="main.ecommerce.log_transaction_amount"
)
margin = fe.get_feature(full_name="main.ecommerce.margin")

fe.create_feature_spec(
    name="main.ecommerce.derived_transaction_features",
    features=[log_transaction_amount, margin],
    extra_pip_requirements=["numpy==1.26.4"],
)

Segui i passaggi di creazione dell'endpoint sopra con feature_spec_name="main.ecommerce.derived_transaction_features" e un nome endpoint come derived-transaction-features. Dopo che l'endpoint è pronto, fornisce la chiave di ricerca e il valore del tempo di richiesta:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
response = w.serving_endpoints.query(
    name="derived-transaction-features",
    dataframe_records=[
        {"customer_id": "customer_123", "transaction_amount": 99.0},
    ],
)

La risposta contiene solo gli output richiesti log_transaction_amount e margin, non i valori intermedi di ricavi e costi. Per formati di dipendenze, permessi di ruota e risoluzione dei problemi di installazione, vedi Aggiungi dipendenze Python.

  • Ultimo aggiornamento: