Pular para o conteúdo principal
Última atualização em

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

Nesta página, aprenda a formatar solicitações de pontuação para seu modelo disponibilizado e como enviar essas solicitações para o endpoint de servindo modelo. A orientação é relevante para a veiculação de modelos personalizados, que a Databricks define como modelos de ML tradicionais ou modelos Python personalizados empacotados no formato MLflow. Registrar os modelos no Unity Catalog ou no registro de modelos do workspace. Os exemplos incluem scikit-learn, XGBoost, PyTorch e modelos de transformadores Hugging Face. Consulte Implantar modelos usando o Model Serving para obter mais informações sobre esta 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.

atenção

Se o seu endpoint tiver **otimização de rota** habilitada, o fluxo de autenticação e o URL de invocação descritos nesta página não se aplicam. Endpoints otimizados para rota aceitam apenas tokens OAuth (e não tokens de acesso pessoal) e devem ser consultados em um URL dedicado. Consulte Consultar endpoints de disponibilização otimizados para rota para o fluxo completo, incluindo uma receita de ponta a ponta que você pode copiar e colar, e solução de problemas.

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 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​

Servir modelo oferece as seguintes opções para enviar solicitações de pontuação aos modelos servidos:

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.

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 ENDPOINT_INVOCATION_URL como https://<databricks-instance>/serving-endpoints/<endpoint-name>/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.

Classifique um modelo aceitando o formato de entrada dividido do quadro de dados.

Bash
curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
  -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]]
    }]
  }'

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

Bash
curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
  -H 'Content-Type: application/json' \
  -d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'

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 ENDPOINT_INVOCATION_URL como https://<databricks-instance>/serving-endpoints/<endpoint-name>/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 $ENDPOINT_INVOCATION_URL \
    -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 oferece suporte a solicitações de pontuação em Pandas DataFrame (JSON) ou entrada Tensor (JSON ou Protobuf).

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

Entrada de tensor Protobuf​

info

Visualização

Este recurso está em Prévia Pública e está disponível apenas em endpoints implantados após 9 de julho de 2026.

Para modelos com uma assinatura de entrada baseada em tensor, você pode enviar o corpo da solicitação como um ModelInferRequest serializado KServe v2 em vez de JSON, usando Content-Type: application/x-protobuf ou application/vnd.kserve.protobuf. Isso evita a análise de tensores numéricos de texto JSON, sendo, portanto, mais rápido, especialmente para grandes payloads. URL de Endpoint e autenticação permanecem inalterados.

Tipos de dados de tensor suportados são BOOL, UINT8, UINT16, UINT32, UINT64, INT8, INT16, INT32, INT64, FP16, FP32 e FP64.

O exemplo a seguir mostra como criar um corpo de solicitação protobuf.

Python
import numpy as np
from tritonclient.grpc.service_pb2 import ModelInferRequest, ModelInferResponse  # or any other module that provides KServe v2's ModelInferRequest and ModelInferResponse classes

# FP32 tensor of shape [2, 4]
tensor = np.array([[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]], dtype=np.float32)

request = ModelInferRequest()
request.inputs.add(name="input", datatype="FP32", shape=tensor.shape)
request.raw_input_contents.append(tensor.tobytes())

body = request.SerializeToString()

A resposta é um ModelInferResponse serializado com dados de tensor em raw_output_contents.

Python
response = ModelInferResponse()
response.ParseFromString(response_bytes)

values = np.frombuffer(response.raw_output_contents[0], dtype=np.float32).reshape(response.outputs[0].shape)

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

Abrir notebook em uma nova abaOpen in Databricks

Recurso adicional​

Nesta página