Freigeben über

Abfragen von Bereitstellungsendpunkten für benutzerdefinierte Modelle

  • Artikel

In diesem Artikel erfahren Sie, wie Sie Bewertungsanforderungen für Ihr bereitgestelltes Modell formatieren und diese Anforderungen an den Modellbereitstellungsendpunkt senden. Der Leitfaden bezieht sich auf die Bereitstellung benutzerdefinierter Modelle, die Databricks als herkömmliche ML-Modelle definiert, oder benutzerdefinierte Python-Modelle, die im MLflow-Format gepackt sind. Sie können in Unity Catalog oder in der Arbeitsbereichsmodellregistrierung registriert werden. Beispiele sind scikit-learn-, XGBoost-, PyTorch- und Hugging Face-Transformationsmodelle. Weitere Informationen zu diesen Funktionen und unterstützten Modellkategorien finden Sie unter Modellbereitstellung mit Azure Databricks.

Abfrageanforderungen für generative KI und LLM-Workloads finden Sie unter Abfragen von Basismodellen.

Anforderungen

Wichtig

Als bewährte Sicherheitsmethode für Produktionsszenarien empfiehlt Databricks, Computer-zu-Computer-OAuth-Token für die Authentifizierung während der Produktion zu verwenden.

Für die Test- und Entwicklungsphase empfiehlt Databricks die Verwendung eines persönlichen Zugriffstokens, das Dienstprinzipalen anstelle von Arbeitsbereichsbenutzern gehört. Informationen zum Erstellen von Token für Dienstprinzipale finden Sie unter Verwalten von Token für einen Dienstprinzipal.

Abfragen von Methoden und Beispielen

Die Databricks-Modellbereitstellung bietet die folgenden Optionen zum Senden von Bewertungsanforderungen an bereitgestellte Modelle:

Methode Details
Serving-Benutzeroberfläche Wählen Sie in Ihrem Databricks-Arbeitsbereich auf der Seite Bereitstellungsendpunkt die Option Endpunkt abfragen aus. Fügen Sie Eingabedaten des JSON-Formatmodells ein, und klicken Sie auf Anforderung übermitteln. Wenn das Modell ein Eingabebeispiel protokolliert hat, verwenden Sie Beispiel anzeigen, um es zu laden.
REST-API Rufen Sie das Modell mithilfe der REST-API auf, und fragen Sie es ab. Details finden Sie unter POST /serving-endpoints/{name}/invocations. Informationen zum Bewerten von Anforderungen an Endpunkte, die mehreren Modellen dienen, finden Sie unter Abfragen einzelner Modelle hinter einem Endpunkt.
MLflow Deployments SDK Verwenden Sie die Funktion predict() des MLflow Deployments SDK, um das Modell abzufragen.
SQL-Funktion Rufen Sie den Modellrückschluss direkt aus SQL mithilfe der SQL-Funktion „ai_query“ auf. Siehe Abfragen eines bereitgestellten Modells mit ai_query().

Pandas DataFrame-Bewertungsbeispiel

Im folgenden Beispiel wird eine MODEL_VERSION_URI wie https://<databricks-instance>/model/iris-classifier/Production/invocations angenommen, wobei <databricks-instance> der Name Ihrer Databricks-Instanz ist und ein Databricks-REST-API-Token DATABRICKS_API_TOKEN aufgerufen hat.

Siehe Unterstützte Bewertungsformate.

REST-API

Hier wird ein Modell bewertet, dass das Eingabeformat „dataframe_records“ akzeptiert:

curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
  -H 'Content-Type: application/json' \
  -d '{"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]]
    }]
  }'

Hier wird ein Modell bewertet, das Tensoreingaben akzeptiert. Tensoreingaben sollten wie in der Dokumentation zu TensorFlow-Bereitstellungs-APIs beschrieben formatiert werden.

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

Wichtig

Im folgenden Beispiel wird die predict()-API aus dem MLflow Deployments SDK verwendet.


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

Wichtig

Im folgenden Beispiel wird die integrierte SQL-Funktion ai_query verwendet. Diese Funktion befindet sich in der Public Preview, und die Definition kann sich ändern. Siehe Abfragen eines bereitgestellten Modells mit ai_query().

Das folgende Beispiel fragt das Modell hinter dem Endpunkt sentiment-analysis mit dem Dataset text ab und gibt den Rückgabetyp der Anforderung an.

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

Power BI

Sie können ein Dataset in Power BI Desktop wie folgt bewerten:

  1. Öffnen Sie das Dataset, das Sie bewerten möchten.

  2. Wechseln Sie zu „Daten transformieren“.

  3. Klicken Sie mit der rechten Maustaste in den linken Bereich, und wählen Sie Create New Query (Neue Abfrage erstellen) aus.

  4. Wechseln Sie zu Ansicht >Erweiterter Editor.

  5. Ersetzen Sie den Abfragetext durch den folgenden Codeschnipsel, nachdem Sie ein entsprechendes DATABRICKS_API_TOKEN und einen entsprechenden MODEL_VERSION_URI angegeben haben.

    (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. Geben Sie der Abfrage den gewünschten Modellnamen.

  7. Öffnen Sie den erweiterten Abfrage-Editor für Ihr Dataset, und wenden Sie die Modellfunktion an.

Tensoreingabebeispiel

Im folgenden Beispiel wird ein Modell bewertet, das Tensoreingaben akzeptiert. Tensoreingaben sollten wie in der Dokumentation zu TensorFlow-Bereitstellungs-APIs beschrieben formatiert werden. In diesem Beispiel wird eine MODEL_VERSION_URI wie https://<databricks-instance>/model/iris-classifier/Production/invocations angenommen, wobei <databricks-instance> der Name Ihrer Databricks-Instanzist und ein Databricks-REST-API-Token DATABRICKS_API_TOKEN aufgerufen hat.

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

Unterstützte Bewertungsformate

Für benutzerdefinierte Modelle unterstützt Model Serving Bewertungsanforderungen in Pandas DataFrame- oder Tensor-Eingaben.

Pandas DataFrame

Zum Senden von Anforderungen muss ein mit JSON serialisierter Pandas DataFrame mit einem der unterstützten Schlüssel und einem dem Eingabeformat entsprechenden JSON-Objekt erstellt werden.

  • (Empfohlen) Das Format dataframe_split ist ein JSON-serialisierter Pandas DataFrame in der split-Ausrichtung.

    {
  "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 ist ein JSON-serialisierter Pandas DataFrame in der records-Ausrichtung.

    Hinweis

    Dieses Format garantiert nicht die Beibehaltung der Spaltenreihenfolge, und das split-Format wird dem records-Format vorgezogen.

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

Die Antwort vom Endpunkt enthält die Ausgabe Ihres Modells, serialisiert mit JSON, umschlossen in einem predictions-Schlüssel.

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

Tensoreingabe

Wenn Ihr Modell Tensoren erwartet, z. B. ein TensorFlow- oder Pytorch-Modell, gibt es zwei unterstützte Formatoptionen für das Senden von Anforderungen: instances und inputs.

Wenn mehrere benannte Tensoren pro Zeile vorhanden sind, benötigen Sie für jede Zeile jeweils einen der verschiedenen Tensoren.

  • instances: Ein tensorsbasiertes Format, das Tensoren im Zeilenformat akzeptiert. Verwenden Sie dieses Format, wenn alle Eingabetensoren die gleiche nullte Dimension aufweisen. Konzeptionell betrachtet könnte jeder Tensor in der Instanzliste mit den anderen Tensoren gleichen Namens in der restlichen Liste verknüpft werden, um den vollständigen Eingabetensor für das Modell zu erstellen, was nur möglich wäre, wenn alle Tensoren die gleiche nullte Dimension haben.

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

    Das folgende Beispiel zeigt, wie mehrere benannte Tensoren angegeben werden.

    {
"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: Dient zum Senden von Abfragen mit Tensoren im Spaltenformat. Diese Anforderung ist anders, da t2 über eine andere Anzahl von Tensorinstanzen (3) verfügt als t1 und t3. Die Eingabe ist daher nicht im Instanzenformat (instances) darstellbar.

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

Die Antwort vom Endpunkt hat folgendes Format.

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

Notebook-Beispiel

Im folgenden Notebook finden Sie ein Beispiel dafür, wie Sie Ihren Modellbereitstellungsendpunkt mit einem Python-Modell testen können:

Notebook zum Testen des Modellbereitstellungsendpunkts

Notebook abrufen

Zusätzliche Ressourcen