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 query para cargas de trabalho de AI e LLM, consulte Usar modelos de base.
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
- 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 .
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 |
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.
- REST API
- MLflow Deployments SDK
- PowerBI
Classifique um modelo aceitando o formato de entrada dividido do quadro de dados.
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.
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]]}'
O exemplo a seguir usa a API predict() do SDK do MLflow Deployments.
import os
import mlflow.deployments
os.environ["DATABRICKS_HOST"] = "https://<workspace_host>.databricks.com"
os.environ["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]]
}
}
)
Você pode pontuar um dataset no Power BI Desktop usando as seguintes passos:
-
Abra o site dataset que o senhor deseja pontuar.
-
Ir para transformação de dados.
-
Clique com o botão direito do mouse no painel esquerdo e selecione Criar nova consulta .
-
Acesse o site > Advanced Editor .
-
Substitua o corpo da consulta pelo trecho de código abaixo, depois de preencher os campos
DATABRICKS_API_TOKENeENDPOINT_INVOCATION_URLapropriados.(dataset as table ) as table =>letcall_predict = (dataset as table ) as list =>letapiToken = DATABRICKS_API_TOKEN,modelUri = ENDPOINT_INVOCATION_URL,responseList = Json.Document(Web.Contents(modelUri,[Headers = [#"Content-Type" = "application/json",#"Authorization" = Text.Format("Bearer #{0}", {apiToken})],Content = {"dataframe_records": Json.FromValue(dataset)}]))inresponseList,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")indatasetWithPrediction -
Nomeie a consulta com o nome do modelo desejado.
-
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 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.
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 formato
dataframe_splité um Pandas DataFrame serializado em JSON na orientaçãosplit.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çãorecords.
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 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]]}]} -
inputsenvie consultas com tensores em formato colunar. Essa solicitação é diferente porque, na verdade, há um número diferente de instâncias de tensor det2(3) do quet1et3, portanto, não é possível representar essa entrada no formatoinstances.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.
{
"predictions": [0, 1, 1, 1, 0]
}
Entrada de tensor Protobuf
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.
As solicitações de Protobuf não são capturadas em tabelas de inferência.
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.
Os tipos de dados de tensor suportados são BOOL, UINT8, UINT16, UINT32, UINT64, INT8, INT16, INT32, INT64, FP16, FP32, FP64 e BYTES. Para dados de texto e binários em tensores BYTES, consulte Entradas de texto e binárias em solicitações protobuf.
Envie os dados para cada entrada em raw_input_contents, na mesma ordem que inputs. As solicitações que colocam dados de tensor nos campos contents digitados, como fp32_contents, falham com HTTP 400.
O exemplo a seguir mostra como criar um corpo de solicitação protobuf.
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.
response = ModelInferResponse()
response.ParseFromString(response_bytes)
values = np.frombuffer(response.raw_output_contents[0], dtype=np.float32).reshape(response.outputs[0].shape)
Entradas de texto e binárias em solicitações protobuf
BYTES tensores estão disponíveis em Endpoint implantados após 10 de novembro de 2026. Para usá-los em um endpoint implantado anteriormente, forneça uma nova versão do modelo no endpoint.
Um tensor BYTES contém valores de comprimento variável, como texto ou o conteúdo de um arquivo. Uma solicitação pode misturar tensores BYTES com tensores numéricos, por exemplo, um título e um vetor de recurso para cada linha. Em raw_input_contents, cada valor BYTES é um comprimento little-endian de 4 bytes seguido pelos bytes do valor, conforme definido pelo protocolo KServe v2.
A assinatura de entrada do modelo determina o que o modelo recebe para cada entrada BYTES:
Tipo de assinatura | O que o modelo recebe | Usar para |
|---|---|---|
| Uma matriz NumPy de valores de Python | Texto livre, como títulos, queries e descrições. |
| Uma matriz de strings NumPy de largura fixa ( | Valores curtos de comprimento semelhante, como códigos. |
| Uma matriz de bytes NumPy de largura fixa ( | Arquivos e outros dados binários. Consulte Enviar arquivos em solicitações protobuf. |
O exemplo a seguir Logs um modelo que recebe uma entrada de texto e uma entrada numérica. Declare entradas de texto como object para que um valor longo não preencha todos os outros valores na solicitação.
import mlflow
import numpy as np
from mlflow.models import ModelSignature
from mlflow.types import Schema, TensorSpec
class TitleTagger(mlflow.pyfunc.PythonModel):
def predict(self, context, model_input, params=None):
titles = model_input["title"] # numpy array of Python str
features = model_input["features"] # float32 array of shape (rows, 600)
genres = ["Sci-Fi" if "space" in title.lower() else "Drama" for title in titles]
return {"genre": np.array(genres, dtype=object), "score": features.mean(axis=1)}
signature = ModelSignature(
inputs=Schema(
[
TensorSpec(np.dtype(object), (-1,), "title"), # text: use object, not str
TensorSpec(np.dtype(np.float32), (-1, 600), "features"),
]
),
outputs=Schema(
[
TensorSpec(np.dtype(object), (-1,), "genre"),
TensorSpec(np.dtype(np.float32), (-1,), "score"),
]
),
)
with mlflow.start_run():
mlflow.pyfunc.log_model(
name="model",
python_model=TitleTagger(),
signature=signature,
registered_model_name="main.default.title_tagger",
)
Para criar uma solicitação, coloque valores de texto e binários em uma matriz NumPy com dtype=object e codifique-a com serialize_byte_tensor de tritonclient. Outros clientes KServe v2 oferecem auxiliares equivalentes.
import numpy as np
from tritonclient.grpc.service_pb2 import ModelInferRequest, ModelInferResponse
from tritonclient.utils import deserialize_bytes_tensor, serialize_byte_tensor, triton_to_np_dtype
titles = np.array(["Lost in Space", "Love, Actually"], dtype=object)
features = np.random.rand(2, 600).astype(np.float32)
request = ModelInferRequest()
request.inputs.add(name="title", datatype="BYTES", shape=titles.shape)
request.raw_input_contents.append(serialize_byte_tensor(titles).item())
request.inputs.add(name="features", datatype="FP32", shape=features.shape)
request.raw_input_contents.append(features.tobytes())
body = request.SerializeToString()
Saídas de texto e binárias, como matrizes str, bytes ou object e listas de strings, são retornadas como tensores BYTES. Cada valor retorna como Python bytes.
response = ModelInferResponse()
response.ParseFromString(response_bytes)
outputs = {}
for tensor, raw in zip(response.outputs, response.raw_output_contents):
if tensor.datatype == "BYTES":
values = deserialize_bytes_tensor(raw)
else:
values = np.frombuffer(raw, dtype=triton_to_np_dtype(tensor.datatype))
outputs[tensor.name] = values.reshape(tensor.shape)
genres = [genre.decode("utf-8") for genre in outputs["genre"]]
Um modelo que retorna um DataFrame pandas com colunas de texto e numéricas falha com HTTP 500 para solicitações protobuf. Retorna um dicionário de matrizes NumPy, como no exemplo anterior.
Entradas de texto e binárias têm os seguintes limites:
- Tamanho decodificado : os valores de texto e binários em uma solicitação podem ocupar no máximo 256 MiB após a decodificação. Com uma assinatura
stroubytes, cada valor é preenchido com o valor mais longo na solicitação, então um valor longo pode levar uma solicitação além do limite. Solicitações que excedem o limite falham com HTTP 400. Use uma assinaturaobjectpara texto livre e envie arquivos de tamanho semelhante na mesma solicitação. - Bytes zero à direita : Com uma assinatura
stroubytes, um valor que termina em um byte zero (0x00) falha com HTTP 400, pois as matrizes NumPy de largura fixa descartam os bytes zero à direita. Para enviar arquivos que terminam com um byte zero, consulte Enviar arquivos em solicitações protobuf. - Tamanho da solicitação : As solicitações Protobuf têm o mesmo limite de tamanho de 16 MB que as solicitações JSON. Consulte Limites e regiões de Model Serving.
- Desempenho : Os tensores numéricos são copiados diretamente para arrays NumPy, mas os valores de texto são decodificados um valor de cada vez, na velocidade aproximada de parsing de JSON. Solicitações que são principalmente texto apresentam pouca aceleração em relação ao JSON.
Enviar arquivos em solicitações protobuf
BYTES os tensores podem transportar arquivos cujo tamanho varia de linha para linha, como imagens, áudio e documentos. Envie um arquivo por linha como bytes brutos, com uma assinatura de entrada bytes. O modelo recebe os bytes exatos de cada arquivo e o decodifica. Uma solicitação JSON pode transportar dados binários apenas como texto base64, que é cerca de 33% maior.
Os usos comuns incluem o seguinte:
- Imagens : envie arquivos JPEG ou PNG para modelos de classificação, detecção ou incorporação de imagens, que os decodificam e redimensionam. Em um endpoint de GPU, o modelo pode decodificar as imagens na GPU.
- Áudio : envie arquivos WAV, FLAC ou MP3 para modelos de reconhecimento de fala ou classificação de áudio.
- Documentos : Envie arquivos PDF ou outros documentos para modelos de parsing e extração.
- Registros serializados : envie arquivos Parquet ou outros dados serializados que o modelo lê.
Se os seus dados tiverem um tamanho fixo para cada linha, como pixels decodificados ou amostras de áudio, envie-os como um tensor numérico, como UINT8 ou FP32.
O exemplo a seguir Logs um modelo que lê arquivos de imagem e retorna o tamanho de cada imagem.
import io
import mlflow
import numpy as np
from mlflow.models import ModelSignature
from mlflow.types import Schema, TensorSpec
class ImageInfo(mlflow.pyfunc.PythonModel):
def predict(self, context, model_input, params=None):
from PIL import Image
widths, heights = [], []
for data in model_input["image"]: # one encoded image file per row
image = Image.open(io.BytesIO(bytes(data)))
widths.append(image.width)
heights.append(image.height)
return {"width": np.array(widths, dtype=np.int32), "height": np.array(heights, dtype=np.int32)}
signature = ModelSignature(
inputs=Schema([TensorSpec(np.dtype(bytes), (-1,), "image")]), # files: use bytes
outputs=Schema(
[
TensorSpec(np.dtype(np.int32), (-1,), "width"),
TensorSpec(np.dtype(np.int32), (-1,), "height"),
]
),
)
with mlflow.start_run():
mlflow.pyfunc.log_model(
name="model",
python_model=ImageInfo(),
signature=signature,
registered_model_name="main.default.image_info",
extra_pip_requirements=["pillow"],
)
Para enviar arquivos, leia cada arquivo em uma matriz NumPy com dtype=object. Não use uma matriz de bytes NumPy de largura fixa, o que remove bytes zero à direita de cada valor.
from pathlib import Path
paths = ["cat.jpg", "dog.png"]
images = np.array([Path(path).read_bytes() for path in paths], dtype=object)
request = ModelInferRequest()
request.inputs.add(name="image", datatype="BYTES", shape=images.shape)
request.raw_input_contents.append(serialize_byte_tensor(images).item())
body = request.SerializeToString()
Com uma assinatura bytes, um arquivo que termina em um byte zero falha com HTTP 400. Arquivos JPEG, PNG, PDF e Parquet terminam com um marcador fixo, portanto você pode enviá-los como estão. Arquivos baseados em ZIP, como DOCX e XLSX, arquivos gzip e alguns arquivos de áudio e vídeo podem terminar em um byte zero. Para enviar esses arquivos, codifique cada um no cliente e decodifique-o no modelo. A codificação com base64 aumenta em cerca de 33% o tamanho de cada arquivo. Adicionar um byte diferente de zero adiciona 1 byte.
import base64
# Option 1: base64. In the model, decode each value with base64.b64decode(bytes(data)).
encoded = np.array([base64.b64encode(Path(path).read_bytes()) for path in paths], dtype=object)
# Option 2: append one byte. In the model, remove it with bytes(data)[:-1].
padded = np.array([Path(path).read_bytes() + b"\x01" for path in paths], dtype=object)
Notebook exemplo
Consulte o Notebook a seguir para ver um exemplo de como testar seu modelo de serviço endpoint com um modelo Python: