カスタムモデルのクエリサービスエンドポイント
このページでは、提供されたモデルのスコアリングリクエストをフォーマットする方法、およびそれらのリクエストをモデルサービングエンドポイントに送信する方法について説明します。このガイダンスは、Databricks が従来の機械学習モデルまたは MLflow 形式でパッケージ化されたカスタマイズされたPythonモデルとして定義する カスタムモデル の提供に関連しています。モデルはUnity Catalogに登録する必要があります。例としては、scikit-learn、XGBoost、PyTorch、Hugging Faceトランスフォーマーモデルなどがあります。この機能とサポートされているモデルカテゴリの詳細については、Model Servingを使用したモデルのデプロイを参照してください。
AI および LLM ワークロードのクエリー リクエストについては、「基盤モデルの使用」を参照してください。
エンドポイントで**ルート最適化**が有効になっている場合、このページで説明されている認証フローと呼び出し URL は適用されません。ルート最適化エンドポイントは OAuth トークンのみを受け入れ(個人用アクセストークンではない)、専用の URL でクエリを実行する必要があります。コピーして貼り付け可能なエンドツーエンドのレシピやトラブルシューティングなど、詳細なフローについては、クエリールート最適化サービングエンドポイントを参照してください。
必要条件
- モデルサービング エンドポイント。
- MLflow Deployment SDK には、MLflow 2.9 以降が必要です。
- 受け入れられた形式での採点リクエスト。
- REST API または MLflow Deployment SDK を使用してスコアリング要求を送信するには、Databricks API トークンが必要です。
クエリの方法と例
モデルサービングでは、サービング対象モデルにスコアリングリクエストを送信するための以下のオプションが提供されます。
手法 | 詳細 |
|---|---|
サービング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) を想定しています。
サポートされているスコアリング形式を参照してください。
- REST API
- MLflow Deployments SDK
- SQL
- PowerBI
データフレーム分割入力形式を受け入れるモデルをスコア付けします。
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 ドキュメントで説明されているように形式設定する必要があります。
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]]}'
次の例では、MLflow Deployments SDK の predict() API を使用しています。
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]]
}
}
)
次の例では、組み込み SQL 関数 ai_query を使用しています。この機能は パブリック プレビュー 段階であり、定義は変更される可能性があります。
次の例では、text データセットを使用して sentiment-analysis エンドポイントの背後にあるモデルに対してクエリを実行し、要求の戻り値の型を指定します。
SELECT text, ai_query(
"sentiment-analysis",
text,
returnType => "STRUCT<label:STRING, score:DOUBLE>"
) AS predict
FROM
catalog.schema.customer_reviews
Power BI Desktop でデータセットをスコアリングするには、次の手順を使用します。
-
スコアリングするデータセットを開きます。
-
[データの変換] に移動します。
-
左側のパネルを右クリックし、[ 新しいクエリの作成 ] を選択します。
-
[詳細エディター> [表示 ] に移動します。
-
適切な
DATABRICKS_API_TOKENを入力してENDPOINT_INVOCATION_URLに入力した後、クエリ本文を次のコードスニペットに置き換えます。(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 -
クエリに目的のモデル名を付けます。
-
データセットの高度なクエリ エディターを開き、モデル関数を適用します。
テンソル入力の例
次の例では、テンソル入力を受け入れるモデルをスコアリングします。Tensor 入力は、 TensorFlow Serving の API ドキュメントで説明されているようにフォーマットする必要があります。この例では、https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocationsのようなENDPOINT_INVOCATION_URL (<databricks-instance> は Databricks インスタンスの名前、Databricks REST API トークンは 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]]}'
サポートされているスコアリング形式
カスタムモデルの場合、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形式が優先されます。
{
"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 キーでラップされます。
{
"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]]]}}
エンドポイントからの応答は、次の形式です。
{
"predictions": [0, 1, 1, 1, 0]
}
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リクエスト本文を作成する方法を示しています。
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です。
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 入力に対してモデルが受け取るものを決定します。
シグネチャタイプ | モデルが受け取るもの | ~に使用 |
|---|---|---|
| UTF-8 からデコードされた Python | タイトル、クエリー、説明などの自由形式のテキスト。 |
| 固定幅の NumPy 文字列配列 ( | コードなど、類似の長さの短い値。 |
| Rawバイトを保持する固定幅のNumPyバイト配列( | ファイルおよびその他のバイナリデータ。Protobuf リクエストでファイルを送信するを参照してください。 |
次の例では、テキスト入力と数値入力を行うモデルをLogsします。テキスト入力は object として宣言し、1 つの長い値がリクエスト内の他のすべての値をパディングしないようにします。
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クライアントも同様のヘルパーを提供しています。
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として返されます。
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します。
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バイト配列は使用しないでください。各値から末尾のゼロバイトが削除されます。
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バイト追加されます。
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 モデルを使用してモデルサービングエンドポイントをテストする方法の例については、次のノートブックを参照してください。