Aller au contenu principal
Dernière mise à jour le

Servir des tables de fonctionnalités

Feature tables can be served in two ways:

  • Model serving : déployez un modèle qui a été entraîné sur des tables de caractéristiques. Le même endpoint est utilisé à la fois pour la recherche de caractéristiques et pour l’inférence du modèle. L’Endpoint recherche ou compute automatiquement les valeurs des caractéristiques en utilisant la traçabilité enregistrée lors de l’enregistrement du modèle. Utilisez ceci pour servir les prédictions du modèle.
  • Feature Serving : déployez un FeatureSpec qui référence directement des tables de fonctionnalités, sans modèle. L’endpoint renvoie les sorties de fonctionnalités demandées. À utiliser lorsqu’une application a besoin de valeurs de fonctionnalités plutôt que de prédictions de modèle. Si vous utilisez finalement des fonctionnalités pour l’inférence de modèle, Databricks vous recommande d’utiliser directement le service de modèle.

Les deux approches prennent en charge les fonctionnalités précalculées et à la demande.

Exigences​

  • Databricks Runtime 14.2 ML ou version ultérieure.
  • Pour utiliser l'API Python, Feature Serving nécessite databricks-feature-engineering version 0.1.2 ou supérieur, qui est intégré à Databricks Runtime 14.2 ML. Pour les versions antérieures de Databricks Runtime ML, installez manuellement la version requise à l’aide de %pip install databricks-feature-engineering>=0.1.2. Si vous utilisez un notebook Databricks, vous devez ensuite redémarrer le noyau Python en exécutant cette commande dans une nouvelle cellule : dbutils.library.restartPython().
  • Pour utiliser le SDK Databricks, Feature Serving nécessite databricks-sdk version 0.18.0 ou une version ultérieure. Pour installer manuellement la version requise, utilisez %pip install databricks-sdk>=0.18.0. Si vous utilisez un notebook Databricks, vous devez ensuite redémarrer le noyau Python en exécutant cette commande dans une nouvelle cellule : dbutils.library.restartPython().

Databricks Feature Serving offre une interface utilisateur et plusieurs options programmatiques pour créer, mettre à jour, interroger et supprimer des endpoints. Cet article comprend des instructions pour chacune des options suivantes :

  • Interface utilisateur Databricks
  • API REST
  • API Python
  • Databricks SDK

Pour utiliser l’API REST ou le SDK MLflow Deployments, vous devez disposer d’un jeton d’API Databricks.

important

En tant que bonne pratique de sécurité pour les scénarios de production, Databricks vous recommande d'utiliser des jetons OAuth machine à machine pour l'authentification pendant la production.

Pour les tests et le développement, Databricks recommande d'utiliser un jeton d'accès personnel appartenant aux Service Principals au lieu des utilisateurs de Workspace. Pour créer des jetons pour les Service Principals, consultez Gérer les jetons pour un Service Principal.

Authentification pour Feature Serving​

Pour en savoir plus sur l'authentification, consultez Autoriser l'accès aux ressources Databricks.

Créer un FeatureSpec​

Un FeatureSpec est un ensemble de fonctionnalités et de fonctions défini par l'utilisateur. Vous pouvez combiner des fonctionnalités et des fonctions dans un FeatureSpec. FeatureSpecs sont stockés et gérés par Unity Catalog et apparaissent dans l’Explorateur de catalogues.

Les tables spécifiées dans un FeatureSpec doivent être publiées dans un magasin de fonctionnalités en ligne ou dans un magasin en ligne tiers. Consultez les magasins de fonctionnalités en ligne Databricks.

Vous devez utiliser le package databricks-feature-engineering pour créer un FeatureSpec.

Tout d'abord, définissez la fonction :

Python
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
)

Ensuite, vous pouvez utiliser la fonction dans un FeatureSpec:

Python
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,
)

Spécifier les valeurs default​

Pour spécifier les valeurs default des fonctionnalités, utilisez le paramètre default_values dans le FeatureLookup. Voir l'exemple suivant :

Python
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"
        },
    ),
]

Si les colonnes de features sont renommées en utilisant le parameter rename_outputs, default_values doit utiliser les noms de features renommées.

Python
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
  }
)

Ajouter des dépendances Python​

Si une fonction définie par l’utilisateur (UDF) importe des packages Python, déclarez-les lorsque vous créez FeatureSpec. Le paramètre extra_pip_requirements nécessite databricks-feature-engineering version 0,17,0 ou supérieure. Feature Serving installe automatiquement les packages MLflow et databricks-feature-lookup.

Par exemple, si une UDF dans votre spécification de fonctionnalité importe NumPy, ajoutez l'exigence à la spécification :

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

Utilisez main.default.customer_features_with_dependencies comme nom de spécification lorsque vous créez l’endpoint.

Chaque entrée de extra_pip_requirements doit être une chaîne de exigences PyPI, telle que numpy==1.26.4, ou un chemin d'accès vers un fichier .whl dans un volume Unity Catalog. Par exemple, utilisez /Volumes/main/libraries/wheels/custom_features-1.0.0-py3-none-any.whl pour une roue que vous avez upload. Le créateur de l'Endpoint doit disposer de READ VOLUME sur le volume ainsi que de USE CATALOG et USE SCHEMA sur son catalogue et son schéma parents.

Pour les packages provenant d'un repository privé, configurez le dépôt de packages par default du Workspace. N'incluez pas d'options de commande pip, telles que --index-url, dans extra_pip_requirements.

Les dépendances dans la clause ENVIRONMENT d'une UDF Unity Catalog s'appliquent à l'exécution SQL hors ligne. Feature Serving ne les copie pas automatiquement. Déclarez chaque package requis par les UDF, y compris les UDF dans les fonctionnalités amont, dans les exigences de la spécification de fonctionnalité.

Si le déploiement de l'endpoint échoue, inspectez les logs de build pour détecter les erreurs d'installation de package, les conflits de version ou les échecs d'accès aux wheel. Consultez Monitor model quality and endpoint health.

Pour un exemple avec CustomUDF et FeatureViewSource, consultez Servir des fonctionnalités CustomUDF et leurs dépendances. Pour les dépendances du service de modèle, consultez Dépendances UDF personnalisées.

Créer un endpoint​

Le FeatureSpec définit l'Endpoint. Pour plus d'informations, consultez Créer des endpoints de déploiement de modèles personnalisés, la documentation de l'API Python, ou la documentation du SDK Databricks pour plus de détails.

remarque

Pour les charges de travail sensibles à la latence ou nécessitant un nombre élevé de requêtes par seconde, Model Serving offre l'optimisation du routage sur les endpoints de Model Serving personnalisés, consultez Optimisation du routage sur les endpoints de service.

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"
      )
    ]
  )
)

Pour voir l’endpoint, cliquez sur Serving dans la barre latérale gauche de l’interface utilisateur de Databricks. Lorsque l'état est Ready , l'Endpoint est prêt à répondre aux queries. Pour en savoir plus sur Model Serving, consultez Model Serving.

Enregistrer le DataFrame augmenté dans la table d'inférence​

Pour les endpoints créés à partir de février 2025, vous pouvez configurer l'endpoint de déploiement de modèle pour consigner le DataFrame augmenté qui contient les valeurs de fonctionnalité recherchées et les valeurs de retour de fonction. Le DataFrame est enregistré dans la table d'inférence pour le modèle servi.

Pour obtenir des instructions sur la configuration de ceci, consultez Journaliser les DataFrames de recherche de fonctionnalités dans des tables d'inférence.

Pour plus d'information sur les tables d'inférence, consultez Logs les requêtes et les réponses pour les Endpoint de service (hérité).

Obtenir un Endpoint​

Vous pouvez utiliser le Databricks SDK ou l'API Python pour obtenir les métadonnées et le statut d'un Endpoint.

Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

Obtenir le schéma d'un Endpoint​

Vous pouvez utiliser le SDK Databricks ou l'API REST pour obtenir le schéma d'un Endpoint. Pour plus d'informations sur le schéma de l'endpoint, consultez Obtenir un schéma d'endpoint de diffusion de modèle.

Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

Query un Endpoint​

Vous pouvez utiliser l'API REST, le SDK de déploiement MLflow ou l'interface utilisateur de Serving pour interroger un endpoint.

Le code suivant montre comment configurer les identifiants et créer le client lors de l'utilisation du SDK de déploiement MLflow.

  # Set up credentials
  export DATABRICKS_HOST=...
  export DATABRICKS_TOKEN=...
Python
  # Set up the client
  import mlflow.deployments

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

En tant que bonne pratique de sécurité lorsque vous vous authentifiez avec des outils, des systèmes, des scripts et des applications automatisés, Databricks vous recommande d'utiliser des jetons OAuth.

Si vous utilisez l'authentification par jeton d'accès personnel, Databricks recommande d'utiliser des jetons d'accès personnels appartenant aux Service Principal plutôt qu'aux utilisateurs du Workspace. Pour créer des jetons pour les Service Principals, consultez Gérer les jetons pour un Service Principal.

Interroger un Endpoint à l'aide des APIs​

Cette section comprend des exemples d'interrogation d'un Endpoint à l'aide de l'API REST ou du SDK de déploiements MLflow.

important

L'exemple suivant utilise predict() l'API du SDK MLflow Deployments. Cette API est Expérimentale et la définition de l'API peut changer.

Python
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},
        ]
    },
)

Interroger un Endpoint à l'aide de l'interface utilisateur​

Vous pouvez interroger un endpoint de service directement depuis l’interface utilisateur de mise en service. L’interface utilisateur comprend des exemples de code généré que vous pouvez utiliser pour interroger l’endpoint.

  1. Dans la barre latérale gauche du workspace Databricks, cliquez sur **Serving**.

  2. Cliquez sur l'Endpoint que vous souhaitez query.

  3. Dans le coin supérieur droit de l'écran, cliquez sur Endpoint de requête .

    bouton d'Endpoint de query

  4. Dans le champ Requête , saisissez le corps de la requête au format JSON.

  5. Cliquez sur Envoyer la demande .

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

La boîte de dialogue Query endpoint inclut du code d'exemple généré en curl, Python et SQL. Cliquez sur les tab pour afficher et copier le code d'exemple.

dialogue d'Endpoint de query

Pour copier le code, cliquez sur l'icône de copie en haut à droite de la zone de texte.

Bouton Copier dans la boîte de dialogue de l'Endpoint de query.

Mettre à jour un Endpoint​

important

Pour modifier la configuration d'un Endpoint Feature Serving (tel que le changement du FeatureSpec ou de la taille de la charge de travail), utilisez toujours les APIs de mise à jour décrites dans cette section. Ne supprimez pas et ne recréez pas l'endpoint pour appliquer les modifications. La suppression d'un Endpoint en production entraîne un temps d'arrêt immédiat et interrompt toutes les applications qui le query.

Vous pouvez mettre à jour un Endpoint à l'aide de l'API REST, du Databricks SDK ou de l'interface utilisateur de Serving.

Mettre à jour un Endpoint à l'aide des APIs​

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"
    )
  ]
)

Mettre à jour un endpoint à l'aide de l'UI​

Suivez ces étapes pour utiliser l'interface utilisateur de Serving :

  1. Dans la barre latérale gauche du workspace Databricks, cliquez sur **Serving**.
  2. Dans le tableau, cliquez sur le nom de l'Endpoint que vous souhaitez mettre à jour. L'écran de l'Endpoint apparaît.
  3. Dans le coin supérieur droit de l’écran, cliquez sur Modifier l’endpoint .
  4. Dans la boîte de dialogue **Modifier l'endpoint de déploiement**, modifiez les paramètres de l'endpoint selon les besoins.
  5. Cliquez sur Mettre à jour pour enregistrer vos modifications.

mettre à jour un Endpoint

Supprimer un endpoint​

attention

Cette action est irréversible. La suppression d'un endpoint Feature Serving entraîne une indisponibilité immédiate pour toute application l'interrogeant. Si vous souhaitez modifier la configuration de l'endpoint, utilisez Mettre à jour un endpoint au lieu de supprimer et recréer l'endpoint.

Vous pouvez supprimer un Endpoint en utilisant l'API REST, le SDK Databricks, l'API Python ou l'interface utilisateur de Serving.

Supprimer un endpoint à l'aide d'APIs​

Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

Supprimer un endpoint via l'interface utilisateur​

Suivez ces étapes pour supprimer un Endpoint à l'aide de l'interface utilisateur de service :

  1. Dans la barre latérale gauche du workspace Databricks, cliquez sur **Serving**.
  2. Dans le tableau, cliquez sur le nom de l’Endpoint que vous souhaitez supprimer. L'écran de l'Endpoint apparaît.
  3. Dans le coin supérieur droit de l'écran, cliquez sur le menu kebab Icône du menu kebab. et sélectionnez Supprimer .

supprimer un endpoint

Surveiller l'état de santé d'un Endpoint​

Pour plus d'informations sur les Logs et les métriques disponibles pour les Endpoint Feature Serving, consultez Surveiller la qualité du modèle et la santé des Endpoint.

Contrôle d'accès​

Pour plus d'informations sur les autorisations sur les Endpoint Feature Serving, voir Gérer les autorisations sur un Endpoint de déploiement de modèle.

Exemple de Notebook​

Ce Notebook illustre comment utiliser le SDK Databricks pour créer un Endpoint Feature Serving à l'aide du Magasin de fonctionnalités en ligne Databricks.

Notebook d'exemple de Feature Serving avec magasin en ligne.

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks
Sur cette page