通过

自定义模型的查询服务终结点

  • 项目

在本文中，你将了解如何为服务的模型设置评分请求的格式，以及如何将这些请求发送到模型服务终结点。 本指南与服务的“自定义模型”相关，Databricks 将其定义为传统的 ML 模型或以 MLflow 格式打包的自定义 Python 模型。 可以在 Unity 目录或工作区模型注册表中注册它们。 示例包括 scikit-learn、XGBoost、PyTorch 和 Hugging Face 转换器模型。 有关此功能和支持的模型类别的详细信息，请参阅 Azure Databricks 的模型服务。

有关生成 AI 和 LLM 工作负载的查询请求，请参阅 查询生成 AI 模型。

要求

重要

作为适用于生产场景的安全最佳做法，Databricks 建议在生产期间使用计算机到计算机 OAuth 令牌来进行身份验证。

对于测试和开发，Databricks 建议使用属于服务主体（而不是工作区用户）的个人访问令牌。 若要为服务主体创建令牌，请参阅管理服务主体的令牌。

查询方法和示例

Mosaic AI 模型服务提供以下选项，可用于向服务的模型发送评分请求：

方法 详细信息
Serving 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 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 中为数据集评分：

  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 或 Tensor 输入中的评分请求。

Pandas 数据帧

请求应通过以下方式发送：使用某个受支持的键和与输入格式对应的 JSON 对象来构造 JSON 序列化 Pandas 数据帧。

  • （推荐）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 数据帧。

    注意

    此格式不保证保留列顺序，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 模型测试模型服务终结点的示例，请参阅以下笔记本：

测试模型服务终结点笔记本

获取笔记本

其他资源