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

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

有关生成 AI 和 LLM 工作负载的查询请求,请参阅 “使用基础模型”。

要求

重要

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

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

查询方法和示例

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

方法 详细信息
服务 UI 从 Databricks 工作区的“服务终结点”页中选择“查询终结点”。 插入 JSON 格式的模型输入数据,然后单击“发送请求”。 如果模型记录了输入示例,请使用“显示示例”来加载该示例。
SQL 函数 使用 ai_query SQL 函数直接从 SQL 调用模型推理。 请参阅 ai_query 函数
REST API 使用 REST API 调用和查询模型。 有关详细信息,请参阅 POST /serving-endpoints/{name}/invocations。 有关为多个模型提供服务的终结点的评分请求,请参阅查询终结点背后的单个模型
MLflow 部署 SDK 使用 MLflow 部署 SDK 的 predict() 函数查询模型。

Pandas DataFrame 评分示例

下面的示例假设一个MODEL_VERSION_URI类似https://<databricks-instance>/model/iris-classifier/Production/invocations<databricks-instance>是您的Databricks 实例的名称,还有一个名为DATABRICKS_API_TOKEN

请参阅支持的评分格式

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

重要

以下示例使用 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]]
                    }
                }
          )

PowerBI

可以使用以下步骤在 Power BI Desktop 中为数据集评分:

  1. 打开要评分的数据集。

  2. 转到“转换数据”。

  3. 在左侧面板中右键单击并选择“ 创建新查询”。

  4. 转到“视图>高级编辑器”。

  5. 填写适当的 DATABRICKS_API_TOKENMODEL_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. 打开你的数据集的高级查询编辑器,并应用模型函数。

张量输入示例

以下示例对接受张量输入的模型进行评分。 Tensor 输入的格式应按照 TensorFlow Serving 的 API 文档中所描述的设置。本示例假设一个MODEL_VERSION_URI类似https://<databricks-instance>/model/iris-classifier/Production/invocations,其中 <databricks-instance>是您的Databricks 实例的名称,而 是称为DATABRICKS_API_TOKEN的名称。

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_recordsrecords 方向的 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 模型)时,有两个受支持的格式选项用于发送请求:instancesinputs

如果每行有多个命名张量,则每行必须有其中一个张量。

  • 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) 的张量实例的数量实际上与 t1t3 不同,因此不可能用 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 模型测试模型服务终结点的示例,请参阅以下笔记本:

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

获取笔记本

其他资源