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

Neste artigo, saiba como formatar solicitações de pontuação para seu modelo atendido e como enviar essas solicitações para o ponto de extremidade de serviço do modelo. A orientação é relevante para servir modelos personalizados, que o Databricks define como modelos de ML tradicionais ou modelos Python personalizados empacotados no formato MLflow. Eles podem ser registrados no Unity Catalog ou no registro do modelo de espaço de trabalho. Exemplos incluem os modelos de transformador scikit-learn, XGBoost, PyTorch e Hugging Face. Consulte Modelo servindo com o Azure Databricks para obter mais informações sobre essa funcionalidade e categorias de modelo com suporte.

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

Requerimentos

• Um modelo de ponto de extremidade de serviço.
• Para o SDK de implantação do MLflow, o MLflow 2.9 ou superior é necessário.
• Pedido de pontuação num formato aceite.
• Para enviar uma solicitação de pontuação por meio da API REST ou do SDK de implantação do MLflow, você deve ter um token de API do Databricks.

Consultando métodos e exemplos

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

Exemplo de pontuação do Pandas DataFrame

O exemplo a seguir pressupõe um MODEL_VERSION_URI like , onde <databricks-instance> é o nome da sua instância do Databricks e um token da API REST do Databricks chamado DATABRICKS_API_TOKENhttps://<databricks-instance>/model/iris-classifier/Production/invocations.

Consulte Formatos de pontuação suportados.

API REST

Pontuar um modelo que aceita o formato de entrada dividido do dataframe.

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

Pontuar um modelo aceitando entradas tensoras. 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]]}'

SDK de implantações MLflow

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

O exemplo a seguir consulta o modelo por trás do sentiment-analysis ponto de extremidade com o text conjunto de dados 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

Power BI

Você pode pontuar um conjunto de dados no Power BI Desktop usando as seguintes etapas:

1. Abra o conjunto de dados que você deseja pontuar.

2. Vá para Transformar dados.

3. Clique com o botão direito do mouse no painel esquerdo e selecione Criar nova consulta.

4. Vá para Ver > Editor Avançado.

5. Substitua o corpo da consulta pelo trecho de código abaixo, depois de preencher um arquivo apropriado DATABRICKS_API_TOKEN e 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. Nomeie a consulta com o nome do modelo desejado.

7. Abra o editor de consultas avançado para seu conjunto de dados e aplique a função de modelo.

Exemplo de entrada de tensor

O exemplo a seguir pontua um modelo que aceita entradas tensoras. As entradas do tensor devem ser formatadas conforme descrito nos documentos da API do TensorFlow Serving. Este exemplo pressupõe um MODEL_VERSION_URI like https://<databricks-instance>/model/iris-classifier/Production/invocations, onde <databricks-instance> é o nome da sua instância do Databricks e um token da API REST do Databricks 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 Model Serving suporta solicitações de pontuação na entrada Pandas DataFrame ou Tensor.

Pandas DataFrame

As solicitações devem ser enviadas construindo um Pandas DataFrame serializado por JSON com uma das chaves suportadas e um objeto JSON correspondente ao formato de entrada.

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

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

  Nota

  Este formato não garante a preservação da ordem das colunas, e o split formato é preferido sobre o records formato.

  {
    "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 ponto de extremidade contém a saída do seu modelo, serializada com JSON, encapsulada em uma predictions chave.

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

Entrada tensor

Quando seu modelo espera tensores, como um modelo TensorFlow ou Pytorch, há duas opções de formato suportadas para enviar solicitações: instances e inputs.

Se você tiver vários tensores nomeados por linha, então você tem que ter um de cada tensor para cada linha.

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

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

  {
  "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 ponto de extremidade está no seguinte formato.

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

Exemplo de bloco de notas

Consulte o bloco de anotações a seguir para obter um exemplo de como testar seu ponto de extremidade do Model Serving com um modelo Python:

Modelo de teste Servindo o bloco de anotações de ponto de extremidade

Obter o bloco de notas

Recursos adicionais

• Tabelas de inferência para monitoramento e depuração de modelos.
• Modelos de base de consulta e modelos externos.