Kueri yang melayani titik akhir untuk model kustom

Artikel
05/21/2024

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. Mereka dapat didaftarkan baik di Katalog Unity atau di registri model ruang kerja. Contohnya termasuk model transformator scikit-learn, XGBoost, PyTorch, dan Hugging Face. Lihat Model yang melayani dengan Azure Databricks untuk informasi selengkapnya tentang fungsionalitas ini dan kategori model yang didukung.

Untuk permintaan kueri untuk beban kerja AI dan LLM generatif, lihat Model fondasi kueri.

Persyaratan

Model yang melayani titik akhir.
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 kueri

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

Metode	Detail
Melayani UI	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.
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.
Fungsi SQL	Panggil inferensi model langsung dari SQL menggunakan `ai_query` fungsi SQL. Lihat Mengkueri model yang dilayani dengan ai_query().

Contoh penilaian Pandas DataFrame

Contoh berikut mengasumsikan MODEL_VERSION_URI seperti https://<databricks-instance>/model/iris-classifier/Production/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 $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]]
    }]
  }'

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 $MODEL_VERSION_URI \
   -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 SDK Penyebaran 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

Penting

Contoh berikut menggunakan fungsi SQL bawaan, ai_query. Fungsi ini adalah Pratinjau Publik dan definisinya mungkin berubah. Lihat Mengkueri model yang dilayani dengan ai_query().

Contoh berikut mengkueri model di belakang sentiment-analysis titik akhir dengan himpunan text data dan menentukan jenis pengembalian permintaan.

SELECT text, ai_query(
    "sentiment-analysis",
    text,
    returnType => "STRUCT<label:STRING, score:DOUBLE>"
  ) AS predict
FROM
  catalog.schema.customer_reviews

PowerBI

Anda dapat mencetak himpunan data 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 Lanjutan.

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

(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

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 menilai model yang menerima input tensor. Input tensor harus diformat seperti yang dijelaskan dalam dokumen API TensorFlow Serving. Contoh ini mengasumsikan MODEL_VERSION_URI seperti https://<databricks-instance>/model/iris-classifier/Production/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 $MODEL_VERSION_URI \
    -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 berseri JSON dalam records orientasi.

Catatan

Format ini tidak menjamin pelestarian pengurutan kolom, dan split formatnya lebih disukai records daripada format.

{
  "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 menentukan beberapa tensor bernama.
```
{
"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 titik akhir 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 Uji Model Melayani

Dapatkan buku catatan

Sumber Daya Tambahan:

Tabel inferensi untuk model pemantauan dan penelusuran kesalahan.
Model fondasi kueri.

Bagikan melalui

Kueri yang melayani titik akhir untuk model kustom

Persyaratan

Metode dan contoh kueri

Contoh penilaian Pandas DataFrame

REST API

SDK Penyebaran MLflow

SQL

PowerBI

Contoh input tensor

Format penilaian yang didukung

Pandas DataFrame

Input tensor

Contoh buku catatan

Buku catatan titik akhir Uji Model Melayani

Sumber Daya Tambahan:

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: