Tabulky funkcí pro obsluhu

Tabulky funkcí lze poskytovat dvěma způsoby:

  • Nasazení modelu: Nasaďte model, který byl trénován na tabulkách příznaků. Stejný endpoint se používá jak pro vyhledávání atributů, tak pro inferenci modelem. Koncový bod automaticky vyhledává nebo počítá hodnoty atributů na základě linie původu sledované při zaznamenání modelu. Použijte toto k poskytování predikcí modelu.
  • Poskytování funkcí: Nasaďte FeatureSpec, který přímo odkazuje na tabulky funkcí, bez modelu. Koncový bod vrací požadované výstupy funkcí. Tuto možnost použijte, když aplikace potřebuje hodnoty funkcí místo předpovědí modelu. Pokud featurey nakonec používáte pro inferenci modelu, Databricks doporučuje používat model serving přímo.

Oba přístupy podporují předpočítané i on-demand funkce.

Požadavky

  • Databricks Runtime 14.2 ML nebo novější
  • Pokud chcete používat rozhraní API Python, služba funkcí vyžaduje databricks-feature-engineering verze 0.1.2 nebo vyšší, která je integrovaná do Databricks Runtime 14.2 ML. Pro starší verze Databricks Runtime ML ručně nainstalujte požadovanou verzi pomocí %pip install databricks-feature-engineering>=0.1.2. Pokud používáte poznámkový blok Databricks, musíte restartovat jádro Python spuštěním tohoto příkazu v nové buňce: dbutils.library.restartPython().
  • Pokud chcete použít sadu Databricks SDK, Feature Serving vyžaduje databricks-sdk verzi 0.18.0 nebo vyšší. Chcete-li ručně nainstalovat požadovanou verzi, použijte %pip install databricks-sdk>=0.18.0. Pokud používáte poznámkový blok Databricks, musíte restartovat jádro Python spuštěním tohoto příkazu v nové buňce: dbutils.library.restartPython().

Služba funkcí Databricks poskytuje uživatelské rozhraní a několik programových možností pro vytváření, aktualizaci, dotazování a odstraňování koncových bodů. Tento článek obsahuje pokyny pro každou z následujících možností:

  • Uživatelské rozhraní Databricks
  • REST API
  • rozhraní API Python
  • Databricks SDK

Pokud chcete použít rozhraní REST API nebo sadu SDK pro nasazení MLflow, musíte mít token rozhraní API Databricks.

Důležité

Jako osvědčený postup zabezpečení pro produkční scénáře doporučuje Databricks používat OAuth tokeny pro stroj-stroj autentizaci pro ověřování v produkčním prostředí.

Pro účely testování a vývoje doporučuje Databricks místo uživatelů pracovního prostoru používat osobní přístupový token patřící instančním objektům . Pokud chcete vytvořit tokeny pro instanční objekty, přečtěte si téma Správa tokenů instančního objektu.

Ověřování pro obsluhu funkcí

Informace o ověřování najdete v tématu Ověření přístupu k prostředkům Azure Databricks.

Vytvořte soubor FeatureSpec

FeatureSpec je uživatelsky definovaná sada vlastností a funkcí. Můžete zkombinovat vlastnosti a funkce v objektu FeatureSpec. FeatureSpecs se ukládají a spravují pomocí katalogu Unity a zobrazují se v Průzkumníku katalogu.

Tabulky zadané v FeatureSpec musí být publikovány v online feature store nebo v online obchodu třetí strany. Podívejte se na úložiště funkcí Databricks Online.

K vytvoření souboru databricks-feature-engineeringje nutné použít FeatureSpec balíček .

Nejprve definujte funkci:

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

CATALOG = "main"
SCHEMA = "default"

def difference(num_1: float, num_2: float) -> float:
  """
  A function that accepts two floating point numbers, subtracts the second one
  from the first, and returns the result as a float.

  Args:
      num_1 (float): The first number.
      num_2 (float): The second number.

  Returns:
      float: The resulting difference of the two input numbers.
  """
  return num_1 - num_2

client.create_python_function(
  func=difference,
  catalog=CATALOG,
  schema=SCHEMA,
  replace=True
)

Pak můžete funkci použít v FeatureSpec:

from databricks.feature_engineering import (
  FeatureFunction,
  FeatureLookup,
  FeatureEngineeringClient,
)

fe = FeatureEngineeringClient()

features = [
  # Lookup column `average_yearly_spend` and `country` from a table in UC by the input `user_id`.
  FeatureLookup(
    table_name="main.default.customer_profile",
    lookup_key="user_id",
    feature_names=["average_yearly_spend", "country"]
  ),
  # Calculate a new feature called `spending_gap` - the difference between `ytd_spend` and `average_yearly_spend`.
  FeatureFunction(
    udf_name="main.default.difference",
    output_name="spending_gap",
    # Bind the function parameter with input from other features or from request.
    # The function calculates num_1 - num_2.
    input_bindings={"num_1": "ytd_spend", "num_2": "average_yearly_spend"},
  ),
]

# Create a `FeatureSpec` with the features defined above.
# The `FeatureSpec` can be accessed in Unity Catalog as a function.
fe.create_feature_spec(
  name="main.default.customer_features",
  features=features,
)

Zadání výchozích hodnot

Chcete-li zadat výchozí hodnoty pro funkce, použijte default_values parametr v souboru FeatureLookup. Podívejte se na následující příklad:

feature_lookups = [
    FeatureLookup(
        table_name="ml.recommender_system.customer_features",
        feature_names=[
            "membership_tier",
            "age",
            "page_views_count_30days",
        ],
        lookup_key="customer_id",
        default_values={
          "age": 18,
          "membership_tier": "bronze"
        },
    ),
]

Pokud se sloupce funkcí přejmenují pomocí parametru rename_outputs , default_values musí používat přejmenované názvy funkcí.

FeatureLookup(
  table_name = 'main.default.table',
  feature_names = ['materialized_feature_value'],
  lookup_key = 'id',
  rename_outputs={"materialized_feature_value": "feature_value"},
  default_values={
    "feature_value": 0
  }
)

Přidat závislosti v Python

Pokud uživatelsky definovaná funkce (UDF) importuje balíčky do Python, deklarujte je při vytváření .FeatureSpec Parametr extra_pip_requirements vyžaduje databricks-feature-engineering verzi 0.17.0 nebo novější. Feature Serving automaticky instaluje balíčky MLflow a databricks-feature-lookup.

Například pokud UDF ve vaší specifikaci funkce importuje NumPy, přidejte požadavek do specifikace:

fe.create_feature_spec(
    name="main.default.customer_features_with_dependencies",
    features=features,
    extra_pip_requirements=["numpy==1.26.4"],
)

Použijte main.default.customer_features_with_dependencies jako název specifikace při vytváření endpointu.

Každý záznam v extra_pip_requirements musí být řetězec požadavku PyPI, například numpy==1.26.4, nebo cesta k souboru .whl ve svazku Unity Catalog. Například použijte /Volumes/main/libraries/wheels/custom_features-1.0.0-py3-none-any.whl pro kolo, které jste nahráli. Tvůrce koncového bodu musí mít READ VOLUME pro svazek a USE CATALOG a USE SCHEMA pro jeho nadřazený katalog a schéma.

Pro balíčky z privátního repozitáře nakonfigurujte výchozí repozitář balíčků v pracovním prostoru. Do extra_pip_requirements nevkládejte volby příkazu pip, například --index-url.

Závislosti v klauzuli ENVIRONMENT funkce UDF v Unity Catalogu platí pro offline spouštění SQL. Feature Serving je automaticky nekopíruje. Deklarujte každý balíček potřebný pro UDF, včetně UDF v upstream funkcích, v požadavcích specifikace funkcí.

Pokud nasazení koncového bodu selže, zkontrolujte protokoly sestavení, zda neobsahují chyby při instalaci balíčků, konflikty verzí nebo chyby přístupu k wheel balíčkům. Viz Monitorování kvality modelu a stavu koncového bodu.

Příklad s CustomUDF a FeatureViewSource naleznete v části Funkce Serve CustomUDF a jejich závislosti. Pro závislosti obsluhující model viz Vlastní UDF závislosti.

Vytvoření koncového bodu

FeatureSpec definuje koncový bod. Další informace najdete v tématu Vytvoření vlastních modelů obsluhujících koncové body dokumentaci k rozhraní API Python nebo dokumentaci k Databricks SDK.

Poznámka:

U úloh, které jsou citlivé na latenci nebo vyžadují vysoké dotazy za sekundu, nabízí služba Model Serving optimalizaci tras u vlastních koncových bodů obsluhy modelů, viz Optimalizace tras pro obsluhu koncových bodů.

Databricks SDK – Python

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

workspace = WorkspaceClient()

# Create endpoint
workspace.serving_endpoints.create(
  name="my-serving-endpoint",
  config = EndpointCoreConfigInput(
    served_entities=[
    ServedEntityInput(
        entity_name="main.default.customer_features",
        scale_to_zero_enabled=True,
        workload_size="Small"
      )
    ]
  )
)

rozhraní API Python

from databricks.feature_engineering.entities.feature_serving_endpoint import (
  ServedEntity,
  EndpointCoreConfig,
)

fe.create_feature_serving_endpoint(
  name="customer-features",
    config=EndpointCoreConfig(
    served_entities=ServedEntity(
      feature_spec_name="main.default.customer_features",
             workload_size="Small",
             scale_to_zero_enabled=True,
             instance_profile_arn=None,
    )
  )
)

REST API

curl -X POST -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints \
    -H 'Content-Type: application/json' \
    -d '"name": "customer-features",
   "config": {
       "served_entities": [
           {
               "entity_name": "main.default.customer_features",
               "workload_size": "Small",
               "scale_to_zero_enabled": true
           }
       ]
   }'

Pokud chcete vidět koncový bod, klikněte na Serving v levém postranním panelu uživatelského rozhraní Databricks. Jakmile je stav Připraveno, koncový bod je připravený reagovat na dotazy. Další informace o poskytování modelu najdete v tématu Obsluha modelů.

Uložení rozšířeného datového rámce v tabulce odvozování

U koncových bodů vytvořených od února 2025 můžete nakonfigurovat model obsluhující koncový bod pro protokolování rozšířeného datového rámce, který obsahuje hodnoty vyhledáných funkcí a návratové hodnoty funkce. Datový rámec je uložen do inferenční tabulky pro nasazený model.

Pokyny k nastavení této konfigurace najdete v tématu vyhledávání datových rámců funkcionality protokolu k inferenčním tabulkám.

Pro informace o inferenčních tabulkách viz Protokolování požadavků a odpovědí pro koncové body pro poskytování (starší verze).

Získání koncového bodu

K získání metadat a stavu koncového bodu můžete použít sadu Databricks SDK nebo rozhraní API Python.

Databricks SDK – Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

endpoint = workspace.serving_endpoints.get(name="customer-features")
# print(endpoint)

rozhraní API Python

endpoint = fe.get_feature_serving_endpoint(name="customer-features")
# print(endpoint)

Získání schématu koncového bodu

K získání schématu koncového bodu můžete použít sadu Databricks SDK nebo rozhraní REST API. Další informace o schématu koncového bodu naleznete v tématu Získání modelu obsluhující schéma koncového bodu.

Databricks SDK – Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

# Create endpoint
endpoint = workspace.serving_endpoints.get_open_api(name="customer-features")

REST API

ACCESS_TOKEN=<token>
ENDPOINT_NAME=<endpoint name>

curl "https://example.databricks.com/api/2.0/serving-endpoints/$ENDPOINT_NAME/openapi" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json"

Proveďte dotaz na koncový bod

K dotazování koncového bodu můžete použít rozhraní REST API, sadu MLflow Deployments SDK nebo obslužné uživatelské rozhraní.

Následující kód ukazuje, jak nastavit přihlašovací údaje a vytvořit klienta při použití sady SDK pro nasazení MLflow.

  # Set up credentials
  export DATABRICKS_HOST=...
  export DATABRICKS_TOKEN=...

  # Set up the client
  import mlflow.deployments

  client = mlflow.deployments.get_deploy_client("databricks")

Poznámka:

Databricks doporučuje jako osvědčený bezpečnostní postup při ověřování pomocí automatizovaných nástrojů, systémů, skriptů a aplikací používat osobní přístupové tokeny, které náleží služebním účtům, namísto uživatelů pracovního prostoru. Pokud chcete vytvořit tokeny pro instanční objekty, přečtěte si téma Správa tokenů instančního objektu.

Dotazování koncového bodu pomocí rozhraní API

Tato část obsahuje příklady dotazování koncového bodu pomocí rozhraní REST API nebo sady SDK pro nasazení MLflow.

Sada SDK pro nasazení MLflow

Důležité

Následující příklad používá predict() API z MLflow Deployments SDK. Toto rozhraní API je experimentální a definice rozhraní API se může změnit.

import mlflow.deployments

client = mlflow.deployments.get_deploy_client("databricks")
response = client.predict(
    endpoint="test-feature-endpoint",
    inputs={
        "dataframe_records": [
            {"user_id": 1, "ytd_spend": 598},
            {"user_id": 2, "ytd_spend": 280},
        ]
    },
)

REST API

curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
  -H 'Content-Type: application/json' \
  -d '{"dataframe_records": [
          {"user_id": 1, "ytd_spend": 598},
          {"user_id": 2, "ytd_spend": 280}
      ]}'

Dotazování koncového bodu pomocí uživatelského rozhraní

Servisní koncový bod můžete přímo dotazovat přes uživatelské rozhraní pro zadávání. Uživatelské rozhraní obsahuje vygenerované příklady kódu, které můžete použít k dotazování koncového bodu.

  1. Na levém bočním panelu pracovního prostoru Azure Databricks klikněte na Serving.

  2. Klikněte na koncový bod, který chcete dotazovat.

  3. V pravém horním rohu obrazovky klikněte na koncový bod dotazu.

    Tlačítko koncového bodu dotazu

  4. Do pole Požadavek zadejte text požadavku ve formátu JSON.

  5. Klikněte na Odeslat požadavek.

// Example of a request body.
{
  "dataframe_records": [
    { "user_id": 1, "ytd_spend": 598 },
    { "user_id": 2, "ytd_spend": 280 }
  ]
}

Dialogové okno Koncový bod Query obsahuje vygenerovaný ukázkový kód v curl, Python a také SQL. Kliknutím na karty zobrazíte a zkopírujete ukázkový kód.

Dialogové okno koncového bodu dotazu

Pokud chcete kód zkopírovat, klikněte v pravém horním rohu textového pole na ikonu kopírování.

Tlačítko kopírovat v dialogovém okně koncového bodu dotazu

Aktualizace koncového bodu

Důležité

Pokud chcete upravit konfiguraci koncového bodu služby funkcí (například velikost úlohy či FeatureSpec), vždy použijte aktualizační rozhraní API popsaná v této části. Nemazejte a nevytvářejte koncový bod znovu, abyste použili změny. Odstranění živého koncového bodu způsobí okamžitý výpadek a přeruší všechny aplikace, které se na něj dotazují.

Koncový bod můžete aktualizovat pomocí rozhraní REST API, sady Databricks SDK nebo uživatelského rozhraní obsluhy.

Aktualizace koncového bodu pomocí rozhraní API

Databricks SDK – Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

workspace.serving_endpoints.update_config(
  name="my-serving-endpoint",
  served_entities=[
    ServedEntityInput(
      entity_name="main.default.customer_features",
      scale_to_zero_enabled=True,
      workload_size="Small"
    )
  ]
)

REST API

curl -X PUT -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints/<endpoint_name>/config \
  -H 'Content-Type: application/json' \
  -d '"served_entities": [
        {
            "name": "customer-features",
            "entity_name": "main.default.customer_features_new",
            "workload_size": "Small",
            "scale_to_zero_enabled": True
        }
    ]'

Aktualizace koncového bodu pomocí uživatelského rozhraní

Při používání uživatelského rozhraní obsluhy postupujte takto:

  1. Na levém bočním panelu pracovního prostoru Azure Databricks klikněte na Serving.
  2. V tabulce klikněte na název koncového bodu, který chcete aktualizovat. Zobrazí se obrazovka koncového bodu.
  3. V pravém horním rohu obrazovky klikněte na Upravit koncový bod.
  4. V dialogovém okně Upravit obsluhující koncový bod upravte nastavení koncového bodu podle potřeby.
  5. Uložte změny kliknutím na Aktualizovat.

aktualizovat koncový bod

Aktualizovat závislosti živého endpointu Feature Serving

Endpoint Feature Serving řeší své závislosti při prvním sestavení a nasazení: oprávnění, která jeho princip služby potřebuje ke čtení online tabulky (USE CATALOG, USE SCHEMA a SELECT), a EXECUTE na Unity Catalog UDF popsaném v jeho FeatureSpec. Endpoint tato oprávnění pevně nastaví při sestavení a neřeší je znovu při běžném opětovném nasazení nebo restartu. Pokud online tabulku nebo UDF znovu vytvoříte, endpoint na ni ztratí oprávnění. Pokud aktualizujete UDF na místě, endpoint bude dál spouštět původní verzi. Vyhledávání feature může selhat nebo tiše použít starou logiku UDF, i když koncový bod stále hlásí Ready.

Pro online tabulky i on-demand UDF Databricks doporučuje verzovanou migraci: vytvořit novou verzi závislosti, vytvořit nový koncový bod nad ní a migrovat provoz na nový endpoint. To vám pomůže vyhnout se výpadkům a poruchám popsaným v této části.

Znovu vytvořte online tabulku

Varování

Nesmažte a nevytvářejte online tabulku přímo na místě pod aktivním koncovým bodem Feature Serving.

Když vytvoříte endpoint, Model Serving uděluje instančnímu objektu služby endpointu USE CATALOG v katalogu online tabulky, USE SCHEMA na jejím schématu a SELECT na online tabulce. Smazání a znovuvytvoření tabulky, i když má stejný název, vytvoří v Unity Catalog nový zabezpečitelný objekt, takže se oprávnění SELECT nepřenese. Instanční objekt služby ztratí přístup k tabulce, mintování tokenů OAuth selže a připojení k online obchodu se vrátí k autentizaci heslem a selže. Vyhledávání funkcí pak selže s chybami jako KeyError: 'OAUTH_TOKEN' nebo password authentication failed.

Tyto chyby lze snadno přehlédnout: endpoint stále hlásí Ready a synchronizační pipeline stále ukazuje úspěšné běhy, zatímco vyhledávání selhávají. Změnu režimu synchronizace online tabulky (například mezi CONTINUOUS a SNAPSHOT) nelze provést přímo a vyžaduje znovuvytvoření tabulky, což může tento problém také spustit.

Endpoint nečte konkrétní online tabulku. Vyhledává feature pomocí offline tabulky feature pojmenované v jejím FeatureSpec, a když je tabulka feature publikována do více než jedné online tabulky, endpoint použije tu nejstarší. Publikování stejné tabulky funkcí do druhé online tabulky nepřesune endpoint do nové online tabulky. Viz omezení Online Feature Store.

Pro minimalizaci prostojů verzujte offline tabulku funkcí i online tabulku:

  1. Vytvořte novou offline tabulku prvků a zahrňte verzi do jejího názvu (například customer_features_v2).
  2. Publikujte novou tabulku funkcí do nové online tabulky. Viz Publikování tabulky funkcí.
  3. Vytvořte novou FeatureSpec tabulku, která používá novou tabulku funkcí, a vytvořte nový endpoint pro Feature Serving, který ji obsluhuje.
  4. Migrujte provoz na nový endpoint. Jakmile starý endpoint přestane přijímat provoz, smažte ho i jeho online tabulku.

Aktualizovat on-demand UDF

Varování

Neměňte přímo UDF z Unity Catalog používanou prvkem FeatureSpec.

On-demand UDF prvku FeatureSpec je zabudován do obsluhovaného koncového bodu při nasazení. Obyčejné obnovení nebo opětovné nasazení používá stejný UDF v tomto image. Aktualizace UDF přímo na místě pod stejným názvem nenabývá účinnosti. Pokud UDF odstraníte a znovu vytvoříte, endpoint na něm také ztratí EXECUTE, takže vyhledávání s UDF selžou.

FeatureSpecs a UDF nemají pole verze, proto verzujte podle názvu: vytvořte nový UDF a nový FeatureSpec, vytvořte nový endpoint, který používá nový FeatureSpec, a migrujte na něj provoz. Viz Vytvořit položku FeatureSpec.

Viz Výpočet feature na vyžádání.

Obnovte koncový bod po změně přímo na místě

Pokud jste už změnili závislost přímo na místě, přetvořte endpoint tak, aby znovu vyřešil své závislosti. Vytvořte nový FeatureSpec (nebo u endpointu Model Serving zaregistrujte novou verzi modelu) a aktualizujte endpoint, aby jej obsluhoval. Změna toho, co endpoint obsluhuje, znovu sestaví endpoint, který zřídí nový instanční objekt služby a znovu spustí nastavení oprávnění. Žádná z těchto možností spolehlivě neobnoví koncový bod: jeho zastavení a spuštění, prosté znovunasazení nebo změna proměnné prostředí.

Odstranění koncového bodu

Varování

Tato akce je nevratná. Odstranění endpointu pro poskytování funkce způsobí okamžitý výpadek pro všechny aplikace, které na něj odesílají dotazy. Pokud chcete změnit konfiguraci koncového bodu, místo odstranění a opětovného vytvoření koncového bodu použijte aktualizaci koncového bodu .

Koncový bod můžete odstranit pomocí rozhraní REST API, sady Databricks SDK, rozhraní API Python nebo uživatelského rozhraní obsluhy.

Odstranění koncového bodu pomocí rozhraní API

Databricks SDK – Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

workspace.serving_endpoints.delete(name="customer-features")

rozhraní API Python

fe.delete_feature_serving_endpoint(name="customer-features")

REST API

curl -X DELETE -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints/<endpoint_name>

Odstranění koncového bodu pomocí uživatelského rozhraní

Pomocí uživatelského rozhraní obsluhy odstraňte koncový bod takto:

  1. Na levém bočním panelu pracovního prostoru Azure Databricks klikněte na Serving.
  2. V tabulce klikněte na název koncového bodu, který chcete odstranit. Zobrazí se obrazovka koncového bodu.
  3. V pravém horním rohu obrazovky klikněte na ikonu nabídky Kebab. a vyberte Odstranit.

odstranění koncového bodu

Monitorování stavu koncového bodu

Informace o protokolech a metrikách dostupných pro koncové body Feature Serving naleznete v části Monitorování kvality modelu a zdravotního stavu koncových bodů.

Řízení přístupu

Informace o oprávněních ke koncovým bodům obsluhy funkcí najdete v tématu Správa oprávnění pro koncový bod obsluhující model.

Příklad poznámkového bloku

Tento poznámkový blok ukazuje, jak pomocí sady Databricks SDK vytvořit koncový bod obsluhy funkcí pomocí úložiště funkcí Databricks Online.

Ukázkový poznámkový blok pro poskytování funkcí s online obchodem

Získejte poznámkový blok

  • Poslední aktualizace v