メインコンテンツまでスキップ

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

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

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

必要条件​

important

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

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

クエリの方法と例​

Mosaic AI Model Serving は、提供されたモデルにスコアリングリクエストを送信するための次のオプションを提供します。

メソッド

詳細

サービングUI

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

SQL 関数

ai_query SQL 関数を使用して、SQL から直接モデル推論を呼び出します。ai_query関数を参照してください。

REST API

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

MLflow デプロイ SDK

MLflow Deployments SDK の predict() 関数を使用して、モデルに対してクエリを実行します。

Pandas データフレーム のスコアリングの例​

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

サポートされているスコアリング形式を参照してください。

Score a model accepting dataframe split input format.

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

Score a model accepting tensor inputs. Tensor inputs should be formatted as described in TensorFlow Serving’s API documentation.

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

テンソル入力の例​

次の例では、テンソル入力を受け入れるモデルをスコアリングします。 Tensor 入力は、 TensorFlow Serving の API ドキュメントで説明されているようにフォーマットする必要があります。 この例では、https://<databricks-instance>/model/iris-classifier/Production/invocationsのようなMODEL_VERSION_URI (<databricks-instance> は Databricks インスタンスの名前、Databricks REST API トークンは DATABRICKS_API_TOKEN) を想定しています。

Bash
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 データフレーム またはTensor入力でのスコアリングリクエストをサポートします。

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形式が優先されます。

JSON
{
  "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 キーでラップされます。

JSON
{
  "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]
          ]
        ]
      }
    }

エンドポイントからの応答は、次の形式です。

JSON
{
  "predictions": [0, 1, 1, 1, 0]
}

ノートブックの例​

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

Test モデルサービング endpoint ノートブック

Open notebook in new tab

追加のリソース​

に最終更新