Partager via

Interroger des points de terminaison de service pour des modèles personnalisés

  • Article

Dans cet article, vous allez découvrir comment mettre en forme des requêtes de scoring pour votre modèle servi, et comment envoyer ces requêtes au point de terminaison de service du modèle. Ces instructions s’appliquent au service de modèles personnalisés, que Databricks définit comme des modèles ML traditionnels ou des modèles Python personnalisés empaquetés au format MLflow. Ils peuvent être inscrits dans Unity Catalog ou dans le registre de modèle de l’espace de travail. Il peut s’agir notamment de modèles scikit-learn, XGBoost, PyTorch et Hugging Face Transformer. Pour plus d’informations sur cette fonctionnalité et sur les catégories de modèles prises en charge, consultez Service de modèles avec Azure Databricks.

Pour plus d’informations sur les demandes de requêtes pour les charges de travail LLM et IA générative, consultez Modèles de base pour les requêtes.

Exigences

Important

À titre de meilleure 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 pas à des utilisateurs de l’espace de travail. Pour créer des jetons d’accès pour des principaux de service, consultez la section Gérer les jetons pour un principal de service.

Interrogation de méthodes et exemples

Le Service de modèles Databricks fournit les options suivantes pour envoyer des requêtes de scoring aux modèles servis :

Méthode Détails
Interface utilisateur de service Dans la page Serving endpoint de votre espace de travail Databricks, sélectionnez Query endpoint. Insérez les données d’entrée du modèle au format JSON, puis cliquez sur Envoyer la requête. Si le modèle a un exemple d’entrée enregistré, utilisez Afficher l’exemple pour le charger.
API REST Appelez et interrogez le modèle en utilisant l’API REST. Pour plus de détails, consultez POST /serving-endpoints/{name}/invocations. Pour les requêtes de scoring adressées aux points de terminaison servant plusieurs modèles, consultez Interroger des modèles individuels derrière un point de terminaison.
Kit de développement logiciel (SDK) de déploiements MLflow Utilisez la fonction predict() du Kit de développement logiciel (SDK) Déploiements MLflow pour interroger le modèle.
Fonction SQL Appelez l’inférence de modèle directement à partir de SQL à l’aide de la fonction SQL ai_query. Voir Interroger un modèle servi avec ai_query().

Exemple de scoring DataFrame Pandas

L’exemple suivant suppose un MODEL_VERSION_URI comme https://<databricks-instance>/model/iris-classifier/Production/invocations, où <databricks-instance> est le nom de votre instance Databricks, et un jeton d’API REST Databricks nommé DATABRICKS_API_TOKEN.

Consultez Formats de scoring pris en charge.

API REST

Évaluez un modèle acceptant le format d’entrée des enregistrements de dataframe.

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
  -H 'Content-Type: application/json' \
  -d '{"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]]
    }]
  }'

Évaluez un modèle acceptant les entrées de tenseur. Les entrées de tenseur doivent être mises en forme conformément à la documentation de l’API de TensorFlow Serving.

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

Kit SDK de déploiements MLflow

Important

L’exemple suivant utilise l’API predict() à partir du Kit SDK de déploiements MLflow.


import mlflow.deployments

export DATABRICKS_HOST="https://<workspace_host>.databricks.com"
export DATABRICKS_TOKEN="dapi-your-databricks-token"

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

response = client.predict(
            endpoint="test-model-endpoint",
            inputs={"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]]
                    }
                }
           )

SQL

Important

L’exemple suivant utilise la fonction SQL intégrée, ai_query. Cette fonction est en préversion publique et sa définition est susceptible de changer. Voir Interroger un modèle servi avec ai_query().

L’exemple suivant interroge le modèle derrière le point de terminaison sentiment-analysis avec le jeu de données text et spécifie le type de retour de la requête.

SELECT text, ai_query(
    "sentiment-analysis",
    text,
    returnType => "STRUCT<label:STRING, score:DOUBLE>"
  ) AS predict
FROM
  catalog.schema.customer_reviews

Powerbi

Vous pouvez évaluer un jeu de données dans Power BI Desktop en procédant comme suit :

  1. Ouvrez le jeu de données à évaluer.

  2. Accédez à Transformer les données.

  3. Cliquez avec le bouton droit dans le volet gauche et sélectionnez Créer une requête.

  4. Accédez à Afficher > Éditeur avancé.

  5. Remplacez le corps de la requête par l’extrait de code ci-dessous, après avoir fourni un DATABRICKS_API_TOKEN approprié et un MODEL_VERSION_URI.

    (dataset as table ) as table =>
let
  call_predict = (dataset as table ) as list =>
  let
    apiToken = DATABRICKS_API_TOKEN,
    modelUri = MODEL_VERSION_URI,
    responseList = Json.Document(Web.Contents(modelUri,
      [
        Headers = [
          #"Content-Type" = "application/json",
          #"Authorization" = Text.Format("Bearer #{0}", {apiToken})
        ],
        Content = {"dataframe_records": Json.FromValue(dataset)}
      ]
    ))
  in
    responseList,
  predictionList = List.Combine(List.Transform(Table.Split(dataset, 256), (x) => call_predict(x))),
  predictionsTable = Table.FromList(predictionList, (x) => {x}, {"Prediction"}),
  datasetWithPrediction = Table.Join(
    Table.AddIndexColumn(predictionsTable, "index"), "index",
    Table.AddIndexColumn(dataset, "index"), "index")
in
  datasetWithPrediction

  6. Nommez la requête avec le nom de modèle de votre choix.

  7. Ouvrez l’éditeur de requête avancé pour votre jeu de données et appliquez la fonction de modèle.

Exemple d’entrée Tensor

L’exemple suivant note un modèle acceptant des entrées de capteur. Les entrées de tenseur doivent être mises en forme conformément à la documentation de l’API de TensorFlow Serving. Cet exemple suppose un MODEL_VERSION_URI comme https://<databricks-instance>/model/iris-classifier/Production/invocations, où <databricks-instance> est le nom de votre instance Databricks, et un jeton d’API REST Databricks nommé DATABRICKS_API_TOKEN.

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
    -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 requêtes de scoring dans une entrée DataFrame Pandas ou Tensor.

DataFrame Pandas

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

  • Le format dataframe_split (recommandé) est un DataFrame Pandas sérialisé au format JSON en orientation split.

    {
  "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é au format JSON dans l’orientation records.

    Remarque

    Ce format ne garantit pas la conservation du classement des colonnes, et le split format est préféré au records format.

    {
  "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 du point de terminaison contient la sortie de votre modèle, sérialisée avec JSON, encapsulée dans une clé predictions.

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

Entrée Tensor

Si votre modèle attend des tenseurs, comme un modèle TensorFlow ou Pytorch, il existe deux options de mise en forme 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 tenseur de chaque pour toutes les lignes.

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

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

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

    {
"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 envoient des requêtes avec des tenseurs dans un format en colonnes. Cette requête est différente, car il existe en fait un nombre différent d’instances de tenseur de t2 (3) que t1 et t3, et il n’est donc pas possible de représenter cette entrée dans le format instances.

    {
"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 du point de terminaison se présente au format suivant.

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

Exemple de notebook

Consultez le notebook suivant pour obtenir un exemple de test de votre point de terminaison de service du modèle avec un modèle Python :

Tester le notebook du point de terminaison de service du modèle

Obtenir le notebook

Ressources supplémentaires