カスタム モデルのエンドポイントを提供するクエリ

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

生成 AI と LLM ワークロードのクエリ要求については、「 基礎モデルの使用」を参照してください。

要件

• モデルの提供のエンドポイント。
• MLflow デプロイ SDK のためには、MLflow 2.9 以上が必要です。
• 受け入れられる形式でのスコアリング要求。
• REST API または MLflow デプロイ SDK を介してスコアリング要求を送信するには、Databricks API トークンが必要です。

クエリの方法と例

Mosaic AI Model Serving には、提供モデルにスコアリング要求を送信するための以下のオプションが用意されています。

Pandas DataFrame スコアリングの例

次の例では、MODEL_VERSION_URI のような https://<databricks-instance>/model/iris-classifier/Production/invocations (<databricks-instance> は Databricks インスタンスの名前です) と、 という名前の DATABRICKS_API_TOKEN トークンを想定しています。

「サポートされているスコアリング形式」をご覧ください。

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

テンソル入力を受け付けるモデルをスコアリングします。 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 デプロイ SDK

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

パワーBI

次の手順を使用して、Power BI Desktop でデータセットをスコア付けできます。

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

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

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

4. [ビュー > 詳細エディター] へ移動します。

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

要求は、サポートされているいずれかのキーと、入力形式に対応した 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 です。

  注

  この形式では列の順序が保持される保証はないため、 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 モデルを使用してモデル サービング エンドポイントをテストする方法の例については、以下のノートブックを参照してください:

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

ノートブックを入手

その他のリソース

• モデルの監視とデバッグのための推論テーブル。
• 基礎モデルを使用します。
• モデル サービスのデバッグ ガイド。