Créer des Endpoint de service de modèle personnalisés

Cet article décrit comment créer des endpoints de Model Serving qui servent des modèles personnalisés à l'aide de Databricks Model Serving.

Model Serving propose les options suivantes pour la création d'endpoints de service :

• L'Interface utilisateur de déploiement
• API REST
• SDK de déploiements MLflow

Pour créer des Endpoint qui servent des modèles d'IA générative, consultez Créer des Endpoint de service de modèle de fondation.

Exigences

• Votre workspace doit se trouver dans une région prise en charge.
• Si vous utilisez des bibliothèques personnalisées ou des bibliothèques d'un serveur miroir privé avec votre modèle, consultez Utiliser des bibliothèques Python personnalisées avec Model Serving avant de créer l'endpoint du modèle.
• Pour créer des endpoints à l'aide du SDK MLflow Deployments, vous devez installer le client MLflow Deployment. Pour l'installer, exécutez :

Python

import mlflow.deployments

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

Identité et accès

Pour créer ou mettre à jour un endpoint de service de modèle, l'appelant et le créateur enregistré de l'endpoint doivent tous deux :

• Soyez membre du workspace.
• Détenez le droit workspace-access.

Identité du créateur

Lorsque vous créez un Endpoint, Databricks enregistre l'identité de l'appelant en tant que créateur de l'Endpoint. Cette identité — généralement un Service Principal — est utilisée pour accéder aux Ressources Unity Catalog au nom de l'Endpoint et ne peut pas être modifiée après la création.

Si le créateur enregistré ne dispose pas des autorisations Unity Catalog requises ou a été supprimé du workspace, vous devez supprimer l'endpoint et le recréer sous un service principal qui dispose des autorisations requises et est un membre actuel du workspace.

Les mises à jour de la configuration et des entités servies réévaluent l'appartenance au workspace du créateur enregistré et les autorisations. Les mises à jour échouent avec PERMISSION_DENIED si le créateur enregistré n'est plus un membre du workspace, même lorsque l'appelant dispose d'autorisations valides.

Autorisations d'entités servies

Le créateur enregistré doit détenir les autorisations suivantes sur chaque entité servie. Les autorisations validées lors de la création ou de la mise à jour de l'Endpoint entraînent l'échec de la requête avec PERMISSION_DENIED si elles sont manquantes. Les autorisations requises au moment de la query ne sont pas validées en amont — les autorisations manquantes entraînent des erreurs d’exécution lorsque l’Endpoint sert le trafic.

Type de ressource	Octroi requis	Lorsque validé
Modèle Unity Catalog	USE CATALOG sur le catalogue, USE SCHEMA sur le schéma, EXECUTE sur le modèle	Création ou mise à jour d'endpoint

Type de ressource	Octroi requis	Lorsque validé
Modèle Unity Catalog	USE CATALOG sur le catalogue, USE SCHEMA sur le schéma, EXECUTE sur le modèle	Création ou mise à jour d'endpoint

remarque

Si un modèle Unity Catalog déclare des dépendances de fonctions transitives, le créateur enregistré a également besoin de EXECUTE sur ces fonctions en amont.

Gérer l'accès aux Endpoint

Pour comprendre les options de contrôle d'accès pour les Endpoint de déploiement de modèles, consultez Gérer les autorisations sur un Endpoint de déploiement de modèles.

Créer un endpoint

Serving UI

Vous pouvez créer un endpoint pour le déploiement de modèles avec l'interface utilisateur de Serving .

1. Cliquez sur Service dans la barre latérale pour afficher l’interface utilisateur de Service.

2. Cliquez sur Créer un Endpoint de service .

   

Pour les modèles dans Unity Catalog (recommandé) ou l'hérité Workspace Model Registry:

1. Dans le champ Nom , fournissez un nom pour votre Endpoint.

   • Les noms d'Endpoint ne peuvent pas utiliser le préfixe databricks-. Ce préfixe est réservé aux Endpoints préconfigurés de Databricks.

2. Dans la section Entités servies

   1. Cliquez dans le champ Entité pour ouvrir le formulaire Sélectionner l'entité servie .

   2. Sélectionnez **Mes modèles : Unity Catalog** ou **Mes modèles : Model Registry** selon l'endroit où votre modèle est enregistré. Le formulaire se met à jour dynamiquement en fonction de votre sélection.

      • Tous les modèles ne sont pas des modèles personnalisés. Les modèles peuvent être des modèles de fondation ou des fonctionnalités pour le Feature Serving.

   3. Sélectionnez le modèle et la version du modèle que vous souhaitez déployer.

   4. Sélectionnez le pourcentage de trafic à acheminer vers votre modèle servi.

   5. Sélectionnez la taille du compute à utiliser. Vous pouvez utiliser des computes CPU ou GPU pour vos charges de travail. Voir type de compute pour les types de charges de travail disponibles, y compris les options CPU_MEDIUM et CPU_LARGE pour les modèles qui nécessitent plus de mémoire que le type standard CPU. Pour des exemples de code GPU, consultez Types de charges de travail GPU.

   6. Sous Compute Scale-out , sélectionnez la taille de la Monter en charge de compute qui correspond au nombre de requêtes que ce modèle servi peut traiter simultanément. Ce nombre doit être approximativement égal à QPS x temps d'exécution du modèle. Pour les paramètres de compute définis par les clients, consultez les limites de service de modèle.

      1. Les tailles disponibles sont Petite pour 0 à 4 requêtes, Moyenne pour 8 à 16 requêtes et Grande pour 16 à 64 requêtes.

   7. Spécifiez si l'Endpoint doit monter en charge à zéro lorsqu'il n'est pas utilisé. La mise à l'échelle à zéro n'est pas recommandée pour les Endpoint de production, car la capacité n'est pas garantie lorsqu'elle est mise à l'échelle à zéro. Quand un Endpoint se met à l’échelle à zéro, il y a une latence additionnelle, également appelée démarrage à froid (cold start), lorsque le Endpoint monte en charge pour servir les requêtes.

   8. Sous Configuration avancée, vous pouvez :

      • Renommez l'entité servie pour personnaliser son affichage dans l'Endpoint.
      • Ajoutez un profil d'instance pour vous connecter aux ressources AWS depuis votre Endpoint.
      • Ajoutez des variables d’environnement pour vous connecter aux ressources de votre endpoint ou enregistrez votre DataFrame de recherche de fonctionnalités dans la table d’inférence de l’endpoint. L’enregistrement du DataFrame de recherche de fonctionnalités nécessite MLflow 2.14.0 ou supérieur.

   9. (Facultatif) Pour ajouter des entités servies supplémentaires à votre endpoint, cliquez sur Ajouter une entité servie et répétez les étapes de configuration ci-dessus. Vous pouvez déployer plusieurs modèles ou versions de modèle à partir d’un Endpoint unique et contrôler la répartition du trafic entre eux. Pour plus d’informations, consultez serve multiple models.

3. Dans la section **Optimisation de l'itinéraire**, vous pouvez activer l'optimisation de l'itinéraire pour votre endpoint. L'optimisation de l'itinéraire est recommandée pour les endpoints avec des exigences élevées en matière de QPS et de throughput. Consultez Optimisation de l'itinéraire sur l'Endpoint de service.

4. Dans la section AI Gateway , vous pouvez sélectionner les fonctionnalités de gouvernance à activer sur votre Endpoint. Voir la gouvernance de l'IA avec Unity AI Gateway.

5. Cliquez sur Créer. La page Endpoints de service s'affiche avec l' état de l'endpoint de service indiqué comme Non prêt.

   

REST API

Vous pouvez créer des endpoints à l’aide de l’API REST. Voir POST /api/2.0/serving-endpoints pour les paramètres de configuration des Endpoint.

L'exemple suivant crée un Endpoint qui sert la 3e version du modèle my-ads-model qui est enregistré dans le registre de modèles Unity Catalog. Pour spécifier un modèle d'Unity Catalog, veuillez fournir le nom complet du modèle, y compris le catalogue et le schéma parents, tel que catalog.schema.example-model. Cet exemple utilise une simultanéité définie sur mesure avec min_provisioned_concurrency et max_provisioned_concurrency. Les valeurs de simultanéité doivent être des multiples de 4.

Bash

POST /api/2.0/serving-endpoints

{
  "name": "uc-model-endpoint",
  "config":
  {
    "served_entities": [
      {
        "name": "ads-entity",
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "3",
        "min_provisioned_concurrency": 4,
        "max_provisioned_concurrency": 12,
        "scale_to_zero_enabled": false
      }
    ]
  }
}

Voici un exemple de réponse. L'état config_update de l'endpoint est NOT_UPDATING et le modèle servi est dans un état READY.

JSON

{
  "name": "uc-model-endpoint",
  "creator": "user@email.com",
  "creation_timestamp": 1700089637000,
  "last_updated_timestamp": 1700089760000,
  "state": {
    "ready": "READY",
    "config_update": "NOT_UPDATING"
  },
  "config": {
    "served_entities": [
      {
        "name": "ads-entity",
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "3",
        "min_provisioned_concurrency": 4,
        "max_provisioned_concurrency": 12,
        "scale_to_zero_enabled": false,
        "workload_type": "CPU",
        "state": {
          "deployment": "DEPLOYMENT_READY",
          "deployment_state_message": ""
        },
        "creator": "user@email.com",
        "creation_timestamp": 1700089760000
      }
    ],
    "config_version": 1
  },
  "tags": [
    {
      "key": "team",
      "value": "data science"
    }
  ],
  "id": "e3bd3e471d6045d6b75f384279e4b6ab",
  "permission_level": "CAN_MANAGE",
  "route_optimized": false
}

MLflow Deployments SDK

Les déploiements MLflow fournissent une API pour les tâches de création, de mise à jour et de suppression. Les APIs pour ces tâches acceptent les mêmes paramètres que l’API REST pour le déploiement d’Endpoint. Consultez POST /api/2.0/serving-endpoints pour les paramètres de configuration de l’endpoint.

L'exemple suivant crée un Endpoint qui sert la 3e version du modèle my-ads-model qui est enregistré dans le registre de modèles Unity Catalog. Vous devez fournir le nom complet du modèle, y compris le catalogue parent et le schéma, tel que catalog.schema.example-model. Cet exemple utilise une simultanéité définie sur mesure avec min_provisioned_concurrency et max_provisioned_concurrency. Les valeurs de simultanéité doivent être des multiples de 4.

Python

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.create_endpoint(
    name="unity-catalog-model-endpoint",
    config={
        "served_entities": [
            {
                "name": "ads-entity",
                "entity_name": "catalog.schema.my-ads-model",
                "entity_version": "3",
                "min_provisioned_concurrency": 4,
                "max_provisioned_concurrency": 12,
                "scale_to_zero_enabled": False
            }
        ]
    }
)

Workspace Client

L'exemple suivant montre comment créer un Endpoint à l'aide du SDK client Databricks Workspace.

Python

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

w = WorkspaceClient()

w.serving_endpoints.create(
    name="uc-model-endpoint",
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                name="ads-entity",
                entity_name="catalog.schema.my-ads-model",
                entity_version="3",
                workload_size="Small",
                scale_to_zero_enabled=False
            )
        ]
    )
)

Vous pouvez également :

• Activez les tables d'inférence pour capturer automatiquement les requêtes entrantes et les réponses sortantes vers vos Endpoint de service de modèle.
• Si vous avez activé les tables d’inférence sur votre Endpoint, vous pouvez enregistrer votre DataFrame de recherche de fonctionnalités dans la table d’inférence.

Vous pouvez également :

• Ajouter un profil d'instance à un Endpoint de mise en service de modèle
• Configurer l'accès aux Ressources à partir des Endpoint de mise en service de modèles.

Types de charges de travail GPU

Le déploiement de GPU est compatible avec les versions de package suivantes :

• PyTorch 1.13.0 - 2.0.1
• TensorFlow 2.5.0 - 2.13.0
• MLflow 2.4.0 et versions supérieures

Les exemples suivants montrent comment créer des Endpoints GPU à l'aide de différentes méthodes.

Serving UI

Pour configurer votre endpoint pour les charges de travail GPU avec l'interface utilisateur Serving , sélectionnez le type de GPU souhaité dans la liste déroulante Type de compute lors de la création de votre endpoint. Suivez les mêmes étapes que dans Créer un endpoint, mais sélectionnez un type de charge de travail GPU au lieu de CPU.

REST API

Pour déployer vos modèles à l'aide de GPU, incluez le champ workload_type dans votre configuration d'Endpoint.

Bash

POST /api/2.0/serving-endpoints

{
  "name": "gpu-model-endpoint",
  "config": {
    "served_entities": [{
      "entity_name": "catalog.schema.my-gpu-model",
      "entity_version": "1",
      "workload_type": "GPU_SMALL",
      "workload_size": "Small",
      "scale_to_zero_enabled": false
    }]
  }
}

MLflow Deployments SDK

L'exemple suivant montre comment créer un Endpoint GPU à l'aide du SDK MLflow Deployments.

Python

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.create_endpoint(
    name="gpu-model-endpoint",
    config={
        "served_entities": [{
            "entity_name": "catalog.schema.my-gpu-model",
            "entity_version": "1",
            "workload_type": "GPU_SMALL",
            "workload_size": "Small",
            "scale_to_zero_enabled": False
        }]
    }
)

Workspace Client

L’exemple suivant montre comment créer un endpoint GPU à l’aide du SDK client Databricks Workspace.

Python

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

w = WorkspaceClient()

w.serving_endpoints.create(
    name="gpu-model-endpoint",
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                entity_name="catalog.schema.my-gpu-model",
                entity_version="1",
                workload_type="GPU_SMALL",
                workload_size="Small",
                scale_to_zero_enabled=False
            )
        ]
    )
)

Les types de charges de travail GPU disponibles dépendent de votre fournisseur cloud, comme résumé dans le tableau suivant.

Type de charge de travail GPU	Instance GPU	Mémoire GPU
GPU_SMALL	1xT4	16 Go
GPU_MEDIUM	1xA10G	24 Go
MULTIGPU_MEDIUM	4xA10G	96 Go
GPU_MEDIUM_8	8xA10G	192 Go

Type de charge de travail GPU	Instance GPU	Mémoire GPU
GPU_SMALL	1xT4	16 Go
GPU_MEDIUM	1xA10G	24 Go
MULTIGPU_MEDIUM	4xA10G	96 Go
GPU_MEDIUM_8	8xA10G	192 Go

Pour les Endpoint GPU, la valeur de simultanéité détermine le nombre de réplicas alloués pour servir votre modèle. Le nombre de répliques est égal à la valeur de concurrence divisée par 4. Par exemple, définir min_provisioned_concurrency sur 12 alloue 3 répliques.

Modifier un endpoint de modèle personnalisé

Après avoir activé un endpoint de modèle personnalisé, vous pouvez mettre à jour la configuration du compute comme souhaité. Cette configuration est particulièrement utile si vous avez besoin de ressources supplémentaires pour votre modèle. La taille du Workload et la configuration du compute jouent un rôle clé dans les ressources allouées pour la diffusion de votre modèle.

remarque

Les mises à jour de la configuration et des entités servies revalident l'appartenance au Workspace du créateur enregistré de l'Endpoint et les autorisations par entité servie. Confirmez qu'ils sont toujours valides avant de soumettre une mise à jour ; voir Identité et accès.

Pour éviter les échecs de mise à jour :

• Utilisez un service principal de longue durée, détenu par votre équipe, comme créateur d'endpoint.
• N'utilisez pas de compte d’utilisateur personnel qui pourrait être désactivé ou supprimé du workspace ultérieurement.
• Le créateur enregistré doit rester membre de l'workspace pendant toute la durée de vie de l'endpoint.

remarque

Les mises à jour de la configuration de l'Endpoint peuvent échouer. Lorsque des défaillances surviennent, la configuration active existante demeure effective comme si la mise à jour n’avait pas eu lieu.

Vérifiez que la mise à jour a été appliquée avec succès en consultant le statut de votre Endpoint.

Tant que la nouvelle configuration n'est pas prête, l'ancienne configuration continue de servir le trafic de prédiction. Pendant qu'une mise à jour est en cours, une autre mise à jour ne peut pas être effectuée. Cependant, vous pouvez annuler une mise à jour en cours à partir de l'interface utilisateur de Serving.

Serving UI

Après avoir activé un endpoint de modèle, sélectionnez Modifier l’endpoint pour modifier la configuration de compute de votre endpoint.

Vous pouvez modifier la plupart des aspects de la configuration de l'Endpoint, à l'exception du nom de l'Endpoint et de certaines propriétés immuables.

Vous pouvez annuler une mise à jour de configuration en cours en sélectionnant Annuler la mise à jour sur la page des détails de l'endpoint.

REST API

Voici un exemple de mise à jour de configuration d'endpoint utilisant l'API REST. Voir PUT /api/2.0/serving-endpoints/{name}/config.

Bash

PUT /api/2.0/serving-endpoints/{name}/config

{
  "name": "unity-catalog-model-endpoint",
  "config":
  {
    "served_entities": [
      {
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "5",
        "workload_size": "Small",
        "scale_to_zero_enabled": true
      }
    ],
    "traffic_config":
    {
      "routes": [
        {
          "served_model_name": "my-ads-model-5",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

MLflow Deployments SDK

Le SDK de déploiements MLflow utilise les mêmes parameters que l’API REST, voir PUT /api/2.0/serving-endpoints/{name}/config pour les détails du schéma de requête et de réponse.

L'exemple de code suivant utilise un modèle du registre de modèles Unity Catalog :

Python

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.update_endpoint_config(
  endpoint=f"{endpointname}",
  config={
    "served_entities": [
        {
            "entity_name": f"{catalog}.{schema}.{model_name}",
            "entity_version": "1",
            "workload_size": "Small",
            "scale_to_zero_enabled": True
        }
    ],
    "traffic_config": {
        "routes": [
            {
                "served_model_name": f"{model_name}-1",
                "traffic_percentage": 100
            }
        ]
    }
  }
)

Notation d'un Endpoint de modèle

Pour noter votre modèle, envoyez des requêtes à l'endpoint de mise en service du modèle.

• Voir Endpoint de service de query pour les modèles personnalisés.
• Consultez Utiliser des modèles de fondation.

Ressources supplémentaires

• Gérer les Endpoint de service de modèle.
• Modèles externes dans Model Serving.
• Si vous préférez utiliser Python, vous pouvez utiliser le SDK Python Databricks pour le service en temps réel.

Exemples de Notebooks

Les notebooks suivants incluent différents modèles enregistrés Databricks que vous pouvez utiliser pour commencer à utiliser les endpoints de service de modèles. Pour d'autres exemples, consultez Tutoriel : Déployer et query un modèle personnalisé.

Les exemples de modèles peuvent être importés dans le Workspace en suivant les instructions figurant dans Importer un Notebook. Après avoir choisi et créé un modèle à partir de l'un des exemples, enregistrez-le dans Unity Catalog, puis suivez les étapes du flux de travail de l'interface utilisateur pour le déploiement du modèle.

Entraînez et enregistrez un modèle scikit-learn pour le Notebook de service de modèle

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Entraîner et enregistrer un modèle HuggingFace pour un Notebook de service de modèle

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks