Ponto de extremidade de serviço de consulta para modelos personalizados

Neste artigo, o senhor aprenderá a formatar solicitações de pontuação para o modelo atendido e a enviar essas solicitações para o modelo atendido endpoint. A orientação é relevante para a veiculação de modelos personalizados , que o site Databricks define como modelos ML tradicionais ou modelos Python personalizados no formato MLflow. Eles podem ser registrados em Unity Catalog ou no workspace registro de modelo. Os exemplos incluem os modelos de transformadores scikit-learn, XGBoost, PyTorch e Hugging Face. Consulte modelos implantados usando Mosaic AI Model Serving para obter mais informações sobre essa funcionalidade e as categorias de modelos suportadas.

Para solicitações de consulta para cargas de trabalho generativas AI e LLM, consulte Usar modelos básicos.

Requisitos

• A servindo o modelo endpoint.
• Para o MLflow Deployment SDK, é necessário o MLflow 2.9 ou o acima.
• Solicitação de pontuação em um formato aceito.
• Para enviar uma solicitação de pontuação por meio do REST API ou MLflow Deployment SDK, o senhor deve ter um token Databricks API .

important

Como prática recomendada de segurança para cenários de produção, a Databricks recomenda que o senhor use tokens OAuth máquina a máquina para autenticação durante a produção.

Para testes e desenvolvimento, o site Databricks recomenda o uso de tokens de acesso pessoal pertencentes à entidade de serviço em vez de usuários do site workspace. Para criar tokens o site para uma entidade de serviço, consulte gerenciar tokens para uma entidade de serviço.

Métodos e exemplos de consulta

O Mosaic AI Model Serving oferece as seguintes opções para o envio de solicitações de pontuação para modelos atendidos:

Método	Detalhes
UI de serviço	Selecione Query endpoint na página Serving endpoint em seu site Databricks workspace. Insira os dados de entrada do modelo no formato JSON e clique em Send Request (Enviar solicitação ). Se o modelo tiver um registro de exemplo de entrada, use Show Example para carregá-lo.
Função SQL	Invoque a inferência do modelo diretamente do SQL usando a função ai_query SQL. Veja a funçãoai_query.
API REST	Chamar e consultar o modelo usando a API REST. Consulte POST /serving-endpoint/{name}/invocations para obter detalhes. Para solicitações de pontuação para o endpoint que atende a vários modelos, consulte Consultar modelos individuais em endpoint.
SDK de implantações do MLflow	Use a função predict() do MLflow Deployments SDK para consultar o modelo.

Exemplo de pontuação do Pandas DataFrame

O exemplo a seguir pressupõe um MODEL_VERSION_URI como https://<databricks-instance>/model/iris-classifier/Production/invocations, em que <databricks-instance> é o nome da sua instância Databricks, e um Databricks REST API tokens chamado DATABRICKS_API_TOKEN.

Consulte Formatos de pontuação suportados.

REST API

Score a model accepting dataframe split input format.

Bash

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]]
    }]
  }'

Score a model accepting tensor inputs. Tensor inputs should be formatted as described in TensorFlow Serving’s API documentation.

Bash

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 Deployments SDK

important

The following example uses the predict() API from the MLflow Deployments SDK.

Python

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

You can score a dataset in Power BI Desktop using the following steps:

1. Open dataset you want to score.

2. Go to Transform Data.

3. Right-click in the left panel and select Create New Query.

4. Go to View > Advanced Editor.

5. Replace the query body with the code snippet below, after filling in an appropriate DATABRICKS_API_TOKEN and 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. Name the query with your desired model name.

7. Open the advanced query editor for your dataset and apply the model function.

Exemplo de entrada de tensor

O exemplo a seguir pontua um modelo que aceita entradas de tensor. As entradas do Tensor devem ser formatadas conforme descrito nos documentos da API do TensorFlow Serving. Este exemplo pressupõe um MODEL_VERSION_URI como https://<databricks-instance>/model/iris-classifier/Production/invocations, em que <databricks-instance> é o nome da sua instância Databricks, e um Databricks REST API tokens chamado DATABRICKS_API_TOKEN.

Bash

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]]}'

Formatos de pontuação suportados

Para modelos personalizados, o servindo modelo suporta solicitações de pontuação em Pandas DataFrame ou entrada Tensor.

Pandas DataFrame

As solicitações devem ser enviadas por meio da construção de um JSON-serializado Pandas DataFrame com uma das chaves compatíveis e um objeto JSON correspondente ao formato de entrada.

• (Recomendado) O formatodataframe_split é um Pandas DataFrame serializado em JSON na orientação split.

  JSON

  {
    "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 é um Pandas DataFrame serializado em JSON na orientação records.

nota

Esse formato não garante a preservação da ordem das colunas, e o formato split é preferível ao formato records.

JSON

{
  "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
    }
  ]
}

A resposta do endpoint contém a saída do seu modelo, serializada com JSON, envolvida em um predictions key.

JSON

{
  "predictions": [0, 1, 1, 1, 0]
}

Entrada de tensor

Quando seu modelo espera tensores, como um modelo TensorFlow ou PyTorch, há duas opções de formato compatíveis para o envio de solicitações: instances e inputs.

Se você tiver vários tensores nomeados por linha, precisará ter um de cada tensor para cada linha.

• instances é um formato baseado em tensores que aceita tensores em formato de linha. Use esse formato se todos os tensores de entrada tiverem a mesma dimensão 0. Conceitualmente, cada tensor na lista de instâncias poderia ser unido aos outros tensores de mesmo nome no restante da lista para construir o tensor de entrada completo para o modelo, o que só seria possível se todos os tensores tivessem a mesma dimensão 0.

  JSON

  { "instances": [1, 2, 3] }

  O exemplo a seguir mostra como especificar vários tensores nomeados.

  JSON

  {
    "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 envie consultas com tensores em formato colunar. Essa solicitação é diferente porque, na verdade, há um número diferente de instâncias de tensor de t2 (3) do que t1 e t3, portanto, não é possível representar essa entrada no formato instances.

  JSON

  {
    "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]
        ]
      ]
    }
  }

A resposta do endpoint está no seguinte formato.

JSON

{
  "predictions": [0, 1, 1, 1, 0]
}

Notebook exemplo

Consulte o Notebook a seguir para ver um exemplo de como testar seu modelo de serviço endpoint com um modelo Python:

Teste servindo o modelo endpoint Notebook

Open notebook in new tab

Recurso adicional

• Tabelas de inferência para monitoramento e depuração de modelos.
• Use modelos de base.
• guia de depuração para manutenção do modelo.