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.
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
- Un Endpoint de service de modèle.
- Pour le SDK de déploiement MLflow, MLflow 2.9 ou version ultérieure est requis.
- Demande de notation dans un format accepté.
- Pour envoyer une requête de scoring via l'API REST ou le SDK de déploiement MLflow, vous devez disposer d'un jeton d'API Databricks.
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. |
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.
- REST API
- MLflow Deployments SDK
- SQL
- PowerBI
Évaluez un modèle acceptant le format d'entrée fractionné du dataframe.
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.
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]]}'
L'exemple suivant utilise l'API predict() du SDK de déploiement MLflow.
import os
import mlflow.deployments
os.environ["DATABRICKS_HOST"] = "https://<workspace_host>.databricks.com"
os.environ["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]]
}
}
)
L'exemple suivant utilise la fonction SQL intégrée, ai_query. Cette fonction est en prévisualisation publique et la définition pourrait changer.
L'exemple suivant interroge le modèle derrière l'endpoint sentiment-analysis avec le dataset 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
Vous pouvez évaluer un dataset dans Power BI Desktop en suivant les étapes suivantes :
-
Ouvrez le dataset que vous souhaitez évaluer.
-
Accéder à Transformer les données.
-
Faites un clic droit dans le panneau de gauche et sélectionnez Créer une nouvelle query.
-
Accédez à Affichage > Éditeur avancé .
-
Remplacez le corps de la query par l'extrait de code ci-dessous, après avoir renseigné un
DATABRICKS_API_TOKENet unENDPOINT_INVOCATION_URLappropriés.(dataset as table ) as table =>letcall_predict = (dataset as table ) as list =>letapiToken = DATABRICKS_API_TOKEN,modelUri = ENDPOINT_INVOCATION_URL,responseList = Json.Document(Web.Contents(modelUri,[Headers = [#"Content-Type" = "application/json",#"Authorization" = Text.Format("Bearer #{0}", {apiToken})],Content = {"dataframe_records": Json.FromValue(dataset)}]))inresponseList,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")indatasetWithPrediction -
Nommez la requête avec le nom de modèle souhaité.
-
Ouvrez l'éditeur de query avancé pour votre dataset et appliquez la fonction du modèle.
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.
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 format
dataframe_splitest un DataFrame Pandas sérialisé en JSON dans l'orientationsplit.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_recordsest un DataFrame Pandas sérialisé en JSON dans l'orientationrecords.
Ce format ne garantit pas la préservation de l'ordre des colonnes, et le format split est préféré au format records.
{
"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.
{
"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.
-
instancesest 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]]}]} -
inputsEnvoyer 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 det2(3) quet1ett3, il n'est donc pas possible de représenter cette entrée au formatinstances.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.
{
"predictions": [0, 1, 1, 1, 0]
}
Entrée Protobuf tensorielle
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.
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.
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
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 |
|---|---|---|
| Une matrice NumPy de valeurs Python | Texte libre, tel que les titres, les queries et les descriptions. |
| Un tableau de chaînes NumPy à largeur fixe ( | Valeurs courtes de longueur similaire, telles que des codes. |
| Un tableau d'octets NumPy à largeur fixe ( | 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.
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.
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.
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
stroubytes, 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 signatureobjectpour le texte libre et envoyez des fichiers de taille similaire dans la même requête. - Octets zéro finaux : avec une signature
stroubytes, 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.
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.
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.
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 :