Kueri yang melayani titik akhir untuk model kustom

Dalam artikel ini, pelajari cara memformat permintaan penilaian untuk model yang dilayani, dan cara mengirim permintaan tersebut ke titik akhir penyajian model. Panduan ini relevan untuk melayani model kustom, yang didefinisikan Databricks sebagai model ML tradisional atau model Python yang disesuaikan yang dipaketkan dalam format MLflow. Daftarkan model di Unity Catalog atau di registri model ruang kerja. Contohnya termasuk model transformator scikit-learn, XGBoost, PyTorch, dan Hugging Face. Lihat Menyebarkan model menggunakan Mosaic AI Model Serving untuk informasi selengkapnya tentang fungsionalitas ini dan kategori model yang didukung.

Untuk permintaan kueri untuk beban kerja AI generatif dan LLM, lihat Gunakan model dasar.

Persyaratan

Titik akhir penyajian model
Untuk SDK Penyebaran MLflow, MLflow 2.9 atau yang lebih tinggi diperlukan.
Permintaan penilaian dalam format yang diterima.
Untuk mengirim permintaan penilaian melalui REST API atau MLflow Deployment SDK, Anda harus memiliki token Databricks API.

Penting

Sebagai praktik terbaik keamanan untuk skenario produksi, Databricks merekomendasikan agar Anda menggunakan token OAuth mesin-ke-mesin untuk autentikasi selama produksi.

Untuk pengujian dan pengembangan, Databricks merekomendasikan penggunaan token akses pribadi milik perwakilan layanan alih-alih pengguna ruang kerja. Untuk membuat token untuk perwakilan layanan, lihat Mengelola token untuk perwakilan layanan.

Metode dan contoh pengkuerian

Mosaic AI Model Serving menyediakan opsi berikut untuk mengirim permintaan penilaian ke model yang dilayani:

Metode	Detail-detail
Menyajikan Antarmuka Pengguna	Pilih Titik akhir kueri dari halaman Titik akhir penayangan di ruang kerja Databricks Anda. Sisipkan data input model format JSON dan klik Kirim Permintaan. Jika model memiliki contoh input yang dicatat, gunakan Tampilkan Contoh untuk memuatnya.
Fungsi SQL	Panggil inferensi model langsung dari SQL menggunakan `ai_query` fungsi SQL. Silakan lihat fungsi `ai_query`.
REST API	Panggil dan kueri model menggunakan REST API. Lihat POST /serving-endpoints/{name}/invocations untuk detailnya. Untuk permintaan penilaian ke titik akhir yang melayani beberapa model, lihat Mengkueri model individual di belakang titik akhir.
SDK Penyebaran MLflow	Gunakan fungsi predict() MLflow Deployments SDK untuk mengkueri model.

Contoh penilaian Pandas DataFrame

Contoh berikut mengasumsikan ENDPOINT_INVOCATION_URL seperti https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocations, di mana <databricks-instance> adalah nama instans Databricks Anda, dan token Databricks REST API yang disebut DATABRICKS_API_TOKEN.

Lihat Format penilaian yang didukung.

REST API

Menilai model yang menerima format input pemisahan kerangka data.

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

Menilai model yang menerima input tensor. Input tensor harus diformat seperti yang dijelaskan dalam dokumentasi API 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]]}'

SDK Penyebaran MLflow

Penting

Contoh berikut menggunakan predict() API dari MLflow Deployments SDK.

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

Anda dapat menilai data set di Power BI Desktop menggunakan langkah-langkah berikut:

Buka himpunan data yang ingin Anda skor.
Pergi untuk mengubah data.
Klik kanan di panel kiri dan pilih Buat Kueri Baru.
Buka Lihat > Editor Tingkat Lanjut.

Ganti badan kueri dengan cuplikan kode di bawah ini, setelah mengisi yang sesuai DATABRICKS_API_TOKEN dan ENDPOINT_INVOCATION_URL.

(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

Beri nama kueri dengan nama model yang Anda inginkan.
Buka editor kueri tingkat lanjut untuk himpunan data Anda dan terapkan fungsi model.

Contoh input tensor

Contoh berikut memberikan skor pada model yang menerima input tensor. Input tensor harus diformat seperti yang dijelaskan dalam dokumen API TensorFlow Serving. Contoh ini mengasumsikan ENDPOINT_INVOCATION_URL seperti https://<databricks-instance>/serving-endpoints/<endpoint-name>/invocations, di mana <databricks-instance> adalah nama instans Databricks Anda, dan token Databricks REST API yang disebut 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]]}'

Format penilaian yang didukung

Untuk model kustom, Model Serving mendukung permintaan penilaian dalam input Pandas DataFrame atau Tensor.

Pandas DataFrame

Permintaan harus dikirim dengan membuat Pandas DataFrame berseri JSON dengan salah satu kunci yang didukung dan objek JSON yang sesuai dengan format input.

(Disarankan)dataframe_split format adalah Pandas DataFrame berseri JSON dalam split orientasi.

{
  "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 adalah Pandas DataFrame dalam bentuk JSON dengan orientasi records.

Catatan

Format ini tidak menjamin pelestarian pengurutan kolom, dan format split lebih disukai daripada format 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
    }
  ]
}

Respons dari titik akhir berisi output dari model Anda, yang diserialisasikan dengan JSON, dibungkus dalam predictions kunci.

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

Input tensor

Saat model Anda mengharapkan tensor, seperti model TensorFlow atau Pytorch, ada dua opsi format yang didukung untuk mengirim permintaan: instances dan inputs.

Jika Anda memiliki beberapa tensor bernama per baris, maka Anda harus memiliki salah satu dari setiap tensor untuk setiap baris.

instances adalah format berbasis tensor yang menerima tensor dalam format baris. Gunakan format ini jika semua tensor input memiliki dimensi 0-th yang sama. Secara konseptual, setiap tensor dalam daftar instans dapat digabungkan dengan tensor lain dengan nama yang sama di sisa daftar untuk membangun tensor input lengkap untuk model, yang hanya akan dimungkinkan jika semua tensor memiliki dimensi 0-th yang sama.
```
{ "instances": [1, 2, 3] }
```
Contoh berikut menunjukkan cara mengatur beberapa tensor yang diberi nama.
```
{
  "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 kirim kueri dengan tensor dalam format kolom. Permintaan ini berbeda karena sebenarnya ada jumlah instans tensor yang berbeda dari t2 (3) dari t1 dan t3, sehingga tidak mungkin untuk mewakili input ini dalam instances format .

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

Respons dari endpoint adalah dalam format berikut.

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

Contoh buku catatan

Lihat buku catatan berikut untuk contoh cara menguji titik akhir Model Melayani Anda dengan model Python:

Buku catatan titik akhir penyajian model uji

Dapatkan buku catatan

Sumber Daya Tambahan:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-02-14