Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Les tables de caractéristiques peuvent être fournies de deux manières :
- Déploiement de modèle : déployez un modèle entraîné sur des tables de fonctionnalités. Le même point de terminaison est utilisé à la fois pour la recherche de fonctionnalités et l’inférence de modèles. Le point de terminaison recherche ou calcule automatiquement les valeurs des caractéristiques, en utilisant la lignée suivie lors de l’enregistrement du modèle. Utilisez ceci pour fournir les prédictions du modèle.
-
Feature Serving : Déployez un
FeatureSpecqui fait directement référence aux tables de fonctionnalités, sans modèle. Le point de terminaison renvoie les résultats des fonctionnalités demandées. Utilisez-le lorsqu’une application a besoin de valeurs de fonctionnalités plutôt que de prédictions de modèle. Si, à terme, vous utilisez des fonctionnalités pour l’inférence de modèles, Databricks recommande d’utiliser directement le model serving.
Les deux approches prennent en charge les fonctionnalités précalculées et à la demande.
Conditions requises
- Databricks Runtime 14.2 ML ou version ultérieure.
- Pour utiliser l’API Python, Feature Service nécessite
databricks-feature-engineeringversion 0.1.2 ou ultérieure, qui est intégrée à 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 redémarrer le noyau Python en exécutant cette commande dans une nouvelle cellule :dbutils.library.restartPython(). - Pour utiliser le kit de développement logiciel (SDK) Databricks, Feature Serving nécessite
databricks-sdkversion 0.18.0 ou ultérieure. Installez manuellement la version requise à l’aide de%pip install databricks-sdk>=0.18.0. Si vous utilisez un notebook Databricks, vous devez redémarrer le noyau Python en exécutant cette commande dans une nouvelle cellule :dbutils.library.restartPython().
Databricks Feature Serving fournit une IU et plusieurs options programmatiques pour créer, mettre à jour, interroger et supprimer des points de terminaison. Cet article comprend des instructions pour chacune des options suivantes :
- IU Databricks
- API REST
- API Python
- Kit de développement logiciel (SDK) Databricks
Pour utiliser l’API REST ou le kit de développement logiciel (SDK) des déploiements MLflow, vous devez disposer d’un jeton d’API Databricks.
Importante
À titre de bonne pratique de sécurité pour les scénarios de production, Databricks vous recommande d’utiliser des jetons OAuth machine à machine pour l’authentification en production.
Pour les tests et le développement, Databricks recommande d’utiliser un jeton d’accès personnel appartenant à des principaux de service, et non à des utilisateurs de l’espace de travail. Pour créer des jetons d’accès pour des principaux de service, consultez Gérer les jetons pour un principal de service.
Authentification pour Feature Serving
Pour plus d’informations sur l’authentification, consultez Autoriser l’accès aux ressources Azure Databricks.
Créez une classe FeatureSpec
Un FeatureSpec est un ensemble de fonctionnalités et fonctions défini par l’utilisateur. Vous pouvez combiner des fonctionnalités et des fonctions dans un FeatureSpec. Les FeatureSpecs sont stockés dans Unity Catalog et et gérés par ce dernier et s’affichent dans Catalog Explorer.
Les tables spécifiées dans un FeatureSpec doivent être publiées dans un magasin de fonctionnalités en ligne ou un magasin en ligne tiers. Consultez les magasins de fonctionnalités Databricks Online.
Vous devez créer un databricks-feature-engineering à l’aide du package FeatureSpec.
Tout d’abord, définissez la fonction :
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
)
Vous pouvez ensuite utiliser la fonction dans un 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,
)
Spécifier les valeurs par défaut
Pour spécifier des valeurs par défaut pour les fonctionnalités, utilisez le default_values paramètre dans le FeatureLookup. Consultez l’exemple suivant :
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 caractéristiques sont renommées à l’aide du rename_outputs paramètre, default_values doivent utiliser les noms de fonctionnalités renommés.
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 paquets Python, déclarez-les lorsque vous créez le FeatureSpecfichier . Le extra_pip_requirements paramètre nécessite databricks-feature-engineering la version 0.17.0 ou supérieure. Feature Serving installe automatiquement les paquets MLflow et databricks-feature-lookup.
Par exemple, si un UDF dans votre spécification de fonctionnalité importe NumPy, ajoutez l’exigence à la spécification :
fe.create_feature_spec(
name="main.default.customer_features_with_dependencies",
features=features,
extra_pip_requirements=["numpy==1.26.4"],
)
Utilisez-le main.default.customer_features_with_dependencies comme nom de la spécification lorsque vous créez le point de terminaison.
Chaque entrée dans extra_pip_requirements doit être une chaîne d’exigences PyPI, comme numpy==1.26.4, ou un chemin vers un .whl fichier dans un volume du catalogue Unity. Par exemple, utilisez /Volumes/main/libraries/wheels/custom_features-1.0.0-py3-none-any.whl pour une roue que vous avez téléchargée. Le créateur de terminaison doit avoir READ VOLUME sur le volume et USE SCHEMAUSE CATALOG sur son catalogue parent et son schéma.
Pour les paquets provenant d’un dépôt privé, configurez le dépôt de paquets par défaut de l’espace de travail. Ne mettez pas d’options de commande pip, telles que --index-url, dans extra_pip_requirements.
Les dépendances dans une ENVIRONMENT clause UDF du catalogue Unity s’appliquent à l’exécution SQL hors ligne. Le service de fonctionnalités ne les copie pas automatiquement. Déclarez tous les packages nécessaires aux UDF, y compris celles des fonctionnalités en amont, dans les exigences de la spécification de la fonctionnalité.
Si le déploiement de l’endpoint échoue, consultez les journaux de compilation afin d’identifier les erreurs d’installation de paquets, les conflits de versions ou les échecs d’accès aux fichiers wheel. Consultez Surveiller la qualité du modèle et l’intégrité du point de terminaison.
Pour un exemple avec CustomUDF et FeatureViewSource, voir Servir les caractéristiques CustomUDF et leurs dépendances. Pour les dépendances de service de modèles, voir Dépendances UDF personnalisées.
Créer un point de terminaison
Le FeatureSpec définit le point de terminaison. Pour plus d’informations, consultez Create custom model service endpoints, la documentation de l’API Python ou la documentation Databricks SDK pour plus d’informations.
Remarque
Pour les charges de travail sensibles à la latence ou nécessitant des requêtes élevées par seconde, Model Service offre une optimisation de routage sur des points de terminaison de service de modèle personnalisés, consultez Optimisation de l’itinéraire sur les points de terminaison de service.
Kit de développement logiciel (SDK) Databricks - 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"
)
]
)
)
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,
)
)
)
API REST
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
}
]
}'
Pour afficher le point de terminaison, cliquez sur Mise en service dans la barre latérale gauche de l’IU Databricks. Lorsque l’état est Prêt, le point de terminaison est prêt à répondre aux requêtes. Pour en savoir plus sur le service de modèle, consultez Service de modèle.
Enregistrer le DataFrame augmenté dans la table d’inférence
Pour les points de terminaison créés à partir de février 2025, vous pouvez configurer le modèle servant le point de terminaison 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 le paramétrage de cette configuration, consultez DataFrames de recherche de fonctionnalités de journal des tables d’inférence.
Pour plus d’informations sur les tables d’inférence, voir Journaliser les requêtes et les réponses pour les points de terminaison de service (ancienne version).
Obtenir un point de terminaison
Vous pouvez utiliser le Kit de développement logiciel (SDK) Databricks ou l’API Python pour obtenir les métadonnées et l’état d’un point de terminaison.
Kit de développement logiciel (SDK) Databricks - Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()
endpoint = workspace.serving_endpoints.get(name="customer-features")
# print(endpoint)
API Python
endpoint = fe.get_feature_serving_endpoint(name="customer-features")
# print(endpoint)
Obtenir le schéma d’un point de terminaison
Vous pouvez utiliser le Kit de développement logiciel (SDK) Databricks ou l’API REST pour obtenir le schéma d’un point de terminaison. Pour en savoir plus sur le schéma de point de terminaison, consultez Obtenir un schéma de point de terminaison de mise en service de modèles.
Kit de développement logiciel (SDK) Databricks - Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()
# Create endpoint
endpoint = workspace.serving_endpoints.get_open_api(name="customer-features")
API REST
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"
Interroger un point de terminaison
Vous pouvez interroger un point de terminaison à l’aide de l’API REST, du kit de développement logiciel (SDK) de déploiements MLflow ou l’IU de mise en service.
Le code suivant montre comment configurer des informations d’identification et créer le client en cas d’utilisation du kit de développement logiciel (SDK) de déploiements MLflow.
# Set up credentials
export DATABRICKS_HOST=...
export DATABRICKS_TOKEN=...
# Set up the client
import mlflow.deployments
client = mlflow.deployments.get_deploy_client("databricks")
Remarque
En guise de bonne pratique de sécurité, quand vous vous authentifiez avec des outils, systèmes, scripts et applications automatisés, Databricks recommande d’utiliser des jetons d’accès personnels appartenant à des principaux de service et non des utilisateurs de l’espace de travail. Pour créer des jetons d’accès pour des principaux de service, consultez Gérer les jetons pour un principal de service.
Interroger un point de terminaison à l’aide d’API
Cette section inclut des exemples d’interrogation d’un point de terminaison à l’aide de l’API REST ou du kit de développement logiciel (SDK) de déploiements MLflow.
Kit de développement logiciel (SDK) de déploiements MLflow
Importante
L’exemple suivant utilise l’API predict() à partir du kit de développement logiciel (SDK) de déploiements MLflow. Cette API est expérimentale et sa définition est susceptible de changer.
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},
]
},
)
API REST
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}
]}'
Interroger un point de terminaison à l’aide de l’IU
Vous pouvez interroger un point de terminaison de mise en service directement à partir de l’IU de mise en service. L’IU inclut des exemples de code générés vous permettant d’interroger le point de terminaison.
Dans la barre latérale gauche de l’espace de travail Azure Databricks, cliquez sur Serving.
Cliquez sur le point de terminaison à interroger.
En haut de l’écran à droite, cliquez sur Interroger le point de terminaison.
Dans la zone Requête, saisissez le corps de la requête au format JSON.
Cliquez sur Envoyer la demande.
// Example of a request body.
{
"dataframe_records": [
{ "user_id": 1, "ytd_spend": 598 },
{ "user_id": 2, "ytd_spend": 280 }
]
}
La boîte de dialogue du point de terminaison Query comprend du code d'exemple généré en curl, Python et SQL. Cliquez sur les onglets pour afficher et copier l’exemple de code.
Pour copier le code, cliquez sur l’icône de copie en haut de la zone de texte à droite.
Mettre à jour un point de terminaison
Importante
Pour modifier la configuration d’un point de terminaison Feature Serving (par exemple, changer la taille de la charge de travail ou le FeatureSpec), utilisez toujours les API de mise à jour décrites dans cette section. Ne supprimez pas et recréez le point de terminaison pour appliquer des modifications. La suppression d’un point de terminaison en direct entraîne un temps d’arrêt immédiat et interrompt toutes les applications qui l’interrogent.
Vous pouvez mettre à jour un point de terminaison à l’aide de l’API REST, du kit de développement logiciel (SDK) Databricks ou de l’IU de mise en service.
Mettre à jour un point de terminaison à l’aide d’API
Kit de développement logiciel (SDK) Databricks - 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"
)
]
)
API REST
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
}
]'
Mettre à jour un point de terminaison à l’aide de l’IU
Pour utiliser l’IU de mise en service, procédez comme suit :
- Dans la barre latérale gauche de l’espace de travail Azure Databricks, cliquez sur Serving.
- Dans la table, cliquez sur le nom du point de terminaison à mettre à jour. L’écran du point de terminaison s’affiche alors.
- En haut de l’écran à droite, cliquez sur Modifier le point de terminaison.
- Dans la boîte de dialogue Modifier le point de terminaison de mise en service, modifiez les paramètres du point de terminaison si nécessaire.
- Cliquez sur Mettre à jour pour enregistrer vos modifications.
Mettre à jour les dépendances d’un point de terminaison Feature Serving actif
Un point de terminaison Feature Serving résout ses dépendances lors de sa création et de son déploiement : les privilèges dont son principal de service a besoin pour lire la table en ligne (USE CATALOG, SELECT et EXECUTE), ainsi que FeatureSpec sur l’UDF du catalogue Unity décrit dans son USE SCHEMA. Le point de terminaison fixe ces autorisations au moment de la compilation et ne les résout pas lors d’un simple redéploiement ou redémarrage. Si vous recréez la table online ou la fonction définie par l’utilisateur (UDF), le point de terminaison perd l’autorisation d’y accéder. Si vous mettez à jour la UDF en place, l’endpoint continue d’exécuter la version originale. Les résolutions de features peuvent échouer, ou utiliser silencieusement l’ancienne logique UDF, même lorsque le point de terminaison continue de signaler Prêt.
Pour les tables en ligne et les UDF à la demande, Databricks recommande une migration versionnée : créer une nouvelle version de la dépendance, créer un nouveau point de terminaison avec celle-ci, et migrer le trafic vers le nouveau point de terminaison. Cela vous aide à éviter les temps d’arrêt et les modes de défaillance décrits dans cette section.
Recréer un tableau en ligne
Avertissement
Ne supprimez pas et ne recréez pas une table en ligne en place sous un endpoint Feature Serving actif.
Lorsque vous créez un point de terminaison, Model Serving accorde au principal de service du point de terminaison USE CATALOG sur le catalogue de la table en ligne, USE SCHEMA sur son schéma et SELECT sur la table en ligne. Supprimer et recréer la table, même avec le même nom, crée un nouvel objet sécurisable dans Unity Catalog, donc l’SELECT autorisation n’est pas conservée. Le principal de service perd l’accès à la table, la génération de jetons OAuth échoue, et la connexion à la boutique en ligne retombe en authentification par mot de passe et échoue. Les recherches de caractéristiques échouent alors avec des erreurs telles que KeyError: 'OAUTH_TOKEN' ou password authentication failed.
Ces échecs passent facilement inaperçus : le point de terminaison affiche toujours Prêt et le pipeline de synchronisation affiche toujours les exécutions réussies, tandis que les recherches échouent. Changer le mode de synchronisation d’une table en ligne (par exemple, entre CONTINUOUS et SNAPSHOT) ne peut pas être fait sur place et nécessite de recréer la table, ce qui peut aussi déclencher ce problème.
Un endpoint ne lit pas une table en ligne spécifique. Il recherche les caractéristiques via la table de caractéristiques hors ligne nommée dans son FeatureSpec, et lorsqu’une table de caractéristiques est publiée sur plusieurs tables en ligne, le point de terminaison utilise la plus ancienne. Publier la même table d’entités sur une seconde table en ligne ne déplace pas un endpoint vers la nouvelle table en ligne. Voir les limites du Feature Store en ligne.
Pour minimiser les temps d’arrêt, versionnez la table des fonctionnalités hors ligne ainsi que la table en ligne :
- Créez une nouvelle table de fonctionnalités hors ligne, et incluez la version dans son nom (par exemple,
customer_features_v2). - Publiez le nouveau tableau des fonctionnalités dans un nouveau tableau en ligne. Voir Publier une table des fonctionnalités.
- Créez un nouveau
FeatureSpecqui utilise la nouvelle table de fonctionnalités, et créez un nouveau point de terminaison Feature Serving qui le sert. - Migrez le trafic vers le nouveau point de terminaison. Une fois que l’ancien point de terminaison ne reçoit plus de trafic, supprimez-le ainsi que sa table en ligne.
Mettre à jour un UDF à la demande
Avertissement
Ne modifiez pas un UDF du catalogue Unity utilisé par un FeatureSpec sur place.
L’UDF à la demande de A FeatureSpec est intégré dans le point de terminaison de service au moment du déploiement. Un simple rafraîchissement ou redéploiement réutilise la même UDF dans cette image de service. Une mise à jour en place de l’UDF sous le même nom ne prend pas effet. Si vous supprimez et recréez l’UDF, le point de terminaison perd également EXECUTE, donc les recherches utilisant l’UDF échouent.
FeatureSpecs et les UDF n’ont pas de champ de version, donc gérer les versions par le nom : créer un nouvel UDF et un nouveau FeatureSpec, créer un nouveau point de terminaison qui utilise le nouveau FeatureSpec, et migrer le trafic vers celui-ci. Voir « Créer un FeatureSpec ».
Voir le calcul de fonctionnalités à la demande.
Récupérer un point de terminaison de service après un changement en place
Si vous avez déjà modifié directement une dépendance, reconstruisez le point de terminaison pour qu’il résolve à nouveau ses dépendances. Créer un nouveau FeatureSpec point de terminaison (ou, pour un point de terminaison de Model Serving, enregistrer une nouvelle version de modèle), et mettre à jour le point de terminaison pour le servir. Modifier ce que le point de terminaison expose reconstruit le point de terminaison, ce qui crée un nouveau principal de service et relance la configuration des autorisations. Aucune de ces méthodes ne reconstruit de manière fiable le point de terminaison : l’arrêter et le redémarrer, simplement redéployer ou modifier une variable d’environnement.
Supprimer un point de terminaison
Avertissement
Cette action est irréversible. La suppression d’un point de terminaison de service de fonctionnalités entraîne un arrêt immédiat des applications qui le sollicitent. Si vous souhaitez modifier la configuration du point de terminaison, utilisez Mettre à jour un point de terminaison au lieu de supprimer et recréer le point de terminaison.
Vous pouvez supprimer un point de terminaison à l’aide de l’API REST, du Kit de développement logiciel (SDK) Databricks, de l’API Python ou de l’interface utilisateur de service.
Supprimer un point de terminaison à l’aide d’API
Kit de développement logiciel (SDK) Databricks - Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()
workspace.serving_endpoints.delete(name="customer-features")
API Python
fe.delete_feature_serving_endpoint(name="customer-features")
API REST
curl -X DELETE -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints/<endpoint_name>
Supprimer un point de terminaison à l’aide de l’IU
Pour supprimer un point de terminaison à l’aide de l’IU de mise en service, procédez comme suit :
- Dans la barre latérale gauche de l’espace de travail Azure Databricks, cliquez sur Serving.
- Dans la table, cliquez sur le nom du point de terminaison à supprimer. L’écran du point de terminaison s’affiche alors.
- En haut à droite de l’écran, cliquez sur l’icône du
, puis sélectionnez Supprimer.
Surveiller l’intégrité d’un point de terminaison
Pour en savoir plus sur les journaux et les mesures disponibles pour les points de terminaison Feature Serving, consultez Surveiller la qualité des modèles et l’intégrité des points de terminaison.
Contrôle d’accès
Pour en savoir plus sur les autorisations des points de terminaison Feature Serving, consultez Gérer les autorisations sur un point de terminaison de mise en service de modèles.
Exemple de notebook
Ce notebook illustre comment utiliser le SDK (Kit de développement logiciel) de Databricks pour créer un point d'accès de diffusion de fonctionnalités à l'aide du magasin de fonctionnalités en ligne de Databricks.