Eseguire query sugli endpoint per i modelli personalizzati

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 nello Unity Catalog 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 supportate, vedere Gestire modelli con Azure Databricks.

Per le richieste di query per carichi di lavoro generativi di intelligenza artificiale e LLM, vedere Eseguire query sui modelli di intelligenza artificiale generativi.

Fabbisogno

• 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.

Esecuzione di query su metodi ed esempi

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

Esempio di assegnazione dei punteggi del DataFrame Pandas

L'esempio seguente presuppone un MODEL_VERSION_URI valore simile ahttps://<databricks-instance>/model/iris-classifier/Production/invocations , dove <databricks-instance> è il nome dell'istanza di Databricks e un token API REST di Databricks denominato DATABRICKS_API_TOKEN.

Vedere Formati di assegnazione dei punteggi supportati.

REST API

Assegnare un punteggio a un modello che accetta la formula di input di divisione 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

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

Nell'esempio seguente viene eseguita una query sul modello dietro l'endpoint sentiment-analysis con il text set di dati e viene specificato il tipo restituito della richiesta.

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

PowerBI

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

1. Aprire il set di dati per assegnare un punteggio.

2. Vai a Trasformazione Dati.

3. Fare clic con il pulsante destro del mouse nel pannello sinistro e selezionare Crea Nuova Query.

4. Passare a Visualizza > Editor avanzato.

5. 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
   

6. Assegnare alla query il nome del modello desiderato.

7. Aprire l'editor di query avanzato per il set di dati e applicare la funzione del modello.

Esempio di input tensor

L'esempio seguente assegna un punteggio a un modello che accetta input tensor. Gli input tensor devono essere formattati come descritto nella documentazione API di TensorFlow Serving. Questo esempio presuppone un MODEL_VERSION_URI valore simile https://<databricks-instance>/model/iris-classifier/Production/invocations, dove <databricks-instance> è il nome dell'istanza di Databricks, e un token API REST di Databricks denominato 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 formatodataframe_split (consigliato) è un DataFrame Pandas serializzato JSON nel 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 è DataFrame Pandas serializzato JSON nel records orientamento.

  Nota

  Questa formula non garantisce la conservazione dell'ordinamento delle colonne e la formula split è preferibile rispetto alla formula 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 modello, serializzato con JSON, di cui è stato eseguito il wrapping in una predictions chiave.

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

Input tensor

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 columnar. 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

Ottenere il notebook

Risorse aggiuntive

• Informazioni sulle tabelle di inferenza per il monitoraggio e il debug dei modelli.
• Eseguire query sui modelli di intelligenza artificiale generativi.
• Guida al debug per la gestione dei modelli.