Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Esta característica se encuentra en versión preliminar privada. Para probarlo, póngase en contacto con su contacto de Azure Databricks.
Los paquetes de automatización declarativa (anteriormente conocidos como Databricks Asset Bundles) te permiten validar, desplegar y ejecutar programáticamente recursos de Azure Databricks, como Feature Views y los endpoints que las sirven. Consulte ¿Qué son los conjuntos de automatización declarativos?.
Este tutorial crea un paquete que declara dos Feature Views en streaming, las materializa en una tienda online y las sirve a través de un FeatureSpec endpoint de servicio de funcionalidades. Luego consultas el endpoint, cambias qué características sirve y lo desmantelas todo.
Las Vistas de Características y su materialización siguen Administrar Vistas de Características usando Paquetes de Automatización Declarativa, que las explica en detalle. Para crear un FeatureSpec y un endpoint con la API de Python en cambio, consulte Servir vistas de características.
Cada paso muestra la configuración tanto en YAML como en Python. Elige un idioma y la página sigue tu elección.
Requirements
Para completar este tutorial, necesitará lo siguiente:
- Databricks CLI versión 1.26.0 o superior. Ejecute
databricks --versionpara comprobarlo. Consulte Instalación o actualización de la CLI de Databricks. - Un área de trabajo habilitada para el Catálogo de Unity. Vea Requisitos.
- Permiso para crear entidades y materializarlas. Consulte Permisos.
- Permiso para crear un endpoint de servicio de modelo. Consulte Identidad y acceso.
- Una tienda online existente. Consulte Crear una tienda online.
- Un Stream existente. Un Stream no es un recurso de paquete, así que créalo primero y refírelo por nombre en el paquete. Ver Crear un stream.
- Python 3.10 o superior, para declarar los recursos en Python.
Servir recursos en un paquete
Un paquete sirve Feature Views a través de dos tipos de recursos:
-
FeatureSpec: una función del Catálogo de Unity que lista las características a servir. No contiene valores de características. Un endpoint que lo sirve las lee de las tablas en línea en las que se materializan las Feature Views. Consulte Servir variables con unFeatureSpecy, para la referencia de configuración, feature_spec. -
Endpoint de servicio de características: un endpoint de servicio de modelo que sirve una
FeatureSpeccaracterística en lugar de un modelo. Un paquete lo declara como un recursomodel_serving_endpoints. Para la referencia de configuración, consulte model_serving_endpoint.
Publicar Feature Views desde un bundle
Los siguientes pasos consisten en construir y desplegar el paquete, consultar el endpoint, cambiar lo que ofrece y limpiar.
Configuración de la autenticación
Primero, configura la autenticación entre la CLI de Databricks en tu máquina de desarrollo y tu espacio de trabajo de Azure Databricks. En esta página se supone que desea usar la autenticación de usuario a máquina (U2M) de OAuth y un perfil de configuración de Azure Databricks correspondiente denominado DEFAULT para la autenticación.
Note
La autenticación U2M es adecuada para probar estos pasos en tiempo real. Para flujos de trabajo totalmente automatizados, Databricks recomienda usar la autenticación de máquina a máquina (M2M) de OAuth en su lugar. Consulte las instrucciones de configuración de autenticación de M2M en Autorizar acceso de la entidad de servicio a Azure Databricks con OAuth.
Use el CLI de Databricks para iniciar la administración de tokens de OAuth localmente mediante la ejecución del siguiente comando para cada área de trabajo de destino.
En el comando siguiente, reemplace
<workspace-url>por la dirección URL de Azure Databricks por área de trabajo, por ejemplo,https://adb-1234567890123456.7.azuredatabricks.net.databricks auth login --host <workspace-url>La CLI de Databricks le pide que guarde la información que especificó como un perfil de configuración de Azure Databricks. Presione
Enterpara aceptar el nombre del perfil sugerido o escriba el nombre de un perfil nuevo o existente. Cualquier perfil existente con el mismo nombre se sobrescribe con la información que ha introducido. Puede usar perfiles para cambiar rápidamente el contexto de autenticación entre varias áreas de trabajo.Para obtener una lista de los perfiles existentes, en una terminal o una línea de comandos por separado, use la CLI de Databricks para ejecutar el comando
databricks auth profiles. Para ver la configuración existente de un perfil específico, ejecute el comandodatabricks auth env --profile <profile-name>.En el explorador web, complete las instrucciones en pantalla para iniciar sesión en el área de trabajo de Azure Databricks.
Para ver el valor actual del token de OAuth de un perfil y la próxima marca de tiempo de expiración del token, ejecute uno de los siguientes comandos:
databricks auth token --host <workspace-url>databricks auth token -p <profile-name>databricks auth token --host <workspace-url> -p <profile-name>
Si tiene varios perfiles con el mismo valor de
--host, es posible que tenga que especificar las opciones--hosty-ppara ayudar a la CLI de Databricks a encontrar la información correcta del token de OAuth coincidente.
Crea el bundle
Crea un directorio vacío para el paquete, con un databricks.yml archivo en su raíz y un resources directorio al lado.
YAML
Cada uno de los siguientes pasos añade un archivo bajo resources/:
databricks.yml
resources/
streaming_features.yml
feature_spec.yml
serving_endpoint.yml
databricks.yml contiene el nombre del paquete, la include entrada que carga cada archivo bajo resources/, y las variables a las que se refieren los recursos:
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
Los recursos declarados en Python solo se encuentran mediante el python mapeo en databricks.yml. Sin él, el paquete se valida y se despliega con éxito pero no contiene recursos, así que añádelo ahora:
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 el proyecto y su entorno virtual, y añade el paquete:
uv init --bare
uv venv .venv
uv add databricks-bundles
Cree resources/__init__.py con la función que databricks.yml nombra:
from databricks.bundles.core import Bundle, Resources
def load_resources(bundle: Bundle) -> Resources:
resources = Resources()
# The following steps add resources here.
return resources
Declarar las vistas de características y su materialización
Ambas vistas de características leen el mismo flujo y agregan por clave durante los últimos 90 minutos.
events_90m cuenta los eventos y amount_sum_90m suma value.amount. Un conjunto de materialización escribe en ambos en la tienda online en modo streaming. Para saber qué significa cada clave de configuración, consulte el Paso 4 del tutorial de Vistas de características.
Una vista de características en streaming dirige una columna de entrada como ruta al registro del flujo, así que sustituye los nombres que utiliza el esquema de tu flujo donde los ejemplos muestren value.*.
YAML
Creación de 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
Añadir las importaciones 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,
)
Luego añade esto al cuerpo de 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
),
),
]
),
)
Añadir una FeatureSpec
El FeatureSpec enumera las características que ofrece el endpoint. Cada entrada en features nombra una vista de características con declarative_feature.
Una FeatureSpec solo puede crearse después de que cada Vista de Característica que nombra se materialice en una tienda online. Las referencias ${resources.features...} en declarative_feature hacen que la especificación dependa de las Vistas de Características events_90m y amount_sum_90m, y lifecycle.depends_on añade la dependencia que ninguna referencia expresa, en el conjunto de materialización serving_online. El paquete crea la especificación después de que los tres hayan terminado y la elimina antes que ellos. Consulte Reglas que debe cumplir una FeatureSpec.
YAML
Creación de 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
Añadir las importaciones a resources/__init__.py:
from databricks.bundles.feature_specs import (
DeclarativeFeature,
DependsOn,
FeatureSpec,
Features,
Lifecycle,
)
Luego añade esto al cuerpo de 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')]),
),
)
Añadir un endpoint para servir características
El endpoint sirve el/la FeatureSpec que entity_name nombra. Debido a que entity_name hace referencia al name de la especificación, el paquete crea el endpoint después de la especificación, como muestra la salida en Deploy, y lo elimina antes de la especificación. Con scale_to_zero_enabled, el endpoint reduce su capacidad de cómputo a cero cuando no recibe solicitudes.
YAML
Creación de 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
Añadir las importaciones a resources/__init__.py:
from databricks.bundles.model_serving_endpoints import (
EndpointCoreConfigInput,
ModelServingEndpoint,
ServedEntityInput,
)
Luego añade esto al cuerpo de 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
Compruebe la configuración y luego revise qué hace el despliegue:
databricks bundle validate
databricks bundle plan
En un primer despliegue, los cinco recursos informan 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
Despliegue el paquete en el área de trabajo.
databricks bundle deploy
El despliegue crea los recursos en orden de dependencia y finaliza cuando el endpoint está listo, lo que lleva varios minutos:
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
Consulta del punto de conexión
Envía las claves para buscarlas como dataframe_records. Un registro nombra cada clave por el último segmento de la ruta de entidades de la Vista de Características, de modo que value.key se convierte en key:
databricks serving-endpoints query event-features --json '{"dataframe_records": [{"key": 1280}, {"key": 1188}, {"key": 42}, {"key": 10001}]}'
La respuesta contiene un objeto para cada registro, en el orden de la solicitud. Cada objeto contiene un valor para cada Vista de características, identificado por el nombre de la Vista de características sin su catálogo ni esquema:
{
"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 clave sin eventos en la ventana devuelve 0 para el conteo y null para la suma, como hace la clave 10001 . Cada clave devuelve estos valores hasta que la tubería de materialización escribe sus primeras filas, lo que puede ocurrir varios minutos después de que databricks bundle deploy devuelva. Para otras formas de consultar un endpoint, consulte Consultar un endpoint.
Eliminar una Feature View de FeatureSpec
Cualquier cambio en una FeatureSpec la elimina y la vuelve a crear. Un endpoint en ejecución sigue sirviendo las funciones del FeatureSpec que fue creado, por lo que un cambio que conserva el nombre de la especificación no afecta al endpoint. Consulta Actualizar dependencias de un endpoint activo de Feature Serving.
Para ver esto, elimina amount_sum_90m de la especificación y mantén su nombre:
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 Informa únicamente de una recreación de la especificación:
recreate feature_specs.event_features
Plan: 1 to add, 0 to change, 1 to delete, 4 unchanged
databricks bundle deploy pide confirmación antes de recrear la especificación:
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
El endpoint sigue devolviendo ambas funciones:
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
}
]
}
Renombrar la FeatureSpec
Para cambiar lo que sirve el endpoint, dale al FeatureSpec un nombre nuevo. El endpoint entity_name hace referencia al nombre, por lo que el despliegue también actualiza el endpoint, y el endpoint sigue respondiendo solicitudes con las funciones del original FeatureSpec hasta que la actualización se completa.
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 Informa de una recreación de la especificación y una actualización del 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 solicita confirmación, vuelve a crear la especificación y vuelve cuando el endpoint ha sido actualizado:
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
El punto final ahora devuelve solo events_90m:
databricks serving-endpoints query event-features --json '{"dataframe_records": [{"key": 1188}]}'
{
"outputs": [
{
"events_90m": 68
}
]
}
Limpieza
La tubería de materialización sigue funcionando y el endpoint sigue atendiendo solicitudes, hasta que los elimines. Desmonta el bundle cuando termines:
databricks bundle destroy
databricks bundle destroy Enumera lo que elimina y pide confirmación:
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 el usuario que creó una función materializada puede eliminarla, así que ejecuta databricks bundle destroy con la misma identidad que desplegó el paquete. Consulte delete_materialized_feature().
Limitations
- Cuando una Vista de Características se materializa en modo batch, su tabla en línea existe solo después de la primera ejecución del conjunto de materialización, por lo que un endpoint desplegado en el mismo
databricks bundle deployfalla. Corredatabricks bundle deployde nuevo después de la primera ejecución. - Eliminar una vista de característica a la que sirve un
FeatureSpecno está bloqueado y dejaFeatureSpecobsoleto.
Pasos siguientes
- Para la referencia completa de configuración, consulte feature_spec y model_serving_endpoint.
- Para conceder a otras entidades de seguridad acceso a las características que ofrece un endpoint, consulte Permisos.
- Para monitorizar, actualizar y eliminar endpoints de Feature Serving, consulte Servir tablas de funciones.
- Para cambiar las Feature Views y su materialización, consulte Gestionar Feature Views usando Declarative Automation Bundles.