カスタム モデルのエンドポイントを提供するクエリ
この記事では、提供されたモデルのスコアリング要求を書式設定する方法と、それらの要求をモデル提供エンドポイントに送信する方法について説明します。 このガイダンスは、Databricks が MLflow 形式でパッケージ化された従来の ML モデルまたはカスタマイズされた Python モデルとして定義するカスタム モデルの提供に関連しています。 これらは、Unity Catalog またはワークスペース モデル レジストリに登録できます。 たとえば、scikit-learn、XGBoost、PyTorch、Hugging Face トランスフォーマー モデルなどがあります。 この機能とサポートされるモデル カテゴリの詳細については、「Azure Databricks でのモデルの提供」をご覧ください。
生成 AI と LLM ワークロードのクエリ要求については、「基盤モデルと外部モデルに対してクエリを実行する」を参照してください。
要件
- モデルの提供のエンドポイント。
- MLflow デプロイ 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 の predict() 関数を使用します。 |
SQL 関数 | SQL 関数の ai_query を使用して、SQL から直接モデル推論を呼び出します。 「ai_query() を使用した提供モデルに対するクエリの実行」を参照してください。 |
Pandas DataFrame スコアリングの例
次の例では、https://<databricks-instance>/model/iris-classifier/Production/invocations
のような MODEL_VERSION_URI
(<databricks-instance>
は Databricks インスタンスの名前です) と、DATABRICKS_API_TOKEN
という名前の Databricks REST API トークンを想定しています。
「サポートされているスコアリング形式」をご覧ください。
REST API
データフレーム分割入力形式を受け入れるモデルをスコア付けします。
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]]
}]
}'
テンソル入力を受け付けるモデルをスコアリングします。 テンソル入力は、「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 デプロイ SDK
重要
次の例では、MLflow デプロイ 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
重要
次の例では、組み込みの SQL 関数である ai_query を使用します。 この関数はパブリック プレビューであり、定義が変更される可能性があります。 「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
PowerBI
次の手順を使用して、Power BI Desktop でデータセットをスコア付けできます。
スコア付けするデータセットを開きます。
[データの変換] に移動します。
左側のパネルを右クリックし、[新しいクエリの作成] を選択します。
[ビュー > 詳細エディター] へ移動します。
適切な
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
希望するモデル名でクエリに名前を付けます。
データセットの詳細クエリ エディターを開き、モデル関数を適用します。
テンソル入力の例
次の例では、テンソル入力を受け取るモデルをスコア付けします。 テンソル入力は、「TensorFlow Serving の API ドキュメント」の説明に従って書式設定する必要があります。この例では、https://<databricks-instance>/model/iris-classifier/Production/invocations
のような MODEL_VERSION_URI
(<databricks-instance>
は Databricks インスタンスの名前です) と、DATABRICKS_API_TOKEN
という名前の Databricks REST 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]]}'
サポートされているスコアリング形式
カスタム モデルの場合、モデル提供では Pandas DataFrame または Tensor 入力でのスコア付け要求をサポートします。
Pandas DataFrame
要求は、サポートされているいずれかのキーと、入力形式に対応した 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 です。Note
この形式では列の順序が保持される保証はないため、
split
形式よりも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 } ] }
エンドポイントからの応答には、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]
}
ノートブックの例
Python モデルを使用してモデル サービス エンドポイントをテストする方法の例については、以下のノートブックを参照してください: