メインコンテンツまでスキップ

カスタムモデルのクエリサービスエンドポイント

このページでは、提供されたモデルのスコアリングリクエストをフォーマットする方法、およびそれらのリクエストをモデルサービングエンドポイントに送信する方法について説明します。このガイダンスは、Databricks が従来の機械学習モデルまたは MLflow 形式でパッケージ化されたカスタマイズされたPythonモデルとして定義する カスタムモデル の提供に関連しています。モデルはUnity Catalogに登録する必要があります。例としては、scikit-learn、XGBoost、PyTorch、Hugging Faceトランスフォーマーモデルなどがあります。この機能とサポートされているモデルカテゴリの詳細については、Model Servingを使用したモデルのデプロイを参照してください。

AI および LLM ワークロードのクエリー リクエストについては、「基盤モデルの使用」を参照してください。

警告

エンドポイントで**ルート最適化**が有効になっている場合、このページで説明されている認証フローと呼び出し URL は適用されません。ルート最適化エンドポイントは OAuth トークンのみを受け入れ(個人用アクセストークンではない)、専用の URL でクエリを実行する必要があります。コピーして貼り付け可能なエンドツーエンドのレシピやトラブルシューティングなど、詳細なフローについては、クエリールート最適化サービングエンドポイントを参照してください。

必要条件​

クエリの方法と例​

モデルサービングでは、サービング対象モデルにスコアリングリクエストを送信するための以下のオプションが提供されます。

手法

詳細

サービングUI

Databricks ワークスペースの サービス エンドポイント ページから クエリ エンドポイント を選択します。JSON形式のモデル入力データを挿入し、[ リクエストを送信 ]をクリックします。 モデルに入力例がログに記録されている場合は、[ 例を表示 ] を使用して読み込みます。

REST API

REST API を使用してモデルを呼び出し、クエリを実行します。 詳細は POST /serving-endpoints/{name}/invocations を参照してください。 複数のモデルを提供するエンドポイントへの要求のスコアリングについては、 エンドポイントの背後にある個々のモデルのクエリを参照してください。

MLflow Deployments SDK

MLflow Deployments SDK の predict() 関数を使用して、モデルに対してクエリを実行します。

手法

詳細

サービングUI

Databricks ワークスペースの サービス エンドポイント ページから クエリ エンドポイント を選択します。JSON形式のモデル入力データを挿入し、[ リクエストを送信 ]をクリックします。 モデルに入力例がログに記録されている場合は、[ 例を表示 ] を使用して読み込みます。

REST API

REST API を使用してモデルを呼び出し、クエリを実行します。 詳細は POST /serving-endpoints/{name}/invocations を参照してください。 複数のモデルを提供するエンドポイントへの要求のスコアリングについては、 エンドポイントの背後にある個々のモデルのクエリを参照してください。

MLflow Deployments SDK

MLflow Deployments SDK の predict() 関数を使用して、モデルに対してクエリを実行します。

Pandas データフレーム のスコアリングの例​

次の例では、 https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocationsのようなENDPOINT_INVOCATION_URL (<databricks-instance> は Databricks インスタンスの名前、Databricks REST API トークンは DATABRICKS_API_TOKEN) を想定しています。

サポートされているスコアリング形式を参照してください。

データフレーム分割入力形式を受け入れるモデルをスコア付けします。

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]]
}]
}'

テンソル入力を受け入れるモデルをスコアリングします。Tensor 入力は、 TensorFlow Serving の API ドキュメントで説明されているように形式設定する必要があります。

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]]}'

テンソル入力の例​

次の例では、テンソル入力を受け入れるモデルをスコアリングします。Tensor 入力は、 TensorFlow Serving の API ドキュメントで説明されているようにフォーマットする必要があります。この例では、https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocationsのようなENDPOINT_INVOCATION_URL (<databricks-instance> は Databricks インスタンスの名前、Databricks REST API トークンは 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]]}'

サポートされているスコアリング形式​

カスタムモデルの場合、Model Servingは、Pandas DataFrame(JSON)またはテンソル入力(JSONまたはProtobuf)でのスコアリングリクエストをサポートしています。

Pandas データフレーム​

リクエストを送信するには、サポートされているキーの 1 つと、入力形式に対応する JSON オブジェクトを使用して、JSON でシリアル化された Pandas データフレーム を構築する必要があります。

  • (推奨)dataframe_split 形式は、 split 方向の JSON シリアル化された Pandas データフレーム です。

    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 は、 records 方向の JSON シリアル化された Pandas データフレーム です。

注記

この形式は、列の順序の保持を保証するものではなく、records形式よりもsplit形式が優先されます。

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
}
]
}

エンドポイントからの応答には、モデルからの出力が含まれ、JSON でシリアル化され、 predictions キーでラップされます。

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

テンソル入力​

モデルがテンソルを想定する場合 ( TensorFlow モデルや PyTorch モデルなど)、リクエストの送信には instances と inputs の 2 つの形式オプションがサポートされています。

行ごとに複数の名前付きテンソルがある場合は、各行に各テンソルを1つずつ持つ必要があります。

  • instances は、行形式のテンソルを受け入れるテンソルベースの形式です。 すべての入力テンソルの 0 番目の次元が同じ場合は、この形式を使用します。 概念的には、インスタンスリストの各テンソルをリストの残りの部分にある同じ名前の他のテンソルと結合して、モデルの完全な入力テンソルを構築できますが、これはすべてのテンソルが同じ0次元を持つ場合にのみ可能です。

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

    次の例は、複数の名前付きテンソルを指定する方法を示しています。

    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 テンソルを含むクエリを列形式で送信します。 このリクエストは、実際には t2 (3) のテンソルインスタンスの数が t1 や t3とは異なるため、この入力を 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]
    ]
    ]
    }
    }

エンドポイントからの応答は、次の形式です。

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

Protobufテンソル入力​

備考

プレビュー

この機能はパブリック プレビュー段階であり、2026年7月9日以降にデプロイされたEndpointでのみ利用可能です。

Protobuf リクエストは推論テーブルには記録されません。

テンソルベースの入力シグネチャを持つモデルの場合、Content-Type: application/x-protobufまたはapplication/vnd.kserve.protobufを使用して、JSONの代わりに、シリアル化されたKServe v2 ModelInferRequestとしてリクエストボディを送信できます。これにより、JSONテキストから数値テンソルを解析することが回避されるため、特に大きなペイロードの場合に高速です。Endpoint URLと認証は変更されていません。

サポートされているテンソルデータ型は BOOL、UINT8、UINT16、UINT32、UINT64、INT8、INT16、INT32、INT64、FP16、FP32、FP64、および BYTES です。BYTES テンソルのテキストおよびバイナリデータの詳細については、Protobuf リクエストでのテキストおよびバイナリ入力を参照してください。

inputsと同じ順序で、raw_input_contentsの各入力のデータを送信します。fp32_contentsなどの型付きcontentsフィールドにテンソルデータを配置するリクエストは、HTTP 400で失敗します。

次の例は、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()

応答は、raw_output_contentsにテンソルデータを含むシリアル化されたModelInferResponseです。

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

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

protobufリクエストのテキストおよびバイナリ入力​

注記

BYTES テンソルは、2026年11月10日以降にデプロイされたEndpointで利用可能です。以前にデプロイされたEndpointで使用するには、Endpointで新しいモデルバージョンを提供します。

BYTES テンソルは、テキストやファイルのコンテンツなど、可変長の値を保持します。リクエストは、例えば各行のタイトルと特徴量ベクトルなど、BYTES テンソルと数値テンソルを組み合わせることができます。raw_input_contents の各 BYTES 値は、KServe v2プロトコルで定義されているように、4バイトのリトルエンディアン長の後に値のバイトが続く形式です。

モデルの入力シグネチャは、各 BYTES 入力に対してモデルが受け取るものを決定します。

シグネチャタイプ

モデルが受け取るもの

~に使用

object

UTF-8 からデコードされた Python str 値の NumPy 配列。各値は独自のサイズを保持します。

タイトル、クエリー、説明などの自由形式のテキスト。

str

固定幅の NumPy 文字列配列 (<U)。すべての値は、リクエストで最も長い値にパディングされます(文字ごとに4バイト)。

コードなど、類似の長さの短い値。

bytes

Rawバイトを保持する固定幅のNumPyバイト配列(S)。すべての値は、リクエスト内の最長の値にパディングされます。

ファイルおよびその他のバイナリデータ。Protobuf リクエストでファイルを送信するを参照してください。

シグネチャタイプ

モデルが受け取るもの

~に使用

object

UTF-8 からデコードされた Python str 値の NumPy 配列。各値は独自のサイズを保持します。

タイトル、クエリー、説明などの自由形式のテキスト。

str

固定幅の NumPy 文字列配列 (<U)。すべての値は、リクエストで最も長い値にパディングされます(文字ごとに4バイト)。

コードなど、類似の長さの短い値。

bytes

Rawバイトを保持する固定幅のNumPyバイト配列(S)。すべての値は、リクエスト内の最長の値にパディングされます。

ファイルおよびその他のバイナリデータ。Protobuf リクエストでファイルを送信するを参照してください。

次の例では、テキスト入力と数値入力を行うモデルをLogsします。テキスト入力は object として宣言し、1 つの長い値がリクエスト内の他のすべての値をパディングしないようにします。

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",
)

リクエストを構築するには、dtype=objectを含む NumPy 配列にテキスト値とバイナリ値を入れて、tritonclientからserialize_byte_tensorでエンコードします。他のKServe v2クライアントも同様のヘルパーを提供しています。

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()

文字列の配列やリストなどのテキストおよびバイナリ出力(str、bytes、objectなど)は、BYTESテンソルとして返されます。各値は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"]]

テキストと数値の両方の列を持つpandas DataFrameを返すモデルは、protobuf要求に対してHTTP 500で失敗します。代わりに、前述の例のように、 NumPy 配列の辞書を返します。

テキストおよびバイナリ入力には、次の制限があります:

  • デコードされたサイズ : 1つのリクエスト内のテキスト値とバイナリ値は、デコード後に最大256 MiBを占有できます。strまたはbytesシグネチャでは、すべての値がリクエスト内で最も長い値にパディングされるため、1つの長い値によってリクエストが制限を超える可能性があります。制限を超えたリクエストはHTTP 400で失敗します。自由テキストにはobjectシグネチャを使用し、同じリクエストで同サイズのファイルを送信してください。
  • 末尾のゼロバイト :str または bytes シグネチャを使用する場合、末尾がゼロバイト (0x00) の値は HTTP 400 で失敗します。これは、固定幅の NumPy 配列が末尾のゼロバイトを削除するためです。末尾がゼロバイトのファイルを送信するには、Protobufリクエストでファイルを送信するを参照してください。
  • 要求サイズ : Protobuf 要求には、 JSON 要求と同じ 16 MB のサイズ制限があります。モデルサービングの制限と地域を参照してください。
  • パフォーマンス :数値テンソルはNumPy配列に直接コピーされますが、テキスト値はJSON解析とほぼ同じ速度で一度に1つずつデコードされます。ほとんどがテキストのリクエストでは、JSONに比べてスピードアップはほとんど見られません。

protobufリクエストでファイルを送信する​

BYTES テンソルは、画像、音声、ドキュメントなど、行ごとにサイズが異なるファイルを保持できます。bytes 入力シグネチャを使用して、ファイルごとに 1 つのファイルを raw バイトとして送信します。モデルは各ファイルの正確なバイト数を受け取り、デコードします。JSONリクエストはバイナリデータをbase64テキストとしてしか保持できず、約33%大きくなります。

一般的な用途には次のようなものがあります。

  • 画像 :JPEGファイルまたはPNGファイルを画像分類、検出、または埋め込みモデルに送信すると、それらがデコードおよびリサイズされます。GPU endpointでは、モデルはGPU上で画像をデコードできます。
  • オーディオ :WAV、FLAC、またはMP3ファイルを音声認識モデルまたは音声分類モデルに送信します。
  • ドキュメント : PDFファイルやその他のドキュメントを解析モデルや抽出モデルに送信します。
  • シリアル化されたレコード : モデルが読み取る Parquet ファイルまたはその他のシリアル化されたデータを送信します。

デコードされたピクセルやオーディオサンプルなど、各行のサイズが固定されているデータを送信する場合は、代わりに UINT8 や FP32 などの数値テンソルとして送信してください。

次の例は、画像ファイルを読み込み、各画像のサイズを返すモデルをLogsします。

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"],
)

ファイルを送信するには、各ファイルをdtype=objectを使用してNumPy配列に読み込みます。固定幅のNumPyバイト配列は使用しないでください。各値から末尾のゼロバイトが削除されます。

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()

bytes シグネチャの場合、ゼロバイトで終わるファイルは HTTP 400 で失敗します。JPEG、 PNG、 PDF、 Parquetファイルは固定マーカーで終わるため、そのまま送信できます。DOCXや XLSX、 gzipファイル、および一部のオーディオ ファイルやビデオ ファイルなどのZIPベースのファイルは、ゼロバイトで終わる場合があります。これらのファイルを送信するには、クライアントで各ファイルをエンコードし、モデルでデコードします。Base64でエンコードすると、各ファイルのサイズが約33%増加します。1つのゼロ以外のバイトを追加すると、1バイト追加されます。

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)

ノートブックの例​

Python モデルを使用してモデルサービングエンドポイントをテストする方法の例については、次のノートブックを参照してください。

モデルサービング エンドポイントテスト用 ノートブック

追加のリソース​