Servir vistas de características usando paquetes de automatización declarativa

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 --version para 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 un FeatureSpec y, para la referencia de configuración, feature_spec.
  • Endpoint de servicio de características: un endpoint de servicio de modelo que sirve una FeatureSpec característica en lugar de un modelo. Un paquete lo declara como un recurso model_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.

  1. 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>
    
  2. La CLI de Databricks le pide que guarde la información que especificó como un perfil de configuración de Azure Databricks. Presione Enter para 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 comando databricks auth env --profile <profile-name>.

  3. En el explorador web, complete las instrucciones en pantalla para iniciar sesión en el área de trabajo de Azure Databricks.

  4. 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 --host y -p para 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 deploy falla. Corre databricks bundle deploy de nuevo después de la primera ejecución.
  • Eliminar una vista de característica a la que sirve un FeatureSpec no está bloqueado y deja FeatureSpec obsoleto.

Pasos siguientes