Příklad: Nasazení a dotazování koncového bodu obsluhující funkce

Tento článek ukazuje, jak nasadit a dotazovat se na koncový bod obsluhující funkci v podrobném procesu. Tento článek používá sadu Databricks SDK. Některé kroky je také možné provést pomocí rozhraní REST API nebo uživatelského rozhraní Databricks a zahrnout odkazy na dokumentaci pro tyto metody.

V tomto příkladu máte tabulku měst s jejich umístěním (zeměpisná šířka a délka) a doporučovací aplikace, která bere v úvahu aktuální vzdálenost uživatele od těchto měst. Vzhledem k tomu, že se umístění uživatele neustále mění, musí se vzdálenost mezi uživatelem a každým městem vypočítat v době odvozování. Tento kurz ukazuje, jak provádět tyto výpočty s nízkou latencí pomocí tabulek Databricks Online a obsluhy funkcí Databricks. Úplnou sadu ukázkového kódu najdete v ukázkovém poznámkovém bloku.

Krok 1. Vytvoření zdrojové tabulky

Zdrojová tabulka obsahuje předpočítané hodnoty funkcí a může to být libovolná tabulka Delta v katalogu Unity s primárním klíčem. V tomto příkladu tabulka obsahuje seznam měst s jejich zeměpisnou šířkou a délkou. Primární klíč je destination_id. Ukázková data jsou zobrazená níže.

název	destination_id (pk)	zeměpisná šířka	zeměpisná délka
Nashville, Tennessee	0	36.162663	-86.7816
Honolulu, Havaj	0	21.309885	-157.85814
Las Vegas, Nevada	2	36.171562	-115.1391
New York, New York	3	40.712776	-74.005974

Krok 2. Vytvoření online tabulky

Online tabulka je kopie tabulky Delta určená jen pro čtení, která je optimalizovaná pro online přístup. Další informace viz online tabulky Databricks (starší verze).

Pokud chcete vytvořit online tabulku, můžete použít uživatelské rozhraní Vytvořit online tabulku pomocíuživatelského rozhraní , ROZHRANÍ REST APInebo sady Databricks SDK, jak je znázorněno v následujícím příkladu:

from pprint import pprint
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import *
import mlflow

workspace = WorkspaceClient()

# Create an online table
feature_table_name = f"main.on_demand_demo.location_features"
online_table_name=f"main.on_demand_demo.location_features_online"

spec = OnlineTableSpec(
 primary_key_columns=["destination_id"],
 source_table_full_name = feature_table_name,
 run_triggered=OnlineTableSpecTriggeredSchedulingPolicy.from_dict({'triggered': 'true'}),
 perform_full_copy=True)

# ignore "already exists" error
try:
 online_table_pipeline = workspace.online_tables.create(name=online_table_name, spec=spec)
except Exception as e:
 if "already exists" in str(e):
   pass
 else:
   raise e

pprint(workspace.online_tables.get(online_table_name))

Krok 3. Vytvoření funkce v katalogu Unity

V tomto příkladu funkce vypočítá vzdálenost mezi cílem (jehož umístění se nezmění) a uživatelem (jehož umístění se často mění a není známo do doby odvozování).

# Define the function. This function calculates the distance between two locations.
function_name = f"main.on_demand_demo.distance"

spark.sql(f"""
CREATE OR REPLACE FUNCTION {function_name}(latitude DOUBLE, longitude DOUBLE, user_latitude DOUBLE, user_longitude DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON AS
$$
import math
lat1 = math.radians(latitude)
lon1 = math.radians(longitude)
lat2 = math.radians(user_latitude)
lon2 = math.radians(user_longitude)

# Earth's radius in kilometers
radius = 6371

# Haversine formula
dlat = lat2 - lat1
dlon = lon2 - lon1
a = math.sin(dlat/2)**2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon/2)**2
c = 2 * math.atan2(math.sqrt(a), math.sqrt(1-a))
distance = radius * c

return distance
$$""")

Krok 4. Vytvoření specifikace funkce v katalogu Unity

Specifikace funkce určuje funkce, které koncový bod obsluhuje, a jejich vyhledávací klíče. Určuje také všechny požadované funkce, které se použijí na načtené funkce s jejich vazbami. Podrobnosti najdete v tématu Vytvoření souboru FeatureSpec.

from databricks.feature_engineering import FeatureLookup, FeatureFunction, FeatureEngineeringClient

fe = FeatureEngineeringClient()

features=[
 FeatureLookup(
   table_name=feature_table_name,
   lookup_key="destination_id"
 ),
 FeatureFunction(
   udf_name=function_name,
   output_name="distance",
   input_bindings={
     "latitude": "latitude",
     "longitude": "longitude",
     "user_latitude": "user_latitude",
     "user_longitude": "user_longitude"
   },
 ),
]

feature_spec_name = f"main.on_demand_demo.travel_spec"

# The following code ignores errors raised if a feature_spec with the specified name already exists.
try:
 fe.create_feature_spec(name=feature_spec_name, features=features, exclude_columns=None)
except Exception as e:
 if "already exists" in str(e):
   pass
 else:
   raise e

Krok 5. Vytvoření koncového bodu obsluhy funkcí

K vytvoření koncového bodu obsluhy funkce můžete použít uživatelské rozhraní Vytvořit koncový bod, rozhraní REST API nebo sadu Databricks SDK, jak je znázorněno tady.

Koncový bod obsluhující funkci přebírá feature_spec jako parametr, který jste vytvořili v kroku 4.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

# Create endpoint
endpoint_name = "fse-location"

try:
 status = workspace.serving_endpoints.create_and_wait(
   name=endpoint_name,
   config = EndpointCoreConfigInput(
     served_entities=[
       ServedEntityInput(
         entity_name=feature_spec_name,
         scale_to_zero_enabled=True,
         workload_size="Small"
       )
     ]
   )
 )
 print(status)

# Get the status of the endpoint
status = workspace.serving_endpoints.get(name=endpoint_name)
print(status)

Krok 6. Dotazování koncového bodu obsluhy funkce

Při dotazování koncového bodu zadáte primární klíč a volitelně všechna kontextová data, která funkce používá. V tomto příkladu funkce přebírá jako vstup aktuální umístění uživatele (zeměpisnou šířku a délku). Vzhledem k tomu, že se umístění uživatele neustále mění, musí být funkce poskytována v době odvozování jako kontextová funkce.

Koncový bod můžete také dotazovat pomocí dotazu uživatelského rozhraní na koncový bod pomocí uživatelského rozhraní nebo rozhraní REST API.

Pro zjednodušení tento příklad vypočítá pouze vzdálenost do dvou měst. Realističtější scénář může vypočítat vzdálenost uživatele od jednotlivých umístění v tabulce funkcí a určit města, která se mají doporučit.

import mlflow.deployments

client = mlflow.deployments.get_deploy_client("databricks")
response = client.predict(
   endpoint=endpoint_name,
   inputs={
       "dataframe_records": [
           {"destination_id": 1, "user_latitude": 37, "user_longitude": -122},
           {"destination_id": 2, "user_latitude": 37, "user_longitude": -122},
       ]
   },
)

pprint(response)

Ukázkový poznámkový blok

Úplný obrázek kroků najdete v tomto poznámkovém bloku:

Ukázkový poznámkový blok s ukázkami funkcí s online tabulkami

Získejte notebook

Další informace

Podrobnosti o použití rozhraní Python API pro přípravu funkcí najdete v referenční dokumentaci.