カスタムモデルのサービングエンドポイントをクエリする
この記事では、提供されるモデルのスコアリング リクエストをフォーマットする方法と、それらのリクエストをモデルサービング エンドポイントに送信する方法を学びます。 このガイダンスは、Databricks が従来の機械学習モデルまたは MLflow 形式でパッケージ化されたカスタマイズされた Python モデルとして定義するカスタムモデルの提供に関連しています。 これらは、 Unity Catalogまたはワークスペース モデルレジストリのいずれかに登録できます。 例には、 Scikit-Learn 、XGBoost、PyTorch、および Hugging Face トランスフォーマー モデルが含まれます。 この機能とサポートされているモデル カテゴリの詳細については、「Databricks によるモデルサービング」を参照してください。
生成AI および LLM ワークロードのクエリ要求については、「 クエリ生成AI モデル」を参照してください。
要件
MLflow Deployment SDK には、MLflow 2.9 以降が必要です。
REST API または MLflow デプロイメント SDK を介してスコアリング要求を送信するには、Databricks API トークンが必要です。
重要
オンプレミス運用シナリオのセキュリティのベスト プラクティスとして、 Databricksでは、オンプレミス運用中の認証にマシン間OAuthトークンを使用することをお勧めします。
テストと開発の場合、 Databricksでは、ワークスペース ユーザーではなく、サービスプリンシパルに属する個人用アクセストークンを使用することをお勧めします。 サービスプリンシパルのトークンを作成するには、 「サービスプリンシパルのトークンの管理」を参照してください。
クエリの方法と例
Mosaic AI Model Serving では、サービス提供モデルにスコアリング リクエストを送信するための次のオプションが提供されます。
手法 |
詳細 |
---|---|
UI の提供 |
Databricks ワークスペースの[サービス提供エンドポイント]ページから[クエリ エンドポイント]を選択します。 JSON 形式のモデル入力データを挿入し、 「リクエストの送信」をクリックします。 モデルに入力例がログに記録されている場合は、[ 例を表示 ]を使用して読み込みます。 |
REST API |
REST API を使用してモデルを呼び出し、クエリを実行します。 詳細は、 POST /serving-endpoints/{name}/invocations を参照してください。 複数のモデルを提供するエンドポイントへの要求のスコアリングについては、「 エンドポイントの背後にある個々のモデルをクエリする」を参照してください。 |
MLflow デプロイメント SDK |
MLflow Deployments SDK のdetect()関数を使用してモデルをクエリします。 |
SQL関数 |
|
Pandas DataFrame スコアリングの例
次の例では、 MODEL_VERSION_URI
がhttps://<databricks-instance>/model/iris-classifier/Production/invocations
に似ていることを前提としています。ここで、 <databricks-instance>
Databricks インスタンスの名前であり、 Databricks REST API トークンはDATABRICKS_API_TOKEN
と呼ばれます。
「サポートされているスコアリング形式」を参照してください。
データフレーム分割入力形式を受け入れるモデルをスコア付けします。
curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
-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 $MODEL_VERSION_URI \
-H 'Content-Type: application/json' \
-d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'
重要
次の例では、 MLflow Deployments SDKのpredict()
API を使用します。
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 関数AIを使用します。 この関数は パブリック プレビューであり 、定義は変更される可能性があります。 「 サーブされたモデルを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 でデータセットにスコアを付けることができます。
スコアを付けたいデータセットを開きます。
[データの変換] に移動します。
左側のパネルを右クリックし、[ 新しいクエリの作成]を選択します。
[ View > Advanced Editor (詳細エディターの表示)] に移動します。
クエリ本文を以下のコードスニペットに置き換え、適切な
DATABRICKS_API_TOKEN
と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
クエリに目的のモデル名を付けます。
データセットの高度なクエリ エディターを開き、モデル関数を適用します。
テンソル入力の例
次の例では、テンソル入力を受け入れるモデルをスコアリングします。 Tensor 入力は、 TensorFlow Serving の API ドキュメントで説明されているようにフォーマットする必要があります。 この例では、 MODEL_VERSION_URI
がhttps://<databricks-instance>/model/iris-classifier/Production/invocations
に似ていることを前提としています。ここで、 <databricks-instance>
Databricks インスタンスの名前であり、 Databricks REST API トークンは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]]}'
サポートされているスコアリング形式
カスタム モデルの場合、モデルサービングは Pandas DataFrame または Tensor 入力でのリクエストのスコアリングをサポートします。
Pandas DataFrame
リクエストは、サポートされているキーの 1 つと入力形式に対応する JSON オブジェクトを使用して JSON シリアル化された Pandas DataFrame を構築して送信する必要があります。
(推奨)
dataframe_split
形式は、split
方向の JSON シリアル化された Pandas DataFrame です。{ "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 DataFrame です。注:
この形式では、列の順序が保持される保証はなく、
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モデルなど、モデルがテンソルを必要とする場合、リクエストを送信するためにサポートされている形式オプションが 2 つあります: instances
と inputs
。
行ごとに複数の名前付きテンソルがある場合は、すべての行に各テンソルを1つずつ持つ必要があります。
instances
は、テンソルを行形式で受け入れるテンソルベースの形式です。 すべての入力テンソルの次元が同じ 0 番目の次元である場合に、この形式を使用します。 概念的には、インスタンスリスト内の各テンソルをリストの残りの部分の同じ名前の他のテンソルと結合して、モデルの完全な入力テンソルを構築できますが、これはすべてのテンソルが同じ0番目の次元を持つ場合にのみ可能です。{"instances": [ 1, 2, 3 ]}
次の例は、複数の名前付きテンソルを指定する方法を示しています。
{ "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
形式で表すことはできません。{ "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]
}