Pubblicare le Feature View utilizzando i Declarative Automation Bundles

Importante

Questa funzionalità è in anteprima privata. Per provarlo, contattare il contatto di Azure Databricks.

I Declarative Automation Bundles (precedentemente noti come Databricks Asset Bundles) ti permettono di validare, distribuire ed eseguire programmaticamente risorse Azure Databricks come le Feature View e gli endpoint che le serviscono. Vedere Che cosa sono i bundle di automazione dichiarativa?.

Questo tutorial crea un pacchetto che dichiara due Feature View in streaming, le materializza su uno store online e le serve tramite un FeatureSpec endpoint di Feature Servering. Poi interroghi l'endpoint, cambi quali funzionalità serve e smonti tutto.

Le Feature View e la loro materializzazione seguono Manage Feature Views using Declarative Automation Bundles, che le spiega in dettaglio. Per creare un FeatureSpec e un endpoint con l'API Python invece, vedi Serve Feature Views.

Ogni passaggio mostra la configurazione sia in YAML che in Python. Scegli una lingua e la pagina segue la tua scelta.

Requirements

Per completare questa esercitazione, sono necessari gli elementi seguenti:

  • Databricks CLI versione 1.26.0 o successiva. Eseguire databricks --version per verificare. Consulta Installare o aggiornare la CLI di Databricks.
  • Un'area di lavoro abilitata per il Catalogo di Unity. Vedere Requisiti.
  • Permesso per creare funzionalità e materializzarle. Vedere Autorizzazioni.
  • Autorizzazione a creare un endpoint di serving del modello. Vedere Identità e accesso.
  • Un negozio online esistente. Vedi Creare un negozio online.
  • Un Stream esistente. Uno stream non è una risorsa bundle, quindi crealo prima e fai riferimento a esso per nome nel bundle. Vedi Creare un stream.
  • Python 3.10 o superiore, per dichiarare le risorse in Python.

Servire risorse in un bundle

Un bundle gestisce le Feature View attraverso due tipi di risorse:

  • FeatureSpec: una funzione del Catalogo Unity che elenca le funzionalità da servire. Non contiene valori delle feature. Un endpoint che li serve li legge dalle tabelle online a cui le Feature View sono materializzate. Vedi Servire feature con FeatureSpec e, per il riferimento alla configurazione, feature_spec.
  • Feature Serving endpoint: un endpoint di servizio di modello che serve un FeatureSpec invece di un modello. Un bundle lo dichiara come una risorsa model_serving_endpoints. Per il riferimento di configurazione, vedi model_serving_endpoint.

Pubblicare Feature Views da un bundle

I passaggi seguenti consistono nel costruire e distribuire il bundle, interrogare l'endpoint, modificare ciò che serve e ripulire.

Configurare l'autenticazione

Per prima cosa, imposta l'autenticazione tra la CLI Databricks sulla tua macchina di sviluppo e l'area di lavoro Azure Databricks. Questa pagina presuppone che si voglia usare l'autenticazione da utente a computer (U2M) OAuth e un profilo di configurazione di Azure Databricks corrispondente denominato DEFAULT per l'autenticazione.

Note

L'autenticazione U2M è appropriata per provare questi passaggi in tempo reale. Per i flussi di lavoro completamente automatizzati, Databricks consiglia di usare invece l'autenticazione OAuth da computer a computer (M2M). Consulta le istruzioni di configurazione dell'autenticazione M2M in Autorizzare l'accesso dell'entità di servizio ad Azure Databricks con OAuth.

  1. Usare l'interfaccia della riga di comando di Databricks per avviare la gestione dei token OAuth in locale eseguendo il comando seguente per ogni area di lavoro di destinazione.

    Nel comando seguente sostituire <workspace-url> con l'URL di Azure Databricks per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net.

    databricks auth login --host <workspace-url>
    
  2. Il Databricks CLI richiede di salvare le informazioni immesse come profilo di configurazione di Azure Databricks. Premere Enter per accettare il nome del profilo suggerito oppure immettere il nome di un profilo nuovo o esistente. Qualsiasi profilo esistente con lo stesso nome viene sovrascritto con le informazioni immesse. È possibile usare i profili per cambiare rapidamente il contesto di autenticazione tra più aree di lavoro.

    Per ottenere un elenco di tutti i profili esistenti, in un terminale o un prompt dei comandi separato, usare il Databricks CLI per eseguire il comando databricks auth profiles. Per visualizzare le impostazioni esistenti di un profilo specifico, eseguire il comando databricks auth env --profile <profile-name>.

  3. Nel Web browser completare le istruzioni visualizzate per accedere all'area di lavoro Azure Databricks.

  4. Per visualizzare il valore corrente del token OAuth di un profilo e il timestamp di scadenza imminente del token, eseguire uno dei comandi seguenti:

    • databricks auth token --host <workspace-url>
    • databricks auth token -p <profile-name>
    • databricks auth token --host <workspace-url> -p <profile-name>

    Se si dispone di più profili con lo stesso valore --host, potrebbe essere necessario specificare insieme le opzioni --host e -p per consentire al Databricks CLI di trovare le informazioni corrette corrispondenti sul token OAuth.

Crea il bundle

Crea una directory vuota per il bundle, con un databricks.yml file alla radice e una resources directory accanto ad essa.

YAML

Ognuno dei passaggi seguenti aggiunge un file sotto resources/:

databricks.yml
resources/
  streaming_features.yml
  feature_spec.yml
  serving_endpoint.yml

databricks.yml contiene il nome del bundle, la include voce che carica ogni file sotto resources/, e le variabili a cui le risorse si riferiscono:

bundle:
  name: feature-serving-quickstart

include:
  - resources/*.yml

variables:
  catalog:
    description: The catalog that the Feature Views and the FeatureSpec are written to.
    default: main
  schema:
    description: The schema that the Feature Views and the FeatureSpec are written to.
    default: features_demo
  stream:
    description: The three-level name of a Stream registered in Unity Catalog.
    default: main.features_demo.events
  online_store:
    description: The online store that serves the features.
    default: my_online_store
  endpoint_name:
    description: The name of the Feature Serving endpoint.
    default: event-features

Python

Le risorse dichiarate in Python si trovano solo tramite la python mappatura in databricks.yml. Senza di esso il bundle si convalida e viene distribuito con successo ma non contiene risorse, quindi aggiungilo ora:

bundle:
  name: feature-serving-quickstart

python:
  venv_path: .venv
  resources:
    - 'resources:load_resources'

variables:
  catalog:
    description: The catalog that the Feature Views and the FeatureSpec are written to.
    default: main
  schema:
    description: The schema that the Feature Views and the FeatureSpec are written to.
    default: features_demo
  stream:
    description: The three-level name of a Stream registered in Unity Catalog.
    default: main.features_demo.events
  online_store:
    description: The online store that serves the features.
    default: my_online_store
  endpoint_name:
    description: The name of the Feature Serving endpoint.
    default: event-features

Crea il progetto e il suo ambiente virtuale, e aggiungi il pacchetto:

uv init --bare
uv venv .venv
uv add databricks-bundles

Crea resources/__init__.py con la funzione che assegna un nome a databricks.yml:

from databricks.bundles.core import Bundle, Resources


def load_resources(bundle: Bundle) -> Resources:
    resources = Resources()
    # The following steps add resources here.
    return resources

Dichiara le Feature Views e la loro materializzazione

Entrambe le Feature View leggono lo stesso Stream e aggregano per chiave negli ultimi 90 minuti. events_90m conta gli eventi e amount_sum_90m somma value.amount. Un set di materializzazione scrive sia nello store online sia in modalità streaming. Per sapere cosa significa ciascuna chiave di configurazione, consulta il Passaggio 4 del tutorial sulle Feature Views.

Una Vista Feature in streaming rivolge una colonna di input come percorso verso il record dello stream, quindi sostituisci i nomi utilizzati dallo schema del tuo Stream ovunque gli esempi mostrino value.*.

YAML

Creare resources/streaming_features.yml:

resources:
  features:
    events_90m:
      full_name: ${var.catalog}.${var.schema}.events_90m
      description: Events per key over a trailing 90 minutes
      source:
        stream_source:
          full_name: ${var.stream}
      function:
        aggregation_function:
          count_function:
            input: value.amount
          time_window:
            rolling:
              window_duration: 5400s
      entities:
        - name: value.key
      timeseries_column:
        name: value.event_timestamp

    amount_sum_90m:
      full_name: ${var.catalog}.${var.schema}.amount_sum_90m
      description: Sum of amount per key over a trailing 90 minutes
      source:
        stream_source:
          full_name: ${var.stream}
      function:
        aggregation_function:
          sum:
            input: value.amount
          time_window:
            rolling:
              window_duration: 5400s
      entities:
        - name: value.key
      timeseries_column:
        name: value.event_timestamp

  materialization_sets:
    serving_online:
      materialized_features:
        - feature_name: ${resources.features.events_90m.full_name}
          online_store_config:
            online_store_name: ${var.online_store}
            catalog_name: ${var.catalog}
            schema_name: ${var.schema}
            table_name_prefix: serving_online
          streaming_mode:
            mode: STREAMING_MODE_TYPE_RTM
        - feature_name: ${resources.features.amount_sum_90m.full_name}
          online_store_config:
            online_store_name: ${var.online_store}
            catalog_name: ${var.catalog}
            schema_name: ${var.schema}
            table_name_prefix: serving_online
          streaming_mode:
            mode: STREAMING_MODE_TYPE_RTM

Python

Aggiungi le importazioni a resources/__init__.py:

from databricks.bundles.features import (
    AggregationFunction,
    CountFunction,
    DataSource,
    EntityColumn,
    Feature,
    Function,
    RollingWindow,
    StreamSource,
    SumFunction,
    TimeseriesColumn,
    TimeWindow,
)
from databricks.bundles.materialization_sets import (
    MaterializationSet,
    MaterializedFeature,
    OnlineStoreConfig,
    StreamingMode,
    StreamingModeStreamingModeType,
)

Poi aggiungi questo al corpo di load_resources:

resources.add_feature(
    'events_90m',
    Feature(
        full_name='${var.catalog}.${var.schema}.events_90m',
        description='Events per key over a trailing 90 minutes',
        source=DataSource(stream_source=StreamSource(full_name='${var.stream}')),
        function=Function(
            aggregation_function=AggregationFunction(
                count_function=CountFunction(input='value.amount'),
                time_window=TimeWindow(rolling=RollingWindow(window_duration='5400s')),
            )
        ),
        entities=[EntityColumn(name='value.key')],
        timeseries_column=TimeseriesColumn(name='value.event_timestamp'),
    ),
)

resources.add_feature(
    'amount_sum_90m',
    Feature(
        full_name='${var.catalog}.${var.schema}.amount_sum_90m',
        description='Sum of amount per key over a trailing 90 minutes',
        source=DataSource(stream_source=StreamSource(full_name='${var.stream}')),
        function=Function(
            aggregation_function=AggregationFunction(
                sum=SumFunction(input='value.amount'),
                time_window=TimeWindow(rolling=RollingWindow(window_duration='5400s')),
            )
        ),
        entities=[EntityColumn(name='value.key')],
        timeseries_column=TimeseriesColumn(name='value.event_timestamp'),
    ),
)

resources.add_materialization_set(
    'serving_online',
    MaterializationSet(
        materialized_features=[
            MaterializedFeature(
                feature_name='${resources.features.events_90m.full_name}',
                online_store_config=OnlineStoreConfig(
                    online_store_name='${var.online_store}',
                    catalog_name='${var.catalog}',
                    schema_name='${var.schema}',
                    table_name_prefix='serving_online',
                ),
                streaming_mode=StreamingMode(
                    mode=StreamingModeStreamingModeType.STREAMING_MODE_TYPE_RTM
                ),
            ),
            MaterializedFeature(
                feature_name='${resources.features.amount_sum_90m.full_name}',
                online_store_config=OnlineStoreConfig(
                    online_store_name='${var.online_store}',
                    catalog_name='${var.catalog}',
                    schema_name='${var.schema}',
                    table_name_prefix='serving_online',
                ),
                streaming_mode=StreamingMode(
                    mode=StreamingModeStreamingModeType.STREAMING_MODE_TYPE_RTM
                ),
            ),
        ]
    ),
)

Aggiungi una FeatureSpec

Il FeatureSpec elenca le funzionalità che l'endpoint serve. Ogni voce in features nomina una Vista Feature con declarative_feature.

Un FeatureSpec può essere creato solo dopo che ogni Feature View che nomina è materializzata in un archivio online. I riferimenti ${resources.features...} in declarative_feature fanno dipendere la spec dalle Feature Views events_90m e amount_sum_90m, e lifecycle.depends_on aggiunge la dipendenza che nessun riferimento esprime, dal set di materializzazione serving_online. Il bundle crea la specifica dopo tutte e tre le versioni e la cancella prima di loro. Vedi Regole che una FeatureSpec deve soddisfare.

YAML

Creare resources/feature_spec.yml:

resources:
  feature_specs:
    event_features:
      name: ${var.catalog}.${var.schema}.event_features
      features:
        - declarative_feature:
            feature: ${resources.features.events_90m.full_name}
        - declarative_feature:
            feature: ${resources.features.amount_sum_90m.full_name}
      lifecycle:
        depends_on:
          - resource: materialization_sets.serving_online

Python

Aggiungi le importazioni a resources/__init__.py:

from databricks.bundles.feature_specs import (
    DeclarativeFeature,
    DependsOn,
    FeatureSpec,
    Features,
    Lifecycle,
)

Poi aggiungi questo al corpo di load_resources:

resources.add_feature_spec(
    'event_features',
    FeatureSpec(
        name='${var.catalog}.${var.schema}.event_features',
        features=[
            Features(
                declarative_feature=DeclarativeFeature(
                    feature='${resources.features.events_90m.full_name}'
                )
            ),
            Features(
                declarative_feature=DeclarativeFeature(
                    feature='${resources.features.amount_sum_90m.full_name}'
                )
            ),
        ],
        lifecycle=Lifecycle(depends_on=[DependsOn(resource='materialization_sets.serving_online')]),
    ),
)

Aggiungi un endpoint di Feature Serving

L'endpoint serve il FeatureSpec a cui entity_name dà il nome. Poiché entity_name fa riferimento alla specifica name, il bundle crea l'endpoint dopo la specifica, come mostrato nell'output in Deploy , e lo elimina prima della specifica. Con scale_to_zero_enabled, l'endpoint riduce il suo calcolo a zero quando non riceve richieste.

YAML

Creare resources/serving_endpoint.yml:

resources:
  model_serving_endpoints:
    event_endpoint:
      name: ${var.endpoint_name}
      config:
        served_entities:
          - entity_name: ${resources.feature_specs.event_features.name}
            workload_size: Small
            scale_to_zero_enabled: true

Python

Aggiungi le importazioni a resources/__init__.py:

from databricks.bundles.model_serving_endpoints import (
    EndpointCoreConfigInput,
    ModelServingEndpoint,
    ServedEntityInput,
)

Poi aggiungi questo al corpo di load_resources:

resources.add_model_serving_endpoint(
    'event_endpoint',
    ModelServingEndpoint(
        name='${var.endpoint_name}',
        config=EndpointCoreConfigInput(
            served_entities=[
                ServedEntityInput(
                    entity_name='${resources.feature_specs.event_features.name}',
                    workload_size='Small',
                    scale_to_zero_enabled=True,
                )
            ]
        ),
    ),
)

Deploy

Controlla la configurazione, quindi ripassa cosa fa il deployment:

databricks bundle validate
databricks bundle plan

Alla prima distribuzione, tutte e cinque le risorse riportano create:

create feature_specs.event_features
create features.amount_sum_90m
create features.events_90m
create materialization_sets.serving_online
create model_serving_endpoints.event_endpoint

Plan: 5 to add, 0 to change, 0 to delete, 0 unchanged

Distribuire il bundle nell'area di lavoro:

databricks bundle deploy

La distribuzione crea le risorse in ordine di dipendenza e si conclude quando l'endpoint è pronto, il che richiede diversi minuti:

Uploading bundle files to /Workspace/Users/someone@example.com/.bundle/feature-serving-quickstart/default/files...
Created features.events_90m
Created features.amount_sum_90m
Created materialization_sets.serving_online
Created feature_specs.event_features
Created model_serving_endpoints.event_endpoint
Files: 4 uploaded, 0 deleted
Resources: 5 created, 0 changed, 0 deleted, 0 unchanged

Eseguire una query sull'endpoint

Invia le chiavi da cercare in dataframe_records. Un record nomina ogni chiave con l'ultimo segmento del percorso di entità della vista Feature View, quindi value.key diventa key:

databricks serving-endpoints query event-features --json '{"dataframe_records": [{"key": 1280}, {"key": 1188}, {"key": 42}, {"key": 10001}]}'

La risposta contiene un oggetto per ciascun record, nell'ordine della richiesta. Ogni oggetto contiene un valore per ciascuna Vista Feature, indicato dal nome della Vista Feature senza il suo catalogo e schema:

{
  "outputs": [
    {
      "events_90m": 10,
      "amount_sum_90m": 10
    },
    {
      "events_90m": 11,
      "amount_sum_90m": 11
    },
    {
      "events_90m": 9,
      "amount_sum_90m": 10
    },
    {
      "events_90m": 0,
      "amount_sum_90m": null
    }
  ]
}

Una chiave senza eventi nella finestra restituisce 0 il conteggio e null la somma, come invece fa la chiave 10001 . Ogni chiave restituisce questi valori fino a quando la pipeline di materializzazione non scrive le sue prime righe, operazione che può avvenire diversi minuti dopo che databricks bundle deploy restituisce. Per altri modi di interrogare un endpoint, vedi Interroga un endpoint.

Rimuovere una Feature View dalla FeatureSpec

Qualsiasi modifica a una FeatureSpec la elimina e la ricrea. Un endpoint in esecuzione continua a fornire le funzionalità con cui FeatureSpec è stato creato, quindi una modifica che mantiene il nome della specifica non influisce sull'endpoint. Vedi Aggiornare le dipendenze di un endpoint live di Feature Serving.

Per vedere questo, rimuovi amount_sum_90m dalla specifica e mantieni il suo nome:

YAML

   feature_specs:
     event_features:
       name: ${var.catalog}.${var.schema}.event_features
       features:
         - declarative_feature:
             feature: ${resources.features.events_90m.full_name}
-        - declarative_feature:
-            feature: ${resources.features.amount_sum_90m.full_name}
       lifecycle:

Python

         features=[
             Features(
                 declarative_feature=DeclarativeFeature(
                     feature='${resources.features.events_90m.full_name}'
                 )
             ),
-            Features(
-                declarative_feature=DeclarativeFeature(
-                    feature='${resources.features.amount_sum_90m.full_name}'
-                )
-            ),
         ],

databricks bundle plan segnala solo la ricreazione della specifica:

recreate feature_specs.event_features

Plan: 1 to add, 0 to change, 1 to delete, 4 unchanged

databricks bundle deploy chiede conferma prima di ricreare la specifica:

Uploading bundle files to /Workspace/Users/someone@example.com/.bundle/feature-serving-quickstart/default/files...

This action will result in the deletion or recreation of the following feature specs.
Grants on them that are not declared in the bundle are lost:
  recreate resources.feature_specs.event_features

Would you like to proceed? [y/N]: y
Recreated feature_specs.event_features
Files: 1 uploaded, 0 deleted
Resources: 1 created, 0 changed, 1 deleted, 4 unchanged

L'endpoint restituisce comunque entrambe le feature:

databricks serving-endpoints query event-features --json '{"dataframe_records": [{"key": 1188}, {"key": 42}]}'
{
  "outputs": [
    {
      "events_90m": 16,
      "amount_sum_90m": 20
    },
    {
      "events_90m": 12,
      "amount_sum_90m": 11
    }
  ]
}

Rinomina la FeatureSpec

Per cambiare ciò che l'endpoint serve, assegna al FeatureSpec un nuovo nome. Gli endpoint entity_name fanno riferimento al nome, quindi la distribuzione aggiorna anche l'endpoint, e l'endpoint continua a rispondere alle richieste con le funzionalità presenti nell'originale FeatureSpec fino al completamento dell'aggiornamento.

YAML

   feature_specs:
     event_features:
-      name: ${var.catalog}.${var.schema}.event_features
+      name: ${var.catalog}.${var.schema}.event_features_v2

Python

     FeatureSpec(
-        name='${var.catalog}.${var.schema}.event_features',
+        name='${var.catalog}.${var.schema}.event_features_v2',

databricks bundle plan segnala la ricreazione della specifica e un aggiornamento dell'endpoint:

recreate feature_specs.event_features
update model_serving_endpoints.event_endpoint

Plan: 1 to add, 1 to change, 1 to delete, 3 unchanged

databricks bundle deploy chiede conferma, ricrea la specifica e ritorna quando l'endpoint è stato aggiornato:

Uploading bundle files to /Workspace/Users/someone@example.com/.bundle/feature-serving-quickstart/default/files...

This action will result in the deletion or recreation of the following feature specs.
Grants on them that are not declared in the bundle are lost:
  recreate resources.feature_specs.event_features

Would you like to proceed? [y/N]: y
Recreated feature_specs.event_features
Updated model_serving_endpoints.event_endpoint
Files: 1 uploaded, 0 deleted
Resources: 1 created, 1 changed, 1 deleted, 3 unchanged

L'endpoint ora restituisce solo events_90m:

databricks serving-endpoints query event-features --json '{"dataframe_records": [{"key": 1188}]}'
{
  "outputs": [
    {
      "events_90m": 68
    }
  ]
}

Pulizia

La pipeline di materializzazione continua a funzionare e l'endpoint continua a rispondere finché non li elimini. Smonta il bundle quando hai finito:

databricks bundle destroy

databricks bundle destroy Elenca cosa cancella e chiede conferma:

The following resources will be deleted:
  delete resources.feature_specs.event_features
  delete resources.features.amount_sum_90m
  delete resources.features.events_90m
  delete resources.materialization_sets.serving_online
  delete resources.model_serving_endpoints.event_endpoint

This action will result in the deletion of the following Feature Views.
Deleting a Feature View that a FeatureSpec serves is not blocked, and leaves the FeatureSpec stale:
  delete resources.features.amount_sum_90m
  delete resources.features.events_90m

This action will result in the deletion of the following feature specs.
Feature Serving endpoints and training code that use them can no longer load them:
  delete resources.feature_specs.event_features

All files and directories at the following location will be deleted: /Workspace/Users/someone@example.com/.bundle/feature-serving-quickstart/default

Would you like to proceed? [y/N]: y
Destroy: 5 deleted

Solo l'utente che ha creato una funzionalità materializzata può eliminarla, quindi esegui databricks bundle destroy con la stessa identità che ha distribuito il bundle. Vedete delete_materialized_feature().

Limitations

  • Quando una Feature View viene materializzata in modalità batch, la sua tabella online esiste solo dopo la prima esecuzione del set di materializzazione, quindi un endpoint distribuito/pubblicato all’interno dello stesso databricks bundle deploy non riesce. Esegui databricks bundle deploy di nuovo dopo la prima esecuzione.
  • L'eliminazione di una vista Feature servita da FeatureSpec non viene bloccata e lascia FeatureSpec obsoleto.

Passaggi successivi