Consultar pontos de extremidade de serviço para modelos personalizados

  • Artigo

Neste artigo, saiba como formatar solicitações de pontuação para o seu modelo servido e como enviar essas solicitações para o ponto de extremidade de serviço de modelo. As diretrizes são relevantes para atender modelos personalizados, que o Databricks define como modelos de ML tradicionais ou modelos de Python personalizados empacotados no formato MLflow. Eles podem ser registrados no Catálogo do Unity ou no registro de modelo de workspace. Os exemplos incluem modelos de transformador scikit-learn, XGBoost, PyTorch e Hugging Face. Confira Serviço de modelo com o Azure Databricks para obter mais informações sobre esta funcionalidade e categorias de modelo com suporte.

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

Requisitos

Importante

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

Para testes e desenvolvimento, a Databricks recomenda a utilização de um token de acesso pessoal pertencente a principais de serviço em vez de utilizadores do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Consultar métodos e exemplos

O Serviço de Modelo de IA do Mosaico fornece as seguintes opções para enviar solicitações de pontuação para modelos atendidos:

Método Detalhes
Servindo a interface do usuário Selecione o Ponto de extremidade de consulta na página do Ponto de extremidade de serviço no workspace do Databricks. Insira os dados de entrada do modelo no formato JSON e clique em Enviar solicitação. Se o modelo tiver um exemplo de entrada registrado, use Mostrar Exemplo para carregá-lo.
API REST Chame e consulte o modelo usando a API REST. Consulte POST /serving-endpoints/{name}/invocações para obter detalhes. Para solicitações de pontuação para pontos de extremidade que atendem a vários modelos, consulte Consultar modelos individuais em um ponto de extremidade.
SDK de Implantações do MLflow Use a função predict() do SDK de Implantações do MLflow para consultar o modelo.
Função SQL Invoque a inferência de modelo diretamente do SQL usando a função SQL ai_query. Consulte Pergunte a um modelo atendido com ai_query().

Exemplo de pontuação do DataFrame do Pandas

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 de sua instância do Databricks, e um token de API REST do Databricks chamado DATABRICKS_API_TOKEN.

Confira os Formatos de pontuação com suporte.

API REST

Pontuação de um modelo que aceita o formato de entrada de divisão de 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 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]]}'

SDK de Implantações do MLflow

Importante

O exemplo a seguir usa a API predict() do SDK de Implantações do 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

Importante

O exemplo a seguir usa a função SQL integrada, ai_query. Esta função está em Visualização Pública e a definição pode ser alterada. Consulte Pergunte a um modelo atendido com ai_query().

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

PowerBI

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

  1. Abra o conjunto de dados que deseja pontuar.

  2. Acesse Transformar Dados.

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

  4. Acesse Exibir > Editor Avançado.

  5. Substitua o corpo da consulta pelo snippet de código abaixo, depois de preencher um DATABRICKS_API_TOKEN e um 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. Dê à consulta o nome do modelo desejado.

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

Exemplo de entrada do tensor

O exemplo a seguir pontua um modelo que aceita entradas de tensor. As entradas de tensor devem ser formatadas conforme descrito nos documentos da API do Serviço do TensorFlow. Esse 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 do Databricks e um token 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 com suporte

Para modelos personalizados, o Serviço de Modelo dá suporte a solicitações de pontuação na entrada DataFrame ou Tensor do Pandas.

Pandas DataFrame

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

  • (Recomendado)O formato dataframe_split é um DataFrame do Pandas serializado por 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 ordenação de coluna e o formato split é preferencial em relação 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 ponto de extremidade contém a saída do seu modelo, serializada com JSON, encapsulada em uma chave predictions.

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

Entrada do tensor

Quando seu modelo espera tensores, como um modelo TensorFlow ou Pytorch, existem duas opções de formato com suporte para enviar 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 no formato de linha. Use esse formato se todos os tensores de entrada tiverem a mesma dimensão 0-th. 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-th.

    {"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 no formato colunar. Essa solicitação é diferente porque, na verdade, há um número diferente de instâncias de tensores de t2 (3) do que t1t3, então 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 ponto de extremidade está no formato a seguir.

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

Exemplo de notebook

Confira o notebook a seguir para ver um exemplo de como testar seu ponto de extremidade de serviço do modelo com um modelo do Python:

Testar o notebook do ponto de extremidade de serviço do modelo

Obter notebook

Recursos adicionais