Udostępnianie widoków funkcji za pomocą pakietów automatyzacji deklaratywnej

Important

Ta funkcja jest dostępna w prywatnej wersji zapoznawczej. Aby ją wypróbować, skontaktuj się z osobą kontaktową usługi Azure Databricks.

Deklaratywne Pakiety Automatyzacji (dawniej znane jako Databricks Asset Bundles) umożliwiają programową weryfikację, wdrażanie i uruchamianie zasobów Azure Databricks, takich jak Feature View oraz punkty końcowe, które je obsługują. Zobacz Co to są pakiety automatyzacji deklaratywnej?.

Ten samouczek tworzy pakiet, który deklaruje dwa strumieniowe Feature Views, materializuje je w magazynie online i serwuje przez FeatureSpec i punkt końcowy Feature Serving. Następnie zapytasz endpoint, zmienisz cechy, które obsługuje, i usuniesz wszystko.

Widoki cech i ich materializacja są opisane w Zarządzaj widokami cech za pomocą pakietów automatyzacji deklaratywnej, które szczegółowo je wyjaśnia. Aby zamiast tego utworzyć FeatureSpec i punkt końcowy za pomocą interfejsu API Python, zobacz Widoki funkcji serwowania.

Każdy krok pokazuje konfigurację zarówno w YAML, jak i Python. Wybierz język, a strona dostosuje się do twojego wyboru.

Requirements

Do ukończenia tego samouczka potrzebne są następujące elementy:

Udostępnianie zasobów w pakiecie

Pakiet obsługuje Feature Views za pomocą dwóch typów zasobów:

  • FeatureSpec: funkcja Katalogu Unity, która wymienia cechy do obsługi. Nie posiada wartości cech. Punkt końcowy, który je udostępnia, odczytuje je z tabel online, do których materializowane są widoki cech. Zobacz Serwowanie funkcji za pomocą FeatureSpec, a odniesienie do konfiguracji znajdziesz w feature_spec.
  • Endpoint Feature Serving: endpoint obsługujący modele, który obsługuje FeatureSpec zamiast modelu. Pakiet deklaruje go jako zasób model_serving_endpoints. Informacje referencyjne o konfiguracji znajdziesz w model_serving_endpoint.

Udostępnianie widoków cech z pakietu

Poniższe kroki pozwalają zbudować i wdrożyć pakiet, wysłać zapytanie do punktu końcowego, zmienić to, co jest udostępniane, oraz posprzątać.

Konfigurowanie uwierzytelniania

Najpierw skonfiguruj uwierzytelnianie między narzędziem Databricks CLI na komputerze deweloperskim a obszarem roboczym Azure Databricks. Na tej stronie założono, że chcesz użyć uwierzytelniania użytkownika do komputera (U2M) OAuth i odpowiedniego profilu konfiguracji usługi Azure Databricks o nazwie DEFAULT na potrzeby uwierzytelniania.

Note

Uwierzytelnianie U2M jest odpowiednie do wypróbowania tych kroków w czasie rzeczywistym. W przypadku w pełni zautomatyzowanych przepływów pracy usługa Databricks zaleca zamiast tego użycie uwierzytelniania maszynowego do maszyny OAuth (M2M). Zobacz instrukcje dotyczące konfigurowania uwierzytelniania M2M w temacie Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth.

  1. Użyj Databricks CLI, aby lokalnie zainicjować zarządzanie tokenami OAuth, uruchamiając następujące polecenie dla każdego docelowego obszaru roboczego.

    W poniższym poleceniu zastąp ciąg <workspace-url> adresem URL usługi Azure Databricks dla obszaru roboczego, na przykład https://adb-1234567890123456.7.azuredatabricks.net.

    databricks auth login --host <workspace-url>
    
  2. Interfejs wiersza polecenia usługi Databricks poprosi Cię o zapisanie wprowadzonych informacji jako profil konfiguracji usługi Azure Databricks. Naciśnij Enter , aby zaakceptować sugerowaną nazwę profilu lub wprowadź nazwę nowego lub istniejącego profilu. Każdy istniejący profil o tej samej nazwie zostanie zastąpiony wprowadzonymi informacjami. Profile umożliwiają szybkie przełączanie kontekstu uwierzytelniania między wieloma obszarami roboczymi.

    Aby uzyskać listę wszystkich istniejących profilów, w osobnym terminalu lub wierszu polecenia użyj interfejsu wiersza polecenia usługi Databricks, aby uruchomić polecenie databricks auth profiles. Aby wyświetlić istniejące ustawienia określonego profilu, uruchom polecenie databricks auth env --profile <profile-name>.

  3. W przeglądarce internetowej wykonaj instrukcje na ekranie, aby zalogować się do obszaru roboczego usługi Azure Databricks.

  4. Aby wyświetlić bieżącą wartość tokenu OAuth profilu i zbliżający się znacznik czasu wygaśnięcia tokenu, uruchom jedno z następujących poleceń:

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

    Jeśli masz wiele profilów o tej samej wartości --host, może być konieczne jednoczesne określenie opcji --host i -p, aby pomóc interfejsowi CLI usługi Databricks w znalezieniu prawidłowych informacji pasujących do tokenu OAuth.

Utwórz pakiet

Stwórz pusty katalog dla pakietu, z plikiem databricks.yml w jego korzeniu i katalogiem resources obok.

YAML

Każdy z poniższych kroków dodaje jeden plik pod resources/:

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

databricks.yml zawiera nazwę pakietu, include wpis ładujący każdy plik pod resources/, oraz zmienne, do których odwołują się zasoby:

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

Zasoby zadeklarowane w Pythonie są dostępne tylko poprzez mapowanie python w databricks.yml. Bez niego pakiet waliduje i wdraża się pomyślnie, ale nie zawiera zasobów, więc dodaj go teraz:

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

Utwórz projekt i jego środowisko wirtualne, a następnie dodaj pakiet:

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

Stwórz resources/__init__.py za pomocą funkcji, która nadaje nazwy 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

Deklaruj widoki cech i ich materializację

Oba widoki funkcji odczytują ten sam strumień i agregują według klucza w ciągu ostatnich 90 minut. events_90m zlicza zdarzenia i amount_sum_90m sumuje value.amount. Jeden zestaw materializacji zapisuje do obu magazynów, w tym do sklepu online, w trybie strumieniowym. Aby dowiedzieć się, co oznacza każdy klucz konfiguracyjny, zobacz Krok 4 samouczka Widoki funkcji.

Strumieniowy widok funkcji odwołuje się do kolumny wejściowej jako do ścieżki w rekordzie strumienia, więc zastępuj nazwami używanymi przez schemat Twojego strumienia wszędzie tam, gdzie w przykładach występuje value.*.

YAML

Utwórz 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

Dodaj importy do 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,
)

Następnie dodaj to do ciała 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
                ),
            ),
        ]
    ),
)

Dodaj FeatureSpec

Element FeatureSpec zawiera listę funkcji, które obsługuje punkt końcowy. Każdy wpis w features wymienia jeden Widok cech za pomocą declarative_feature.

FeatureSpec można utworzyć dopiero po tym, jak każdy Widok Cech, który wymienia, zostanie zmaterializowany w sklepie internetowym. Odwołania ${resources.features...} w declarative_feature sprawiają, że specyfikacja zależy od widoków events_90m cech i amount_sum_90m, oraz dodaje lifecycle.depends_on zależność, której żadne odniesienie nie wyraża, od zbioru serving_onlinematerializacji . Pakiet tworzy specyfikację po wszystkich trzech i usuwa ją przed nimi. Zobacz Zasady, które musi spełniać FeatureSpec.

YAML

Utwórz 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

Dodaj importy do resources/__init__.py:

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

Następnie dodaj to do ciała 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')]),
    ),
)

Dodaj punkt końcowy Feature Serving

Punkt końcowy obsługuje FeatureSpec, które entity_name nazywa. Ponieważ entity_name odwołuje się do specyfikacji name, pakiet tworzy punkt końcowy po specyfikacji, jak pokazuje wynik w Deploy , i usuwa go przed specyfikacją. Z scale_to_zero_enabled, punkt końcowy skaluje swoje obliczenia do zera, gdy nie otrzymuje żadnych żądań.

YAML

Utwórz 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

Dodaj importy do resources/__init__.py:

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

Następnie dodaj to do ciała 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

Sprawdź konfigurację, a następnie przejrzyj, co robi wdrożenie:

databricks bundle validate
databricks bundle plan

Podczas pierwszego wdrożenia wszystkie pięć zasobów raportuje 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

Wdróż pakiet w obszarze roboczym:

databricks bundle deploy

Wdrożenie tworzy zasoby w kolejności zależności i zwraca, gdy punkt końcowy jest gotowy, co zajmuje kilka minut:

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

Wykonywanie zapytań względem punktu końcowego

Wyślij klucze do wyszukania jako dataframe_records. Rekord nazywa każdy klucz według ostatniego segmentu ścieżki encji widoku cech, więc value.key staje się key:

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

Odpowiedź zawiera jeden obiekt dla każdego rekordu, w kolejności żądania. Każdy obiekt posiada jedną wartość dla każdego widoku cech, z kluczem będącym nazwą widoku cech, bez katalogu i schematu:

{
  "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
    }
  ]
}

Klucz bez zdarzeń w oknie zwraca 0 dla liczby i null dla sumy, tak jak klucz 10001 does. Każdy klucz zwraca te wartości aż do momentu, gdy potok materializacji zapisze swoje pierwsze wiersze, co może nastąpić kilka minut po tym, jak zwróci wartość databricks bundle deploy. Aby poznać inne sposoby wykonywania zapytania do punktu końcowego, zobacz Wykonywanie zapytania do punktu końcowego.

Usuń Feature View z FeatureSpec

Każda zmiana elementu FeatureSpec usuwa go i tworzy ponownie. Działający endpoint nadal obsługuje cechy z FeatureSpec, na podstawie którego został zbudowany, więc zmiana zachowująca nazwę specyfikacji nie wpływa na endpoint. Zobacz Zaktualizuj zależności aktywnego punktu końcowego Feature Serving.

Aby to zobaczyć, usuń amount_sum_90m ze specyfikacji i zachowaj jej nazwę:

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 zgłasza jedynie ponowne utworzenie specyfikacji:

recreate feature_specs.event_features

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

databricks bundle deploy Prosi o potwierdzenie przed ponownym utworzeniem specyfikacji:

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

Endpoint nadal zwraca oba feature’y:

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
    }
  ]
}

Zmień nazwę FeatureSpec

Aby zmienić to, co udostępnia punkt końcowy, nadaj elementowi FeatureSpec nową nazwę. Endpoint odwołuje entity_name się do nazwy, więc wdrożenie również aktualizuje endpoint, a endpoint odpowiada na żądania z funkcjami z oryginału FeatureSpec aż do zakończenia aktualizacji.

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 Zgłasza ponowne utworzenie specyfikacji oraz aktualizację punktu końcowego:

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 prosi o potwierdzenie, odtwarza specyfikację i wraca, gdy punkt końcowy zostanie zaktualizowany:

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

Punkt końcowy zwraca teraz tylko events_90m:

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

Czyszczenie

Potok materializacji działa dalej, a punkt końcowy nadal obsługuje żądania, aż je usuniesz. Usuń pakiet po skończeniu:

databricks bundle destroy

databricks bundle destroy Wyświetla listę usuwanych treści i prosi o potwierdzenie:

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

Tylko użytkownik, który stworzył zmaterializowaną funkcję, może ją usunąć, więc uruchom databricks bundle destroy ją jako tę samą tożsamość, która wdrożyła pakiet. Zobacz: delete_materialized_feature().

Limitations

  • Gdy widok cech jest materializowany w trybie wsadowym, jego tabela online istnieje dopiero po pierwszym uruchomieniu zestawu materializacji, więc wdrożenie endpointu w tym samym databricks bundle deploy kończy się niepowodzeniem. Uruchom databricks bundle deploy ponownie po pierwszym uruchomieniu.
  • Usunięcie widoku funkcji obsługiwanego przez FeatureSpec nie jest blokowane i pozostawia FeatureSpec nieaktualnym.

Następne kroki