Eseguire query sugli endpoint per i modelli personalizzati

Articolo
03/11/2025

Questo articolo illustra come fare a formattare le richieste di assegnazione dei punteggi per il modello servito e come inviare tali richieste all'endpoint di gestione del modello. Il materiale sussidiario è rilevante per la gestione di modelli personalizzati, che Databricks definisce come modelli di ML tradizionali o modelli Python personalizzati inclusi nel pacchetto della formula MLflow. Possono essere registrati nel catalogo unity o nel registro dei modelli dell'area di lavoro. Gli esempi includono i modelli scikit-learn, XGBoost, PyTorch e Hugging Face transformer. Per altre informazioni su questa funzionalità e sulle categorie di modelli supportati, vedere Distribuire modelli con Mosaic AI Model Serving.

Per richieste di query relative a carichi di lavoro di intelligenza artificiale generativa e LLM, consultare i modelli di base per le query .

Requisiti

Endpoint di gestione di un modello.
Per MLflow Deployment SDK, è necessario MLflow 2,9 o versione successiva.
Richiesta di assegnazione dei punteggi in una formula accettata.
Per inviare una richiesta di assegnazione dei punteggi tramite l'API REST o MLflow Deployment SDK, è necessario disporre di un token API Databricks.

Importante

Come buona prassi di sicurezza per scenari di produzione, Databricks consiglia di utilizzare token OAuth da macchina a macchina per l'autenticazione durante la produzione.

Per il test e lo sviluppo, Databricks consiglia di usare un token di accesso personale appartenente alle entità servizio anziché agli utenti dell'area di lavoro. Per creare token per le entità servizio, vedere Gestire i token per un'entità servizio.

Metodi ed esempi di query

Mosaic AI Model Serving offre le opzioni seguenti per l'invio di richieste di assegnazione dei punteggi ai modelli serviti:

Metodo	Dettagli
Gestione interfaccia utente	Selezionare endpoint di Query dalla pagina endpoint di Serving nell'area di lavoro di Databricks. Inserire i dati di input del modello in formato JSON e fare clic su Invia richiesta. Se nel modello è registrato un esempio di input, usare Mostra esempio per caricarlo.
Funzione SQL	Richiamare l'inferenza del modello direttamente da SQL utilizzando la funzione SQL `ai_query`. Vedere `ai_query` funzione.
REST API	Chiamare ed eseguire query sul modello usando l'API REST. Per informazioni dettagliate, consultare POST /serving-endpoints/{name}/invocations. Per le richieste di assegnazione dei punteggi agli endpoint che servono più modelli, consultare Eseguire query su singoli modelli dietro un endpoint.
MLflow Deployments SDK	Usare la funzione predict() di MLflow Deployments SDK per eseguire query sul modello.

Esempio di assegnazione dei punteggi del DataFrame Pandas

Nell'esempio seguente si presuppone un MODEL_VERSION_URI come https://<databricks-instance>/model/iris-classifier/Production/invocations, dove <databricks-instance> è il nome dell'istanza di Databrickse un token API REST Databricks denominato DATABRICKS_API_TOKEN.

Vedere Formati di assegnazione dei punteggi supportati.

REST API

Valutare un modello che accetta il formato di input suddiviso del dataframe.

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

Assegnare un punteggio a un modello che accetta input tensor. Gli input tensor devono essere formattati come descritto nella documentazione dell'API di 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]]}'

MLflow Deployments SDK

Importante

Il seguente esempio usa l'API predict() dello SDK di MLflow Deployments.


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

PowerBI

È possibile assegnare un punteggio a un set di dati in Power BI Desktop seguendo questa procedura:

Aprire il set di dati per assegnare un punteggio.
Vai a Trasformazione Dati.
Fare clic con il pulsante destro del mouse nel pannello sinistro e selezionare Crea Nuova Query.
Passare a Visualizza > Editor avanzato.

Sostituire il corpo della query con il frammento di codice seguente, dopo aver compilato un oggetto appropriato DATABRICKS_API_TOKEN e 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

Dai alla query il nome del modello desiderato.
Aprire l'editor di query avanzato per il set di dati e applicare la funzione del modello.

Esempio di input tensore

L'esempio seguente assegna un punteggio a un modello che accetta input tensor. Gli input dei tensori devono essere formattati come descritto nella documentazione API di TensorFlow Serving. Questo esempio presuppone un MODEL_VERSION_URI come https://<databricks-instance>/model/iris-classifier/Production/invocations, dove <databricks-instance> è il nome dell'istanza di Databrickse un token API REST Databricks chiamato 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]]}'

Formati di assegnazione dei punteggi supportati

Per i modelli personalizzati, Model Serving supporta le richieste di assegnazione dei punteggi nell'input DataFrame Pandas o Tensor.

DataFrame Pandas

Le richieste devono essere inviate creando un DataFrame Pandas serializzato JSON con una delle chiavi supportate e un oggetto JSON corrispondente alla formula di input.

Il formato (consigliato)dataframe_split è un Pandas DataFrame serializzato in JSON nell'split orientamento.

{
  "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 è un DataFrame di Pandas serializzato in JSON con orientamento records.

Nota

Questo formato non garantisce la conservazione dell'ordinamento delle colonne e il formato split è preferibile rispetto al 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
    }
  ]
}

La risposta dall'endpoint contiene l'output del tuo modello, serializzato in JSON, avvolto in una chiave predictions.

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

Tensore di input

Quando il modello prevede tensori, ad esempio un modello TensorFlow o Pytorch, sono disponibili due opzioni di formato supportate per l'invio di richieste: instances e inputs.

Se sono presenti più tensori denominati per riga, è necessario avere uno di ogni tensore per ogni riga.

instances è un formato basato su tensori che accetta tensori in formato riga. Utilizzare questo formato se tutti i tensori di input hanno la stessa dimensione 0-th. Concettualmente, ogni tensore nell'elenco di istanze può essere unito agli altri tensori dello stesso nome nel resto dell'elenco per costruire il tensore di input completo per il modello, che sarebbe possibile solo se tutti i tensori hanno la stessa dimensione 0-th.
```
{ "instances": [1, 2, 3] }
```
Nell'esempio seguente viene illustrato come specificare più tensori denominati.
```
{
  "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 inviare query con tensori in formato colonnare. Questa richiesta è diversa perché in realtà sono presenti un numero diverso di istanze tensor di t2 (3) rispetto t1 a e t3, pertanto non è possibile rappresentare questo input nel instances formato.

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

La risposta dall’endpoint è nel formato seguente.

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

Esempio di notebook

Vedere il notebook seguente per un esempio di come testare l'endpoint Model Serving con un modello Python:

Testare il notebook dell'endpoint di gestione del modello

Prendi il notebook

Condividi tramite