Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 --versionper 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 conFeatureSpece, per il riferimento alla configurazione, feature_spec. -
Feature Serving endpoint: un endpoint di servizio di modello che serve un
FeatureSpecinvece di un modello. Un bundle lo dichiara come una risorsamodel_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.
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 esempiohttps://adb-1234567890123456.7.azuredatabricks.net.databricks auth login --host <workspace-url>Il Databricks CLI richiede di salvare le informazioni immesse come profilo di configurazione di Azure Databricks. Premere
Enterper 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 comandodatabricks auth env --profile <profile-name>.Nel Web browser completare le istruzioni visualizzate per accedere all'area di lavoro Azure Databricks.
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--hoste-pper 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 deploynon riesce. Eseguidatabricks bundle deploydi nuovo dopo la prima esecuzione. - L'eliminazione di una vista Feature servita da
FeatureSpecnon viene bloccata e lasciaFeatureSpecobsoleto.
Passaggi successivi
- Per il riferimento completo alla configurazione, vedi feature_spec e model_serving_endpoint.
- Per concedere ad altri soggetti l'accesso alle funzionalità servite da un endpoint, vedi Autorizzazioni.
- Per monitorare, aggiornare ed eliminare gli endpoint di Feature Serving, consulta Serve feature tables.
- Per modificare le Feature View e la loro materializzazione, vedi Gestire le Feature View utilizzando i Dichiarative Automation Bundles.