Özel modeller için sorgu sunma uç noktaları

Bu sayfada, sunulan modeliniz için puanlama isteklerini biçimlendirmeyi ve bu istekleri model sunum uç noktasına göndermeyi öğrenin. Bu kılavuz, Databricks'in MLflow biçiminde paketlenmiş geleneksel ML modelleri veya özelleştirilmiş Python modelleri olarak tanımladığı özel modelleri sunmayla ilgilidir. Modelleri Unity Kataloğu'na veya çalışma alanı modeli kayıt defterine kaydedin. Örnek olarak scikit-learn, XGBoost, PyTorch ve Hugging Face transformatör modelleri verilebilir. Bu işlevsellik ve desteklenen model kategorileri hakkında daha fazla bilgi için bkz. Model Sunma kullanarak modelleri dağıtma .

AI ve LLM iş yüklerine yönelik sorgu istekleri için bkz. Temel modelleri kullanma.

Uyarı

Uç noktanızda yol iyileştirme etkinleştirildiyse, bu sayfada açıklanan kimlik doğrulama akışı ve çağırma URL'si geçerli değildir. Yol için iyileştirilmiş uç noktalar yalnızca OAuth belirteçlerini (kişisel erişim belirteçleri değil) kabul eder ve ayrılmış bir URL'de sorgulanmalıdır. Kopyalayıp yapıştırabileceğiniz uçtan uca tarif ve sorun giderme de dahil olmak üzere tam akış için rota için iyileştirilmiş hizmet uç noktalarını sorgulama bölümüne bakın.

Gereksinimler

  • Bir model sunma uç noktası.
  • MLflow Dağıtım SDK'sı için MLflow 2.9 veya üzeri gereklidir.
  • Kabul edilen biçimde puanlama isteği.
  • REST API veya MLflow Dağıtım SDK'sı aracılığıyla puanlama isteği göndermek için Databricks API belirtecine sahip olmanız gerekir.

Önemli

Databricks, üretim senaryoları için en iyi güvenlik uygulaması olarak üretim sırasında kimlik doğrulaması için makineden makineye OAuth belirteçleri kullanmanızı önerir.

Databricks, test ve geliştirme için çalışma alanı kullanıcıları yerine hizmet sorumlularına ait bir kişisel erişim belirteci kullanılmasını önerir. Hizmet sorumluları için belirteçler oluşturmak üzere Hizmet sorumlusu için belirteçleri yönetme sayfasına bakın.

Sorgulama yöntemleri ve örnekleri

Model Sunma, sunulan modellere puanlama istekleri göndermek için aşağıdaki seçenekleri sağlar:

Yöntem Ayrıntılar
Kullanıcı arabirimini sunma Databricks çalışma alanınızdaki Hizmet uç noktası sayfasından Sorgu uç noktası seçin. JSON formatında model girdi verilerini ekleyin ve İstek Gönder'e tıklayın. Modelin günlüğe kaydedilmiş bir giriş örneği varsa, yüklemek için Örneği Göster'i kullanın.
SQL işlevi SQL işlevini kullanarak model çıkarımını doğrudan SQL'den çağırın ai_query . bkz. ai_query işlevi.
REST API REST API'yi kullanarak modeli çağırın ve sorgulayın. Ayrıntılar için post /serving-endpoints/{name}/invocations bölümüne bakın. Birden çok model sunan uç noktalara yönelik istekleri puanlamak için, bkz Bir uç nokta üzerinden bireysel modelleri sorgulama.
MLflow Dağıtımları SDK'sı Modeli sorgulamak için MLflow Dağıtımları SDK'sının predict() işlevini kullanın.

Pandas DataFrame puanlama örneği

Aşağıdaki örnek, gibi bir varsayımını içerir; burada , Databricks instance'ınızınolarak adlandırılmış adıdır ve olarak adlandırılan Databricks REST API belirtecidir.

Bkz . Desteklenen puanlama biçimleri.

REST API

Veri çerçevesi bölünmüş giriş biçimini kabul eden bir modeli değerlendirme.

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

Tensor girişlerini kabul eden bir modeli değerlendirmek. Tensor girişleri , TensorFlow Hizmeti'nin API belgelerinde açıklandığı gibi biçimlendirilmelidir.

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

MLflow Dağıtımları SDK'sı

Önemli

Aşağıdaki örnek, MLflow Dağıtımları SDK'sından predict()API'yi kullanır.

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

PowerBI

Aşağıdaki adımları kullanarak Power BI Desktop'ta bir veri kümesini puanlayabilirsiniz:

  1. Puanlamak istediğiniz veri kümesini açın.

  2. Verileri Dönüştür'e gidin.

  3. Sol panele sağ tıklayın ve yeni sorgu oluşturseçin.

  4. Gelişmiş Düzenleyici Görüntüle'ye >gidin.

  5. Uygun DATABRICKS_API_TOKEN ve ENDPOINT_INVOCATION_URLdeğerini doldurduktan sonra sorgu gövdesini aşağıdaki kod parçacığıyla değiştirin.

    (dataset as table ) as table =>
let
  call_predict = (dataset as table ) as list =>
  let
    apiToken = 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)}
      ]
    ))
  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. Sorguyu istediğiniz model adıyla adlandırın.

  7. Veri kümeniz için gelişmiş sorgu düzenleyicisini açın ve model işlevini uygulayın.

Tensor girişinin bir örneği

Aşağıdaki örnek, tensor girişlerini kabul eden bir modeli puanlar. Tensor girişleri, TensorFlow Hizmeti'nin API belgelerinde açıklandığı gibi biçimlendirilmelidir. Bu örnekte, gibi ENDPOINT_INVOCATION_URLbir https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocations olduğu varsayılır; burada <databricks-instance>Databricks örneğinizin adı ve adlı bir DATABRICKS_API_TOKEN bulunur.

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

Desteklenen puanlama biçimleri

Özel modeller için Model Sunma, Pandas DataFrame (JSON) veya Tensor girişinde (JSON veya Protobuf) puanlama isteklerini destekler.

Pandas DataFrame

İstekler, desteklenen anahtarlardan birine ve giriş biçimine karşılık gelen bir JSON nesnesine sahip bir JSON serileştirilmiş Pandas DataFrame oluşturularak gönderilmelidir.

  • (Önerilen)dataframe_split biçimi, split yönündeki JSON serileştirilmiş Pandas DataFrame'dir.

    {
  "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, records yönlendirmesinde JSON ile serileştirilmiş bir Pandas DataFrame'dir.

    Not

    Bu biçim sütun sıralamanın korunmasını garanti etmez ve split biçimi yerine records biçimi tercih edilir.

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

Uç noktadan gelen yanıt, modelinizin JSON ile seri hale getirilmiş ve bir predictions anahtara sarmalanmış çıkışını içerir.

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

Tensor girişi

Modeliniz TensorFlow veya Pytorch modeli gibi tensorlar beklediğinde, istek göndermek için desteklenen iki biçim seçeneği vardır: instances ve inputs.

Satır başına birden çok adlandırılmış tensor'larınız varsa, her satır için her tensordan birine sahip olmanız gerekir.

  • instances , satır biçiminde tensor kabul eden tensor tabanlı bir biçimdir. Tüm giriş tensorları aynı 0. boyuta sahipse bu biçimi kullanın. Kavramsal olarak, örnek listesindeki her tensor, modelin tam giriş tensorunu oluşturmak üzere listenin geri kalanında aynı adı taşıyan diğer tensorlarla birleştirilebilir ve bu da yalnızca tüm tensorların aynı 0. boyuta sahip olması durumunda mümkün olabilir.

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

    Aşağıdaki örnek, birden fazla isimlendirilmiş tensörü nasıl belirteceğinizi gösteriyor.

    {
  "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 sütun biçiminde tensor içeren sorgular gönderin. Farklı sayıda t2 tensor örneği (3) olduğundan t1 ve t3'den bu istek farklıdır, dolayısıyla bu girdi instances formatında temsil edilemez.

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

Uç noktadan gelen yanıt aşağıdaki biçimdedir.

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

Protobuf tensör girişi

Önemli

Bu özellik Genel Önizleme aşamasındadır ve yalnızca 9 Temmuz 2026'da dağıtılan uç noktalarda kullanılabilir.

Protobuf istekleri çıkarım tablolarında yakalanmaz.

Tensor tabanlı giriş imzasına sahip modeller için, istek gövdesini JSON yerine serileştirilmiş KServe v2ModelInferRequest olarak, Content-Type: application/x-protobuf veya application/vnd.kserve.protobuf kullanarak gönderebilirsiniz. Bu, sayısal tensorların JSON metninden ayrıştırılmasını önler, bu nedenle özellikle büyük yükler için daha hızlıdır. Uç nokta URL'si ve kimlik doğrulaması değiştirilmez.

Desteklenen tensor veri türleri şunlardır: BOOL, UINT8, UINT16, UINT32, UINT64, , INT8, , INT16INT32INT64FP16FP32ve .FP64

Aşağıdaki örnek, bir protobuf istek gövdesinin nasıl oluşturulacağını gösterir.

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()

Yanıt, ModelInferResponse içinde tensör verileri bulunan serileştirilmiş bir raw_output_contents öğesidir.

response = ModelInferResponse()
response.ParseFromString(response_bytes)

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

Not defteri örneği

Python modeliyle Model Sunma uç noktanızı test etme örneği için aşağıdaki not defterine bakın:

Test Modeli Sunma uç nokta not defteri

not defteri al

Ek kaynaklar

  • Last updated on