查詢提供自定義模型的端點

發行項
05/21/2024

在本文中，瞭解如何格式化服務模型的評分要求，以及如何將這些要求傳送至模型服務端點。本指南與提供 自定義模型有關，Databricks 會定義為傳統 ML 模型或以 MLflow 格式封裝的自定義 Python 模型。它們可以在 Unity 目錄或工作區模型登錄中註冊。範例包括 scikit-learn、XGBoost、PyTorch 和 Hugging 臉部轉換器模型。如需此功能和支援的模型類別的詳細資訊，請參閱使用 Azure Databricks 提供模型。

如需產生 AI 和 LLM 工作負載的查詢要求，請參閱查詢基礎模型。

需求

提供端點的模型。
針對 MLflow 部署 SDK，需要 MLflow 2.9 或更新版本。
接受格式的評分要求。
若要透過 REST API 或 MLflow 部署 SDK 傳送評分要求，您必須有 Databricks API 令牌。

重要

Databricks 是生產案例的安全性最佳做法，建議您在生產期間使用機器對機器 OAuth 令牌進行驗證。

為了測試和開發，Databricks 建議使用屬於服務主體的個人存取令牌，而不是工作區使用者。若要建立服務主體的令牌，請參閱管理服務主體的令牌。

查詢方法和範例

Databricks 模型服務提供下列選項，可將評分要求傳送至服務模型：

方法	詳細資料
提供UI	從 Databricks 工作區中的 [服務端點] 頁面選取 [查詢端點]。插入 JSON 格式模型輸入數據，然後按兩下 [ 傳送要求]。如果模型已記錄輸入範例，請使用顯示範例來載入它。
REST API	使用 REST API 呼叫和查詢模型。如需詳細資訊，請參閱 POST /serving-endpoints/{name}/調用。如需為多個模型服務的端點評分要求，請參閱查詢端點背後的個別模型。
MLflow 部署 SDK	使用 MLflow 部署 SDK 的 predict（）函式來查詢模型。
SQL 函式	使用 SQL 函式直接從 SQL 叫用 `ai_query` 模型推斷。請參閱使用 ai_query（）查詢服務模型。

Pandas DataFrame 評分範例

下列範例假設類似 MODEL_VERSION_URIhttps://<databricks-instance>/model/iris-classifier/Production/invocations，其中 <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]]
    }]
  }'

評分接受張量輸入的模型。 Tensor 輸入的格式應如 TensorFlow 服務 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

重要

下列範例使用 predict() MLflow 部署 SDK 中的 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

使用您想要的模型名稱來命名查詢。
開啟數據集的進階查詢編輯器，並套用模型函式。

Tensor 輸入範例

下列範例會為接受張量輸入的模型評分。 Tensor 輸入的格式應該如 TensorFlow 服務 API 檔中所述。此範例假設類似 MODEL_VERSION_URIhttps://<databricks-instance>/model/iris-classifier/Production/invocations，其中 <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 format 是方向為 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 方向為 JSON 串行化的 Pandas DataFrame records 。

注意

此格式不保證保留資料行順序，而且 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]
}

Tensor 輸入

當您的模型預期張量，例如 TensorFlow 或 Pytorch 模型時，傳送要求有兩個支援的格式選項： instances 和 inputs。

如果您的每個數據列有多個具名張量，則必須針對每個數據列各有一個張量。

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 以單欄格式傳送具有張量的查詢。此要求不同，因為與和 t3實際上有不同數目的t2t1張量實例，因此無法以 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

Tensor 輸入範例

支援的評分格式

Pandas DataFrame

Tensor 輸入

筆記本範例

測試模型服務端點筆記本

其他資源

意見反應

意見反應

其他資源