Aller au contenu principal
Dernière mise à jour le

Endpoints de mise en service des requêtes pour les modèles personnalisés

Dans cette page, apprenez à formater les requêtes de scoring pour votre modèle déployé et à envoyer ces requêtes à l'endpoint de service de modèle. Les conseils sont pertinents pour le déploiement de modèles personnalisés, que Databricks définit comme des modèles de ML traditionnels ou des modèles Python personnalisés empaquetés au format MLflow. Enregistrez les modèles dans Unity Catalog ou dans le registre de modèles du workspace. Les exemples incluent les modèles scikit-learn, XGBoost, PyTorch et de transformateur Hugging Face. Voir Déployer des modèles à l'aide de Model Serving pour plus d'informations sur cette fonctionnalité et les catégories de modèles prises en charge.

Pour les requêtes de query pour l’IA générative et les charges de travail LLM, consultez Utiliser des modèles de fondation.

attention

Si votre endpoint a l' optimisation d'itinéraire activée, le flux d'authentification et l'URL d'invocation décrits sur cette page ne s'appliquent pas. Les Endpoint optimisés pour l'itinéraire n'acceptent que les jetons OAuth (pas les jetons d'accès personnels) et doivent être interrogés à une URL dédiée. Consultez Interroger les Endpoint de service optimisés pour l'itinéraire pour le flux complet, y compris une recette de bout en bout que vous pouvez copier-coller, et le dépannage.

Exigences​

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.

Méthodes et exemples de requête​

Model Serving offre les options suivantes pour l'envoi de requêtes de scoring aux modèles servis :

Méthode

Détails

Interface utilisateur de service

Sélectionnez Query endpoint à partir de la page Serving endpoint dans votre Workspace Databricks. Insérez les données d'entrée du modèle au format JSON et cliquez sur Envoyer la demande . Si le modèle a un exemple d'entrée journalisé, utilisez Afficher l'exemple pour le charger.

fonction SQL

Invoquez l'inférence de modèle directement depuis SQL en utilisant la fonction SQL ai_query. Voir la ai_query fonction.

API REST

Appelez et interrogez le modèle à l'aide de l'API REST. Voir POST /serving-endpoints/{name}/invocations pour plus de détails. Pour les requêtes de scoring vers des endpoints diffusant plusieurs modèles, voir Interroger des modèles individuels derrière un endpoint.

SDK de déploiements MLflow

Utilisez la fonction predict() du SDK de déploiement MLflow pour interroger le modèle.

Méthode

Détails

Interface utilisateur de service

Sélectionnez Query endpoint à partir de la page Serving endpoint dans votre Workspace Databricks. Insérez les données d'entrée du modèle au format JSON et cliquez sur Envoyer la demande . Si le modèle a un exemple d'entrée journalisé, utilisez Afficher l'exemple pour le charger.

fonction SQL

Invoquez l'inférence de modèle directement depuis SQL en utilisant la fonction SQL ai_query. Voir la ai_query fonction.

API REST

Appelez et interrogez le modèle à l'aide de l'API REST. Voir POST /serving-endpoints/{name}/invocations pour plus de détails. Pour les requêtes de scoring vers des endpoints diffusant plusieurs modèles, voir Interroger des modèles individuels derrière un endpoint.

SDK de déploiements MLflow

Utilisez la fonction predict() du SDK de déploiement MLflow pour interroger le modèle.

Exemple de scoring de DataFrame Pandas​

L'exemple suivant suppose un ENDPOINT_INVOCATION_URL comme https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocations, où <databricks-instance> est le nom de votre instance Databricks, et un jeton d'API REST Databricks appelé DATABRICKS_API_TOKEN.

Voir formats de notation pris en charge.

Évaluez un modèle acceptant le format d'entrée fractionné du dataframe.

Bash
curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
  -H 'Content-Type: application/json' \
  -d '{"dataframe_split": [{
    "columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
    "data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]]
    }]
  }'

Évaluez un modèle acceptant les entrées tensor. Les entrées de tenseurs doivent être formatées comme décrit dans la documentation de l’API TensorFlow Serving.

Bash
curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
  -H 'Content-Type: application/json' \
  -d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'

Exemple d'entrée Tensor​

L'exemple suivant évalue un modèle acceptant des entrées tensor. Les entrées tensor doivent être formatées comme décrit dans les documents d'API de TensorFlow Serving. Cet exemple suppose un ENDPOINT_INVOCATION_URL comme https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocations, où <databricks-instance> est le nom de votre instance Databricks, et un jeton d'API REST Databricks appelé DATABRICKS_API_TOKEN.

Bash
curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
    -H 'Content-Type: application/json' \
    -d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'

Formats de scoring pris en charge​

Pour les modèles personnalisés, Model Serving prend en charge les demandes de scoring dans un DataFrame Pandas (JSON) ou une entrée Tensor (JSON ou Protobuf).

DataFrame Pandas​

Les requêtes doivent être envoyées en construisant un DataFrame Pandas sérialisé en JSON avec l'une des clés prises en charge et un objet JSON correspondant au format d'entrée.

  • (Recommandé) Le formatdataframe_split est un DataFrame Pandas sérialisé en JSON dans l'orientation split.

    JSON
    {
      "dataframe_split": {
        "index": [0, 1],
        "columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
        "data": [
          [5.1, 3.5, 1.4, 0.2],
          [4.9, 3.0, 1.4, 0.2]
        ]
      }
    }

  • dataframe_records est un DataFrame Pandas sérialisé en JSON dans l'orientation records.

remarque

Ce format ne garantit pas la préservation de l'ordre des colonnes, et le format split est préféré au format records.

JSON
{
  "dataframe_records": [
    {
      "sepal length (cm)": 5.1,
      "sepal width (cm)": 3.5,
      "petal length (cm)": 1.4,
      "petal width (cm)": 0.2
    },
    {
      "sepal length (cm)": 4.9,
      "sepal width (cm)": 3,
      "petal length (cm)": 1.4,
      "petal width (cm)": 0.2
    },
    {
      "sepal length (cm)": 4.7,
      "sepal width (cm)": 3.2,
      "petal length (cm)": 1.3,
      "petal width (cm)": 0.2
    }
  ]
}

La réponse de l’Endpoint contient le résultat de votre modèle, sérialisé avec JSON, enveloppé dans une clé predictions.

JSON
{
  "predictions": [0, 1, 1, 1, 0]
}

Entrée de tenseur​

Lorsque votre modèle attend des tenseurs, comme un modèle TensorFlow ou PyTorch, il existe deux options de format prises en charge pour l'envoi de requêtes : instances et inputs.

Si vous avez plusieurs tenseurs nommés par ligne, alors vous devez avoir un de chaque tenseur pour chaque ligne.

  • instances est un format basé sur les tenseurs qui accepte les tenseurs au format de ligne. Utilisez ce format si tous les tenseurs d'entrée ont la même dimension 0. Conceptuellement, chaque tenseur de la liste d'instances pourrait être joint aux autres tenseurs du même nom dans le reste de la liste pour construire le tenseur d'entrée complet pour le modèle, ce qui ne serait possible que si tous les tenseurs ont la même dimension 0.

    JSON
    { "instances": [1, 2, 3] }

    L'exemple suivant montre comment spécifier plusieurs tenseurs nommés.

    JSON
    {
      "instances": [
        {
          "t1": "a",
          "t2": [1, 2, 3, 4, 5],
          "t3": [
            [1, 2],
            [3, 4],
            [5, 6]
          ]
        },
        {
          "t1": "b",
          "t2": [6, 7, 8, 9, 10],
          "t3": [
            [7, 8],
            [9, 10],
            [11, 12]
          ]
        }
      ]
    }

  • inputs Envoyer des requêtes avec des tenseurs au format colonne. Cette requête est différente car il y a en fait un nombre différent d'instances de tenseurs de t2 (3) que t1 et t3, il n'est donc pas possible de représenter cette entrée au format instances.

    JSON
    {
      "inputs": {
        "t1": ["a", "b"],
        "t2": [
          [1, 2, 3, 4, 5],
          [6, 7, 8, 9, 10]
        ],
        "t3": [
          [
            [1, 2],
            [3, 4],
            [5, 6]
          ],
          [
            [7, 8],
            [9, 10],
            [11, 12]
          ]
        ]
      }
    }

La réponse de l'Endpoint est au format suivant.

JSON
{
  "predictions": [0, 1, 1, 1, 0]
}

Entrée Protobuf tensorielle​

info

Aperçu

Cette fonctionnalité est en Public Preview et est uniquement disponible sur les endpoints déployés après le 9 juillet 2026.

Pour les modèles avec une signature d'entrée basée sur des tenseurs, vous pouvez envoyer le corps de la requête sous forme de ModelInferRequest KServe v2 sérialisé au lieu de JSON, en utilisant Content-Type: application/x-protobuf ou application/vnd.kserve.protobuf. Cela évite l'analyse des tenseurs numériques à partir du texte JSON, ce qui est plus rapide, surtout pour les charges utiles volumineuses. L'URL d'Endpoint et l'authentification restent inchangées.

Les types de données de tenseur pris en charge sont les suivants : BOOL, UINT8, UINT16, UINT32, UINT64, INT8, INT16, INT32, INT64, FP16, FP32 et FP64.

L'exemple suivant montre comment créer un corps de requête protobuf.

Python
import numpy as np
from tritonclient.grpc.service_pb2 import ModelInferRequest, ModelInferResponse  # or any other module that provides KServe v2's ModelInferRequest and ModelInferResponse classes

# FP32 tensor of shape [2, 4]
tensor = np.array([[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]], dtype=np.float32)

request = ModelInferRequest()
request.inputs.add(name="input", datatype="FP32", shape=tensor.shape)
request.raw_input_contents.append(tensor.tobytes())

body = request.SerializeToString()

La réponse est un ModelInferResponse sérialisé avec les données du tenseur dans raw_output_contents.

Python
response = ModelInferResponse()
response.ParseFromString(response_bytes)

values = np.frombuffer(response.raw_output_contents[0], dtype=np.float32).reshape(response.outputs[0].shape)

Exemple de Notebook​

Consultez le notebook suivant pour un exemple de la façon de tester votre Endpoint Model Serving avec un modèle Python :

Notebook de l'Endpoint Model Serving de test

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Ressources supplémentaires​

Sur cette page