Aller au contenu principal

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. Ces directives s'appliquent au déploiement de modèles personnalisés , que Databricks définit comme des modèles ML traditionnels ou des modèles Python personnalisés packagés au format MLflow. Les modèles doivent être enregistrés dans Unity Catalog. Les exemples incluent les modèles scikit-learn, XGBoost, PyTorch et de transformateur Hugging Face. Pour plus d'informations sur cette fonctionnalité et les catégories de modèles prises en charge, consultez Déployer des modèles à l'aide de Model Serving.

Pour les requêtes de query pour les charges de travail d’IA et de LLM, consultez Utiliser les 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​

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.

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.

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.

Les requêtes Protobuf ne sont pas capturées dans les tables d'inférence.

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 BOOL, UINT8, UINT16, UINT32, UINT64, INT8, INT16, INT32, INT64, FP16, FP32, FP64 et BYTES. Pour les données texte et binaires dans les tenseurs BYTES, consultez Entrées texte et binaires dans les requêtes protobuf.

Envoyez les données pour chaque entrée dans raw_input_contents, dans le même ordre que inputs. Les requêtes qui mettent les données de tenseur dans les champs contents typés, tels que fp32_contents, échouent avec HTTP 400.

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)

Entrées textuelles et binaires dans les requêtes protobuf​

remarque

BYTES Les tenseurs sont disponibles sur les Endpoint déployés après le 10 novembre 2026. Pour les utiliser sur un endpoint déployé plus tôt, servez une nouvelle version du modèle sur l'endpoint.

Un tenseur BYTES contient des valeurs de longueur variable, comme du texte ou le contenu d’un fichier. Une requête peut mélanger des tenseurs BYTES avec des tenseurs numériques, par exemple un titre et un vecteur de caractéristiques pour chaque ligne. Dans raw_input_contents, chaque valeur BYTES est une longueur little-endian de 4 octets suivie des octets de la valeur, comme défini par le protocole KServe v2.

La signature d’entrée du modèle détermine ce que votre modèle reçoit pour chaque entrée BYTES :

Type de signature

Ce que le modèle reçoit

À utiliser pour

object

Une matrice NumPy de valeurs Python str, décodées à partir de UTF-8. Chaque valeur conserve sa propre taille.

Texte libre, tel que les titres, les queries et les descriptions.

str

Un tableau de chaînes NumPy à largeur fixe (<U). Chaque valeur est complétée par la valeur la plus longue de la requête, à 4 octets par caractère.

Valeurs courtes de longueur similaire, telles que des codes.

bytes

Un tableau d'octets NumPy à largeur fixe (S) contenant les octets bruts. Chaque valeur est complétée par la valeur la plus longue de la requête.

Fichiers et autres données binaires. Consultez Envoyer des fichiers dans les requêtes protobuf.

Type de signature

Ce que le modèle reçoit

À utiliser pour

object

Une matrice NumPy de valeurs Python str, décodées à partir de UTF-8. Chaque valeur conserve sa propre taille.

Texte libre, tel que les titres, les queries et les descriptions.

str

Un tableau de chaînes NumPy à largeur fixe (<U). Chaque valeur est complétée par la valeur la plus longue de la requête, à 4 octets par caractère.

Valeurs courtes de longueur similaire, telles que des codes.

bytes

Un tableau d'octets NumPy à largeur fixe (S) contenant les octets bruts. Chaque valeur est complétée par la valeur la plus longue de la requête.

Fichiers et autres données binaires. Consultez Envoyer des fichiers dans les requêtes protobuf.

L'exemple suivant Logs un modèle qui prend une entrée texte et une entrée numérique. Déclarez les entrées texte comme object afin qu'une valeur longue ne complète pas toutes les autres valeurs de la requête.

Python
import mlflow
import numpy as np
from mlflow.models import ModelSignature
from mlflow.types import Schema, TensorSpec


class TitleTagger(mlflow.pyfunc.PythonModel):
def predict(self, context, model_input, params=None):
titles = model_input["title"] # numpy array of Python str
features = model_input["features"] # float32 array of shape (rows, 600)
genres = ["Sci-Fi" if "space" in title.lower() else "Drama" for title in titles]
return {"genre": np.array(genres, dtype=object), "score": features.mean(axis=1)}


signature = ModelSignature(
inputs=Schema(
[
TensorSpec(np.dtype(object), (-1,), "title"), # text: use object, not str
TensorSpec(np.dtype(np.float32), (-1, 600), "features"),
]
),
outputs=Schema(
[
TensorSpec(np.dtype(object), (-1,), "genre"),
TensorSpec(np.dtype(np.float32), (-1,), "score"),
]
),
)

with mlflow.start_run():
mlflow.pyfunc.log_model(
name="model",
python_model=TitleTagger(),
signature=signature,
registered_model_name="main.default.title_tagger",
)

Pour créer une demande, mettez du texte et des valeurs binaires dans une matrice NumPy avec dtype=object et encodez-la avec serialize_byte_tensor à partir de tritonclient. Les autres clients KServe v2 fournissent des assistants équivalents.

Python
import numpy as np
from tritonclient.grpc.service_pb2 import ModelInferRequest, ModelInferResponse
from tritonclient.utils import deserialize_bytes_tensor, serialize_byte_tensor, triton_to_np_dtype

titles = np.array(["Lost in Space", "Love, Actually"], dtype=object)
features = np.random.rand(2, 600).astype(np.float32)

request = ModelInferRequest()
request.inputs.add(name="title", datatype="BYTES", shape=titles.shape)
request.raw_input_contents.append(serialize_byte_tensor(titles).item())
request.inputs.add(name="features", datatype="FP32", shape=features.shape)
request.raw_input_contents.append(features.tobytes())

body = request.SerializeToString()

Les sorties texte et binaires, comme les tableaux str, bytes ou object et les listes de chaînes, sont retournées sous forme de tenseurs BYTES. Chaque valeur revient sous forme de Python bytes.

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

outputs = {}
for tensor, raw in zip(response.outputs, response.raw_output_contents):
if tensor.datatype == "BYTES":
values = deserialize_bytes_tensor(raw)
else:
values = np.frombuffer(raw, dtype=triton_to_np_dtype(tensor.datatype))
outputs[tensor.name] = values.reshape(tensor.shape)

genres = [genre.decode("utf-8") for genre in outputs["genre"]]

Un modèle qui retourne un DataFrame pandas avec des colonnes de texte et numériques échoue avec HTTP 500 pour les requêtes protobuf. Retournez plutôt un dictionnaire de matrices NumPy, comme dans l'exemple précédent.

Les entrées texte et binaires ont les limites suivantes :

  • Taille décodée : les valeurs texte et binaire d'une requête peuvent occuper au maximum 256 Mio après décodage. Avec une signature str ou bytes, chaque valeur est complétée pour correspondre à la valeur la plus longue de la requête. Une seule valeur longue peut donc faire dépasser la limite à une requête. Les requêtes dépassant la limite échouent avec une erreur HTTP 400. Utilisez une signature object pour le texte libre et envoyez des fichiers de taille similaire dans la même requête.
  • Octets zéro finaux : avec une signature str ou bytes, une valeur qui se termine par un octet zéro (0x00) échoue avec une erreur HTTP 400, car les matrices NumPy de largeur fixe suppriment les octets zéro finaux. Pour envoyer des fichiers qui se terminent par un octet zéro, consultez Send files in protobuf requests.
  • Taille de requête : les requêtes Protobuf ont la même limite de taille de 16 Mo que les requêtes JSON. Consultez les limites et régions de Model Serving.
  • Performance : les tenseurs numériques sont copiés directement dans les matrices NumPy, mais les valeurs de texte sont décodées une valeur à la fois, à peu près à la vitesse de l'analyse JSON. Les requêtes qui sont principalement du texte voient peu d'accélération par rapport au JSON.

Envoyer des fichiers dans des demandes protobuf​

BYTES les tenseurs peuvent transporter des fichiers dont la taille varie d’une ligne à l’autre, comme des images, des fichiers audio et des documents. Envoyez un fichier par ligne sous forme d’octets bruts, avec une signature d’entrée bytes. Le modèle reçoit les octets exacts de chaque fichier et les décode. Une requête JSON ne peut transporter des données binaires que sous forme de texte base64, ce qui augmente leur taille d’environ 33 %.

Les utilisations courantes sont les suivantes :

  • Images : envoyez des fichiers JPEG ou PNG vers des modèles de classification, de détection ou d'incorporation d'images, qui les décodent et les redimensionnent. Sur un endpoint GPU, le modèle peut décoder les images sur le GPU.
  • Audio : envoyez des fichiers WAV, FLAC ou MP3 à des modèles de reconnaissance vocale ou de classification audio.
  • Documents : envoyez des fichiers PDF ou d'autres documents à des modèles d'analyse et d'extraction.
  • Enregistrements sérialisés : envoyez des fichiers Parquet ou d’autres données sérialisées que le modèle lit.

Si vos données ont une taille fixe pour chaque ligne, comme des pixels décodés ou des échantillons audio, envoyez-les plutôt sous la forme d’un tenseur numérique tel que UINT8 ou FP32.

L’exemple suivant Logs un modèle qui lit des fichiers image et renvoie la taille de chaque image.

Python
import io

import mlflow
import numpy as np
from mlflow.models import ModelSignature
from mlflow.types import Schema, TensorSpec


class ImageInfo(mlflow.pyfunc.PythonModel):
def predict(self, context, model_input, params=None):
from PIL import Image

widths, heights = [], []
for data in model_input["image"]: # one encoded image file per row
image = Image.open(io.BytesIO(bytes(data)))
widths.append(image.width)
heights.append(image.height)
return {"width": np.array(widths, dtype=np.int32), "height": np.array(heights, dtype=np.int32)}


signature = ModelSignature(
inputs=Schema([TensorSpec(np.dtype(bytes), (-1,), "image")]), # files: use bytes
outputs=Schema(
[
TensorSpec(np.dtype(np.int32), (-1,), "width"),
TensorSpec(np.dtype(np.int32), (-1,), "height"),
]
),
)

with mlflow.start_run():
mlflow.pyfunc.log_model(
name="model",
python_model=ImageInfo(),
signature=signature,
registered_model_name="main.default.image_info",
extra_pip_requirements=["pillow"],
)

Pour envoyer des fichiers, lisez chaque fichier dans une matrice NumPy avec dtype=object. N'utilisez pas de matrice d'octets NumPy à largeur fixe, qui supprime les octets zéro de fin de chaque valeur.

Python
from pathlib import Path

paths = ["cat.jpg", "dog.png"]
images = np.array([Path(path).read_bytes() for path in paths], dtype=object)

request = ModelInferRequest()
request.inputs.add(name="image", datatype="BYTES", shape=images.shape)
request.raw_input_contents.append(serialize_byte_tensor(images).item())

body = request.SerializeToString()

Avec une signature bytes, un fichier se terminant par un octet zéro échoue avec HTTP 400. Les fichiers JPEG, PNG, PDF et Parquet se terminent par un marqueur fixe, vous pouvez donc les envoyer tels quels. Les fichiers basés sur ZIP tels que DOCX et XLSX, les fichiers gzip et certains fichiers audio et vidéo peuvent se terminer par un octet zéro. Pour envoyer ces fichiers, encodez chaque fichier sur le client et décodez-le dans le modèle. L'encodage avec base64 ajoute environ 33 % à la taille de chaque fichier. L'ajout d'un octet non nul ajoute 1 octet.

Python
import base64

# Option 1: base64. In the model, decode each value with base64.b64decode(bytes(data)).
encoded = np.array([base64.b64encode(Path(path).read_bytes()) for path in paths], dtype=object)

# Option 2: append one byte. In the model, remove it with bytes(data)[:-1].
padded = np.array([Path(path).read_bytes() + b"\x01" for path in paths], dtype=object)

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

Ressources supplémentaires​