通过

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

在本文中，你将了解如何为服务的模型设置评分请求的格式，以及如何将这些请求发送到模型服务终结点。 本指南与服务的“自定义模型”相关，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_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. 打开你的数据集的高级查询编辑器，并应用模型函数。

张量输入示例

以下示例对接受张量输入的模型进行评分。 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_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 模型测试模型服务终结点的示例，请参阅以下笔记本：

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

获取笔记本

其他资源