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

[アーティクル]
06/24/2024

この記事では、提供されたモデルのスコアリング要求を書式設定する方法と、それらの要求をモデル提供エンドポイントに送信する方法について説明します。このガイダンスは、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 モデルを使用してモデルサービスエンドポイントをテストする方法の例については、以下のノートブックを参照してください:

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

ノートブックを入手

次の方法で共有

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

要件

クエリの方法と例

Pandas DataFrame スコアリングの例

REST API

MLflow デプロイ SDK

SQL

PowerBI

テンソル入力の例

サポートされているスコアリング形式

Pandas DataFrame

テンソル入力

ノートブックの例

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

その他のリソース

フィードバック

フィードバック

その他のリソース

次の方法で共有

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

要件

クエリの方法と例

Pandas DataFrame スコアリングの例

REST API

MLflow デプロイ SDK

SQL

PowerBI

テンソル入力の例

サポートされているスコアリング形式

Pandas DataFrame

テンソル入力

ノートブックの例

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

その他のリソース

フィードバック

フィードバック

その他のリソース

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

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