共用方式為

查詢自訂模型的服務端點

  • 發行項

在本文中，了解如何格式化所服務模型的評分要求，以及如何將這些要求傳送至模型服務端點。 此指引與服務自訂模型相關，Databricks 將其定義為傳統 ML 模型或以 MLflow 格式封裝的自訂 Python 模型。 這些模型可以在 Unity Catalog 或工作區模型登錄中註冊。 範例包括 Scikit-learn、XGBoost、PyTorch 和 Hugging Face 轉換器模型。 如需此功能和支援的模型類別的詳細資訊，請參閱透過 Azure Databricks 提供的模型服務。

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

需求

重要

作為生產案例的安全最佳做法，Databricks 建議您在生產期間使用機器對機器 OAuth 權杖進行驗證。

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

查詢方法和範例

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

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

Pandas DataFrame 評分範例

下列範例假設 MODEL_VERSION_URI (如 https://<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]]
    }]
  }'

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

重要

下列範例使用 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() 查詢所服務模型。

下列範例使用 sentiment-analysis 資料集查詢 text 端點後面的模型，並指定要求的傳回類型。

SELECT text, ai_query(
    "sentiment-analysis",
    text,
    returnType => "STRUCT<label:STRING, score:DOUBLE>"
  ) AS predict
FROM
  catalog.schema.customer_reviews

PowerBI

您可以使用下列步驟在 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. 開啟資料集的進階查詢編輯器，並套用模型函數。

張量輸入範例

下列範例為接受張量輸入的模型評分。 張量輸入的格式應如 TensorFlow 服務的 API 文件中所述。此範例假設 MODEL_VERSION_URI (如 https://<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 或張量輸入中的評分要求。

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 模型) 時，有兩個支援的格式選項用於傳送要求：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 以單欄式格式傳送具有張量的查詢。 此要求不同，由於 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 模型測試模型服務端點的範例，請參閱下列筆記本：

測試模型服務端點筆記本

取得筆記本

其他資源