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

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

Para solicitações de consulta para cargas de trabalho de IA generativa e LLM, consulte Modelos de base de consulta.

Requisitos

Importante

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 Databricks recomenda o uso de um access token pessoal pertencente à entidade de serviço em vez de usuários do workspace. Para criar o site tokens para uma entidade de serviço, consulte gerenciar tokens para uma entidade de serviço.

Métodos de consulta e exemplos

O Databricks servindo modelo fornece as seguintes opções para enviar solicitações de pontuação para modelos servidos:

Método

Detalhes

Servindo a UI

Selecione Query endpoint na página Serving endpoint em seu 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.

API REST

Chame e consulte o modelo usando a API REST. Consulte POST /serving-endpoint/{name}/invocations para obter detalhes. Para solicitações de pontuação para pontos de extremidade que atendem 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.

Função SQL

Invoque a inferência de modelo diretamente do SQL usando a função ai_query SQL. Consulte Consultar um modelo atendido com ai_query().

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.

Pontua um modelo que aceita o formato de entrada de registros de dataframe.

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
  -H 'Content-Type: application/json' \
  -d '{"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]]
    }]
  }'

Pontua um modelo que aceita entradas de tensor. As entradas do Tensor devem ser formatadas conforme descrito na documentação da API do TensorFlow Serving.

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

Importante

O exemplo a seguir usa a API predict() do SDK do MLflow Deployments.


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

Importante

O exemplo a seguir usa a função SQL integrada, IA. Essa função é uma visualização pública e a definição pode ser alterada. Consulte Consultar um modelo atendido com ai_query().

O exemplo a seguir consulta o modelo por trás do endpoint sentiment-analysis com o text dataset e especifica o tipo de retorno da solicitação.

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

Você pode pontuar um dataset no Power BI Desktop usando as seguintes passos:

  1. Abra o site dataset que o senhor deseja pontuar.

  2. Ir para transformação de dados.

  3. Clique com o botão direito do mouse no painel esquerdo e selecione Create New Query (Criar nova consulta).

  4. Acesse view > Advanced Editor.

  5. Substitua o corpo da consulta pelo trecho de código abaixo, depois de preencher os campos DATABRICKS_API_TOKEN e MODEL_VERSION_URI apropriados.

    (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. Nomeie a consulta com o nome do modelo desejado.

  7. Abra o editor de consultas avançadas do site dataset e aplique a função de modelo.

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.

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 DataFrame Pandas ou entrada Tensor.

Pandas DataFrame

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

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

    {
  "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.

    Observação

    Esse formato não garante a preservação da ordem das colunas, e o formato split é preferível ao formato 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
  }
  ]
}

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

{
  "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 o senhor tiver vários tensores nomeados por linha, terá que ter um de cada tensor para cada linha.

  • instances é um formato baseado em tensores que aceita tensores no formato de linha. Use esse formato se todos os tensores de entrada tiverem a mesma 0ª dimensão. Conceitualmente, cada tensor na lista de instâncias poderia ser unido a outros tensores com o 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.

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

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

    {
 "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 enviar 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) em relação a t1 e t3, portanto, não é possível representar essa entrada no formato 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]]]
 }
}

A resposta do endpoint está no seguinte formato.

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

Notebook exemplo

Consulte o seguinte Notebook para ver um exemplo de como testar seu endpoint servindo modelo com um modelo Python:

Teste servindo o modelo endpoint Notebook

Abra o bloco de anotações em outra guia