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

この記事では、提供されるモデルのスコアリング リクエストをフォーマットする方法と、それらのリクエストをモデルサービング エンドポイントに送信する方法を学びます。 このガイダンスは、Databricks が従来の機械学習モデルまたは MLflow 形式でパッケージ化されたカスタマイズされた Python モデルとして定義するカスタムモデルの提供に関連しています。 これらは、 Unity Catalogまたはワークスペース モデルレジストリのいずれかに登録できます。 例には、 Scikit-Learn 、XGBoost、PyTorch、および Hugging Face トランスフォーマー モデルが含まれます。 この機能とサポートされているモデル カテゴリの詳細については、「Databricks によるモデルサービング」を参照してください。

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

要件

重要

オンプレミス運用シナリオのセキュリティのベスト プラクティスとして、 Databricksでは、オンプレミス運用中の認証にマシン間OAuthトークンを使用することをお勧めします。

テストと開発の場合、 Databricksでは、ワークスペース ユーザーではなく、サービスプリンシパルに属する個人用アクセストークンを使用することをお勧めします。 サービスプリンシパルのトークンを作成するには、 「サービスプリンシパルのトークンの管理」を参照してください。

クエリの方法と例

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

手法

詳細

UI の提供

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

REST API

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

MLflow デプロイメント SDK

MLflow Deployments SDK のdetect()関数を使用してモデルをクエリします。

SQL関数

ai_query SQL 関数を使用して、SQL からモデル推論を直接呼び出します。 「 ai_query() を使用して提供されたモデルをクエリする」を参照してください。

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": [{
     "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]]
    }]
  }'

テンソル入力を受け入れるモデルをスコアリングします。 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 でデータセットにスコアを付けることができます。

  1. スコアを付けたいデータセットを開きます。

  2. [データの変換] に移動します。

  3. 左側のパネルを右クリックし、[ 新しいクエリの作成]を選択します。

  4. [ View > Advanced Editor (詳細エディターの表示)] に移動します。

  5. クエリ本文を以下のコードスニペットに置き換え、適切な 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

  6. クエリに目的のモデル名を付けます。

  7. データセットの高度なクエリ エディターを開き、モデル関数を適用します。

テンソル入力の例

次の例では、テンソル入力を受け入れるモデルをスコアリングします。 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]
}

ノートブックの例

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

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

ノートブックを新しいタブで開く